test0908
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fixed #26020 -- Normalized header stylings in docs.

This commit is contained in:
Elif T. Kus 2016-01-03 12:56:22 +02:00 committed by Tim Graham
parent 79d0a4fdb0
commit bca9faae95
132 changed files with 1498 additions and 1464 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/contents.txt
View File

@ -1,5 +1,3 @@
.. _contents:
============================= =============================
Django documentation contents Django documentation contents
============================= =============================
@ -27,4 +25,4 @@ Indices, glossary and tables
* :ref:`genindex` * :ref:`genindex`
* :ref:`modindex` * :ref:`modindex`
* :ref:`glossary` * :doc:`glossary`

21
docs/faq/admin.txt
View File

@ -1,8 +1,9 @@
==============
FAQ: The admin FAQ: The admin
============== ==============
I can't log in. When I enter a valid username and password, it just brings up the login page again, with no error messages. I can't log in. When I enter a valid username and password, it just brings up the login page again, with no error messages.
--------------------------------------------------------------------------------------------------------------------------- ===========================================================================================================================
The login cookie isn't being set correctly, because the domain of the cookie 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 sent out by Django doesn't match the domain in your browser. Try these two
@ -14,7 +15,7 @@ things:
should set :setting:`SESSION_COOKIE_DOMAIN` = 'www.example.com'. should set :setting:`SESSION_COOKIE_DOMAIN` = 'www.example.com'.
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. 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.
----------------------------------------------------------------------------------------------------------------------------------------------------------- ===========================================================================================================================================================
If you're sure your username and password are correct, make sure your user If you're sure your username and password are correct, make sure your user
account has :attr:`~django.contrib.auth.models.User.is_active` and account has :attr:`~django.contrib.auth.models.User.is_active` and
@ -22,7 +23,7 @@ account has :attr:`~django.contrib.auth.models.User.is_active` and
only allows access to users with those two fields both set to True. only allows access to users with those two fields both set to True.
How do I automatically set a field's value to the user who last edited the object in the admin? How do I automatically set a field's value to the user who last edited the object in the admin?
----------------------------------------------------------------------------------------------- ===============================================================================================
The :class:`~django.contrib.admin.ModelAdmin` class provides customization hooks The :class:`~django.contrib.admin.ModelAdmin` class provides customization hooks
that allow you to transform an object as it saved, using details from the that allow you to transform an object as it saved, using details from the
@ -32,7 +33,7 @@ object to reflect the user that edited it. See :ref:`the documentation on
ModelAdmin methods <model-admin-methods>` for an example. ModelAdmin methods <model-admin-methods>` for an example.
How do I limit admin access so that objects can only be edited by the users who created them? How do I limit admin access so that objects can only be edited by the users who created them?
--------------------------------------------------------------------------------------------- =============================================================================================
The :class:`~django.contrib.admin.ModelAdmin` class also provides customization The :class:`~django.contrib.admin.ModelAdmin` class also provides customization
hooks that allow you to control the visibility and editability of objects in the hooks that allow you to control the visibility and editability of objects in the
@ -42,13 +43,13 @@ admin. Using the same trick of extracting the user from the request, the
control the visibility and editability of objects in the admin. control the visibility and editability of objects in the admin.
My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_wsgi. My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_wsgi.
--------------------------------------------------------------------------------------------------------------------------- =========================================================================================================================
See :ref:`serving the admin files <serving-the-admin-files>` See :ref:`serving the admin files <serving-the-admin-files>`
in the "How to use Django with mod_wsgi" documentation. in the "How to use Django with mod_wsgi" documentation.
My "list_filter" contains a ManyToManyField, but the filter doesn't display. My "list_filter" contains a ManyToManyField, but the filter doesn't display.
---------------------------------------------------------------------------- ============================================================================
Django won't bother displaying the filter for a ``ManyToManyField`` if there Django won't bother displaying the filter for a ``ManyToManyField`` if there
are fewer than two related objects. are fewer than two related objects.
@ -59,7 +60,7 @@ database, it won't display a "Site" filter. In that case, filtering by site
would be meaningless. would be meaningless.
Some objects aren't appearing in the admin. Some objects aren't appearing in the admin.
------------------------------------------- ===========================================
Inconsistent row counts may be caused by missing foreign key values or a Inconsistent row counts may be caused by missing foreign key values or a
foreign key field incorrectly set to :attr:`null=False foreign key field incorrectly set to :attr:`null=False
@ -71,7 +72,7 @@ shown in the admin changelist because the Django model is declaring an
integrity constraint that is not implemented at the database level. integrity constraint that is not implemented at the database level.
How can I customize the functionality of the admin interface? How can I customize the functionality of the admin interface?
------------------------------------------------------------- =============================================================
You've got several options. If you want to piggyback on top of an add/change You've got several options. If you want to piggyback on top of an add/change
form that Django automatically generates, you can attach arbitrary JavaScript form that Django automatically generates, you can attach arbitrary JavaScript
@ -89,7 +90,7 @@ If you want to customize the look-and-feel of the admin interface, read the
next question. next question.
The dynamically-generated admin site is ugly! How can I change it? The dynamically-generated admin site is ugly! How can I change it?
------------------------------------------------------------------ ==================================================================
We like it, but if you don't agree, you can modify the admin site's We like it, but if you don't agree, you can modify the admin site's
presentation by editing the CSS stylesheet and/or associated image files. The presentation by editing the CSS stylesheet and/or associated image files. The
@ -97,7 +98,7 @@ site is built using semantic HTML and plenty of CSS hooks, so any changes you'd
like to make should be possible by editing the stylesheet. like to make should be possible by editing the stylesheet.
What browsers are supported for using the admin? What browsers are supported for using the admin?
------------------------------------------------ ================================================
The admin provides a fully-functional experience to `YUI's A-grade`_ browsers, The admin provides a fully-functional experience to `YUI's A-grade`_ browsers,
with the notable exception of IE6, which is not supported. with the notable exception of IE6, which is not supported.

9
docs/faq/contributing.txt
View File

@ -1,14 +1,15 @@
======================
FAQ: Contributing code FAQ: Contributing code
====================== ======================
How can I get started contributing code to Django? How can I get started contributing code to Django?
-------------------------------------------------- ==================================================
Thanks for asking! We've written an entire document devoted to this question. Thanks for asking! We've written an entire document devoted to this question.
It's titled :doc:`Contributing to Django </internals/contributing/index>`. It's titled :doc:`Contributing to Django </internals/contributing/index>`.
I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch? I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch?
-------------------------------------------------------------------------------------------- ============================================================================================
Don't worry: We're not ignoring you! Don't worry: We're not ignoring you!
@ -43,7 +44,7 @@ we'll just close the ticket. So if your ticket is still open, it doesn't mean
we're ignoring you; it just means we haven't had time to look at it yet. we're ignoring you; it just means we haven't had time to look at it yet.
When and how might I remind the core team of a patch I care about? When and how might I remind the core team of a patch I care about?
------------------------------------------------------------------ ==================================================================
A polite, well-timed message to the mailing list is one way to get attention. A polite, well-timed message to the mailing list is one way to get attention.
To determine the right time, you need to keep an eye on the schedule. If you To determine the right time, you need to keep an eye on the schedule. If you
@ -70,7 +71,7 @@ additional attention -- certainly not the attention that you need in order to
get your pet bug addressed. get your pet bug addressed.
But I've reminded you several times and you keep ignoring my patch! But I've reminded you several times and you keep ignoring my patch!
------------------------------------------------------------------- ===================================================================
Seriously - we're not ignoring you. If your patch stands no chance of Seriously - we're not ignoring you. If your patch stands no chance of
inclusion in Django, we'll close the ticket. For all the other tickets, we inclusion in Django, we'll close the ticket. For all the other tickets, we

27
docs/faq/general.txt
View File

@ -1,8 +1,9 @@
============
FAQ: General FAQ: General
============ ============
Why does this project exist? Why does this project exist?
---------------------------- ============================
Django grew from a very practical need: World Online, a newspaper Web Django grew from a very practical need: World Online, a newspaper Web
operation, is responsible for building intensive Web applications on journalism operation, is responsible for building intensive Web applications on journalism
@ -29,7 +30,7 @@ thrilled to be able to give something back to the open-source community.
.. _PostgreSQL: http://www.postgresql.org/ .. _PostgreSQL: http://www.postgresql.org/
What does "Django" mean, and how do you pronounce it? What does "Django" mean, and how do you pronounce it?
----------------------------------------------------- =====================================================
Django is named after `Django Reinhardt`_, a gypsy jazz guitarist from the 1930s Django is named after `Django Reinhardt`_, a gypsy jazz guitarist from the 1930s
to early 1950s. To this day, he's considered one of the best guitarists of all time. to early 1950s. To this day, he's considered one of the best guitarists of all time.
@ -44,14 +45,14 @@ We've also recorded an `audio clip of the pronunciation`_.
.. _audio clip of the pronunciation: http://red-bean.com/~adrian/django_pronunciation.mp3 .. _audio clip of the pronunciation: http://red-bean.com/~adrian/django_pronunciation.mp3
Is Django stable? Is Django stable?
----------------- =================
Yes, it's quite stable. Companies like Disqus, Instagram, Pinterest, and Yes, it's quite stable. Companies like Disqus, Instagram, Pinterest, and
Mozilla have been using Django for many years. Sites built on Django have Mozilla have been using Django for many years. Sites built on Django have
weathered traffic spikes of over 50 thousand hits per second. weathered traffic spikes of over 50 thousand hits per second.
Does Django scale? Does Django scale?
------------------ ==================
Yes. Compared to development time, hardware is cheap, and so Django is Yes. Compared to development time, hardware is cheap, and so Django is
designed to take advantage of as much hardware as you can throw at it. designed to take advantage of as much hardware as you can throw at it.
@ -64,14 +65,14 @@ application layer. And it ships with a simple-yet-powerful
:doc:`cache framework </topics/cache>`. :doc:`cache framework </topics/cache>`.
Who's behind this? Who's behind this?
------------------ ==================
Django was originally developed at World Online, the Web department of a Django was originally developed at World Online, the Web department of a
newspaper in Lawrence, Kansas, USA. Django's now run by an international newspaper in Lawrence, Kansas, USA. Django's now run by an international
:doc:`team of volunteers </internals/team>`. :doc:`team of volunteers </internals/team>`.
Which sites use Django? Which sites use Django?
----------------------- =======================
`DjangoSites.org`_ features a constantly growing list of Django-powered sites. `DjangoSites.org`_ features a constantly growing list of Django-powered sites.
@ -80,7 +81,7 @@ Which sites use Django?
.. _faq-mtv: .. _faq-mtv:
Django appears to be a MVC framework, but you call the Controller the "view", and the View the "template". How come you don't use the standard names? Django appears to be a MVC framework, but you call the Controller the "view", and the View the "template". How come you don't use the standard names?
----------------------------------------------------------------------------------------------------------------------------------------------------- =====================================================================================================================================================
Well, the standard names are debatable. Well, the standard names are debatable.
@ -110,7 +111,7 @@ regardless of how things are named, Django gets stuff done in a way that's most
logical to us. logical to us.
<Framework X> does <feature Y> -- why doesn't Django? <Framework X> does <feature Y> -- why doesn't Django?
----------------------------------------------------- =====================================================
We're well aware that there are other awesome Web frameworks out there, and We're well aware that there are other awesome Web frameworks out there, and
we're not averse to borrowing ideas where appropriate. However, Django was we're not averse to borrowing ideas where appropriate. However, Django was
@ -119,7 +120,7 @@ aware that "because <Framework X> does it" is not going to be sufficient reason
to add a given feature to Django. to add a given feature to Django.
Why did you write all of Django from scratch, instead of using other Python libraries? Why did you write all of Django from scratch, instead of using other Python libraries?
-------------------------------------------------------------------------------------- ======================================================================================
When Django was originally written a couple of years ago, Adrian and Simon When Django was originally written a couple of years ago, Adrian and Simon
spent quite a bit of time exploring the various Python Web frameworks spent quite a bit of time exploring the various Python Web frameworks
@ -145,7 +146,7 @@ We've documented our philosophies on the
:doc:`design philosophies page </misc/design-philosophies>`. :doc:`design philosophies page </misc/design-philosophies>`.
Is Django a content-management-system (CMS)? Is Django a content-management-system (CMS)?
-------------------------------------------- ============================================
No, Django is not a CMS, or any sort of "turnkey product" in and of itself. No, Django is not a CMS, or any sort of "turnkey product" in and of itself.
It's a Web framework; it's a programming tool that lets you build websites. It's a Web framework; it's a programming tool that lets you build websites.
@ -162,7 +163,7 @@ means!).
.. _Drupal: https://drupal.org/ .. _Drupal: https://drupal.org/
How can I download the Django documentation to read it offline? How can I download the Django documentation to read it offline?
--------------------------------------------------------------- ===============================================================
The Django docs are available in the ``docs`` directory of each Django tarball The Django docs are available in the ``docs`` directory of each Django tarball
release. These docs are in reST (reStructuredText) format, and each text file release. These docs are in reST (reStructuredText) format, and each text file
@ -178,7 +179,7 @@ information than the docs that come with the latest Django release.
.. _stored in revision control: https://github.com/django/django/tree/master/docs/ .. _stored in revision control: https://github.com/django/django/tree/master/docs/
Where can I find Django developers for hire? Where can I find Django developers for hire?
-------------------------------------------- ============================================
Consult our `developers for hire page`_ for a list of Django developers who Consult our `developers for hire page`_ for a list of Django developers who
would be happy to help you. would be happy to help you.
@ -190,7 +191,7 @@ https://people.djangoproject.com/ .
.. _developers for hire page: https://code.djangoproject.com/wiki/DevelopersForHire .. _developers for hire page: https://code.djangoproject.com/wiki/DevelopersForHire
How do I cite Django? How do I cite Django?
--------------------- =====================
It's difficult to give an official citation format, for two reasons: citation It's difficult to give an official citation format, for two reasons: citation
formats can vary wildly between publications, and citation standards for formats can vary wildly between publications, and citation standards for

11
docs/faq/help.txt
View File

@ -1,8 +1,9 @@
=================
FAQ: Getting Help FAQ: Getting Help
================= =================
How do I do X? Why doesn't Y work? Where can I go to get help? How do I do X? Why doesn't Y work? Where can I go to get help?
-------------------------------------------------------------- ==============================================================
If this FAQ doesn't contain an answer to your question, you might want to If this FAQ doesn't contain an answer to your question, you might want to
try the |django-users| mailing list. Feel free to ask any question related try the |django-users| mailing list. Feel free to ask any question related
@ -16,7 +17,7 @@ active community of helpful individuals who may be able to solve your problem.
.. _message-does-not-appear-on-django-users: .. _message-does-not-appear-on-django-users:
Why hasn't my message appeared on django-users? Why hasn't my message appeared on django-users?
----------------------------------------------- ===============================================
|django-users| has a lot of subscribers. This is good for the community, as |django-users| has a lot of subscribers. This is good for the community, as
it means many people are available to contribute answers to questions. it means many people are available to contribute answers to questions.
@ -30,7 +31,7 @@ list might take a little longer to get answered. We apologize for any
inconvenience that this policy may cause. inconvenience that this policy may cause.
Nobody on django-users answered my question! What should I do? Nobody on django-users answered my question! What should I do?
-------------------------------------------------------------- ==============================================================
Try making your question more specific, or provide a better example of your Try making your question more specific, or provide a better example of your
problem. problem.
@ -48,13 +49,13 @@ for discussion of the development of Django itself. Asking a tech support
question there is considered quite impolite. question there is considered quite impolite.
I think I've found a bug! What should I do? I think I've found a bug! What should I do?
------------------------------------------- ===========================================
Detailed instructions on how to handle a potential bug can be found in our Detailed instructions on how to handle a potential bug can be found in our
:ref:`Guide to contributing to Django <reporting-bugs>`. :ref:`Guide to contributing to Django <reporting-bugs>`.
I think I've found a security problem! What should I do? I think I've found a security problem! What should I do?
-------------------------------------------------------- ========================================================
If you think you've found a security problem with Django, please send a message If you think you've found a security problem with Django, please send a message
to security@djangoproject.com. This is a private list only open to long-time, to security@djangoproject.com. This is a private list only open to long-time,

11
docs/faq/install.txt
View File

@ -1,8 +1,9 @@
=================
FAQ: Installation FAQ: Installation
================= =================
How do I get started? How do I get started?
--------------------- =====================
#. `Download the code`_. #. `Download the code`_.
#. Install Django (read the :doc:`installation guide </intro/install>`). #. Install Django (read the :doc:`installation guide </intro/install>`).
@ -14,7 +15,7 @@ How do I get started?
.. _ask questions: https://www.djangoproject.com/community/ .. _ask questions: https://www.djangoproject.com/community/
What are Django's prerequisites? What are Django's prerequisites?
-------------------------------- ================================
Django requires Python. See the table in the next question for the versions of Django requires Python. See the table in the next question for the versions of
Python that work with each version of Django. Other Python libraries may be Python that work with each version of Django. Other Python libraries may be
@ -40,7 +41,7 @@ PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported.
.. _faq-python-version-support: .. _faq-python-version-support:
What Python version can I use with Django? What Python version can I use with Django?
------------------------------------------ ==========================================
============== =============== ============== ===============
Django version Python versions Django version Python versions
@ -60,7 +61,7 @@ version of Python ends. For example, Python 3.3 security support ends September
is the last version to support Python 3.3. is the last version to support Python 3.3.
What Python version should I use with Django? What Python version should I use with Django?
--------------------------------------------- =============================================
As of Django 1.6, Python 3 support is considered stable and you can safely use As of Django 1.6, Python 3 support is considered stable and you can safely use
it in production. See also :doc:`/topics/python3`. However, the community is it in production. See also :doc:`/topics/python3`. However, the community is
@ -81,7 +82,7 @@ Third-party applications for use with Django are, of course, free to set their
own version requirements. own version requirements.
Should I use the stable version or development version? Should I use the stable version or development version?
------------------------------------------------------- =======================================================
Generally, if you're using code in production, you should be using a Generally, if you're using code in production, you should be using a
stable release. The Django project publishes a full stable release stable release. The Django project publishes a full stable release

13
docs/faq/models.txt
View File

@ -1,10 +1,11 @@
=========================
FAQ: Databases and models FAQ: Databases and models
========================= =========================
.. _faq-see-raw-sql-queries: .. _faq-see-raw-sql-queries:
How can I see the raw SQL queries Django is running? How can I see the raw SQL queries Django is running?
---------------------------------------------------- ====================================================
Make sure your Django :setting:`DEBUG` setting is set to ``True``. Make sure your Django :setting:`DEBUG` setting is set to ``True``.
Then, just do this:: Then, just do this::
@ -37,12 +38,12 @@ just call ``reset_queries()``, like this::
reset_queries() reset_queries()
Can I use Django with a pre-existing database? Can I use Django with a pre-existing database?
---------------------------------------------- ==============================================
Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`. Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`.
If I make changes to a model, how do I update the database? If I make changes to a model, how do I update the database?
----------------------------------------------------------- ===========================================================
Take a look at Django's support for :mod:`schema migrations Take a look at Django's support for :mod:`schema migrations
<django.db.migrations>`. <django.db.migrations>`.
@ -52,7 +53,7 @@ If you don't mind clearing data, your project's ``manage.py`` utility has a
immediately after :djadmin:`migrate` was executed. immediately after :djadmin:`migrate` was executed.
Do Django models support multiple-column primary keys? Do Django models support multiple-column primary keys?
------------------------------------------------------ ======================================================
No. Only single-column primary keys are supported. No. Only single-column primary keys are supported.
@ -64,7 +65,7 @@ as the admin interface to work; e.g., you need a simple way of being able to
specify an object to edit or delete. specify an object to edit or delete.
Does Django support NoSQL databases? Does Django support NoSQL databases?
------------------------------------ ====================================
NoSQL databases are not officially supported by Django itself. There are, NoSQL databases are not officially supported by Django itself. There are,
however, a number of side project and forks which allow NoSQL functionality in however, a number of side project and forks which allow NoSQL functionality in
@ -76,7 +77,7 @@ You can also take a look on `the wiki page`_ which discusses some alternatives.
.. _`the wiki page`: https://code.djangoproject.com/wiki/NoSqlSupport .. _`the wiki page`: https://code.djangoproject.com/wiki/NoSqlSupport
How do I add database-specific options to my CREATE TABLE statements, such as specifying MyISAM as the table type? How do I add database-specific options to my CREATE TABLE statements, such as specifying MyISAM as the table type?
------------------------------------------------------------------------------------------------------------------ ==================================================================================================================
We try to avoid adding special cases in the Django code to accommodate all the We try to avoid adding special cases in the Django code to accommodate all the
database-specific options such as table type, etc. If you'd like to use any of database-specific options such as table type, etc. If you'd like to use any of

11
docs/faq/usage.txt
View File

@ -1,8 +1,9 @@
=================
FAQ: Using Django FAQ: Using Django
================= =================
Why do I get an error about importing DJANGO_SETTINGS_MODULE? Why do I get an error about importing DJANGO_SETTINGS_MODULE?
------------------------------------------------------------- =============================================================
Make sure that: Make sure that:
@ -14,7 +15,7 @@ Make sure that:
* The module doesn't contain syntax errors (of course). * The module doesn't contain syntax errors (of course).
I can't stand your template language. Do I have to use it? I can't stand your template language. Do I have to use it?
---------------------------------------------------------- ==========================================================
We happen to think our template engine is the best thing since chunky bacon, We happen to think our template engine is the best thing since chunky bacon,
but we recognize that choosing a template language runs close to religion. but we recognize that choosing a template language runs close to religion.
@ -22,7 +23,7 @@ There's nothing about Django that requires using the template language, so
if you're attached to Jinja2, Mako, or whatever, feel free to use those. if you're attached to Jinja2, Mako, or whatever, feel free to use those.
Do I have to use your model/database layer? Do I have to use your model/database layer?
------------------------------------------- ===========================================
Nope. Just like the template system, the model/database layer is decoupled from Nope. Just like the template system, the model/database layer is decoupled from
the rest of the framework. the rest of the framework.
@ -32,7 +33,7 @@ use Django's automatically-generated admin site. That app is coupled to the
Django database layer. Django database layer.
How do I use image and file fields? How do I use image and file fields?
----------------------------------- ===================================
Using a :class:`~django.db.models.FileField` or an Using a :class:`~django.db.models.FileField` or an
:class:`~django.db.models.ImageField` in a model takes a few steps: :class:`~django.db.models.ImageField` in a model takes a few steps:
@ -58,7 +59,7 @@ Using a :class:`~django.db.models.FileField` or an
``{{ object.mug_shot.url }}``. ``{{ object.mug_shot.url }}``.
How do I make a variable available to all my templates? How do I make a variable available to all my templates?
------------------------------------------------------- =======================================================
Sometimes your templates just all need the same thing. A common example would Sometimes your templates just all need the same thing. A common example would
be dynamically-generated menus. At first glance, it seems logical to simply be dynamically-generated menus. At first glance, it seems logical to simply

2
docs/glossary.txt
View File

@ -1,5 +1,3 @@
.. _glossary:
======== ========
Glossary Glossary
======== ========

1
docs/howto/custom-file-storage.txt
View File

@ -1,3 +1,4 @@
===============================
Writing a custom storage system Writing a custom storage system
=============================== ===============================

14
docs/howto/custom-lookups.txt
View File

@ -10,7 +10,7 @@ explains how to write custom lookups and how to alter the working of existing
lookups. For the API references of lookups, see the :doc:`/ref/models/lookups`. lookups. For the API references of lookups, see the :doc:`/ref/models/lookups`.
A simple lookup example A simple lookup example
~~~~~~~~~~~~~~~~~~~~~~~ =======================
Let's start with a simple custom lookup. We will write a custom lookup ``ne`` Let's start with a simple custom lookup. We will write a custom lookup ``ne``
which works opposite to ``exact``. ``Author.objects.filter(name__ne='Jack')`` which works opposite to ``exact``. ``Author.objects.filter(name__ne='Jack')``
@ -93,7 +93,7 @@ the parameters for the query. We then return a tuple containing the generated
SQL string and the parameters. SQL string and the parameters.
A simple transformer example A simple transformer example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ============================
The custom lookup above is great, but in some cases you may want to be able to The custom lookup above is great, but in some cases you may want to be able to
chain lookups together. For example, let's suppose we are building an chain lookups together. For example, let's suppose we are building an
@ -159,8 +159,8 @@ be done by adding an ``output_field`` attribute to the transform::
This ensures that further lookups like ``abs__lte`` behave as they would for This ensures that further lookups like ``abs__lte`` behave as they would for
a ``FloatField``. a ``FloatField``.
Writing an efficient abs__lt lookup Writing an efficient ``abs__lt`` lookup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =======================================
When using the above written ``abs`` lookup, the SQL produced will not use When using the above written ``abs`` lookup, the SQL produced will not use
indexes efficiently in some cases. In particular, when we use indexes efficiently in some cases. In particular, when we use
@ -211,7 +211,7 @@ transformations in Python.
be very efficient. be very efficient.
A bilateral transformer example A bilateral transformer example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ===============================
The ``AbsoluteValue`` example we discussed previously is a transformation which The ``AbsoluteValue`` example we discussed previously is a transformation which
applies to the left-hand side of the lookup. There may be some cases where you applies to the left-hand side of the lookup. There may be some cases where you
@ -248,7 +248,7 @@ insensitive query like this::
SELECT ... WHERE UPPER("author"."name") = UPPER('doe') SELECT ... WHERE UPPER("author"."name") = UPPER('doe')
Writing alternative implementations for existing lookups Writing alternative implementations for existing lookups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ========================================================
Sometimes different database vendors require different SQL for the same Sometimes different database vendors require different SQL for the same
operation. For this example we will rewrite a custom implementation for operation. For this example we will rewrite a custom implementation for
@ -276,7 +276,7 @@ methods, and then falls back to ``as_sql``. The vendor names for the in-built
backends are ``sqlite``, ``postgresql``, ``oracle`` and ``mysql``. backends are ``sqlite``, ``postgresql``, ``oracle`` and ``mysql``.
How Django determines the lookups and transforms which are used How Django determines the lookups and transforms which are used
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ===============================================================
In some cases you may wish to dynamically change which ``Transform`` or In some cases you may wish to dynamically change which ``Transform`` or
``Lookup`` is returned based on the name passed in, rather than fixing it. As ``Lookup`` is returned based on the name passed in, rather than fixing it. As

42
docs/howto/custom-template-tags.txt
View File

@ -11,7 +11,7 @@ defining custom tags and filters using Python, and then make them
available to your templates using the :ttag:`{% load %}<load>` tag. available to your templates using the :ttag:`{% load %}<load>` tag.
Code layout Code layout
----------- ===========
The most common place to specify custom template tags and filters is inside The most common place to specify custom template tags and filters is inside
a Django app. If they relate to an existing app, it makes sense to bundle them a Django app. If they relate to an existing app, it makes sense to bundle them
@ -89,7 +89,7 @@ an application.
.. _howto-writing-custom-template-filters: .. _howto-writing-custom-template-filters:
Writing custom template filters Writing custom template filters
------------------------------- ===============================
Custom filters are just Python functions that take one or two arguments: Custom filters are just Python functions that take one or two arguments:
@ -127,7 +127,7 @@ your function. Example::
return value.lower() return value.lower()
Registering custom filters Registering custom filters
~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------
.. method:: django.template.Library.filter() .. method:: django.template.Library.filter()
@ -162,7 +162,7 @@ are described in :ref:`filters and auto-escaping <filters-auto-escaping>` and
:ref:`filters and time zones <filters-timezones>` below. :ref:`filters and time zones <filters-timezones>` below.
Template filters that expect strings Template filters that expect strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------
.. method:: django.template.defaultfilters.stringfilter() .. method:: django.template.defaultfilters.stringfilter()
@ -187,7 +187,7 @@ methods).
.. _filters-auto-escaping: .. _filters-auto-escaping:
Filters and auto-escaping Filters and auto-escaping
~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------
When writing a custom filter, give some thought to how the filter will interact 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 with Django's auto-escaping behavior. Note that three types of strings can be
@ -376,7 +376,7 @@ Template filter code falls into one of two situations:
.. _filters-timezones: .. _filters-timezones:
Filters and time zones Filters and time zones
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
If you write a custom filter that operates on :class:`~datetime.datetime` If you write a custom filter that operates on :class:`~datetime.datetime`
objects, you'll usually register it with the ``expects_localtime`` flag set to objects, you'll usually register it with the ``expects_localtime`` flag set to
@ -397,7 +397,7 @@ conversions in templates <time-zones-in-templates>`.
.. _howto-writing-custom-template-tags: .. _howto-writing-custom-template-tags:
Writing custom template tags Writing custom template tags
---------------------------- ============================
Tags are more complex than filters, because tags can do anything. Django Tags are more complex than filters, because tags can do anything. Django
provides a number of shortcuts that make writing most types of tags easier. provides a number of shortcuts that make writing most types of tags easier.
@ -407,7 +407,7 @@ scratch for those cases when the shortcuts aren't powerful enough.
.. _howto-custom-template-tags-simple-tags: .. _howto-custom-template-tags-simple-tags:
Simple tags Simple tags
~~~~~~~~~~~ -----------
.. method:: django.template.Library.simple_tag() .. method:: django.template.Library.simple_tag()
@ -514,7 +514,7 @@ you see fit:
.. _howto-custom-template-tags-inclusion-tags: .. _howto-custom-template-tags-inclusion-tags:
Inclusion tags Inclusion tags
~~~~~~~~~~~~~~ --------------
.. method:: django.template.Library.inclusion_tag() .. method:: django.template.Library.inclusion_tag()
@ -648,7 +648,7 @@ positional arguments. For example:
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %} {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}
Assignment tags Assignment tags
~~~~~~~~~~~~~~~ ---------------
.. method:: django.template.Library.assignment_tag() .. method:: django.template.Library.assignment_tag()
@ -677,14 +677,14 @@ followed by the variable name, and output it yourself where you see fit:
<p>The time is {{ the_time }}.</p> <p>The time is {{ the_time }}.</p>
Advanced custom template tags Advanced custom template tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
Sometimes the basic features for custom template tag creation aren't enough. Sometimes the basic features for custom template tag creation aren't enough.
Don't worry, Django gives you complete access to the internals required to build Don't worry, Django gives you complete access to the internals required to build
a template tag from the ground up. a template tag from the ground up.
A quick overview A quick overview
~~~~~~~~~~~~~~~~ ----------------
The template system works in a two-step process: compiling and rendering. To The template system works in a two-step process: compiling and rendering. To
define a custom template tag, you specify how the compilation works and how define a custom template tag, you specify how the compilation works and how
@ -702,7 +702,7 @@ converted into a ``Node`` (the compilation function), and what the node's
``render()`` method does. ``render()`` method does.
Writing the compilation function Writing the compilation function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
For each template tag the template parser encounters, it calls a Python For each template tag the template parser encounters, it calls a Python
function with the tag contents and the parser object itself. This function is function with the tag contents and the parser object itself. This function is
@ -772,7 +772,7 @@ Notes:
engine too slow. It's low-level because that's fastest. engine too slow. It's low-level because that's fastest.
Writing the renderer Writing the renderer
~~~~~~~~~~~~~~~~~~~~ --------------------
The second step in writing custom tags is to define a ``Node`` subclass that The second step in writing custom tags is to define a ``Node`` subclass that
has a ``render()`` method. has a ``render()`` method.
@ -811,7 +811,7 @@ without having to be parsed multiple times.
.. _tags-auto-escaping: .. _tags-auto-escaping:
Auto-escaping considerations Auto-escaping considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
The output from template tags is **not** automatically run through the The output from template tags is **not** automatically run through the
auto-escaping filters (with the exception of auto-escaping filters (with the exception of
@ -853,7 +853,7 @@ tag is used inside a :ttag:`{% autoescape off %}<autoescape>` block.
.. _template_tag_thread_safety: .. _template_tag_thread_safety:
Thread-safety considerations Thread-safety considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
Once a node is parsed, its ``render`` method may be called any number of times. Once a node is parsed, its ``render`` method may be called any number of times.
Since Django is sometimes run in multi-threaded environments, a single node may Since Django is sometimes run in multi-threaded environments, a single node may
@ -936,7 +936,7 @@ like the current iteration of the ``CycleNode``, should be stored in the
variables, make ``render_context[self]`` a dictionary. variables, make ``render_context[self]`` a dictionary.
Registering the tag Registering the tag
~~~~~~~~~~~~~~~~~~~ -------------------
Finally, register the tag with your module's ``Library`` instance, as explained Finally, register the tag with your module's ``Library`` instance, as explained
in :ref:`writing custom template filters<howto-writing-custom-template-tags>` in :ref:`writing custom template filters<howto-writing-custom-template-tags>`
@ -965,7 +965,7 @@ If you leave off the ``name`` argument, as in the second example above, Django
will use the function's name as the tag name. will use the function's name as the tag name.
Passing template variables to the tag Passing template variables to the tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------
Although you can pass any number of arguments to a template tag using Although you can pass any number of arguments to a template tag using
``token.split_contents()``, the arguments are all unpacked as ``token.split_contents()``, the arguments are all unpacked as
@ -1032,7 +1032,7 @@ Variable resolution will throw a ``VariableDoesNotExist`` exception if it
cannot resolve the string passed to it in the current context of the page. cannot resolve the string passed to it in the current context of the page.
Setting a variable in the context Setting a variable in the context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------
The above examples simply output a value. Generally, it's more flexible if your The above examples simply output a value. Generally, it's more flexible if your
template tags set template variables instead of outputting values. That way, template tags set template variables instead of outputting values. That way,
@ -1123,7 +1123,7 @@ context-updating template tag, consider using the
the tag results to a template variable. the tag results to a template variable.
Parsing until another block tag Parsing until another block tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
Template tags can work in tandem. For instance, the standard Template tags can work in tandem. For instance, the standard
:ttag:`{% comment %}<comment>` tag hides everything until ``{% endcomment %}``. :ttag:`{% comment %}<comment>` tag hides everything until ``{% endcomment %}``.
@ -1167,7 +1167,7 @@ After ``parser.parse()`` is called, the parser hasn't yet "consumed" the
``{% comment %}`` and ``{% endcomment %}`` is ignored. ``{% comment %}`` and ``{% endcomment %}`` is ignored.
Parsing until another block tag, and saving contents Parsing until another block tag, and saving contents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------------
In the previous example, ``do_comment()`` discarded everything between In the previous example, ``do_comment()`` discarded everything between
``{% comment %}`` and ``{% endcomment %}``. Instead of doing that, it's ``{% comment %}`` and ``{% endcomment %}``. Instead of doing that, it's

1
docs/howto/deployment/index.txt
View File

@ -1,3 +1,4 @@
================
Deploying Django Deploying Django
================ ================

6
docs/howto/deployment/wsgi/index.txt
View File

@ -22,7 +22,7 @@ Django includes getting-started documentation for the following WSGI servers:
uwsgi uwsgi
The ``application`` object The ``application`` object
-------------------------- ==========================
The key concept of deploying with WSGI is the ``application`` callable which The key concept of deploying with WSGI is the ``application`` callable which
the application server uses to communicate with your code. It's commonly the application server uses to communicate with your code. It's commonly
@ -42,7 +42,7 @@ set to ``<project_name>.wsgi.application``, which points to the ``application``
callable in :file:`<project_name>/wsgi.py`. callable in :file:`<project_name>/wsgi.py`.
Configuring the settings module Configuring the settings module
------------------------------- ===============================
When the WSGI server loads your application, Django needs to import the When the WSGI server loads your application, Django needs to import the
settings module — that's where your entire application is defined. settings module — that's where your entire application is defined.
@ -68,7 +68,7 @@ If this variable isn't set, the default :file:`wsgi.py` sets it to
Applying WSGI middleware Applying WSGI middleware
------------------------ ========================
To apply `WSGI middleware`_ you can simply wrap the application object. For To apply `WSGI middleware`_ you can simply wrap the application object. For
instance you could add these lines at the bottom of :file:`wsgi.py`:: instance you could add these lines at the bottom of :file:`wsgi.py`::

13
docs/howto/error-reporting.txt
View File

@ -1,3 +1,4 @@
===============
Error reporting Error reporting
=============== ===============
@ -12,10 +13,10 @@ You need to keep track of errors that occur in deployed sites, so Django can be
configured to create reports with details about those errors. configured to create reports with details about those errors.
Email reports Email reports
------------- =============
Server errors Server errors
~~~~~~~~~~~~~ -------------
When :setting:`DEBUG` is ``False``, Django will email the users listed in the When :setting:`DEBUG` is ``False``, Django will email the users listed in the
:setting:`ADMINS` setting whenever your code raises an unhandled exception and :setting:`ADMINS` setting whenever your code raises an unhandled exception and
@ -49,7 +50,7 @@ To activate this behavior, put the email addresses of the recipients in the
</topics/logging>`. </topics/logging>`.
404 errors 404 errors
~~~~~~~~~~ ----------
Django can also be configured to email errors about broken links (404 "page Django can also be configured to email errors about broken links (404 "page
not found" errors). Django sends emails about 404 errors when: not found" errors). Django sends emails about 404 errors when:
@ -119,7 +120,7 @@ and override its methods.
.. _filtering-error-reports: .. _filtering-error-reports:
Filtering error reports Filtering error reports
----------------------- =======================
.. warning:: .. warning::
@ -130,7 +131,7 @@ Filtering error reports
through email). through email).
Filtering sensitive information Filtering sensitive information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
.. currentmodule:: django.views.decorators.debug .. currentmodule:: django.views.decorators.debug
@ -231,7 +232,7 @@ production environment (that is, where :setting:`DEBUG` is set to ``False``):
.. _custom-error-reports: .. _custom-error-reports:
Custom error reports Custom error reports
~~~~~~~~~~~~~~~~~~~~ --------------------
All :func:`sensitive_variables` and :func:`sensitive_post_parameters` do is, All :func:`sensitive_variables` and :func:`sensitive_post_parameters` do is,
respectively, annotate the decorated function with the names of sensitive respectively, annotate the decorated function with the names of sensitive

1
docs/howto/index.txt
View File

@ -1,3 +1,4 @@
===============
"How-to" guides "How-to" guides
=============== ===============

2
docs/howto/outputting-csv.txt
View File

@ -76,7 +76,7 @@ mention:
.. _streaming-csv-files: .. _streaming-csv-files:
Streaming large CSV files Streaming large CSV files
~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------
When dealing with views that generate very large responses, you might want to When dealing with views that generate very large responses, you might want to
consider using Django's :class:`~django.http.StreamingHttpResponse` instead. consider using Django's :class:`~django.http.StreamingHttpResponse` instead.

6
docs/howto/writing-migrations.txt
View File

@ -9,7 +9,7 @@ migrations, see :doc:`the topic guide </topics/migrations>`.
.. _data-migrations-and-multiple-databases: .. _data-migrations-and-multiple-databases:
Data migrations and multiple databases Data migrations and multiple databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ======================================
When using multiple databases, you may need to figure out whether or not to When using multiple databases, you may need to figure out whether or not to
run a migration against a particular database. For example, you may want to run a migration against a particular database. For example, you may want to
@ -72,7 +72,7 @@ practice to pass ``model_name`` as a hint to make it as transparent as possible
to the router. This is especially important for reusable and third-party apps. to the router. This is especially important for reusable and third-party apps.
Migrations that add unique fields Migrations that add unique fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =================================
Applying a "plain" migration that adds a unique non-nullable field to a table Applying a "plain" migration that adds a unique non-nullable field to a table
with existing rows will raise an error because the value used to populate with existing rows will raise an error because the value used to populate
@ -185,7 +185,7 @@ the respective field according to your needs.
``RunPython`` will have their original ``uuid``’s overwritten. ``RunPython`` will have their original ``uuid``’s overwritten.
Controlling the order of migrations Controlling the order of migrations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ===================================
Django determines the order in which migrations should be applied not by the Django determines the order in which migrations should be applied not by the
filename of each migration, but by building a graph using two properties on the filename of each migration, but by building a graph using two properties on the

3
docs/index.txt
View File

@ -1,6 +1,3 @@
.. _index:
==================== ====================
Django documentation Django documentation
==================== ====================

8
docs/internals/contributing/bugs-and-features.txt
View File

@ -32,7 +32,7 @@ general points:
.. _reporting-bugs: .. _reporting-bugs:
Reporting bugs Reporting bugs
-------------- ==============
Well-written bug reports are *incredibly* helpful. However, there's a certain Well-written bug reports are *incredibly* helpful. However, there's a certain
amount of overhead involved in working with any bug tracking system so your amount of overhead involved in working with any bug tracking system so your
@ -61,7 +61,7 @@ To understand the lifecycle of your ticket once you have created it, refer to
:doc:`triaging-tickets`. :doc:`triaging-tickets`.
Reporting user interface bugs and features Reporting user interface bugs and features
------------------------------------------ ==========================================
If your bug or feature request touches on anything visual in nature, there If your bug or feature request touches on anything visual in nature, there
are a few additional guidelines to follow: are a few additional guidelines to follow:
@ -87,7 +87,7 @@ are a few additional guidelines to follow:
find your ticket. find your ticket.
Requesting features Requesting features
------------------- ===================
We're always trying to make Django better, and your feature requests are a key We're always trying to make Django better, and your feature requests are a key
part of that. Here are some tips on how to make a request most effectively: part of that. Here are some tips on how to make a request most effectively:
@ -128,7 +128,7 @@ See also: :ref:`documenting-new-features`.
.. _how-we-make-decisions: .. _how-we-make-decisions:
How we make decisions How we make decisions
--------------------- =====================
Whenever possible, we strive for a rough consensus. To that end, we'll often Whenever possible, we strive for a rough consensus. To that end, we'll often
have informal votes on |django-developers| about a feature. In these votes we have informal votes on |django-developers| about a feature. In these votes we

6
docs/internals/contributing/committing-code.txt
View File

@ -10,7 +10,7 @@ who wants to contribute code to Django, have a look at
.. _handling-pull-requests: .. _handling-pull-requests:
Handling pull requests Handling pull requests
---------------------- ======================
Since Django is now hosted at GitHub, most patches are provided in the form of Since Django is now hosted at GitHub, most patches are provided in the form of
pull requests. pull requests.
@ -101,7 +101,7 @@ community, getting work done, and having a usable commit history.
.. _committing-guidelines: .. _committing-guidelines:
Committing guidelines Committing guidelines
--------------------- =====================
In addition, please follow the following guidelines when committing code to In addition, please follow the following guidelines when committing code to
Django's Git repository: Django's Git repository:
@ -200,7 +200,7 @@ Django's Git repository:
to automate this. to automate this.
Reverting commits Reverting commits
----------------- =================
Nobody's perfect; mistakes will be committed. Nobody's perfect; mistakes will be committed.

8
docs/internals/contributing/localizing.txt
View File

@ -9,7 +9,7 @@ and localization infrastructure available to Django applications, described in
the :doc:`i18n documentation </topics/i18n/index>`. the :doc:`i18n documentation </topics/i18n/index>`.
Translations Translations
------------ ============
Translations are contributed by Django users worldwide. The translation work is Translations are contributed by Django users worldwide. The translation work is
coordinated at `Transifex`_. coordinated at `Transifex`_.
@ -53,11 +53,11 @@ translation manager's availability. So don't miss the string freeze period
to complete and fix the translations for your language! to complete and fix the translations for your language!
Formats Formats
------- =======
You can also review ``conf/locale/<locale>/formats.py``. This file describes You can also review ``conf/locale/<locale>/formats.py``. This file describes
the date, time and numbers formatting particularities of your locale. See the date, time and numbers formatting particularities of your locale. See
:ref:`format-localization` for details. :doc:`/topics/i18n/formatting` for details.
The format files aren't managed by the use of Transifex. To change them, you The format files aren't managed by the use of Transifex. To change them, you
must :doc:`create a patch<writing-code/submitting-patches>` against the must :doc:`create a patch<writing-code/submitting-patches>` against the
@ -75,7 +75,7 @@ Django source tree, as for any code change:
.. _translating-documentation: .. _translating-documentation:
Documentation Documentation
------------- =============
There is also an opportunity to translate the documentation, though this is a There is also an opportunity to translate the documentation, though this is a
huge undertaking to complete entirely (you have been warned!). We use the same huge undertaking to complete entirely (you have been warned!). We use the same

6
docs/internals/contributing/new-contributors.txt
View File

@ -11,7 +11,7 @@ to get started? This is the section for you.
tutorial will give you an introduction to the tools and the workflow. tutorial will give you an introduction to the tools and the workflow.
First steps First steps
----------- ===========
Start with these easy tasks to discover Django's development process. Start with these easy tasks to discover Django's development process.
@ -70,7 +70,7 @@ Start with these easy tasks to discover Django's development process.
Guidelines Guidelines
---------- ==========
As a newcomer on a large project, it's easy to experience frustration. Here's As a newcomer on a large project, it's easy to experience frustration. Here's
some advice to make your work on Django more useful and rewarding. some advice to make your work on Django more useful and rewarding.
@ -138,7 +138,7 @@ some advice to make your work on Django more useful and rewarding.
.. _new-contributors-faq: .. _new-contributors-faq:
FAQ FAQ
--- ===
1. **This ticket I care about has been ignored for days/weeks/months! What can 1. **This ticket I care about has been ignored for days/weeks/months! What can
I do to get it committed?** I do to get it committed?**

44
docs/internals/contributing/triaging-tickets.txt
View File

@ -32,7 +32,7 @@ Django is a community project, and every contribution helps. We can't do this
without **you**! without **you**!
Triage workflow Triage workflow
--------------- ===============
Unfortunately, not all bug reports and feature requests in the ticket tracker Unfortunately, not all bug reports and feature requests in the ticket tracker
provide all the :doc:`required details<bugs-and-features>`. A number of provide all the :doc:`required details<bugs-and-features>`. A number of
@ -96,20 +96,20 @@ require much much more.
.. _triage-stages: .. _triage-stages:
Triage stages Triage stages
------------- =============
Below we describe in more detail the various stages that a ticket may flow Below we describe in more detail the various stages that a ticket may flow
through during its lifetime. through during its lifetime.
Unreviewed Unreviewed
~~~~~~~~~~ ----------
The ticket has not been reviewed by anyone who felt qualified to make a The ticket has not been reviewed by anyone who felt qualified to make a
judgment about whether the ticket contained a valid issue, a viable feature, judgment about whether the ticket contained a valid issue, a viable feature,
or ought to be closed for any of the various reasons. or ought to be closed for any of the various reasons.
Accepted Accepted
~~~~~~~~ --------
The big gray area! The absolute meaning of "accepted" is that the issue The big gray area! The absolute meaning of "accepted" is that the issue
described in the ticket is valid and is in some stage of being worked on. described in the ticket is valid and is in some stage of being worked on.
@ -142,7 +142,7 @@ Beyond that there are several considerations:
explaining what is needed to improve the code. explaining what is needed to improve the code.
Ready For Checkin Ready For Checkin
~~~~~~~~~~~~~~~~~ -----------------
The ticket was reviewed by any member of the community other than the person The ticket was reviewed by any member of the community other than the person
who supplied the patch and found to meet all the requirements for a who supplied the patch and found to meet all the requirements for a
@ -152,7 +152,7 @@ review prior to being committed. See the
RFC forever! What should I do?" RFC forever! What should I do?"
Someday/Maybe Someday/Maybe
~~~~~~~~~~~~~ -------------
This stage isn't shown on the diagram. It's only used by core developers to This stage isn't shown on the diagram. It's only used by core developers to
keep track of high-level ideas or long term feature requests. keep track of high-level ideas or long term feature requests.
@ -163,12 +163,12 @@ consider adding someday to the framework if an excellent patch is submitted.
They are not a high priority. They are not a high priority.
Other triage attributes Other triage attributes
----------------------- =======================
A number of flags, appearing as checkboxes in Trac, can be set on a ticket: A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
Has patch Has patch
~~~~~~~~~ ---------
This means the ticket has an associated This means the ticket has an associated
:doc:`patch<writing-code/submitting-patches>`. These will be reviewed :doc:`patch<writing-code/submitting-patches>`. These will be reviewed
@ -178,20 +178,20 @@ The following three fields (Needs documentation, Needs tests,
Patch needs improvement) apply only if a patch has been supplied. Patch needs improvement) apply only if a patch has been supplied.
Needs documentation Needs documentation
~~~~~~~~~~~~~~~~~~~ -------------------
This flag is used for tickets with patches that need associated This flag is used for tickets with patches that need associated
documentation. Complete documentation of features is a prerequisite documentation. Complete documentation of features is a prerequisite
before we can check them into the codebase. before we can check them into the codebase.
Needs tests Needs tests
~~~~~~~~~~~ -----------
This flags the patch as needing associated unit tests. Again, this This flags the patch as needing associated unit tests. Again, this
is a required part of a valid patch. is a required part of a valid patch.
Patch needs improvement Patch needs improvement
~~~~~~~~~~~~~~~~~~~~~~~ -----------------------
This flag means that although the ticket *has* a patch, it's not quite This flag means that although the ticket *has* a patch, it's not quite
ready for checkin. This could mean the patch no longer applies ready for checkin. This could mean the patch no longer applies
@ -199,12 +199,12 @@ cleanly, there is a flaw in the implementation, or that the code
doesn't meet our standards. doesn't meet our standards.
Easy pickings Easy pickings
~~~~~~~~~~~~~ -------------
Tickets that would require small, easy, patches. Tickets that would require small, easy, patches.
Type Type
~~~~ ----
Tickets should be categorized by *type* between: Tickets should be categorized by *type* between:
@ -219,14 +219,14 @@ Tickets should be categorized by *type* between:
better, faster, stronger. better, faster, stronger.
Component Component
~~~~~~~~~ ---------
Tickets should be classified into *components* indicating which area of Tickets should be classified into *components* indicating which area of
the Django codebase they belong to. This makes tickets better organized and the Django codebase they belong to. This makes tickets better organized and
easier to find. easier to find.
Severity Severity
~~~~~~~~ --------
The *severity* attribute is used to identify blockers, that is, issues which The *severity* attribute is used to identify blockers, that is, issues which
should get fixed before releasing the next version of Django. Typically those should get fixed before releasing the next version of Django. Typically those
@ -235,26 +235,26 @@ causing severe data losses. This attribute is quite rarely used and the vast
majority of tickets have a severity of "Normal". majority of tickets have a severity of "Normal".
Version Version
~~~~~~~ -------
It is possible to use the *version* attribute to indicate in which It is possible to use the *version* attribute to indicate in which
version the reported bug was identified. version the reported bug was identified.
UI/UX UI/UX
~~~~~ -----
This flag is used for tickets that relate to User Interface and User This flag is used for tickets that relate to User Interface and User
Experiences questions. For example, this flag would be appropriate for Experiences questions. For example, this flag would be appropriate for
user-facing features in forms or the admin interface. user-facing features in forms or the admin interface.
Cc Cc
~~ --
You may add your username or email address to this field to be notified when You may add your username or email address to this field to be notified when
new contributions are made to the ticket. new contributions are made to the ticket.
Keywords Keywords
~~~~~~~~ --------
With this field you may label a ticket with multiple keywords. This can be With this field you may label a ticket with multiple keywords. This can be
useful, for example, to group several tickets of a same theme. Keywords can useful, for example, to group several tickets of a same theme. Keywords can
@ -266,7 +266,7 @@ as "formset", "modelformset", and "ManagementForm".
.. _closing-tickets: .. _closing-tickets:
Closing Tickets Closing Tickets
--------------- ===============
When a ticket has completed its useful lifecycle, it's time for it to be When a ticket has completed its useful lifecycle, it's time for it to be
closed. Closing a ticket is a big responsibility, though. You have to be sure closed. Closing a ticket is a big responsibility, though. You have to be sure
@ -338,7 +338,7 @@ developers and bring the issue to |django-developers| instead.
.. _how-can-i-help-with-triaging: .. _how-can-i-help-with-triaging:
How can I help with triaging? How can I help with triaging?
----------------------------- =============================
The triage process is primarily driven by community members. Really, The triage process is primarily driven by community members. Really,
**ANYONE** can help. **ANYONE** can help.
@ -422,7 +422,7 @@ the ticket database:
.. _password reset page: https://www.djangoproject.com/accounts/password/reset/ .. _password reset page: https://www.djangoproject.com/accounts/password/reset/
Bisecting a regression Bisecting a regression
---------------------- ======================
.. highlight:: console .. highlight:: console

16
docs/internals/contributing/writing-code/coding-style.txt
View File

@ -5,7 +5,7 @@ Coding style
Please follow these coding standards when writing code for inclusion in Django. Please follow these coding standards when writing code for inclusion in Django.
Python style Python style
------------ ============
* Please conform to the indentation style dictated in the ``.editorconfig`` * Please conform to the indentation style dictated in the ``.editorconfig``
file. We recommend using a text editor with `EditorConfig`_ support to avoid file. We recommend using a text editor with `EditorConfig`_ support to avoid
@ -52,7 +52,7 @@ Python style
to use regular expression matching. to use regular expression matching.
Imports Imports
------- =======
* Use `isort <https://github.com/timothycrosley/isort#readme>`_ to automate * Use `isort <https://github.com/timothycrosley/isort#readme>`_ to automate
import sorting using the guidelines below. import sorting using the guidelines below.
@ -132,7 +132,7 @@ Imports
from django.views.generic.base import View from django.views.generic.base import View
Template style Template style
-------------- ==============
* In Django template code, put one (and only one) space between the curly * In Django template code, put one (and only one) space between the curly
brackets and the tag contents. brackets and the tag contents.
@ -150,7 +150,7 @@ Template style
{{foo}} {{foo}}
View style View style
---------- ==========
* In Django views, the first parameter in a view function should be called * In Django views, the first parameter in a view function should be called
``request``. ``request``.
@ -166,7 +166,7 @@ View style
# ... # ...
Model style Model style
----------- ===========
* Field names should be all lowercase, using underscores instead of * Field names should be all lowercase, using underscores instead of
camelCase. camelCase.
@ -240,7 +240,7 @@ Model style
) )
Use of ``django.conf.settings`` Use of ``django.conf.settings``
------------------------------- ===============================
Modules should not in general use settings stored in ``django.conf.settings`` Modules should not in general use settings stored in ``django.conf.settings``
at the top level (i.e. evaluated when the module is imported). The explanation at the top level (i.e. evaluated when the module is imported). The explanation
@ -276,7 +276,7 @@ such as ``django.utils.functional.LazyObject``,
``django.utils.functional.lazy()`` or ``lambda``. ``django.utils.functional.lazy()`` or ``lambda``.
Miscellaneous Miscellaneous
------------- =============
* Mark all strings for internationalization; see the :doc:`i18n * Mark all strings for internationalization; see the :doc:`i18n
documentation </topics/i18n/index>` for details. documentation </topics/i18n/index>` for details.
@ -299,7 +299,7 @@ Miscellaneous
single trivial change. single trivial change.
JavaScript style JavaScript style
---------------- ================
For details about the JavaScript code style used by Django, see For details about the JavaScript code style used by Django, see
:doc:`javascript`. :doc:`javascript`.

16
docs/internals/contributing/writing-code/javascript.txt
View File

@ -9,7 +9,7 @@ Please follow these coding standards when writing JavaScript code for inclusion
in Django. in Django.
Code style Code style
---------- ==========
* Please conform to the indentation style dictated in the ``.editorconfig`` * Please conform to the indentation style dictated in the ``.editorconfig``
file. We recommend using a text editor with `EditorConfig`_ support to avoid file. We recommend using a text editor with `EditorConfig`_ support to avoid
@ -27,7 +27,7 @@ Code style
.. _javascript-patches: .. _javascript-patches:
JavaScript patches JavaScript patches
------------------ ==================
Django's admin system leverages the jQuery framework to increase the Django's admin system leverages the jQuery framework to increase the
capabilities of the admin interface. In conjunction, there is an emphasis on capabilities of the admin interface. In conjunction, there is an emphasis on
@ -41,7 +41,7 @@ production use (e.g. ``foo.min.js``). Any links to the file in the codebase
should point to the compressed version. should point to the compressed version.
Compressing JavaScript Compressing JavaScript
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
To simplify the process of providing optimized JavaScript code, Django To simplify the process of providing optimized JavaScript code, Django
includes a handy Python script which should be used to create a "minified" includes a handy Python script which should be used to create a "minified"
@ -61,13 +61,13 @@ Please don't forget to run ``compress.py`` and include the ``diff`` of the
minified scripts when submitting patches for Django's JavaScript. minified scripts when submitting patches for Django's JavaScript.
JavaScript tests JavaScript tests
---------------- ================
Django's JavaScript tests can be run in a browser or from the command line. Django's JavaScript tests can be run in a browser or from the command line.
The tests are located in a top level ``js_tests`` directory. The tests are located in a top level ``js_tests`` directory.
Writing tests Writing tests
~~~~~~~~~~~~~ -------------
Django's JavaScript tests use `QUnit`_. Here is an example test module: Django's JavaScript tests use `QUnit`_. Here is an example test module:
@ -101,12 +101,12 @@ Please consult the QUnit documentation for information on the types of
`assertions supported by QUnit <https://api.qunitjs.com/category/assert/>`_. `assertions supported by QUnit <https://api.qunitjs.com/category/assert/>`_.
Running tests Running tests
~~~~~~~~~~~~~ -------------
The JavaScript tests may be run from a web browser or from the command line. The JavaScript tests may be run from a web browser or from the command line.
Testing from a web browser Testing from a web browser
^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~
To run the tests from a web browser, open up ``js_tests/tests.html`` in your To run the tests from a web browser, open up ``js_tests/tests.html`` in your
browser. browser.
@ -119,7 +119,7 @@ over HTTP. To view code coverage:
* Open http://localhost:8000/js_tests/tests.html in your web browser. * Open http://localhost:8000/js_tests/tests.html in your web browser.
Testing from the command line Testing from the command line
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To run the tests from the command line, you need to have `Node.js`_ installed. To run the tests from the command line, you need to have `Node.js`_ installed.

30
docs/internals/contributing/writing-code/submitting-patches.txt
View File

@ -7,7 +7,7 @@ with associated patches will get fixed *far* more quickly than those
without patches. without patches.
Typo fixes and trivial documentation changes Typo fixes and trivial documentation changes
-------------------------------------------- ============================================
If you are fixing a really trivial issue, for example changing a word in the If you are fixing a really trivial issue, for example changing a word in the
documentation, the preferred way to provide the patch is using GitHub pull documentation, the preferred way to provide the patch is using GitHub pull
@ -16,7 +16,7 @@ requests without a Trac ticket.
See the :doc:`working-with-git` for more details on how to use pull requests. See the :doc:`working-with-git` for more details on how to use pull requests.
"Claiming" tickets "Claiming" tickets
------------------ ==================
In an open-source project with hundreds of contributors around the world, it's In an open-source project with hundreds of contributors around the world, it's
important to manage communication efficiently so that work doesn't get important to manage communication efficiently so that work doesn't get
@ -62,7 +62,7 @@ and time availability), claim it by following these steps:
.. _Contributor License Agreement: https://www.djangoproject.com/foundation/cla/ .. _Contributor License Agreement: https://www.djangoproject.com/foundation/cla/
Ticket claimers' responsibility Ticket claimers' responsibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
Once you've claimed a ticket, you have a responsibility to work on that ticket Once you've claimed a ticket, you have a responsibility to work on that ticket
in a reasonably timely fashion. If you don't have time to work on it, either in a reasonably timely fashion. If you don't have time to work on it, either
@ -80,7 +80,7 @@ your claim on the ticket may be revoked.
As always, more communication is better than less communication! As always, more communication is better than less communication!
Which tickets should be claimed? Which tickets should be claimed?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
Of course, going through the steps of claiming tickets is overkill in some Of course, going through the steps of claiming tickets is overkill in some
cases. cases.
@ -96,7 +96,7 @@ or not, to submit patches to a ticket if you happen to have a patch ready.
.. _patch-style: .. _patch-style:
Patch style Patch style
----------- ===========
Make sure that any contribution you do fulfills at least the following Make sure that any contribution you do fulfills at least the following
requirements: requirements:
@ -143,7 +143,7 @@ Regardless of the way you submit your work, follow these steps.
.. _Development dashboard: https://dashboard.djangoproject.com/ .. _Development dashboard: https://dashboard.djangoproject.com/
Non-trivial patches Non-trivial patches
------------------- ===================
A "non-trivial" patch is one that is more than a simple bug fix. It's a patch A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
that introduces Django functionality and makes some sort of design decision. that introduces Django functionality and makes some sort of design decision.
@ -157,7 +157,7 @@ ask.
.. _deprecating-a-feature: .. _deprecating-a-feature:
Deprecating a feature Deprecating a feature
--------------------- =====================
There are a couple reasons that code in Django might be deprecated: There are a couple reasons that code in Django might be deprecated:
@ -233,7 +233,7 @@ In each :term:`feature release`, all ``RemovedInDjangoXXWarning``\s matching
the new version are removed. the new version are removed.
JavaScript patches JavaScript patches
------------------ ==================
For information on JavaScript patches, see the :ref:`javascript-patches` For information on JavaScript patches, see the :ref:`javascript-patches`
documentation. documentation.
@ -241,7 +241,7 @@ documentation.
.. _patch-review-checklist: .. _patch-review-checklist:
Patch review checklist Patch review checklist
---------------------- ======================
Use this checklist to review a pull request. If you are reviewing a pull Use this checklist to review a pull request. If you are reviewing a pull
request that is not your own and it passes all the criteria below, please set request that is not your own and it passes all the criteria below, please set
@ -260,7 +260,7 @@ Looking to get your patch reviewed? Ensure the Trac flags on the ticket are
set so that the ticket appears in that queue. set so that the ticket appears in that queue.
Documentation Documentation
~~~~~~~~~~~~~ -------------
* Does the documentation build without any errors (``make html``, or * Does the documentation build without any errors (``make html``, or
``make.bat html`` on Windows, from the ``docs`` directory)? ``make.bat html`` on Windows, from the ``docs`` directory)?
@ -269,13 +269,13 @@ Documentation
* Are there any :ref:`spelling errors <documentation-spelling-check>`? * Are there any :ref:`spelling errors <documentation-spelling-check>`?
Bugs Bugs
~~~~ ----
* Is there a proper regression test (the test should fail before the fix * Is there a proper regression test (the test should fail before the fix
is applied)? is applied)?
New Features New Features
~~~~~~~~~~~~ ------------
* Are there tests to "exercise" all of the new code? * Are there tests to "exercise" all of the new code?
* Is there a release note in ``docs/releases/A.B.txt``? * Is there a release note in ``docs/releases/A.B.txt``?
@ -284,12 +284,12 @@ New Features
``.. versionadded:: A.B`` or ``.. versionchanged:: A.B``? ``.. versionadded:: A.B`` or ``.. versionchanged:: A.B``?
Deprecating a feature Deprecating a feature
~~~~~~~~~~~~~~~~~~~~~ ---------------------
See the :ref:`deprecating-a-feature` guide. See the :ref:`deprecating-a-feature` guide.
All code changes All code changes
~~~~~~~~~~~~~~~~ ----------------
* Does the :doc:`coding style * Does the :doc:`coding style
</internals/contributing/writing-code/coding-style>` conform to our </internals/contributing/writing-code/coding-style>` conform to our
@ -300,7 +300,7 @@ All code changes
to build the pull request against our continuous integration server. to build the pull request against our continuous integration server.
All tickets All tickets
~~~~~~~~~~~ -----------
* Is the pull request a single squashed commit with a message that follows our * Is the pull request a single squashed commit with a message that follows our
:ref:`commit message format <committing-guidelines>`? :ref:`commit message format <committing-guidelines>`?

26
docs/internals/contributing/writing-code/unit-tests.txt
View File

@ -16,10 +16,10 @@ how to write new tests.
.. _running-unit-tests: .. _running-unit-tests:
Running the unit tests Running the unit tests
---------------------- ======================
Quickstart Quickstart
~~~~~~~~~~ ----------
If you are on Python 2, you'll first need to install a backport of the If you are on Python 2, you'll first need to install a backport of the
``unittest.mock`` module that's available in Python 3. See ``unittest.mock`` module that's available in Python 3. See
@ -48,7 +48,7 @@ Having problems? See :ref:`troubleshooting-unit-tests` for some common issues.
.. _running-unit-tests-settings: .. _running-unit-tests-settings:
Using another ``settings`` module Using another ``settings`` module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------
The included settings module allows you to run the test suite using The included settings module allows you to run the test suite using
SQLite. If you want to test behavior using a different database (and SQLite. If you want to test behavior using a different database (and
@ -92,7 +92,7 @@ test settings dictionary for the applicable database.
.. _runtests-specifying-labels: .. _runtests-specifying-labels:
Running only some of the tests Running only some of the tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
Django's entire test suite takes a while to run, and running every single test Django's entire test suite takes a while to run, and running every single test
could be redundant if, say, you just added a test to Django that you want to could be redundant if, say, you just added a test to Django that you want to
@ -119,7 +119,7 @@ Going beyond that, you can specify an individual test method like this::
$ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects $ ./runtests.py --settings=path.to.settings i18n.tests.TranslationTests.test_lazy_objects
Running the Selenium tests Running the Selenium tests
~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------
Some tests require Selenium and a Web browser (Firefox, Google Chrome, or Some tests require Selenium and a Web browser (Firefox, Google Chrome, or
Internet Explorer). To allow those tests to be run rather than skipped, you must Internet Explorer). To allow those tests to be run rather than skipped, you must
@ -131,7 +131,7 @@ install the selenium_ package into your Python path and run the tests with the
.. _running-unit-tests-dependencies: .. _running-unit-tests-dependencies:
Running all the tests Running all the tests
~~~~~~~~~~~~~~~~~~~~~ ---------------------
If you want to run the full suite of tests, you'll need to install a number of If you want to run the full suite of tests, you'll need to install a number of
dependencies: dependencies:
@ -188,7 +188,7 @@ associated tests will be skipped.
.. _pip requirements files: https://pip.pypa.io/en/latest/user_guide.html#requirements-files .. _pip requirements files: https://pip.pypa.io/en/latest/user_guide.html#requirements-files
Code coverage Code coverage
~~~~~~~~~~~~~ -------------
Contributors are encouraged to run coverage on the test suite to identify areas Contributors are encouraged to run coverage on the test suite to identify areas
that need additional tests. The coverage tool installation and use is described that need additional tests. The coverage tool installation and use is described
@ -211,7 +211,7 @@ and also excludes several directories not relevant to the results
.. _contrib-apps: .. _contrib-apps:
Contrib apps Contrib apps
------------ ============
Tests for contrib apps can be found in the ``tests/`` directory, typically Tests for contrib apps can be found in the ``tests/`` directory, typically
under ``<app_name>_tests``. For example, tests for ``contrib.auth`` are located under ``<app_name>_tests``. For example, tests for ``contrib.auth`` are located
@ -220,10 +220,10 @@ in ``tests/auth_tests``.
.. _troubleshooting-unit-tests: .. _troubleshooting-unit-tests:
Troubleshooting Troubleshooting
--------------- ===============
Many test failures with ``UnicodeEncodeError`` Many test failures with ``UnicodeEncodeError``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------
If the ``locales`` package is not installed, some tests will fail with a If the ``locales`` package is not installed, some tests will fail with a
``UnicodeEncodeError``. ``UnicodeEncodeError``.
@ -234,7 +234,7 @@ You can resolve this on Debian-based systems, for example, by running::
$ dpkg-reconfigure locales $ dpkg-reconfigure locales
Tests that only fail in combination Tests that only fail in combination
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------
In case a test passes when run in isolation but fails within the whole suite, In case a test passes when run in isolation but fails within the whole suite,
we have some tools to help analyze the problem. we have some tools to help analyze the problem.
@ -279,7 +279,7 @@ cause any trouble::
$ ./runtests.py basic --reverse $ ./runtests.py basic --reverse
Seeing the SQL queries run during a test Seeing the SQL queries run during a test
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------
If you wish to examine the SQL being run in failing tests, you can turn on If you wish to examine the SQL being run in failing tests, you can turn on
:ref:`SQL logging <django-db-logger>` using the ``--debug-sql`` option. If you :ref:`SQL logging <django-db-logger>` using the ``--debug-sql`` option. If you
@ -288,7 +288,7 @@ combine this with ``--verbosity=2``, all SQL queries will be output::
$ ./runtests.py basic --debug-sql $ ./runtests.py basic --debug-sql
Seeing the full traceback of a test failure Seeing the full traceback of a test failure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------
By default tests are run in parallel with one process per core. When the tests By default tests are run in parallel with one process per core. When the tests
are run in parallel, however, you'll only see a truncated traceback for any are run in parallel, however, you'll only see a truncated traceback for any

19
docs/internals/contributing/writing-code/working-with-git.txt
View File

@ -1,3 +1,4 @@
===========================
Working with Git and GitHub Working with Git and GitHub
=========================== ===========================
@ -14,7 +15,7 @@ You could also upload a traditional patch to Trac, but it's less practical for
reviews. reviews.
Installing Git Installing Git
-------------- ==============
Django uses `Git`_ for its source control. You can `download Django uses `Git`_ for its source control. You can `download
<http://git-scm.com/download>`_ Git, but it's often easier to install with <http://git-scm.com/download>`_ Git, but it's often easier to install with
@ -38,7 +39,7 @@ used to associate your commits with your GitHub account.
.. _GitHub: https://github.com/ .. _GitHub: https://github.com/
Setting up local repository Setting up local repository
--------------------------- ===========================
When you have created your GitHub account, with the nick "GitHub_nick", and When you have created your GitHub account, with the nick "GitHub_nick", and
forked Django's repository, create a local copy of your fork:: forked Django's repository, create a local copy of your fork::
@ -64,7 +65,7 @@ You can add other remotes similarly, for example::
git remote add akaariai git@github.com:akaariai/django.git git remote add akaariai git@github.com:akaariai/django.git
Working on a ticket Working on a ticket
------------------- ===================
When working on a ticket create a new branch for the work, and base that work When working on a ticket create a new branch for the work, and base that work
on upstream/master:: on upstream/master::
@ -94,7 +95,7 @@ necessary::
git commit -m 'Added two more tests for edge cases' git commit -m 'Added two more tests for edge cases'
Publishing work Publishing work
~~~~~~~~~~~~~~~ ---------------
You can publish your work on GitHub just by doing:: You can publish your work on GitHub just by doing::
@ -143,7 +144,7 @@ ready for merging -- or sufficiently close that a committer will finish it
himself. himself.
Rebasing branches Rebasing branches
~~~~~~~~~~~~~~~~~ -----------------
In the example above you created two commits, the "Fixed ticket_xxxxx" commit In the example above you created two commits, the "Fixed ticket_xxxxx" commit
and "Added two more tests" commit. and "Added two more tests" commit.
@ -189,7 +190,7 @@ commit hashes do not match any more. This is acceptable, as the branch is merely
a topic branch, and nobody should be basing their work on it. a topic branch, and nobody should be basing their work on it.
After upstream has changed After upstream has changed
~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------
When upstream (django/django) has changed, you should rebase your work. To When upstream (django/django) has changed, you should rebase your work. To
do this, use:: do this, use::
@ -215,7 +216,7 @@ This way your branch will contain only commits related to its topic, which
makes squashing easier. makes squashing easier.
After review After review
~~~~~~~~~~~~ ------------
It is unusual to get any non-trivial amount of code into core without changes It is unusual to get any non-trivial amount of code into core without changes
requested by reviewers. In this case, it is often a good idea to add the requested by reviewers. In this case, it is often a good idea to add the
@ -247,7 +248,7 @@ Note that the committer is likely to squash the review commit into the previous
commit when committing the code. commit when committing the code.
Working on a patch Working on a patch
------------------ ==================
One of the ways that developers can contribute to Django is by reviewing One of the ways that developers can contribute to Django is by reviewing
patches. Those patches will typically exist as pull requests on GitHub and patches. Those patches will typically exist as pull requests on GitHub and
@ -264,7 +265,7 @@ For more detail on working with pull requests see the
:ref:`guidelines for committers <handling-pull-requests>`. :ref:`guidelines for committers <handling-pull-requests>`.
Summary Summary
------- =======
* Work on GitHub if you can. * Work on GitHub if you can.
* Announce your work on the Trac ticket by linking to your GitHub branch. * Announce your work on the Trac ticket by linking to your GitHub branch.

50
docs/internals/contributing/writing-documentation.txt
View File

@ -19,7 +19,7 @@ This section explains how writers can craft their documentation changes
in the most useful and least error-prone ways. in the most useful and least error-prone ways.
Getting the raw documentation Getting the raw documentation
----------------------------- =============================
Though Django's documentation is intended to be read as HTML at Though Django's documentation is intended to be read as HTML at
https://docs.djangoproject.com/, we edit it as a collection of text files for https://docs.djangoproject.com/, we edit it as a collection of text files for
@ -36,7 +36,7 @@ to have the docs for the last release be up-to-date and correct (see
:ref:`differences-between-doc-versions`). :ref:`differences-between-doc-versions`).
Getting started with Sphinx Getting started with Sphinx
--------------------------- ===========================
Django's documentation uses the Sphinx__ documentation system, which in turn Django's documentation uses the Sphinx__ documentation system, which in turn
is based on docutils__. The basic idea is that lightly-formatted plain-text is based on docutils__. The basic idea is that lightly-formatted plain-text
@ -66,7 +66,7 @@ Primer <sphinx:rst-primer>`. After that, you'll want to read about the
metadata, indexing, and cross-references. metadata, indexing, and cross-references.
How the documentation is organized How the documentation is organized
---------------------------------- ==================================
The documentation is organized into several categories: The documentation is organized into several categories:
@ -117,7 +117,7 @@ The documentation is organized into several categories:
repeat the same material. repeat the same material.
Writing style Writing style
------------- =============
When using pronouns in reference to a hypothetical person, such as "a user with When using pronouns in reference to a hypothetical person, such as "a user with
a session cookie", gender neutral pronouns (they/their/them) should be used. a session cookie", gender neutral pronouns (they/their/them) should be used.
@ -130,7 +130,7 @@ Instead of:
* himself or herself... use themselves. * himself or herself... use themselves.
Commonly used terms Commonly used terms
------------------- ===================
Here are some style guidelines on commonly used terms throughout the Here are some style guidelines on commonly used terms throughout the
documentation: documentation:
@ -160,7 +160,7 @@ documentation:
* **website** -- use one word, without capitalization. * **website** -- use one word, without capitalization.
Django-specific terminology Django-specific terminology
--------------------------- ===========================
* **model** -- it's not capitalized. * **model** -- it's not capitalized.
@ -172,7 +172,7 @@ Django-specific terminology
* **view** -- it's not capitalized. * **view** -- it's not capitalized.
Guidelines for reStructuredText files Guidelines for reStructuredText files
------------------------------------- =====================================
These guidelines regulate the format of our reST (reStructuredText) These guidelines regulate the format of our reST (reStructuredText)
documentation: documentation:
@ -199,8 +199,26 @@ documentation:
* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx' * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
documentation. documentation.
* Use these heading styles::
===
One
===
Two
===
Three
-----
Four
~~~~
Five
^^^^
Django-specific markup Django-specific markup
---------------------- ======================
Besides the `Sphinx built-in markup`__, Django's docs defines some extra Besides the `Sphinx built-in markup`__, Django's docs defines some extra
description units: description units:
@ -251,7 +269,7 @@ __ http://sphinx-doc.org/markup/
.. _documenting-new-features: .. _documenting-new-features:
Documenting new features Documenting new features
------------------------ ========================
Our policy for new features is: Our policy for new features is:
@ -309,7 +327,7 @@ We can simply remove the ``.. versionadded:: A.B`` annotation without any
indentation changes when the time comes. indentation changes when the time comes.
Minimizing images Minimizing images
----------------- =================
Optimize image compression where possible. For PNG files, use OptiPNG and Optimize image compression where possible. For PNG files, use OptiPNG and
AdvanceCOMP's ``advpng``: AdvanceCOMP's ``advpng``:
@ -324,7 +342,7 @@ This is based on OptiPNG version 0.7.5. Older versions may complain about the
``--strip all`` option being lossy. ``--strip all`` option being lossy.
An example An example
---------- ==========
For a quick example of how it all fits together, consider this hypothetical For a quick example of how it all fits together, consider this hypothetical
example: example:
@ -377,7 +395,7 @@ example:
.. setting:: ADMINS .. setting:: ADMINS
ADMINS ADMINS
------ ======
Default: ``[]`` (Empty list) Default: ``[]`` (Empty list)
@ -400,7 +418,7 @@ That's basically how everything fits together.
.. _improving-the-documentation: .. _improving-the-documentation:
Improving the documentation Improving the documentation
--------------------------- ===========================
A few small improvements can be made to make the documentation read and A few small improvements can be made to make the documentation read and
look better: look better:
@ -451,7 +469,7 @@ look better:
.. _documentation-spelling-check: .. _documentation-spelling-check:
Spelling check Spelling check
-------------- ==============
Before you commit your docs, it's a good idea to run the spelling checker. Before you commit your docs, it's a good idea to run the spelling checker.
You'll need to install a couple packages first: You'll need to install a couple packages first:
@ -475,7 +493,7 @@ one of the following:
to ``docs/spelling_wordlist`` (please keep the list in alphabetical order). to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
Translating documentation Translating documentation
------------------------- =========================
See :ref:`Localizing the Django documentation <translating-documentation>` if See :ref:`Localizing the Django documentation <translating-documentation>` if
you'd like to help translate the documentation into another language. you'd like to help translate the documentation into another language.
@ -483,7 +501,7 @@ you'd like to help translate the documentation into another language.
.. _django-admin-manpage: .. _django-admin-manpage:
``django-admin`` man page ``django-admin`` man page
------------------------- =========================
Sphinx can generate a manual page for the Sphinx can generate a manual page for the
:doc:`django-admin </ref/django-admin>` command. This is configured in :doc:`django-admin </ref/django-admin>` command. This is configured in

1
docs/internals/index.txt
View File

@ -1,3 +1,4 @@
================
Django internals Django internals
================ ================

12
docs/internals/mailing-lists.txt
View File

@ -16,7 +16,7 @@ anyone.
.. _django-users-mailing-list: .. _django-users-mailing-list:
``django-users`` ``django-users``
---------------- ================
This is the right place if you are looking to ask any question regarding the This is the right place if you are looking to ask any question regarding the
installation, usage, or debugging of Django. installation, usage, or debugging of Django.
@ -38,7 +38,7 @@ installation, usage, or debugging of Django.
.. _django-core-mentorship-mailing-list: .. _django-core-mentorship-mailing-list:
``django-core-mentorship`` ``django-core-mentorship``
-------------------------- ==========================
The Django Core Mentorship list is intended to provide a welcoming The Django Core Mentorship list is intended to provide a welcoming
introductory environment for community members interested in contributing to introductory environment for community members interested in contributing to
@ -55,7 +55,7 @@ the Django Project.
.. _django-developers-mailing-list: .. _django-developers-mailing-list:
``django-developers`` ``django-developers``
--------------------- =====================
The discussion about the development of Django itself takes place here. The discussion about the development of Django itself takes place here.
@ -76,7 +76,7 @@ The discussion about the development of Django itself takes place here.
.. _django-i18n-mailing-list: .. _django-i18n-mailing-list:
``django-i18n`` ``django-i18n``
--------------- ===============
This is the place to discuss the internationalization and localization of This is the place to discuss the internationalization and localization of
Django's components. Django's components.
@ -92,7 +92,7 @@ Django's components.
.. _django-announce-mailing-list: .. _django-announce-mailing-list:
``django-announce`` ``django-announce``
------------------- ===================
A (very) low-traffic list for announcing new releases of Django and important A (very) low-traffic list for announcing new releases of Django and important
bugfixes. bugfixes.
@ -108,7 +108,7 @@ bugfixes.
.. _django-updates-mailing-list: .. _django-updates-mailing-list:
``django-updates`` ``django-updates``
------------------ ==================
All the ticket updates are mailed automatically to this list, which is tracked All the ticket updates are mailed automatically to this list, which is tracked
by developers and interested community members. by developers and interested community members.

2
docs/internals/security.txt
View File

@ -1,5 +1,3 @@
.. _internals-security:
========================== ==========================
Django's security policies Django's security policies
========================== ==========================

1
docs/intro/index.txt
View File

@ -1,3 +1,4 @@
===============
Getting started Getting started
=============== ===============

13
docs/intro/install.txt
View File

@ -1,3 +1,4 @@
===================
Quick install guide Quick install guide
=================== ===================
@ -7,7 +8,7 @@ possibilities; this guide will guide you to a simple, minimal installation
that'll work while you walk through the introduction. that'll work while you walk through the introduction.
Install Python Install Python
-------------- ==============
Being a Python Web framework, Django requires Python. See Being a Python Web framework, Django requires Python. See
:ref:`faq-python-version-support` for details. Python includes a lightweight :ref:`faq-python-version-support` for details. Python includes a lightweight
@ -34,21 +35,21 @@ you should see something like::
>>> >>>
Set up a database Set up a database
----------------- =================
This step is only necessary if you'd like to work with a "large" database engine This step is only necessary if you'd like to work with a "large" database engine
like PostgreSQL, MySQL, or Oracle. To install such a database, consult the like PostgreSQL, MySQL, or Oracle. To install such a database, consult the
:ref:`database installation information <database-installation>`. :ref:`database installation information <database-installation>`.
Remove any old versions of Django Remove any old versions of Django
--------------------------------- =================================
If you are upgrading your installation of Django from a previous version, you If you are upgrading your installation of Django from a previous version, you
will need to :ref:`uninstall the old Django version before installing the new will need to :ref:`uninstall the old Django version before installing the new
version <removing-old-versions-of-django>`. version <removing-old-versions-of-django>`.
Install Django Install Django
-------------- ==============
You've got three easy options to install Django: You've got three easy options to install Django:
@ -77,7 +78,7 @@ You've got three easy options to install Django:
Verifying Verifying
--------- =========
To verify that Django can be seen by Python, type ``python`` from your shell. To verify that Django can be seen by Python, type ``python`` from your shell.
Then at the Python prompt, try to import Django: Then at the Python prompt, try to import Django:
@ -91,6 +92,6 @@ Then at the Python prompt, try to import Django:
You may have another version of Django installed. You may have another version of Django installed.
That's it! That's it!
---------- ==========
That's it -- you can now :doc:`move onto the tutorial </intro/tutorial01>`. That's it -- you can now :doc:`move onto the tutorial </intro/tutorial01>`.

1
docs/misc/index.txt
View File

@ -1,3 +1,4 @@
=================================
Meta-documentation and miscellany Meta-documentation and miscellany
================================= =================================

6
docs/ref/class-based-views/base.txt
View File

@ -14,7 +14,7 @@ ancestor classes are documented under the section title of **Ancestors (MRO)**.
MRO is an acronym for Method Resolution Order. MRO is an acronym for Method Resolution Order.
View View
---- ====
.. class:: django.views.generic.base.View .. class:: django.views.generic.base.View
@ -103,7 +103,7 @@ View
list of the allowed HTTP method names for the view. list of the allowed HTTP method names for the view.
TemplateView TemplateView
------------ ============
.. class:: django.views.generic.base.TemplateView .. class:: django.views.generic.base.TemplateView
@ -155,7 +155,7 @@ TemplateView
the keyword arguments captured from the URL pattern that served the view. the keyword arguments captured from the URL pattern that served the view.
RedirectView RedirectView
------------ ============
.. class:: django.views.generic.base.RedirectView .. class:: django.views.generic.base.RedirectView

42
docs/ref/class-based-views/flattened-index.txt
View File

@ -9,10 +9,10 @@ documentation organized by the class which defines the behavior, see
:doc:`Class-based views</ref/class-based-views/index>` :doc:`Class-based views</ref/class-based-views/index>`
Simple generic views Simple generic views
-------------------- ====================
View View
~~~~ ----
.. class:: View() .. class:: View()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -27,7 +27,7 @@ View
* :meth:`~django.views.generic.base.View.http_method_not_allowed` * :meth:`~django.views.generic.base.View.http_method_not_allowed`
TemplateView TemplateView
~~~~~~~~~~~~ ------------
.. class:: TemplateView() .. class:: TemplateView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -49,7 +49,7 @@ TemplateView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
RedirectView RedirectView
~~~~~~~~~~~~ ------------
.. class:: RedirectView() .. class:: RedirectView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -73,10 +73,10 @@ RedirectView
* ``put()`` * ``put()``
Detail Views Detail Views
------------ ============
DetailView DetailView
~~~~~~~~~~ ----------
.. class:: DetailView() .. class:: DetailView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -107,10 +107,10 @@ DetailView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
List Views List Views
---------- ==========
ListView ListView
~~~~~~~~ --------
.. class:: ListView() .. class:: ListView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -143,10 +143,10 @@ ListView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
Editing views Editing views
------------- =============
FormView FormView
~~~~~~~~ --------
.. class:: FormView() .. class:: FormView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -176,7 +176,7 @@ FormView
* :meth:`~django.views.generic.edit.ProcessFormView.put` * :meth:`~django.views.generic.edit.ProcessFormView.put`
CreateView CreateView
~~~~~~~~~~ ----------
.. class:: CreateView() .. class:: CreateView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -218,7 +218,7 @@ CreateView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
UpdateView UpdateView
~~~~~~~~~~ ----------
.. class:: UpdateView() .. class:: UpdateView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -260,7 +260,7 @@ UpdateView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
DeleteView DeleteView
~~~~~~~~~~ ----------
.. class:: DeleteView() .. class:: DeleteView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -294,10 +294,10 @@ DeleteView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
Date-based views Date-based views
---------------- ================
ArchiveIndexView ArchiveIndexView
~~~~~~~~~~~~~~~~ ----------------
.. class:: ArchiveIndexView() .. class:: ArchiveIndexView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -335,7 +335,7 @@ ArchiveIndexView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
YearArchiveView YearArchiveView
~~~~~~~~~~~~~~~ ---------------
.. class:: YearArchiveView() .. class:: YearArchiveView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -376,7 +376,7 @@ YearArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
MonthArchiveView MonthArchiveView
~~~~~~~~~~~~~~~~ ----------------
.. class:: MonthArchiveView() .. class:: MonthArchiveView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -420,7 +420,7 @@ MonthArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
WeekArchiveView WeekArchiveView
~~~~~~~~~~~~~~~ ---------------
.. class:: WeekArchiveView() .. class:: WeekArchiveView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -462,7 +462,7 @@ WeekArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
DayArchiveView DayArchiveView
~~~~~~~~~~~~~~ --------------
.. class:: DayArchiveView() .. class:: DayArchiveView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -510,7 +510,7 @@ DayArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
TodayArchiveView TodayArchiveView
~~~~~~~~~~~~~~~~ ----------------
.. class:: TodayArchiveView() .. class:: TodayArchiveView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):
@ -558,7 +558,7 @@ TodayArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` * :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
DateDetailView DateDetailView
~~~~~~~~~~~~~~ --------------
.. class:: DateDetailView() .. class:: DateDetailView()
**Attributes** (with optional accessor): **Attributes** (with optional accessor):

14
docs/ref/class-based-views/generic-date-based.txt
View File

@ -23,7 +23,7 @@ views for displaying drilldown pages for date-based data.
return reverse('article-detail', kwargs={'pk': self.pk}) return reverse('article-detail', kwargs={'pk': self.pk})
ArchiveIndexView ArchiveIndexView
---------------- ================
.. class:: ArchiveIndexView .. class:: ArchiveIndexView
@ -87,7 +87,7 @@ ArchiveIndexView
This will output all articles. This will output all articles.
YearArchiveView YearArchiveView
--------------- ===============
.. class:: YearArchiveView .. class:: YearArchiveView
@ -192,7 +192,7 @@ YearArchiveView
</div> </div>
MonthArchiveView MonthArchiveView
---------------- ================
.. class:: MonthArchiveView .. class:: MonthArchiveView
@ -289,7 +289,7 @@ MonthArchiveView
</p> </p>
WeekArchiveView WeekArchiveView
--------------- ===============
.. class:: WeekArchiveView .. class:: WeekArchiveView
@ -392,7 +392,7 @@ WeekArchiveView
filter ``'%U'`` outputs the number of seconds since the Unix epoch. filter ``'%U'`` outputs the number of seconds since the Unix epoch.
DayArchiveView DayArchiveView
-------------- ==============
.. class:: DayArchiveView .. class:: DayArchiveView
@ -494,7 +494,7 @@ DayArchiveView
</p> </p>
TodayArchiveView TodayArchiveView
---------------- ================
.. class:: TodayArchiveView .. class:: TodayArchiveView
@ -551,7 +551,7 @@ TodayArchiveView
name of the new template. name of the new template.
DateDetailView DateDetailView
-------------- ==============
.. class:: DateDetailView .. class:: DateDetailView

4
docs/ref/class-based-views/generic-display.txt
View File

@ -6,7 +6,7 @@ The two following generic class-based views are designed to display data. On
many projects they are typically the most commonly used views. many projects they are typically the most commonly used views.
DetailView DetailView
---------- ==========
.. class:: django.views.generic.detail.DetailView .. class:: django.views.generic.detail.DetailView
@ -73,7 +73,7 @@ DetailView
<p>Date: {{ now|date }}</p> <p>Date: {{ now|date }}</p>
ListView ListView
-------- ========
.. class:: django.views.generic.list.ListView .. class:: django.views.generic.list.ListView

8
docs/ref/class-based-views/generic-editing.txt
View File

@ -25,7 +25,7 @@ editing content:
return reverse('author-detail', kwargs={'pk': self.pk}) return reverse('author-detail', kwargs={'pk': self.pk})
FormView FormView
-------- ========
.. class:: django.views.generic.edit.FormView .. class:: django.views.generic.edit.FormView
@ -81,7 +81,7 @@ FormView
CreateView CreateView
---------- ==========
.. class:: django.views.generic.edit.CreateView .. class:: django.views.generic.edit.CreateView
@ -136,7 +136,7 @@ CreateView
</form> </form>
UpdateView UpdateView
---------- ==========
.. class:: django.views.generic.edit.UpdateView .. class:: django.views.generic.edit.UpdateView
@ -193,7 +193,7 @@ UpdateView
</form> </form>
DeleteView DeleteView
---------- ==========
.. class:: django.views.generic.edit.DeleteView .. class:: django.views.generic.edit.DeleteView

4
docs/ref/class-based-views/index.txt
View File

@ -16,7 +16,7 @@ Class-based views API reference. For introductory material, see the
flattened-index flattened-index
Specification Specification
------------- =============
Each request served by a class-based view has an independent state; therefore, Each request served by a class-based view has an independent state; therefore,
it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
@ -44,7 +44,7 @@ previous example, this means that every request on ``MyView`` is able to use
the class (return ``True`` on a ``hasattr`` check). the class (return ``True`` on a ``hasattr`` check).
Base vs Generic views Base vs Generic views
--------------------- =====================
Base class-based views can be thought of as *parent* views, which can be Base class-based views can be thought of as *parent* views, which can be
used by themselves or inherited from. They may not provide all the used by themselves or inherited from. They may not provide all the

12
docs/ref/class-based-views/mixins-date-based.txt
View File

@ -11,7 +11,7 @@ Date-based mixins
characters from the :ttag:`now` template tag as they are not compatible. characters from the :ttag:`now` template tag as they are not compatible.
YearMixin YearMixin
--------- =========
.. class:: YearMixin .. class:: YearMixin
@ -63,7 +63,7 @@ YearMixin
:attr:`~DateMixin.allow_future`. :attr:`~DateMixin.allow_future`.
MonthMixin MonthMixin
---------- ==========
.. class:: MonthMixin .. class:: MonthMixin
@ -115,7 +115,7 @@ MonthMixin
:attr:`~DateMixin.allow_future`. :attr:`~DateMixin.allow_future`.
DayMixin DayMixin
-------- ========
.. class:: DayMixin .. class:: DayMixin
@ -167,7 +167,7 @@ DayMixin
:attr:`~DateMixin.allow_future`. :attr:`~DateMixin.allow_future`.
WeekMixin WeekMixin
--------- =========
.. class:: WeekMixin .. class:: WeekMixin
@ -220,7 +220,7 @@ WeekMixin
:attr:`~DateMixin.allow_future`. :attr:`~DateMixin.allow_future`.
DateMixin DateMixin
--------- =========
.. class:: DateMixin .. class:: DateMixin
@ -266,7 +266,7 @@ DateMixin
:attr:`~DateMixin.allow_future` by default. :attr:`~DateMixin.allow_future` by default.
BaseDateListView BaseDateListView
---------------- ================
.. class:: BaseDateListView .. class:: BaseDateListView

8
docs/ref/class-based-views/mixins-editing.txt
View File

@ -15,7 +15,7 @@ The following mixins are used to construct Django's editing views:
the documentation on :doc:`/ref/class-based-views/generic-editing`. the documentation on :doc:`/ref/class-based-views/generic-editing`.
FormMixin FormMixin
--------- =========
.. class:: django.views.generic.edit.FormMixin .. class:: django.views.generic.edit.FormMixin
@ -95,7 +95,7 @@ FormMixin
name 'form'. name 'form'.
ModelFormMixin ModelFormMixin
-------------- ==============
.. class:: django.views.generic.edit.ModelFormMixin .. class:: django.views.generic.edit.ModelFormMixin
@ -181,7 +181,7 @@ ModelFormMixin
ProcessFormView ProcessFormView
--------------- ===============
.. class:: django.views.generic.edit.ProcessFormView .. class:: django.views.generic.edit.ProcessFormView
@ -221,7 +221,7 @@ ProcessFormView
DeletionMixin DeletionMixin
------------- =============
.. class:: django.views.generic.edit.DeletionMixin .. class:: django.views.generic.edit.DeletionMixin

4
docs/ref/class-based-views/mixins-multiple-object.txt
View File

@ -3,7 +3,7 @@ Multiple object mixins
====================== ======================
MultipleObjectMixin MultipleObjectMixin
------------------- ===================
.. class:: django.views.generic.list.MultipleObjectMixin .. class:: django.views.generic.list.MultipleObjectMixin
@ -193,7 +193,7 @@ MultipleObjectMixin
MultipleObjectTemplateResponseMixin MultipleObjectTemplateResponseMixin
----------------------------------- ===================================
.. class:: django.views.generic.list.MultipleObjectTemplateResponseMixin .. class:: django.views.generic.list.MultipleObjectTemplateResponseMixin

4
docs/ref/class-based-views/mixins-simple.txt
View File

@ -3,7 +3,7 @@ Simple mixins
============= =============
ContextMixin ContextMixin
------------ ============
.. class:: django.views.generic.base.ContextMixin .. class:: django.views.generic.base.ContextMixin
@ -32,7 +32,7 @@ ContextMixin
<alters-data-description>`. <alters-data-description>`.
TemplateResponseMixin TemplateResponseMixin
--------------------- =====================
.. class:: django.views.generic.base.TemplateResponseMixin .. class:: django.views.generic.base.TemplateResponseMixin

4
docs/ref/class-based-views/mixins-single-object.txt
View File

@ -3,7 +3,7 @@ Single object mixins
==================== ====================
SingleObjectMixin SingleObjectMixin
----------------- =================
.. class:: django.views.generic.detail.SingleObjectMixin .. class:: django.views.generic.detail.SingleObjectMixin
@ -132,7 +132,7 @@ SingleObjectMixin
SingleObjectTemplateResponseMixin SingleObjectTemplateResponseMixin
--------------------------------- =================================
.. class:: django.views.generic.detail.SingleObjectTemplateResponseMixin .. class:: django.views.generic.detail.SingleObjectTemplateResponseMixin

8
docs/ref/clickjacking.txt
View File

@ -52,7 +52,7 @@ How to use it
============= =============
Setting X-Frame-Options for all responses Setting X-Frame-Options for all responses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------
To set the same ``X-Frame-Options`` value for all responses in your site, put To set the same ``X-Frame-Options`` value for all responses in your site, put
``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to ``'django.middleware.clickjacking.XFrameOptionsMiddleware'`` to
@ -86,7 +86,7 @@ that tells the middleware not to set the header::
Setting X-Frame-Options per view Setting X-Frame-Options per view
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
To set the ``X-Frame-Options`` header on a per view basis, Django provides these To set the ``X-Frame-Options`` header on a per view basis, Django provides these
decorators:: decorators::
@ -114,7 +114,7 @@ modern browser. Older browsers will quietly ignore the header and need `other
clickjacking prevention techniques`_. clickjacking prevention techniques`_.
Browsers that support X-Frame-Options Browsers that support X-Frame-Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------
* Internet Explorer 8+ * Internet Explorer 8+
* Firefox 3.6.9+ * Firefox 3.6.9+
@ -123,7 +123,7 @@ Browsers that support X-Frame-Options
* Chrome 4.1+ * Chrome 4.1+
See also See also
~~~~~~~~ --------
A `complete list`_ of browsers supporting ``X-Frame-Options``. A `complete list`_ of browsers supporting ``X-Frame-Options``.

1
docs/ref/contrib/auth.txt
View File

@ -1,3 +1,4 @@
=======================
``django.contrib.auth`` ``django.contrib.auth``
======================= =======================

24
docs/ref/contrib/gis/forms-api.txt
View File

@ -18,7 +18,7 @@ In addition to the regular :ref:`form field arguments <core-field-arguments>`,
GeoDjango form fields take the following optional arguments. GeoDjango form fields take the following optional arguments.
``srid`` ``srid``
~~~~~~~~ --------
.. attribute:: Field.srid .. attribute:: Field.srid
@ -28,7 +28,7 @@ GeoDjango form fields take the following optional arguments.
input values into that SRID. input values into that SRID.
``geom_type`` ``geom_type``
~~~~~~~~~~~~~ -------------
.. attribute:: Field.geom_type .. attribute:: Field.geom_type
@ -40,42 +40,42 @@ Form field classes
================== ==================
``GeometryField`` ``GeometryField``
~~~~~~~~~~~~~~~~~ -----------------
.. class:: GeometryField .. class:: GeometryField
``PointField`` ``PointField``
~~~~~~~~~~~~~~ --------------
.. class:: PointField .. class:: PointField
``LineStringField`` ``LineStringField``
~~~~~~~~~~~~~~~~~~~ -------------------
.. class:: LineStringField .. class:: LineStringField
``PolygonField`` ``PolygonField``
~~~~~~~~~~~~~~~~ ----------------
.. class:: PolygonField .. class:: PolygonField
``MultiPointField`` ``MultiPointField``
~~~~~~~~~~~~~~~~~~~ -------------------
.. class:: MultiPointField .. class:: MultiPointField
``MultiLineStringField`` ``MultiLineStringField``
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
.. class:: MultiLineStringField .. class:: MultiLineStringField
``MultiPolygonField`` ``MultiPolygonField``
~~~~~~~~~~~~~~~~~~~~~ ---------------------
.. class:: MultiPolygonField .. class:: MultiPolygonField
``GeometryCollectionField`` ``GeometryCollectionField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
.. class:: GeometryCollectionField .. class:: GeometryCollectionField
@ -91,7 +91,7 @@ Note that none of the currently available widgets supports 3D geometries, hence
geometry fields will fallback using a simple ``Textarea`` widget for such data. geometry fields will fallback using a simple ``Textarea`` widget for such data.
Widget attributes Widget attributes
~~~~~~~~~~~~~~~~~ -----------------
GeoDjango widgets are template-based, so their attributes are mostly different GeoDjango widgets are template-based, so their attributes are mostly different
from other Django widget attributes. from other Django widget attributes.
@ -134,7 +134,7 @@ widget. For example::
forms.OSMWidget(attrs={'map_width': 800, 'map_height': 500})) forms.OSMWidget(attrs={'map_width': 800, 'map_height': 500}))
Widget classes Widget classes
~~~~~~~~~~~~~~ --------------
``BaseGeometryWidget`` ``BaseGeometryWidget``

52
docs/ref/contrib/gis/functions.txt
View File

@ -36,7 +36,7 @@ Measurement Relationships Operations Editors
================== ======================= ====================== =================== ================== ===================== ================== ======================= ====================== =================== ================== =====================
Area Area
---- ====
.. class:: Area(expression, **extra) .. class:: Area(expression, **extra)
@ -48,7 +48,7 @@ float value is returned, as it's not possible to automatically determine the
unit of the field. unit of the field.
AsGeoJSON AsGeoJSON
--------- =========
.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra) .. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
@ -80,7 +80,7 @@ Keyword Argument Description
===================== ===================================================== ===================== =====================================================
AsGML AsGML
----- =====
.. class:: AsGML(expression, version=2, precision=8, **extra) .. class:: AsGML(expression, version=2, precision=8, **extra)
@ -111,7 +111,7 @@ Keyword Argument Description
__ https://en.wikipedia.org/wiki/Geography_Markup_Language __ https://en.wikipedia.org/wiki/Geography_Markup_Language
AsKML AsKML
----- =====
.. class:: AsKML(expression, precision=8, **extra) .. class:: AsKML(expression, precision=8, **extra)
@ -138,7 +138,7 @@ Keyword Argument Description
__ https://developers.google.com/kml/documentation/ __ https://developers.google.com/kml/documentation/
AsSVG AsSVG
----- =====
.. class:: AsSVG(expression, relative=False, precision=8, **extra) .. class:: AsSVG(expression, relative=False, precision=8, **extra)
@ -162,7 +162,7 @@ Keyword Argument Description
__ http://www.w3.org/Graphics/SVG/ __ http://www.w3.org/Graphics/SVG/
BoundingCircle BoundingCircle
-------------- ==============
.. class:: BoundingCircle(expression, num_seg=48, **extra) .. class:: BoundingCircle(expression, num_seg=48, **extra)
@ -172,7 +172,7 @@ Accepts a single geographic field or expression and returns the smallest circle
polygon that can fully contain the geometry. polygon that can fully contain the geometry.
Centroid Centroid
-------- ========
.. class:: Centroid(expression, **extra) .. class:: Centroid(expression, **extra)
@ -182,7 +182,7 @@ Accepts a single geographic field or expression and returns the ``centroid``
value of the geometry. value of the geometry.
Difference Difference
---------- ==========
.. class:: Difference(expr1, expr2, **extra) .. class:: Difference(expr1, expr2, **extra)
@ -197,7 +197,7 @@ geometry B.
MySQL support was added. MySQL support was added.
Distance Distance
-------- ========
.. class:: Distance(expr1, expr2, spheroid=None, **extra) .. class:: Distance(expr1, expr2, spheroid=None, **extra)
@ -241,7 +241,7 @@ queryset is calculated::
:ref:`supported_units`. :ref:`supported_units`.
Envelope Envelope
-------- ========
.. class:: Envelope(expression, **extra) .. class:: Envelope(expression, **extra)
@ -251,7 +251,7 @@ Accepts a single geographic field or expression and returns the geometry
representing the bounding box of the geometry. representing the bounding box of the geometry.
ForceRHR ForceRHR
-------- ========
.. class:: ForceRHR(expression, **extra) .. class:: ForceRHR(expression, **extra)
@ -262,7 +262,7 @@ of the polygon/multipolygon in which all of the vertices follow the
right-hand rule. right-hand rule.
GeoHash GeoHash
------- =======
.. class:: GeoHash(expression, **extra) .. class:: GeoHash(expression, **extra)
@ -278,7 +278,7 @@ representation of the geometry.
__ https://en.wikipedia.org/wiki/Geohash __ https://en.wikipedia.org/wiki/Geohash
Intersection Intersection
------------ ============
.. class:: Intersection(expr1, expr2, **extra) .. class:: Intersection(expr1, expr2, **extra)
@ -292,7 +292,7 @@ intersection between them.
MySQL support was added. MySQL support was added.
Length Length
------ ======
.. class:: Length(expression, spheroid=True, **extra) .. class:: Length(expression, spheroid=True, **extra)
@ -309,7 +309,7 @@ accurate, less resource-intensive) or on a spheroid (more accurate, more
resource-intensive) with the ``spheroid`` keyword argument. resource-intensive) with the ``spheroid`` keyword argument.
MemSize MemSize
------- =======
.. class:: MemSize(expression, **extra) .. class:: MemSize(expression, **extra)
@ -319,7 +319,7 @@ Accepts a single geographic field or expression and returns the memory size
(number of bytes) that the geometry field takes. (number of bytes) that the geometry field takes.
NumGeometries NumGeometries
------------- =============
.. class:: NumGeometries(expression, **extra) .. class:: NumGeometries(expression, **extra)
@ -330,7 +330,7 @@ geometries if the geometry field is a collection (e.g., a ``GEOMETRYCOLLECTION``
or ``MULTI*`` field); otherwise returns ``None``. or ``MULTI*`` field); otherwise returns ``None``.
NumPoints NumPoints
--------- =========
.. class:: NumPoints(expression, **extra) .. class:: NumPoints(expression, **extra)
@ -340,7 +340,7 @@ Accepts a single geographic field or expression and returns the number of points
in the first linestring in the geometry field; otherwise returns ``None``. in the first linestring in the geometry field; otherwise returns ``None``.
Perimeter Perimeter
--------- =========
.. class:: Perimeter(expression, **extra) .. class:: Perimeter(expression, **extra)
@ -352,7 +352,7 @@ MySQL, a raw float value is returned, as it's not possible to automatically
determine the unit of the field. determine the unit of the field.
PointOnSurface PointOnSurface
-------------- ==============
.. class:: PointOnSurface(expression, **extra) .. class:: PointOnSurface(expression, **extra)
@ -362,7 +362,7 @@ Accepts a single geographic field or expression and returns a ``Point`` geometry
guaranteed to lie on the surface of the field; otherwise returns ``None``. guaranteed to lie on the surface of the field; otherwise returns ``None``.
Reverse Reverse
------- =======
.. class:: Reverse(expression, **extra) .. class:: Reverse(expression, **extra)
@ -372,7 +372,7 @@ Accepts a single geographic field or expression and returns a geometry with
reversed coordinates. reversed coordinates.
Scale Scale
----- =====
.. class:: Scale(expression, x, y, z=0.0, **extra) .. class:: Scale(expression, x, y, z=0.0, **extra)
@ -383,7 +383,7 @@ scaled coordinates by multiplying them with the ``x``, ``y``, and optionally
``z`` parameters. ``z`` parameters.
SnapToGrid SnapToGrid
---------- ==========
.. class:: SnapToGrid(expression, *args, **extra) .. class:: SnapToGrid(expression, *args, **extra)
@ -403,7 +403,7 @@ Number of Arguments Description
=================== ===================================================== =================== =====================================================
SymDifference SymDifference
------------- =============
.. class:: SymDifference(expr1, expr2, **extra) .. class:: SymDifference(expr1, expr2, **extra)
@ -418,7 +418,7 @@ parameters.
MySQL support was added. MySQL support was added.
Transform Transform
--------- =========
.. class:: Transform(expression, srid, **extra) .. class:: Transform(expression, srid, **extra)
@ -435,7 +435,7 @@ the transformed geometry to the spatial reference system specified by the
are not necessarily the same as those used by PostGIS. are not necessarily the same as those used by PostGIS.
Translate Translate
--------- =========
.. class:: Translate(expression, x, y, z=0.0, **extra) .. class:: Translate(expression, x, y, z=0.0, **extra)
@ -446,7 +446,7 @@ its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric
parameters. parameters.
Union Union
----- =====
.. class:: Union(expr1, expr2, **extra) .. class:: Union(expr1, expr2, **extra)

12
docs/ref/contrib/gis/install/geolibs.txt
View File

@ -120,10 +120,10 @@ script, compile, and install::
$ cd .. $ cd ..
Troubleshooting Troubleshooting
^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~
Can't find GEOS library Can't find GEOS library
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^
When GeoDjango can't find GEOS, this error is raised: When GeoDjango can't find GEOS, this error is raised:
@ -139,7 +139,7 @@ If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binut
.. _geoslibrarypath: .. _geoslibrarypath:
``GEOS_LIBRARY_PATH`` ``GEOS_LIBRARY_PATH``
~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^
If your GEOS library is in a non-standard location, or you don't want to If your GEOS library is in a non-standard location, or you don't want to
modify the system's library path then the :setting:`GEOS_LIBRARY_PATH` modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`
@ -222,10 +222,10 @@ __ https://trac.osgeo.org/gdal/wiki/GdalOgrInPython
.. _gdaltrouble: .. _gdaltrouble:
Troubleshooting Troubleshooting
^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~
Can't find GDAL library Can't find GDAL library
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^
When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
will be false: will be false:
@ -242,7 +242,7 @@ The solution is to properly configure your :ref:`libsettings` *or* set
.. _gdallibrarypath: .. _gdallibrarypath:
``GDAL_LIBRARY_PATH`` ``GDAL_LIBRARY_PATH``
~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^
If your GDAL library is in a non-standard location, or you don't want to If your GDAL library is in a non-standard location, or you don't want to
modify the system's library path then the :setting:`GDAL_LIBRARY_PATH` modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`

32
docs/ref/contrib/gis/install/index.txt
View File

@ -129,7 +129,7 @@ an environment variable, or by configuring the library path for the entire
system. system.
``LD_LIBRARY_PATH`` environment variable ``LD_LIBRARY_PATH`` environment variable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A user may set this environment variable to customize the library paths A user may set this environment variable to customize the library paths
they want to use. The typical library directory for software they want to use. The typical library directory for software
@ -140,7 +140,7 @@ could place the following in their bash profile::
export LD_LIBRARY_PATH=/usr/local/lib export LD_LIBRARY_PATH=/usr/local/lib
Setting system library path Setting system library path
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include On GNU/Linux systems, there is typically a file in ``/etc/ld.so.conf``, which may include
additional paths from files in another directory, such as ``/etc/ld.so.conf.d``. additional paths from files in another directory, such as ``/etc/ld.so.conf.d``.
@ -160,7 +160,7 @@ modifying the system library path::
.. _binutils: .. _binutils:
Install ``binutils`` Install ``binutils``
^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~
GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
module) to discover libraries. The ``find_library`` routine uses a program module) to discover libraries. The ``find_library`` routine uses a program
@ -203,7 +203,7 @@ Foundation, however, this is not required.
.. _macosx_python: .. _macosx_python:
Python Python
^^^^^^ ~~~~~~
Although OS X comes with Python installed, users can use `framework Although OS X comes with Python installed, users can use `framework
installers`__ provided by the Python Software Foundation. An advantage to installers`__ provided by the Python Software Foundation. An advantage to
@ -223,7 +223,7 @@ __ https://www.python.org/ftp/python/
.. _postgresapp: .. _postgresapp:
Postgres.app Postgres.app
^^^^^^^^^^^^ ~~~~~~~~~~~~
`Postgres.app <http://postgresapp.com/>`_ is a standalone PostgreSQL server `Postgres.app <http://postgresapp.com/>`_ is a standalone PostgreSQL server
that includes the PostGIS extension. You will also need to install ``gdal`` and that includes the PostGIS extension. You will also need to install ``gdal`` and
@ -243,7 +243,7 @@ terminal prompt.
.. _homebrew: .. _homebrew:
Homebrew Homebrew
^^^^^^^^ ~~~~~~~~
`Homebrew`__ provides "recipes" for building binaries and packages from source. `Homebrew`__ provides "recipes" for building binaries and packages from source.
It provides recipes for the GeoDjango prerequisites on Macintosh computers It provides recipes for the GeoDjango prerequisites on Macintosh computers
@ -263,7 +263,7 @@ __ http://brew.sh/
.. _kyngchaos: .. _kyngchaos:
KyngChaos packages KyngChaos packages
^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~
William Kyngesburye provides a number of `geospatial library binary packages`__ William Kyngesburye provides a number of `geospatial library binary packages`__
that make it simple to get GeoDjango installed on OS X without compiling that make it simple to get GeoDjango installed on OS X without compiling
@ -306,7 +306,7 @@ __ http://www.kyngchaos.com/software/postgres
.. _psycopg2_kyngchaos: .. _psycopg2_kyngchaos:
psycopg2 psycopg2
~~~~~~~~ ^^^^^^^^
After you've installed the KyngChaos binaries and modified your ``PATH``, as After you've installed the KyngChaos binaries and modified your ``PATH``, as
described above, ``psycopg2`` may be installed using the following command:: described above, ``psycopg2`` may be installed using the following command::
@ -334,7 +334,7 @@ __ http://pdb.finkproject.org/pdb/browse.php?summary=django-gis
.. _macports: .. _macports:
MacPorts MacPorts
^^^^^^^^ ~~~~~~~~
`MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh `MacPorts`__ may be used to install GeoDjango prerequisites on Macintosh
computers running OS X. Because MacPorts still builds the software from source, computers running OS X. Because MacPorts still builds the software from source,
@ -379,7 +379,7 @@ GeoDjango on Windows.
GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer. GEOS and GDAL, are not yet provided by the :ref:`OSGeo4W` installer.
Python Python
^^^^^^ ~~~~~~
First, download the latest `Python 2.7 installer`__ from the Python website. First, download the latest `Python 2.7 installer`__ from the Python website.
Next, run the installer and keep the defaults -- for example, keep Next, run the installer and keep the defaults -- for example, keep
@ -395,7 +395,7 @@ Next, run the installer and keep the defaults -- for example, keep
__ https://python.org/download/ __ https://python.org/download/
PostgreSQL PostgreSQL
^^^^^^^^^^ ~~~~~~~~~~
First, download the latest `PostgreSQL 9.x installer`__ from the First, download the latest `PostgreSQL 9.x installer`__ from the
`EnterpriseDB`__ website. After downloading, simply run the installer, `EnterpriseDB`__ website. After downloading, simply run the installer,
@ -427,7 +427,7 @@ __ http://www.enterprisedb.com
.. _postgisasb: .. _postgisasb:
PostGIS PostGIS
^^^^^^^ ~~~~~~~
From within the Application Stack Builder (to run outside of the installer, From within the Application Stack Builder (to run outside of the installer,
:menuselection:`Start --> Programs --> PostgreSQL 9.x`), select :menuselection:`Start --> Programs --> PostgreSQL 9.x`), select
@ -446,7 +446,7 @@ default PostGIS database).
password in the 'Database Connection Information' dialog. password in the 'Database Connection Information' dialog.
psycopg2 psycopg2
^^^^^^^^ ~~~~~~~~
The ``psycopg2`` Python module provides the interface between Python and the The ``psycopg2`` Python module provides the interface between Python and the
PostgreSQL database. Download the latest `Windows installer`__ for your version PostgreSQL database. Download the latest `Windows installer`__ for your version
@ -457,7 +457,7 @@ __ http://www.stickpeople.com/projects/python/win-psycopg/
.. _osgeo4w: .. _osgeo4w:
OSGeo4W OSGeo4W
^^^^^^^ ~~~~~~~
The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS
libraries required by GeoDjango. First, download the `OSGeo4W installer`_, libraries required by GeoDjango. First, download the `OSGeo4W installer`_,
@ -471,7 +471,7 @@ installer.
.. _OSGeo4W installer: https://trac.osgeo.org/osgeo4w/ .. _OSGeo4W installer: https://trac.osgeo.org/osgeo4w/
Modify Windows environment Modify Windows environment
^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to use GeoDjango, you will need to add your Python and OSGeo4W In order to use GeoDjango, you will need to add your Python and OSGeo4W
directories to your Windows system ``Path``, as well as create ``GDAL_DATA`` directories to your Windows system ``Path``, as well as create ``GDAL_DATA``
@ -506,7 +506,7 @@ script, :download:`geodjango_setup.bat`.
variables accordingly. variables accordingly.
Install Django and set up database Install Django and set up database
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Finally, :ref:`install Django <installing-official-release>` on your system. Finally, :ref:`install Django <installing-official-release>` on your system.

14
docs/ref/contrib/gis/install/spatialite.txt
View File

@ -20,13 +20,13 @@ __ http://www.gaia-gis.it/gaia-sins/
.. _spatialite_source: .. _spatialite_source:
Installing from source Installing from source
~~~~~~~~~~~~~~~~~~~~~~ ======================
:doc:`GEOS and PROJ.4</ref/contrib/gis/install/geolibs>` should be installed :doc:`GEOS and PROJ.4</ref/contrib/gis/install/geolibs>` should be installed
prior to building SpatiaLite. prior to building SpatiaLite.
SQLite SQLite
^^^^^^ ------
Check first if SQLite is compiled with the `R*Tree module`__. Run the sqlite3 Check first if SQLite is compiled with the `R*Tree module`__. Run the sqlite3
command line interface and enter the following query:: command line interface and enter the following query::
@ -57,7 +57,7 @@ __ https://www.sqlite.org/download.html
.. _spatialitebuild: .. _spatialitebuild:
SpatiaLite library (``libspatialite``) SpatiaLite library (``libspatialite``)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ --------------------------------------
Get the latest SpatiaLite library source bundle from the Get the latest SpatiaLite library source bundle from the
`download page`__:: `download page`__::
@ -81,13 +81,13 @@ __ http://www.gaia-gis.it/gaia-sins/libspatialite-sources/
.. _spatialite_macosx: .. _spatialite_macosx:
Mac OS X-specific instructions Mac OS X-specific instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ==============================
To install the SpatiaLite library and tools, Mac OS X users can choose between To install the SpatiaLite library and tools, Mac OS X users can choose between
:ref:`kyngchaos` and `Homebrew`_. :ref:`kyngchaos` and `Homebrew`_.
KyngChaos KyngChaos
^^^^^^^^^ ---------
First, follow the instructions in the :ref:`kyngchaos` section. First, follow the instructions in the :ref:`kyngchaos` section.
@ -109,7 +109,7 @@ add the following to your ``settings.py``::
__ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html __ http://www.gaia-gis.it/spatialite-2.3.1/binaries.html
Homebrew Homebrew
^^^^^^^^ --------
`Homebrew`_ handles all the SpatiaLite related packages on your behalf, `Homebrew`_ handles all the SpatiaLite related packages on your behalf,
including SQLite3, SpatiaLite, PROJ, and GEOS. Install them like this:: including SQLite3, SpatiaLite, PROJ, and GEOS. Install them like this::
@ -128,7 +128,7 @@ following to your ``settings.py``::
.. _create_spatialite_db: .. _create_spatialite_db:
Creating a spatial database for SpatiaLite Creating a spatial database for SpatiaLite
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ==========================================
When running ``manage.py migrate`` with a SQLite or SpatiaLite database, the When running ``manage.py migrate`` with a SQLite or SpatiaLite database, the
database file will be automatically created if it doesn't exist. Django will database file will be automatically created if it doesn't exist. Django will

4
docs/ref/contrib/gis/model-api.txt
View File

@ -104,7 +104,7 @@ __ https://en.wikipedia.org/wiki/WGS84
.. _selecting-an-srid: .. _selecting-an-srid:
Selecting an SRID Selecting an SRID
^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~
Choosing an appropriate SRID for your model is an important decision that the Choosing an appropriate SRID for your model is an important decision that the
developer should consider carefully. The SRID is an integer specifier that developer should consider carefully. The SRID is an integer specifier that
@ -213,7 +213,7 @@ details.
.. _geography-type: .. _geography-type:
Geography Type Geography Type
^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~
The geography type provides native support for spatial features represented The geography type provides native support for spatial features represented
with geographic coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_ with geographic coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_

6
docs/ref/contrib/gis/testing.txt
View File

@ -20,7 +20,7 @@ Settings
.. setting:: POSTGIS_VERSION .. setting:: POSTGIS_VERSION
``POSTGIS_VERSION`` ``POSTGIS_VERSION``
^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~
When GeoDjango's spatial backend initializes on PostGIS, it has to perform When GeoDjango's spatial backend initializes on PostGIS, it has to perform
an SQL query to determine the version in order to figure out what an SQL query to determine the version in order to figure out what
@ -43,7 +43,7 @@ only needs to have the ability to create databases. In other configurations,
you may be required to use a database superuser. you may be required to use a database superuser.
Create database user Create database user
^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~
To make a database user with the ability to create databases, use the To make a database user with the ability to create databases, use the
following command:: following command::
@ -59,7 +59,7 @@ Alternatively, you may alter an existing user's role from the SQL shell
postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE; postgres# ALTER ROLE <user_name> CREATEDB NOSUPERUSER NOCREATEROLE;
Create database superuser Create database superuser
^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~
This may be done at the time the user is created, for example:: This may be done at the time the user is created, for example::

4
docs/ref/contrib/gis/tutorial.txt
View File

@ -695,7 +695,7 @@ GeoDjango extends :doc:`Django's admin application </ref/contrib/admin/index>`
with support for editing geometry fields. with support for editing geometry fields.
Basics Basics
^^^^^^ ~~~~~~
GeoDjango also supplements the Django admin by allowing users to create GeoDjango also supplements the Django admin by allowing users to create
and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_). and modify geometries on a JavaScript slippy map (powered by `OpenLayers`_).
@ -742,7 +742,7 @@ position.
.. _osmgeoadmin-intro: .. _osmgeoadmin-intro:
``OSMGeoAdmin`` ``OSMGeoAdmin``
^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~
With the :class:`~django.contrib.gis.admin.OSMGeoAdmin`, GeoDjango uses With the :class:`~django.contrib.gis.admin.OSMGeoAdmin`, GeoDjango uses
a `Open Street Map`_ layer in the admin. a `Open Street Map`_ layer in the admin.

16
docs/ref/contrib/humanize.txt
View File

@ -16,7 +16,7 @@ filters.
.. templatefilter:: apnumber .. templatefilter:: apnumber
apnumber apnumber
-------- ========
For numbers 1-9, returns the number spelled out. Otherwise, returns the For numbers 1-9, returns the number spelled out. Otherwise, returns the
number. This follows Associated Press style. number. This follows Associated Press style.
@ -32,7 +32,7 @@ You can pass in either an integer or a string representation of an integer.
.. templatefilter:: intcomma .. templatefilter:: intcomma
intcomma intcomma
-------- ========
Converts an integer to a string containing commas every three digits. Converts an integer to a string containing commas every three digits.
@ -43,7 +43,7 @@ Examples:
* ``450000`` becomes ``450,000``. * ``450000`` becomes ``450,000``.
* ``4500000`` becomes ``4,500,000``. * ``4500000`` becomes ``4,500,000``.
:ref:`Format localization <format-localization>` will be respected if enabled, :doc:`/topics/i18n/formatting` will be respected if enabled,
e.g. with the ``'de'`` language: e.g. with the ``'de'`` language:
* ``45000`` becomes ``'45.000'``. * ``45000`` becomes ``'45.000'``.
@ -54,7 +54,7 @@ You can pass in either an integer or a string representation of an integer.
.. templatefilter:: intword .. templatefilter:: intword
intword intword
------- =======
Converts a large integer to a friendly text representation. Works best for Converts a large integer to a friendly text representation. Works best for
numbers over 1 million. numbers over 1 million.
@ -67,7 +67,7 @@ Examples:
Values up to 10^100 (Googol) are supported. Values up to 10^100 (Googol) are supported.
:ref:`Format localization <format-localization>` will be respected if enabled, :doc:`/topics/i18n/formatting` will be respected if enabled,
e.g. with the ``'de'`` language: e.g. with the ``'de'`` language:
* ``1000000`` becomes ``'1,0 Million'``. * ``1000000`` becomes ``'1,0 Million'``.
@ -79,7 +79,7 @@ You can pass in either an integer or a string representation of an integer.
.. templatefilter:: naturalday .. templatefilter:: naturalday
naturalday naturalday
---------- ==========
For dates that are the current day or within one day, return "today", For dates that are the current day or within one day, return "today",
"tomorrow" or "yesterday", as appropriate. Otherwise, format the date using "tomorrow" or "yesterday", as appropriate. Otherwise, format the date using
@ -98,7 +98,7 @@ Examples (when 'today' is 17 Feb 2007):
.. templatefilter:: naturaltime .. templatefilter:: naturaltime
naturaltime naturaltime
----------- ===========
For datetime values, returns a string representing how many seconds, For datetime values, returns a string representing how many seconds,
minutes or hours ago it was -- falling back to the :tfilter:`timesince` minutes or hours ago it was -- falling back to the :tfilter:`timesince`
@ -130,7 +130,7 @@ Examples (when 'now' is 17 Feb 2007 16:30:00):
.. templatefilter:: ordinal .. templatefilter:: ordinal
ordinal ordinal
------- =======
Converts an integer to its ordinal as a string. Converts an integer to its ordinal as a string.

42
docs/ref/contrib/postgres/aggregates.txt
View File

@ -19,17 +19,17 @@ These functions are described in more detail in the `PostgreSQL docs
{'arr': [0, 1, 2]} {'arr': [0, 1, 2]}
General-purpose aggregation functions General-purpose aggregation functions
------------------------------------- =====================================
ArrayAgg ArrayAgg
~~~~~~~~ --------
.. class:: ArrayAgg(expression, **extra) .. class:: ArrayAgg(expression, **extra)
Returns a list of values, including nulls, concatenated into an array. Returns a list of values, including nulls, concatenated into an array.
BitAnd BitAnd
~~~~~~ ------
.. class:: BitAnd(expression, **extra) .. class:: BitAnd(expression, **extra)
@ -37,7 +37,7 @@ BitAnd
``None`` if all values are null. ``None`` if all values are null.
BitOr BitOr
~~~~~ -----
.. class:: BitOr(expression, **extra) .. class:: BitOr(expression, **extra)
@ -45,7 +45,7 @@ BitOr
``None`` if all values are null. ``None`` if all values are null.
BoolAnd BoolAnd
~~~~~~~~ -------
.. class:: BoolAnd(expression, **extra) .. class:: BoolAnd(expression, **extra)
@ -53,7 +53,7 @@ BoolAnd
null or if there are no values, otherwise ``False`` . null or if there are no values, otherwise ``False`` .
BoolOr BoolOr
~~~~~~ ------
.. class:: BoolOr(expression, **extra) .. class:: BoolOr(expression, **extra)
@ -61,7 +61,7 @@ BoolOr
values are null or if there are no values, otherwise ``False``. values are null or if there are no values, otherwise ``False``.
StringAgg StringAgg
~~~~~~~~~ ---------
.. class:: StringAgg(expression, delimiter) .. class:: StringAgg(expression, delimiter)
@ -73,16 +73,16 @@ StringAgg
Required argument. Needs to be a string. Required argument. Needs to be a string.
Aggregate functions for statistics Aggregate functions for statistics
---------------------------------- ==================================
``y`` and ``x`` ``y`` and ``x``
~~~~~~~~~~~~~~~ ---------------
The arguments ``y`` and ``x`` for all these functions can be the name of a The arguments ``y`` and ``x`` for all these functions can be the name of a
field or an expression returning a numeric data. Both are required. field or an expression returning a numeric data. Both are required.
Corr Corr
~~~~ ----
.. class:: Corr(y, x) .. class:: Corr(y, x)
@ -90,7 +90,7 @@ Corr
aren't any matching rows. aren't any matching rows.
CovarPop CovarPop
~~~~~~~~ --------
.. class:: CovarPop(y, x, sample=False) .. class:: CovarPop(y, x, sample=False)
@ -106,7 +106,7 @@ CovarPop
population covariance. population covariance.
RegrAvgX RegrAvgX
~~~~~~~~ --------
.. class:: RegrAvgX(y, x) .. class:: RegrAvgX(y, x)
@ -114,7 +114,7 @@ RegrAvgX
``float``, or ``None`` if there aren't any matching rows. ``float``, or ``None`` if there aren't any matching rows.
RegrAvgY RegrAvgY
~~~~~~~~ --------
.. class:: RegrAvgY(y, x) .. class:: RegrAvgY(y, x)
@ -122,7 +122,7 @@ RegrAvgY
``float``, or ``None`` if there aren't any matching rows. ``float``, or ``None`` if there aren't any matching rows.
RegrCount RegrCount
~~~~~~~~~ ---------
.. class:: RegrCount(y, x) .. class:: RegrCount(y, x)
@ -130,7 +130,7 @@ RegrCount
are not null. are not null.
RegrIntercept RegrIntercept
~~~~~~~~~~~~~ -------------
.. class:: RegrIntercept(y, x) .. class:: RegrIntercept(y, x)
@ -139,7 +139,7 @@ RegrIntercept
matching rows. matching rows.
RegrR2 RegrR2
~~~~~~ ------
.. class:: RegrR2(y, x) .. class:: RegrR2(y, x)
@ -147,7 +147,7 @@ RegrR2
``None`` if there aren't any matching rows. ``None`` if there aren't any matching rows.
RegrSlope RegrSlope
~~~~~~~~~ ---------
.. class:: RegrSlope(y, x) .. class:: RegrSlope(y, x)
@ -156,7 +156,7 @@ RegrSlope
matching rows. matching rows.
RegrSXX RegrSXX
~~~~~~~ -------
.. class:: RegrSXX(y, x) .. class:: RegrSXX(y, x)
@ -164,7 +164,7 @@ RegrSXX
variable) as a ``float``, or ``None`` if there aren't any matching rows. variable) as a ``float``, or ``None`` if there aren't any matching rows.
RegrSXY RegrSXY
~~~~~~~ -------
.. class:: RegrSXY(y, x) .. class:: RegrSXY(y, x)
@ -173,7 +173,7 @@ RegrSXY
matching rows. matching rows.
RegrSYY RegrSYY
~~~~~~~ -------
.. class:: RegrSYY(y, x) .. class:: RegrSYY(y, x)
@ -181,7 +181,7 @@ RegrSYY
variable) as a ``float``, or ``None`` if there aren't any matching rows. variable) as a ``float``, or ``None`` if there aren't any matching rows.
Usage examples Usage examples
-------------- ==============
We will use this example table:: We will use this example table::

51
docs/ref/contrib/postgres/fields.txt
View File

@ -1,3 +1,4 @@
================================
PostgreSQL specific model fields PostgreSQL specific model fields
================================ ================================
@ -7,7 +8,7 @@ module.
.. currentmodule:: django.contrib.postgres.fields .. currentmodule:: django.contrib.postgres.fields
ArrayField ArrayField
---------- ==========
.. class:: ArrayField(base_field, size=None, **options) .. class:: ArrayField(base_field, size=None, **options)
@ -91,7 +92,7 @@ ArrayField
nullable and the values padded with ``None``. nullable and the values padded with ``None``.
Querying ArrayField Querying ArrayField
^^^^^^^^^^^^^^^^^^^ -------------------
There are a number of custom lookups and transforms for :class:`ArrayField`. There are a number of custom lookups and transforms for :class:`ArrayField`.
We will use the following example model:: We will use the following example model::
@ -242,7 +243,7 @@ lookups available after the transform do not change. For example::
fashion by Django. fashion by Django.
Indexing ArrayField Indexing ArrayField
^^^^^^^^^^^^^^^^^^^ -------------------
At present using :attr:`~django.db.models.Field.db_index` will create a At present using :attr:`~django.db.models.Field.db_index` will create a
``btree`` index. This does not offer particularly significant help to querying. ``btree`` index. This does not offer particularly significant help to querying.
@ -250,7 +251,7 @@ A more useful index is a ``GIN`` index, which you should create using a
:class:`~django.db.migrations.operations.RunSQL` operation. :class:`~django.db.migrations.operations.RunSQL` operation.
HStoreField HStoreField
----------- ===========
.. class:: HStoreField(**options) .. class:: HStoreField(**options)
@ -292,7 +293,7 @@ HStoreField
:class:`~django.contrib.postgres.validators.KeysValidator`. :class:`~django.contrib.postgres.validators.KeysValidator`.
Querying HStoreField Querying HStoreField
^^^^^^^^^^^^^^^^^^^^ --------------------
In addition to the ability to query by key, there are a number of custom In addition to the ability to query by key, there are a number of custom
lookups available for ``HStoreField``. lookups available for ``HStoreField``.
@ -457,7 +458,7 @@ using in conjunction with lookups on
<QuerySet [<Dog: Meg>]> <QuerySet [<Dog: Meg>]>
JSONField JSONField
--------- =========
.. versionadded:: 1.9 .. versionadded:: 1.9
@ -492,7 +493,7 @@ JSONField
**As a result, this field requires PostgreSQL ≥ 9.4 and Psycopg2 ≥ 2.5.4**. **As a result, this field requires PostgreSQL ≥ 9.4 and Psycopg2 ≥ 2.5.4**.
Querying JSONField Querying JSONField
^^^^^^^^^^^^^^^^^^ ------------------
We will use the following example model:: We will use the following example model::
@ -575,7 +576,7 @@ containment and keys with :class:`~django.contrib.postgres.fields.HStoreField`.
.. _range-fields: .. _range-fields:
Range Fields Range Fields
------------ ============
There are five range field types, corresponding to the built-in range types in There are five range field types, corresponding to the built-in range types in
PostgreSQL. These fields are used to store a range of values; for example the PostgreSQL. These fields are used to store a range of values; for example the
@ -588,7 +589,7 @@ information is necessary. The default is lower bound included, upper bound
excluded. excluded.
IntegerRangeField IntegerRangeField
^^^^^^^^^^^^^^^^^ -----------------
.. class:: IntegerRangeField(**options) .. class:: IntegerRangeField(**options)
@ -598,7 +599,7 @@ IntegerRangeField
Python. Python.
BigIntegerRangeField BigIntegerRangeField
^^^^^^^^^^^^^^^^^^^^ --------------------
.. class:: BigIntegerRangeField(**options) .. class:: BigIntegerRangeField(**options)
@ -608,7 +609,7 @@ BigIntegerRangeField
Python. Python.
FloatRangeField FloatRangeField
^^^^^^^^^^^^^^^ ---------------
.. class:: FloatRangeField(**options) .. class:: FloatRangeField(**options)
@ -617,7 +618,7 @@ FloatRangeField
database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in Python. database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in Python.
DateTimeRangeField DateTimeRangeField
^^^^^^^^^^^^^^^^^^ ------------------
.. class:: DateTimeRangeField(**options) .. class:: DateTimeRangeField(**options)
@ -627,7 +628,7 @@ DateTimeRangeField
Python. Python.
DateRangeField DateRangeField
^^^^^^^^^^^^^^ --------------
.. class:: DateRangeField(**options) .. class:: DateRangeField(**options)
@ -636,7 +637,7 @@ DateRangeField
database and a :class:`~psycopg2:psycopg2.extras.DateRange` in Python. database and a :class:`~psycopg2:psycopg2.extras.DateRange` in Python.
Querying Range Fields Querying Range Fields
^^^^^^^^^^^^^^^^^^^^^ ---------------------
There are a number of custom lookups and transforms for range fields. They are There are a number of custom lookups and transforms for range fields. They are
available on all the above fields, but we will use the following example available on all the above fields, but we will use the following example
@ -675,7 +676,7 @@ operators ``@>``, ``<@``, and ``&&`` respectively.
.. fieldlookup:: rangefield.contains .. fieldlookup:: rangefield.contains
contains contains
'''''''' ^^^^^^^^
>>> Event.objects.filter(ages__contains=NumericRange(4, 5)) >>> Event.objects.filter(ages__contains=NumericRange(4, 5))
<QuerySet [<Event: Soft play>]> <QuerySet [<Event: Soft play>]>
@ -683,7 +684,7 @@ contains
.. fieldlookup:: rangefield.contained_by .. fieldlookup:: rangefield.contained_by
contained_by contained_by
'''''''''''' ^^^^^^^^^^^^
>>> Event.objects.filter(ages__contained_by=NumericRange(0, 15)) >>> Event.objects.filter(ages__contained_by=NumericRange(0, 15))
<QuerySet [<Event: Soft play>]> <QuerySet [<Event: Soft play>]>
@ -707,7 +708,7 @@ contained_by
.. fieldlookup:: rangefield.overlap .. fieldlookup:: rangefield.overlap
overlap overlap
''''''' ^^^^^^^
>>> Event.objects.filter(ages__overlap=NumericRange(8, 12)) >>> Event.objects.filter(ages__overlap=NumericRange(8, 12))
<QuerySet [<Event: Soft play>]> <QuerySet [<Event: Soft play>]>
@ -724,7 +725,7 @@ the specific range comparison operators.
.. fieldlookup:: rangefield.fully_lt .. fieldlookup:: rangefield.fully_lt
fully_lt fully_lt
'''''''' ^^^^^^^^
The returned ranges are strictly less than the passed range. In other words, The returned ranges are strictly less than the passed range. In other words,
all the points in the returned range are less than all those in the passed all the points in the returned range are less than all those in the passed
@ -736,7 +737,7 @@ range.
.. fieldlookup:: rangefield.fully_gt .. fieldlookup:: rangefield.fully_gt
fully_gt fully_gt
'''''''' ^^^^^^^^
The returned ranges are strictly greater than the passed range. In other words, The returned ranges are strictly greater than the passed range. In other words,
the all the points in the returned range are greater than all those in the the all the points in the returned range are greater than all those in the
@ -748,7 +749,7 @@ passed range.
.. fieldlookup:: rangefield.not_lt .. fieldlookup:: rangefield.not_lt
not_lt not_lt
'''''' ^^^^^^
The returned ranges do not contain any points less than the passed range, that The returned ranges do not contain any points less than the passed range, that
is the lower bound of the returned range is at least the lower bound of the is the lower bound of the returned range is at least the lower bound of the
@ -760,7 +761,7 @@ passed range.
.. fieldlookup:: rangefield.not_gt .. fieldlookup:: rangefield.not_gt
not_gt not_gt
'''''' ^^^^^^
The returned ranges do not contain any points greater than the passed range, that The returned ranges do not contain any points greater than the passed range, that
is the upper bound of the returned range is at most the upper bound of the is the upper bound of the returned range is at most the upper bound of the
@ -772,7 +773,7 @@ passed range.
.. fieldlookup:: rangefield.adjacent_to .. fieldlookup:: rangefield.adjacent_to
adjacent_to adjacent_to
''''''''''' ^^^^^^^^^^^
The returned ranges share a bound with the passed range. The returned ranges share a bound with the passed range.
@ -788,7 +789,7 @@ lower or upper bound, or query based on emptiness.
.. fieldlookup:: rangefield.startswith .. fieldlookup:: rangefield.startswith
startswith startswith
'''''''''' ^^^^^^^^^^
Returned objects have the given lower bound. Can be chained to valid lookups Returned objects have the given lower bound. Can be chained to valid lookups
for the base field. for the base field.
@ -799,7 +800,7 @@ for the base field.
.. fieldlookup:: rangefield.endswith .. fieldlookup:: rangefield.endswith
endswith endswith
'''''''' ^^^^^^^^
Returned objects have the given upper bound. Can be chained to valid lookups Returned objects have the given upper bound. Can be chained to valid lookups
for the base field. for the base field.
@ -810,7 +811,7 @@ for the base field.
.. fieldlookup:: rangefield.isempty .. fieldlookup:: rangefield.isempty
isempty isempty
''''''' ^^^^^^^
Returned objects are empty ranges. Can be chained to valid lookups for a Returned objects are empty ranges. Can be chained to valid lookups for a
:class:`~django.db.models.BooleanField`. :class:`~django.db.models.BooleanField`.

8
docs/ref/contrib/postgres/forms.txt
View File

@ -1,3 +1,4 @@
===========================================
PostgreSQL specific form fields and widgets PostgreSQL specific form fields and widgets
=========================================== ===========================================
@ -6,6 +7,9 @@ All of these fields and widgets are available from the
.. currentmodule:: django.contrib.postgres.forms .. currentmodule:: django.contrib.postgres.forms
Fields
======
SimpleArrayField SimpleArrayField
---------------- ----------------
@ -217,10 +221,10 @@ DateRangeField
:class:`~django.contrib.postgres.fields.DateRangeField`. :class:`~django.contrib.postgres.fields.DateRangeField`.
Widgets Widgets
------- =======
RangeWidget RangeWidget
~~~~~~~~~~~ -----------
.. class:: RangeWidget(base_widget, attrs=None) .. class:: RangeWidget(base_widget, attrs=None)

3
docs/ref/contrib/postgres/functions.txt
View File

@ -1,3 +1,4 @@
======================================
PostgreSQL specific database functions PostgreSQL specific database functions
====================================== ======================================
@ -7,7 +8,7 @@ All of these functions are available from the
.. currentmodule:: django.contrib.postgres.functions .. currentmodule:: django.contrib.postgres.functions
TransactionNow TransactionNow
-------------- ==============
.. class:: TransactionNow() .. class:: TransactionNow()

1
docs/ref/contrib/postgres/index.txt
View File

@ -1,3 +1,4 @@
===========================
``django.contrib.postgres`` ``django.contrib.postgres``
=========================== ===========================

7
docs/ref/contrib/postgres/operations.txt
View File

@ -1,3 +1,4 @@
=============================
Database migration operations Database migration operations
============================= =============================
@ -7,7 +8,7 @@ the ``django.contrib.postgres.operations`` module.
.. currentmodule:: django.contrib.postgres.operations .. currentmodule:: django.contrib.postgres.operations
CreateExtension CreateExtension
--------------- ===============
.. class:: CreateExtension(name) .. class:: CreateExtension(name)
@ -18,7 +19,7 @@ CreateExtension
This is a required argument. The name of the extension to be installed. This is a required argument. The name of the extension to be installed.
HStoreExtension HStoreExtension
--------------- ===============
.. class:: HStoreExtension() .. class:: HStoreExtension()
@ -27,7 +28,7 @@ HStoreExtension
connection to interpret hstore data. connection to interpret hstore data.
UnaccentExtension UnaccentExtension
----------------- =================
.. class:: UnaccentExtension() .. class:: UnaccentExtension()

4
docs/ref/contrib/postgres/validators.txt
View File

@ -5,7 +5,7 @@ Validators
.. module:: django.contrib.postgres.validators .. module:: django.contrib.postgres.validators
``KeysValidator`` ``KeysValidator``
----------------- =================
.. class:: KeysValidator(keys, strict=False, messages=None) .. class:: KeysValidator(keys, strict=False, messages=None)
@ -20,7 +20,7 @@ Validators
the value of a key is non-empty. the value of a key is non-empty.
Range validators Range validators
---------------- ================
.. class:: RangeMaxValueValidator(limit_value, message=None) .. class:: RangeMaxValueValidator(limit_value, message=None)

9
docs/ref/files/file.txt
View File

@ -1,3 +1,4 @@
===================
The ``File`` object The ``File`` object
=================== ===================
@ -7,7 +8,7 @@ for basic file handling in Django.
.. currentmodule:: django.core.files .. currentmodule:: django.core.files
The ``File`` Class The ``File`` Class
------------------ ==================
.. class:: File(file_object) .. class:: File(file_object)
@ -90,7 +91,7 @@ The ``File`` Class
.. currentmodule:: django.core.files.base .. currentmodule:: django.core.files.base
The ``ContentFile`` Class The ``ContentFile`` Class
------------------------- =========================
.. class:: ContentFile(File) .. class:: ContentFile(File)
@ -107,7 +108,7 @@ The ``ContentFile`` Class
.. currentmodule:: django.core.files.images .. currentmodule:: django.core.files.images
The ``ImageFile`` Class The ``ImageFile`` Class
----------------------- =======================
.. class:: ImageFile(file_object) .. class:: ImageFile(file_object)
@ -127,7 +128,7 @@ The ``ImageFile`` Class
.. currentmodule:: django.core.files .. currentmodule:: django.core.files
Additional methods on files attached to objects Additional methods on files attached to objects
----------------------------------------------- ===============================================
Any :class:`File` that is associated with an object (as with ``Car.photo``, Any :class:`File` that is associated with an object (as with ``Car.photo``,
below) will also have a couple of extra methods: below) will also have a couple of extra methods:

7
docs/ref/files/storage.txt
View File

@ -1,10 +1,11 @@
================
File storage API File storage API
================ ================
.. module:: django.core.files.storage .. module:: django.core.files.storage
Getting the current storage class Getting the current storage class
--------------------------------- =================================
Django provides two convenient ways to access the current storage class: Django provides two convenient ways to access the current storage class:
@ -27,7 +28,7 @@ Django provides two convenient ways to access the current storage class:
raised if the import is unsuccessful. raised if the import is unsuccessful.
The FileSystemStorage Class The FileSystemStorage Class
--------------------------- ===========================
.. class:: FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None) .. class:: FileSystemStorage(location=None, base_url=None, file_permissions_mode=None, directory_permissions_mode=None)
@ -62,7 +63,7 @@ The FileSystemStorage Class
an exception if the given file name does not exist. an exception if the given file name does not exist.
The Storage Class The Storage Class
----------------- =================
.. class:: Storage .. class:: Storage

4
docs/ref/files/uploads.txt
View File

@ -137,7 +137,7 @@ All file upload handlers should be subclasses of
handlers wherever you wish. handlers wherever you wish.
Required methods Required methods
~~~~~~~~~~~~~~~~ ----------------
Custom file upload handlers **must** define the following methods: Custom file upload handlers **must** define the following methods:
@ -171,7 +171,7 @@ Custom file upload handlers **must** define the following methods:
the ``UploadedFile`` object should come from subsequent upload handlers. the ``UploadedFile`` object should come from subsequent upload handlers.
Optional methods Optional methods
~~~~~~~~~~~~~~~~ ----------------
Custom upload handlers may also define any of the following optional methods or Custom upload handlers may also define any of the following optional methods or
attributes: attributes:

48
docs/ref/forms/api.txt
View File

@ -13,7 +13,7 @@ The Forms API
.. _ref-forms-api-bound-unbound: .. _ref-forms-api-bound-unbound:
Bound and unbound forms Bound and unbound forms
----------------------- =======================
A :class:`Form` instance is either **bound** to a set of data, or **unbound**. A :class:`Form` instance is either **bound** to a set of data, or **unbound**.
@ -69,7 +69,7 @@ another :class:`Form` instance. There is no way to change data in a
should consider its data immutable, whether it has data or not. should consider its data immutable, whether it has data or not.
Using forms to validate data Using forms to validate data
---------------------------- ============================
.. method:: Form.clean() .. method:: Form.clean()
@ -201,7 +201,7 @@ This includes ``ValidationError``\s that are raised in :meth:`Form.clean()
"...") <django.forms.Form.add_error>`. "...") <django.forms.Form.add_error>`.
Behavior of unbound forms Behavior of unbound forms
~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------
It's meaningless to validate a form with no data, but, for the record, here's It's meaningless to validate a form with no data, but, for the record, here's
what happens with unbound forms:: what happens with unbound forms::
@ -213,7 +213,7 @@ what happens with unbound forms::
{} {}
Dynamic initial values Dynamic initial values
---------------------- ======================
.. attribute:: Form.initial .. attribute:: Form.initial
@ -249,7 +249,7 @@ precedence::
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
Checking which form data has changed Checking which form data has changed
------------------------------------ ====================================
.. method:: Form.has_changed() .. method:: Form.has_changed()
@ -286,7 +286,7 @@ provided in :attr:`~Form.initial`. It returns an empty list if no data differs.
... print("The following fields changed: %s" % ", ".join(f.changed_data)) ... print("The following fields changed: %s" % ", ".join(f.changed_data))
Accessing the fields from the form Accessing the fields from the form
---------------------------------- ==================================
.. attribute:: Form.fields .. attribute:: Form.fields
@ -320,7 +320,7 @@ process::
'<tr><th>Username:</th><td><input name="name" type="text" value="class" /></td></tr>' '<tr><th>Username:</th><td><input name="name" type="text" value="class" /></td></tr>'
Accessing "clean" data Accessing "clean" data
---------------------- ======================
.. attribute:: Form.cleaned_data .. attribute:: Form.cleaned_data
@ -414,7 +414,7 @@ fields). More information about this is in :doc:`/ref/forms/validation`.
.. _ref-forms-api-outputting-html: .. _ref-forms-api-outputting-html:
Outputting forms as HTML Outputting forms as HTML
------------------------ ========================
The second task of a ``Form`` object is to render itself as HTML. To do so, The second task of a ``Form`` object is to render itself as HTML. To do so,
simply ``print`` it:: simply ``print`` it::
@ -476,7 +476,7 @@ form, other output styles are available. Each style is available as a method on
a form object, and each rendering method returns a Unicode object. a form object, and each rendering method returns a Unicode object.
``as_p()`` ``as_p()``
~~~~~~~~~~ ----------
.. method:: Form.as_p() .. method:: Form.as_p()
@ -493,7 +493,7 @@ containing one field::
<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p> <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>
``as_ul()`` ``as_ul()``
~~~~~~~~~~~ -----------
.. method:: Form.as_ul() .. method:: Form.as_ul()
@ -512,7 +512,7 @@ flexibility::
<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li> <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>
``as_table()`` ``as_table()``
~~~~~~~~~~~~~~ --------------
.. method:: Form.as_table() .. method:: Form.as_table()
@ -532,7 +532,7 @@ it calls its ``as_table()`` method behind the scenes::
.. _ref-forms-api-styling-form-rows: .. _ref-forms-api-styling-form-rows:
Styling required or erroneous form rows Styling required or erroneous form rows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------
.. attribute:: Form.error_css_class .. attribute:: Form.error_css_class
.. attribute:: Form.required_css_class .. attribute:: Form.required_css_class
@ -571,7 +571,7 @@ classes, as needed. The HTML will look something like::
.. _ref-forms-api-configuring-label: .. _ref-forms-api-configuring-label:
Configuring form elements' HTML ``id`` attributes and ``<label>`` tags Configuring form elements' HTML ``id`` attributes and ``<label>`` tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------------------------------
.. attribute:: Form.auto_id .. attribute:: Form.auto_id
@ -693,7 +693,7 @@ using the ``label_suffix`` parameter to
:meth:`~django.forms.BoundField.label_tag`. :meth:`~django.forms.BoundField.label_tag`.
Notes on field ordering Notes on field ordering
~~~~~~~~~~~~~~~~~~~~~~~ -----------------------
In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
displayed in the order in which you define them in your form class. For displayed in the order in which you define them in your form class. For
@ -727,7 +727,7 @@ You may rearrange the fields any time using ``order_fields()`` with a list of
field names as in :attr:`~django.forms.Form.field_order`. field names as in :attr:`~django.forms.Form.field_order`.
How errors are displayed How errors are displayed
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
If you render a bound ``Form`` object, the act of rendering will automatically If you render a bound ``Form`` object, the act of rendering will automatically
run the form's validation if it hasn't already happened, and the HTML output run the form's validation if it hasn't already happened, and the HTML output
@ -761,7 +761,7 @@ method you're using::
.. _ref-forms-error-list-format: .. _ref-forms-error-list-format:
Customizing the error list format Customizing the error list format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------
By default, forms use ``django.forms.utils.ErrorList`` to format validation By default, forms use ``django.forms.utils.ErrorList`` to format validation
errors. If you'd like to use an alternate class for displaying errors, you can errors. If you'd like to use an alternate class for displaying errors, you can
@ -785,7 +785,7 @@ Python 2)::
<p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p> <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
More granular output More granular output
-------------------- ====================
The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are simply shortcuts -- The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are simply shortcuts --
they're not the only way a form object can be displayed. they're not the only way a form object can be displayed.
@ -824,7 +824,7 @@ The field-specific output honors the form object's ``auto_id`` setting::
<input type="text" name="message" id="id_message" /> <input type="text" name="message" id="id_message" />
Attributes of ``BoundField`` Attributes of ``BoundField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
.. attribute:: BoundField.data .. attribute:: BoundField.data
@ -922,7 +922,7 @@ Attributes of ``BoundField``
message message
Methods of ``BoundField`` Methods of ``BoundField``
~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------
.. method:: BoundField.as_hidden(attrs=None, **kwargs) .. method:: BoundField.as_hidden(attrs=None, **kwargs)
@ -995,7 +995,7 @@ Methods of ``BoundField``
hi hi
Customizing ``BoundField`` Customizing ``BoundField``
-------------------------- ==========================
.. versionadded:: 1.9 .. versionadded:: 1.9
@ -1039,7 +1039,7 @@ Now you can access the country in a template with
.. _binding-uploaded-files: .. _binding-uploaded-files:
Binding uploaded files to a form Binding uploaded files to a form
-------------------------------- ================================
Dealing with forms that have ``FileField`` and ``ImageField`` fields Dealing with forms that have ``FileField`` and ``ImageField`` fields
is a little more complicated than a normal form. is a little more complicated than a normal form.
@ -1080,7 +1080,7 @@ form data *and* file data::
>>> f = ContactFormWithMugshot() >>> f = ContactFormWithMugshot()
Testing for multipart forms Testing for multipart forms
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
.. method:: Form.is_multipart() .. method:: Form.is_multipart()
@ -1103,7 +1103,7 @@ Here's an example of how you might use this in a template::
</form> </form>
Subclassing forms Subclassing forms
----------------- =================
If you have multiple ``Form`` classes that share fields, you can use If you have multiple ``Form`` classes that share fields, you can use
subclassing to remove redundancy. subclassing to remove redundancy.
@ -1164,7 +1164,7 @@ by setting the name of the field to ``None`` on the subclass. For example::
.. _form-prefix: .. _form-prefix:
Prefixes for forms Prefixes for forms
------------------ ==================
.. attribute:: Form.prefix .. attribute:: Form.prefix

96
docs/ref/forms/fields.txt
View File

@ -33,14 +33,14 @@ exception or returns the clean value::
.. _core-field-arguments: .. _core-field-arguments:
Core field arguments Core field arguments
-------------------- ====================
Each ``Field`` class constructor takes at least these arguments. Some Each ``Field`` class constructor takes at least these arguments. Some
``Field`` classes take additional, field-specific arguments, but the following ``Field`` classes take additional, field-specific arguments, but the following
should *always* be accepted: should *always* be accepted:
``required`` ``required``
~~~~~~~~~~~~ ------------
.. attribute:: Field.required .. attribute:: Field.required
@ -93,7 +93,7 @@ For other ``Field`` classes, it might be ``None``. (This varies from field to
field.) field.)
``label`` ``label``
~~~~~~~~~ ---------
.. attribute:: Field.label .. attribute:: Field.label
@ -120,7 +120,7 @@ We've specified ``auto_id=False`` to simplify the output::
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
``label_suffix`` ``label_suffix``
~~~~~~~~~~~~~~~~ ----------------
.. attribute:: Field.label_suffix .. attribute:: Field.label_suffix
@ -138,7 +138,7 @@ The ``label_suffix`` argument lets you override the form's
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></p> <p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></p>
``initial`` ``initial``
~~~~~~~~~~~ -----------
.. attribute:: Field.initial .. attribute:: Field.initial
@ -206,7 +206,7 @@ Instead of a constant, you can also pass any callable::
The callable will be evaluated only when the unbound form is displayed, not when it is defined. The callable will be evaluated only when the unbound form is displayed, not when it is defined.
``widget`` ``widget``
~~~~~~~~~~ ----------
.. attribute:: Field.widget .. attribute:: Field.widget
@ -214,7 +214,7 @@ The ``widget`` argument lets you specify a ``Widget`` class to use when
rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information. rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information.
``help_text`` ``help_text``
~~~~~~~~~~~~~ -------------
.. attribute:: Field.help_text .. attribute:: Field.help_text
@ -253,7 +253,7 @@ fields. We've specified ``auto_id=False`` to simplify the output::
<p>Cc myself: <input type="checkbox" name="cc_myself" /></p> <p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
``error_messages`` ``error_messages``
~~~~~~~~~~~~~~~~~~ ------------------
.. attribute:: Field.error_messages .. attribute:: Field.error_messages
@ -280,7 +280,7 @@ In the `built-in Field classes`_ section below, each ``Field`` defines the
error message keys it uses. error message keys it uses.
``validators`` ``validators``
~~~~~~~~~~~~~~ --------------
.. attribute:: Field.validators .. attribute:: Field.validators
@ -290,18 +290,18 @@ for this field.
See the :doc:`validators documentation </ref/validators>` for more information. See the :doc:`validators documentation </ref/validators>` for more information.
``localize`` ``localize``
~~~~~~~~~~~~ ------------
.. attribute:: Field.localize .. attribute:: Field.localize
The ``localize`` argument enables the localization of form data input, as well The ``localize`` argument enables the localization of form data input, as well
as the rendered output. as the rendered output.
See the :ref:`format localization <format-localization>` documentation for See the :doc:`format localization </topics/i18n/formatting>` documentation for
more information. more information.
``disabled`` ``disabled``
~~~~~~~~~~~~ ------------
.. attribute:: Field.disabled .. attribute:: Field.disabled
@ -313,10 +313,10 @@ Even if a user tampers with the field's value submitted to the server, it will
be ignored in favor of the value from the form's initial data. be ignored in favor of the value from the form's initial data.
Checking if the field data has changed Checking if the field data has changed
-------------------------------------- ======================================
``has_changed()`` ``has_changed()``
~~~~~~~~~~~~~~~~~~ -----------------
.. method:: Field.has_changed() .. method:: Field.has_changed()
@ -328,7 +328,7 @@ See the :class:`Form.has_changed()` documentation for more information.
.. _built-in-fields: .. _built-in-fields:
Built-in ``Field`` classes Built-in ``Field`` classes
-------------------------- ==========================
Naturally, the ``forms`` library comes with a set of ``Field`` classes that Naturally, the ``forms`` library comes with a set of ``Field`` classes that
represent common validation needs. This section documents each built-in field. represent common validation needs. This section documents each built-in field.
@ -338,7 +338,7 @@ For each field, we describe the default widget used if you don't specify
(see the section on ``required`` above to understand what that means). (see the section on ``required`` above to understand what that means).
``BooleanField`` ``BooleanField``
~~~~~~~~~~~~~~~~ ----------------
.. class:: BooleanField(**kwargs) .. class:: BooleanField(**kwargs)
@ -358,7 +358,7 @@ For each field, we describe the default widget used if you don't specify
creating the ``BooleanField``. creating the ``BooleanField``.
``CharField`` ``CharField``
~~~~~~~~~~~~~ -------------
.. class:: CharField(**kwargs) .. class:: CharField(**kwargs)
@ -385,7 +385,7 @@ For each field, we describe the default widget used if you don't specify
trailing whitespace. trailing whitespace.
``ChoiceField`` ``ChoiceField``
~~~~~~~~~~~~~~~ ---------------
.. class:: ChoiceField(**kwargs) .. class:: ChoiceField(**kwargs)
@ -410,7 +410,7 @@ For each field, we describe the default widget used if you don't specify
callable, it is evaluated each time the field's form is initialized. callable, it is evaluated each time the field's form is initialized.
``TypedChoiceField`` ``TypedChoiceField``
~~~~~~~~~~~~~~~~~~~~ --------------------
.. class:: TypedChoiceField(**kwargs) .. class:: TypedChoiceField(**kwargs)
@ -442,7 +442,7 @@ For each field, we describe the default widget used if you don't specify
accordingly. accordingly.
``DateField`` ``DateField``
~~~~~~~~~~~~~ -------------
.. class:: DateField(**kwargs) .. class:: DateField(**kwargs)
@ -478,10 +478,10 @@ For each field, we describe the default widget used if you don't specify
'%d %B %Y', # '25 October 2006' '%d %B %Y', # '25 October 2006'
'%d %B, %Y'] # '25 October, 2006' '%d %B, %Y'] # '25 October, 2006'
See also :ref:`format localization <format-localization>`. See also :doc:`format localization </topics/i18n/formatting>`.
``DateTimeField`` ``DateTimeField``
~~~~~~~~~~~~~~~~~ -----------------
.. class:: DateTimeField(**kwargs) .. class:: DateTimeField(**kwargs)
@ -511,10 +511,10 @@ For each field, we describe the default widget used if you don't specify
'%m/%d/%y %H:%M', # '10/25/06 14:30' '%m/%d/%y %H:%M', # '10/25/06 14:30'
'%m/%d/%y'] # '10/25/06' '%m/%d/%y'] # '10/25/06'
See also :ref:`format localization <format-localization>`. See also :doc:`format localization </topics/i18n/formatting>`.
``DecimalField`` ``DecimalField``
~~~~~~~~~~~~~~~~ ----------------
.. class:: DecimalField(**kwargs) .. class:: DecimalField(**kwargs)
@ -552,7 +552,7 @@ For each field, we describe the default widget used if you don't specify
The maximum number of decimal places permitted. The maximum number of decimal places permitted.
``DurationField`` ``DurationField``
~~~~~~~~~~~~~~~~~ -----------------
.. class:: DurationField(**kwargs) .. class:: DurationField(**kwargs)
@ -567,7 +567,7 @@ For each field, we describe the default widget used if you don't specify
:func:`~django.utils.dateparse.parse_duration`. :func:`~django.utils.dateparse.parse_duration`.
``EmailField`` ``EmailField``
~~~~~~~~~~~~~~ --------------
.. class:: EmailField(**kwargs) .. class:: EmailField(**kwargs)
@ -583,7 +583,7 @@ For each field, we describe the default widget used if you don't specify
given length. given length.
``FileField`` ``FileField``
~~~~~~~~~~~~~ -------------
.. class:: FileField(**kwargs) .. class:: FileField(**kwargs)
@ -611,7 +611,7 @@ For each field, we describe the default widget used if you don't specify
length and ``%(length)d`` will be replaced with the current filename length. length and ``%(length)d`` will be replaced with the current filename length.
``FilePathField`` ``FilePathField``
~~~~~~~~~~~~~~~~~ -----------------
.. class:: FilePathField(**kwargs) .. class:: FilePathField(**kwargs)
@ -654,7 +654,7 @@ For each field, we describe the default widget used if you don't specify
``FloatField`` ``FloatField``
~~~~~~~~~~~~~~ --------------
.. class:: FloatField(**kwargs) .. class:: FloatField(**kwargs)
@ -671,7 +671,7 @@ For each field, we describe the default widget used if you don't specify
These control the range of values permitted in the field. These control the range of values permitted in the field.
``ImageField`` ``ImageField``
~~~~~~~~~~~~~~ --------------
.. class:: ImageField(**kwargs) .. class:: ImageField(**kwargs)
@ -703,7 +703,7 @@ For each field, we describe the default widget used if you don't specify
.. _Image: https://pillow.readthedocs.org/en/latest/reference/Image.html .. _Image: https://pillow.readthedocs.org/en/latest/reference/Image.html
``IntegerField`` ``IntegerField``
~~~~~~~~~~~~~~~~ ----------------
.. class:: IntegerField(**kwargs) .. class:: IntegerField(**kwargs)
@ -727,7 +727,7 @@ For each field, we describe the default widget used if you don't specify
These control the range of values permitted in the field. These control the range of values permitted in the field.
``GenericIPAddressField`` ``GenericIPAddressField``
~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------
.. class:: GenericIPAddressField(**kwargs) .. class:: GenericIPAddressField(**kwargs)
@ -762,7 +762,7 @@ For each field, we describe the default widget used if you don't specify
when ``protocol`` is set to ``'both'``. when ``protocol`` is set to ``'both'``.
``MultipleChoiceField`` ``MultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~ -----------------------
.. class:: MultipleChoiceField(**kwargs) .. class:: MultipleChoiceField(**kwargs)
@ -779,7 +779,7 @@ For each field, we describe the default widget used if you don't specify
Takes one extra required argument, ``choices``, as for :class:`ChoiceField`. Takes one extra required argument, ``choices``, as for :class:`ChoiceField`.
``TypedMultipleChoiceField`` ``TypedMultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
.. class:: TypedMultipleChoiceField(**kwargs) .. class:: TypedMultipleChoiceField(**kwargs)
@ -801,7 +801,7 @@ For each field, we describe the default widget used if you don't specify
:class:`TypedChoiceField`. :class:`TypedChoiceField`.
``NullBooleanField`` ``NullBooleanField``
~~~~~~~~~~~~~~~~~~~~ --------------------
.. class:: NullBooleanField(**kwargs) .. class:: NullBooleanField(**kwargs)
@ -811,7 +811,7 @@ For each field, we describe the default widget used if you don't specify
* Validates nothing (i.e., it never raises a ``ValidationError``). * Validates nothing (i.e., it never raises a ``ValidationError``).
``RegexField`` ``RegexField``
~~~~~~~~~~~~~~ --------------
.. class:: RegexField(**kwargs) .. class:: RegexField(**kwargs)
@ -840,7 +840,7 @@ For each field, we describe the default widget used if you don't specify
regex validation. regex validation.
``SlugField`` ``SlugField``
~~~~~~~~~~~~~ -------------
.. class:: SlugField(**kwargs) .. class:: SlugField(**kwargs)
@ -864,7 +864,7 @@ For each field, we describe the default widget used if you don't specify
to ASCII letters. Defaults to ``False``. to ASCII letters. Defaults to ``False``.
``TimeField`` ``TimeField``
~~~~~~~~~~~~~ -------------
.. class:: TimeField(**kwargs) .. class:: TimeField(**kwargs)
@ -888,7 +888,7 @@ For each field, we describe the default widget used if you don't specify
'%H:%M', # '14:30' '%H:%M', # '14:30'
``URLField`` ``URLField``
~~~~~~~~~~~~ ------------
.. class:: URLField(**kwargs) .. class:: URLField(**kwargs)
@ -906,7 +906,7 @@ For each field, we describe the default widget used if you don't specify
These are the same as ``CharField.max_length`` and ``CharField.min_length``. These are the same as ``CharField.max_length`` and ``CharField.min_length``.
``UUIDField`` ``UUIDField``
~~~~~~~~~~~~~ -------------
.. class:: UUIDField(**kwargs) .. class:: UUIDField(**kwargs)
@ -919,10 +919,10 @@ For each field, we describe the default widget used if you don't specify
to the :class:`~python:uuid.UUID` constructor. to the :class:`~python:uuid.UUID` constructor.
Slightly complex built-in ``Field`` classes Slightly complex built-in ``Field`` classes
------------------------------------------- ===========================================
``ComboField`` ``ComboField``
~~~~~~~~~~~~~~ --------------
.. class:: ComboField(**kwargs) .. class:: ComboField(**kwargs)
@ -950,7 +950,7 @@ Slightly complex built-in ``Field`` classes
ValidationError: ['Ensure this value has at most 20 characters (it has 28).'] ValidationError: ['Ensure this value has at most 20 characters (it has 28).']
``MultiValueField`` ``MultiValueField``
~~~~~~~~~~~~~~~~~~~ -------------------
.. class:: MultiValueField(fields=(), **kwargs) .. class:: MultiValueField(fields=(), **kwargs)
@ -1033,7 +1033,7 @@ Slightly complex built-in ``Field`` classes
This method must be implemented in the subclasses. This method must be implemented in the subclasses.
``SplitDateTimeField`` ``SplitDateTimeField``
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
.. class:: SplitDateTimeField(**kwargs) .. class:: SplitDateTimeField(**kwargs)
@ -1064,7 +1064,7 @@ Slightly complex built-in ``Field`` classes
for :class:`TimeField` are used. for :class:`TimeField` are used.
Fields which handle relationships Fields which handle relationships
--------------------------------- =================================
Two fields are available for representing relationships between Two fields are available for representing relationships between
models: :class:`ModelChoiceField` and models: :class:`ModelChoiceField` and
@ -1087,7 +1087,7 @@ method::
self.fields['foo_select'].queryset = ... self.fields['foo_select'].queryset = ...
``ModelChoiceField`` ``ModelChoiceField``
~~~~~~~~~~~~~~~~~~~~ --------------------
.. class:: ModelChoiceField(**kwargs) .. class:: ModelChoiceField(**kwargs)
@ -1180,7 +1180,7 @@ method::
return "My Object #%i" % obj.id return "My Object #%i" % obj.id
``ModelMultipleChoiceField`` ``ModelMultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
.. class:: ModelMultipleChoiceField(**kwargs) .. class:: ModelMultipleChoiceField(**kwargs)
@ -1208,7 +1208,7 @@ method::
user's selection. user's selection.
Creating custom fields Creating custom fields
---------------------- ======================
If the built-in ``Field`` classes don't meet your needs, you can easily create If the built-in ``Field`` classes don't meet your needs, you can easily create
custom ``Field`` classes. To do this, just create a subclass of custom ``Field`` classes. To do this, just create a subclass of

2
docs/ref/forms/formsets.txt
View File

@ -12,4 +12,4 @@ Formset API reference. For introductory material about formsets, see the
Returns a ``FormSet`` class for the given ``form`` class. Returns a ``FormSet`` class for the given ``form`` class.
See :ref:`formsets` for example usage. See :doc:`formsets </topics/forms/formsets>` for example usage.

4
docs/ref/forms/models.txt
View File

@ -61,8 +61,8 @@ Model Form API reference. For introductory material about model forms, see the
Arguments ``formset``, ``extra``, ``max_num``, ``can_order``, Arguments ``formset``, ``extra``, ``max_num``, ``can_order``,
``can_delete`` and ``validate_max`` are passed through to ``can_delete`` and ``validate_max`` are passed through to
:func:`~django.forms.formsets.formset_factory`. See :ref:`formsets` for :func:`~django.forms.formsets.formset_factory`. See :doc:`formsets
details. </topics/forms/formsets>` for details.
See :ref:`model-formsets` for example usage. See :ref:`model-formsets` for example usage.

21
docs/ref/forms/validation.txt
View File

@ -1,10 +1,9 @@
.. currentmodule:: django.forms =========================
.. _form-and-field-validation:
Form and field validation Form and field validation
========================= =========================
.. currentmodule:: django.forms
Form validation happens when the data is cleaned. If you want to customize Form validation happens when the data is cleaned. If you want to customize
this process, there are various places to make changes, each one serving a this process, there are various places to make changes, each one serving a
different purpose. Three types of cleaning methods are run during form different purpose. Three types of cleaning methods are run during form
@ -112,7 +111,7 @@ for all remaining fields are still executed.
.. _raising-validation-error: .. _raising-validation-error:
Raising ``ValidationError`` Raising ``ValidationError``
--------------------------- ===========================
In order to make error messages flexible and easy to override, consider the In order to make error messages flexible and easy to override, consider the
following guidelines: following guidelines:
@ -184,7 +183,7 @@ greatly benefit from fully featured ``ValidationError``\s (with a ``code`` name
and a ``params`` dictionary). and a ``params`` dictionary).
Raising multiple errors Raising multiple errors
~~~~~~~~~~~~~~~~~~~~~~~ -----------------------
If you detect multiple errors during a cleaning method and wish to signal all If you detect multiple errors during a cleaning method and wish to signal all
of them to the form submitter, it is possible to pass a list of errors to the of them to the form submitter, it is possible to pass a list of errors to the
@ -206,7 +205,7 @@ with ``code``\s and ``params`` but a list of strings will also work::
]) ])
Using validation in practice Using validation in practice
---------------------------- ============================
The previous sections explained how validation works in general for forms. The previous sections explained how validation works in general for forms.
Since it can sometimes be easier to put things into place by seeing each Since it can sometimes be easier to put things into place by seeing each
@ -216,7 +215,7 @@ previous features.
.. _validators: .. _validators:
Using validators Using validators
~~~~~~~~~~~~~~~~ ----------------
Django's form (and model) fields support use of simple utility functions and Django's form (and model) fields support use of simple utility functions and
classes known as validators. A validator is merely a callable object or classes known as validators. A validator is merely a callable object or
@ -254,7 +253,7 @@ argument being the pattern: ``^[-a-zA-Z0-9_]+$``. See the section on
available and for an example of how to write a validator. available and for an example of how to write a validator.
Form field default cleaning Form field default cleaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
Let's first create a custom form field that validates its input is a string Let's first create a custom form field that validates its input is a string
containing comma-separated email addresses. The full class looks like this:: containing comma-separated email addresses. The full class looks like this::
@ -300,7 +299,7 @@ method will be run as part of the cleaning process and it will, in turn, call
the custom ``to_python()`` and ``validate()`` methods. the custom ``to_python()`` and ``validate()`` methods.
Cleaning a specific field attribute Cleaning a specific field attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------
Continuing on from the previous example, suppose that in our ``ContactForm``, Continuing on from the previous example, suppose that in our ``ContactForm``,
we want to make sure that the ``recipients`` field always contains the address we want to make sure that the ``recipients`` field always contains the address
@ -326,7 +325,7 @@ write a cleaning method that operates on the ``recipients`` field, like so::
.. _validating-fields-with-clean: .. _validating-fields-with-clean:
Cleaning and validating fields that depend on each other Cleaning and validating fields that depend on each other
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------------------
Suppose we add another requirement to our contact form: if the ``cc_myself`` Suppose we add another requirement to our contact form: if the ``cc_myself``
field is ``True``, the ``subject`` must contain the word ``"help"``. We are field is ``True``, the ``subject`` must contain the word ``"help"``. We are

41
docs/ref/forms/widgets.txt
View File

@ -22,7 +22,7 @@ dictionary that corresponds to the widget.
.. _widget-to-field: .. _widget-to-field:
Specifying widgets Specifying widgets
------------------ ==================
Whenever you specify a field on a form, Django will use a default widget Whenever you specify a field on a form, Django will use a default widget
that is appropriate to the type of data that is to be displayed. To find that is appropriate to the type of data that is to be displayed. To find
@ -43,9 +43,8 @@ example::
This would specify a form with a comment that uses a larger :class:`Textarea` This would specify a form with a comment that uses a larger :class:`Textarea`
widget, rather than the default :class:`TextInput` widget. widget, rather than the default :class:`TextInput` widget.
Setting arguments for widgets Setting arguments for widgets
----------------------------- =============================
Many widgets have optional extra arguments; they can be set when defining the Many widgets have optional extra arguments; they can be set when defining the
widget on the field. In the following example, the widget on the field. In the following example, the
@ -69,9 +68,8 @@ widget on the field. In the following example, the
See the :ref:`built-in widgets` for more information about which widgets See the :ref:`built-in widgets` for more information about which widgets
are available and which arguments they accept. are available and which arguments they accept.
Widgets inheriting from the Select widget Widgets inheriting from the Select widget
----------------------------------------- =========================================
Widgets inheriting from the :class:`Select` widget deal with choices. They Widgets inheriting from the :class:`Select` widget deal with choices. They
present the user with a list of options to choose from. The different widgets present the user with a list of options to choose from. The different widgets
@ -96,14 +94,13 @@ example::
>>> choice_field.widget.choices >>> choice_field.widget.choices
[('1', 'First and only')] [('1', 'First and only')]
Widgets which offer a :attr:`~Select.choices` attribute can however be used Widgets which offer a :attr:`~Select.choices` attribute can however be used
with fields which are not based on choice -- such as a :class:`CharField` -- with fields which are not based on choice -- such as a :class:`CharField` --
but it is recommended to use a :class:`ChoiceField`-based field when the but it is recommended to use a :class:`ChoiceField`-based field when the
choices are inherent to the model and not just the representational widget. choices are inherent to the model and not just the representational widget.
Customizing widget instances Customizing widget instances
---------------------------- ============================
When Django renders a widget as HTML, it only renders very minimal markup - When Django renders a widget as HTML, it only renders very minimal markup -
Django doesn't add class names, or any other widget-specific attributes. This Django doesn't add class names, or any other widget-specific attributes. This
@ -116,7 +113,7 @@ There are two ways to customize widgets: :ref:`per widget instance
.. _styling-widget-instances: .. _styling-widget-instances:
Styling widget instances Styling widget instances
^^^^^^^^^^^^^^^^^^^^^^^^ ------------------------
If you want to make one widget instance look different from another, you will If you want to make one widget instance look different from another, you will
need to specify additional attributes at the time when the widget object is need to specify additional attributes at the time when the widget object is
@ -167,7 +164,7 @@ You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See
.. _styling-widget-classes: .. _styling-widget-classes:
Styling widget classes Styling widget classes
^^^^^^^^^^^^^^^^^^^^^^ ----------------------
With widgets, it is possible to add assets (``css`` and ``javascript``) With widgets, it is possible to add assets (``css`` and ``javascript``)
and more deeply customize their appearance and behavior. and more deeply customize their appearance and behavior.
@ -181,13 +178,16 @@ detail in the :doc:`Form Assets </topics/forms/media>` topic guide.
.. _base-widget-classes: .. _base-widget-classes:
Base Widget classes Base widget classes
------------------- ===================
Base widget classes :class:`Widget` and :class:`MultiWidget` are subclassed by Base widget classes :class:`Widget` and :class:`MultiWidget` are subclassed by
all the :ref:`built-in widgets <built-in widgets>` and may serve as a all the :ref:`built-in widgets <built-in widgets>` and may serve as a
foundation for custom widgets. foundation for custom widgets.
``Widget``
----------
.. class:: Widget(attrs=None) .. class:: Widget(attrs=None)
This abstract class cannot be rendered, but provides the basic attribute This abstract class cannot be rendered, but provides the basic attribute
@ -257,6 +257,9 @@ foundation for custom widgets.
customize it and add expensive processing, you should implement some customize it and add expensive processing, you should implement some
caching mechanism yourself. caching mechanism yourself.
``MultiWidget``
---------------
.. class:: MultiWidget(widgets, attrs=None) .. class:: MultiWidget(widgets, attrs=None)
A widget that is composed of multiple widgets. A widget that is composed of multiple widgets.
@ -410,7 +413,7 @@ foundation for custom widgets.
.. _built-in widgets: .. _built-in widgets:
Built-in widgets Built-in widgets
---------------- ================
Django provides a representation of all the basic HTML widgets, plus some Django provides a representation of all the basic HTML widgets, plus some
commonly used groups of widgets in the ``django.forms.widgets`` module, commonly used groups of widgets in the ``django.forms.widgets`` module,
@ -421,7 +424,7 @@ and :ref:`handling of multi-valued input <composite-widgets>`.
.. _text-widgets: .. _text-widgets:
Widgets handling input of text Widgets handling input of text
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ------------------------------
These widgets make use of the HTML elements ``input`` and ``textarea``. These widgets make use of the HTML elements ``input`` and ``textarea``.
@ -496,7 +499,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
If no ``format`` argument is provided, the default format is the first If no ``format`` argument is provided, the default format is the first
format found in :setting:`DATE_INPUT_FORMATS` and respects format found in :setting:`DATE_INPUT_FORMATS` and respects
:ref:`format-localization`. :doc:`/topics/i18n/formatting`.
``DateTimeInput`` ``DateTimeInput``
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
@ -513,7 +516,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
If no ``format`` argument is provided, the default format is the first If no ``format`` argument is provided, the default format is the first
format found in :setting:`DATETIME_INPUT_FORMATS` and respects format found in :setting:`DATETIME_INPUT_FORMATS` and respects
:ref:`format-localization`. :doc:`/topics/i18n/formatting`.
By default, the microseconds part of the time value is always set to ``0``. By default, the microseconds part of the time value is always set to ``0``.
If microseconds are required, use a subclass with the If microseconds are required, use a subclass with the
@ -534,7 +537,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
If no ``format`` argument is provided, the default format is the first If no ``format`` argument is provided, the default format is the first
format found in :setting:`TIME_INPUT_FORMATS` and respects format found in :setting:`TIME_INPUT_FORMATS` and respects
:ref:`format-localization`. :doc:`/topics/i18n/formatting`.
For the treatment of microseconds, see :class:`DateTimeInput`. For the treatment of microseconds, see :class:`DateTimeInput`.
@ -548,7 +551,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``.
.. _selector-widgets: .. _selector-widgets:
Selector and checkbox widgets Selector and checkbox widgets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -----------------------------
``CheckboxInput`` ``CheckboxInput``
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
@ -712,7 +715,7 @@ When looping over the checkboxes, the ``label`` and ``input`` tags include
.. _file-upload-widgets: .. _file-upload-widgets:
File upload widgets File upload widgets
^^^^^^^^^^^^^^^^^^^ -------------------
``FileInput`` ``FileInput``
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -733,7 +736,7 @@ File upload widgets
.. _composite-widgets: .. _composite-widgets:
Composite widgets Composite widgets
^^^^^^^^^^^^^^^^^ -----------------
``MultipleHiddenInput`` ``MultipleHiddenInput``
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~

18
docs/ref/models/database-functions.txt
View File

@ -24,7 +24,7 @@ allows the field to have two "empty values", but it's important for the
``Coalesce`` example below. ``Coalesce`` example below.
Coalesce Coalesce
-------- ========
.. class:: Coalesce(*expressions, **extra) .. class:: Coalesce(*expressions, **extra)
@ -65,7 +65,7 @@ Usage examples::
>>> Coalesce('updated', now_sql) >>> Coalesce('updated', now_sql)
Concat Concat
------ ======
.. class:: Concat(*expressions, **extra) .. class:: Concat(*expressions, **extra)
@ -92,7 +92,7 @@ Usage example::
Margaret Smith (Maggie) Margaret Smith (Maggie)
Greatest Greatest
-------- ========
.. class:: Greatest(*expressions, **extra) .. class:: Greatest(*expressions, **extra)
@ -136,7 +136,7 @@ and ``comment.modified``.
a sensible minimum value to provide as a default. a sensible minimum value to provide as a default.
Least Least
----- =====
.. class:: Least(*expressions, **extra) .. class:: Least(*expressions, **extra)
@ -160,7 +160,7 @@ will result in a database error.
a sensible maximum value to provide as a default. a sensible maximum value to provide as a default.
Length Length
------ ======
.. class:: Length(expression, **extra) .. class:: Length(expression, **extra)
@ -191,7 +191,7 @@ It can also be registered as a transform. For example::
The ability to register the function as a transform was added. The ability to register the function as a transform was added.
Lower Lower
------ =====
.. class:: Lower(expression, **extra) .. class:: Lower(expression, **extra)
@ -213,7 +213,7 @@ Usage example::
The ability to register the function as a transform was added. The ability to register the function as a transform was added.
Now Now
--- ===
.. class:: Now() .. class:: Now()
@ -236,7 +236,7 @@ Usage example::
timestamp, use :class:`django.contrib.postgres.functions.TransactionNow`. timestamp, use :class:`django.contrib.postgres.functions.TransactionNow`.
Substr Substr
------ ======
.. class:: Substr(expression, pos, length=None, **extra) .. class:: Substr(expression, pos, length=None, **extra)
@ -255,7 +255,7 @@ Usage example::
marga marga
Upper Upper
------ =====
.. class:: Upper(expression, **extra) .. class:: Upper(expression, **extra)

8
docs/ref/models/lookups.txt
View File

@ -31,7 +31,7 @@ A lookup expression consists of three parts:
.. _lookup-registration-api: .. _lookup-registration-api:
Registration API Registration API
~~~~~~~~~~~~~~~~ ================
Django uses :class:`~lookups.RegisterLookupMixin` to give a class the interface to Django uses :class:`~lookups.RegisterLookupMixin` to give a class the interface to
register lookups on itself. The two prominent examples are register lookups on itself. The two prominent examples are
@ -75,7 +75,7 @@ follow this API.
.. _query-expression: .. _query-expression:
The Query Expression API The Query Expression API
~~~~~~~~~~~~~~~~~~~~~~~~ ========================
The query expression API is a common set of methods that classes define to be The query expression API is a common set of methods that classes define to be
usable in query expressions to translate themselves into SQL expressions. Direct usable in query expressions to translate themselves into SQL expressions. Direct
@ -118,7 +118,7 @@ following methods:
be a :class:`~django.db.models.Field` instance. be a :class:`~django.db.models.Field` instance.
Transform reference Transform reference
~~~~~~~~~~~~~~~~~~~ ===================
.. class:: Transform .. class:: Transform
@ -163,7 +163,7 @@ Transform reference
its ``lhs.output_field``. its ``lhs.output_field``.
Lookup reference Lookup reference
~~~~~~~~~~~~~~~~ ================
.. class:: Lookup .. class:: Lookup

4
docs/ref/models/meta.txt
View File

@ -24,7 +24,7 @@ Field access API
================ ================
Retrieving a single field instance of a model by name Retrieving a single field instance of a model by name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------------------
.. method:: Options.get_field(field_name) .. method:: Options.get_field(field_name)
@ -62,7 +62,7 @@ Retrieving a single field instance of a model by name
FieldDoesNotExist: User has no field named 'does_not_exist' FieldDoesNotExist: User has no field named 'does_not_exist'
Retrieving all field instances of a model Retrieving all field instances of a model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------
.. method:: Options.get_fields(include_parents=True, include_hidden=False) .. method:: Options.get_fields(include_parents=True, include_hidden=False)

2
docs/ref/models/relations.txt
View File

@ -178,7 +178,7 @@ Related objects reference
related manager's methods are disabled. related manager's methods are disabled.
Direct Assignment Direct Assignment
----------------- =================
A related object set can be replaced in bulk with one operation by assigning a A related object set can be replaced in bulk with one operation by assigning a
new iterable of objects to it:: new iterable of objects to it::

212
docs/ref/templates/builtins.txt
View File

@ -10,14 +10,14 @@ documentation for any custom tags or filters installed.
.. _ref-templates-builtins-tags: .. _ref-templates-builtins-tags:
Built-in tag reference Built-in tag reference
---------------------- ======================
.. highlight:: html+django .. highlight:: html+django
.. templatetag:: autoescape .. templatetag:: autoescape
autoescape autoescape
^^^^^^^^^^ ----------
Controls the current auto-escaping behavior. This tag takes either ``on`` or Controls the current auto-escaping behavior. This tag takes either ``on`` or
``off`` as an argument and that determines whether auto-escaping is in effect ``off`` as an argument and that determines whether auto-escaping is in effect
@ -41,7 +41,7 @@ Sample usage::
.. templatetag:: block .. templatetag:: block
block block
^^^^^ -----
Defines a block that can be overridden by child templates. See Defines a block that can be overridden by child templates. See
:ref:`Template inheritance <template-inheritance>` for more information. :ref:`Template inheritance <template-inheritance>` for more information.
@ -49,7 +49,7 @@ Defines a block that can be overridden by child templates. See
.. templatetag:: comment .. templatetag:: comment
comment comment
^^^^^^^ -------
Ignores everything between ``{% comment %}`` and ``{% endcomment %}``. Ignores everything between ``{% comment %}`` and ``{% endcomment %}``.
An optional note may be inserted in the first tag. For example, this is An optional note may be inserted in the first tag. For example, this is
@ -67,7 +67,7 @@ Sample usage::
.. templatetag:: csrf_token .. templatetag:: csrf_token
csrf_token csrf_token
^^^^^^^^^^ ----------
This tag is used for CSRF protection, as described in the documentation for This tag is used for CSRF protection, as described in the documentation for
:doc:`Cross Site Request Forgeries </ref/csrf>`. :doc:`Cross Site Request Forgeries </ref/csrf>`.
@ -75,7 +75,7 @@ This tag is used for CSRF protection, as described in the documentation for
.. templatetag:: cycle .. templatetag:: cycle
cycle cycle
^^^^^ -----
Produces one of its arguments each time this tag is encountered. The first Produces one of its arguments each time this tag is encountered. The first
argument is produced on the first encounter, the second argument on the second argument is produced on the first encounter, the second argument on the second
@ -188,7 +188,7 @@ call to ``{% cycle %}`` doesn't specify ``silent``::
.. templatetag:: debug .. templatetag:: debug
debug debug
^^^^^ -----
Outputs a whole load of debugging information, including the current context Outputs a whole load of debugging information, including the current context
and imported modules. and imported modules.
@ -196,7 +196,7 @@ and imported modules.
.. templatetag:: extends .. templatetag:: extends
extends extends
^^^^^^^ -------
Signals that this template extends a parent template. Signals that this template extends a parent template.
@ -215,7 +215,7 @@ See :ref:`template-inheritance` for more information.
.. templatetag:: filter .. templatetag:: filter
filter filter
^^^^^^ ------
Filters the contents of the block through one or more filters. Multiple Filters the contents of the block through one or more filters. Multiple
filters can be specified with pipes and filters can have arguments, just as filters can be specified with pipes and filters can have arguments, just as
@ -239,7 +239,7 @@ Sample usage::
.. templatetag:: firstof .. templatetag:: firstof
firstof firstof
^^^^^^^ -------
Outputs the first argument variable that is not ``False``. Outputs nothing if Outputs the first argument variable that is not ``False``. Outputs nothing if
all the passed variables are ``False``. all the passed variables are ``False``.
@ -283,7 +283,7 @@ output inside a variable.
.. templatetag:: for .. templatetag:: for
for for
^^^ ---
Loops over each item in an array, making the item available in a context Loops over each item in an array, making the item available in a context
variable. For example, to display a list of athletes provided in variable. For example, to display a list of athletes provided in
@ -341,7 +341,7 @@ Variable Description
========================== =============================================== ========================== ===============================================
for ... empty for ... empty
^^^^^^^^^^^^^ -------------
The ``for`` tag can take an optional ``{% empty %}`` clause whose text is The ``for`` tag can take an optional ``{% empty %}`` clause whose text is
displayed if the given array is empty or could not be found:: displayed if the given array is empty or could not be found::
@ -370,7 +370,7 @@ than -- the following::
.. templatetag:: if .. templatetag:: if
if if
^^ --
The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e. The ``{% if %}`` tag evaluates a variable, and if that variable is "true" (i.e.
exists, is not empty, and is not a false boolean value) the contents of the exists, is not empty, and is not a false boolean value) the contents of the
@ -392,7 +392,7 @@ clauses, as well as an ``{% else %}`` clause that will be displayed if all
previous conditions fail. These clauses are optional. previous conditions fail. These clauses are optional.
Boolean operators Boolean operators
""""""""""""""""" ~~~~~~~~~~~~~~~~~
:ttag:`if` tags may use ``and``, ``or`` or ``not`` to test a number of :ttag:`if` tags may use ``and``, ``or`` or ``not`` to test a number of
variables or to negate a given variable:: variables or to negate a given variable::
@ -435,7 +435,7 @@ them to indicate precedence, you should use nested :ttag:`if` tags.
``<=``, ``>=`` and ``in`` which work as follows: ``<=``, ``>=`` and ``in`` which work as follows:
``==`` operator ``==`` operator
~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^
Equality. Example:: Equality. Example::
@ -444,7 +444,7 @@ Equality. Example::
{% endif %} {% endif %}
``!=`` operator ``!=`` operator
~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^
Inequality. Example:: Inequality. Example::
@ -454,7 +454,7 @@ Inequality. Example::
{% endif %} {% endif %}
``<`` operator ``<`` operator
~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^
Less than. Example:: Less than. Example::
@ -463,7 +463,7 @@ Less than. Example::
{% endif %} {% endif %}
``>`` operator ``>`` operator
~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^
Greater than. Example:: Greater than. Example::
@ -472,7 +472,7 @@ Greater than. Example::
{% endif %} {% endif %}
``<=`` operator ``<=`` operator
~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^
Less than or equal to. Example:: Less than or equal to. Example::
@ -481,7 +481,7 @@ Less than or equal to. Example::
{% endif %} {% endif %}
``>=`` operator ``>=`` operator
~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^
Greater than or equal to. Example:: Greater than or equal to. Example::
@ -490,7 +490,7 @@ Greater than or equal to. Example::
{% endif %} {% endif %}
``in`` operator ``in`` operator
~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^
Contained within. This operator is supported by many Python containers to test Contained within. This operator is supported by many Python containers to test
whether the given value is in the container. The following are some examples whether the given value is in the container. The following are some examples
@ -511,7 +511,7 @@ of how ``x in y`` will be interpreted::
{% endif %} {% endif %}
``not in`` operator ``not in`` operator
~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^
Not contained within. This is the negation of the ``in`` operator. Not contained within. This is the negation of the ``in`` operator.
@ -525,7 +525,7 @@ you should use::
{% if a > b and b > c %} {% if a > b and b > c %}
Filters Filters
""""""" ~~~~~~~
You can also use filters in the :ttag:`if` expression. For example:: You can also use filters in the :ttag:`if` expression. For example::
@ -534,7 +534,7 @@ You can also use filters in the :ttag:`if` expression. For example::
{% endif %} {% endif %}
Complex expressions Complex expressions
""""""""""""""""""" ~~~~~~~~~~~~~~~~~~~
All of the above can be combined to form complex expressions. For such All of the above can be combined to form complex expressions. For such
expressions, it can be important to know how the operators are grouped when the expressions, it can be important to know how the operators are grouped when the
@ -563,7 +563,7 @@ Sometimes that is better for clarity anyway, for the sake of those who do not
know the precedence rules. know the precedence rules.
``ifequal`` and ``ifnotequal`` ``ifequal`` and ``ifnotequal``
"""""""""""""""""""""""""""""" ------------------------------
``{% ifequal a b %} ... {% endifequal %}`` is an obsolete way to write ``{% ifequal a b %} ... {% endifequal %}`` is an obsolete way to write
``{% if a == b %} ... {% endif %}``. Likewise, ``{% ifnotequal a b %} ... ``{% if a == b %} ... {% endif %}``. Likewise, ``{% ifnotequal a b %} ...
@ -573,7 +573,7 @@ The ``ifequal`` and ``ifnotequal`` tags will be deprecated in a future release.
.. templatetag:: ifchanged .. templatetag:: ifchanged
ifchanged ifchanged
^^^^^^^^^ ---------
Check if a value has changed from the last iteration of a loop. Check if a value has changed from the last iteration of a loop.
@ -618,7 +618,7 @@ will be displayed if the value has not changed::
.. templatetag:: include .. templatetag:: include
include include
^^^^^^^ -------
Loads a template and renders it with the current context. This is a way of Loads a template and renders it with the current context. This is a way of
"including" other templates within a template. "including" other templates within a template.
@ -691,7 +691,7 @@ and returns an empty string.
.. templatetag:: load .. templatetag:: load
load load
^^^^ ----
Loads a custom template tag set. Loads a custom template tag set.
@ -713,7 +713,7 @@ more information.
.. templatetag:: lorem .. templatetag:: lorem
lorem lorem
^^^^^ -----
Displays random "lorem ipsum" Latin text. This is useful for providing sample Displays random "lorem ipsum" Latin text. This is useful for providing sample
data in templates. data in templates.
@ -747,7 +747,7 @@ Examples:
.. templatetag:: now .. templatetag:: now
now now
^^^ ---
Displays the current date and/or time, using a format according to the given Displays the current date and/or time, using a format according to the given
string. Such string can contain format specifiers characters as described string. Such string can contain format specifiers characters as described
@ -772,7 +772,7 @@ This would display as "It is the 4th of September".
:setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`, :setting:`DATE_FORMAT`, :setting:`DATETIME_FORMAT`,
:setting:`SHORT_DATE_FORMAT` or :setting:`SHORT_DATETIME_FORMAT`. :setting:`SHORT_DATE_FORMAT` or :setting:`SHORT_DATETIME_FORMAT`.
The predefined formats may vary depending on the current locale and The predefined formats may vary depending on the current locale and
if :ref:`format-localization` is enabled, e.g.:: if :doc:`/topics/i18n/formatting` is enabled, e.g.::
It is {% now "SHORT_DATETIME_FORMAT" %} It is {% now "SHORT_DATETIME_FORMAT" %}
@ -786,7 +786,7 @@ output (as a string) inside a variable. This is useful if you want to use
.. templatetag:: regroup .. templatetag:: regroup
regroup regroup
^^^^^^^ -------
Regroups a list of alike objects by a common attribute. Regroups a list of alike objects by a common attribute.
@ -900,7 +900,7 @@ Another solution is to sort the data in the template using the
{% regroup cities|dictsort:"country" by country as country_list %} {% regroup cities|dictsort:"country" by country as country_list %}
Grouping on other properties Grouping on other properties
"""""""""""""""""""""""""""" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Any valid template lookup is a legal grouping attribute for the regroup Any valid template lookup is a legal grouping attribute for the regroup
tag, including methods, attributes, dictionary keys and list items. For tag, including methods, attributes, dictionary keys and list items. For
@ -922,7 +922,7 @@ attribute, allowing you to group on the display string rather than the
.. templatetag:: spaceless .. templatetag:: spaceless
spaceless spaceless
^^^^^^^^^ ---------
Removes whitespace between HTML tags. This includes tab Removes whitespace between HTML tags. This includes tab
characters and newlines. characters and newlines.
@ -951,7 +951,7 @@ this example, the space around ``Hello`` won't be stripped::
.. templatetag:: templatetag .. templatetag:: templatetag
templatetag templatetag
^^^^^^^^^^^ -----------
Outputs one of the syntax characters used to compose template tags. Outputs one of the syntax characters used to compose template tags.
@ -980,7 +980,7 @@ Sample usage::
.. templatetag:: url .. templatetag:: url
url url
^^^ ---
Returns an absolute path reference (a URL without the domain name) matching a Returns an absolute path reference (a URL without the domain name) matching a
given view and optional parameters. Any special characters in the resulting given view and optional parameters. Any special characters in the resulting
@ -1061,7 +1061,7 @@ by the context as to the current application.
.. templatetag:: verbatim .. templatetag:: verbatim
verbatim verbatim
^^^^^^^^ --------
Stops the template engine from rendering the contents of this block tag. Stops the template engine from rendering the contents of this block tag.
@ -1082,7 +1082,7 @@ You can also designate a specific closing tag, allowing the use of
.. templatetag:: widthratio .. templatetag:: widthratio
widthratio widthratio
^^^^^^^^^^ ----------
For creating bar charts and such, this tag calculates the ratio of a given For creating bar charts and such, this tag calculates the ratio of a given
value to a maximum value, and then applies that ratio to a constant. value to a maximum value, and then applies that ratio to a constant.
@ -1105,7 +1105,7 @@ variable. It can be useful, for instance, in a :ttag:`blocktrans` like this::
.. templatetag:: with .. templatetag:: with
with with
^^^^ ----
Caches a complex variable under a simpler name. This is useful when accessing Caches a complex variable under a simpler name. This is useful when accessing
an "expensive" method (e.g., one that hits the database) multiple times. an "expensive" method (e.g., one that hits the database) multiple times.
@ -1131,12 +1131,12 @@ You can assign more than one context variable::
.. _ref-templates-builtins-filters: .. _ref-templates-builtins-filters:
Built-in filter reference Built-in filter reference
------------------------- =========================
.. templatefilter:: add .. templatefilter:: add
add add
^^^ ---
Adds the argument to the value. Adds the argument to the value.
@ -1166,7 +1166,7 @@ output will be ``[1, 2, 3, 4, 5, 6]``.
.. templatefilter:: addslashes .. templatefilter:: addslashes
addslashes addslashes
^^^^^^^^^^ ----------
Adds slashes before quotes. Useful for escaping strings in CSV, for example. Adds slashes before quotes. Useful for escaping strings in CSV, for example.
@ -1180,7 +1180,7 @@ If ``value`` is ``"I'm using Django"``, the output will be
.. templatefilter:: capfirst .. templatefilter:: capfirst
capfirst capfirst
^^^^^^^^ --------
Capitalizes the first character of the value. If the first character is not Capitalizes the first character of the value. If the first character is not
a letter, this filter has no effect. a letter, this filter has no effect.
@ -1194,7 +1194,7 @@ If ``value`` is ``"django"``, the output will be ``"Django"``.
.. templatefilter:: center .. templatefilter:: center
center center
^^^^^^ ------
Centers the value in a field of a given width. Centers the value in a field of a given width.
@ -1207,7 +1207,7 @@ If ``value`` is ``"Django"``, the output will be ``" Django "``.
.. templatefilter:: cut .. templatefilter:: cut
cut cut
^^^ ---
Removes all values of arg from the given string. Removes all values of arg from the given string.
@ -1221,7 +1221,7 @@ If ``value`` is ``"String with spaces"``, the output will be
.. templatefilter:: date .. templatefilter:: date
date date
^^^^ ----
Formats a date according to the given format. Formats a date according to the given format.
@ -1350,7 +1350,7 @@ representation of a ``datetime`` value. E.g.::
.. templatefilter:: default .. templatefilter:: default
default default
^^^^^^^ -------
If value evaluates to ``False``, uses the given default. Otherwise, uses the If value evaluates to ``False``, uses the given default. Otherwise, uses the
value. value.
@ -1364,7 +1364,7 @@ If ``value`` is ``""`` (the empty string), the output will be ``nothing``.
.. templatefilter:: default_if_none .. templatefilter:: default_if_none
default_if_none default_if_none
^^^^^^^^^^^^^^^ ---------------
If (and only if) value is ``None``, uses the given default. Otherwise, uses the If (and only if) value is ``None``, uses the given default. Otherwise, uses the
value. value.
@ -1381,7 +1381,7 @@ If ``value`` is ``None``, the output will be the string ``"nothing"``.
.. templatefilter:: dictsort .. templatefilter:: dictsort
dictsort dictsort
^^^^^^^^ --------
Takes a list of dictionaries and returns that list sorted by the key given in Takes a list of dictionaries and returns that list sorted by the key given in
the argument. the argument.
@ -1435,7 +1435,7 @@ then the output would be::
.. templatefilter:: dictsortreversed .. templatefilter:: dictsortreversed
dictsortreversed dictsortreversed
^^^^^^^^^^^^^^^^ ----------------
Takes a list of dictionaries and returns that list sorted in reverse order by Takes a list of dictionaries and returns that list sorted in reverse order by
the key given in the argument. This works exactly the same as the above filter, the key given in the argument. This works exactly the same as the above filter,
@ -1444,7 +1444,7 @@ but the returned value will be in reverse order.
.. templatefilter:: divisibleby .. templatefilter:: divisibleby
divisibleby divisibleby
^^^^^^^^^^^ -----------
Returns ``True`` if the value is divisible by the argument. Returns ``True`` if the value is divisible by the argument.
@ -1457,7 +1457,7 @@ If ``value`` is ``21``, the output would be ``True``.
.. templatefilter:: escape .. templatefilter:: escape
escape escape
^^^^^^ ------
Escapes a string's HTML. Specifically, it makes these replacements: Escapes a string's HTML. Specifically, it makes these replacements:
@ -1486,7 +1486,7 @@ For example, you can apply ``escape`` to fields when :ttag:`autoescape` is off::
.. templatefilter:: escapejs .. templatefilter:: escapejs
escapejs escapejs
^^^^^^^^ --------
Escapes characters for use in JavaScript strings. This does *not* make the Escapes characters for use in JavaScript strings. This does *not* make the
string safe for use in HTML, but does protect you from syntax errors when using string safe for use in HTML, but does protect you from syntax errors when using
@ -1502,7 +1502,7 @@ the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u00
.. templatefilter:: filesizeformat .. templatefilter:: filesizeformat
filesizeformat filesizeformat
^^^^^^^^^^^^^^ --------------
Formats the value like a 'human-readable' file size (i.e. ``'13 KB'``, Formats the value like a 'human-readable' file size (i.e. ``'13 KB'``,
``'4.1 MB'``, ``'102 bytes'``, etc.). ``'4.1 MB'``, ``'102 bytes'``, etc.).
@ -1524,7 +1524,7 @@ If ``value`` is 123456789, the output would be ``117.7 MB``.
.. templatefilter:: first .. templatefilter:: first
first first
^^^^^ -----
Returns the first item in a list. Returns the first item in a list.
@ -1537,7 +1537,7 @@ If ``value`` is the list ``['a', 'b', 'c']``, the output will be ``'a'``.
.. templatefilter:: floatformat .. templatefilter:: floatformat
floatformat floatformat
^^^^^^^^^^^ -----------
When used without an argument, rounds a floating-point number to one decimal When used without an argument, rounds a floating-point number to one decimal
place -- but only if there's a decimal part to be displayed. For example: place -- but only if there's a decimal part to be displayed. For example:
@ -1590,7 +1590,7 @@ with an argument of ``-1``.
.. templatefilter:: force_escape .. templatefilter:: force_escape
force_escape force_escape
^^^^^^^^^^^^ ------------
Applies HTML escaping to a string (see the :tfilter:`escape` filter for Applies HTML escaping to a string (see the :tfilter:`escape` filter for
details). This filter is applied *immediately* and returns a new, escaped details). This filter is applied *immediately* and returns a new, escaped
@ -1608,7 +1608,7 @@ the :tfilter:`linebreaks` filter::
.. templatefilter:: get_digit .. templatefilter:: get_digit
get_digit get_digit
^^^^^^^^^ ---------
Given a whole number, returns the requested digit, where 1 is the right-most Given a whole number, returns the requested digit, where 1 is the right-most
digit, 2 is the second-right-most digit, etc. Returns the original value for digit, 2 is the second-right-most digit, etc. Returns the original value for
@ -1624,7 +1624,7 @@ If ``value`` is ``123456789``, the output will be ``8``.
.. templatefilter:: iriencode .. templatefilter:: iriencode
iriencode iriencode
^^^^^^^^^ ---------
Converts an IRI (Internationalized Resource Identifier) to a string that is Converts an IRI (Internationalized Resource Identifier) to a string that is
suitable for including in a URL. This is necessary if you're trying to use suitable for including in a URL. This is necessary if you're trying to use
@ -1642,7 +1642,7 @@ If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&amp;me=2"``.
.. templatefilter:: join .. templatefilter:: join
join join
^^^^ ----
Joins a list with a string, like Python's ``str.join(list)`` Joins a list with a string, like Python's ``str.join(list)``
@ -1656,7 +1656,7 @@ If ``value`` is the list ``['a', 'b', 'c']``, the output will be the string
.. templatefilter:: last .. templatefilter:: last
last last
^^^^ ----
Returns the last item in a list. Returns the last item in a list.
@ -1670,7 +1670,7 @@ string ``"d"``.
.. templatefilter:: length .. templatefilter:: length
length length
^^^^^^ ------
Returns the length of the value. This works for both strings and lists. Returns the length of the value. This works for both strings and lists.
@ -1686,7 +1686,7 @@ The filter returns ``0`` for an undefined variable.
.. templatefilter:: length_is .. templatefilter:: length_is
length_is length_is
^^^^^^^^^ ---------
Returns ``True`` if the value's length is the argument, or ``False`` otherwise. Returns ``True`` if the value's length is the argument, or ``False`` otherwise.
@ -1700,7 +1700,7 @@ If ``value`` is ``['a', 'b', 'c', 'd']`` or ``"abcd"``, the output will be
.. templatefilter:: linebreaks .. templatefilter:: linebreaks
linebreaks linebreaks
^^^^^^^^^^ ----------
Replaces line breaks in plain text with appropriate HTML; a single Replaces line breaks in plain text with appropriate HTML; a single
newline becomes an HTML line break (``<br />``) and a new line newline becomes an HTML line break (``<br />``) and a new line
@ -1716,7 +1716,7 @@ slug</p>``.
.. templatefilter:: linebreaksbr .. templatefilter:: linebreaksbr
linebreaksbr linebreaksbr
^^^^^^^^^^^^ ------------
Converts all newlines in a piece of plain text to HTML line breaks Converts all newlines in a piece of plain text to HTML line breaks
(``<br />``). (``<br />``).
@ -1731,7 +1731,7 @@ slug``.
.. templatefilter:: linenumbers .. templatefilter:: linenumbers
linenumbers linenumbers
^^^^^^^^^^^ -----------
Displays text with line numbers. Displays text with line numbers.
@ -1754,7 +1754,7 @@ the output will be::
.. templatefilter:: ljust .. templatefilter:: ljust
ljust ljust
^^^^^ -----
Left-aligns the value in a field of a given width. Left-aligns the value in a field of a given width.
@ -1769,7 +1769,7 @@ If ``value`` is ``Django``, the output will be ``"Django "``.
.. templatefilter:: lower .. templatefilter:: lower
lower lower
^^^^^ -----
Converts a string into all lowercase. Converts a string into all lowercase.
@ -1783,7 +1783,7 @@ If ``value`` is ``Totally LOVING this Album!``, the output will be
.. templatefilter:: make_list .. templatefilter:: make_list
make_list make_list
^^^^^^^^^ ---------
Returns the value turned into a list. For a string, it's a list of characters. Returns the value turned into a list. For a string, it's a list of characters.
For an integer, the argument is cast into an unicode string before creating a For an integer, the argument is cast into an unicode string before creating a
@ -1800,7 +1800,7 @@ list ``['1', '2', '3']``.
.. templatefilter:: phone2numeric .. templatefilter:: phone2numeric
phone2numeric phone2numeric
^^^^^^^^^^^^^ -------------
Converts a phone number (possibly containing letters) to its numerical Converts a phone number (possibly containing letters) to its numerical
equivalent. equivalent.
@ -1817,7 +1817,7 @@ If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``.
.. templatefilter:: pluralize .. templatefilter:: pluralize
pluralize pluralize
^^^^^^^^^ ---------
Returns a plural suffix if the value is not 1. By default, this suffix is Returns a plural suffix if the value is not 1. By default, this suffix is
``'s'``. ``'s'``.
@ -1848,14 +1848,14 @@ Example::
.. templatefilter:: pprint .. templatefilter:: pprint
pprint pprint
^^^^^^ ------
A wrapper around :func:`pprint.pprint` -- for debugging, really. A wrapper around :func:`pprint.pprint` -- for debugging, really.
.. templatefilter:: random .. templatefilter:: random
random random
^^^^^^ ------
Returns a random item from the given list. Returns a random item from the given list.
@ -1868,7 +1868,7 @@ If ``value`` is the list ``['a', 'b', 'c', 'd']``, the output could be ``"b"``.
.. templatefilter:: rjust .. templatefilter:: rjust
rjust rjust
^^^^^ -----
Right-aligns the value in a field of a given width. Right-aligns the value in a field of a given width.
@ -1883,7 +1883,7 @@ If ``value`` is ``Django``, the output will be ``" Django"``.
.. templatefilter:: safe .. templatefilter:: safe
safe safe
^^^^ ----
Marks a string as not requiring further HTML escaping prior to output. When Marks a string as not requiring further HTML escaping prior to output. When
autoescaping is off, this filter has no effect. autoescaping is off, this filter has no effect.
@ -1899,7 +1899,7 @@ autoescaping is off, this filter has no effect.
.. templatefilter:: safeseq .. templatefilter:: safeseq
safeseq safeseq
^^^^^^^ -------
Applies the :tfilter:`safe` filter to each element of a sequence. Useful in Applies the :tfilter:`safe` filter to each element of a sequence. Useful in
conjunction with other filters that operate on sequences, such as conjunction with other filters that operate on sequences, such as
@ -1914,7 +1914,7 @@ individual elements of the sequence.
.. templatefilter:: slice .. templatefilter:: slice
slice slice
^^^^^ -----
Returns a slice of the list. Returns a slice of the list.
@ -1931,7 +1931,7 @@ If ``some_list`` is ``['a', 'b', 'c']``, the output will be ``['a', 'b']``.
.. templatefilter:: slugify .. templatefilter:: slugify
slugify slugify
^^^^^^^ -------
Converts to ASCII. Converts spaces to hyphens. Removes characters that aren't Converts to ASCII. Converts spaces to hyphens. Removes characters that aren't
alphanumerics, underscores, or hyphens. Converts to lowercase. Also strips alphanumerics, underscores, or hyphens. Converts to lowercase. Also strips
@ -1946,7 +1946,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.
.. templatefilter:: stringformat .. templatefilter:: stringformat
stringformat stringformat
^^^^^^^^^^^^ ------------
Formats the variable according to the argument, a string formatting specifier. Formats the variable according to the argument, a string formatting specifier.
This specifier uses Python string formatting syntax, with the exception that This specifier uses Python string formatting syntax, with the exception that
@ -1964,7 +1964,7 @@ If ``value`` is ``10``, the output will be ``1.000000E+01``.
.. templatefilter:: striptags .. templatefilter:: striptags
striptags striptags
^^^^^^^^^ ---------
Makes all possible efforts to strip all [X]HTML tags. Makes all possible efforts to strip all [X]HTML tags.
@ -1988,7 +1988,7 @@ output will be ``"Joel is a slug"``.
.. templatefilter:: time .. templatefilter:: time
time time
^^^^ ----
Formats a time according to the given format. Formats a time according to the given format.
@ -2034,7 +2034,7 @@ used, without applying any localization.
.. templatefilter:: timesince .. templatefilter:: timesince
timesince timesince
^^^^^^^^^ ---------
Formats a date as the time since that date (e.g., "4 days, 6 hours"). Formats a date as the time since that date (e.g., "4 days, 6 hours").
@ -2054,7 +2054,7 @@ date that is in the future relative to the comparison point.
.. templatefilter:: timeuntil .. templatefilter:: timeuntil
timeuntil timeuntil
^^^^^^^^^ ---------
Similar to ``timesince``, except that it measures the time from now until the Similar to ``timesince``, except that it measures the time from now until the
given date or datetime. For example, if today is 1 June 2006 and given date or datetime. For example, if today is 1 June 2006 and
@ -2075,7 +2075,7 @@ date that is in the past relative to the comparison point.
.. templatefilter:: title .. templatefilter:: title
title title
^^^^^ -----
Converts a string into titlecase by making words start with an uppercase Converts a string into titlecase by making words start with an uppercase
character and the remaining characters lowercase. This tag makes no effort to character and the remaining characters lowercase. This tag makes no effort to
@ -2090,7 +2090,7 @@ If ``value`` is ``"my FIRST post"``, the output will be ``"My First Post"``.
.. templatefilter:: truncatechars .. templatefilter:: truncatechars
truncatechars truncatechars
^^^^^^^^^^^^^ -------------
Truncates a string if it is longer than the specified number of characters. Truncates a string if it is longer than the specified number of characters.
Truncated strings will end with a translatable ellipsis sequence ("..."). Truncated strings will end with a translatable ellipsis sequence ("...").
@ -2106,7 +2106,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"Joel i..."``.
.. templatefilter:: truncatechars_html .. templatefilter:: truncatechars_html
truncatechars_html truncatechars_html
^^^^^^^^^^^^^^^^^^ ------------------
Similar to :tfilter:`truncatechars`, except that it is aware of HTML tags. Any Similar to :tfilter:`truncatechars`, except that it is aware of HTML tags. Any
tags that are opened in the string and not closed before the truncation point tags that are opened in the string and not closed before the truncation point
@ -2124,7 +2124,7 @@ Newlines in the HTML content will be preserved.
.. templatefilter:: truncatewords .. templatefilter:: truncatewords
truncatewords truncatewords
^^^^^^^^^^^^^ -------------
Truncates a string after a certain number of words. Truncates a string after a certain number of words.
@ -2141,7 +2141,7 @@ Newlines within the string will be removed.
.. templatefilter:: truncatewords_html .. templatefilter:: truncatewords_html
truncatewords_html truncatewords_html
^^^^^^^^^^^^^^^^^^ ------------------
Similar to :tfilter:`truncatewords`, except that it is aware of HTML tags. Any Similar to :tfilter:`truncatewords`, except that it is aware of HTML tags. Any
tags that are opened in the string and not closed before the truncation point, tags that are opened in the string and not closed before the truncation point,
@ -2162,7 +2162,7 @@ Newlines in the HTML content will be preserved.
.. templatefilter:: unordered_list .. templatefilter:: unordered_list
unordered_list unordered_list
^^^^^^^^^^^^^^ --------------
Recursively takes a self-nested list and returns an HTML unordered list -- Recursively takes a self-nested list and returns an HTML unordered list --
WITHOUT opening and closing <ul> tags. WITHOUT opening and closing <ul> tags.
@ -2186,7 +2186,7 @@ contains ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then
.. templatefilter:: upper .. templatefilter:: upper
upper upper
^^^^^ -----
Converts a string into all uppercase. Converts a string into all uppercase.
@ -2199,7 +2199,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"JOEL IS A SLUG"``.
.. templatefilter:: urlencode .. templatefilter:: urlencode
urlencode urlencode
^^^^^^^^^ ---------
Escapes a value for use in a URL. Escapes a value for use in a URL.
@ -2224,7 +2224,7 @@ If ``value`` is ``"https://www.example.org/"``, the output will be
.. templatefilter:: urlize .. templatefilter:: urlize
urlize urlize
^^^^^^ ------
Converts URLs and email addresses in text into clickable links. Converts URLs and email addresses in text into clickable links.
@ -2268,7 +2268,7 @@ Django's built-in :tfilter:`escape` filter. The default value for
.. templatefilter:: urlizetrunc .. templatefilter:: urlizetrunc
urlizetrunc urlizetrunc
^^^^^^^^^^^ -----------
Converts URLs and email addresses into clickable links just like urlize_, but Converts URLs and email addresses into clickable links just like urlize_, but
truncates URLs longer than the given character limit. truncates URLs longer than the given character limit.
@ -2289,7 +2289,7 @@ As with urlize_, this filter should only be applied to plain text.
.. templatefilter:: wordcount .. templatefilter:: wordcount
wordcount wordcount
^^^^^^^^^ ---------
Returns the number of words. Returns the number of words.
@ -2302,7 +2302,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``4``.
.. templatefilter:: wordwrap .. templatefilter:: wordwrap
wordwrap wordwrap
^^^^^^^^ --------
Wraps words at specified line length. Wraps words at specified line length.
@ -2321,7 +2321,7 @@ If ``value`` is ``Joel is a slug``, the output would be::
.. templatefilter:: yesno .. templatefilter:: yesno
yesno yesno
^^^^^ -----
Maps values for ``True``, ``False``, and (optionally) ``None``, to the strings Maps values for ``True``, ``False``, and (optionally) ``None``, to the strings
"yes", "no", "maybe", or a custom mapping passed as a comma-separated list, and "yes", "no", "maybe", or a custom mapping passed as a comma-separated list, and
@ -2343,14 +2343,14 @@ Value Argument Outputs
========== ====================== =========================================== ========== ====================== ===========================================
Internationalization tags and filters Internationalization tags and filters
------------------------------------- =====================================
Django provides template tags and filters to control each aspect of Django provides template tags and filters to control each aspect of
:doc:`internationalization </topics/i18n/index>` in templates. They allow for :doc:`internationalization </topics/i18n/index>` in templates. They allow for
granular control of translations, formatting, and time zone conversions. granular control of translations, formatting, and time zone conversions.
i18n i18n
^^^^ ----
This library allows specifying translatable text in templates. This library allows specifying translatable text in templates.
To enable it, set :setting:`USE_I18N` to ``True``, then load it with To enable it, set :setting:`USE_I18N` to ``True``, then load it with
@ -2359,7 +2359,7 @@ To enable it, set :setting:`USE_I18N` to ``True``, then load it with
See :ref:`specifying-translation-strings-in-template-code`. See :ref:`specifying-translation-strings-in-template-code`.
l10n l10n
^^^^ ----
This library provides control over the localization of values in templates. This library provides control over the localization of values in templates.
You only need to load the library using ``{% load l10n %}``, but you'll often You only need to load the library using ``{% load l10n %}``, but you'll often
@ -2368,7 +2368,7 @@ set :setting:`USE_L10N` to ``True`` so that localization is active by default.
See :ref:`topic-l10n-templates`. See :ref:`topic-l10n-templates`.
tz tz
^^ --
This library provides control over time zone conversions in templates. This library provides control over time zone conversions in templates.
Like ``l10n``, you only need to load the library using ``{% load tz %}``, Like ``l10n``, you only need to load the library using ``{% load tz %}``,
@ -2378,25 +2378,25 @@ to local time happens by default.
See :ref:`time-zones-in-templates`. See :ref:`time-zones-in-templates`.
Other tags and filters libraries Other tags and filters libraries
-------------------------------- ================================
Django comes with a couple of other template-tag libraries that you have to Django comes with a couple of other template-tag libraries that you have to
enable explicitly in your :setting:`INSTALLED_APPS` setting and enable in your enable explicitly in your :setting:`INSTALLED_APPS` setting and enable in your
template with the :ttag:`{% load %}<load>` tag. template with the :ttag:`{% load %}<load>` tag.
django.contrib.humanize django.contrib.humanize
^^^^^^^^^^^^^^^^^^^^^^^ -----------------------
A set of Django template filters useful for adding a "human touch" to data. See A set of Django template filters useful for adding a "human touch" to data. See
:doc:`/ref/contrib/humanize`. :doc:`/ref/contrib/humanize`.
static static
^^^^^^ ------
.. templatetag:: static .. templatetag:: static
static static
"""""" ~~~~~~
To link to static files that are saved in :setting:`STATIC_ROOT` Django ships To link to static files that are saved in :setting:`STATIC_ROOT` Django ships
with a :ttag:`static` template tag. If the :mod:`django.contrib.staticfiles` with a :ttag:`static` template tag. If the :mod:`django.contrib.staticfiles`
@ -2433,7 +2433,7 @@ slightly different call::
.. templatetag:: get_static_prefix .. templatetag:: get_static_prefix
get_static_prefix get_static_prefix
""""""""""""""""" ~~~~~~~~~~~~~~~~~
You should prefer the :ttag:`static` template tag, but if you need more control You should prefer the :ttag:`static` template tag, but if you need more control
over exactly where and how :setting:`STATIC_URL` is injected into the template, over exactly where and how :setting:`STATIC_URL` is injected into the template,
@ -2454,7 +2454,7 @@ the value multiple times::
.. templatetag:: get_media_prefix .. templatetag:: get_media_prefix
get_media_prefix get_media_prefix
"""""""""""""""" ~~~~~~~~~~~~~~~~
Similar to the :ttag:`get_static_prefix`, ``get_media_prefix`` populates a Similar to the :ttag:`get_static_prefix`, ``get_media_prefix`` populates a
template variable with the media prefix :setting:`MEDIA_URL`, e.g.:: template variable with the media prefix :setting:`MEDIA_URL`, e.g.::

8
docs/ref/urlresolvers.txt
View File

@ -11,7 +11,7 @@
to work until Django 2.0. to work until Django 2.0.
reverse() reverse()
--------- =========
If you need to use something similar to the :ttag:`url` template tag in If you need to use something similar to the :ttag:`url` template tag in
your code, Django provides the following function: your code, Django provides the following function:
@ -81,7 +81,7 @@ use for reversing. By default, the root URLconf for the current thread is used.
results. results.
reverse_lazy() reverse_lazy()
-------------- ==============
A lazily evaluated version of `reverse()`_. A lazily evaluated version of `reverse()`_.
@ -101,7 +101,7 @@ URLConf is loaded. Some common cases where this function is necessary are:
signature. signature.
resolve() resolve()
--------- =========
The ``resolve()`` function can be used for resolving URL paths to the The ``resolve()`` function can be used for resolving URL paths to the
corresponding view functions. It has the following signature: corresponding view functions. It has the following signature:
@ -203,7 +203,7 @@ view would raise a ``Http404`` error before redirecting to it::
return response return response
get_script_prefix() get_script_prefix()
------------------- ===================
.. function:: get_script_prefix() .. function:: get_script_prefix()

14
docs/ref/urls.txt
View File

@ -5,7 +5,7 @@
.. module:: django.conf.urls .. module:: django.conf.urls
static() static()
-------- ========
.. function:: static.static(prefix, view=django.views.static.serve, **kwargs) .. function:: static.static(prefix, view=django.views.static.serve, **kwargs)
@ -19,7 +19,7 @@ Helper function to return a URL pattern for serving files in debug mode::
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
url() url()
----- =====
.. function:: url(regex, view, kwargs=None, name=None) .. function:: url(regex, view, kwargs=None, name=None)
@ -37,7 +37,7 @@ See :ref:`Naming URL patterns <naming-url-patterns>` for why the ``name``
parameter is useful. parameter is useful.
include() include()
--------- =========
.. function:: include(module, namespace=None, app_name=None) .. function:: include(module, namespace=None, app_name=None)
include(pattern_list) include(pattern_list)
@ -86,7 +86,7 @@ See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`.
application namespace or remove the instance namespace. application namespace or remove the instance namespace.
handler400 handler400
---------- ==========
.. data:: handler400 .. data:: handler400
@ -102,7 +102,7 @@ See the documentation about :ref:`the 400 (bad request) view
<http_bad_request_view>` for more information. <http_bad_request_view>` for more information.
handler403 handler403
---------- ==========
.. data:: handler403 .. data:: handler403
@ -118,7 +118,7 @@ See the documentation about :ref:`the 403 (HTTP Forbidden) view
<http_forbidden_view>` for more information. <http_forbidden_view>` for more information.
handler404 handler404
---------- ==========
.. data:: handler404 .. data:: handler404
@ -133,7 +133,7 @@ See the documentation about :ref:`the 404 (HTTP Not Found) view
<http_not_found_view>` for more information. <http_not_found_view>` for more information.
handler500 handler500
---------- ==========
.. data:: handler500 .. data:: handler500

2
docs/releases/1.1.3.txt
View File

@ -19,7 +19,7 @@ Backwards incompatible changes
============================== ==============================
Restricted filters in admin interface Restricted filters in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------
The Django administrative interface, django.contrib.admin, supports The Django administrative interface, django.contrib.admin, supports
filtering of displayed lists of objects by fields on the corresponding filtering of displayed lists of objects by fields on the corresponding

2
docs/releases/1.1.4.txt
View File

@ -19,7 +19,7 @@ Backwards incompatible changes
============================== ==============================
CSRF exception for AJAX requests CSRF exception for AJAX requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
Django includes a CSRF-protection mechanism, which makes use of a Django includes a CSRF-protection mechanism, which makes use of a
token inserted into outgoing forms. Middleware then checks for the token inserted into outgoing forms. Middleware then checks for the

74
docs/releases/1.10.txt
View File

@ -27,10 +27,10 @@ What's new in Django 1.10
... ...
Minor features Minor features
~~~~~~~~~~~~~~ --------------
:mod:`django.contrib.admin` :mod:`django.contrib.admin`
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
* For sites running on a subpath, the default :attr:`URL for the "View site" * For sites running on a subpath, the default :attr:`URL for the "View site"
link <django.contrib.admin.AdminSite.site_url>` at the top of each admin page link <django.contrib.admin.AdminSite.site_url>` at the top of each admin page
@ -57,12 +57,12 @@ Minor features
method is now the preferred way of retrieving the change message. method is now the preferred way of retrieving the change message.
:mod:`django.contrib.admindocs` :mod:`django.contrib.admindocs`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ... * ...
:mod:`django.contrib.auth` :mod:`django.contrib.auth`
^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~
* The default iteration count for the PBKDF2 password hasher has been increased * The default iteration count for the PBKDF2 password hasher has been increased
by 25%. This backwards compatible change will not affect users who have by 25%. This backwards compatible change will not affect users who have
@ -77,12 +77,12 @@ Minor features
to allow using it without credentials. to allow using it without credentials.
:mod:`django.contrib.contenttypes` :mod:`django.contrib.contenttypes`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ... * ...
:mod:`django.contrib.gis` :mod:`django.contrib.gis`
^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`Distance lookups <distance-lookups>` now accept expressions as the * :ref:`Distance lookups <distance-lookups>` now accept expressions as the
distance value parameter. distance value parameter.
@ -122,39 +122,39 @@ Minor features
<django.contrib.gis.geos.MultiLineString.closed>` properties. <django.contrib.gis.geos.MultiLineString.closed>` properties.
:mod:`django.contrib.messages` :mod:`django.contrib.messages`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ... * ...
:mod:`django.contrib.postgres` :mod:`django.contrib.postgres`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ... * ...
:mod:`django.contrib.redirects` :mod:`django.contrib.redirects`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ... * ...
:mod:`django.contrib.sessions` :mod:`django.contrib.sessions`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The :djadmin:`clearsessions` management command now removes file-based * The :djadmin:`clearsessions` management command now removes file-based
sessions. sessions.
:mod:`django.contrib.sitemaps` :mod:`django.contrib.sitemaps`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ... * ...
:mod:`django.contrib.sites` :mod:`django.contrib.sites`
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The :class:`~django.contrib.sites.models.Site` model now supports * The :class:`~django.contrib.sites.models.Site` model now supports
:ref:`natural keys <topics-serialization-natural-keys>`. :ref:`natural keys <topics-serialization-natural-keys>`.
:mod:`django.contrib.staticfiles` :mod:`django.contrib.staticfiles`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The :ttag:`static` template tag now uses ``django.contrib.staticfiles`` * The :ttag:`static` template tag now uses ``django.contrib.staticfiles``
if it's in ``INSTALLED_APPS``. This is especially useful for third-party apps if it's in ``INSTALLED_APPS``. This is especially useful for third-party apps
@ -163,61 +163,61 @@ Minor features
not worry about whether or not the ``staticfiles`` app is installed. not worry about whether or not the ``staticfiles`` app is installed.
:mod:`django.contrib.syndication` :mod:`django.contrib.syndication`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ... * ...
Cache Cache
^^^^^ ~~~~~
* The file-based cache backend now uses the highest pickling protocol. * The file-based cache backend now uses the highest pickling protocol.
CSRF CSRF
^^^^ ~~~~
* The default :setting:`CSRF_FAILURE_VIEW`, ``views.csrf.csrf_failure()`` now * The default :setting:`CSRF_FAILURE_VIEW`, ``views.csrf.csrf_failure()`` now
accepts an optional ``template_name`` parameter, defaulting to accepts an optional ``template_name`` parameter, defaulting to
``'403_csrf.html'``, to control the template used to render the page. ``'403_csrf.html'``, to control the template used to render the page.
Database backends Database backends
^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~
* ... * ...
Email Email
^^^^^ ~~~~~
* ... * ...
File Storage File Storage
^^^^^^^^^^^^ ~~~~~~~~~~~~
* ... * ...
File Uploads File Uploads
^^^^^^^^^^^^ ~~~~~~~~~~~~
* ... * ...
Forms Forms
^^^^^ ~~~~~
* Form and widget ``Media`` is now served using * Form and widget ``Media`` is now served using
:mod:`django.contrib.staticfiles` if installed. :mod:`django.contrib.staticfiles` if installed.
Generic Views Generic Views
^^^^^^^^^^^^^ ~~~~~~~~~~~~~
* The :class:`~django.views.generic.base.View` class can now be imported from * The :class:`~django.views.generic.base.View` class can now be imported from
``django.views``. ``django.views``.
Internationalization Internationalization
^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~
* ... * ...
Management Commands Management Commands
^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~
* The new :option:`check --fail-level` option allows specifying the message * The new :option:`check --fail-level` option allows specifying the message
level that will cause the command to exit with a non-zero status. level that will cause the command to exit with a non-zero status.
@ -235,12 +235,12 @@ Management Commands
exit, instead of opening the interactive shell. exit, instead of opening the interactive shell.
Migrations Migrations
^^^^^^^^^^ ~~~~~~~~~~
* Added support for serialization of ``enum.Enum`` objects. * Added support for serialization of ``enum.Enum`` objects.
Models Models
^^^^^^ ~~~~~~
* Reverse foreign keys from proxy models are now propagated to their * Reverse foreign keys from proxy models are now propagated to their
concrete class. The reverse relation attached by a concrete class. The reverse relation attached by a
@ -264,7 +264,7 @@ Models
may be called without any arguments to return all objects in the queryset. may be called without any arguments to return all objects in the queryset.
Requests and Responses Requests and Responses
^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~
* Added ``request.user`` to the debug view. * Added ``request.user`` to the debug view.
@ -274,30 +274,30 @@ Requests and Responses
stream-like object and allow wrapping it with :py:class:`io.TextIOWrapper`. stream-like object and allow wrapping it with :py:class:`io.TextIOWrapper`.
Serialization Serialization
^^^^^^^^^^^^^ ~~~~~~~~~~~~~
* The ``django.core.serializers.json.DjangoJSONEncoder`` now knows how to * The ``django.core.serializers.json.DjangoJSONEncoder`` now knows how to
serialize lazy strings, typically used for translatable content. serialize lazy strings, typically used for translatable content.
Signals Signals
^^^^^^^ ~~~~~~~
* ... * ...
Templates Templates
^^^^^^^^^ ~~~~~~~~~
* Added the ``autoescape`` option to the * Added the ``autoescape`` option to the
:class:`~django.template.backends.django.DjangoTemplates` backend and the :class:`~django.template.backends.django.DjangoTemplates` backend and the
:class:`~django.template.Engine` class. :class:`~django.template.Engine` class.
Tests Tests
^^^^^ ~~~~~
* ... * ...
URLs URLs
^^^^ ~~~~
* An addition in :func:`django.setup()` allows URL resolving that happens * An addition in :func:`django.setup()` allows URL resolving that happens
outside of the request/response cycle (e.g. in management commands and outside of the request/response cycle (e.g. in management commands and
@ -305,7 +305,7 @@ URLs
is set. is set.
Validators Validators
^^^^^^^^^^ ~~~~~~~~~~
* :class:`~django.core.validators.URLValidator` now limits the length of * :class:`~django.core.validators.URLValidator` now limits the length of
domain name labels to 63 characters and the total length of domain domain name labels to 63 characters and the total length of domain
@ -323,7 +323,7 @@ Backwards incompatible changes in 1.10
may appear as a backwards incompatible change. may appear as a backwards incompatible change.
Database backend API Database backend API
~~~~~~~~~~~~~~~~~~~~ --------------------
* ... * ...
@ -471,7 +471,7 @@ Features deprecated in 1.10
=========================== ===========================
Direct assignment to a reverse foreign key or many-to-many relation Direct assignment to a reverse foreign key or many-to-many relation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------------------------------
Instead of assigning related objects using direct assignment:: Instead of assigning related objects using direct assignment::
@ -486,7 +486,7 @@ added in Django 1.9::
This prevents confusion about an assignment resulting in an implicit save. This prevents confusion about an assignment resulting in an implicit save.
:mod:`django.contrib.gis` :mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------
* The ``get_srid()`` and ``set_srid()`` methods of * The ``get_srid()`` and ``set_srid()`` methods of
:class:`~django.contrib.gis.geos.GEOSGeometry` are deprecated in favor :class:`~django.contrib.gis.geos.GEOSGeometry` are deprecated in favor
@ -505,7 +505,7 @@ This prevents confusion about an assignment resulting in an implicit save.
:attr:`~django.contrib.gis.geos.GEOSGeometry.unary_union` property. :attr:`~django.contrib.gis.geos.GEOSGeometry.unary_union` property.
Miscellaneous Miscellaneous
~~~~~~~~~~~~~ -------------
* The ``makemigrations --exit`` option is deprecated in favor of the * The ``makemigrations --exit`` option is deprecated in favor of the
:option:`makemigrations --check` option. :option:`makemigrations --check` option.

2
docs/releases/1.2.4.txt
View File

@ -19,7 +19,7 @@ Backwards incompatible changes
============================== ==============================
Restricted filters in admin interface Restricted filters in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------
The Django administrative interface, django.contrib.admin, supports The Django administrative interface, django.contrib.admin, supports
filtering of displayed lists of objects by fields on the corresponding filtering of displayed lists of objects by fields on the corresponding

8
docs/releases/1.2.5.txt
View File

@ -19,7 +19,7 @@ Backwards incompatible changes
============================== ==============================
CSRF exception for AJAX requests CSRF exception for AJAX requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
Django includes a CSRF-protection mechanism, which makes use of a Django includes a CSRF-protection mechanism, which makes use of a
token inserted into outgoing forms. Middleware then checks for the token inserted into outgoing forms. Middleware then checks for the
@ -68,7 +68,7 @@ documentation for your version of Django, as the exact code necessary
is different for some older versions of Django. is different for some older versions of Django.
FileField no longer deletes files FileField no longer deletes files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------
In earlier Django versions, when a model instance containing a In earlier Django versions, when a model instance containing a
:class:`~django.db.models.FileField` was deleted, :class:`~django.db.models.FileField` was deleted,
@ -82,7 +82,7 @@ yourself (for instance, with a custom management command that can be run
manually or scheduled to run periodically via e.g. cron). manually or scheduled to run periodically via e.g. cron).
Use of custom SQL to load initial data in tests Use of custom SQL to load initial data in tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------------
Django provides a custom SQL hooks as a way to inject hand-crafted SQL Django provides a custom SQL hooks as a way to inject hand-crafted SQL
into the database synchronization process. One of the possible uses into the database synchronization process. One of the possible uses
@ -112,7 +112,7 @@ should either insert it using :ref:`test fixtures
test case. test case.
ModelAdmin.lookup_allowed signature changed ModelAdmin.lookup_allowed signature changed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------
Django 1.2.4 introduced a method ``lookup_allowed`` on ``ModelAdmin``, to cope Django 1.2.4 introduced a method ``lookup_allowed`` on ``ModelAdmin``, to cope
with a security issue (changeset `[15033] with a security issue (changeset `[15033]

14
docs/releases/1.2.txt
View File

@ -309,7 +309,7 @@ Django's :doc:`internationalization framework </topics/i18n/index>` has been exp
with locale-aware formatting and form processing. That means, if enabled, dates with locale-aware formatting and form processing. That means, if enabled, dates
and numbers on templates will be displayed using the format specified for the and numbers on templates will be displayed using the format specified for the
current locale. Django will also use localized formats when parsing data in current locale. Django will also use localized formats when parsing data in
forms. See :ref:`Format localization <format-localization>` for more details. forms. See :doc:`/topics/i18n/formatting` for more details.
``readonly_fields`` in ``ModelAdmin`` ``readonly_fields`` in ``ModelAdmin``
------------------------------------- -------------------------------------
@ -1072,10 +1072,10 @@ to provide localizers the possibility to translate date and time formats. They
were translatable :term:`translation strings <translation string>` that could were translatable :term:`translation strings <translation string>` that could
be recognized because they were all upper case (for example be recognized because they were all upper case (for example
:setting:`DATETIME_FORMAT`, :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT`). :setting:`DATETIME_FORMAT`, :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT`).
They have been deprecated in favor of the new :ref:`Format localization They have been deprecated in favor of the new :doc:`/topics/i18n/formatting`
<format-localization>` infrastructure that allows localizers to specify that infrastructure that allows localizers to specify that information in a
information in a ``formats.py`` file in the corresponding ``formats.py`` file in the corresponding ``django/conf/locale/<locale name>/``
``django/conf/locale/<locale name>/`` directory. directory.
GeoDjango GeoDjango
--------- ---------
@ -1089,7 +1089,7 @@ following sections provide information on the most-popular APIs that
were affected by these changes. were affected by these changes.
``SpatialBackend`` ``SpatialBackend``
^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~
Prior to the creation of the separate spatial backends, the Prior to the creation of the separate spatial backends, the
``django.contrib.gis.db.backend.SpatialBackend`` object was ``django.contrib.gis.db.backend.SpatialBackend`` object was
@ -1117,7 +1117,7 @@ Would need to be changed::
PostGISAdaptor = connection.ops.Adapter PostGISAdaptor = connection.ops.Adapter
``SpatialRefSys`` and ``GeometryColumns`` models ``SpatialRefSys`` and ``GeometryColumns`` models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In previous versions of GeoDjango, :mod:`django.contrib.gis.db.models` In previous versions of GeoDjango, :mod:`django.contrib.gis.db.models`
had ``SpatialRefSys`` and ``GeometryColumns`` models for querying had ``SpatialRefSys`` and ``GeometryColumns`` models for querying

2
docs/releases/1.3.4.txt
View File

@ -7,7 +7,7 @@ Django 1.3.4 release notes
This is the fourth release in the Django 1.3 series. This is the fourth release in the Django 1.3 series.
Host header poisoning Host header poisoning
--------------------- =====================
Some parts of Django -- independent of end-user-written applications -- make Some parts of Django -- independent of end-user-written applications -- make
use of full URLs, including domain name, which are generated from the HTTP Host use of full URLs, including domain name, which are generated from the HTTP Host

4
docs/releases/1.3.5.txt
View File

@ -14,7 +14,7 @@ the other we've chosen to take further steps to tighten up Django's code in
response to independent discovery of potential problems from multiple sources. response to independent discovery of potential problems from multiple sources.
Host header poisoning Host header poisoning
--------------------- =====================
Several earlier Django security releases focused on the issue of poisoning the Several earlier Django security releases focused on the issue of poisoning the
HTTP Host header, causing Django to generate URLs pointing to arbitrary, HTTP Host header, causing Django to generate URLs pointing to arbitrary,
@ -35,7 +35,7 @@ Any deviation from this will now be rejected, raising the exception
:exc:`django.core.exceptions.SuspiciousOperation`. :exc:`django.core.exceptions.SuspiciousOperation`.
Redirect poisoning Redirect poisoning
------------------ ==================
Also following up on a previous issue: in July of this year, we made changes to Also following up on a previous issue: in July of this year, we made changes to
Django's HTTP redirect classes, performing additional validation of the scheme Django's HTTP redirect classes, performing additional validation of the scheme

8
docs/releases/1.3.6.txt
View File

@ -11,7 +11,7 @@ This is the sixth bugfix/security release in the Django 1.3 series.
Host header poisoning Host header poisoning
--------------------- =====================
Some parts of Django -- independent of end-user-written applications -- make Some parts of Django -- independent of end-user-written applications -- make
use of full URLs, including domain name, which are generated from the HTTP Host use of full URLs, including domain name, which are generated from the HTTP Host
@ -36,7 +36,7 @@ This host validation is disabled when ``DEBUG`` is ``True`` or when running test
XML deserialization XML deserialization
------------------- ===================
The XML parser in the Python standard library is vulnerable to a number of The XML parser in the Python standard library is vulnerable to a number of
attacks via external entities and entity expansion. Django uses this parser for attacks via external entities and entity expansion. Django uses this parser for
@ -57,7 +57,7 @@ management command, you will need to ensure they do not contain a DTD.
Formset memory exhaustion Formset memory exhaustion
------------------------- =========================
Previous versions of Django did not validate or limit the form-count data Previous versions of Django did not validate or limit the form-count data
provided by the client in a formset's management form, making it possible to provided by the client in a formset's management form, making it possible to
@ -70,7 +70,7 @@ factory argument).
Admin history view information leakage Admin history view information leakage
-------------------------------------- ======================================
In previous versions of Django, an admin user without change permission on a In previous versions of Django, an admin user without change permission on a
model could still view the unicode representation of instances via their admin model could still view the unicode representation of instances via their admin

84
docs/releases/1.3.txt
View File

@ -68,7 +68,7 @@ What's new in Django 1.3
======================== ========================
Class-based views Class-based views
~~~~~~~~~~~~~~~~~ -----------------
Django 1.3 adds a framework that allows you to use a class as a view. Django 1.3 adds a framework that allows you to use a class as a view.
This means you can compose a view out of a collection of methods that This means you can compose a view out of a collection of methods that
@ -86,7 +86,7 @@ your function-based generic views to class-based
views <https://docs.djangoproject.com/en/1.4/topics/generic-views-migration/>`_. views <https://docs.djangoproject.com/en/1.4/topics/generic-views-migration/>`_.
Logging Logging
~~~~~~~ -------
Django 1.3 adds framework-level support for Python's ``logging`` Django 1.3 adds framework-level support for Python's ``logging``
module. This means you can now easily configure and control logging module. This means you can now easily configure and control logging
@ -97,7 +97,7 @@ handled as a logging activity. See :doc:`the documentation on Django's
logging interface </topics/logging>` for more details. logging interface </topics/logging>` for more details.
Extended static files handling Extended static files handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
Django 1.3 ships with a new contrib app -- Django 1.3 ships with a new contrib app --
``django.contrib.staticfiles`` -- to help developers handle the static ``django.contrib.staticfiles`` -- to help developers handle the static
@ -118,7 +118,7 @@ for more details or learn how to :doc:`manage static files
</howto/static-files/index>`. </howto/static-files/index>`.
unittest2 support unittest2 support
~~~~~~~~~~~~~~~~~ -----------------
Python 2.7 introduced some major changes to the ``unittest`` library, Python 2.7 introduced some major changes to the ``unittest`` library,
adding some extremely useful features. To ensure that every Django adding some extremely useful features. To ensure that every Django
@ -146,7 +146,7 @@ you just won't get any of the nice new unittest2 features.
.. _unittest2: https://pypi.python.org/pypi/unittest2 .. _unittest2: https://pypi.python.org/pypi/unittest2
Transaction context managers Transaction context managers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
Users of Python 2.5 and above may now use transaction management functions as Users of Python 2.5 and above may now use transaction management functions as
`context managers`_. For example:: `context managers`_. For example::
@ -157,7 +157,7 @@ Users of Python 2.5 and above may now use transaction management functions as
.. _context managers: https://docs.python.org/glossary.html#term-context-manager .. _context managers: https://docs.python.org/glossary.html#term-context-manager
Configurable delete-cascade Configurable delete-cascade
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
:class:`~django.db.models.ForeignKey` and :class:`~django.db.models.ForeignKey` and
:class:`~django.db.models.OneToOneField` now accept an :class:`~django.db.models.OneToOneField` now accept an
@ -170,7 +170,7 @@ For more information, see the :attr:`~django.db.models.ForeignKey.on_delete`
documentation. documentation.
Contextual markers and comments for translatable strings Contextual markers and comments for translatable strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------------------
For translation strings with ambiguous meaning, you can now For translation strings with ambiguous meaning, you can now
use the ``pgettext`` function to specify the context of the string. use the ``pgettext`` function to specify the context of the string.
@ -182,7 +182,7 @@ For more information, see :ref:`contextual-markers` and
:ref:`translator-comments`. :ref:`translator-comments`.
Improvements to built-in template tags Improvements to built-in template tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------
A number of improvements have been made to Django's built-in template tags: A number of improvements have been made to Django's built-in template tags:
@ -199,7 +199,7 @@ A number of improvements have been made to Django's built-in template tags:
you to load a single tag or filter from a library. you to load a single tag or filter from a library.
TemplateResponse TemplateResponse
~~~~~~~~~~~~~~~~ ----------------
It can sometimes be beneficial to allow decorators or middleware to It can sometimes be beneficial to allow decorators or middleware to
modify a response *after* it has been constructed by the view. For modify a response *after* it has been constructed by the view. For
@ -220,7 +220,7 @@ For more details, see the :doc:`documentation </ref/template-response>`
on the :class:`~django.template.response.TemplateResponse` class. on the :class:`~django.template.response.TemplateResponse` class.
Caching changes Caching changes
~~~~~~~~~~~~~~~ ---------------
Django 1.3 sees the introduction of several improvements to the Django 1.3 sees the introduction of several improvements to the
Django's caching infrastructure. Django's caching infrastructure.
@ -247,7 +247,7 @@ caching in Django</topics/cache>`.
.. _pylibmc: http://sendapatch.se/projects/pylibmc/ .. _pylibmc: http://sendapatch.se/projects/pylibmc/
Permissions for inactive users Permissions for inactive users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
If you provide a custom auth backend with ``supports_inactive_user`` If you provide a custom auth backend with ``supports_inactive_user``
set to ``True``, an inactive ``User`` instance will check the backend set to ``True``, an inactive ``User`` instance will check the backend
@ -256,14 +256,14 @@ permission handling. See the :doc:`authentication docs </topics/auth/index>`
for more details. for more details.
GeoDjango GeoDjango
~~~~~~~~~ ---------
The GeoDjango test suite is now included when The GeoDjango test suite is now included when
:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py`` :ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``
when using :ref:`spatial database backends <spatial-backends>`. when using :ref:`spatial database backends <spatial-backends>`.
:setting:`MEDIA_URL` and :setting:`STATIC_URL` must end in a slash :setting:`MEDIA_URL` and :setting:`STATIC_URL` must end in a slash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------------------------------
Previously, the :setting:`MEDIA_URL` setting only required a trailing slash if Previously, the :setting:`MEDIA_URL` setting only required a trailing slash if
it contained a suffix beyond the domain name. it contained a suffix beyond the domain name.
@ -279,7 +279,7 @@ In Django 1.4 this same condition will raise ``DeprecationWarning``,
and in Django 1.5 will raise an ``ImproperlyConfigured`` exception. and in Django 1.5 will raise an ``ImproperlyConfigured`` exception.
Everything else Everything else
~~~~~~~~~~~~~~~ ---------------
Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added
lots of big ticket items to Django, like multiple-database support, lots of big ticket items to Django, like multiple-database support,
@ -335,7 +335,7 @@ Backwards-incompatible changes in 1.3
===================================== =====================================
CSRF validation now applies to AJAX requests CSRF validation now applies to AJAX requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------
Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX
requests from CSRF verification; due to `security issues`_ reported to requests from CSRF verification; due to `security issues`_ reported to
@ -347,7 +347,7 @@ AJAX requests.
.. _security issues: https://www.djangoproject.com/weblog/2011/feb/08/security/ .. _security issues: https://www.djangoproject.com/weblog/2011/feb/08/security/
Restricted filters in admin interface Restricted filters in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------
Prior to Django 1.2.5, the Django administrative interface allowed Prior to Django 1.2.5, the Django administrative interface allowed
filtering on any model field or relation -- not just those specified filtering on any model field or relation -- not just those specified
@ -357,7 +357,7 @@ admin must be for fields or relations specified in ``list_filter`` or
``date_hierarchy``. ``date_hierarchy``.
Deleting a model doesn't delete associated files Deleting a model doesn't delete associated files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------------
In earlier Django versions, when a model instance containing a In earlier Django versions, when a model instance containing a
:class:`~django.db.models.FileField` was deleted, :class:`~django.db.models.FileField` was deleted,
@ -371,7 +371,7 @@ instance, with a custom management command that can be run manually or
scheduled to run periodically via e.g. cron). scheduled to run periodically via e.g. cron).
PasswordInput default rendering behavior PasswordInput default rendering behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------
The :class:`~django.forms.PasswordInput` form widget, intended for use The :class:`~django.forms.PasswordInput` form widget, intended for use
with form fields which represent passwords, accepts a boolean keyword with form fields which represent passwords, accepts a boolean keyword
@ -394,7 +394,7 @@ explicitly indicate this. For example::
password = forms.CharField(widget=forms.PasswordInput(render_value=True)) password = forms.CharField(widget=forms.PasswordInput(render_value=True))
Clearable default widget for FileField Clearable default widget for FileField
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------
Django 1.3 now includes a :class:`~django.forms.ClearableFileInput` form widget Django 1.3 now includes a :class:`~django.forms.ClearableFileInput` form widget
in addition to :class:`~django.forms.FileInput`. ``ClearableFileInput`` renders in addition to :class:`~django.forms.FileInput`. ``ClearableFileInput`` renders
@ -420,7 +420,7 @@ To return to the previous rendering (without the ability to clear the
widgets = {'document': forms.FileInput} widgets = {'document': forms.FileInput}
New index on database session table New index on database session table
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------
Prior to Django 1.3, the database table used by the database backend Prior to Django 1.3, the database table used by the database backend
for the :doc:`sessions </topics/http/sessions>` app had no index on for the :doc:`sessions </topics/http/sessions>` app had no index on
@ -437,7 +437,7 @@ index can be found by running the ``sqlindexes`` admin command::
python manage.py sqlindexes sessions python manage.py sqlindexes sessions
No more naughty words No more naughty words
~~~~~~~~~~~~~~~~~~~~~ ---------------------
Django has historically provided (and enforced) a list of profanities. Django has historically provided (and enforced) a list of profanities.
The comments app has enforced this list of profanities, preventing people from The comments app has enforced this list of profanities, preventing people from
@ -462,7 +462,7 @@ problem.
.. _commit that implemented this change: https://code.djangoproject.com/changeset/13996 .. _commit that implemented this change: https://code.djangoproject.com/changeset/13996
Localflavor changes Localflavor changes
~~~~~~~~~~~~~~~~~~~ -------------------
Django 1.3 introduces the following backwards-incompatible changes to Django 1.3 introduces the following backwards-incompatible changes to
local flavors: local flavors:
@ -482,7 +482,7 @@ local flavors:
``USStateField`` not including them. ``USStateField`` not including them.
FormSet updates FormSet updates
~~~~~~~~~~~~~~~ ---------------
In Django 1.3 ``FormSet`` creation behavior is modified slightly. Historically In Django 1.3 ``FormSet`` creation behavior is modified slightly. Historically
the class didn't make a distinction between not being passed data and being the class didn't make a distinction between not being passed data and being
@ -511,7 +511,7 @@ if you need to instantiate an empty ``FormSet``, don't pass in the data or use
>>> formset = ArticleFormSet(data=None) >>> formset = ArticleFormSet(data=None)
Callables in templates Callables in templates
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
Previously, a callable in a template would only be called automatically as part Previously, a callable in a template would only be called automatically as part
of the variable resolution process if it was retrieved via attribute of the variable resolution process if it was retrieved via attribute
@ -529,7 +529,7 @@ designed for web designers, and was never deliberately supported, it is possible
that some templates may be broken by this change. that some templates may be broken by this change.
Use of custom SQL to load initial data in tests Use of custom SQL to load initial data in tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------------
Django provides a custom SQL hooks as a way to inject hand-crafted SQL Django provides a custom SQL hooks as a way to inject hand-crafted SQL
into the database synchronization process. One of the possible uses into the database synchronization process. One of the possible uses
@ -559,7 +559,7 @@ should either insert it using :ref:`test fixtures
test case. test case.
Changed priority of translation loading Changed priority of translation loading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------
Work has been done to simplify, rationalize and properly document the algorithm Work has been done to simplify, rationalize and properly document the algorithm
used by Django at runtime to build translations from the different translations used by Django at runtime to build translations from the different translations
@ -605,7 +605,7 @@ domain):
.. _corresponding deprecated features section: loading_of_project_level_translations_ .. _corresponding deprecated features section: loading_of_project_level_translations_
Transaction management Transaction management
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
When using managed transactions -- that is, anything but the default When using managed transactions -- that is, anything but the default
autocommit mode -- it is important when a transaction is marked as autocommit mode -- it is important when a transaction is marked as
@ -639,14 +639,14 @@ the read operation that retrieves the ``MyObject`` instance leaves the
transaction in a dirty state. transaction in a dirty state.
No password reset for inactive users No password reset for inactive users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------
Prior to Django 1.3, inactive users were able to request a password reset email Prior to Django 1.3, inactive users were able to request a password reset email
and reset their password. In Django 1.3 inactive users will receive the same and reset their password. In Django 1.3 inactive users will receive the same
message as a nonexistent account. message as a nonexistent account.
Password reset view now accepts ``from_email`` Password reset view now accepts ``from_email``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------
The :func:`django.contrib.auth.views.password_reset` view now accepts a The :func:`django.contrib.auth.views.password_reset` view now accepts a
``from_email`` parameter, which is passed to the ``password_reset_form``’s ``from_email`` parameter, which is passed to the ``password_reset_form``’s
@ -679,7 +679,7 @@ be removed entirely.
</internals/deprecation>`. </internals/deprecation>`.
``mod_python`` support ``mod_python`` support
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
The ``mod_python`` library has not had a release since 2007 or a commit since The ``mod_python`` library has not had a release since 2007 or a commit since
2008. The Apache Foundation board voted to remove ``mod_python`` from the set 2008. The Apache Foundation board voted to remove ``mod_python`` from the set
@ -694,7 +694,7 @@ recommended by the Django project, but FastCGI is also supported. Support for
``mod_python`` deployment will be removed in Django 1.5. ``mod_python`` deployment will be removed in Django 1.5.
Function-based generic views Function-based generic views
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
As a result of the introduction of class-based generic views, the As a result of the introduction of class-based generic views, the
function-based generic views provided by Django have been deprecated. function-based generic views provided by Django have been deprecated.
@ -706,7 +706,7 @@ The following modules and the views they contain have been deprecated:
* ``django.views.generic.simple`` * ``django.views.generic.simple``
Test client response ``template`` attribute Test client response ``template`` attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------
Django's :ref:`test client <test-client>` returns Django's :ref:`test client <test-client>` returns
:class:`~django.test.Response` objects annotated with extra testing :class:`~django.test.Response` objects annotated with extra testing
@ -722,7 +722,7 @@ In Django 1.3 the ``template`` attribute is deprecated in favor of a new
list, even if it has only a single element or no elements. list, even if it has only a single element or no elements.
``DjangoTestRunner`` ``DjangoTestRunner``
~~~~~~~~~~~~~~~~~~~~ --------------------
As a result of the introduction of support for unittest2, the features As a result of the introduction of support for unittest2, the features
of ``django.test.simple.DjangoTestRunner`` (including fail-fast of ``django.test.simple.DjangoTestRunner`` (including fail-fast
@ -731,7 +731,7 @@ redundancy, ``DjangoTestRunner`` has been turned into an empty placeholder
class, and will be removed entirely in Django 1.5. class, and will be removed entirely in Django 1.5.
Changes to ``url`` and ``ssi`` Changes to ``url`` and ``ssi``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
Most template tags will allow you to pass in either constants or Most template tags will allow you to pass in either constants or
variables as arguments -- for example:: variables as arguments -- for example::
@ -771,7 +771,7 @@ templates should be modified to use the new ``future`` libraries and
syntax. syntax.
Changes to the login methods of the admin Changes to the login methods of the admin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------
In previous version the admin app defined login methods in multiple locations In previous version the admin app defined login methods in multiple locations
and ignored the almost identical implementation in the already used auth app. and ignored the almost identical implementation in the already used auth app.
@ -788,7 +788,7 @@ attribute.
.. _r12634: https://code.djangoproject.com/changeset/12634 .. _r12634: https://code.djangoproject.com/changeset/12634
``reset`` and ``sqlreset`` management commands ``reset`` and ``sqlreset`` management commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------
Those commands have been deprecated. The ``flush`` and ``sqlflush`` commands Those commands have been deprecated. The ``flush`` and ``sqlflush`` commands
can be used to delete everything. You can also use ALTER TABLE or DROP TABLE can be used to delete everything. You can also use ALTER TABLE or DROP TABLE
@ -796,7 +796,7 @@ statements manually.
GeoDjango GeoDjango
~~~~~~~~~ ---------
* The function-based :setting:`TEST_RUNNER` previously used to execute * The function-based :setting:`TEST_RUNNER` previously used to execute
the GeoDjango test suite, ``django.contrib.gis.tests.run_gis_tests``, was the GeoDjango test suite, ``django.contrib.gis.tests.run_gis_tests``, was
@ -812,7 +812,7 @@ GeoDjango
called when the SRID of the geometry is less than 0 or ``None``. called when the SRID of the geometry is less than 0 or ``None``.
``CZBirthNumberField.clean`` ``CZBirthNumberField.clean``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
Previously this field's ``clean()`` method accepted a second, gender, argument Previously this field's ``clean()`` method accepted a second, gender, argument
which allowed stronger validation checks to be made, however since this which allowed stronger validation checks to be made, however since this
@ -820,7 +820,7 @@ argument could never actually be passed from the Django form machinery it is
now pending deprecation. now pending deprecation.
``CompatCookie`` ``CompatCookie``
~~~~~~~~~~~~~~~~ ----------------
Previously, ``django.http`` exposed an undocumented ``CompatCookie`` class, Previously, ``django.http`` exposed an undocumented ``CompatCookie`` class,
which was a bugfix wrapper around the standard library ``SimpleCookie``. As the which was a bugfix wrapper around the standard library ``SimpleCookie``. As the
@ -830,7 +830,7 @@ django.http import SimpleCookie`` instead.
.. _loading_of_project_level_translations: .. _loading_of_project_level_translations:
Loading of *project-level* translations Loading of *project-level* translations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------
This release of Django starts the deprecation process for inclusion of This release of Django starts the deprecation process for inclusion of
translations located under the so-called *project path* in the translation translations located under the so-called *project path* in the translation
@ -865,7 +865,7 @@ Rationale for this decision:
inconsistency. inconsistency.
``PermWrapper`` moved to ``django.contrib.auth.context_processors`` ``PermWrapper`` moved to ``django.contrib.auth.context_processors``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------------------------------
In Django 1.2, we began the process of changing the location of the In Django 1.2, we began the process of changing the location of the
``auth`` context processor from ``django.core.context_processors`` to ``auth`` context processor from ``django.core.context_processors`` to
@ -877,7 +877,7 @@ moved to ``django.contrib.auth.context_processors``, along with the
identical to their old versions; only the module location has changed. identical to their old versions; only the module location has changed.
Removal of ``XMLField`` Removal of ``XMLField``
~~~~~~~~~~~~~~~~~~~~~~~ -----------------------
When Django was first released, Django included an ``XMLField`` that performed When Django was first released, Django included an ``XMLField`` that performed
automatic XML validation for any field input. However, this validation function automatic XML validation for any field input. However, this validation function

2
docs/releases/1.4.10.txt
View File

@ -7,7 +7,7 @@ Django 1.4.10 release notes
Django 1.4.10 fixes a Python-compatibility bug in the 1.4 series. Django 1.4.10 fixes a Python-compatibility bug in the 1.4 series.
Python compatibility Python compatibility
-------------------- ====================
Django 1.4.9 inadvertently introduced issues with Python 2.5 compatibility. Django 1.4.9 inadvertently introduced issues with Python 2.5 compatibility.
Django 1.4.10 restores Python 2.5 compatibility. This was issue #21362 in Django 1.4.10 restores Python 2.5 compatibility. This was issue #21362 in

2
docs/releases/1.4.2.txt
View File

@ -7,7 +7,7 @@ Django 1.4.2 release notes
This is the second security release in the Django 1.4 series. This is the second security release in the Django 1.4 series.
Host header poisoning Host header poisoning
--------------------- =====================
Some parts of Django -- independent of end-user-written applications -- make Some parts of Django -- independent of end-user-written applications -- make
use of full URLs, including domain name, which are generated from the HTTP Host use of full URLs, including domain name, which are generated from the HTTP Host

4
docs/releases/1.4.3.txt
View File

@ -14,7 +14,7 @@ the other we've chosen to take further steps to tighten up Django's code in
response to independent discovery of potential problems from multiple sources. response to independent discovery of potential problems from multiple sources.
Host header poisoning Host header poisoning
--------------------- =====================
Several earlier Django security releases focused on the issue of poisoning the Several earlier Django security releases focused on the issue of poisoning the
HTTP Host header, causing Django to generate URLs pointing to arbitrary, HTTP Host header, causing Django to generate URLs pointing to arbitrary,
@ -35,7 +35,7 @@ Any deviation from this will now be rejected, raising the exception
:exc:`django.core.exceptions.SuspiciousOperation`. :exc:`django.core.exceptions.SuspiciousOperation`.
Redirect poisoning Redirect poisoning
------------------ ==================
Also following up on a previous issue: in July of this year, we made changes to Also following up on a previous issue: in July of this year, we made changes to
Django's HTTP redirect classes, performing additional validation of the scheme Django's HTTP redirect classes, performing additional validation of the scheme

8
docs/releases/1.4.4.txt
View File

@ -12,7 +12,7 @@ This is the fourth bugfix/security release in the Django 1.4 series.
Host header poisoning Host header poisoning
--------------------- =====================
Some parts of Django -- independent of end-user-written applications -- make Some parts of Django -- independent of end-user-written applications -- make
use of full URLs, including domain name, which are generated from the HTTP Host use of full URLs, including domain name, which are generated from the HTTP Host
@ -37,7 +37,7 @@ This host validation is disabled when ``DEBUG`` is ``True`` or when running test
XML deserialization XML deserialization
------------------- ===================
The XML parser in the Python standard library is vulnerable to a number of The XML parser in the Python standard library is vulnerable to a number of
attacks via external entities and entity expansion. Django uses this parser for attacks via external entities and entity expansion. Django uses this parser for
@ -58,7 +58,7 @@ management command, you will need to ensure they do not contain a DTD.
Formset memory exhaustion Formset memory exhaustion
------------------------- =========================
Previous versions of Django did not validate or limit the form-count data Previous versions of Django did not validate or limit the form-count data
provided by the client in a formset's management form, making it possible to provided by the client in a formset's management form, making it possible to
@ -71,7 +71,7 @@ factory argument).
Admin history view information leakage Admin history view information leakage
-------------------------------------- ======================================
In previous versions of Django, an admin user without change permission on a In previous versions of Django, an admin user without change permission on a
model could still view the unicode representation of instances via their admin model could still view the unicode representation of instances via their admin

2
docs/releases/1.4.6.txt
View File

@ -10,7 +10,7 @@ the 1.4 series, as well as one other bug.
This is the sixth bugfix/security release in the Django 1.4 series. This is the sixth bugfix/security release in the Django 1.4 series.
Mitigated possible XSS attack via user-supplied redirect URLs Mitigated possible XSS attack via user-supplied redirect URLs
------------------------------------------------------------- =============================================================
Django relies on user input in some cases (e.g. Django relies on user input in some cases (e.g.
:func:`django.contrib.auth.views.login`, ``django.contrib.comments``, and :func:`django.contrib.auth.views.login`, ``django.contrib.comments``, and

2
docs/releases/1.4.7.txt
View File

@ -8,7 +8,7 @@ Django 1.4.7 fixes one security issue present in previous Django releases in
the 1.4 series. the 1.4 series.
Directory traversal vulnerability in ``ssi`` template tag Directory traversal vulnerability in ``ssi`` template tag
--------------------------------------------------------- =========================================================
In previous versions of Django it was possible to bypass the In previous versions of Django it was possible to bypass the
``ALLOWED_INCLUDE_ROOTS`` setting used for security with the ``ssi`` ``ALLOWED_INCLUDE_ROOTS`` setting used for security with the ``ssi``

4
docs/releases/1.4.8.txt
View File

@ -8,7 +8,7 @@ Django 1.4.8 fixes two security issues present in previous Django releases in
the 1.4 series. the 1.4 series.
Denial-of-service via password hashers Denial-of-service via password hashers
-------------------------------------- ======================================
In previous versions of Django, no limit was imposed on the plaintext In previous versions of Django, no limit was imposed on the plaintext
length of a password. This allowed a denial-of-service attack through length of a password. This allowed a denial-of-service attack through
@ -21,7 +21,7 @@ limit on passwords and will fail authentication with any submitted
password of greater length. password of greater length.
Corrected usage of :func:`~django.views.decorators.debug.sensitive_post_parameters` in :mod:`django.contrib.auth`’s admin Corrected usage of :func:`~django.views.decorators.debug.sensitive_post_parameters` in :mod:`django.contrib.auth`’s admin
------------------------------------------------------------------------------------------------------------------------- =========================================================================================================================
The decoration of the ``add_view`` and ``user_change_password`` user admin The decoration of the ``add_view`` and ``user_change_password`` user admin
views with :func:`~django.views.decorators.debug.sensitive_post_parameters` views with :func:`~django.views.decorators.debug.sensitive_post_parameters`

2
docs/releases/1.4.9.txt
View File

@ -8,7 +8,7 @@ Django 1.4.9 fixes a security-related bug in the 1.4 series and one other
data corruption bug. data corruption bug.
Readdressed denial-of-service via password hashers Readdressed denial-of-service via password hashers
-------------------------------------------------- ==================================================
Django 1.4.8 imposes a 4096-byte limit on passwords in order to mitigate a Django 1.4.8 imposes a 4096-byte limit on passwords in order to mitigate a
denial-of-service attack through submission of bogus but extremely large denial-of-service attack through submission of bogus but extremely large

152
docs/releases/1.4.txt
View File

@ -81,7 +81,7 @@ What's new in Django 1.4
======================== ========================
Support for time zones Support for time zones
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
In previous versions, Django used "naive" date/times (that is, date/times In previous versions, Django used "naive" date/times (that is, date/times
without an associated time zone), leaving it up to each developer to interpret without an associated time zone), leaving it up to each developer to interpret
@ -108,7 +108,7 @@ project, read the :ref:`migration guide <time-zones-migration-guide>`. If you
encounter problems, there's a helpful :ref:`FAQ <time-zones-faq>`. encounter problems, there's a helpful :ref:`FAQ <time-zones-faq>`.
Support for in-browser testing frameworks Support for in-browser testing frameworks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------
Django 1.4 supports integration with in-browser testing frameworks like Django 1.4 supports integration with in-browser testing frameworks like
Selenium_. The new :class:`django.test.LiveServerTestCase` base class lets you Selenium_. The new :class:`django.test.LiveServerTestCase` base class lets you
@ -120,7 +120,7 @@ concrete examples.
.. _Selenium: http://seleniumhq.org/ .. _Selenium: http://seleniumhq.org/
Updated default project layout and ``manage.py`` Updated default project layout and ``manage.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------------
Django 1.4 ships with an updated default project layout and ``manage.py`` file Django 1.4 ships with an updated default project layout and ``manage.py`` file
for the :djadmin:`startproject` management command. These fix some issues with for the :djadmin:`startproject` management command. These fix some issues with
@ -186,7 +186,7 @@ prefix, some places without it), the imports will need to be cleaned up when
switching to the new ``manage.py``. switching to the new ``manage.py``.
Custom project and app templates Custom project and app templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
The :djadmin:`startapp` and :djadmin:`startproject` management commands The :djadmin:`startapp` and :djadmin:`startproject` management commands
now have a ``--template`` option for specifying a path or URL to a custom app now have a ``--template`` option for specifying a path or URL to a custom app
@ -207,7 +207,7 @@ For more information, see the :djadmin:`startapp` and :djadmin:`startproject`
documentation. documentation.
Improved WSGI support Improved WSGI support
~~~~~~~~~~~~~~~~~~~~~ ---------------------
The :djadmin:`startproject` management command now adds a :file:`wsgi.py` The :djadmin:`startproject` management command now adds a :file:`wsgi.py`
module to the initial project layout, containing a simple WSGI application that module to the initial project layout, containing a simple WSGI application that
@ -224,7 +224,7 @@ with the same WSGI configuration that is used for deployment. The new
callable configured via :setting:`WSGI_APPLICATION`.) callable configured via :setting:`WSGI_APPLICATION`.)
``SELECT FOR UPDATE`` support ``SELECT FOR UPDATE`` support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
Django 1.4 includes a :meth:`QuerySet.select_for_update() Django 1.4 includes a :meth:`QuerySet.select_for_update()
<django.db.models.query.QuerySet.select_for_update>` method, which generates a <django.db.models.query.QuerySet.select_for_update>` method, which generates a
@ -236,7 +236,7 @@ For more details, see the documentation for
:meth:`~django.db.models.query.QuerySet.select_for_update`. :meth:`~django.db.models.query.QuerySet.select_for_update`.
``Model.objects.bulk_create`` in the ORM ``Model.objects.bulk_create`` in the ORM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------
This method lets you create multiple objects more efficiently. It can result in This method lets you create multiple objects more efficiently. It can result in
significant performance increases if you have many objects. significant performance increases if you have many objects.
@ -248,7 +248,7 @@ See the :meth:`~django.db.models.query.QuerySet.bulk_create` docs for more
information. information.
``QuerySet.prefetch_related`` ``QuerySet.prefetch_related``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
Similar to :meth:`~django.db.models.query.QuerySet.select_related` but with a Similar to :meth:`~django.db.models.query.QuerySet.select_related` but with a
different strategy and broader scope, different strategy and broader scope,
@ -263,7 +263,7 @@ doing O(n) database queries (or worse) if objects on your primary ``QuerySet``
each have many related objects that you also need to fetch. each have many related objects that you also need to fetch.
Improved password hashing Improved password hashing
~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------
Django's auth system (``django.contrib.auth``) stores passwords using a one-way Django's auth system (``django.contrib.auth``) stores passwords using a one-way
algorithm. Django 1.3 uses the SHA1_ algorithm, but increasing processor speeds algorithm. Django 1.3 uses the SHA1_ algorithm, but increasing processor speeds
@ -279,7 +279,7 @@ details, see :ref:`auth_password_storage`.
.. _bcrypt: https://en.wikipedia.org/wiki/Bcrypt .. _bcrypt: https://en.wikipedia.org/wiki/Bcrypt
HTML5 doctype HTML5 doctype
~~~~~~~~~~~~~ -------------
We've switched the admin and other bundled templates to use the HTML5 We've switched the admin and other bundled templates to use the HTML5
doctype. While Django will be careful to maintain compatibility with older doctype. While Django will be careful to maintain compatibility with older
@ -288,7 +288,7 @@ admin pages without having to lose HTML validity or override the provided
templates to change the doctype. templates to change the doctype.
List filters in admin interface List filters in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
Prior to Django 1.4, the :mod:`~django.contrib.admin` app let you specify Prior to Django 1.4, the :mod:`~django.contrib.admin` app let you specify
change list filters by specifying a field lookup, but it didn't allow you to change list filters by specifying a field lookup, but it didn't allow you to
@ -297,7 +297,7 @@ used internally and known as "FilterSpec"). For more details, see the
documentation for :attr:`~django.contrib.admin.ModelAdmin.list_filter`. documentation for :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
Multiple sort in admin interface Multiple sort in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
The admin change list now supports sorting on multiple columns. It respects all The admin change list now supports sorting on multiple columns. It respects all
elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering` attribute, and elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering` attribute, and
@ -307,7 +307,7 @@ behavior of desktop GUIs. We also added a
ordering dynamically (i.e., depending on the request). ordering dynamically (i.e., depending on the request).
New ``ModelAdmin`` methods New ``ModelAdmin`` methods
~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------
We added a :meth:`~django.contrib.admin.ModelAdmin.save_related` method to We added a :meth:`~django.contrib.admin.ModelAdmin.save_related` method to
:mod:`~django.contrib.admin.ModelAdmin` to ease customization of how :mod:`~django.contrib.admin.ModelAdmin` to ease customization of how
@ -320,7 +320,7 @@ enable dynamic customization of fields and links displayed on the admin
change list. change list.
Admin inlines respect user permissions Admin inlines respect user permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------
Admin inlines now only allow those actions for which the user has Admin inlines now only allow those actions for which the user has
permission. For ``ManyToMany`` relationships with an auto-created intermediate permission. For ``ManyToMany`` relationships with an auto-created intermediate
@ -329,7 +329,7 @@ related model determines if the user has the permission to add, change or
delete relationships. delete relationships.
Tools for cryptographic signing Tools for cryptographic signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
Django 1.4 adds both a low-level API for signing values and a high-level API Django 1.4 adds both a low-level API for signing values and a high-level API
for setting and reading signed cookies, one of the most common uses of for setting and reading signed cookies, one of the most common uses of
@ -339,7 +339,7 @@ See the :doc:`cryptographic signing </topics/signing>` docs for more
information. information.
Cookie-based session backend Cookie-based session backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
Django 1.4 introduces a cookie-based session backend that uses the tools for Django 1.4 introduces a cookie-based session backend that uses the tools for
:doc:`cryptographic signing </topics/signing>` to store the session data in :doc:`cryptographic signing </topics/signing>` to store the session data in
@ -356,7 +356,7 @@ See the :ref:`cookie-based session backend <cookie-session-backend>` docs for
more information. more information.
New form wizard New form wizard
~~~~~~~~~~~~~~~ ---------------
The previous ``FormWizard`` from ``django.contrib.formtools`` has been The previous ``FormWizard`` from ``django.contrib.formtools`` has been
replaced with a new implementation based on the class-based views replaced with a new implementation based on the class-based views
@ -369,13 +369,13 @@ storage backend. The latter uses the tools for
Django 1.4 to store the wizard's state in the user's cookies. Django 1.4 to store the wizard's state in the user's cookies.
``reverse_lazy`` ``reverse_lazy``
~~~~~~~~~~~~~~~~ ----------------
A lazily evaluated version of ``reverse()`` was added to allow using URL A lazily evaluated version of ``reverse()`` was added to allow using URL
reversals before the project's URLconf gets loaded. reversals before the project's URLconf gets loaded.
Translating URL patterns Translating URL patterns
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
Django can now look for a language prefix in the URLpattern when using the new Django can now look for a language prefix in the URLpattern when using the new
:func:`~django.conf.urls.i18n.i18n_patterns` helper function. :func:`~django.conf.urls.i18n.i18n_patterns` helper function.
@ -385,7 +385,7 @@ It's also now possible to define translatable URL patterns using
and how to internationalize URL patterns. and how to internationalize URL patterns.
Contextual translation support for ``{% trans %}`` and ``{% blocktrans %}`` Contextual translation support for ``{% trans %}`` and ``{% blocktrans %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------------------------------------
The :ref:`contextual translation<contextual-markers>` support introduced in The :ref:`contextual translation<contextual-markers>` support introduced in
Django 1.3 via the ``pgettext`` function has been extended to the Django 1.3 via the ``pgettext`` function has been extended to the
@ -393,7 +393,7 @@ Django 1.3 via the ``pgettext`` function has been extended to the
keyword. keyword.
Customizable ``SingleObjectMixin`` URLConf kwargs Customizable ``SingleObjectMixin`` URLConf kwargs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------------
Two new attributes, Two new attributes,
:attr:`pk_url_kwarg<django.views.generic.detail.SingleObjectMixin.pk_url_kwarg>` :attr:`pk_url_kwarg<django.views.generic.detail.SingleObjectMixin.pk_url_kwarg>`
@ -404,14 +404,14 @@ enable the customization of URLconf keyword arguments used for single
object generic views. object generic views.
Assignment template tags Assignment template tags
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
A new ``assignment_tag`` helper function was added to ``template.Library`` to A new ``assignment_tag`` helper function was added to ``template.Library`` to
ease the creation of template tags that store data in a specified context ease the creation of template tags that store data in a specified context
variable. variable.
``*args`` and ``**kwargs`` support for template tag helper functions ``*args`` and ``**kwargs`` support for template tag helper functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------------------------------
The :ref:`simple_tag<howto-custom-template-tags-simple-tags>`, The :ref:`simple_tag<howto-custom-template-tags-simple-tags>`,
:ref:`inclusion_tag <howto-custom-template-tags-inclusion-tags>` and newly :ref:`inclusion_tag <howto-custom-template-tags-inclusion-tags>` and newly
@ -433,7 +433,7 @@ For example:
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %} {% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}
No wrapping of exceptions in ``TEMPLATE_DEBUG`` mode No wrapping of exceptions in ``TEMPLATE_DEBUG`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------------
In previous versions of Django, whenever the ``TEMPLATE_DEBUG`` setting In previous versions of Django, whenever the ``TEMPLATE_DEBUG`` setting
was ``True``, any exception raised during template rendering (even exceptions was ``True``, any exception raised during template rendering (even exceptions
@ -448,7 +448,7 @@ exceptions from template rendering is now consistent regardless of the value of
``TemplateSyntaxError`` in order to catch other errors. ``TemplateSyntaxError`` in order to catch other errors.
``truncatechars`` template filter ``truncatechars`` template filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------
This new filter truncates a string to be no longer than the specified This new filter truncates a string to be no longer than the specified
number of characters. Truncated strings end with a translatable ellipsis number of characters. Truncated strings end with a translatable ellipsis
@ -456,7 +456,7 @@ sequence ("..."). See the documentation for :tfilter:`truncatechars` for
more details. more details.
``static`` template tag ``static`` template tag
~~~~~~~~~~~~~~~~~~~~~~~ -----------------------
The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has a new The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has a new
``static`` template tag to refer to files saved with the ``static`` template tag to refer to files saved with the
@ -465,7 +465,7 @@ The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has a new
files from a cloud service<staticfiles-from-cdn>`. files from a cloud service<staticfiles-from-cdn>`.
``CachedStaticFilesStorage`` storage backend ``CachedStaticFilesStorage`` storage backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------
The :mod:`staticfiles<django.contrib.staticfiles>` contrib app now has a The :mod:`staticfiles<django.contrib.staticfiles>` contrib app now has a
:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` backend :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` backend
@ -478,7 +478,7 @@ See the :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage`
docs for more information. docs for more information.
Simple clickjacking protection Simple clickjacking protection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
We've added a middleware to provide easy protection against `clickjacking We've added a middleware to provide easy protection against `clickjacking
<https://en.wikipedia.org/wiki/Clickjacking>`_ using the ``X-Frame-Options`` <https://en.wikipedia.org/wiki/Clickjacking>`_ using the ``X-Frame-Options``
@ -487,7 +487,7 @@ you'll almost certainly want to :doc:`enable it </ref/clickjacking/>` to help
plug that security hole for browsers that support the header. plug that security hole for browsers that support the header.
CSRF improvements CSRF improvements
~~~~~~~~~~~~~~~~~ -----------------
We've made various improvements to our CSRF features, including the We've made various improvements to our CSRF features, including the
:func:`~django.views.decorators.csrf.ensure_csrf_cookie` decorator, which can :func:`~django.views.decorators.csrf.ensure_csrf_cookie` decorator, which can
@ -497,7 +497,7 @@ improve the security and usefulness of CSRF protection. See the :doc:`CSRF
docs </ref/csrf>` for more information. docs </ref/csrf>` for more information.
Error report filtering Error report filtering
~~~~~~~~~~~~~~~~~~~~~~ ----------------------
We added two function decorators, We added two function decorators,
:func:`~django.views.decorators.debug.sensitive_variables` and :func:`~django.views.decorators.debug.sensitive_variables` and
@ -516,7 +516,7 @@ filter<custom-error-reports>`. For more information see the docs on
:ref:`Filtering error reports<filtering-error-reports>`. :ref:`Filtering error reports<filtering-error-reports>`.
Extended IPv6 support Extended IPv6 support
~~~~~~~~~~~~~~~~~~~~~ ---------------------
Django 1.4 can now better handle IPv6 addresses with the new Django 1.4 can now better handle IPv6 addresses with the new
:class:`~django.db.models.GenericIPAddressField` model field, :class:`~django.db.models.GenericIPAddressField` model field,
@ -525,7 +525,7 @@ the validators :data:`~django.core.validators.validate_ipv46_address` and
:data:`~django.core.validators.validate_ipv6_address`. :data:`~django.core.validators.validate_ipv6_address`.
HTML comparisons in tests HTML comparisons in tests
~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------
The base classes in :mod:`django.test` now have some helpers to The base classes in :mod:`django.test` now have some helpers to
compare HTML without tripping over irrelevant differences in whitespace, compare HTML without tripping over irrelevant differences in whitespace,
@ -540,10 +540,10 @@ client's response contains a given HTML fragment. See the :ref:`assertions
documentation <assertions>` for more. documentation <assertions>` for more.
Two new date format strings Two new date format strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------
Two new :tfilter:`date` formats were added for use in template filters, Two new :tfilter:`date` formats were added for use in template filters,
template tags and :ref:`format-localization`: template tags and :doc:`/topics/i18n/formatting`:
- ``e`` -- the name of the timezone of the given datetime object - ``e`` -- the name of the timezone of the given datetime object
- ``o`` -- the ISO 8601 year number - ``o`` -- the ISO 8601 year number
@ -562,7 +562,7 @@ But now it needs to also escape ``e`` and ``o``::
For more information, see the :tfilter:`date` documentation. For more information, see the :tfilter:`date` documentation.
Minor features Minor features
~~~~~~~~~~~~~~ --------------
Django 1.4 also includes several smaller improvements worth noting: Django 1.4 also includes several smaller improvements worth noting:
@ -666,7 +666,7 @@ Backwards incompatible changes in 1.4
===================================== =====================================
SECRET_KEY setting is required SECRET_KEY setting is required
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
Running Django with an empty or known :setting:`SECRET_KEY` disables many of Running Django with an empty or known :setting:`SECRET_KEY` disables many of
Django's security protections and can lead to remote-code-execution Django's security protections and can lead to remote-code-execution
@ -680,7 +680,7 @@ due to the severity of the consequences of running Django with no
:setting:`SECRET_KEY`. :setting:`SECRET_KEY`.
django.contrib.admin django.contrib.admin
~~~~~~~~~~~~~~~~~~~~ --------------------
The included administration app ``django.contrib.admin`` has for a long time The included administration app ``django.contrib.admin`` has for a long time
shipped with a default set of static files such as JavaScript, images and shipped with a default set of static files such as JavaScript, images and
@ -715,7 +715,7 @@ If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
:file:`django/contrib/admin/static/admin/`. :file:`django/contrib/admin/static/admin/`.
Supported browsers for the admin Supported browsers for the admin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
Django hasn't had a clear policy on which browsers are supported by the Django hasn't had a clear policy on which browsers are supported by the
admin app. Our new policy formalizes existing practices: `YUI's A-grade`_ admin app. Our new policy formalizes existing practices: `YUI's A-grade`_
@ -733,7 +733,7 @@ any range of browsers.
.. _YUI's A-grade: http://yuilibrary.com/yui/docs/tutorials/gbs/ .. _YUI's A-grade: http://yuilibrary.com/yui/docs/tutorials/gbs/
Removed admin icons Removed admin icons
~~~~~~~~~~~~~~~~~~~ -------------------
As part of an effort to improve the performance and usability of the admin's As part of an effort to improve the performance and usability of the admin's
change-list sorting interface and :attr:`horizontal change-list sorting interface and :attr:`horizontal
@ -751,7 +751,7 @@ If you used those icons to customize the admin, then you'll need to replace
them with your own icons or get the files from a previous release. them with your own icons or get the files from a previous release.
CSS class names in admin forms CSS class names in admin forms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------
To avoid conflicts with other common CSS class names (e.g. "button"), we added To avoid conflicts with other common CSS class names (e.g. "button"), we added
a prefix ("field-") to all CSS class names automatically generated from the a prefix ("field-") to all CSS class names automatically generated from the
@ -761,7 +761,7 @@ style sheets or JavaScript files if you previously used plain field names as
selectors for custom styles or JavaScript transformations. selectors for custom styles or JavaScript transformations.
Compatibility with old signed data Compatibility with old signed data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------
Django 1.3 changed the cryptographic signing mechanisms used in a number of Django 1.3 changed the cryptographic signing mechanisms used in a number of
places in Django. While Django 1.3 kept fallbacks that would accept hashes places in Django. While Django 1.3 kept fallbacks that would accept hashes
@ -831,7 +831,7 @@ instance:
password hashes. password hashes.
django.contrib.flatpages django.contrib.flatpages
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
Starting in 1.4, the Starting in 1.4, the
:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` only :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware` only
@ -845,7 +845,7 @@ Also, redirects returned by flatpages are now permanent (with 301 status code),
to match the behavior of :class:`~django.middleware.common.CommonMiddleware`. to match the behavior of :class:`~django.middleware.common.CommonMiddleware`.
Serialization of :class:`~datetime.datetime` and :class:`~datetime.time` Serialization of :class:`~datetime.datetime` and :class:`~datetime.time`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------------------------------------
As a consequence of time-zone support, and according to the ECMA-262 As a consequence of time-zone support, and according to the ECMA-262
specification, we made changes to the JSON serializer: specification, we made changes to the JSON serializer:
@ -865,7 +865,7 @@ Though the serializers now use these new formats when creating fixtures, they
can still load fixtures that use the old format. can still load fixtures that use the old format.
``supports_timezone`` changed to ``False`` for SQLite ``supports_timezone`` changed to ``False`` for SQLite
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------------------
The database feature ``supports_timezone`` used to be ``True`` for SQLite. The database feature ``supports_timezone`` used to be ``True`` for SQLite.
Indeed, if you saved an aware datetime object, SQLite stored a string that Indeed, if you saved an aware datetime object, SQLite stored a string that
@ -878,7 +878,7 @@ datetimes are now stored without time-zone information in SQLite. When
object, Django raises an exception. object, Django raises an exception.
``MySQLdb``-specific exceptions ``MySQLdb``-specific exceptions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------
The MySQL backend historically has raised ``MySQLdb.OperationalError`` The MySQL backend historically has raised ``MySQLdb.OperationalError``
when a query triggered an exception. We've fixed this bug, and we now raise when a query triggered an exception. We've fixed this bug, and we now raise
@ -887,7 +887,7 @@ when a query triggered an exception. We've fixed this bug, and we now raise
clauses. clauses.
Database connection's thread-locality Database connection's thread-locality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------
``DatabaseWrapper`` objects (i.e. the connection objects referenced by ``DatabaseWrapper`` objects (i.e. the connection objects referenced by
``django.db.connection`` and ``django.db.connections["some_alias"]``) used to ``django.db.connection`` and ``django.db.connections["some_alias"]``) used to
@ -913,7 +913,7 @@ Concurrency behavior is defined by the underlying backend implementation.
Check their documentation for details. Check their documentation for details.
`COMMENTS_BANNED_USERS_GROUP` setting `COMMENTS_BANNED_USERS_GROUP` setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------
Django's comments has historically Django's comments has historically
supported excluding the comments of a special user group, but we've never supported excluding the comments of a special user group, but we've never
@ -950,7 +950,7 @@ Save this model manager in your custom comment app (e.g., in
objects = BanningCommentManager() objects = BanningCommentManager()
`IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings `IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------------------
Until Django 1.3, it was possible to exclude some URLs from Django's Until Django 1.3, it was possible to exclude some URLs from Django's
:doc:`404 error reporting</howto/error-reporting>` by adding prefixes to :doc:`404 error reporting</howto/error-reporting>` by adding prefixes to
@ -988,7 +988,7 @@ Don't forget to escape characters that have a special meaning in a regular
expression, such as periods. expression, such as periods.
CSRF protection extended to PUT and DELETE CSRF protection extended to PUT and DELETE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------
Previously, Django's :doc:`CSRF protection </ref/csrf/>` provided Previously, Django's :doc:`CSRF protection </ref/csrf/>` provided
protection only against POST requests. Since use of PUT and DELETE methods in protection only against POST requests. Since use of PUT and DELETE methods in
@ -1000,7 +1000,7 @@ If you're using PUT or DELETE methods in AJAX applications, please see the
:ref:`instructions about using AJAX and CSRF <csrf-ajax>`. :ref:`instructions about using AJAX and CSRF <csrf-ajax>`.
Password reset view now accepts ``subject_template_name`` Password reset view now accepts ``subject_template_name``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------------------
The ``password_reset`` view in ``django.contrib.auth`` now accepts a The ``password_reset`` view in ``django.contrib.auth`` now accepts a
``subject_template_name`` parameter, which is passed to the password save form ``subject_template_name`` parameter, which is passed to the password save form
@ -1009,21 +1009,21 @@ form, then you will need to ensure your form's ``save()`` method accepts this
keyword argument. keyword argument.
``django.core.template_loaders`` ``django.core.template_loaders``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------
This was an alias to ``django.template.loader`` since 2005, and we've removed it This was an alias to ``django.template.loader`` since 2005, and we've removed it
without emitting a warning due to the length of the deprecation. If your code without emitting a warning due to the length of the deprecation. If your code
still referenced this, please use ``django.template.loader`` instead. still referenced this, please use ``django.template.loader`` instead.
``django.db.models.fields.URLField.verify_exists`` ``django.db.models.fields.URLField.verify_exists``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------------
This functionality has been removed due to intractable performance and This functionality has been removed due to intractable performance and
security issues. Any existing usage of ``verify_exists`` should be security issues. Any existing usage of ``verify_exists`` should be
removed. removed.
``django.core.files.storage.Storage.open`` ``django.core.files.storage.Storage.open``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------
The ``open`` method of the base Storage class used to take an obscure parameter The ``open`` method of the base Storage class used to take an obscure parameter
``mixin`` that allowed you to dynamically change the base classes of the ``mixin`` that allowed you to dynamically change the base classes of the
@ -1049,7 +1049,7 @@ method, like this::
return Spam(open(self.path(name), mode)) return Spam(open(self.path(name), mode))
YAML deserializer now uses ``yaml.safe_load`` YAML deserializer now uses ``yaml.safe_load``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------
``yaml.load`` is able to construct any Python object, which may trigger ``yaml.load`` is able to construct any Python object, which may trigger
arbitrary code execution if you process a YAML document that comes from an arbitrary code execution if you process a YAML document that comes from an
@ -1059,7 +1059,7 @@ fixtures are trusted data, the YAML deserializer now uses ``yaml.safe_load``
for additional security. for additional security.
Session cookies now have the ``httponly`` flag by default Session cookies now have the ``httponly`` flag by default
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------------------
Session cookies now include the ``httponly`` attribute by default to Session cookies now include the ``httponly`` attribute by default to
help reduce the impact of potential XSS attacks. As a consequence of help reduce the impact of potential XSS attacks. As a consequence of
@ -1069,7 +1069,7 @@ compatibility, use ``SESSION_COOKIE_HTTPONLY = False`` in your
settings file. settings file.
The :tfilter:`urlize` filter no longer escapes every URL The :tfilter:`urlize` filter no longer escapes every URL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------------------
When a URL contains a ``%xx`` sequence, where ``xx`` are two hexadecimal When a URL contains a ``%xx`` sequence, where ``xx`` are two hexadecimal
digits, :tfilter:`urlize` now assumes that the URL is already escaped and digits, :tfilter:`urlize` now assumes that the URL is already escaped and
@ -1078,7 +1078,7 @@ contains a ``%xx`` sequence, but such URLs are very unlikely to happen in the
wild, because they would confuse browsers too. wild, because they would confuse browsers too.
``assertTemplateUsed`` and ``assertTemplateNotUsed`` as context manager ``assertTemplateUsed`` and ``assertTemplateNotUsed`` as context manager
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------------------------------------
It's now possible to check whether a template was used within a block of It's now possible to check whether a template was used within a block of
code with :meth:`~django.test.SimpleTestCase.assertTemplateUsed` and code with :meth:`~django.test.SimpleTestCase.assertTemplateUsed` and
@ -1093,7 +1093,7 @@ can be used as a context manager::
See the :ref:`assertion documentation<assertions>` for more. See the :ref:`assertion documentation<assertions>` for more.
Database connections after running the test suite Database connections after running the test suite
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------------
The default test runner no longer restores the database connections after The default test runner no longer restores the database connections after
tests' execution. This prevents the production database from being exposed to tests' execution. This prevents the production database from being exposed to
@ -1106,7 +1106,7 @@ subclassing ``DjangoTestRunner`` and overriding its ``teardown_databases()``
method. method.
Output of :djadmin:`manage.py help <help>` Output of :djadmin:`manage.py help <help>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------
:djadmin:`manage.py help <help>` now groups available commands by application. :djadmin:`manage.py help <help>` now groups available commands by application.
If you depended on the output of this command -- if you parsed it, for example If you depended on the output of this command -- if you parsed it, for example
@ -1115,7 +1115,7 @@ management commands in a script, use
:djadmin:`manage.py help --commands <help>` instead. :djadmin:`manage.py help --commands <help>` instead.
``extends`` template tag ``extends`` template tag
~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------
Previously, the :ttag:`extends` tag used a buggy method of parsing arguments, Previously, the :ttag:`extends` tag used a buggy method of parsing arguments,
which could lead to it erroneously considering an argument as a string literal which could lead to it erroneously considering an argument as a string literal
@ -1126,7 +1126,7 @@ interests of full disclosure, the ``ExtendsNode.__init__`` definition has
changed, which may break any custom tags that use this class. changed, which may break any custom tags that use this class.
Loading some incomplete fixtures no longer works Loading some incomplete fixtures no longer works
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------------
Prior to 1.4, a default value was inserted for fixture objects that were missing Prior to 1.4, a default value was inserted for fixture objects that were missing
a specific date or datetime value when auto_now or auto_now_add was set for the a specific date or datetime value when auto_now or auto_now_add was set for the
@ -1135,7 +1135,7 @@ incomplete fixtures will fail. Because fixtures are a raw import, they should
explicitly specify all field values, regardless of field options on the model. explicitly specify all field values, regardless of field options on the model.
Development Server Multithreading Development Server Multithreading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------
The development server is now is multithreaded by default. Use the The development server is now is multithreaded by default. Use the
:option:`runserver --nothreading` option to disable the use of threading in the :option:`runserver --nothreading` option to disable the use of threading in the
@ -1144,7 +1144,7 @@ development server::
django-admin.py runserver --nothreading django-admin.py runserver --nothreading
Attributes disabled in markdown when safe mode set Attributes disabled in markdown when safe mode set
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------------
Prior to Django 1.4, attributes were included in any markdown output regardless Prior to Django 1.4, attributes were included in any markdown output regardless
of safe mode setting of the filter. With version > 2.1 of the Python-Markdown of safe mode setting of the filter. With version > 2.1 of the Python-Markdown
@ -1155,7 +1155,7 @@ Python-Markdown library less than 2.1, a warning is issued that the output is
insecure. insecure.
FormMixin get_initial returns an instance-specific dictionary FormMixin get_initial returns an instance-specific dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------------------------
In Django 1.3, the ``get_initial`` method of the In Django 1.3, the ``get_initial`` method of the
:class:`django.views.generic.edit.FormMixin` class was returning the :class:`django.views.generic.edit.FormMixin` class was returning the
@ -1169,14 +1169,14 @@ Features deprecated in 1.4
========================== ==========================
Old styles of calling ``cache_page`` decorator Old styles of calling ``cache_page`` decorator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------
Some legacy ways of calling :func:`~django.views.decorators.cache.cache_page` Some legacy ways of calling :func:`~django.views.decorators.cache.cache_page`
have been deprecated. Please see the documentation for the correct way to use have been deprecated. Please see the documentation for the correct way to use
this decorator. this decorator.
Support for PostgreSQL versions older than 8.2 Support for PostgreSQL versions older than 8.2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------------
Django 1.3 dropped support for PostgreSQL versions older than 8.0, and we Django 1.3 dropped support for PostgreSQL versions older than 8.0, and we
suggested using a more recent version because of performance improvements suggested using a more recent version because of performance improvements
@ -1187,7 +1187,7 @@ Django 1.4 takes that policy further and sets 8.2 as the minimum PostgreSQL
version it officially supports. version it officially supports.
Request exceptions are now always logged Request exceptions are now always logged
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------
When we added :doc:`logging support </topics/logging/>` in Django in 1.3, the When we added :doc:`logging support </topics/logging/>` in Django in 1.3, the
admin error email support was moved into the admin error email support was moved into the
@ -1227,7 +1227,7 @@ The existence of any ``'filters'`` key under the ``'mail_admins'`` handler will
disable this backward-compatibility shim and deprecation warning. disable this backward-compatibility shim and deprecation warning.
``django.conf.urls.defaults`` ``django.conf.urls.defaults``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
Until Django 1.3, the functions :func:`~django.conf.urls.include`, Until Django 1.3, the functions :func:`~django.conf.urls.include`,
``patterns()`` and :func:`~django.conf.urls.url` plus ``patterns()`` and :func:`~django.conf.urls.url` plus
@ -1237,7 +1237,7 @@ were located in a ``django.conf.urls.defaults`` module.
In Django 1.4, they live in :mod:`django.conf.urls`. In Django 1.4, they live in :mod:`django.conf.urls`.
``django.contrib.databrowse`` ``django.contrib.databrowse``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------
Databrowse has not seen active development for some time, and this does not show Databrowse has not seen active development for some time, and this does not show
any sign of changing. There had been a suggestion for a `GSOC project`_ to any sign of changing. There had been a suggestion for a `GSOC project`_ to
@ -1252,7 +1252,7 @@ itself, so it's available to be adopted by an individual or group as
a third-party project. a third-party project.
``django.core.management.setup_environ`` ``django.core.management.setup_environ``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------------------
This function temporarily modified ``sys.path`` in order to make the parent This function temporarily modified ``sys.path`` in order to make the parent
"project" directory importable under the old flat :djadmin:`startproject` "project" directory importable under the old flat :djadmin:`startproject`
@ -1265,7 +1265,7 @@ These uses should be replaced by setting the ``DJANGO_SETTINGS_MODULE``
environment variable or using :func:`django.conf.settings.configure`. environment variable or using :func:`django.conf.settings.configure`.
``django.core.management.execute_manager`` ``django.core.management.execute_manager``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------
This function was previously used by ``manage.py`` to execute a management This function was previously used by ``manage.py`` to execute a management
command. It is identical to command. It is identical to
@ -1276,7 +1276,7 @@ of these functions is documented as part of the public API, but a deprecation
path is needed due to use in existing ``manage.py`` files. path is needed due to use in existing ``manage.py`` files.
``is_safe`` and ``needs_autoescape`` attributes of template filters ``is_safe`` and ``needs_autoescape`` attributes of template filters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------------------------------
Two flags, ``is_safe`` and ``needs_autoescape``, define how each template filter Two flags, ``is_safe`` and ``needs_autoescape``, define how each template filter
interacts with Django's auto-escaping behavior. They used to be attributes of interacts with Django's auto-escaping behavior. They used to be attributes of
@ -1299,7 +1299,7 @@ Now, the flags are keyword arguments of :meth:`@register.filter
See :ref:`filters and auto-escaping <filters-auto-escaping>` for more information. See :ref:`filters and auto-escaping <filters-auto-escaping>` for more information.
Wildcard expansion of application names in `INSTALLED_APPS` Wildcard expansion of application names in `INSTALLED_APPS`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -----------------------------------------------------------
Until Django 1.3, :setting:`INSTALLED_APPS` accepted wildcards in application Until Django 1.3, :setting:`INSTALLED_APPS` accepted wildcards in application
names, like ``django.contrib.*``. The expansion was performed by a names, like ``django.contrib.*``. The expansion was performed by a
@ -1313,14 +1313,14 @@ settings file to list all your applications explicitly.
.. _this can't be done reliably: https://docs.python.org/tutorial/modules.html#importing-from-a-package .. _this can't be done reliably: https://docs.python.org/tutorial/modules.html#importing-from-a-package
``HttpRequest.raw_post_data`` renamed to ``HttpRequest.body`` ``HttpRequest.raw_post_data`` renamed to ``HttpRequest.body``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -------------------------------------------------------------
This attribute was confusingly named ``HttpRequest.raw_post_data``, but it This attribute was confusingly named ``HttpRequest.raw_post_data``, but it
actually provided the body of the HTTP request. It's been renamed to actually provided the body of the HTTP request. It's been renamed to
``HttpRequest.body``, and ``HttpRequest.raw_post_data`` has been deprecated. ``HttpRequest.body``, and ``HttpRequest.raw_post_data`` has been deprecated.
``django.contrib.sitemaps`` bug fix with potential performance implications ``django.contrib.sitemaps`` bug fix with potential performance implications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---------------------------------------------------------------------------
In previous versions, ``Paginator`` objects used in sitemap classes were In previous versions, ``Paginator`` objects used in sitemap classes were
cached, which could result in stale site maps. We've removed the caching, so cached, which could result in stale site maps. We've removed the caching, so
@ -1332,7 +1332,7 @@ To mitigate the performance impact, consider using the :doc:`caching
framework </topics/cache>` within your ``Sitemap`` subclass. framework </topics/cache>` within your ``Sitemap`` subclass.
Versions of Python-Markdown earlier than 2.1 Versions of Python-Markdown earlier than 2.1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ --------------------------------------------
Versions of Python-Markdown earlier than 2.1 do not support the option to Versions of Python-Markdown earlier than 2.1 do not support the option to
disable attributes. As a security issue, earlier versions of this library will disable attributes. As a security issue, earlier versions of this library will

Some files were not shown because too many files have changed in this diff Show More