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

View File

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

View File

@ -1,8 +1,9 @@
==============
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.
---------------------------------------------------------------------------------------------------------------------------
===========================================================================================================================
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
@ -14,7 +15,7 @@ things:
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.
-----------------------------------------------------------------------------------------------------------------------------------------------------------
===========================================================================================================================================================
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
@ -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.
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
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.
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
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.
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>`
in the "How to use Django with mod_wsgi" documentation.
My "list_filter" contains a ManyToManyField, but the filter doesn't display.
----------------------------------------------------------------------------
============================================================================
Django won't bother displaying the filter for a ``ManyToManyField`` if there
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.
Some objects aren't appearing in the admin.
-------------------------------------------
===========================================
Inconsistent row counts may be caused by missing foreign key values or a
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.
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
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.
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
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.
What browsers are supported for using the admin?
------------------------------------------------
================================================
The admin provides a fully-functional experience to `YUI's A-grade`_ browsers,
with the notable exception of IE6, which is not supported.

View File

@ -1,14 +1,15 @@
======================
FAQ: Contributing code
======================
How can I get started contributing code to Django?
--------------------------------------------------
==================================================
Thanks for asking! We've written an entire document devoted to this question.
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?
--------------------------------------------------------------------------------------------
============================================================================================
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.
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.
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.
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
inclusion in Django, we'll close the ticket. For all the other tickets, we

View File

@ -1,8 +1,9 @@
============
FAQ: General
============
Why does this project exist?
----------------------------
============================
Django grew from a very practical need: World Online, a newspaper Web
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/
What does "Django" mean, and how do you pronounce it?
-----------------------------------------------------
=====================================================
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.
@ -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
Is Django stable?
-----------------
=================
Yes, it's quite stable. Companies like Disqus, Instagram, Pinterest, and
Mozilla have been using Django for many years. Sites built on Django have
weathered traffic spikes of over 50 thousand hits per second.
Does Django scale?
------------------
==================
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.
@ -64,14 +65,14 @@ application layer. And it ships with a simple-yet-powerful
:doc:`cache framework </topics/cache>`.
Who's behind this?
------------------
==================
Django was originally developed at World Online, the Web department of a
newspaper in Lawrence, Kansas, USA. Django's now run by an international
:doc:`team of volunteers </internals/team>`.
Which sites use Django?
-----------------------
=======================
`DjangoSites.org`_ features a constantly growing list of Django-powered sites.
@ -80,7 +81,7 @@ Which sites use Django?
.. _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?
-----------------------------------------------------------------------------------------------------------------------------------------------------
=====================================================================================================================================================
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.
<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 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.
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
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>`.
Is Django a content-management-system (CMS)?
--------------------------------------------
============================================
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.
@ -162,7 +163,7 @@ means!).
.. _Drupal: https://drupal.org/
How can I download the Django documentation to read it offline?
---------------------------------------------------------------
===============================================================
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
@ -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/
Where can I find Django developers for hire?
--------------------------------------------
============================================
Consult our `developers for hire page`_ for a list of Django developers who
would be happy to help you.
@ -190,7 +191,7 @@ https://people.djangoproject.com/ .
.. _developers for hire page: https://code.djangoproject.com/wiki/DevelopersForHire
How do I cite Django?
---------------------
=====================
It's difficult to give an official citation format, for two reasons: citation
formats can vary wildly between publications, and citation standards for

View File

@ -1,8 +1,9 @@
=================
FAQ: Getting 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
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:
Why hasn't my message appeared on django-users?
-----------------------------------------------
===============================================
|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.
@ -30,7 +31,7 @@ list might take a little longer to get answered. We apologize for any
inconvenience that this policy may cause.
Nobody on django-users answered my question! What should I do?
--------------------------------------------------------------
==============================================================
Try making your question more specific, or provide a better example of your
problem.
@ -48,13 +49,13 @@ for discussion of the development of Django itself. Asking a tech support
question there is considered quite impolite.
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
:ref:`Guide to contributing to Django <reporting-bugs>`.
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
to security@djangoproject.com. This is a private list only open to long-time,

View File

@ -1,8 +1,9 @@
=================
FAQ: Installation
=================
How do I get started?
---------------------
=====================
#. `Download the code`_.
#. 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/
What are Django's prerequisites?
--------------------------------
================================
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
@ -40,7 +41,7 @@ PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported.
.. _faq-python-version-support:
What Python version can I use with Django?
------------------------------------------
==========================================
============== ===============
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.
What Python version should I use with Django?
---------------------------------------------
=============================================
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
@ -81,7 +82,7 @@ Third-party applications for use with Django are, of course, free to set their
own version requirements.
Should I use the stable version or development version?
-------------------------------------------------------
=======================================================
Generally, if you're using code in production, you should be using a
stable release. The Django project publishes a full stable release

View File

@ -1,10 +1,11 @@
=========================
FAQ: Databases and models
=========================
.. _faq-see-raw-sql-queries:
How can I see the raw SQL queries Django is running?
----------------------------------------------------
====================================================
Make sure your Django :setting:`DEBUG` setting is set to ``True``.
Then, just do this::
@ -37,12 +38,12 @@ just call ``reset_queries()``, like this::
reset_queries()
Can I use Django with a pre-existing database?
----------------------------------------------
==============================================
Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`.
If I make changes to a model, how do I update the database?
-----------------------------------------------------------
===========================================================
Take a look at Django's support for :mod:`schema 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.
Do Django models support multiple-column primary keys?
------------------------------------------------------
======================================================
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.
Does Django support NoSQL databases?
------------------------------------
====================================
NoSQL databases are not officially supported by Django itself. There are,
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
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
database-specific options such as table type, etc. If you'd like to use any of

View File

@ -1,8 +1,9 @@
=================
FAQ: Using Django
=================
Why do I get an error about importing DJANGO_SETTINGS_MODULE?
-------------------------------------------------------------
=============================================================
Make sure that:
@ -14,7 +15,7 @@ Make sure that:
* The module doesn't contain syntax errors (of course).
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,
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.
Do I have to use your model/database layer?
-------------------------------------------
===========================================
Nope. Just like the template system, the model/database layer is decoupled from
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.
How do I use image and file fields?
-----------------------------------
===================================
Using a :class:`~django.db.models.FileField` or an
:class:`~django.db.models.ImageField` in a model takes a few steps:
@ -58,7 +59,7 @@ Using a :class:`~django.db.models.FileField` or an
``{{ object.mug_shot.url }}``.
How do I make a variable available to all my templates?
-------------------------------------------------------
=======================================================
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

View File

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

View File

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

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`.
A simple lookup example
~~~~~~~~~~~~~~~~~~~~~~~
=======================
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')``
@ -93,7 +93,7 @@ the parameters for the query. We then return a tuple containing the generated
SQL string and the parameters.
A simple transformer example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
============================
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
@ -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
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
indexes efficiently in some cases. In particular, when we use
@ -211,7 +211,7 @@ transformations in Python.
be very efficient.
A bilateral transformer example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
===============================
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
@ -248,7 +248,7 @@ insensitive query like this::
SELECT ... WHERE UPPER("author"."name") = UPPER('doe')
Writing alternative implementations for existing lookups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
========================================================
Sometimes different database vendors require different SQL for the same
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``.
How Django determines the lookups and transforms which are used
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
===============================================================
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

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.
Code layout
-----------
===========
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
@ -89,7 +89,7 @@ an application.
.. _howto-writing-custom-template-filters:
Writing custom template filters
-------------------------------
===============================
Custom filters are just Python functions that take one or two arguments:
@ -127,7 +127,7 @@ your function. Example::
return value.lower()
Registering custom filters
~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------
.. 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.
Template filters that expect strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------
.. method:: django.template.defaultfilters.stringfilter()
@ -187,7 +187,7 @@ methods).
.. _filters-auto-escaping:
Filters and auto-escaping
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
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
@ -376,7 +376,7 @@ Template filter code falls into one of two situations:
.. _filters-timezones:
Filters and time zones
~~~~~~~~~~~~~~~~~~~~~~
----------------------
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
@ -397,7 +397,7 @@ conversions in templates <time-zones-in-templates>`.
.. _howto-writing-custom-template-tags:
Writing custom template tags
----------------------------
============================
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.
@ -407,7 +407,7 @@ scratch for those cases when the shortcuts aren't powerful enough.
.. _howto-custom-template-tags-simple-tags:
Simple tags
~~~~~~~~~~~
-----------
.. method:: django.template.Library.simple_tag()
@ -514,7 +514,7 @@ you see fit:
.. _howto-custom-template-tags-inclusion-tags:
Inclusion tags
~~~~~~~~~~~~~~
--------------
.. 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 %}
Assignment tags
~~~~~~~~~~~~~~~
---------------
.. 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>
Advanced custom template tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------
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
a template tag from the ground up.
A quick overview
~~~~~~~~~~~~~~~~
----------------
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
@ -702,7 +702,7 @@ converted into a ``Node`` (the compilation function), and what the node's
``render()`` method does.
Writing the compilation function
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------
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
@ -772,7 +772,7 @@ Notes:
engine too slow. It's low-level because that's fastest.
Writing the renderer
~~~~~~~~~~~~~~~~~~~~
--------------------
The second step in writing custom tags is to define a ``Node`` subclass that
has a ``render()`` method.
@ -811,7 +811,7 @@ without having to be parsed multiple times.
.. _tags-auto-escaping:
Auto-escaping considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
The output from template tags is **not** automatically run through the
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:
Thread-safety considerations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
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
@ -936,7 +936,7 @@ like the current iteration of the ``CycleNode``, should be stored in the
variables, make ``render_context[self]`` a dictionary.
Registering the tag
~~~~~~~~~~~~~~~~~~~
-------------------
Finally, register the tag with your module's ``Library`` instance, as explained
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.
Passing template variables to the tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------
Although you can pass any number of arguments to a template tag using
``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.
Setting a variable in the context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------
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,
@ -1123,7 +1123,7 @@ context-updating template tag, consider using the
the tag results to a template variable.
Parsing until another block tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------
Template tags can work in tandem. For instance, the standard
: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.
Parsing until another block tag, and saving contents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------------------
In the previous example, ``do_comment()`` discarded everything between
``{% comment %}`` and ``{% endcomment %}``. Instead of doing that, it's

View File

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

View File

@ -22,7 +22,7 @@ Django includes getting-started documentation for the following WSGI servers:
uwsgi
The ``application`` object
--------------------------
==========================
The key concept of deploying with WSGI is the ``application`` callable which
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`.
Configuring the settings module
-------------------------------
===============================
When the WSGI server loads your application, Django needs to import the
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
------------------------
========================
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`::

View File

@ -1,3 +1,4 @@
===============
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.
Email reports
-------------
=============
Server errors
~~~~~~~~~~~~~
-------------
When :setting:`DEBUG` is ``False``, Django will email the users listed in the
: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>`.
404 errors
~~~~~~~~~~
----------
Django can also be configured to email errors about broken links (404 "page
not found" errors). Django sends emails about 404 errors when:
@ -119,7 +120,7 @@ and override its methods.
.. _filtering-error-reports:
Filtering error reports
-----------------------
=======================
.. warning::
@ -130,7 +131,7 @@ Filtering error reports
through email).
Filtering sensitive information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------
.. 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
~~~~~~~~~~~~~~~~~~~~
--------------------
All :func:`sensitive_variables` and :func:`sensitive_post_parameters` do is,
respectively, annotate the decorated function with the names of sensitive

View File

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

View File

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

View File

@ -9,7 +9,7 @@ migrations, see :doc:`the topic guide </topics/migrations>`.
.. _data-migrations-and-multiple-databases:
Data migrations and multiple databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
======================================
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
@ -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.
Migrations that add unique fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
=================================
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
@ -185,7 +185,7 @@ the respective field according to your needs.
``RunPython`` will have their original ``uuid``s overwritten.
Controlling the order of migrations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
===================================
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

View File

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

View File

@ -32,7 +32,7 @@ general points:
.. _reporting-bugs:
Reporting bugs
--------------
==============
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
@ -61,7 +61,7 @@ To understand the lifecycle of your ticket once you have created it, refer to
:doc:`triaging-tickets`.
Reporting user interface bugs and features
------------------------------------------
==========================================
If your bug or feature request touches on anything visual in nature, there
are a few additional guidelines to follow:
@ -87,7 +87,7 @@ are a few additional guidelines to follow:
find your ticket.
Requesting features
-------------------
===================
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:
@ -128,7 +128,7 @@ See also: :ref:`documenting-new-features`.
.. _how-we-make-decisions:
How we make decisions
---------------------
=====================
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

View File

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

View File

@ -9,7 +9,7 @@ and localization infrastructure available to Django applications, described in
the :doc:`i18n documentation </topics/i18n/index>`.
Translations
------------
============
Translations are contributed by Django users worldwide. The translation work is
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!
Formats
-------
=======
You can also review ``conf/locale/<locale>/formats.py``. This file describes
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
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:
Documentation
-------------
=============
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

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.
First steps
-----------
===========
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
----------
==========
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.
@ -138,7 +138,7 @@ some advice to make your work on Django more useful and rewarding.
.. _new-contributors-faq:
FAQ
---
===
1. **This ticket I care about has been ignored for days/weeks/months! What can
I do to get it committed?**

View File

@ -32,7 +32,7 @@ Django is a community project, and every contribution helps. We can't do this
without **you**!
Triage workflow
---------------
===============
Unfortunately, not all bug reports and feature requests in the ticket tracker
provide all the :doc:`required details<bugs-and-features>`. A number of
@ -96,20 +96,20 @@ require much much more.
.. _triage-stages:
Triage stages
-------------
=============
Below we describe in more detail the various stages that a ticket may flow
through during its lifetime.
Unreviewed
~~~~~~~~~~
----------
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,
or ought to be closed for any of the various reasons.
Accepted
~~~~~~~~
--------
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.
@ -142,7 +142,7 @@ Beyond that there are several considerations:
explaining what is needed to improve the code.
Ready For Checkin
~~~~~~~~~~~~~~~~~
-----------------
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
@ -152,7 +152,7 @@ review prior to being committed. See the
RFC forever! What should I do?"
Someday/Maybe
~~~~~~~~~~~~~
-------------
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.
@ -163,12 +163,12 @@ consider adding someday to the framework if an excellent patch is submitted.
They are not a high priority.
Other triage attributes
-----------------------
=======================
A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
Has patch
~~~~~~~~~
---------
This means the ticket has an associated
: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.
Needs documentation
~~~~~~~~~~~~~~~~~~~
-------------------
This flag is used for tickets with patches that need associated
documentation. Complete documentation of features is a prerequisite
before we can check them into the codebase.
Needs tests
~~~~~~~~~~~
-----------
This flags the patch as needing associated unit tests. Again, this
is a required part of a valid patch.
Patch needs improvement
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
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
@ -199,12 +199,12 @@ cleanly, there is a flaw in the implementation, or that the code
doesn't meet our standards.
Easy pickings
~~~~~~~~~~~~~
-------------
Tickets that would require small, easy, patches.
Type
~~~~
----
Tickets should be categorized by *type* between:
@ -219,14 +219,14 @@ Tickets should be categorized by *type* between:
better, faster, stronger.
Component
~~~~~~~~~
---------
Tickets should be classified into *components* indicating which area of
the Django codebase they belong to. This makes tickets better organized and
easier to find.
Severity
~~~~~~~~
--------
The *severity* attribute is used to identify blockers, that is, issues which
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".
Version
~~~~~~~
-------
It is possible to use the *version* attribute to indicate in which
version the reported bug was identified.
UI/UX
~~~~~
-----
This flag is used for tickets that relate to User Interface and User
Experiences questions. For example, this flag would be appropriate for
user-facing features in forms or the admin interface.
Cc
~~
--
You may add your username or email address to this field to be notified when
new contributions are made to the ticket.
Keywords
~~~~~~~~
--------
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
@ -266,7 +266,7 @@ as "formset", "modelformset", and "ManagementForm".
.. _closing-tickets:
Closing Tickets
---------------
===============
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
@ -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?
-----------------------------
=============================
The triage process is primarily driven by community members. Really,
**ANYONE** can help.
@ -422,7 +422,7 @@ the ticket database:
.. _password reset page: https://www.djangoproject.com/accounts/password/reset/
Bisecting a regression
----------------------
======================
.. highlight:: console

View File

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

View File

@ -9,7 +9,7 @@ Please follow these coding standards when writing JavaScript code for inclusion
in Django.
Code style
----------
==========
* Please conform to the indentation style dictated in the ``.editorconfig``
file. We recommend using a text editor with `EditorConfig`_ support to avoid
@ -27,7 +27,7 @@ Code style
.. _javascript-patches:
JavaScript patches
------------------
==================
Django's admin system leverages the jQuery framework to increase the
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.
Compressing JavaScript
~~~~~~~~~~~~~~~~~~~~~~
----------------------
To simplify the process of providing optimized JavaScript code, Django
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.
JavaScript tests
----------------
================
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.
Writing tests
~~~~~~~~~~~~~
-------------
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/>`_.
Running tests
~~~~~~~~~~~~~
-------------
The JavaScript tests may be run from a web browser or from the command line.
Testing from a web browser
^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~
To run the tests from a web browser, open up ``js_tests/tests.html`` in your
browser.
@ -119,7 +119,7 @@ over HTTP. To view code coverage:
* Open http://localhost:8000/js_tests/tests.html in your web browser.
Testing from the command line
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To run the tests from the command line, you need to have `Node.js`_ installed.

View File

@ -7,7 +7,7 @@ with associated patches will get fixed *far* more quickly than those
without patches.
Typo fixes and trivial documentation changes
--------------------------------------------
============================================
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
@ -16,7 +16,7 @@ requests without a Trac ticket.
See the :doc:`working-with-git` for more details on how to use pull requests.
"Claiming" tickets
------------------
==================
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
@ -62,7 +62,7 @@ and time availability), claim it by following these steps:
.. _Contributor License Agreement: https://www.djangoproject.com/foundation/cla/
Ticket claimers' responsibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------
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
@ -80,7 +80,7 @@ your claim on the ticket may be revoked.
As always, more communication is better than less communication!
Which tickets should be claimed?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------
Of course, going through the steps of claiming tickets is overkill in some
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
-----------
===========
Make sure that any contribution you do fulfills at least the following
requirements:
@ -143,7 +143,7 @@ Regardless of the way you submit your work, follow these steps.
.. _Development dashboard: https://dashboard.djangoproject.com/
Non-trivial patches
-------------------
===================
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.
@ -157,7 +157,7 @@ ask.
.. _deprecating-a-feature:
Deprecating a feature
---------------------
=====================
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.
JavaScript patches
------------------
==================
For information on JavaScript patches, see the :ref:`javascript-patches`
documentation.
@ -241,7 +241,7 @@ documentation.
.. _patch-review-checklist:
Patch review checklist
----------------------
======================
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
@ -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.
Documentation
~~~~~~~~~~~~~
-------------
* Does the documentation build without any errors (``make html``, or
``make.bat html`` on Windows, from the ``docs`` directory)?
@ -269,13 +269,13 @@ Documentation
* Are there any :ref:`spelling errors <documentation-spelling-check>`?
Bugs
~~~~
----
* Is there a proper regression test (the test should fail before the fix
is applied)?
New Features
~~~~~~~~~~~~
------------
* Are there tests to "exercise" all of the new code?
* Is there a release note in ``docs/releases/A.B.txt``?
@ -284,12 +284,12 @@ New Features
``.. versionadded:: A.B`` or ``.. versionchanged:: A.B``?
Deprecating a feature
~~~~~~~~~~~~~~~~~~~~~
---------------------
See the :ref:`deprecating-a-feature` guide.
All code changes
~~~~~~~~~~~~~~~~
----------------
* Does the :doc:`coding style
</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.
All tickets
~~~~~~~~~~~
-----------
* Is the pull request a single squashed commit with a message that follows our
:ref:`commit message format <committing-guidelines>`?

View File

@ -16,10 +16,10 @@ how to write new tests.
.. _running-unit-tests:
Running the unit tests
----------------------
======================
Quickstart
~~~~~~~~~~
----------
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
@ -48,7 +48,7 @@ Having problems? See :ref:`troubleshooting-unit-tests` for some common issues.
.. _running-unit-tests-settings:
Using another ``settings`` module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------
The included settings module allows you to run the test suite using
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:
Running only some of the tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------
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
@ -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
Running the Selenium tests
~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------
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
@ -131,7 +131,7 @@ install the selenium_ package into your Python path and run the tests with the
.. _running-unit-tests-dependencies:
Running all the tests
~~~~~~~~~~~~~~~~~~~~~
---------------------
If you want to run the full suite of tests, you'll need to install a number of
dependencies:
@ -188,7 +188,7 @@ associated tests will be skipped.
.. _pip requirements files: https://pip.pypa.io/en/latest/user_guide.html#requirements-files
Code coverage
~~~~~~~~~~~~~
-------------
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
@ -211,7 +211,7 @@ and also excludes several directories not relevant to the results
.. _contrib-apps:
Contrib apps
------------
============
Tests for contrib apps can be found in the ``tests/`` directory, typically
under ``<app_name>_tests``. For example, tests for ``contrib.auth`` are located
@ -220,10 +220,10 @@ in ``tests/auth_tests``.
.. _troubleshooting-unit-tests:
Troubleshooting
---------------
===============
Many test failures with ``UnicodeEncodeError``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------------
If the ``locales`` package is not installed, some tests will fail with a
``UnicodeEncodeError``.
@ -234,7 +234,7 @@ You can resolve this on Debian-based systems, for example, by running::
$ dpkg-reconfigure locales
Tests that only fail in combination
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------
In case a test passes when run in isolation but fails within the whole suite,
we have some tools to help analyze the problem.
@ -279,7 +279,7 @@ cause any trouble::
$ ./runtests.py basic --reverse
Seeing the SQL queries run during a test
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------
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
@ -288,7 +288,7 @@ combine this with ``--verbosity=2``, all SQL queries will be output::
$ ./runtests.py basic --debug-sql
Seeing the full traceback of a test failure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------
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

View File

@ -1,3 +1,4 @@
===========================
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.
Installing Git
--------------
==============
Django uses `Git`_ for its source control. You can `download
<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/
Setting up local repository
---------------------------
===========================
When you have created your GitHub account, with the nick "GitHub_nick", and
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
Working on a ticket
-------------------
===================
When working on a ticket create a new branch for the work, and base that work
on upstream/master::
@ -94,7 +95,7 @@ necessary::
git commit -m 'Added two more tests for edge cases'
Publishing work
~~~~~~~~~~~~~~~
---------------
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.
Rebasing branches
~~~~~~~~~~~~~~~~~
-----------------
In the example above you created two commits, the "Fixed ticket_xxxxx" 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.
After upstream has changed
~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------
When upstream (django/django) has changed, you should rebase your work. To
do this, use::
@ -215,7 +216,7 @@ This way your branch will contain only commits related to its topic, which
makes squashing easier.
After review
~~~~~~~~~~~~
------------
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
@ -247,7 +248,7 @@ Note that the committer is likely to squash the review commit into the previous
commit when committing the code.
Working on a patch
------------------
==================
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
@ -264,7 +265,7 @@ For more detail on working with pull requests see the
:ref:`guidelines for committers <handling-pull-requests>`.
Summary
-------
=======
* Work on GitHub if you can.
* Announce your work on the Trac ticket by linking to your GitHub branch.

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.
Getting the raw documentation
-----------------------------
=============================
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
@ -36,7 +36,7 @@ to have the docs for the last release be up-to-date and correct (see
:ref:`differences-between-doc-versions`).
Getting started with Sphinx
---------------------------
===========================
Django's documentation uses the Sphinx__ documentation system, which in turn
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.
How the documentation is organized
----------------------------------
==================================
The documentation is organized into several categories:
@ -117,7 +117,7 @@ The documentation is organized into several categories:
repeat the same material.
Writing style
-------------
=============
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.
@ -130,7 +130,7 @@ Instead of:
* himself or herself... use themselves.
Commonly used terms
-------------------
===================
Here are some style guidelines on commonly used terms throughout the
documentation:
@ -160,7 +160,7 @@ documentation:
* **website** -- use one word, without capitalization.
Django-specific terminology
---------------------------
===========================
* **model** -- it's not capitalized.
@ -172,7 +172,7 @@ Django-specific terminology
* **view** -- it's not capitalized.
Guidelines for reStructuredText files
-------------------------------------
=====================================
These guidelines regulate the format of our reST (reStructuredText)
documentation:
@ -199,8 +199,26 @@ documentation:
* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
documentation.
* Use these heading styles::
===
One
===
Two
===
Three
-----
Four
~~~~
Five
^^^^
Django-specific markup
----------------------
======================
Besides the `Sphinx built-in markup`__, Django's docs defines some extra
description units:
@ -251,7 +269,7 @@ __ http://sphinx-doc.org/markup/
.. _documenting-new-features:
Documenting new features
------------------------
========================
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.
Minimizing images
-----------------
=================
Optimize image compression where possible. For PNG files, use OptiPNG and
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.
An example
----------
==========
For a quick example of how it all fits together, consider this hypothetical
example:
@ -377,7 +395,7 @@ example:
.. setting:: ADMINS
ADMINS
------
======
Default: ``[]`` (Empty list)
@ -400,7 +418,7 @@ That's basically how everything fits together.
.. _improving-the-documentation:
Improving the documentation
---------------------------
===========================
A few small improvements can be made to make the documentation read and
look better:
@ -451,7 +469,7 @@ look better:
.. _documentation-spelling-check:
Spelling check
--------------
==============
Before you commit your docs, it's a good idea to run the spelling checker.
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).
Translating documentation
-------------------------
=========================
See :ref:`Localizing the Django documentation <translating-documentation>` if
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`` man page
-------------------------
=========================
Sphinx can generate a manual page for the
:doc:`django-admin </ref/django-admin>` command. This is configured in

View File

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

View File

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

View File

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

View File

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

View File

@ -1,3 +1,4 @@
===================
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.
Install Python
--------------
==============
Being a Python Web framework, Django requires Python. See
:ref:`faq-python-version-support` for details. Python includes a lightweight
@ -34,21 +35,21 @@ you should see something like::
>>>
Set up a database
-----------------
=================
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
:ref:`database installation information <database-installation>`.
Remove any old versions of Django
---------------------------------
=================================
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
version <removing-old-versions-of-django>`.
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
---------
=========
To verify that Django can be seen by Python, type ``python`` from your shell.
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.
That's it!
----------
==========
That's it -- you can now :doc:`move onto the tutorial </intro/tutorial01>`.

View File

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

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.
View
----
====
.. class:: django.views.generic.base.View
@ -103,7 +103,7 @@ View
list of the allowed HTTP method names for the view.
TemplateView
------------
============
.. class:: django.views.generic.base.TemplateView
@ -155,7 +155,7 @@ TemplateView
the keyword arguments captured from the URL pattern that served the view.
RedirectView
------------
============
.. class:: django.views.generic.base.RedirectView

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>`
Simple generic views
--------------------
====================
View
~~~~
----
.. class:: View()
**Attributes** (with optional accessor):
@ -27,7 +27,7 @@ View
* :meth:`~django.views.generic.base.View.http_method_not_allowed`
TemplateView
~~~~~~~~~~~~
------------
.. class:: TemplateView()
**Attributes** (with optional accessor):
@ -49,7 +49,7 @@ TemplateView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
RedirectView
~~~~~~~~~~~~
------------
.. class:: RedirectView()
**Attributes** (with optional accessor):
@ -73,10 +73,10 @@ RedirectView
* ``put()``
Detail Views
------------
============
DetailView
~~~~~~~~~~
----------
.. class:: DetailView()
**Attributes** (with optional accessor):
@ -107,10 +107,10 @@ DetailView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
List Views
----------
==========
ListView
~~~~~~~~
--------
.. class:: ListView()
**Attributes** (with optional accessor):
@ -143,10 +143,10 @@ ListView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
Editing views
-------------
=============
FormView
~~~~~~~~
--------
.. class:: FormView()
**Attributes** (with optional accessor):
@ -176,7 +176,7 @@ FormView
* :meth:`~django.views.generic.edit.ProcessFormView.put`
CreateView
~~~~~~~~~~
----------
.. class:: CreateView()
**Attributes** (with optional accessor):
@ -218,7 +218,7 @@ CreateView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
UpdateView
~~~~~~~~~~
----------
.. class:: UpdateView()
**Attributes** (with optional accessor):
@ -260,7 +260,7 @@ UpdateView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
DeleteView
~~~~~~~~~~
----------
.. class:: DeleteView()
**Attributes** (with optional accessor):
@ -294,10 +294,10 @@ DeleteView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
Date-based views
----------------
================
ArchiveIndexView
~~~~~~~~~~~~~~~~
----------------
.. class:: ArchiveIndexView()
**Attributes** (with optional accessor):
@ -335,7 +335,7 @@ ArchiveIndexView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
YearArchiveView
~~~~~~~~~~~~~~~
---------------
.. class:: YearArchiveView()
**Attributes** (with optional accessor):
@ -376,7 +376,7 @@ YearArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
MonthArchiveView
~~~~~~~~~~~~~~~~
----------------
.. class:: MonthArchiveView()
**Attributes** (with optional accessor):
@ -420,7 +420,7 @@ MonthArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
WeekArchiveView
~~~~~~~~~~~~~~~
---------------
.. class:: WeekArchiveView()
**Attributes** (with optional accessor):
@ -462,7 +462,7 @@ WeekArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
DayArchiveView
~~~~~~~~~~~~~~
--------------
.. class:: DayArchiveView()
**Attributes** (with optional accessor):
@ -510,7 +510,7 @@ DayArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
TodayArchiveView
~~~~~~~~~~~~~~~~
----------------
.. class:: TodayArchiveView()
**Attributes** (with optional accessor):
@ -558,7 +558,7 @@ TodayArchiveView
* :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
DateDetailView
~~~~~~~~~~~~~~
--------------
.. class:: DateDetailView()
**Attributes** (with optional accessor):

View File

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

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.
DetailView
----------
==========
.. class:: django.views.generic.detail.DetailView
@ -73,7 +73,7 @@ DetailView
<p>Date: {{ now|date }}</p>
ListView
--------
========
.. class:: django.views.generic.list.ListView

View File

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

View File

@ -16,7 +16,7 @@ Class-based views API reference. For introductory material, see the
flattened-index
Specification
-------------
=============
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
@ -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).
Base vs Generic views
---------------------
=====================
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

View File

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

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`.
FormMixin
---------
=========
.. class:: django.views.generic.edit.FormMixin
@ -95,7 +95,7 @@ FormMixin
name 'form'.
ModelFormMixin
--------------
==============
.. class:: django.views.generic.edit.ModelFormMixin
@ -181,7 +181,7 @@ ModelFormMixin
ProcessFormView
---------------
===============
.. class:: django.views.generic.edit.ProcessFormView
@ -221,7 +221,7 @@ ProcessFormView
DeletionMixin
-------------
=============
.. class:: django.views.generic.edit.DeletionMixin

View File

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

View File

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

View File

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

View File

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

View File

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

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.
``srid``
~~~~~~~~
--------
.. attribute:: Field.srid
@ -28,7 +28,7 @@ GeoDjango form fields take the following optional arguments.
input values into that SRID.
``geom_type``
~~~~~~~~~~~~~
-------------
.. attribute:: Field.geom_type
@ -40,42 +40,42 @@ Form field classes
==================
``GeometryField``
~~~~~~~~~~~~~~~~~
-----------------
.. class:: GeometryField
``PointField``
~~~~~~~~~~~~~~
--------------
.. class:: PointField
``LineStringField``
~~~~~~~~~~~~~~~~~~~
-------------------
.. class:: LineStringField
``PolygonField``
~~~~~~~~~~~~~~~~
----------------
.. class:: PolygonField
``MultiPointField``
~~~~~~~~~~~~~~~~~~~
-------------------
.. class:: MultiPointField
``MultiLineStringField``
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
.. class:: MultiLineStringField
``MultiPolygonField``
~~~~~~~~~~~~~~~~~~~~~
---------------------
.. class:: MultiPolygonField
``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.
Widget attributes
~~~~~~~~~~~~~~~~~
-----------------
GeoDjango widgets are template-based, so their attributes are mostly different
from other Django widget attributes.
@ -134,7 +134,7 @@ widget. For example::
forms.OSMWidget(attrs={'map_width': 800, 'map_height': 500}))
Widget classes
~~~~~~~~~~~~~~
--------------
``BaseGeometryWidget``

View File

@ -36,7 +36,7 @@ Measurement Relationships Operations Editors
================== ======================= ====================== =================== ================== =====================
Area
----
====
.. 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.
AsGeoJSON
---------
=========
.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
@ -80,7 +80,7 @@ Keyword Argument Description
===================== =====================================================
AsGML
-----
=====
.. class:: AsGML(expression, version=2, precision=8, **extra)
@ -111,7 +111,7 @@ Keyword Argument Description
__ https://en.wikipedia.org/wiki/Geography_Markup_Language
AsKML
-----
=====
.. class:: AsKML(expression, precision=8, **extra)
@ -138,7 +138,7 @@ Keyword Argument Description
__ https://developers.google.com/kml/documentation/
AsSVG
-----
=====
.. class:: AsSVG(expression, relative=False, precision=8, **extra)
@ -162,7 +162,7 @@ Keyword Argument Description
__ http://www.w3.org/Graphics/SVG/
BoundingCircle
--------------
==============
.. 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.
Centroid
--------
========
.. class:: Centroid(expression, **extra)
@ -182,7 +182,7 @@ Accepts a single geographic field or expression and returns the ``centroid``
value of the geometry.
Difference
----------
==========
.. class:: Difference(expr1, expr2, **extra)
@ -197,7 +197,7 @@ geometry B.
MySQL support was added.
Distance
--------
========
.. class:: Distance(expr1, expr2, spheroid=None, **extra)
@ -241,7 +241,7 @@ queryset is calculated::
:ref:`supported_units`.
Envelope
--------
========
.. 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.
ForceRHR
--------
========
.. class:: ForceRHR(expression, **extra)
@ -262,7 +262,7 @@ of the polygon/multipolygon in which all of the vertices follow the
right-hand rule.
GeoHash
-------
=======
.. class:: GeoHash(expression, **extra)
@ -278,7 +278,7 @@ representation of the geometry.
__ https://en.wikipedia.org/wiki/Geohash
Intersection
------------
============
.. class:: Intersection(expr1, expr2, **extra)
@ -292,7 +292,7 @@ intersection between them.
MySQL support was added.
Length
------
======
.. 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.
MemSize
-------
=======
.. 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.
NumGeometries
-------------
=============
.. 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``.
NumPoints
---------
=========
.. 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``.
Perimeter
---------
=========
.. 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.
PointOnSurface
--------------
==============
.. 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``.
Reverse
-------
=======
.. class:: Reverse(expression, **extra)
@ -372,7 +372,7 @@ Accepts a single geographic field or expression and returns a geometry with
reversed coordinates.
Scale
-----
=====
.. 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.
SnapToGrid
----------
==========
.. class:: SnapToGrid(expression, *args, **extra)
@ -403,7 +403,7 @@ Number of Arguments Description
=================== =====================================================
SymDifference
-------------
=============
.. class:: SymDifference(expr1, expr2, **extra)
@ -418,7 +418,7 @@ parameters.
MySQL support was added.
Transform
---------
=========
.. 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.
Translate
---------
=========
.. 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.
Union
-----
=====
.. class:: Union(expr1, expr2, **extra)

View File

@ -120,10 +120,10 @@ script, compile, and install::
$ cd ..
Troubleshooting
^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~
Can't find GEOS library
~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^
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:
``GEOS_LIBRARY_PATH``
~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^
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`
@ -222,10 +222,10 @@ __ https://trac.osgeo.org/gdal/wiki/GdalOgrInPython
.. _gdaltrouble:
Troubleshooting
^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~
Can't find GDAL library
~~~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^^^
When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
will be false:
@ -242,7 +242,7 @@ The solution is to properly configure your :ref:`libsettings` *or* set
.. _gdallibrarypath:
``GDAL_LIBRARY_PATH``
~~~~~~~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^^^^^^^
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`

View File

@ -129,7 +129,7 @@ an environment variable, or by configuring the library path for the entire
system.
``LD_LIBRARY_PATH`` environment variable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A user may set this environment variable to customize the library paths
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
Setting system library path
^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~
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``.
@ -160,7 +160,7 @@ modifying the system library path::
.. _binutils:
Install ``binutils``
^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~
GeoDjango uses the ``find_library`` function (from the ``ctypes.util`` Python
module) to discover libraries. The ``find_library`` routine uses a program
@ -203,7 +203,7 @@ Foundation, however, this is not required.
.. _macosx_python:
Python
^^^^^^
~~~~~~
Although OS X comes with Python installed, users can use `framework
installers`__ provided by the Python Software Foundation. An advantage to
@ -223,7 +223,7 @@ __ https://www.python.org/ftp/python/
.. _postgresapp:
Postgres.app
^^^^^^^^^^^^
~~~~~~~~~~~~
`Postgres.app <http://postgresapp.com/>`_ is a standalone PostgreSQL server
that includes the PostGIS extension. You will also need to install ``gdal`` and
@ -243,7 +243,7 @@ terminal prompt.
.. _homebrew:
Homebrew
^^^^^^^^
~~~~~~~~
`Homebrew`__ provides "recipes" for building binaries and packages from source.
It provides recipes for the GeoDjango prerequisites on Macintosh computers
@ -263,7 +263,7 @@ __ http://brew.sh/
.. _kyngchaos:
KyngChaos packages
^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~
William Kyngesburye provides a number of `geospatial library binary packages`__
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
~~~~~~~~
^^^^^^^^
After you've installed the KyngChaos binaries and modified your ``PATH``, as
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`__ may be used to install GeoDjango prerequisites on Macintosh
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.
Python
^^^^^^
~~~~~~
First, download the latest `Python 2.7 installer`__ from the Python website.
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/
PostgreSQL
^^^^^^^^^^
~~~~~~~~~~
First, download the latest `PostgreSQL 9.x installer`__ from the
`EnterpriseDB`__ website. After downloading, simply run the installer,
@ -427,7 +427,7 @@ __ http://www.enterprisedb.com
.. _postgisasb:
PostGIS
^^^^^^^
~~~~~~~
From within the Application Stack Builder (to run outside of the installer,
:menuselection:`Start --> Programs --> PostgreSQL 9.x`), select
@ -446,7 +446,7 @@ default PostGIS database).
password in the 'Database Connection Information' dialog.
psycopg2
^^^^^^^^
~~~~~~~~
The ``psycopg2`` Python module provides the interface between Python and the
PostgreSQL database. Download the latest `Windows installer`__ for your version
@ -457,7 +457,7 @@ __ http://www.stickpeople.com/projects/python/win-psycopg/
.. _osgeo4w:
OSGeo4W
^^^^^^^
~~~~~~~
The `OSGeo4W installer`_ makes it simple to install the PROJ.4, GDAL, and GEOS
libraries required by GeoDjango. First, download the `OSGeo4W installer`_,
@ -471,7 +471,7 @@ installer.
.. _OSGeo4W installer: https://trac.osgeo.org/osgeo4w/
Modify Windows environment
^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~
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``
@ -506,7 +506,7 @@ script, :download:`geodjango_setup.bat`.
variables accordingly.
Install Django and set up database
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Finally, :ref:`install Django <installing-official-release>` on your system.

View File

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

View File

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

View File

@ -20,7 +20,7 @@ Settings
.. setting:: POSTGIS_VERSION
``POSTGIS_VERSION``
^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~
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
@ -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.
Create database user
^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~
To make a database user with the ability to create databases, use the
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;
Create database superuser
^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~
This may be done at the time the user is created, for example::

View File

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

View File

@ -16,7 +16,7 @@ filters.
.. templatefilter:: apnumber
apnumber
--------
========
For numbers 1-9, returns the number spelled out. Otherwise, returns the
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
intcomma
--------
========
Converts an integer to a string containing commas every three digits.
@ -43,7 +43,7 @@ Examples:
* ``450000`` becomes ``450,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:
* ``45000`` becomes ``'45.000'``.
@ -54,7 +54,7 @@ You can pass in either an integer or a string representation of an integer.
.. templatefilter:: intword
intword
-------
=======
Converts a large integer to a friendly text representation. Works best for
numbers over 1 million.
@ -67,7 +67,7 @@ Examples:
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:
* ``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
naturalday
----------
==========
For dates that are the current day or within one day, return "today",
"tomorrow" or "yesterday", as appropriate. Otherwise, format the date using
@ -98,7 +98,7 @@ Examples (when 'today' is 17 Feb 2007):
.. templatefilter:: naturaltime
naturaltime
-----------
===========
For datetime values, returns a string representing how many seconds,
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
ordinal
-------
=======
Converts an integer to its ordinal as a string.

View File

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

View File

@ -1,3 +1,4 @@
================================
PostgreSQL specific model fields
================================
@ -7,7 +8,7 @@ module.
.. currentmodule:: django.contrib.postgres.fields
ArrayField
----------
==========
.. class:: ArrayField(base_field, size=None, **options)
@ -91,7 +92,7 @@ ArrayField
nullable and the values padded with ``None``.
Querying ArrayField
^^^^^^^^^^^^^^^^^^^
-------------------
There are a number of custom lookups and transforms for :class:`ArrayField`.
We will use the following example model::
@ -242,7 +243,7 @@ lookups available after the transform do not change. For example::
fashion by Django.
Indexing ArrayField
^^^^^^^^^^^^^^^^^^^
-------------------
At present using :attr:`~django.db.models.Field.db_index` will create a
``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.
HStoreField
-----------
===========
.. class:: HStoreField(**options)
@ -292,7 +293,7 @@ HStoreField
:class:`~django.contrib.postgres.validators.KeysValidator`.
Querying HStoreField
^^^^^^^^^^^^^^^^^^^^
--------------------
In addition to the ability to query by key, there are a number of custom
lookups available for ``HStoreField``.
@ -457,7 +458,7 @@ using in conjunction with lookups on
<QuerySet [<Dog: Meg>]>
JSONField
---------
=========
.. versionadded:: 1.9
@ -492,7 +493,7 @@ JSONField
**As a result, this field requires PostgreSQL ≥ 9.4 and Psycopg2 ≥ 2.5.4**.
Querying JSONField
^^^^^^^^^^^^^^^^^^
------------------
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
------------
============
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
@ -588,7 +589,7 @@ information is necessary. The default is lower bound included, upper bound
excluded.
IntegerRangeField
^^^^^^^^^^^^^^^^^
-----------------
.. class:: IntegerRangeField(**options)
@ -598,7 +599,7 @@ IntegerRangeField
Python.
BigIntegerRangeField
^^^^^^^^^^^^^^^^^^^^
--------------------
.. class:: BigIntegerRangeField(**options)
@ -608,7 +609,7 @@ BigIntegerRangeField
Python.
FloatRangeField
^^^^^^^^^^^^^^^
---------------
.. class:: FloatRangeField(**options)
@ -617,7 +618,7 @@ FloatRangeField
database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in Python.
DateTimeRangeField
^^^^^^^^^^^^^^^^^^
------------------
.. class:: DateTimeRangeField(**options)
@ -627,7 +628,7 @@ DateTimeRangeField
Python.
DateRangeField
^^^^^^^^^^^^^^
--------------
.. class:: DateRangeField(**options)
@ -636,7 +637,7 @@ DateRangeField
database and a :class:`~psycopg2:psycopg2.extras.DateRange` in Python.
Querying Range Fields
^^^^^^^^^^^^^^^^^^^^^
---------------------
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
@ -675,7 +676,7 @@ operators ``@>``, ``<@``, and ``&&`` respectively.
.. fieldlookup:: rangefield.contains
contains
''''''''
^^^^^^^^
>>> Event.objects.filter(ages__contains=NumericRange(4, 5))
<QuerySet [<Event: Soft play>]>
@ -683,7 +684,7 @@ contains
.. fieldlookup:: rangefield.contained_by
contained_by
''''''''''''
^^^^^^^^^^^^
>>> Event.objects.filter(ages__contained_by=NumericRange(0, 15))
<QuerySet [<Event: Soft play>]>
@ -707,7 +708,7 @@ contained_by
.. fieldlookup:: rangefield.overlap
overlap
'''''''
^^^^^^^
>>> Event.objects.filter(ages__overlap=NumericRange(8, 12))
<QuerySet [<Event: Soft play>]>
@ -724,7 +725,7 @@ the specific range comparison operators.
.. fieldlookup:: rangefield.fully_lt
fully_lt
''''''''
^^^^^^^^
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
@ -736,7 +737,7 @@ range.
.. fieldlookup:: rangefield.fully_gt
fully_gt
''''''''
^^^^^^^^
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
@ -748,7 +749,7 @@ passed range.
.. fieldlookup:: rangefield.not_lt
not_lt
''''''
^^^^^^
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
@ -760,7 +761,7 @@ passed range.
.. fieldlookup:: rangefield.not_gt
not_gt
''''''
^^^^^^
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
@ -772,7 +773,7 @@ passed range.
.. fieldlookup:: rangefield.adjacent_to
adjacent_to
'''''''''''
^^^^^^^^^^^
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
startswith
''''''''''
^^^^^^^^^^
Returned objects have the given lower bound. Can be chained to valid lookups
for the base field.
@ -799,7 +800,7 @@ for the base field.
.. fieldlookup:: rangefield.endswith
endswith
''''''''
^^^^^^^^
Returned objects have the given upper bound. Can be chained to valid lookups
for the base field.
@ -810,7 +811,7 @@ for the base field.
.. fieldlookup:: rangefield.isempty
isempty
'''''''
^^^^^^^
Returned objects are empty ranges. Can be chained to valid lookups for a
:class:`~django.db.models.BooleanField`.

View File

@ -1,3 +1,4 @@
===========================================
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
Fields
======
SimpleArrayField
----------------
@ -217,10 +221,10 @@ DateRangeField
:class:`~django.contrib.postgres.fields.DateRangeField`.
Widgets
-------
=======
RangeWidget
~~~~~~~~~~~
-----------
.. class:: RangeWidget(base_widget, attrs=None)

View File

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

View File

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

View File

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

View File

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

View File

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

View File

@ -1,10 +1,11 @@
================
File storage API
================
.. module:: django.core.files.storage
Getting 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.
The FileSystemStorage Class
---------------------------
===========================
.. 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.
The Storage Class
-----------------
=================
.. class:: Storage

View File

@ -137,7 +137,7 @@ All file upload handlers should be subclasses of
handlers wherever you wish.
Required 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.
Optional methods
~~~~~~~~~~~~~~~~
----------------
Custom upload handlers may also define any of the following optional methods or
attributes:

View File

@ -13,7 +13,7 @@ The Forms API
.. _ref-forms-api-bound-unbound:
Bound and unbound forms
-----------------------
=======================
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.
Using forms to validate data
----------------------------
============================
.. method:: Form.clean()
@ -201,7 +201,7 @@ This includes ``ValidationError``\s that are raised in :meth:`Form.clean()
"...") <django.forms.Form.add_error>`.
Behavior of unbound forms
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
It's meaningless to validate a form with no data, but, for the record, here's
what happens with unbound forms::
@ -213,7 +213,7 @@ what happens with unbound forms::
{}
Dynamic initial values
----------------------
======================
.. attribute:: Form.initial
@ -249,7 +249,7 @@ precedence::
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
Checking which form data 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))
Accessing the fields from the form
----------------------------------
==================================
.. attribute:: Form.fields
@ -320,7 +320,7 @@ process::
'<tr><th>Username:</th><td><input name="name" type="text" value="class" /></td></tr>'
Accessing "clean" 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:
Outputting forms as HTML
------------------------
========================
The second task of a ``Form`` object is to render itself as HTML. To do so,
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.
``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>
``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>
``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:
Styling required or erroneous form rows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------
.. attribute:: Form.error_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:
Configuring form elements' HTML ``id`` attributes and ``<label>`` tags
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------------------------------------
.. attribute:: Form.auto_id
@ -693,7 +693,7 @@ using the ``label_suffix`` parameter to
:meth:`~django.forms.BoundField.label_tag`.
Notes on field ordering
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
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
@ -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`.
How errors are displayed
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
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
@ -761,7 +761,7 @@ method you're using::
.. _ref-forms-error-list-format:
Customizing the error list format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------
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
@ -785,7 +785,7 @@ Python 2)::
<p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
More granular output
--------------------
====================
The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are simply shortcuts --
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" />
Attributes of ``BoundField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
.. attribute:: BoundField.data
@ -922,7 +922,7 @@ Attributes of ``BoundField``
message
Methods of ``BoundField``
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
.. method:: BoundField.as_hidden(attrs=None, **kwargs)
@ -995,7 +995,7 @@ Methods of ``BoundField``
hi
Customizing ``BoundField``
--------------------------
==========================
.. versionadded:: 1.9
@ -1039,7 +1039,7 @@ Now you can access the country in a template with
.. _binding-uploaded-files:
Binding uploaded files to a form
--------------------------------
================================
Dealing with forms that have ``FileField`` and ``ImageField`` fields
is a little more complicated than a normal form.
@ -1080,7 +1080,7 @@ form data *and* file data::
>>> f = ContactFormWithMugshot()
Testing for multipart forms
~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------
.. method:: Form.is_multipart()
@ -1103,7 +1103,7 @@ Here's an example of how you might use this in a template::
</form>
Subclassing forms
-----------------
=================
If you have multiple ``Form`` classes that share fields, you can use
subclassing to remove redundancy.
@ -1164,7 +1164,7 @@ by setting the name of the field to ``None`` on the subclass. For example::
.. _form-prefix:
Prefixes for forms
------------------
==================
.. attribute:: Form.prefix

View File

@ -33,14 +33,14 @@ exception or returns the clean value::
.. _core-field-arguments:
Core field arguments
--------------------
====================
Each ``Field`` class constructor takes at least these arguments. Some
``Field`` classes take additional, field-specific arguments, but the following
should *always* be accepted:
``required``
~~~~~~~~~~~~
------------
.. attribute:: Field.required
@ -93,7 +93,7 @@ For other ``Field`` classes, it might be ``None``. (This varies from field to
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>
``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>
``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.
``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.
``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>
``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.
``validators``
~~~~~~~~~~~~~~
--------------
.. attribute:: Field.validators
@ -290,18 +290,18 @@ for this field.
See the :doc:`validators documentation </ref/validators>` for more information.
``localize``
~~~~~~~~~~~~
------------
.. attribute:: Field.localize
The ``localize`` argument enables the localization of form data input, as well
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.
``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.
Checking if the field data has changed
--------------------------------------
======================================
``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 ``Field`` classes
--------------------------
==========================
Naturally, the ``forms`` library comes with a set of ``Field`` classes that
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).
``BooleanField``
~~~~~~~~~~~~~~~~
----------------
.. class:: BooleanField(**kwargs)
@ -358,7 +358,7 @@ For each field, we describe the default widget used if you don't specify
creating the ``BooleanField``.
``CharField``
~~~~~~~~~~~~~
-------------
.. class:: CharField(**kwargs)
@ -385,7 +385,7 @@ For each field, we describe the default widget used if you don't specify
trailing whitespace.
``ChoiceField``
~~~~~~~~~~~~~~~
---------------
.. 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.
``TypedChoiceField``
~~~~~~~~~~~~~~~~~~~~
--------------------
.. class:: TypedChoiceField(**kwargs)
@ -442,7 +442,7 @@ For each field, we describe the default widget used if you don't specify
accordingly.
``DateField``
~~~~~~~~~~~~~
-------------
.. 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'
See also :ref:`format localization <format-localization>`.
See also :doc:`format localization </topics/i18n/formatting>`.
``DateTimeField``
~~~~~~~~~~~~~~~~~
-----------------
.. 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'] # '10/25/06'
See also :ref:`format localization <format-localization>`.
See also :doc:`format localization </topics/i18n/formatting>`.
``DecimalField``
~~~~~~~~~~~~~~~~
----------------
.. 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.
``DurationField``
~~~~~~~~~~~~~~~~~
-----------------
.. 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`.
``EmailField``
~~~~~~~~~~~~~~
--------------
.. class:: EmailField(**kwargs)
@ -583,7 +583,7 @@ For each field, we describe the default widget used if you don't specify
given length.
``FileField``
~~~~~~~~~~~~~
-------------
.. 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.
``FilePathField``
~~~~~~~~~~~~~~~~~
-----------------
.. class:: FilePathField(**kwargs)
@ -654,7 +654,7 @@ For each field, we describe the default widget used if you don't specify
``FloatField``
~~~~~~~~~~~~~~
--------------
.. 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.
``ImageField``
~~~~~~~~~~~~~~
--------------
.. 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
``IntegerField``
~~~~~~~~~~~~~~~~
----------------
.. 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.
``GenericIPAddressField``
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
.. 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'``.
``MultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
.. 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`.
``TypedMultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
.. class:: TypedMultipleChoiceField(**kwargs)
@ -801,7 +801,7 @@ For each field, we describe the default widget used if you don't specify
:class:`TypedChoiceField`.
``NullBooleanField``
~~~~~~~~~~~~~~~~~~~~
--------------------
.. 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``).
``RegexField``
~~~~~~~~~~~~~~
--------------
.. class:: RegexField(**kwargs)
@ -840,7 +840,7 @@ For each field, we describe the default widget used if you don't specify
regex validation.
``SlugField``
~~~~~~~~~~~~~
-------------
.. 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``.
``TimeField``
~~~~~~~~~~~~~
-------------
.. 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'
``URLField``
~~~~~~~~~~~~
------------
.. 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``.
``UUIDField``
~~~~~~~~~~~~~
-------------
.. 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.
Slightly complex built-in ``Field`` classes
-------------------------------------------
===========================================
``ComboField``
~~~~~~~~~~~~~~
--------------
.. 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).']
``MultiValueField``
~~~~~~~~~~~~~~~~~~~
-------------------
.. class:: MultiValueField(fields=(), **kwargs)
@ -1033,7 +1033,7 @@ Slightly complex built-in ``Field`` classes
This method must be implemented in the subclasses.
``SplitDateTimeField``
~~~~~~~~~~~~~~~~~~~~~~
----------------------
.. class:: SplitDateTimeField(**kwargs)
@ -1064,7 +1064,7 @@ Slightly complex built-in ``Field`` classes
for :class:`TimeField` are used.
Fields which handle relationships
---------------------------------
=================================
Two fields are available for representing relationships between
models: :class:`ModelChoiceField` and
@ -1087,7 +1087,7 @@ method::
self.fields['foo_select'].queryset = ...
``ModelChoiceField``
~~~~~~~~~~~~~~~~~~~~
--------------------
.. class:: ModelChoiceField(**kwargs)
@ -1180,7 +1180,7 @@ method::
return "My Object #%i" % obj.id
``ModelMultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
.. class:: ModelMultipleChoiceField(**kwargs)
@ -1208,7 +1208,7 @@ method::
user's selection.
Creating custom fields
----------------------
======================
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

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.
See :ref:`formsets` for example usage.
See :doc:`formsets </topics/forms/formsets>` for example usage.

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``,
``can_delete`` and ``validate_max`` are passed through to
:func:`~django.forms.formsets.formset_factory`. See :ref:`formsets` for
details.
:func:`~django.forms.formsets.formset_factory`. See :doc:`formsets
</topics/forms/formsets>` for details.
See :ref:`model-formsets` for example usage.

View File

@ -1,10 +1,9 @@
.. currentmodule:: django.forms
.. _form-and-field-validation:
=========================
Form and field validation
=========================
.. currentmodule:: django.forms
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
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 ``ValidationError``
---------------------------
===========================
In order to make error messages flexible and easy to override, consider the
following guidelines:
@ -184,7 +183,7 @@ greatly benefit from fully featured ``ValidationError``\s (with a ``code`` name
and a ``params`` dictionary).
Raising multiple errors
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
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
@ -206,7 +205,7 @@ with ``code``\s and ``params`` but a list of strings will also work::
])
Using validation in practice
----------------------------
============================
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
@ -216,7 +215,7 @@ previous features.
.. _validators:
Using validators
~~~~~~~~~~~~~~~~
----------------
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
@ -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.
Form field default cleaning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------
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::
@ -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.
Cleaning a specific field attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------
Continuing on from the previous example, suppose that in our ``ContactForm``,
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:
Cleaning and validating fields that depend on each other
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------------------
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

View File

@ -22,7 +22,7 @@ dictionary that corresponds to the widget.
.. _widget-to-field:
Specifying widgets
------------------
==================
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
@ -43,9 +43,8 @@ example::
This would specify a form with a comment that uses a larger :class:`Textarea`
widget, rather than the default :class:`TextInput` widget.
Setting arguments for widgets
-----------------------------
=============================
Many widgets have optional extra arguments; they can be set when defining 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
are available and which arguments they accept.
Widgets inheriting from the Select widget
-----------------------------------------
=========================================
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
@ -96,14 +94,13 @@ example::
>>> choice_field.widget.choices
[('1', 'First and only')]
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` --
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.
Customizing widget instances
----------------------------
============================
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
@ -116,7 +113,7 @@ There are two ways to customize widgets: :ref:`per widget instance
.. _styling-widget-instances:
Styling widget instances
^^^^^^^^^^^^^^^^^^^^^^^^
------------------------
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
@ -167,7 +164,7 @@ You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See
.. _styling-widget-classes:
Styling widget classes
^^^^^^^^^^^^^^^^^^^^^^
----------------------
With widgets, it is possible to add assets (``css`` and ``javascript``)
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 :class:`Widget` and :class:`MultiWidget` are subclassed by
all the :ref:`built-in widgets <built-in widgets>` and may serve as a
foundation for custom widgets.
``Widget``
----------
.. class:: Widget(attrs=None)
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
caching mechanism yourself.
``MultiWidget``
---------------
.. class:: MultiWidget(widgets, attrs=None)
A widget that is composed of multiple widgets.
@ -410,7 +413,7 @@ foundation for custom widgets.
.. _built-in widgets:
Built-in widgets
----------------
================
Django provides a representation of all the basic HTML widgets, plus some
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:
Widgets handling input of text
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
------------------------------
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
format found in :setting:`DATE_INPUT_FORMATS` and respects
:ref:`format-localization`.
:doc:`/topics/i18n/formatting`.
``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
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``.
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
format found in :setting:`TIME_INPUT_FORMATS` and respects
:ref:`format-localization`.
:doc:`/topics/i18n/formatting`.
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 and checkbox widgets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-----------------------------
``CheckboxInput``
~~~~~~~~~~~~~~~~~
@ -712,7 +715,7 @@ When looping over the checkboxes, the ``label`` and ``input`` tags include
.. _file-upload-widgets:
File upload widgets
^^^^^^^^^^^^^^^^^^^
-------------------
``FileInput``
~~~~~~~~~~~~~
@ -733,7 +736,7 @@ File upload widgets
.. _composite-widgets:
Composite widgets
^^^^^^^^^^^^^^^^^
-----------------
``MultipleHiddenInput``
~~~~~~~~~~~~~~~~~~~~~~~

View File

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

View File

@ -31,7 +31,7 @@ A lookup expression consists of three parts:
.. _lookup-registration-api:
Registration API
~~~~~~~~~~~~~~~~
================
Django uses :class:`~lookups.RegisterLookupMixin` to give a class the interface to
register lookups on itself. The two prominent examples are
@ -75,7 +75,7 @@ follow this API.
.. _query-expression:
The Query Expression API
~~~~~~~~~~~~~~~~~~~~~~~~
========================
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
@ -118,7 +118,7 @@ following methods:
be a :class:`~django.db.models.Field` instance.
Transform reference
~~~~~~~~~~~~~~~~~~~
===================
.. class:: Transform
@ -163,7 +163,7 @@ Transform reference
its ``lhs.output_field``.
Lookup reference
~~~~~~~~~~~~~~~~
================
.. class:: Lookup

View File

@ -24,7 +24,7 @@ Field access API
================
Retrieving a single field instance of a model by 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'
Retrieving all field instances of a model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------
.. method:: Options.get_fields(include_parents=True, include_hidden=False)

View File

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

View File

@ -10,14 +10,14 @@ documentation for any custom tags or filters installed.
.. _ref-templates-builtins-tags:
Built-in tag reference
----------------------
======================
.. highlight:: html+django
.. templatetag:: autoescape
autoescape
^^^^^^^^^^
----------
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
@ -41,7 +41,7 @@ Sample usage::
.. templatetag:: block
block
^^^^^
-----
Defines a block that can be overridden by child templates. See
: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
comment
^^^^^^^
-------
Ignores everything between ``{% comment %}`` and ``{% endcomment %}``.
An optional note may be inserted in the first tag. For example, this is
@ -67,7 +67,7 @@ Sample usage::
.. templatetag:: csrf_token
csrf_token
^^^^^^^^^^
----------
This tag is used for CSRF protection, as described in the documentation for
: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
cycle
^^^^^
-----
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
@ -188,7 +188,7 @@ call to ``{% cycle %}`` doesn't specify ``silent``::
.. templatetag:: debug
debug
^^^^^
-----
Outputs a whole load of debugging information, including the current context
and imported modules.
@ -196,7 +196,7 @@ and imported modules.
.. templatetag:: extends
extends
^^^^^^^
-------
Signals that this template extends a parent template.
@ -215,7 +215,7 @@ See :ref:`template-inheritance` for more information.
.. templatetag:: filter
filter
^^^^^^
------
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
@ -239,7 +239,7 @@ Sample usage::
.. templatetag:: firstof
firstof
^^^^^^^
-------
Outputs the first argument variable that is not ``False``. Outputs nothing if
all the passed variables are ``False``.
@ -283,7 +283,7 @@ output inside a variable.
.. templatetag:: for
for
^^^
---
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
@ -341,7 +341,7 @@ Variable Description
========================== ===============================================
for ... empty
^^^^^^^^^^^^^
-------------
The ``for`` tag can take an optional ``{% empty %}`` clause whose text is
displayed if the given array is empty or could not be found::
@ -370,7 +370,7 @@ than -- the following::
.. templatetag:: if
if
^^
--
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
@ -392,7 +392,7 @@ clauses, as well as an ``{% else %}`` clause that will be displayed if all
previous conditions fail. These clauses are optional.
Boolean operators
"""""""""""""""""
~~~~~~~~~~~~~~~~~
:ttag:`if` tags may use ``and``, ``or`` or ``not`` to test a number of
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:
``==`` operator
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^
Equality. Example::
@ -444,7 +444,7 @@ Equality. Example::
{% endif %}
``!=`` operator
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^
Inequality. Example::
@ -454,7 +454,7 @@ Inequality. Example::
{% endif %}
``<`` operator
~~~~~~~~~~~~~~
^^^^^^^^^^^^^^
Less than. Example::
@ -463,7 +463,7 @@ Less than. Example::
{% endif %}
``>`` operator
~~~~~~~~~~~~~~
^^^^^^^^^^^^^^
Greater than. Example::
@ -472,7 +472,7 @@ Greater than. Example::
{% endif %}
``<=`` operator
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^
Less than or equal to. Example::
@ -481,7 +481,7 @@ Less than or equal to. Example::
{% endif %}
``>=`` operator
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^
Greater than or equal to. Example::
@ -490,7 +490,7 @@ Greater than or equal to. Example::
{% endif %}
``in`` operator
~~~~~~~~~~~~~~~
^^^^^^^^^^^^^^^
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
@ -511,7 +511,7 @@ of how ``x in y`` will be interpreted::
{% endif %}
``not 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 %}
Filters
"""""""
~~~~~~~
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 %}
Complex expressions
"""""""""""""""""""
~~~~~~~~~~~~~~~~~~~
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
@ -563,7 +563,7 @@ Sometimes that is better for clarity anyway, for the sake of those who do not
know the precedence rules.
``ifequal`` and ``ifnotequal``
""""""""""""""""""""""""""""""
------------------------------
``{% ifequal a b %} ... {% endifequal %}`` is an obsolete way to write
``{% 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
ifchanged
^^^^^^^^^
---------
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
include
^^^^^^^
-------
Loads a template and renders it with the current context. This is a way of
"including" other templates within a template.
@ -691,7 +691,7 @@ and returns an empty string.
.. templatetag:: load
load
^^^^
----
Loads a custom template tag set.
@ -713,7 +713,7 @@ more information.
.. templatetag:: lorem
lorem
^^^^^
-----
Displays random "lorem ipsum" Latin text. This is useful for providing sample
data in templates.
@ -747,7 +747,7 @@ Examples:
.. templatetag:: now
now
^^^
---
Displays the current date and/or time, using a format according to the given
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:`SHORT_DATE_FORMAT` or :setting:`SHORT_DATETIME_FORMAT`.
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" %}
@ -786,7 +786,7 @@ output (as a string) inside a variable. This is useful if you want to use
.. templatetag:: regroup
regroup
^^^^^^^
-------
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 %}
Grouping on other properties
""""""""""""""""""""""""""""
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Any valid template lookup is a legal grouping attribute for the regroup
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
spaceless
^^^^^^^^^
---------
Removes whitespace between HTML tags. This includes tab
characters and newlines.
@ -951,7 +951,7 @@ this example, the space around ``Hello`` won't be stripped::
.. templatetag:: templatetag
templatetag
^^^^^^^^^^^
-----------
Outputs one of the syntax characters used to compose template tags.
@ -980,7 +980,7 @@ Sample usage::
.. templatetag:: url
url
^^^
---
Returns an absolute path reference (a URL without the domain name) matching a
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
verbatim
^^^^^^^^
--------
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
widthratio
^^^^^^^^^^
----------
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.
@ -1105,7 +1105,7 @@ variable. It can be useful, for instance, in a :ttag:`blocktrans` like this::
.. templatetag:: with
with
^^^^
----
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.
@ -1131,12 +1131,12 @@ You can assign more than one context variable::
.. _ref-templates-builtins-filters:
Built-in filter reference
-------------------------
=========================
.. templatefilter:: add
add
^^^
---
Adds the argument to the value.
@ -1166,7 +1166,7 @@ output will be ``[1, 2, 3, 4, 5, 6]``.
.. templatefilter:: addslashes
addslashes
^^^^^^^^^^
----------
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
capfirst
^^^^^^^^
--------
Capitalizes the first character of the value. If the first character is not
a letter, this filter has no effect.
@ -1194,7 +1194,7 @@ If ``value`` is ``"django"``, the output will be ``"Django"``.
.. templatefilter:: center
center
^^^^^^
------
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
cut
^^^
---
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
date
^^^^
----
Formats a date according to the given format.
@ -1350,7 +1350,7 @@ representation of a ``datetime`` value. E.g.::
.. templatefilter:: default
default
^^^^^^^
-------
If value evaluates to ``False``, uses the given default. Otherwise, uses the
value.
@ -1364,7 +1364,7 @@ If ``value`` is ``""`` (the empty string), the output will be ``nothing``.
.. templatefilter:: default_if_none
default_if_none
^^^^^^^^^^^^^^^
---------------
If (and only if) value is ``None``, uses the given default. Otherwise, uses the
value.
@ -1381,7 +1381,7 @@ If ``value`` is ``None``, the output will be the string ``"nothing"``.
.. templatefilter:: dictsort
dictsort
^^^^^^^^
--------
Takes a list of dictionaries and returns that list sorted by the key given in
the argument.
@ -1435,7 +1435,7 @@ then the output would be::
.. templatefilter:: dictsortreversed
dictsortreversed
^^^^^^^^^^^^^^^^
----------------
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,
@ -1444,7 +1444,7 @@ but the returned value will be in reverse order.
.. templatefilter:: divisibleby
divisibleby
^^^^^^^^^^^
-----------
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
escape
^^^^^^
------
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
escapejs
^^^^^^^^
--------
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
@ -1502,7 +1502,7 @@ the output will be ``"testing\\u000D\\u000Ajavascript \\u0027string\\u0022 \\u00
.. templatefilter:: filesizeformat
filesizeformat
^^^^^^^^^^^^^^
--------------
Formats the value like a 'human-readable' file size (i.e. ``'13 KB'``,
``'4.1 MB'``, ``'102 bytes'``, etc.).
@ -1524,7 +1524,7 @@ If ``value`` is 123456789, the output would be ``117.7 MB``.
.. templatefilter:: first
first
^^^^^
-----
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
floatformat
^^^^^^^^^^^
-----------
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:
@ -1590,7 +1590,7 @@ with an argument of ``-1``.
.. templatefilter:: force_escape
force_escape
^^^^^^^^^^^^
------------
Applies HTML escaping to a string (see the :tfilter:`escape` filter for
details). This filter is applied *immediately* and returns a new, escaped
@ -1608,7 +1608,7 @@ the :tfilter:`linebreaks` filter::
.. templatefilter:: get_digit
get_digit
^^^^^^^^^
---------
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
@ -1624,7 +1624,7 @@ If ``value`` is ``123456789``, the output will be ``8``.
.. templatefilter:: iriencode
iriencode
^^^^^^^^^
---------
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
@ -1642,7 +1642,7 @@ If ``value`` is ``"?test=1&me=2"``, the output will be ``"?test=1&amp;me=2"``.
.. templatefilter:: join
join
^^^^
----
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
last
^^^^
----
Returns the last item in a list.
@ -1670,7 +1670,7 @@ string ``"d"``.
.. templatefilter:: length
length
^^^^^^
------
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
length_is
^^^^^^^^^
---------
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
linebreaks
^^^^^^^^^^
----------
Replaces line breaks in plain text with appropriate HTML; a single
newline becomes an HTML line break (``<br />``) and a new line
@ -1716,7 +1716,7 @@ slug</p>``.
.. templatefilter:: linebreaksbr
linebreaksbr
^^^^^^^^^^^^
------------
Converts all newlines in a piece of plain text to HTML line breaks
(``<br />``).
@ -1731,7 +1731,7 @@ slug``.
.. templatefilter:: linenumbers
linenumbers
^^^^^^^^^^^
-----------
Displays text with line numbers.
@ -1754,7 +1754,7 @@ the output will be::
.. templatefilter:: ljust
ljust
^^^^^
-----
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
lower
^^^^^
-----
Converts a string into all lowercase.
@ -1783,7 +1783,7 @@ If ``value`` is ``Totally LOVING this Album!``, the output will be
.. templatefilter:: make_list
make_list
^^^^^^^^^
---------
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
@ -1800,7 +1800,7 @@ list ``['1', '2', '3']``.
.. templatefilter:: phone2numeric
phone2numeric
^^^^^^^^^^^^^
-------------
Converts a phone number (possibly containing letters) to its numerical
equivalent.
@ -1817,7 +1817,7 @@ If ``value`` is ``800-COLLECT``, the output will be ``800-2655328``.
.. templatefilter:: pluralize
pluralize
^^^^^^^^^
---------
Returns a plural suffix if the value is not 1. By default, this suffix is
``'s'``.
@ -1848,14 +1848,14 @@ Example::
.. templatefilter:: pprint
pprint
^^^^^^
------
A wrapper around :func:`pprint.pprint` -- for debugging, really.
.. templatefilter:: random
random
^^^^^^
------
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
rjust
^^^^^
-----
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
safe
^^^^
----
Marks a string as not requiring further HTML escaping prior to output. When
autoescaping is off, this filter has no effect.
@ -1899,7 +1899,7 @@ autoescaping is off, this filter has no effect.
.. templatefilter:: safeseq
safeseq
^^^^^^^
-------
Applies the :tfilter:`safe` filter to each element of a sequence. Useful in
conjunction with other filters that operate on sequences, such as
@ -1914,7 +1914,7 @@ individual elements of the sequence.
.. templatefilter:: slice
slice
^^^^^
-----
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
slugify
^^^^^^^
-------
Converts to ASCII. Converts spaces to hyphens. Removes characters that aren't
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
stringformat
^^^^^^^^^^^^
------------
Formats the variable according to the argument, a string formatting specifier.
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
striptags
^^^^^^^^^
---------
Makes all possible efforts to strip all [X]HTML tags.
@ -1988,7 +1988,7 @@ output will be ``"Joel is a slug"``.
.. templatefilter:: time
time
^^^^
----
Formats a time according to the given format.
@ -2034,7 +2034,7 @@ used, without applying any localization.
.. templatefilter:: timesince
timesince
^^^^^^^^^
---------
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
timeuntil
^^^^^^^^^
---------
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
@ -2075,7 +2075,7 @@ date that is in the past relative to the comparison point.
.. templatefilter:: title
title
^^^^^
-----
Converts a string into titlecase by making words start with an uppercase
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
truncatechars
^^^^^^^^^^^^^
-------------
Truncates a string if it is longer than the specified number of characters.
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
truncatechars_html
^^^^^^^^^^^^^^^^^^
------------------
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
@ -2124,7 +2124,7 @@ Newlines in the HTML content will be preserved.
.. templatefilter:: truncatewords
truncatewords
^^^^^^^^^^^^^
-------------
Truncates a string after a certain number of words.
@ -2141,7 +2141,7 @@ Newlines within the string will be removed.
.. templatefilter:: truncatewords_html
truncatewords_html
^^^^^^^^^^^^^^^^^^
------------------
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,
@ -2162,7 +2162,7 @@ Newlines in the HTML content will be preserved.
.. templatefilter:: unordered_list
unordered_list
^^^^^^^^^^^^^^
--------------
Recursively takes a self-nested list and returns an HTML unordered list --
WITHOUT opening and closing <ul> tags.
@ -2186,7 +2186,7 @@ contains ``['States', ['Kansas', ['Lawrence', 'Topeka'], 'Illinois']]``, then
.. templatefilter:: upper
upper
^^^^^
-----
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
urlencode
^^^^^^^^^
---------
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
urlize
^^^^^^
------
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
urlizetrunc
^^^^^^^^^^^
-----------
Converts URLs and email addresses into clickable links just like urlize_, but
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
wordcount
^^^^^^^^^
---------
Returns the number of words.
@ -2302,7 +2302,7 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``4``.
.. templatefilter:: wordwrap
wordwrap
^^^^^^^^
--------
Wraps words at specified line length.
@ -2321,7 +2321,7 @@ If ``value`` is ``Joel is a slug``, the output would be::
.. templatefilter:: yesno
yesno
^^^^^
-----
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
@ -2343,14 +2343,14 @@ Value Argument Outputs
========== ====================== ===========================================
Internationalization tags and filters
-------------------------------------
=====================================
Django provides template tags and filters to control each aspect of
:doc:`internationalization </topics/i18n/index>` in templates. They allow for
granular control of translations, formatting, and time zone conversions.
i18n
^^^^
----
This library allows specifying translatable text in templates.
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`.
l10n
^^^^
----
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
@ -2368,7 +2368,7 @@ set :setting:`USE_L10N` to ``True`` so that localization is active by default.
See :ref:`topic-l10n-templates`.
tz
^^
--
This library provides control over time zone conversions in templates.
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`.
Other tags and filters libraries
--------------------------------
================================
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
template with the :ttag:`{% load %}<load>` tag.
django.contrib.humanize
^^^^^^^^^^^^^^^^^^^^^^^
-----------------------
A set of Django template filters useful for adding a "human touch" to data. See
:doc:`/ref/contrib/humanize`.
static
^^^^^^
------
.. templatetag:: static
static
""""""
~~~~~~
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`
@ -2433,7 +2433,7 @@ slightly different call::
.. templatetag:: get_static_prefix
get_static_prefix
"""""""""""""""""
~~~~~~~~~~~~~~~~~
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,
@ -2454,7 +2454,7 @@ the value multiple times::
.. templatetag:: get_media_prefix
get_media_prefix
""""""""""""""""
~~~~~~~~~~~~~~~~
Similar to the :ttag:`get_static_prefix`, ``get_media_prefix`` populates a
template variable with the media prefix :setting:`MEDIA_URL`, e.g.::

View File

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

View File

@ -5,7 +5,7 @@
.. module:: django.conf.urls
static()
--------
========
.. 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)
url()
-----
=====
.. 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.
include()
---------
=========
.. function:: include(module, namespace=None, app_name=None)
include(pattern_list)
@ -86,7 +86,7 @@ See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`.
application namespace or remove the instance namespace.
handler400
----------
==========
.. data:: handler400
@ -102,7 +102,7 @@ See the documentation about :ref:`the 400 (bad request) view
<http_bad_request_view>` for more information.
handler403
----------
==========
.. data:: handler403
@ -118,7 +118,7 @@ See the documentation about :ref:`the 403 (HTTP Forbidden) view
<http_forbidden_view>` for more information.
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.
handler500
----------
==========
.. data:: handler500

View File

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

View File

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

View File

@ -27,10 +27,10 @@ What's new in Django 1.10
...
Minor features
~~~~~~~~~~~~~~
--------------
:mod:`django.contrib.admin`
^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* 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
@ -57,12 +57,12 @@ Minor features
method is now the preferred way of retrieving the change message.
:mod:`django.contrib.admindocs`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.auth`
^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~
* The default iteration count for the PBKDF2 password hasher has been increased
by 25%. This backwards compatible change will not affect users who have
@ -77,12 +77,12 @@ Minor features
to allow using it without credentials.
:mod:`django.contrib.contenttypes`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.gis`
^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`Distance lookups <distance-lookups>` now accept expressions as the
distance value parameter.
@ -122,39 +122,39 @@ Minor features
<django.contrib.gis.geos.MultiLineString.closed>` properties.
:mod:`django.contrib.messages`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.postgres`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.redirects`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.sessions`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The :djadmin:`clearsessions` management command now removes file-based
sessions.
:mod:`django.contrib.sitemaps`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
:mod:`django.contrib.sites`
^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~
* The :class:`~django.contrib.sites.models.Site` model now supports
:ref:`natural keys <topics-serialization-natural-keys>`.
:mod:`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
@ -163,61 +163,61 @@ Minor features
not worry about whether or not the ``staticfiles`` app is installed.
:mod:`django.contrib.syndication`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* ...
Cache
^^^^^
~~~~~
* The file-based cache backend now uses the highest pickling protocol.
CSRF
^^^^
~~~~
* The default :setting:`CSRF_FAILURE_VIEW`, ``views.csrf.csrf_failure()`` now
accepts an optional ``template_name`` parameter, defaulting to
``'403_csrf.html'``, to control the template used to render the page.
Database backends
^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~
* ...
Email
^^^^^
~~~~~
* ...
File Storage
^^^^^^^^^^^^
~~~~~~~~~~~~
* ...
File Uploads
^^^^^^^^^^^^
~~~~~~~~~~~~
* ...
Forms
^^^^^
~~~~~
* Form and widget ``Media`` is now served using
:mod:`django.contrib.staticfiles` if installed.
Generic Views
^^^^^^^^^^^^^
~~~~~~~~~~~~~
* The :class:`~django.views.generic.base.View` class can now be imported from
``django.views``.
Internationalization
^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~
* ...
Management Commands
^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~
* The new :option:`check --fail-level` option allows specifying the message
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.
Migrations
^^^^^^^^^^
~~~~~~~~~~
* Added support for serialization of ``enum.Enum`` objects.
Models
^^^^^^
~~~~~~
* Reverse foreign keys from proxy models are now propagated to their
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.
Requests and Responses
^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~
* 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`.
Serialization
^^^^^^^^^^^^^
~~~~~~~~~~~~~
* The ``django.core.serializers.json.DjangoJSONEncoder`` now knows how to
serialize lazy strings, typically used for translatable content.
Signals
^^^^^^^
~~~~~~~
* ...
Templates
^^^^^^^^^
~~~~~~~~~
* Added the ``autoescape`` option to the
:class:`~django.template.backends.django.DjangoTemplates` backend and the
:class:`~django.template.Engine` class.
Tests
^^^^^
~~~~~
* ...
URLs
^^^^
~~~~
* An addition in :func:`django.setup()` allows URL resolving that happens
outside of the request/response cycle (e.g. in management commands and
@ -305,7 +305,7 @@ URLs
is set.
Validators
^^^^^^^^^^
~~~~~~~~~~
* :class:`~django.core.validators.URLValidator` now limits the length of
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.
Database backend API
~~~~~~~~~~~~~~~~~~~~
--------------------
* ...
@ -471,7 +471,7 @@ Features deprecated in 1.10
===========================
Direct assignment to a reverse foreign key or many-to-many relation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------------------------
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.
:mod:`django.contrib.gis`
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
* The ``get_srid()`` and ``set_srid()`` methods of
: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.
Miscellaneous
~~~~~~~~~~~~~
-------------
* The ``makemigrations --exit`` option is deprecated in favor of the
:option:`makemigrations --check` option.

View File

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

View File

@ -19,7 +19,7 @@ Backwards incompatible changes
==============================
CSRF exception for AJAX requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------
Django includes a CSRF-protection mechanism, which makes use of a
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.
FileField no longer deletes files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------
In earlier Django versions, when a model instance containing a
: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).
Use of custom SQL to load initial data in tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------------
Django provides a custom SQL hooks as a way to inject hand-crafted SQL
into the database synchronization process. One of the possible uses
@ -112,7 +112,7 @@ should either insert it using :ref:`test fixtures
test case.
ModelAdmin.lookup_allowed signature changed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------
Django 1.2.4 introduced a method ``lookup_allowed`` on ``ModelAdmin``, to cope
with a security issue (changeset `[15033]

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
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
forms. See :ref:`Format localization <format-localization>` for more details.
forms. See :doc:`/topics/i18n/formatting` for more details.
``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
be recognized because they were all upper case (for example
:setting:`DATETIME_FORMAT`, :setting:`DATE_FORMAT`, :setting:`TIME_FORMAT`).
They have been deprecated in favor of the new :ref:`Format localization
<format-localization>` infrastructure that allows localizers to specify that
information in a ``formats.py`` file in the corresponding
``django/conf/locale/<locale name>/`` directory.
They have been deprecated in favor of the new :doc:`/topics/i18n/formatting`
infrastructure that allows localizers to specify that information in a
``formats.py`` file in the corresponding ``django/conf/locale/<locale name>/``
directory.
GeoDjango
---------
@ -1089,7 +1089,7 @@ following sections provide information on the most-popular APIs that
were affected by these changes.
``SpatialBackend``
^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~
Prior to the creation of the separate spatial backends, the
``django.contrib.gis.db.backend.SpatialBackend`` object was
@ -1117,7 +1117,7 @@ Would need to be changed::
PostGISAdaptor = connection.ops.Adapter
``SpatialRefSys`` and ``GeometryColumns`` models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In previous versions of GeoDjango, :mod:`django.contrib.gis.db.models`
had ``SpatialRefSys`` and ``GeometryColumns`` models for querying

View File

@ -7,7 +7,7 @@ Django 1.3.4 release notes
This is the fourth release in the Django 1.3 series.
Host header poisoning
---------------------
=====================
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

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.
Host header poisoning
---------------------
=====================
Several earlier Django security releases focused on the issue of poisoning the
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`.
Redirect poisoning
------------------
==================
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

View File

@ -11,7 +11,7 @@ This is the sixth bugfix/security release in the Django 1.3 series.
Host header poisoning
---------------------
=====================
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
@ -36,7 +36,7 @@ This host validation is disabled when ``DEBUG`` is ``True`` or when running test
XML deserialization
-------------------
===================
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
@ -57,7 +57,7 @@ management command, you will need to ensure they do not contain a DTD.
Formset memory exhaustion
-------------------------
=========================
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
@ -70,7 +70,7 @@ factory argument).
Admin history view information leakage
--------------------------------------
======================================
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

View File

@ -68,7 +68,7 @@ What's new in Django 1.3
========================
Class-based views
~~~~~~~~~~~~~~~~~
-----------------
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
@ -86,7 +86,7 @@ your function-based generic views to class-based
views <https://docs.djangoproject.com/en/1.4/topics/generic-views-migration/>`_.
Logging
~~~~~~~
-------
Django 1.3 adds framework-level support for Python's ``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.
Extended static files handling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------
Django 1.3 ships with a new contrib app --
``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>`.
unittest2 support
~~~~~~~~~~~~~~~~~
-----------------
Python 2.7 introduced some major changes to the ``unittest`` library,
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
Transaction context managers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
Users of Python 2.5 and above may now use transaction management functions as
`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
Configurable delete-cascade
~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------
:class:`~django.db.models.ForeignKey` and
: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.
Contextual markers and comments for translatable strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------------------
For translation strings with ambiguous meaning, you can now
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`.
Improvements to 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.
TemplateResponse
~~~~~~~~~~~~~~~~
----------------
It can sometimes be beneficial to allow decorators or middleware to
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.
Caching changes
~~~~~~~~~~~~~~~
---------------
Django 1.3 sees the introduction of several improvements to the
Django's caching infrastructure.
@ -247,7 +247,7 @@ caching in Django</topics/cache>`.
.. _pylibmc: http://sendapatch.se/projects/pylibmc/
Permissions for inactive users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------
If you provide a custom auth backend with ``supports_inactive_user``
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.
GeoDjango
~~~~~~~~~
---------
The GeoDjango test suite is now included when
:ref:`running the Django test suite <running-unit-tests>` with ``runtests.py``
when using :ref:`spatial database backends <spatial-backends>`.
:setting:`MEDIA_URL` and :setting:`STATIC_URL` must end in a slash
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------------------------
Previously, the :setting:`MEDIA_URL` setting only required a trailing slash if
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.
Everything else
~~~~~~~~~~~~~~~
---------------
Django :doc:`1.1 <1.1>` and :doc:`1.2 <1.2>` added
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------
Prior to Django 1.2.5, Django's CSRF-prevention system exempted AJAX
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/
Restricted filters in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------
Prior to Django 1.2.5, the Django administrative interface allowed
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``.
Deleting a model doesn't delete associated files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------
In earlier Django versions, when a model instance containing a
: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).
PasswordInput default rendering behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------
The :class:`~django.forms.PasswordInput` form widget, intended for use
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))
Clearable default widget for FileField
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------
Django 1.3 now includes a :class:`~django.forms.ClearableFileInput` form widget
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}
New index on database session table
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------
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
@ -437,7 +437,7 @@ index can be found by running the ``sqlindexes`` admin command::
python manage.py sqlindexes sessions
No more naughty words
~~~~~~~~~~~~~~~~~~~~~
---------------------
Django has historically provided (and enforced) a list of profanities.
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
Localflavor changes
~~~~~~~~~~~~~~~~~~~
-------------------
Django 1.3 introduces the following backwards-incompatible changes to
local flavors:
@ -482,7 +482,7 @@ local flavors:
``USStateField`` not including them.
FormSet updates
~~~~~~~~~~~~~~~
---------------
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
@ -511,7 +511,7 @@ if you need to instantiate an empty ``FormSet``, don't pass in the data or use
>>> formset = ArticleFormSet(data=None)
Callables in templates
~~~~~~~~~~~~~~~~~~~~~~
----------------------
Previously, a callable in a template would only be called automatically as part
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.
Use of custom SQL to load initial data in tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------------
Django provides a custom SQL hooks as a way to inject hand-crafted SQL
into the database synchronization process. One of the possible uses
@ -559,7 +559,7 @@ should either insert it using :ref:`test fixtures
test case.
Changed priority of translation loading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------
Work has been done to simplify, rationalize and properly document the algorithm
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_
Transaction management
~~~~~~~~~~~~~~~~~~~~~~
----------------------
When using managed transactions -- that is, anything but the default
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.
No password reset for inactive users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------
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
message as a nonexistent account.
Password reset view now accepts ``from_email``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------------
The :func:`django.contrib.auth.views.password_reset` view now accepts a
``from_email`` parameter, which is passed to the ``password_reset_form``s
@ -679,7 +679,7 @@ be removed entirely.
</internals/deprecation>`.
``mod_python`` support
~~~~~~~~~~~~~~~~~~~~~~
----------------------
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
@ -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.
Function-based generic views
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
As a result of the introduction of class-based generic views, the
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``
Test client response ``template`` attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------
Django's :ref:`test client <test-client>` returns
: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.
``DjangoTestRunner``
~~~~~~~~~~~~~~~~~~~~
--------------------
As a result of the introduction of support for unittest2, the features
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.
Changes to ``url`` and ``ssi``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------
Most template tags will allow you to pass in either constants or
variables as arguments -- for example::
@ -771,7 +771,7 @@ templates should be modified to use the new ``future`` libraries and
syntax.
Changes to the login methods of the admin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------
In previous version the admin app defined login methods in multiple locations
and ignored the almost identical implementation in the already used auth app.
@ -788,7 +788,7 @@ attribute.
.. _r12634: https://code.djangoproject.com/changeset/12634
``reset`` and ``sqlreset`` management 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
@ -796,7 +796,7 @@ statements manually.
GeoDjango
~~~~~~~~~
---------
* The function-based :setting:`TEST_RUNNER` previously used to execute
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``.
``CZBirthNumberField.clean``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
Previously this field's ``clean()`` method accepted a second, gender, argument
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.
``CompatCookie``
~~~~~~~~~~~~~~~~
----------------
Previously, ``django.http`` exposed an undocumented ``CompatCookie`` class,
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------
This release of Django starts the deprecation process for inclusion of
translations located under the so-called *project path* in the translation
@ -865,7 +865,7 @@ Rationale for this decision:
inconsistency.
``PermWrapper`` moved to ``django.contrib.auth.context_processors``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------------------------
In Django 1.2, we began the process of changing the location of the
``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.
Removal of ``XMLField``
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
When Django was first released, Django included an ``XMLField`` that performed
automatic XML validation for any field input. However, this validation function

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.
Python 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

View File

@ -7,7 +7,7 @@ Django 1.4.2 release notes
This is the second security release in the Django 1.4 series.
Host header poisoning
---------------------
=====================
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

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.
Host header poisoning
---------------------
=====================
Several earlier Django security releases focused on the issue of poisoning the
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`.
Redirect poisoning
------------------
==================
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

View File

@ -12,7 +12,7 @@ This is the fourth bugfix/security release in the Django 1.4 series.
Host header poisoning
---------------------
=====================
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
@ -37,7 +37,7 @@ This host validation is disabled when ``DEBUG`` is ``True`` or when running test
XML deserialization
-------------------
===================
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
@ -58,7 +58,7 @@ management command, you will need to ensure they do not contain a DTD.
Formset memory exhaustion
-------------------------
=========================
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
@ -71,7 +71,7 @@ factory argument).
Admin history view information leakage
--------------------------------------
======================================
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

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.
Mitigated possible XSS attack via user-supplied redirect URLs
-------------------------------------------------------------
=============================================================
Django relies on user input in some cases (e.g.
:func:`django.contrib.auth.views.login`, ``django.contrib.comments``, and

View File

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

View File

@ -8,7 +8,7 @@ Django 1.4.8 fixes two security issues present in previous Django releases in
the 1.4 series.
Denial-of-service via password hashers
--------------------------------------
======================================
In previous versions of Django, no limit was imposed on the plaintext
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.
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
views with :func:`~django.views.decorators.debug.sensitive_post_parameters`

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.
Readdressed denial-of-service via password hashers
--------------------------------------------------
==================================================
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

View File

@ -81,7 +81,7 @@ What's new in Django 1.4
========================
Support for time zones
~~~~~~~~~~~~~~~~~~~~~~
----------------------
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
@ -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>`.
Support for in-browser testing frameworks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------
Django 1.4 supports integration with in-browser testing frameworks like
Selenium_. The new :class:`django.test.LiveServerTestCase` base class lets you
@ -120,7 +120,7 @@ concrete examples.
.. _Selenium: http://seleniumhq.org/
Updated default project layout and ``manage.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------
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
@ -186,7 +186,7 @@ prefix, some places without it), the imports will need to be cleaned up when
switching to the new ``manage.py``.
Custom project and app templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------
The :djadmin:`startapp` and :djadmin:`startproject` management commands
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.
Improved WSGI support
~~~~~~~~~~~~~~~~~~~~~
---------------------
The :djadmin:`startproject` management command now adds a :file:`wsgi.py`
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`.)
``SELECT FOR UPDATE`` support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------
Django 1.4 includes a :meth:`QuerySet.select_for_update()
<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`.
``Model.objects.bulk_create`` in the ORM
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------
This method lets you create multiple objects more efficiently. It can result in
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.
``QuerySet.prefetch_related``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------
Similar to :meth:`~django.db.models.query.QuerySet.select_related` but with a
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.
Improved password hashing
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
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
@ -279,7 +279,7 @@ details, see :ref:`auth_password_storage`.
.. _bcrypt: https://en.wikipedia.org/wiki/Bcrypt
HTML5 doctype
~~~~~~~~~~~~~
-------------
We've switched the admin and other bundled templates to use the HTML5
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.
List filters in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------
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
@ -297,7 +297,7 @@ used internally and known as "FilterSpec"). For more details, see the
documentation for :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
Multiple sort in admin interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------
The admin change list now supports sorting on multiple columns. It respects all
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).
New ``ModelAdmin`` methods
~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------
We added a :meth:`~django.contrib.admin.ModelAdmin.save_related` method to
: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.
Admin inlines respect user permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------
Admin inlines now only allow those actions for which the user has
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.
Tools for cryptographic signing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------
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
@ -339,7 +339,7 @@ See the :doc:`cryptographic signing </topics/signing>` docs for more
information.
Cookie-based session backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------
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
@ -356,7 +356,7 @@ See the :ref:`cookie-based session backend <cookie-session-backend>` docs for
more information.
New form wizard
~~~~~~~~~~~~~~~
---------------
The previous ``FormWizard`` from ``django.contrib.formtools`` has been
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.
``reverse_lazy``
~~~~~~~~~~~~~~~~
----------------
A lazily evaluated version of ``reverse()`` was added to allow using URL
reversals before the project's URLconf gets loaded.
Translating URL patterns
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
Django can now look for a language prefix in the URLpattern when using the new
: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.
Contextual translation support for ``{% trans %}`` and ``{% blocktrans %}``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------------------------------------------
The :ref:`contextual translation<contextual-markers>` support introduced in
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.
Customizable ``SingleObjectMixin`` URLConf kwargs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------
Two new attributes,
: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.
Assignment template tags
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
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
variable.
``*args`` and ``**kwargs`` support for template tag helper functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------------------------------
The :ref:`simple_tag<howto-custom-template-tags-simple-tags>`,
: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 %}
No wrapping of exceptions in ``TEMPLATE_DEBUG`` mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------------------
In previous versions of Django, whenever the ``TEMPLATE_DEBUG`` setting
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.
``truncatechars`` template filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------
This new filter truncates a string to be no longer than the specified
number of characters. Truncated strings end with a translatable ellipsis
@ -456,7 +456,7 @@ sequence ("..."). See the documentation for :tfilter:`truncatechars` for
more details.
``static`` template tag
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has a new
``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>`.
``CachedStaticFilesStorage`` storage backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------
The :mod:`staticfiles<django.contrib.staticfiles>` contrib app now has a
:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` backend
@ -478,7 +478,7 @@ See the :class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage`
docs for more information.
Simple clickjacking protection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------
We've added a middleware to provide easy protection against `clickjacking
<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.
CSRF improvements
~~~~~~~~~~~~~~~~~
-----------------
We've made various improvements to our CSRF features, including the
: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.
Error report filtering
~~~~~~~~~~~~~~~~~~~~~~
----------------------
We added two function decorators,
: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>`.
Extended IPv6 support
~~~~~~~~~~~~~~~~~~~~~
---------------------
Django 1.4 can now better handle IPv6 addresses with the new
: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`.
HTML comparisons in tests
~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------
The base classes in :mod:`django.test` now have some helpers to
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.
Two new date format strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------
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
- ``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.
Minor features
~~~~~~~~~~~~~~
--------------
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------
Running Django with an empty or known :setting:`SECRET_KEY` disables many of
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`.
django.contrib.admin
~~~~~~~~~~~~~~~~~~~~
--------------------
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
@ -715,7 +715,7 @@ If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
:file:`django/contrib/admin/static/admin/`.
Supported browsers for the admin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------
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`_
@ -733,7 +733,7 @@ any range of browsers.
.. _YUI's A-grade: http://yuilibrary.com/yui/docs/tutorials/gbs/
Removed admin icons
~~~~~~~~~~~~~~~~~~~
-------------------
As part of an effort to improve the performance and usability of the admin's
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.
CSS class names in admin forms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------
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
@ -761,7 +761,7 @@ style sheets or JavaScript files if you previously used plain field names as
selectors for custom styles or JavaScript transformations.
Compatibility with old signed data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------
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
@ -831,7 +831,7 @@ instance:
password hashes.
django.contrib.flatpages
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
Starting in 1.4, the
: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`.
Serialization of :class:`~datetime.datetime` and :class:`~datetime.time`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------------------------------
As a consequence of time-zone support, and according to the ECMA-262
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.
``supports_timezone`` changed to ``False`` 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
@ -878,7 +878,7 @@ datetimes are now stored without time-zone information in SQLite. When
object, Django raises an exception.
``MySQLdb``-specific exceptions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------
The MySQL backend historically has raised ``MySQLdb.OperationalError``
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.
Database connection's thread-locality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------
``DatabaseWrapper`` objects (i.e. the connection objects referenced by
``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.
`COMMENTS_BANNED_USERS_GROUP` setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------
Django's comments has historically
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()
`IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------------------
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
@ -988,7 +988,7 @@ Don't forget to escape characters that have a special meaning in a regular
expression, such as periods.
CSRF protection extended to PUT and DELETE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------
Previously, Django's :doc:`CSRF protection </ref/csrf/>` provided
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>`.
Password reset view now accepts ``subject_template_name``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------------------------
The ``password_reset`` view in ``django.contrib.auth`` now accepts a
``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.
``django.core.template_loaders``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------
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
still referenced this, please use ``django.template.loader`` instead.
``django.db.models.fields.URLField.verify_exists``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------------
This functionality has been removed due to intractable performance and
security issues. Any existing usage of ``verify_exists`` should be
removed.
``django.core.files.storage.Storage.open``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------
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
@ -1049,7 +1049,7 @@ method, like this::
return Spam(open(self.path(name), mode))
YAML deserializer now uses ``yaml.safe_load``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------------
``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
@ -1059,7 +1059,7 @@ fixtures are trusted data, the YAML deserializer now uses ``yaml.safe_load``
for additional security.
Session cookies now have the ``httponly`` flag by default
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------------------------
Session cookies now include the ``httponly`` attribute by default to
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.
The :tfilter:`urlize` filter no longer escapes every URL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------------------
When a URL contains a ``%xx`` sequence, where ``xx`` are two hexadecimal
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.
``assertTemplateUsed`` and ``assertTemplateNotUsed`` as context manager
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------------------------------------
It's now possible to check whether a template was used within a block of
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.
Database connections after running the test suite
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------
The default test runner no longer restores the database connections after
tests' execution. This prevents the production database from being exposed to
@ -1106,7 +1106,7 @@ subclassing ``DjangoTestRunner`` and overriding its ``teardown_databases()``
method.
Output of :djadmin:`manage.py help <help>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------
: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
@ -1115,7 +1115,7 @@ management commands in a script, use
:djadmin:`manage.py help --commands <help>` instead.
``extends`` template tag
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------
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
@ -1126,7 +1126,7 @@ interests of full disclosure, the ``ExtendsNode.__init__`` definition has
changed, which may break any custom tags that use this class.
Loading some incomplete fixtures no longer works
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------
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
@ -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.
Development Server Multithreading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------
The development server is now is multithreaded by default. Use the
:option:`runserver --nothreading` option to disable the use of threading in the
@ -1144,7 +1144,7 @@ development server::
django-admin.py runserver --nothreading
Attributes disabled in markdown when safe mode set
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------------
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
@ -1155,7 +1155,7 @@ Python-Markdown library less than 2.1, a warning is issued that the output is
insecure.
FormMixin get_initial returns an instance-specific dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------------------
In Django 1.3, the ``get_initial`` method of 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------------
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
this decorator.
Support for PostgreSQL versions older than 8.2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------------
Django 1.3 dropped support for PostgreSQL versions older than 8.0, and we
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.
Request exceptions are now always logged
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------
When we added :doc:`logging support </topics/logging/>` in Django in 1.3, 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.
``django.conf.urls.defaults``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------
Until Django 1.3, the functions :func:`~django.conf.urls.include`,
``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`.
``django.contrib.databrowse``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------
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
@ -1252,7 +1252,7 @@ itself, so it's available to be adopted by an individual or group as
a third-party project.
``django.core.management.setup_environ``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------------------
This function temporarily modified ``sys.path`` in order to make the parent
"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`.
``django.core.management.execute_manager``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------
This function was previously used by ``manage.py`` to execute a management
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.
``is_safe`` and ``needs_autoescape`` attributes of template filters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------------------------
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
@ -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.
Wildcard expansion of application names in `INSTALLED_APPS`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------------------------------------------------
Until Django 1.3, :setting:`INSTALLED_APPS` accepted wildcards in application
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
``HttpRequest.raw_post_data`` renamed to ``HttpRequest.body``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------------------------------
This attribute was confusingly named ``HttpRequest.raw_post_data``, but it
actually provided the body of the HTTP request. It's been renamed to
``HttpRequest.body``, and ``HttpRequest.raw_post_data`` has been deprecated.
``django.contrib.sitemaps`` bug fix with potential performance implications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
---------------------------------------------------------------------------
In previous versions, ``Paginator`` objects used in sitemap classes were
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.
Versions of Python-Markdown earlier than 2.1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------------
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

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