diff --git a/django/utils/html.py b/django/utils/html.py index c985538041..951b3f2a59 100644 --- a/django/utils/html.py +++ b/django/utils/html.py @@ -28,7 +28,9 @@ trailing_empty_content_re = re.compile(r'(?:

(?: |\s|
)*?

\s*)+\ del x # Temporary variable def escape(html): - """Returns the given HTML with ampersands, quotes and carets encoded.""" + """ + Returns the given HTML with ampersands, quotes and angle brackets encoded. + """ return mark_safe(force_unicode(html).replace('&', '&').replace('<', '<').replace('>', '>').replace('"', '"').replace("'", ''')) escape = allow_lazy(escape, unicode) diff --git a/docs/_static/djangodocs.css b/docs/_static/djangodocs.css index fdaccf70ba..a41be6d1b0 100644 --- a/docs/_static/djangodocs.css +++ b/docs/_static/djangodocs.css @@ -103,9 +103,9 @@ dt .literal, table .literal { background:none; } .note, .admonition { padding:.8em 1em .8em; margin: 1em 0; border:1px solid #94da3a; } .admonition-title { font-weight:bold; margin-top:0 !important; margin-bottom:0 !important;} .admonition .last { margin-bottom:0 !important; } -.note, .admonition { padding-left:65px; background:url(docicons-note.gif) .8em .8em no-repeat;} -div.admonition-philosophy { padding-left:65px; background:url(docicons-philosophy.gif) .8em .8em no-repeat;} -div.admonition-behind-the-scenes { padding-left:65px; background:url(docicons-behindscenes.gif) .8em .8em no-repeat;} +.note, .admonition { padding-left:65px; background:url(docicons-note.png) .8em .8em no-repeat;} +div.admonition-philosophy { padding-left:65px; background:url(docicons-philosophy.png) .8em .8em no-repeat;} +div.admonition-behind-the-scenes { padding-left:65px; background:url(docicons-behindscenes.png) .8em .8em no-repeat;} /*** versoinadded/changes ***/ div.versionadded, div.versionchanged { } diff --git a/docs/_static/docicons-behindscenes.gif b/docs/_static/docicons-behindscenes.gif deleted file mode 100644 index 921bc45c33..0000000000 Binary files a/docs/_static/docicons-behindscenes.gif and /dev/null differ diff --git a/docs/_static/docicons-behindscenes.png b/docs/_static/docicons-behindscenes.png new file mode 100644 index 0000000000..dc901bc867 Binary files /dev/null and b/docs/_static/docicons-behindscenes.png differ diff --git a/docs/_static/docicons-note.gif b/docs/_static/docicons-note.gif deleted file mode 100644 index c0d599e90a..0000000000 Binary files a/docs/_static/docicons-note.gif and /dev/null differ diff --git a/docs/_static/docicons-note.png b/docs/_static/docicons-note.png new file mode 100644 index 0000000000..357545fb32 Binary files /dev/null and b/docs/_static/docicons-note.png differ diff --git a/docs/_static/docicons-philosophy.gif b/docs/_static/docicons-philosophy.gif deleted file mode 100644 index 432d93ba79..0000000000 Binary files a/docs/_static/docicons-philosophy.gif and /dev/null differ diff --git a/docs/_static/docicons-philosophy.png b/docs/_static/docicons-philosophy.png new file mode 100644 index 0000000000..09f16c785b Binary files /dev/null and b/docs/_static/docicons-philosophy.png differ diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt index 8620b37603..cfb3226289 100644 --- a/docs/howto/custom-file-storage.txt +++ b/docs/howto/custom-file-storage.txt @@ -63,7 +63,11 @@ backend storage system. Called by ``Storage.save()``. The ``name`` will already have gone through ``get_valid_name()`` and ``get_available_name()``, and the ``content`` will be a -``File`` object itself. No return value is expected. +``File`` object itself. + +Should return the actual name of name of the file saved (usually the ``name`` +passed in, but if the storage needs to change the file name return the new name +instead). ``get_valid_name(name)`` ------------------------ diff --git a/docs/howto/deployment/modpython.txt b/docs/howto/deployment/modpython.txt index 3c3af82ec4..331515bdd8 100644 --- a/docs/howto/deployment/modpython.txt +++ b/docs/howto/deployment/modpython.txt @@ -17,14 +17,22 @@ performance gains over other server arrangements. Django requires Apache 2.x and mod_python 3.x, and you should use Apache's `prefork MPM`_, as opposed to the `worker MPM`_. -You may also be interested in :ref:`How to use Django with FastCGI, SCGI, or -AJP `. +.. seealso:: + + * Apache is a big, complex animal, and this document only scratches the + surface of what Apache can do. If you need more advanced information about + Apache, there's no better source than `Apache's own official + documentation`_ + + * You may also be interested in :ref:`How to use Django with FastCGI, SCGI, + or AJP `. .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _mod_perl: http://perl.apache.org/ .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html +.. _apache's own official documentation: http://httpd.apache.org/docs/ Basic configuration =================== @@ -52,15 +60,15 @@ Django mod_python handler." It passes the value of :ref:`DJANGO_SETTINGS_MODULE .. versionadded:: 1.0 The ``PythonOption django.root ...`` is new in this version. -Because mod_python does not know we are -serving this site from underneath the ``/mysite/`` prefix, this value needs to -be passed through to the mod_python handler in Django, via the ``PythonOption -django.root ...`` line. The value set on that line (the last item) should -match the string given in the ```` directive. The effect of this -is that Django will automatically strip the ``/mysite`` string from the front -of any URLs before matching them against your URLconf patterns. If you later -move your site to live under ``/mysite2``, you will not have to change anything -except the ``django.root`` option in the config file. +Because mod_python does not know we are serving this site from underneath the +``/mysite/`` prefix, this value needs to be passed through to the mod_python +handler in Django, via the ``PythonOption django.root ...`` line. The value set +on that line (the last item) should match the string given in the ```` directive. The effect of this is that Django will automatically strip the +``/mysite`` string from the front of any URLs before matching them against your +URLconf patterns. If you later move your site to live under ``/mysite2``, you +will not have to change anything except the ``django.root`` option in the config +file. When using ``django.root`` you should make sure that what's left, after the prefix has been removed, begins with a slash. Your URLconf patterns that are @@ -97,6 +105,10 @@ setting the Python path for interactive usage. Whenever you try to import something, Python will run through all the directories in ``sys.path`` in turn, from first to last, and try to import from each directory until one succeeds. +Make sure that your Python source files' permissions are set such that the +Apache user (usually named ``apache`` or ``httpd`` on most systems) will have +read access to the files. + An example might make this clearer. Suppose you have some applications under ``/usr/local/django-apps/`` (for example, ``/usr/local/django-apps/weblog/`` and so forth), your settings file is at ``/var/www/mysite/settings.py`` and you have diff --git a/docs/howto/initial-data.txt b/docs/howto/initial-data.txt index b005c01b06..d36329daa4 100644 --- a/docs/howto/initial-data.txt +++ b/docs/howto/initial-data.txt @@ -47,7 +47,7 @@ look like in JSON: "first_name": "Paul", "last_name": "McCartney" } - }, + } ] And here's that same fixture as YAML: diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt index a5e069f6f0..43062bebb6 100644 --- a/docs/howto/static-files.txt +++ b/docs/howto/static-files.txt @@ -10,9 +10,9 @@ How to serve static files Django itself doesn't serve static (media) files, such as images, style sheets, or video. It leaves that job to whichever Web server you choose. -The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and Cherokee_, -are much more fine-tuned at serving static files than a Web application -framework. +The reasoning here is that standard Web servers, such as Apache_, lighttpd_ and +Cherokee_, are much more fine-tuned at serving static files than a Web +application framework. With that said, Django does support static files **during development**. You can use the :func:`django.views.static.serve` view to serve media files. @@ -21,6 +21,11 @@ use the :func:`django.views.static.serve` view to serve media files. .. _lighttpd: http://www.lighttpd.net/ .. _Cherokee: http://www.cherokee-project.com/ +.. seealso:: + + If you just need to serve the admin media from a nonstandard location, see + the :djadminopt:`--adminmedia` parameter to :djadmin:`runserver`. + The big, fat disclaimer ======================= diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 8feb22141e..a97359667f 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -134,18 +134,27 @@ It worked! .. admonition:: Changing the port By default, the :djadmin:`runserver` command starts the development server - on port 8000. If you want to change the server's port, pass it as a - command-line argument. For instance, this command starts the server on port - 8080: + on the internal IP at port 8000. + + If you want to change the server's port, pass + it as a command-line argument. For instance, this command starts the server + on port 8080: .. code-block:: bash python manage.py runserver 8080 + + If you want to change the server's IP, pass it along with the port. So to + listen on all public IPs (useful if you want to show off your work on other + computers), use: + + .. code-block:: bash + + python manage.py runserver 0.0.0.0:8000 Full docs for the development server can be found in the :djadmin:`runserver` reference. - Database setup -------------- diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index df48a0286a..ca0b985508 100644 --- a/docs/intro/tutorial03.txt +++ b/docs/intro/tutorial03.txt @@ -302,6 +302,13 @@ for a given poll. Here's the view:: The new concept here: The view raises the :exc:`~django.http.Http404` exception if a poll with the requested ID doesn't exist. +We'll discuss what you could put in that ``polls/detail.html`` template a bit +later, but if you'd like to quickly get the above example working, just:: + + {{ poll }} + +will get you started for now. + A shortcut: get_object_or_404() ------------------------------- @@ -357,6 +364,10 @@ in ``django/conf/urls/defaults.py``, ``handler404`` is set to Three more things to note about 404 views: + * If :setting:`DEBUG` is set to ``True`` (in your settings module) then your + 404 view will never be used (and thus the ``404.html`` template will never + be rendered) because the traceback will be displayed instead. + * The 404 view is also called if Django doesn't find a match after checking every regular expression in the URLconf. @@ -365,8 +376,9 @@ Three more things to note about 404 views: template in the root of your template directory. The default 404 view will use that template for all 404 errors. - * If :setting:`DEBUG` is set to ``True`` (in your settings module) then your - 404 view will never be used, and the traceback will be displayed instead. + * If :setting:`DEBUG` is set to ``False`` (in your settings module) and if + you didn't create a ``404.html`` file, an ``Http500`` is raised instead. + So remember to create a ``404.html``. Write a 500 (server error) view =============================== diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt index 5c2e1e8ec1..07aa477d67 100644 --- a/docs/intro/tutorial04.txt +++ b/docs/intro/tutorial04.txt @@ -20,7 +20,7 @@ tutorial, so that the template contains an HTML ``
`` element: {% if error_message %}

{{ error_message }}

{% endif %} - + {% for choice in poll.choice_set.all %}
@@ -36,12 +36,12 @@ A quick rundown: selects one of the radio buttons and submits the form, it'll send the POST data ``choice=3``. This is HTML Forms 101. - * We set the form's ``action`` to ``/polls/{{ poll.id }}/vote/``, and we - set ``method="post"``. Using ``method="post"`` (as opposed to - ``method="get"``) is very important, because the act of submitting this - form will alter data server-side. Whenever you create a form that alters - data server-side, use ``method="post"``. This tip isn't specific to - Django; it's just good Web development practice. + * We set the form's ``action`` to ``vote/``, and we set ``method="post"``. + Using ``method="post"`` (as opposed to ``method="get"``) is very + important, because the act of submitting this form will alter data + server-side. Whenever you create a form that alters data server-side, use + ``method="post"``. This tip isn't specific to Django; it's just good Web + development practice. * ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone through its loop @@ -170,7 +170,17 @@ to write Python code to write an app. Let's convert our poll app to use the generic views system, so we can delete a bunch of our own code. We'll just have to take a few steps to make the -conversion. +conversion. We will: + + 1. Convert the URLconf. + + 2. Rename a few templates. + + 3. Delete some the old, now unneeded views. + + 4. Fix up URL handling for the new views. + +Read on for details. .. admonition:: Why the code-shuffle? diff --git a/docs/misc/distributions.txt b/docs/misc/distributions.txt index c94c399ce0..6a0845801d 100644 --- a/docs/misc/distributions.txt +++ b/docs/misc/distributions.txt @@ -4,7 +4,7 @@ Third-party distributions of Django =================================== -Several third-party distributors are now providing versions of Django integrated +Many third-party distributors are now providing versions of Django integrated with their package-management systems. These can make installation and upgrading much easier for users of Django since the integration includes the ability to automatically install dependencies (like database adapters) that Django @@ -15,81 +15,14 @@ if you want to use the development version of Django you'll need to follow the instructions for :ref:`installing the development version ` from our Subversion repository. -FreeBSD -======= +If you're using Linux or a Unix installation, such as OpenSolaris, +check with your distributor to see if they already package Django. If +you're using a Linux distro and don't know how to find out if a package +is available, then now is a good time to learn. The Django Wiki contains +a list of `Third Party Distributions`_ to help you out. -The `FreeBSD`_ ports system offers both Django 0.96 (`py-django`_) and a more -recent, but not current, version based on Django's trunk (`py-django-devel`_). -These are installed in the normal FreeBSD way; for Django 0.96, for example, type: -``cd /usr/ports/www/py-django && sudo make install clean``. +.. _`Third Party Distributions`: http://code.djangoproject.com/wiki/Distributions -.. _FreeBSD: http://www.freebsd.org/ -.. _py-django: http://www.freebsd.org/cgi/cvsweb.cgi/ports/www/py-django/ -.. _py-django-devel: http://www.freebsd.org/cgi/cvsweb.cgi/ports/www/py-django-devel/ - -Linux distributions -=================== - -Debian ------- - -A `packaged version of Django`_ is available for `Debian GNU/Linux`_. Version -0.95.1 is available in the "stable" repository; Version 0.96 is available in -the "testing" and "unstable" repositories. Regardless of your chosen repository, -you can install Django by typing ``apt-get install python-django``. - -When you install this package, ``apt`` will recommend installing a database -adapter; you should select and install the adapter for whichever database you -plan to use with Django. - -.. _Debian GNU/Linux: http://www.debian.org/ -.. _packaged version of Django: http://packages.debian.org/stable/python/python-django - -Fedora ------- - -A Django package is available for `Fedora Linux`_, in the "Fedora Extras" -repository. The `current Fedora package`_ is based on Django 0.96, and can be -installed by typing ``yum install Django``. The previous link is for the i386 -binary. Users of other architectures should be able to use that as a starting -point to find their preferred version. - -.. _Fedora Linux: http://fedora.redhat.com/ -.. _current Fedora package: http://download.fedora.redhat.com/pub/fedora/linux/extras/6/i386/repoview/Django.html - -Gentoo ------- - -A Django package is available for `Gentoo Linux`_, and is based on Django 0.96.1. -The `current Gentoo package`_ can be installed by typing ``emerge django``. - -.. _Gentoo Linux: http://www.gentoo.org/ -.. _current Gentoo package: http://packages.gentoo.org/package/django - -Ubuntu ------- - -The Debian ``python-django`` package is also available for `Ubuntu Linux`_, in -the "universe" repository for Ubuntu 7.10 ("Gutsy Gibbon"). The `current Ubuntu -package`_ is based on Django 0.96.1 and can be installed in the same fashion as -for Debian. - -.. _Ubuntu Linux: http://www.ubuntu.com/ -.. _current Ubuntu package: http://packages.ubuntu.com/gutsy/python/python-django - - -Mac OS X -======== - -MacPorts --------- - -Django 0.96 can be installed via the `MacPorts`_ system. If you're using Python 2.4, -type ``sudo port install py-django-devel``. For Python 2.5, type ``sudo port -install py25-django-devel``. MacPorts can also be used to install a database, -and the Python interface to your chosen database. - -.. _MacPorts: http://www.macports.org/ For distributors ================ diff --git a/docs/obsolete/_images/formrow.gif b/docs/obsolete/_images/formrow.gif deleted file mode 100644 index 3ff425862f..0000000000 Binary files a/docs/obsolete/_images/formrow.gif and /dev/null differ diff --git a/docs/obsolete/_images/formrow.png b/docs/obsolete/_images/formrow.png new file mode 100644 index 0000000000..164dd262b5 Binary files /dev/null and b/docs/obsolete/_images/formrow.png differ diff --git a/docs/obsolete/_images/module.gif b/docs/obsolete/_images/module.gif deleted file mode 100644 index 43c4d4de99..0000000000 Binary files a/docs/obsolete/_images/module.gif and /dev/null differ diff --git a/docs/obsolete/_images/module.png b/docs/obsolete/_images/module.png new file mode 100644 index 0000000000..6acda97809 Binary files /dev/null and b/docs/obsolete/_images/module.png differ diff --git a/docs/obsolete/_images/objecttools_01.gif b/docs/obsolete/_images/objecttools_01.gif deleted file mode 100644 index 067edb6f73..0000000000 Binary files a/docs/obsolete/_images/objecttools_01.gif and /dev/null differ diff --git a/docs/obsolete/_images/objecttools_01.png b/docs/obsolete/_images/objecttools_01.png new file mode 100644 index 0000000000..0aba8163d6 Binary files /dev/null and b/docs/obsolete/_images/objecttools_01.png differ diff --git a/docs/obsolete/_images/objecttools_02.gif b/docs/obsolete/_images/objecttools_02.gif deleted file mode 100644 index 0faa39a6a9..0000000000 Binary files a/docs/obsolete/_images/objecttools_02.gif and /dev/null differ diff --git a/docs/obsolete/_images/objecttools_02.png b/docs/obsolete/_images/objecttools_02.png new file mode 100644 index 0000000000..06a854009b Binary files /dev/null and b/docs/obsolete/_images/objecttools_02.png differ diff --git a/docs/obsolete/admin-css.txt b/docs/obsolete/admin-css.txt index f21d60888c..4f8fb663e2 100644 --- a/docs/obsolete/admin-css.txt +++ b/docs/obsolete/admin-css.txt @@ -29,7 +29,7 @@ group in a box and applies certain styles to the elements within. An ``h2`` within a ``div.module`` will align to the top of the ``div`` as a header for the whole group. -.. image:: _images/module.gif +.. image:: _images/module.png :alt: Example use of module class on admin homepage Column Types @@ -134,7 +134,7 @@ Example from a changelist page:
  • Add redirect
    • -.. image:: _images/objecttools_01.gif +.. image:: _images/objecttools_01.png :alt: Object tools on a changelist page and from a form page: @@ -146,7 +146,7 @@ and from a form page:
  • View on site
    • -.. image:: _images/objecttools_02.gif +.. image:: _images/objecttools_02.png :alt: Object tools on a form page Form Styles @@ -176,7 +176,7 @@ Each row of the form (within the ``fieldset``) should be enclosed in a ``div`` with class ``form-row``. If the field in the row is required, a class of ``required`` should also be added to the ``div.form-row``. -.. image:: _images/formrow.gif +.. image:: _images/formrow.png :alt: Example use of form-row class Labels 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 ``