From c6c25adf6d9f71ea11f61392f6f3d221f01e5216 Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss Date: Fri, 3 Apr 2009 18:30:54 +0000 Subject: Fixed a whole bunch of small docs typos, errors, and ommissions. Fixes #8358, #8396, #8724, #9043, #9128, #9247, #9267, #9267, #9375, #9409, #9414, #9416, #9446, #9454, #9464, #9503, #9518, #9533, #9657, #9658, #9683, #9733, #9771, #9835, #9836, #9837, #9897, #9906, #9912, #9945, #9986, #9992, #10055, #10084, #10091, #10145, #10245, #10257, #10309, #10358, #10359, #10424, #10426, #10508, #10531, #10551, #10635, #10637, #10656, #10658, #10690, #10699, #19528. Thanks to all the respective authors of those tickets. git-svn-id: http://code.djangoproject.com/svn/django/trunk@10371 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/admin/index.txt | 40 +++++++++++++++++- docs/ref/contrib/comments/index.txt | 5 +++ docs/ref/contrib/comments/models.txt | 82 ++++++++++++++++++++++++++++++++++++ docs/ref/contrib/flatpages.txt | 5 +++ docs/ref/contrib/syndication.txt | 15 +++---- docs/ref/databases.txt | 61 +++++++++++++++++++++------ docs/ref/django-admin.txt | 20 +++------ docs/ref/forms/api.txt | 34 +++++++++++++++ docs/ref/forms/fields.txt | 65 +++++++--------------------- docs/ref/forms/widgets.txt | 9 +++- docs/ref/models/fields.txt | 18 ++++---- docs/ref/models/instances.txt | 12 ++++++ docs/ref/models/relations.txt | 27 ++++++++++-- docs/ref/templates/api.txt | 26 +++++++----- docs/ref/unicode.txt | 2 +- 15 files changed, 312 insertions(+), 109 deletions(-) create mode 100644 docs/ref/contrib/comments/models.txt (limited to 'docs/ref') diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 1c14a77a9c..463829538a 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -46,6 +46,11 @@ Other topics :maxdepth: 1 actions + +.. seealso:: + + For information about serving the media files (images, JavaScript, and CSS) + associated with the admin in production, see :ref:`serving-media-files`. ``ModelAdmin`` objects ====================== @@ -425,8 +430,8 @@ edit and save multiple rows at once. ``list_editable`` interacts with a couple of other options in particular ways; you should note the following rules: - * To use ``list_editable`` you must have defined ``ordering`` on - either your model or your ``ModelAdmin``. + * To use ``list_editable`` you must have defined ``ordering`` on either + your model's or your ``ModelAdmin``'s inner ``Meta``. * Any field in ``list_editable`` must also be in ``list_display``. You can't edit a field that's not displayed! @@ -1155,6 +1160,37 @@ If you wish to change the index or login templates, you are better off creating your own ``AdminSite`` instance (see below), and changing the ``index_template`` or ``login_template`` properties. +Linking to admin views +====================== + +.. versionadded:: 1.1 + +All the admin views use :ref:`named URL patterns ` so it's +easy to link to admin views with ``urlresolvers.reverse`` or the :ttag:`url` +template tag. + +Each model gets its own set of views and its own name using the model's app name +and model name. For example, the "add" view for a ``Choice`` model in a +``polls`` app would be named ``"admin_polls_choice_add"``. + +All the available views and their names are: + + ============== ====================================== =================== + View View name Parameters + ============== ====================================== =================== + Change list ``"admin___changelist"`` None + Add object ``"admin___add"`` None + Change object ``"admin___change"`` ``object_id`` + Delete object ``"admin___delete"`` ``object_id`` + Object history ``"admin___history"`` ``object_id`` + ============== ====================================== =================== + +For example, to get the change URL for a particular ``Choice`` object:: + + >>> from django.core import urlresolvers + >>> c = Choice.objects.get(...) + >>> change_url = urlresolvers.reverse('admin_polls_choice_change', (c.id,)) + ``AdminSite`` objects ===================== diff --git a/docs/ref/contrib/comments/index.txt b/docs/ref/contrib/comments/index.txt index 36151d5fbf..f3ccf54ebe 100644 --- a/docs/ref/contrib/comments/index.txt +++ b/docs/ref/contrib/comments/index.txt @@ -99,6 +99,10 @@ For example:: {% for comment in comment_list %} ... {% endfor %} + +This returns a list of :class:`~django.contrib.comments.models.Comment` objects; +see :ref:`the comment model documentation ` for +details. .. templatetag:: get_comment_count @@ -212,6 +216,7 @@ More information .. toctree:: :maxdepth: 1 + models settings signals upgrade diff --git a/docs/ref/contrib/comments/models.txt b/docs/ref/contrib/comments/models.txt new file mode 100644 index 0000000000..af85d68f00 --- /dev/null +++ b/docs/ref/contrib/comments/models.txt @@ -0,0 +1,82 @@ +.. _ref-contrib-comments-models: + +=========================== +The built-in comment models +=========================== + +.. module:: django.contrib.comments.models + :synopsis: The built-in comment models + +.. class:: Comment + + Django's built-in comment model. Has the following fields: + + .. attribute:: content_object + + A :class:`~django.contrib.contettypes.generic.GenericForeignKey` + attribute pointing to the object the comment is attached to. You can use + this to get at the related object (i.e. ``my_comment.content_object``). + + Since this field is a + :class:`~django.contrib.contettypes.generic.GenericForeignKey`, it's + actually syntactic sugar on top of two underlying attributes, described + below. + + .. attribute:: content_type + + A :class:`~django.db.models.ForeignKey` to + :class:`~django.contrib.contenttypes.models.ContentType`; this is the + type of the object the comment is attached to. + + .. attribute:: object_pk + + A :class:`~django.db.models.TextField` containing the primary + key of the object the comment is attached to. + + .. attribute:: site + + A :class:`~django.db.models.ForeignKey` to the + :class:`~django.contrib.sites.models.Site` on which the comment was + posted. + + .. attribute:: user + + A :class:`~django.db.models.ForeignKey` to the + :class:`~django.contrib.auth.models.User` who posted the comment. + May be blank if the comment was posted by an unauthenticated user. + + .. attribute:: user_name + + The name of the user who posted the comment. + + .. attribute:: user_email + + The email of the user who posteed the comment. + + .. attribute:: user_url + + The URL entered by the person who posted the comment. + + .. attribute:: comment + + The actual content of the comment itself. + + .. attribute:: submit_date + + The date the comment was submitted. + + .. attribute:: ip_address + + The IP address of the user posting the comment. + + .. attribute:: is_public + + ``False`` if the comment is in moderation (see + :ref:`ref-contrib-comments-moderation`); If ``True``, the comment will + be displayed on the site. + + .. attribute:: is_removed + + ``True`` if the comment was removed. Used to keep track of removed + comments instead of just deleting them. + diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index f1c3a1b8f5..875a1c05e5 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -39,6 +39,11 @@ To install the flatpages app, follow these steps: ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting, if it's not already in there. + Also make sure you've correctly set :setting:`SITE_ID` to the ID of the + site the settings file represents. This will usually be ``1`` (i.e. + ``SITE_ID = 1``, but if you're not using the sites framework to manage + multiple sites, it could be the ID of a different site. + 2. Add ``'django.contrib.flatpages'`` to your :setting:`INSTALLED_APPS` setting. diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index 795ce0c7c4..cb9c22b8bd 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -160,11 +160,11 @@ into those elements. :class:`~django.contrib.syndication.feeds.Feed` class. * To specify the contents of ````, you have two options. For each item - in :meth:`items()`, Django first tries executing a ``get_absolute_url()`` - method on that object. If that method doesn't exist, it tries calling a - method :meth:`item_link()` in the - :class:`~django.contrib.syndication.feeds.Feed` class, passing it a single - parameter, :attr:`item`, which is the object itself. Both + in :meth:`items()`, Django first tries calling a method + :meth:`item_link()` in the :class:`~django.contrib.syndication.feeds.Feed` + class, passing it a single parameter, :attr:`item`, which is the object + itself. If that method doesn't exist, Django tries executing a + ``get_absolute_url()`` method on that object. . Both ``get_absolute_url()`` and :meth:`item_link()` should return the item's URL as a normal Python string. As with ``get_absolute_url()``, the result of :meth:`item_link()` will be included directly in the URL, so you are @@ -644,9 +644,8 @@ This example illustrates all possible attributes and methods for a Returns the URL for every item in the feed. """ - # ITEM_GUID -- The following method is optional. This property is - # only used for Atom feeds (it is the ID element for an item in an - # Atom feed). If not provided, the item's link is used by default. + # ITEM_GUID -- The following method is optional. If not provided, the + # item's link is used by default. def item_guid(self, obj): """ diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index bd28df0835..d035da2ead 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -80,7 +80,6 @@ You should also audit your existing code for any instances of this behavior before enabling this feature. It's faster, but it provides less automatic protection for multi-call operations. - .. _mysql-notes: MySQL notes @@ -247,18 +246,18 @@ anything in a `MySQL option file`_. Here's a sample configuration which uses a MySQL option file:: - # settings.py - DATABASE_ENGINE = "mysql" - DATABASE_OPTIONS = { - 'read_default_file': '/path/to/my.cnf', - } - - # my.cnf - [client] - database = DATABASE_NAME - user = DATABASE_USER - password = DATABASE_PASSWORD - default-character-set = utf8 + # settings.py + DATABASE_ENGINE = "mysql" + DATABASE_OPTIONS = { + 'read_default_file': '/path/to/my.cnf', + } + + # my.cnf + [client] + database = DATABASE_NAME + user = DATABASE_USER + password = DATABASE_PASSWORD + default-character-set = utf8 Several other MySQLdb connection options may be useful, such as ``ssl``, ``use_unicode``, ``init_command``, and ``sql_mode``. Consult the @@ -426,6 +425,42 @@ This provides the ability to upgrade both the DB-API 2.0 interface or SQLite 3 itself to versions newer than the ones included with your particular Python binary distribution, if needed. +"Database is locked" errors +----------------------------------------------- + +SQLite is meant to be a lightweight database, and thus can't support a high +level of concurrency. ``OperationalError: database is locked`` errors indicate +that your application is experiencing more concurrency than ``sqlite`` can +handle in default configuration. This error means that one thread or process has +an exclusive lock on the database connection and another thread timed out +waiting for the lock the be released. + +Python's SQLite wrapper has +a default timeout value that determines how long the second thread is allowed to +wait on the lock before it times out and raises the ``OperationalError: database +is locked`` error. + +If you're getting this error, you can solve it by: + + * Switching to another database backend. At a certain point SQLite becomes + too "lite" for real-world applications, and these sorts of concurrency + errors indicate you've reached that point. + + * Rewriting your code to reduce concurrency and ensure that database + transactions are short-lived. + + * Increase the default timeout value by setting the ``timeout`` database + option option:: + + DATABASE_OPTIONS = { + # ... + "timeout": 20, + # ... + } + + This will simply make SQLite wait a bit longer before throwing "database + is locked" errors; it won't really do anything to solve them. + .. _oracle-notes: Oracle notes diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 60ed244d17..71804cf022 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -458,8 +458,10 @@ supports the FastCGI protocol. See the :ref:`FastCGI deployment documentation .. _flup: http://www.saddi.com/software/flup/ -runserver [optional port number, or ipaddr:port] ------------------------------------------------- +runserver +--------- + +.. django-admin:: runserver [port or ipaddr:port] Starts a lightweight development Web server on the local machine. By default, the server runs on port 8000 on the IP address 127.0.0.1. You can pass in an @@ -491,8 +493,7 @@ machines on your network. To make your development server viewable to other machines on the network, use its own IP address (e.g. ``192.168.2.1``) or ``0.0.0.0``. ---adminmedia -~~~~~~~~~~~~ +.. django-admin-option:: --adminmedia Use the ``--adminmedia`` option to tell Django where to find the various CSS and JavaScript files for the Django admin interface. Normally, the development @@ -503,8 +504,7 @@ Example usage:: django-admin.py runserver --adminmedia=/tmp/new-admin-style/ ---noreload -~~~~~~~~~~ +.. django-admin-option:: --noreload Use the ``--noreload`` option to disable the use of the auto-reloader. This means any Python code changes you make while the server is running will *not* @@ -541,14 +541,6 @@ By default, the development server doesn't serve any static files for your site (such as CSS files, images, things under ``MEDIA_URL`` and so forth). If you want to configure Django to serve static media, read :ref:`howto-static-files`. -Turning off auto-reload -~~~~~~~~~~~~~~~~~~~~~~~ - -To disable auto-reloading of code while the development server is running, use the -``--noreload`` option, like so:: - - django-admin.py runserver --noreload - shell ----- diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 96c0440fb3..7a2341f69b 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -129,6 +129,40 @@ what happens with unbound forms:: >>> f.errors {} +Dynamic initial values +---------------------- + +.. attribute:: Form.initial + +Use ``initial`` to declare the initial value of form fields at runtime. For +example, you might want to fill in a ``username`` field with the username of the +current session. + +To accomplish this, use the ``initial`` argument to a ``Form``. This argument, +if given, should be a dictionary mapping field names to initial values. Only +include the fields for which you're specifying an initial value; it's not +necessary to include every field in your form. For example:: + + >>> f = ContactForm(initial={'subject': 'Hi there!'}) + +These values are only displayed for unbound forms, and they're not used as +fallback values if a particular value isn't provided. + +Note that if a ``Field`` defines ``initial`` *and* you include ``initial`` when +instantiating the ``Form``, then the latter ``initial`` will have precedence. In +this example, ``initial`` is provided both at the field level and at the form +instance level, and the latter gets precedence:: + + >>> class CommentForm(forms.Form): + ... name = forms.CharField(initial='class') + ... url = forms.URLField() + ... comment = forms.CharField() + >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False) + >>> print f + Name: + Url: + Comment: + Accessing "clean" data ---------------------- diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index d1ff54908d..63ac707acf 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -127,6 +127,8 @@ We've specified ``auto_id=False`` to simplify the output:: The ``initial`` argument lets you specify the initial value to use when rendering this ``Field`` in an unbound ``Form``. +To specify dynamic initial data, see the :attr:`Form.initial` parameter. + The use-case for this is when you want to display an "empty" form in which a field is initialized to a particular value. For example:: @@ -234,7 +236,6 @@ fields. We've specified ``auto_id=False`` to simplify the output:: .. attribute:: Field.error_messages - The ``error_messages`` argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you want to override. For example, here is the default error message:: @@ -256,54 +257,6 @@ And here is a custom error message:: In the `built-in Field classes`_ section below, each ``Field`` defines the error message keys it uses. -Dynamic initial values ----------------------- - -The ``initial`` argument to ``Field`` (explained above) lets you hard-code the -initial value for a ``Field`` -- but what if you want to declare the initial -value at runtime? For example, you might want to fill in a ``username`` field -with the username of the current session. - -To accomplish this, use the ``initial`` argument to a ``Form``. This argument, -if given, should be a dictionary mapping field names to initial values. Only -include the fields for which you're specifying an initial value; it's not -necessary to include every field in your form. For example:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField() - ... url = forms.URLField() - ... comment = forms.CharField() - >>> f = CommentForm(initial={'name': 'your username'}, auto_id=False) - >>> print f - Name: - Url: - Comment: - >>> f = CommentForm(initial={'name': 'another username'}, auto_id=False) - >>> print f - Name: - Url: - Comment: - -Just like the ``initial`` parameter to ``Field``, these values are only -displayed for unbound forms, and they're not used as fallback values if a -particular value isn't provided. - -Finally, note that if a ``Field`` defines ``initial`` *and* you include -``initial`` when instantiating the ``Form``, then the latter ``initial`` will -have precedence. In this example, ``initial`` is provided both at the field -level and at the form instance level, and the latter gets precedence:: - - >>> class CommentForm(forms.Form): - ... name = forms.CharField(initial='class') - ... url = forms.URLField() - ... comment = forms.CharField() - >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False) - >>> print f - Name: - Url: - Comment: - - Built-in ``Field`` classes -------------------------- @@ -819,6 +772,20 @@ example:: def label_from_instance(self, obj): return "My Object #%i" % obj.id +.. attribute:: ModelChoiceField.empty_label + + By default the ``