From 4ffbddf92d89c3b31cef90043721184a501cd454 Mon Sep 17 00:00:00 2001 From: Justin Bronn Date: Fri, 26 Oct 2007 20:47:20 +0000 Subject: gis: Merged revisions 6525-6613 via svnmerge from [repos:django/trunk trunk]. git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@6615 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/apache_auth.txt | 22 +++++++++--------- docs/cache.txt | 54 +++++++++++++++++++++++++++++++++++++++----- docs/contributing.txt | 5 +++++ docs/databases.txt | 8 +++++++ docs/django-admin.txt | 17 ++++++++------ docs/flatpages.txt | 2 +- docs/install.txt | 5 ++++- docs/middleware.txt | 13 ++++++----- docs/model-api.txt | 10 +++++---- docs/modpython.txt | 16 +++++++------ docs/newforms.txt | 52 +++++++++++++++++++++++++++++++++++------- docs/settings.txt | 37 ++++++++++++++++++++++++------ docs/syndication_feeds.txt | 16 +++++++++++++ docs/templates.txt | 56 ++++++++++++++++++++++++++++++---------------- docs/tutorial01.txt | 2 +- 15 files changed, 238 insertions(+), 77 deletions(-) (limited to 'docs') diff --git a/docs/apache_auth.txt b/docs/apache_auth.txt index cab57fe6d5..859050e716 100644 --- a/docs/apache_auth.txt +++ b/docs/apache_auth.txt @@ -28,21 +28,21 @@ with the standard ``Auth*`` and ``Require`` directives:: SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonAuthenHandler django.contrib.auth.handlers.modpython - + .. admonition:: Using the authentication handler with Apache 2.2 If you're using Apache 2.2, you'll need to take a couple extra steps. - + You'll need to ensure that ``mod_auth_basic`` and ``mod_authz_user`` are loaded. These might be compiled statically into Apache, or you might need to use ``LoadModule`` to load them dynamically (as shown in the example at the bottom of this note). - + You'll also need to insert configuration directives that prevent Apache from trying to use other authentication modules. Depending on which other authentication modules you have loaded, you might need one or more of the following directives:: - + AuthBasicAuthoritative Off AuthDefaultAuthoritative Off AuthzLDAPAuthoritative Off @@ -51,18 +51,18 @@ with the standard ``Auth*`` and ``Require`` directives:: AuthzGroupFileAuthoritative Off AuthzOwnerAuthoritative Off AuthzUserAuthoritative Off - + A complete configuration, with differences between Apache 2.0 and Apache 2.2 marked in bold, would look something like: - + .. parsed-literal:: - + **LoadModule auth_basic_module modules/mod_auth_basic.so** **LoadModule authz_user_module modules/mod_authz_user.so** - + ... - - + + AuthType Basic AuthName "example.com" **AuthBasicAuthoritative Off** @@ -71,7 +71,7 @@ with the standard ``Auth*`` and ``Require`` directives:: SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonAuthenHandler django.contrib.auth.handlers.modpython - + By default, the authentication handler will limit access to the ``/example/`` location to users marked as staff members. You can use a set of ``PythonOption`` directives to modify this behavior: diff --git a/docs/cache.txt b/docs/cache.txt index 8ba0383909..d598915d1a 100644 --- a/docs/cache.txt +++ b/docs/cache.txt @@ -119,8 +119,8 @@ in your database that is in the proper format that Django's database-cache system expects. Once you've created that database table, set your ``CACHE_BACKEND`` setting to -``"db://tablename/"``, where ``tablename`` is the name of the database table. -In this example, the cache table's name is ``my_cache_table``: +``"db://tablename"``, where ``tablename`` is the name of the database table. +In this example, the cache table's name is ``my_cache_table``:: CACHE_BACKEND = 'db://my_cache_table' @@ -228,7 +228,7 @@ entire site. Just add ``'django.middleware.cache.CacheMiddleware'`` to your 'django.middleware.common.CommonMiddleware', ) -(The order of ``MIDDLEWARE_CLASSES`` matters. See "Order of MIDDLEWARE_CLASSES" +(The order of ``MIDDLEWARE_CLASSES`` matters. See `Order of MIDDLEWARE_CLASSES`_ below.) Then, add the following required settings to your Django settings file: @@ -288,6 +288,36 @@ Or, using Python 2.4's decorator syntax:: above example, the result of the ``slashdot_this()`` view will be cached for 15 minutes. +Template fragment caching +========================= + +If you're after even more control, you can also cache template fragments using +the ``cache`` template tag. To give your template access to this tag, put ``{% +load cache %}`` near the top of your template. + +The ``{% cache %}`` template tag caches the contents of the block for a given +amount of time. It takes at least two arguments: the cache timeout, in +seconds, and the name to give the cache fragment. For example:: + + {% load cache %} + {% cache 500 sidebar %} + .. sidebar .. + {% endcache %} + +Sometimes you might want to cache multiple copies of a fragment depending on +some dynamic data that appears inside the fragment. For example you may want a +separate cached copy of the sidebar used in the previous example for every user +of your site. This can be easily achieved by passing additional arguments to +the ``{% cache %}`` template tag to uniquely identify the cache fragment:: + + {% load cache %} + {% cache 500 sidebar request.user.username %} + .. sidebar for logged in user .. + {% endcache %} + +If you need more than one argument to identify the fragment that's fine, simply +pass as many arguments to ``{% cache %}`` as you need! + The low-level cache API ======================= @@ -326,6 +356,15 @@ get() can take a ``default`` argument:: >>> cache.get('my_key', 'has expired') 'has expired' +To add a key only if it doesn't already exist, there is an add() method. It +takes the same parameters as set(), but will not attempt to update the cache +if the key specified is already present:: + + >>> cache.set('add_key', 'Initial value') + >>> cache.add('add_key', 'New value') + >>> cache.get('add_key') + 'Initial value' + There's also a get_many() interface that only hits the cache once. get_many() returns a dictionary with all the keys you asked for that actually exist in the cache (and haven't expired):: @@ -524,7 +563,7 @@ the value of the ``CACHE_MIDDLEWARE_SETTINGS`` setting. If you use a custom ``max_age`` in a ``cache_control`` decorator, the decorator will take precedence, and the header values will be merged correctly.) -If you want to use headers to disable caching altogether, +If you want to use headers to disable caching altogether, ``django.views.decorators.never_cache`` is a view decorator that adds headers to ensure the response won't be cached by browsers or other caches. Example:: @@ -556,8 +595,11 @@ within the ``MIDDLEWARE_CLASSES`` setting, because the cache middleware needs to know which headers by which to vary the cache storage. Middleware always adds something to the ``Vary`` response header when it can. -Put the ``CacheMiddleware`` after any middlewares that might add something to -the ``Vary`` header. The following middlewares do so: +Put the ``CacheMiddleware`` *before* any other middleware that might add +something to the ``Vary`` header (response middleware is applied in reverse +order). The following middleware modules do so: * ``SessionMiddleware`` adds ``Cookie`` * ``GZipMiddleware`` adds ``Accept-Encoding`` + * ``LocaleMiddleware`` adds ``Accept-Language`` + diff --git a/docs/contributing.txt b/docs/contributing.txt index 3200a87012..a842f4477a 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -335,6 +335,10 @@ Please follow these coding standards when writing code for inclusion in Django: * Unless otherwise specified, follow `PEP 8`_. + You could use a tool like `pep8.py`_ to check for some problems in this + area, but remember that PEP 8 is only a guide, so respect the style of + the surrounding code as a primary goal. + * Use four spaces for indentation. * Use underscores, not camelCase, for variable, function and method names @@ -924,5 +928,6 @@ requests for commit access are potential flame-war starters, and will be ignored .. _`#django`: irc://irc.freenode.net/django .. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority .. _PEP 8: http://www.python.org/peps/pep-0008.html +.. _pep8.py: http://svn.browsershots.org/trunk/devtools/pep8/pep8.py .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n .. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases diff --git a/docs/databases.txt b/docs/databases.txt index 213c2d666c..4530a1b896 100644 --- a/docs/databases.txt +++ b/docs/databases.txt @@ -76,6 +76,14 @@ the ``mysql`` backend. If you are trying to use an older version of MySQL and the ``mysql_old`` backend, then 1.2.0 *might* work for you. +.. note:: + If you see ``ImportError: cannot import name ImmutableSet`` when trying to + use Django, your MySQLdb installation may contain an outdated ``sets.py`` + file that conflicts with the built-in module of the same name from Python + 2.4 and later. To fix this, verify that you have installed MySQLdb version + 1.2.1p2 or newer, then delete the ``sets.py`` file in the MySQLdb + directory that was left by an earlier version. + .. _MySQLdb: http://sourceforge.net/projects/mysql-python Creating your database diff --git a/docs/django-admin.txt b/docs/django-admin.txt index f098dfa988..e751a7b3d9 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -741,22 +741,25 @@ Customized actions **New in Django development version** -If you want to add an action of your own to ``manage.py``, you can. -Simply add a ``management/commands`` directory to your application. -Each python module in that directory will be discovered and registered as +Applications can register their own actions with ``manage.py``. For example, +you might want to add a ``manage.py`` action for a Django app that you're +distributing. + +To do this, just add a ``management/commands`` directory to your application. +Each Python module in that directory will be auto-discovered and registered as a command that can be executed as an action when you run ``manage.py``:: - /fancy_blog + blog/ __init__.py models.py - /management + management/ __init__.py - /commands + commands/ __init__.py explode.py views.py -In this example, ``explode`` command will be made available to any project +In this example, the ``explode`` command will be made available to any project that includes the ``fancy_blog`` application in ``settings.INSTALLED_APPS``. The ``explode.py`` module has only one requirement -- it must define a class diff --git a/docs/flatpages.txt b/docs/flatpages.txt index 1422f16b6b..d082090689 100644 --- a/docs/flatpages.txt +++ b/docs/flatpages.txt @@ -48,7 +48,7 @@ with the given URL with a site ID that corresponds to the SITE_ID_ setting. If it finds a match, it follows this algorithm: * If the flatpage has a custom template, it loads that template. Otherwise, - it loads the template ``flatpages/default``. + it loads the template ``flatpages/default.html``. * It passes that template a single context variable, ``flatpage``, which is the flatpage object. It uses RequestContext_ in rendering the template. diff --git a/docs/install.txt b/docs/install.txt index 95aa82b2e3..519bf2674c 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -63,7 +63,10 @@ installed. * If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher. You will also want to read the database-specific notes for the `MySQL backend`_. -* If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher. +* If you're using SQLite and either Python 2.3 or Python 2.4, you'll need + pysqlite_. Use version 2.0.3 or higher. Python 2.5 ships with an sqlite + wrapper in the standard library, so you don't need to install anything extra + in that case. * If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher. You will also want to read the database-specific notes for the `Oracle backend`_. diff --git a/docs/middleware.txt b/docs/middleware.txt index 63ba8c6999..30a4899a3e 100644 --- a/docs/middleware.txt +++ b/docs/middleware.txt @@ -178,8 +178,9 @@ request, before Django decides which view to execute. ``process_request()`` should return either ``None`` or an ``HttpResponse`` object. If it returns ``None``, Django will continue processing this request, executing any other middleware and, then, the appropriate view. If it returns -an ``HttpResponse`` object, Django won't bother calling ANY other middleware or -the appropriate view; it'll return that ``HttpResponse``. +an ``HttpResponse`` object, Django won't bother calling ANY other request, +view or exception middleware, or the appropriate view; it'll return that +``HttpResponse``. Response middleware is always called on every response. process_view ------------ @@ -197,8 +198,9 @@ arguments that will be passed to the view. Neither ``view_args`` nor return either ``None`` or an ``HttpResponse`` object. If it returns ``None``, Django will continue processing this request, executing any other ``process_view()`` middleware and, then, the appropriate view. If it returns an -``HttpResponse`` object, Django won't bother calling ANY other middleware or -the appropriate view; it'll return that ``HttpResponse``. +``HttpResponse`` object, Django won't bother calling ANY other request, view +or exception middleware, or the appropriate view; it'll return that +``HttpResponse``. Response middleware is always called on every response. process_response ---------------- @@ -236,7 +238,8 @@ Guidelines * Feel free to look at Django's available middleware for examples. The core Django middleware classes are in ``django/middleware/`` in the - Django distribution. The session middleware is in ``django/contrib/sessions``. + Django distribution. The session middleware is in + ``django/contrib/sessions``. * If you write a middleware component that you think would be useful to other people, contribute to the community! Let us know, and we'll diff --git a/docs/model-api.txt b/docs/model-api.txt index a0844ea961..b49963d8f5 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -149,7 +149,7 @@ and in Django's validation. Django veterans: Note that the argument is now called ``max_length`` to provide consistency throughout Django. There is full legacy support for the old ``maxlength`` argument, but ``max_length`` is preferred. - + ``CommaSeparatedIntegerField`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -678,7 +678,9 @@ set. If ``True``, this field must be unique throughout the table. -This is enforced at the database level and at the Django admin-form level. +This is enforced at the database level and at the Django admin-form level. If +you try to add save a model with a duplicate value in a ``unique`` field, a +``django.db.IntegrityError`` will be raised by the model's ``save()`` method. ``unique_for_date`` ~~~~~~~~~~~~~~~~~~~ @@ -1584,8 +1586,8 @@ Finally, note that in order to use ``list_display_links``, you must define Set ``list_filter`` to activate filters in the right sidebar of the change list page of the admin. This should be a list of field names, and each specified -field should be either a ``BooleanField``, ``CharField``, ``DateField``, -``DateTimeField``, ``IntegerField`` or ``ForeignKey``. +field should be either a ``BooleanField``, ``CharField``, ``DateField``, +``DateTimeField``, ``IntegerField`` or ``ForeignKey``. This example, taken from the ``django.contrib.auth.models.User`` model, shows how both ``list_display`` and ``list_filter`` work:: diff --git a/docs/modpython.txt b/docs/modpython.txt index 4a8c169a51..5b20046168 100644 --- a/docs/modpython.txt +++ b/docs/modpython.txt @@ -87,17 +87,19 @@ lived under the ``weblog/`` directory, you would *also* need to add **parent directories** of anything you import directly must be on the Python path. -.. caution:: +.. note:: - If you're using Windows, remember that the path will contain backslashes. - This string is passed through Python's string parser twice, so you need to - escape each backslash **twice**:: + If you're using Windows, it is still recommended that you use forward + slashes in the pathnames, even though Windows normally uses backslashes + for its native separator. Apache knows how to convert from the forward + slash format to the native format, so this approach is portable and easier + to read (it avoids tricky problems with having to double-escape + backslashes). - PythonPath "['c:\\\\path\\\\to\\\\project'] + sys.path" + This is valid even on a Windows system:: - Or, use raw strings:: + PythonPath "['c:/path/to/project'] + sys.path" - PythonPath "[r'c:\\path\\to\\project'] + sys.path" You can also add directives such as ``PythonAutoReload Off`` for performance. See the `mod_python documentation`_ for a full list of options. diff --git a/docs/newforms.txt b/docs/newforms.txt index 2005adeec8..5e33a478ee 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -100,7 +100,7 @@ Start with this basic ``Form`` subclass, which we'll call ``ContactForm``:: subject = forms.CharField(max_length=100) message = forms.CharField() sender = forms.EmailField() - cc_myself = forms.BooleanField() + cc_myself = forms.BooleanField(required=False) A form is composed of ``Field`` objects. In this case, our form has four fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. We'll explain @@ -860,6 +860,23 @@ classes::
  • Instrument:
  • Haircut type:
    • + +Prefixes for forms +------------------ + +You can put several Django forms inside one ``
    `` tag. To give each +``Form`` its own namespace you need to use the ``prefix`` keyword argument:: + + >>> mother = PersonForm(prefix="mother") + >>> father = PersonForm(prefix="father") + >>> print mother.as_ul() +
    • +
    • + >>> print father.as_ul() +
    • +
    • + + Fields ====== @@ -1043,7 +1060,7 @@ fields. We've specified ``auto_id=False`` to simplify the output:: ... subject = forms.CharField(max_length=100, help_text='100 characters max.') ... message = forms.CharField() ... sender = forms.EmailField(help_text='A valid e-mail address, please.') - ... cc_myself = forms.BooleanField() + ... cc_myself = forms.BooleanField(required=False) >>> f = HelpTextContactForm(auto_id=False) >>> print f.as_table() Subject:
    100 characters max. @@ -1122,9 +1139,20 @@ For each field, we describe the default widget used if you don't specify ~~~~~~~~~~~~~~~~ * Default widget: ``CheckboxInput`` - * Empty value: ``None`` + * Empty value: ``False`` * Normalizes to: A Python ``True`` or ``False`` value. - * Validates nothing (i.e., it never raises a ``ValidationError``). + * Validates that the check box is checked (i.e. the value is ``True``) if + the field has ``required=True``. + +**New in Django development version:** The empty value for a ``CheckboxInput`` +(and hence the standard ``BooleanField``) has changed to return ``False`` +instead of ``None`` in the development version. + +.. note:: + Since all ``Field`` subclasses have ``required=True`` by default, the + validation condition here is important. If you want to include a checkbox + in your form that can be either checked or unchecked, you must remember to + pass in ``required=False`` when creating the ``BooleanField``. ``CharField`` ~~~~~~~~~~~~~ @@ -1132,7 +1160,8 @@ For each field, we describe the default widget used if you don't specify * Default widget: ``TextInput`` * Empty value: ``''`` (an empty string) * Normalizes to: A Unicode object. - * Validates nothing, unless ``max_length`` or ``min_length`` is provided. + * Validates ``max_length`` or ``min_length``, if they are provided. + Otherwise, all inputs are valid. Has two optional arguments for validation, ``max_length`` and ``min_length``. If provided, these arguments ensure that the string is at most or at least the @@ -1172,7 +1201,7 @@ If no ``input_formats`` argument is provided, the default input formats are:: ``DateTimeField`` ~~~~~~~~~~~~~~~~~ - * Default widget: ``TextInput`` + * Default widget: ``DateTimeInput`` * Empty value: ``None`` * Normalizes to: A Python ``datetime.datetime`` object. * Validates that the given value is either a ``datetime.datetime``, @@ -1193,6 +1222,9 @@ If no ``input_formats`` argument is provided, the default input formats are:: '%m/%d/%y %H:%M', # '10/25/06 14:30' '%m/%d/%y', # '10/25/06' +**New in Django development version:** The ``DateTimeField`` used to use a +``TextInput`` widget by default. This has now changed. + ``DecimalField`` ~~~~~~~~~~~~~~~~ @@ -1508,7 +1540,7 @@ like so:: subject = forms.CharField(max_length=100) message = forms.CharField() senders = MultiEmailField() - cc_myself = forms.BooleanField() + cc_myself = forms.BooleanField(required=False) Widgets ======= @@ -1529,6 +1561,7 @@ commonly used groups of widgets: ``MultipleHiddenInput`` Multiple ``...`` ``CheckboxInput`` ``