From d1e5c55258d624058a93c8cacdb1f25ae7857554 Mon Sep 17 00:00:00 2001 From: Luke Plant Date: Fri, 14 Oct 2011 00:12:01 +0000 Subject: [PATCH] Fixed many more ReST indentation errors, somehow accidentally missed from [16955] git-svn-id: http://code.djangoproject.com/svn/django/trunk@16983 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/faq/admin.txt | 18 +- docs/faq/contributing.txt | 18 +- docs/faq/install.txt | 10 +- docs/faq/usage.txt | 54 +- docs/howto/apache-auth.txt | 44 +- docs/howto/custom-file-storage.txt | 10 +- docs/howto/custom-model-fields.txt | 118 +-- docs/howto/custom-template-tags.txt | 358 +++---- docs/howto/deployment/fastcgi.txt | 6 +- docs/howto/deployment/modpython.txt | 34 +- docs/howto/deployment/modwsgi.txt | 18 +- docs/howto/error-reporting.txt | 84 +- docs/howto/i18n.txt | 32 +- docs/howto/jython.txt | 12 +- docs/howto/legacy-databases.txt | 12 +- docs/howto/outputting-csv.txt | 44 +- docs/howto/outputting-pdf.txt | 62 +- docs/howto/static-files.txt | 62 +- docs/index.txt | 276 ++--- .../contributing/bugs-and-features.txt | 150 +-- .../contributing/committing-code.txt | 124 +-- docs/internals/contributing/index.txt | 48 +- docs/internals/contributing/translations.txt | 44 +- .../contributing/triaging-tickets.txt | 228 ++-- .../writing-code/branch-policy.txt | 70 +- .../writing-code/coding-style.txt | 202 ++-- .../writing-code/submitting-patches.txt | 92 +- .../contributing/writing-code/unit-tests.txt | 54 +- .../contributing/writing-documentation.txt | 260 ++--- docs/internals/deprecation.txt | 346 +++--- docs/internals/release-process.txt | 104 +- docs/intro/install.txt | 18 +- docs/intro/overview.txt | 12 +- docs/intro/tutorial01.txt | 128 +-- docs/intro/tutorial02.txt | 76 +- docs/intro/tutorial03.txt | 60 +- docs/intro/tutorial04.txt | 154 +-- docs/intro/whatsnext.txt | 146 +-- docs/misc/api-stability.txt | 160 +-- docs/misc/design-philosophies.txt | 4 +- docs/ref/class-based-views.txt | 260 ++--- docs/ref/contrib/admin/actions.txt | 8 +- docs/ref/contrib/admin/admindocs.txt | 44 +- docs/ref/contrib/comments/custom.txt | 12 +- docs/ref/contrib/comments/index.txt | 80 +- docs/ref/contrib/comments/signals.txt | 84 +- docs/ref/contrib/comments/upgrade.txt | 40 +- docs/ref/contrib/contenttypes.txt | 72 +- docs/ref/contrib/csrf.txt | 66 +- docs/ref/contrib/databrowse.txt | 52 +- docs/ref/contrib/flatpages.txt | 40 +- docs/ref/contrib/formtools/form-preview.txt | 84 +- docs/ref/contrib/formtools/form-wizard.txt | 70 +- docs/ref/contrib/humanize.txt | 72 +- docs/ref/contrib/markup.txt | 8 +- docs/ref/contrib/messages.txt | 28 +- docs/ref/contrib/redirects.txt | 22 +- docs/ref/contrib/sitemaps.txt | 80 +- docs/ref/contrib/sites.txt | 28 +- docs/ref/contrib/staticfiles.txt | 20 +- docs/ref/contrib/syndication.txt | 154 +-- docs/ref/contrib/webdesign.txt | 30 +- docs/ref/databases.txt | 110 +- docs/ref/django-admin.txt | 162 +-- docs/ref/exceptions.txt | 18 +- docs/ref/forms/api.txt | 46 +- docs/ref/forms/fields.txt | 459 ++++---- docs/ref/forms/validation.txt | 114 +- docs/ref/forms/widgets.txt | 131 +-- docs/ref/generic-views.txt | 988 +++++++++--------- docs/ref/middleware.txt | 50 +- docs/ref/models/fields.txt | 58 +- docs/ref/models/instances.txt | 82 +- docs/ref/models/options.txt | 26 +- docs/ref/models/relations.txt | 30 +- docs/ref/request-response.txt | 76 +- docs/ref/settings.txt | 54 +- docs/ref/signals.txt | 85 +- docs/ref/template-response.txt | 12 +- docs/ref/templates/api.txt | 196 ++-- docs/ref/templates/builtins.txt | 282 ++--- docs/ref/unicode.txt | 90 +- docs/ref/utils.txt | 24 +- docs/releases/0.95.txt | 62 +- docs/releases/0.96.txt | 82 +- docs/releases/1.0-porting-guide.txt | 30 +- docs/releases/1.1-alpha-1.txt | 6 +- docs/releases/1.1-beta-1.txt | 60 +- docs/releases/1.1-rc-1.txt | 6 +- docs/releases/1.1.4.txt | 12 +- docs/releases/1.1.txt | 54 +- docs/releases/1.2-alpha-1.txt | 94 +- docs/releases/1.2-beta-1.txt | 6 +- docs/releases/1.2-rc-1.txt | 6 +- docs/releases/1.2.5.txt | 12 +- docs/releases/1.2.txt | 128 +-- docs/releases/1.3-alpha-1.txt | 36 +- docs/releases/1.3-beta-1.txt | 42 +- docs/releases/1.3.txt | 68 +- docs/topics/cache.txt | 170 +-- docs/topics/class-based-views.txt | 26 +- docs/topics/conditional-view-processing.txt | 32 +- docs/topics/db/managers.txt | 36 +- docs/topics/db/models.txt | 274 ++--- docs/topics/db/optimization.txt | 22 +- docs/topics/db/queries.txt | 74 +- docs/topics/db/transactions.txt | 34 +- docs/topics/email.txt | 166 +-- docs/topics/forms/index.txt | 68 +- docs/topics/forms/modelforms.txt | 124 +-- docs/topics/generic-views-migration.txt | 36 +- docs/topics/generic-views.txt | 26 +- docs/topics/http/file-uploads.txt | 176 ++-- docs/topics/http/middleware.txt | 26 +- docs/topics/http/sessions.txt | 80 +- docs/topics/http/shortcuts.txt | 50 +- docs/topics/http/urls.txt | 176 ++-- docs/topics/http/views.txt | 60 +- docs/topics/i18n/deployment.txt | 146 +-- docs/topics/i18n/index.txt | 36 +- docs/topics/i18n/internationalization.txt | 110 +- docs/topics/i18n/localization.txt | 46 +- docs/topics/install.txt | 20 +- docs/topics/logging.txt | 141 ++- docs/topics/serialization.txt | 18 +- docs/topics/settings.txt | 20 +- docs/topics/signals.txt | 28 +- docs/topics/signing.txt | 12 +- docs/topics/testing.txt | 312 +++--- 129 files changed, 5708 insertions(+), 5740 deletions(-) diff --git a/docs/faq/admin.txt b/docs/faq/admin.txt index a0e3b92c374..8ec74919033 100644 --- a/docs/faq/admin.txt +++ b/docs/faq/admin.txt @@ -8,16 +8,16 @@ The login cookie isn't being set correctly, because the domain of the cookie sent out by Django doesn't match the domain in your browser. Try these two things: - * Set the :setting:`SESSION_COOKIE_DOMAIN` setting in your admin config - file to match your domain. For example, if you're going to - "http://www.example.com/admin/" in your browser, in - "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.example.com'``. +* Set the :setting:`SESSION_COOKIE_DOMAIN` setting in your admin config + file to match your domain. For example, if you're going to + "http://www.example.com/admin/" in your browser, in + "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.example.com'``. - * Some browsers (Firefox?) don't like to accept cookies from domains that - don't have dots in them. If you're running the admin site on "localhost" - or another domain that doesn't have a dot in it, try going to - "localhost.localdomain" or "127.0.0.1". And set - :setting:`SESSION_COOKIE_DOMAIN` accordingly. +* Some browsers (Firefox?) don't like to accept cookies from domains that + don't have dots in them. If you're running the admin site on "localhost" + or another domain that doesn't have a dot in it, try going to + "localhost.localdomain" or "127.0.0.1". And set + :setting:`SESSION_COOKIE_DOMAIN` accordingly. I can't log in. When I enter a valid username and password, it brings up the login page again, with a "Please enter a correct username and password" error. ----------------------------------------------------------------------------------------------------------------------------------------------------------- diff --git a/docs/faq/contributing.txt b/docs/faq/contributing.txt index 2cf4ddddd8e..6f2dfd906fd 100644 --- a/docs/faq/contributing.txt +++ b/docs/faq/contributing.txt @@ -26,17 +26,17 @@ The best way to make sure tickets do not get hung up on the way to checkin is to make it dead easy, even for someone who may not be intimately familiar with that area of the code, to understand the problem and verify the fix: - * Are there clear instructions on how to reproduce the bug? If this - touches a dependency (such as PIL), a contrib module, or a specific - database, are those instructions clear enough even for someone not - familiar with it? +* Are there clear instructions on how to reproduce the bug? If this + touches a dependency (such as PIL), a contrib module, or a specific + database, are those instructions clear enough even for someone not + familiar with it? - * If there are several patches attached to the ticket, is it clear what - each one does, which ones can be ignored and which matter? +* If there are several patches attached to the ticket, is it clear what + each one does, which ones can be ignored and which matter? - * Does the patch include a unit test? If not, is there a very clear - explanation why not? A test expresses succinctly what the problem is, - and shows that the patch actually fixes it. +* Does the patch include a unit test? If not, is there a very clear + explanation why not? A test expresses succinctly what the problem is, + and shows that the patch actually fixes it. If your patch stands no chance of inclusion in Django, we won't ignore it -- we'll just close the ticket. So if your ticket is still open, it doesn't mean diff --git a/docs/faq/install.txt b/docs/faq/install.txt index 5ceb9caf52c..90b83f18eee 100644 --- a/docs/faq/install.txt +++ b/docs/faq/install.txt @@ -4,11 +4,11 @@ FAQ: Installation How do I get started? --------------------- - #. `Download the code`_. - #. Install Django (read the :doc:`installation guide `). - #. Walk through the :doc:`tutorial `. - #. Check out the rest of the :doc:`documentation `, and `ask questions`_ if you - run into trouble. +#. `Download the code`_. +#. Install Django (read the :doc:`installation guide `). +#. Walk through the :doc:`tutorial `. +#. Check out the rest of the :doc:`documentation `, and `ask questions`_ if you + run into trouble. .. _`Download the code`: http://www.djangoproject.com/download/ .. _ask questions: http://www.djangoproject.com/community/ diff --git a/docs/faq/usage.txt b/docs/faq/usage.txt index c11514c4cda..2b185be1a6d 100644 --- a/docs/faq/usage.txt +++ b/docs/faq/usage.txt @@ -6,21 +6,21 @@ Why do I get an error about importing DJANGO_SETTINGS_MODULE? Make sure that: - * The environment variable DJANGO_SETTINGS_MODULE is set to a - fully-qualified Python module (i.e. "mysite.settings"). +* The environment variable DJANGO_SETTINGS_MODULE is set to a + fully-qualified Python module (i.e. "mysite.settings"). - * Said module is on ``sys.path`` (``import mysite.settings`` should work). +* Said module is on ``sys.path`` (``import mysite.settings`` should work). - * The module doesn't contain syntax errors (of course). +* The module doesn't contain syntax errors (of course). - * If you're using mod_python but *not* using Django's request handler, - you'll need to work around a mod_python bug related to the use of - ``SetEnv``; before you import anything from Django you'll need to do - the following:: +* If you're using mod_python but *not* using Django's request handler, + you'll need to work around a mod_python bug related to the use of + ``SetEnv``; before you import anything from Django you'll need to do + the following:: - os.environ.update(req.subprocess_env) + os.environ.update(req.subprocess_env) - (where ``req`` is the mod_python request object). + (where ``req`` is the mod_python request object). I can't stand your template language. Do I have to use it? ---------------------------------------------------------- @@ -46,25 +46,25 @@ How do I use image and file fields? Using a :class:`~django.db.models.FileField` or an :class:`~django.db.models.ImageField` in a model takes a few steps: - #. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as - the full path to a directory where you'd like Django to store uploaded - files. (For performance, these files are not stored in the database.) - Define :setting:`MEDIA_URL` as the base public URL of that directory. - Make sure that this directory is writable by the Web server's user - account. +#. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as + the full path to a directory where you'd like Django to store uploaded + files. (For performance, these files are not stored in the database.) + Define :setting:`MEDIA_URL` as the base public URL of that directory. + Make sure that this directory is writable by the Web server's user + account. - #. Add the :class:`~django.db.models.FileField` or - :class:`~django.db.models.ImageField` to your model, making sure to - define the :attr:`~django.db.models.FileField.upload_to` option to tell - Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload - files. +#. Add the :class:`~django.db.models.FileField` or + :class:`~django.db.models.ImageField` to your model, making sure to + define the :attr:`~django.db.models.FileField.upload_to` option to tell + Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload + files. - #. All that will be stored in your database is a path to the file - (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the - convenience :attr:`~django.core.files.File.url` attribute provided by - Django. For example, if your :class:`~django.db.models.ImageField` is - called ``mug_shot``, you can get the absolute path to your image in a - template with ``{{ object.mug_shot.url }}``. +#. All that will be stored in your database is a path to the file + (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the + convenience :attr:`~django.core.files.File.url` attribute provided by + Django. For example, if your :class:`~django.db.models.ImageField` is + called ``mug_shot``, you can get the absolute path to your image in a + template with ``{{ object.mug_shot.url }}``. How do I make a variable available to all my templates? ------------------------------------------------------- diff --git a/docs/howto/apache-auth.txt b/docs/howto/apache-auth.txt index b3723f92c6a..215c519238d 100644 --- a/docs/howto/apache-auth.txt +++ b/docs/howto/apache-auth.txt @@ -14,12 +14,12 @@ dealing with Apache, you can configuring Apache to authenticate against Django's :doc:`authentication system ` directly. For example, you could: - * Serve static/media files directly from Apache only to authenticated users. +* Serve static/media files directly from Apache only to authenticated users. - * Authenticate access to a Subversion_ repository against Django users with - a certain permission. +* Authenticate access to a Subversion_ repository against Django users with + a certain permission. - * Allow certain users to connect to a WebDAV share created with mod_dav_. +* Allow certain users to connect to a WebDAV share created with mod_dav_. .. _Subversion: http://subversion.tigris.org/ .. _mod_dav: http://httpd.apache.org/docs/2.0/mod/mod_dav.html @@ -93,29 +93,29 @@ 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: - ================================ ========================================= - ``PythonOption`` Explanation - ================================ ========================================= - ``DjangoRequireStaffStatus`` If set to ``on`` only "staff" users (i.e. - those with the ``is_staff`` flag set) - will be allowed. +================================ ========================================= +``PythonOption`` Explanation +================================ ========================================= +``DjangoRequireStaffStatus`` If set to ``on`` only "staff" users (i.e. + those with the ``is_staff`` flag set) + will be allowed. - Defaults to ``on``. + Defaults to ``on``. - ``DjangoRequireSuperuserStatus`` If set to ``on`` only superusers (i.e. - those with the ``is_superuser`` flag set) - will be allowed. +``DjangoRequireSuperuserStatus`` If set to ``on`` only superusers (i.e. + those with the ``is_superuser`` flag set) + will be allowed. - Defaults to ``off``. + Defaults to ``off``. - ``DjangoPermissionName`` The name of a permission to require for - access. See :ref:`custom permissions - ` for more - information. +``DjangoPermissionName`` The name of a permission to require for + access. See :ref:`custom permissions + ` for more + information. - By default no specific permission will be - required. - ================================ ========================================= + By default no specific permission will be + required. +================================ ========================================= Note that sometimes ``SetEnv`` doesn't play well in this mod_python configuration, for reasons unknown. If you're having problems getting diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt index 6a431f36a69..5f1dae17ef8 100644 --- a/docs/howto/custom-file-storage.txt +++ b/docs/howto/custom-file-storage.txt @@ -37,11 +37,11 @@ You'll need to follow these steps: Your custom storage system may override any of the storage methods explained in :doc:`/ref/files/storage`, but you **must** implement the following methods: - * :meth:`Storage.delete` - * :meth:`Storage.exists` - * :meth:`Storage.listdir` - * :meth:`Storage.size` - * :meth:`Storage.url` +* :meth:`Storage.delete` +* :meth:`Storage.exists` +* :meth:`Storage.listdir` +* :meth:`Storage.size` +* :meth:`Storage.url` You'll also usually want to use hooks specifically designed for custom storage objects. These are: diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 475ad5ceb3e..1cf4ddb7297 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -133,14 +133,14 @@ example). If this sounds a bit tricky, don't worry -- it will become clearer in the examples below. Just remember that you will often end up creating two classes when you want a custom field: - * The first class is the Python object that your users will manipulate. - They will assign it to the model attribute, they will read from it for - displaying purposes, things like that. This is the ``Hand`` class in our - example. +* The first class is the Python object that your users will manipulate. + They will assign it to the model attribute, they will read from it for + displaying purposes, things like that. This is the ``Hand`` class in our + example. - * The second class is the ``Field`` subclass. This is the class that knows - how to convert your first class back and forth between its permanent - storage form and the Python form. +* The second class is the ``Field`` subclass. This is the class that knows + how to convert your first class back and forth between its permanent + storage form and the Python form. Writing a field subclass ======================== @@ -198,33 +198,33 @@ card values plus their suits; 104 characters in total. The :meth:`~django.db.models.Field.__init__` method takes the following parameters: - * :attr:`~django.db.models.Field.verbose_name` - * :attr:`~django.db.models.Field.name` - * :attr:`~django.db.models.Field.primary_key` - * :attr:`~django.db.models.Field.max_length` - * :attr:`~django.db.models.Field.unique` - * :attr:`~django.db.models.Field.blank` - * :attr:`~django.db.models.Field.null` - * :attr:`~django.db.models.Field.db_index` - * :attr:`~django.db.models.Field.rel`: Used for related fields (like - :class:`ForeignKey`). For advanced use only. - * :attr:`~django.db.models.Field.default` - * :attr:`~django.db.models.Field.editable` - * :attr:`~django.db.models.Field.serialize`: If ``False``, the field will - not be serialized when the model is passed to Django's :doc:`serializers - `. Defaults to ``True``. - * :attr:`~django.db.models.Field.unique_for_date` - * :attr:`~django.db.models.Field.unique_for_month` - * :attr:`~django.db.models.Field.unique_for_year` - * :attr:`~django.db.models.Field.choices` - * :attr:`~django.db.models.Field.help_text` - * :attr:`~django.db.models.Field.db_column` - * :attr:`~django.db.models.Field.db_tablespace`: Currently only used with - the Oracle backend and only for index creation. You can usually ignore - this option. - * :attr:`~django.db.models.Field.auto_created`: True if the field was - automatically created, as for the `OneToOneField` used by model - inheritance. For advanced use only. +* :attr:`~django.db.models.Field.verbose_name` +* :attr:`~django.db.models.Field.name` +* :attr:`~django.db.models.Field.primary_key` +* :attr:`~django.db.models.Field.max_length` +* :attr:`~django.db.models.Field.unique` +* :attr:`~django.db.models.Field.blank` +* :attr:`~django.db.models.Field.null` +* :attr:`~django.db.models.Field.db_index` +* :attr:`~django.db.models.Field.rel`: Used for related fields (like + :class:`ForeignKey`). For advanced use only. +* :attr:`~django.db.models.Field.default` +* :attr:`~django.db.models.Field.editable` +* :attr:`~django.db.models.Field.serialize`: If ``False``, the field will + not be serialized when the model is passed to Django's :doc:`serializers + `. Defaults to ``True``. +* :attr:`~django.db.models.Field.unique_for_date` +* :attr:`~django.db.models.Field.unique_for_month` +* :attr:`~django.db.models.Field.unique_for_year` +* :attr:`~django.db.models.Field.choices` +* :attr:`~django.db.models.Field.help_text` +* :attr:`~django.db.models.Field.db_column` +* :attr:`~django.db.models.Field.db_tablespace`: Currently only used with + the Oracle backend and only for index creation. You can usually ignore + this option. +* :attr:`~django.db.models.Field.auto_created`: True if the field was + automatically created, as for the `OneToOneField` used by model + inheritance. For advanced use only. All of the options without an explanation in the above list have the same meaning they do for normal Django fields. See the :doc:`field documentation @@ -415,11 +415,11 @@ that are more complex than strings, dates, integers or floats, then you'll need to override this method. As a general rule, the method should deal gracefully with any of the following arguments: - * An instance of the correct type (e.g., ``Hand`` in our ongoing example). +* An instance of the correct type (e.g., ``Hand`` in our ongoing example). - * A string (e.g., from a deserializer). +* A string (e.g., from a deserializer). - * Whatever the database returns for the column type you're using. +* Whatever the database returns for the column type you're using. In our ``HandField`` class, we're storing the data as a VARCHAR field in the database, so we need to be able to process strings and ``Hand`` instances in @@ -695,19 +695,19 @@ complex conversions between your Python types and your database and serialization formats. Here are a couple of tips to make things go more smoothly: - 1. Look at the existing Django fields (in - :file:`django/db/models/fields/__init__.py`) for inspiration. Try to find - a field that's similar to what you want and extend it a little bit, - instead of creating an entirely new field from scratch. +1. Look at the existing Django fields (in + :file:`django/db/models/fields/__init__.py`) for inspiration. Try to find + a field that's similar to what you want and extend it a little bit, + instead of creating an entirely new field from scratch. - 2. Put a :meth:`__str__` or :meth:`__unicode__` method on the class you're - wrapping up as a field. There are a lot of places where the default - behavior of the field code is to call - :func:`~django.utils.encoding.force_unicode` on the value. (In our - examples in this document, ``value`` would be a ``Hand`` instance, not a - ``HandField``). So if your :meth:`__unicode__` method automatically - converts to the string form of your Python object, you can save yourself - a lot of work. +2. Put a :meth:`__str__` or :meth:`__unicode__` method on the class you're + wrapping up as a field. There are a lot of places where the default + behavior of the field code is to call + :func:`~django.utils.encoding.force_unicode` on the value. (In our + examples in this document, ``value`` would be a ``Hand`` instance, not a + ``HandField``). So if your :meth:`__unicode__` method automatically + converts to the string form of your Python object, you can save yourself + a lot of work. Writing a ``FileField`` subclass @@ -735,14 +735,14 @@ A few suggestions In addition to the above details, there are a few guidelines which can greatly improve the efficiency and readability of the field's code. - 1. The source for Django's own ``ImageField`` (in - ``django/db/models/fields/files.py``) is a great example of how to - subclass ``FileField`` to support a particular type of file, as it - incorporates all of the techniques described above. +1. The source for Django's own ``ImageField`` (in + ``django/db/models/fields/files.py``) is a great example of how to + subclass ``FileField`` to support a particular type of file, as it + incorporates all of the techniques described above. - 2. Cache file attributes wherever possible. Since files may be stored in - remote storage systems, retrieving them may cost extra time, or even - money, that isn't always necessary. Once a file is retrieved to obtain - some data about its content, cache as much of that data as possible to - reduce the number of times the file must be retrieved on subsequent - calls for that information. +2. Cache file attributes wherever possible. Since files may be stored in + remote storage systems, retrieving them may cost extra time, or even + money, that isn't always necessary. Once a file is retrieved to obtain + some data about its content, cache as much of that data as possible to + reduce the number of times the file must be retrieved on subsequent + calls for that information. diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index c252e630f37..581d69c6316 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -77,9 +77,9 @@ Writing custom template filters Custom filters are just Python functions that take one or two arguments: - * The value of the variable (input) -- not necessarily a string. - * The value of the argument -- this can have a default value, or be left - out altogether. +* The value of the variable (input) -- not necessarily a string. +* The value of the argument -- this can have a default value, or be left + out altogether. For example, in the filter ``{{ var|foo:"bar" }}``, the filter ``foo`` would be passed the variable ``var`` and the argument ``"bar"``. @@ -124,9 +124,9 @@ your ``Library`` instance, to make it available to Django's template language: The ``Library.filter()`` method takes two arguments: - 1. The name of the filter -- a string. - 2. The compilation function -- a Python function (not the name of the - function as a string). +1. The name of the filter -- a string. +2. The compilation function -- a Python function (not the name of the + function as a string). You can use ``register.filter()`` as a decorator instead: @@ -173,156 +173,156 @@ When writing a custom filter, give some thought to how the filter will interact with Django's auto-escaping behavior. Note that three types of strings can be passed around inside the template code: - * **Raw strings** are the native Python ``str`` or ``unicode`` types. On - output, they're escaped if auto-escaping is in effect and presented - unchanged, otherwise. +* **Raw strings** are the native Python ``str`` or ``unicode`` types. On + output, they're escaped if auto-escaping is in effect and presented + unchanged, otherwise. - * **Safe strings** are strings that have been marked safe from further - escaping at output time. Any necessary escaping has already been done. - They're commonly used for output that contains raw HTML that is intended - to be interpreted as-is on the client side. +* **Safe strings** are strings that have been marked safe from further + escaping at output time. Any necessary escaping has already been done. + They're commonly used for output that contains raw HTML that is intended + to be interpreted as-is on the client side. - Internally, these strings are of type ``SafeString`` or ``SafeUnicode``. - They share a common base class of ``SafeData``, so you can test - for them using code like: + Internally, these strings are of type ``SafeString`` or ``SafeUnicode``. + They share a common base class of ``SafeData``, so you can test + for them using code like: - .. code-block:: python + .. code-block:: python - if isinstance(value, SafeData): - # Do something with the "safe" string. - ... + if isinstance(value, SafeData): + # Do something with the "safe" string. + ... - * **Strings marked as "needing escaping"** are *always* escaped on - output, regardless of whether they are in an :ttag:`autoescape` block or - not. These strings are only escaped once, however, even if auto-escaping - applies. +* **Strings marked as "needing escaping"** are *always* escaped on + output, regardless of whether they are in an :ttag:`autoescape` block or + not. These strings are only escaped once, however, even if auto-escaping + applies. - Internally, these strings are of type ``EscapeString`` or - ``EscapeUnicode``. Generally you don't have to worry about these; they - exist for the implementation of the :tfilter:`escape` filter. + Internally, these strings are of type ``EscapeString`` or + ``EscapeUnicode``. Generally you don't have to worry about these; they + exist for the implementation of the :tfilter:`escape` filter. Template filter code falls into one of two situations: - 1. Your filter does not introduce any HTML-unsafe characters (``<``, ``>``, - ``'``, ``"`` or ``&``) into the result that were not already present. In - this case, you can let Django take care of all the auto-escaping - handling for you. All you need to do is put the ``is_safe`` attribute on - your filter function and set it to ``True``, like so: +1. Your filter does not introduce any HTML-unsafe characters (``<``, ``>``, + ``'``, ``"`` or ``&``) into the result that were not already present. In + this case, you can let Django take care of all the auto-escaping + handling for you. All you need to do is put the ``is_safe`` attribute on + your filter function and set it to ``True``, like so: - .. code-block:: python + .. code-block:: python - @register.filter - def myfilter(value): - return value - myfilter.is_safe = True + @register.filter + def myfilter(value): + return value + myfilter.is_safe = True - This attribute tells Django that if a "safe" string is passed into your - filter, the result will still be "safe" and if a non-safe string is - passed in, Django will automatically escape it, if necessary. + This attribute tells Django that if a "safe" string is passed into your + filter, the result will still be "safe" and if a non-safe string is + passed in, Django will automatically escape it, if necessary. - You can think of this as meaning "this filter is safe -- it doesn't - introduce any possibility of unsafe HTML." + You can think of this as meaning "this filter is safe -- it doesn't + introduce any possibility of unsafe HTML." - The reason ``is_safe`` is necessary is because there are plenty of - normal string operations that will turn a ``SafeData`` object back into - a normal ``str`` or ``unicode`` object and, rather than try to catch - them all, which would be very difficult, Django repairs the damage after - the filter has completed. + The reason ``is_safe`` is necessary is because there are plenty of + normal string operations that will turn a ``SafeData`` object back into + a normal ``str`` or ``unicode`` object and, rather than try to catch + them all, which would be very difficult, Django repairs the damage after + the filter has completed. - For example, suppose you have a filter that adds the string ``xx`` to - the end of any input. Since this introduces no dangerous HTML characters - to the result (aside from any that were already present), you should - mark your filter with ``is_safe``: + For example, suppose you have a filter that adds the string ``xx`` to + the end of any input. Since this introduces no dangerous HTML characters + to the result (aside from any that were already present), you should + mark your filter with ``is_safe``: - .. code-block:: python + .. code-block:: python - @register.filter - def add_xx(value): - return '%sxx' % value - add_xx.is_safe = True + @register.filter + def add_xx(value): + return '%sxx' % value + add_xx.is_safe = True - When this filter is used in a template where auto-escaping is enabled, - Django will escape the output whenever the input is not already marked - as "safe". + When this filter is used in a template where auto-escaping is enabled, + Django will escape the output whenever the input is not already marked + as "safe". - By default, ``is_safe`` defaults to ``False``, and you can omit it from - any filters where it isn't required. + By default, ``is_safe`` defaults to ``False``, and you can omit it from + any filters where it isn't required. - Be careful when deciding if your filter really does leave safe strings - as safe. If you're *removing* characters, you might inadvertently leave - unbalanced HTML tags or entities in the result. For example, removing a - ``>`` from the input might turn ```` into ```` from the input might turn ```` into ``