Fixed #26020 -- Normalized header stylings in docs.
This commit is contained in:
Elif T. Kus
Tim Graham
parent
79d0a4fdb0
commit
bca9faae95
|
|
@ -1,5 +1,3 @@
|
|||
.. _contents:
|
||||
|
||||
=============================
|
||||
Django documentation contents
|
||||
=============================
|
||||
|
|
@ -27,4 +25,4 @@ Indices, glossary and tables
|
|||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`glossary`
|
||||
* :doc:`glossary`
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,5 +1,3 @@
|
|||
.. _glossary:
|
||||
|
||||
========
|
||||
Glossary
|
||||
========
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
===============================
|
||||
Writing a custom storage system
|
||||
===============================
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
================
|
||||
Deploying Django
|
||||
================
|
||||
|
||||
|
|
|
|||
|
|
@ -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`::
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
===============
|
||||
"How-to" guides
|
||||
===============
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,3 @@
|
|||
|
||||
.. _index:
|
||||
|
||||
====================
|
||||
Django documentation
|
||||
====================
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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?**
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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>`?
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
================
|
||||
Django internals
|
||||
================
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,3 @@
|
|||
.. _internals-security:
|
||||
|
||||
==========================
|
||||
Django's security policies
|
||||
==========================
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
===============
|
||||
Getting started
|
||||
===============
|
||||
|
||||
|
|
|
|||
|
|
@ -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>`.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
=================================
|
||||
Meta-documentation and miscellany
|
||||
=================================
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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):
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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``.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
=======================
|
||||
``django.contrib.auth``
|
||||
=======================
|
||||
|
||||
|
|
|
|||
|
|
@ -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``
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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]_
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
===========================
|
||||
``django.contrib.postgres``
|
||||
===========================
|
||||
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
|
|
|||
|
|
@ -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&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.::
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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``
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
Loading…
Reference in New Issue