Converted links to external topics so they use intersphinx extension markup.
This allows to make these links more resilent to changes in the target URLs. Thanks Jannis for the report and Aymeric Augustin for the patch. Fixes #16586. git-svn-id: http://code.djangoproject.com/svn/django/trunk@16720 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Ramiro Morales
parent
9110257a32
commit
932b1b8d6d
12
docs/conf.py
12
docs/conf.py
|
|
@ -26,7 +26,7 @@ needs_sphinx = '1.0'
|
|||
|
||||
# Add any Sphinx extension module names here, as strings. They can be extensions
|
||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = ["djangodocs"]
|
||||
extensions = ["djangodocs", "sphinx.ext.intersphinx"]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
# templates_path = []
|
||||
|
|
@ -92,6 +92,16 @@ pygments_style = 'trac'
|
|||
# Note: exclude_dirnames is new in Sphinx 0.5
|
||||
exclude_dirnames = ['.svn']
|
||||
|
||||
# Links to Python's docs should reference the most recent version of the 2.x
|
||||
# branch, which is located at this URL.
|
||||
intersphinx_mapping = {
|
||||
'python': ('http://docs.python.org/2.7', None),
|
||||
'sphinx': ('http://sphinx.pocoo.org/', None),
|
||||
}
|
||||
|
||||
# Python's docs don't change every week.
|
||||
intersphinx_cache_limit = 90 # days
|
||||
|
||||
# -- Options for HTML output ---------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
|
|
|
|||
|
|
@ -22,8 +22,8 @@ usage.
|
|||
|
||||
For a development environment -- if you just want to experiment with Django --
|
||||
you don't need to have a separate Web server installed; Django comes with its
|
||||
own lightweight development server. For a production environment, Django
|
||||
follows the WSGI_ spec, which means it can run on a variety of server
|
||||
own lightweight development server. For a production environment, Django follows
|
||||
the WSGI spec, :pep:`3333`, which means it can run on a variety of server
|
||||
platforms. See :doc:`Deploying Django </howto/deployment/index>` for some
|
||||
popular alternatives. Also, the `server arrangements wiki page`_ contains
|
||||
details for several deployment strategies.
|
||||
|
|
@ -33,7 +33,6 @@ also need a database engine. PostgreSQL_ is recommended, because we're
|
|||
PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported.
|
||||
|
||||
.. _Python: http://www.python.org/
|
||||
.. _WSGI: http://www.python.org/dev/peps/pep-0333/
|
||||
.. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
|
||||
.. _PostgreSQL: http://www.postgresql.org/
|
||||
.. _MySQL: http://www.mysql.com/
|
||||
|
|
@ -48,7 +47,7 @@ version of Python from 2.5 through 2.7, inclusive. However, newer versions of
|
|||
Python are often faster, have more features, and are better supported. If you
|
||||
use a newer version of Python you will also have access to some APIs that
|
||||
aren't available under older versions of Python. For example, since Python 2.6,
|
||||
you can use the advanced string formatting described in `PEP 3101`_.
|
||||
you can use the advanced string formatting described in :pep:`3101`.
|
||||
|
||||
Third-party applications for use with Django are, of course, free to set their
|
||||
own version requirements.
|
||||
|
|
@ -63,8 +62,6 @@ improvements and optimizations to the Python language since version 2.5, and
|
|||
will help ease the process of dropping support for older Python versions on
|
||||
the road to Python 3.
|
||||
|
||||
.. _PEP 3101: http://www.python.org/dev/peps/pep-3101/
|
||||
|
||||
Can I use Django with Python 2.4?
|
||||
---------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -43,19 +43,10 @@ Glossary
|
|||
|
||||
property
|
||||
Also known as "managed attributes", and a feature of Python since
|
||||
version 2.2. From `the property documentation`__:
|
||||
version 2.2. This is a neat way to implement attributes whose usage
|
||||
resembles attribute access, but whose implementation uses method calls.
|
||||
|
||||
Properties are a neat way to implement attributes whose usage
|
||||
resembles attribute access, but whose implementation uses method
|
||||
calls. [...] You
|
||||
could only do this by overriding ``__getattr__`` and
|
||||
``__setattr__``; but overriding ``__setattr__`` slows down all
|
||||
attribute assignments considerably, and overriding ``__getattr__``
|
||||
is always a bit tricky to get right. Properties let you do this
|
||||
painlessly, without having to override ``__getattr__`` or
|
||||
``__setattr__``.
|
||||
|
||||
__ http://www.python.org/download/releases/2.2/descrintro/#property
|
||||
See :func:`property`.
|
||||
|
||||
queryset
|
||||
An object representing some set of rows to be fetched from the database.
|
||||
|
|
|
|||
|
|
@ -335,15 +335,13 @@ responsible for returning a ``Node`` instance based on the contents of the tag.
|
|||
|
||||
For example, let's write a template tag, ``{% current_time %}``, that displays
|
||||
the current date/time, formatted according to a parameter given in the tag, in
|
||||
`strftime syntax`_. It's a good idea to decide the tag syntax before anything
|
||||
else. In our case, let's say the tag should be used like this:
|
||||
:func:`~time.strftime` syntax. It's a good idea to decide the tag syntax before
|
||||
anything else. In our case, let's say the tag should be used like this:
|
||||
|
||||
.. code-block:: html+django
|
||||
|
||||
<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>
|
||||
|
||||
.. _`strftime syntax`: http://docs.python.org/library/time.html#time.strftime
|
||||
|
||||
The parser for this function should grab the parameter and create a ``Node``
|
||||
object::
|
||||
|
||||
|
|
|
|||
|
|
@ -9,10 +9,8 @@ Django into production.
|
|||
.. _mod_wsgi: http://code.google.com/p/modwsgi/
|
||||
|
||||
mod_wsgi is an Apache module which can be used to host any Python application
|
||||
which supports the `Python WSGI interface`_, including Django. Django will work
|
||||
with any version of Apache which supports mod_wsgi.
|
||||
|
||||
.. _python wsgi interface: http://www.python.org/dev/peps/pep-0333/
|
||||
which supports the Python WSGI interface described in :pep:`3333`, including
|
||||
Django. Django will work with any version of Apache which supports mod_wsgi.
|
||||
|
||||
The `official mod_wsgi documentation`_ is fantastic; it's your source for all
|
||||
the details about how to use mod_wsgi. You'll probably want to start with the
|
||||
|
|
|
|||
|
|
@ -3,17 +3,15 @@ Outputting CSV with Django
|
|||
==========================
|
||||
|
||||
This document explains how to output CSV (Comma Separated Values) dynamically
|
||||
using Django views. To do this, you can either use the `Python CSV library`_ or
|
||||
the Django template system.
|
||||
|
||||
.. _Python CSV library: http://docs.python.org/library/csv.html
|
||||
using Django views. To do this, you can either use the Python CSV library or the
|
||||
Django template system.
|
||||
|
||||
Using the Python CSV library
|
||||
============================
|
||||
|
||||
Python comes with a CSV library, ``csv``. The key to using it with Django is
|
||||
that the ``csv`` module's CSV-creation capability acts on file-like objects, and
|
||||
Django's :class:`~django.http.HttpResponse` objects are file-like objects.
|
||||
Python comes with a CSV library, :mod:`csv`. The key to using it with Django is
|
||||
that the :mod:`csv` module's CSV-creation capability acts on file-like objects,
|
||||
and Django's :class:`~django.http.HttpResponse` objects are file-like objects.
|
||||
|
||||
Here's an example::
|
||||
|
||||
|
|
@ -34,7 +32,7 @@ Here's an example::
|
|||
The code and comments should be self-explanatory, but a few things deserve a
|
||||
mention:
|
||||
|
||||
* The response gets a special MIME type, ``text/csv``. This tells
|
||||
* The response gets a special MIME type, :mimetype:`text/csv`. This tells
|
||||
browsers that the document is a CSV file, rather than an HTML file. If
|
||||
you leave this off, browsers will probably interpret the output as HTML,
|
||||
which will result in ugly, scary gobbledygook in the browser window.
|
||||
|
|
@ -59,7 +57,7 @@ mention:
|
|||
Handling Unicode
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Python's ``csv`` module does not support Unicode input. Since Django uses
|
||||
Python's :mod:`csv` module does not support Unicode input. Since Django uses
|
||||
Unicode internally this means strings read from sources such as
|
||||
:class:`~django.http.HttpRequest` are potentially problematic. There are a few
|
||||
options for handling this:
|
||||
|
|
@ -70,20 +68,18 @@ options for handling this:
|
|||
section`_.
|
||||
|
||||
* Use the `python-unicodecsv module`_, which aims to be a drop-in
|
||||
replacement for ``csv`` that gracefully handles Unicode.
|
||||
replacement for :mod:`csv` that gracefully handles Unicode.
|
||||
|
||||
For more information, see the Python `CSV File Reading and Writing`_
|
||||
documentation.
|
||||
For more information, see the Python documentation of the :mod:`csv` module.
|
||||
|
||||
.. _`csv module's examples section`: http://docs.python.org/library/csv.html#examples
|
||||
.. _`python-unicodecsv module`: https://github.com/jdunck/python-unicodecsv
|
||||
.. _`CSV File Reading and Writing`: http://docs.python.org/library/csv.html
|
||||
|
||||
Using the template system
|
||||
=========================
|
||||
|
||||
Alternatively, you can use the :doc:`Django template system </topics/templates>`
|
||||
to generate CSV. This is lower-level than using the convenient Python ``csv``
|
||||
to generate CSV. This is lower-level than using the convenient Python :mod:`csv`
|
||||
module, but the solution is presented here for completeness.
|
||||
|
||||
The idea here is to pass a list of items to your template, and have the
|
||||
|
|
|
|||
|
|
@ -63,10 +63,11 @@ Here's a "Hello World" example::
|
|||
The code and comments should be self-explanatory, but a few things deserve a
|
||||
mention:
|
||||
|
||||
* The response gets a special MIME type, ``application/pdf``. This tells
|
||||
browsers that the document is a PDF file, rather than an HTML file. If
|
||||
you leave this off, browsers will probably interpret the output as HTML,
|
||||
which would result in ugly, scary gobbledygook in the browser window.
|
||||
* The response gets a special MIME type, :mimetype:`application/pdf`. This
|
||||
tells browsers that the document is a PDF file, rather than an HTML file.
|
||||
If you leave this off, browsers will probably interpret the output as
|
||||
HTML, which would result in ugly, scary gobbledygook in the browser
|
||||
window.
|
||||
|
||||
* The response gets an additional ``Content-Disposition`` header, which
|
||||
contains the name of the PDF file. This filename is arbitrary: Call it
|
||||
|
|
@ -97,9 +98,9 @@ Complex PDFs
|
|||
============
|
||||
|
||||
If you're creating a complex PDF document with ReportLab, consider using the
|
||||
cStringIO_ library as a temporary holding place for your PDF file. The cStringIO
|
||||
:mod:`cStringIO` library as a temporary holding place for your PDF file. This
|
||||
library provides a file-like object interface that is particularly efficient.
|
||||
Here's the above "Hello World" example rewritten to use ``cStringIO``::
|
||||
Here's the above "Hello World" example rewritten to use :mod:`cStringIO`::
|
||||
|
||||
# Fall back to StringIO in environments where cStringIO is not available
|
||||
try:
|
||||
|
|
@ -133,8 +134,6 @@ Here's the above "Hello World" example rewritten to use ``cStringIO``::
|
|||
response.write(pdf)
|
||||
return response
|
||||
|
||||
.. _cStringIO: http://docs.python.org/library/stringio.html#module-cStringIO
|
||||
|
||||
Further resources
|
||||
=================
|
||||
|
||||
|
|
|
|||
|
|
@ -146,14 +146,14 @@ Alternatively, you can use a symlink called ``django`` that points to the
|
|||
location of the branch's ``django`` package. If you want to switch back, just
|
||||
change the symlink to point to the old code.
|
||||
|
||||
A third option is to use a `path file`_ (``<something>.pth``). First, make sure
|
||||
there are no files, directories or symlinks named ``django`` in your
|
||||
``site-packages`` directory. Then create a text file named ``django.pth`` and
|
||||
save it to your ``site-packages`` directory. That file should contain a path to
|
||||
your copy of Django on a single line and optional comments. Here is an example
|
||||
that points to multiple branches. Just uncomment the line for the branch you
|
||||
want to use ('Trunk' in this example) and make sure all other lines are
|
||||
commented::
|
||||
A third option is to use a path file (``<something>.pth``). This is a feature of
|
||||
the :mod:`site` module. First, make sure there are no files, directories or
|
||||
symlinks named ``django`` in your ``site-packages`` directory. Then create a
|
||||
text file named ``django.pth`` and save it to your ``site-packages`` directory.
|
||||
That file should contain a path to your copy of Django on a single line and
|
||||
optional comments. Here is an example that points to multiple branches. Just
|
||||
uncomment the line for the branch you want to use ('trunk' in this example) and
|
||||
make sure all other lines are commented::
|
||||
|
||||
# Trunk is a svn checkout of:
|
||||
# http://code.djangoproject.com/svn/django/trunk/
|
||||
|
|
@ -168,5 +168,4 @@ commented::
|
|||
# On windows a path may look like this:
|
||||
# C:/path/to/<branch>
|
||||
|
||||
.. _path file: http://docs.python.org/library/site.html
|
||||
.. _django-developers: http://groups.google.com/group/django-developers
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Python style
|
|||
* Unless otherwise specified, follow :pep:`8`.
|
||||
|
||||
You could use a tool like `pep8`_ to check for some problems in this
|
||||
area, but remember that PEP 8 is only a guide, so respect the style of
|
||||
area, but remember that :pep:`8` is only a guide, so respect the style of
|
||||
the surrounding code as a primary goal.
|
||||
|
||||
* Use four spaces for indentation.
|
||||
|
|
|
|||
|
|
@ -43,12 +43,10 @@ __ http://pygments.org
|
|||
Then, building the HTML is easy; just ``make html`` (or ``make.bat html`` on
|
||||
Windows) from the ``docs`` directory.
|
||||
|
||||
To get started contributing, you'll want to read the `reStructuredText
|
||||
Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
|
||||
that's used to manage metadata, indexing, and cross-references.
|
||||
|
||||
__ http://sphinx.pocoo.org/rest.html
|
||||
__ http://sphinx.pocoo.org/markup/
|
||||
To get started contributing, you'll want to read the :ref:`reStructuredText
|
||||
Primer <sphinx:rst-primer>`. After that, you'll want to read about the
|
||||
:ref:`Sphinx-specific markup <sphinx:sphinxmarkup>` that's used to manage
|
||||
metadata, indexing, and cross-references.
|
||||
|
||||
Commonly used terms
|
||||
-------------------
|
||||
|
|
@ -113,6 +111,9 @@ documentation:
|
|||
greatly helps readers. There's basically no limit to the amount of
|
||||
useful markup you can add.
|
||||
|
||||
* Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
|
||||
documentation.
|
||||
|
||||
Django-specific markup
|
||||
----------------------
|
||||
|
||||
|
|
@ -220,12 +221,9 @@ example:
|
|||
You can find both in the :doc:`settings reference document
|
||||
</ref/settings>`.
|
||||
|
||||
We use the Sphinx doc_ cross reference element when we want to link to
|
||||
another document as a whole and the ref_ element when we want to link to
|
||||
an arbitrary location in a document.
|
||||
|
||||
.. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc
|
||||
.. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref
|
||||
We use the Sphinx :rst:role:`doc` cross reference element when we want to
|
||||
link to another document as a whole and the :rst:role:`ref` element when
|
||||
we want to link to an arbitrary location in a document.
|
||||
|
||||
* Next, notice how the settings are annotated:
|
||||
|
||||
|
|
|
|||
|
|
@ -122,14 +122,13 @@ the URLconf will look for ``myapp/``. In a request to
|
|||
``http://www.example.com/myapp/?page=3``, the URLconf will look for ``myapp/``.
|
||||
|
||||
If you need help with regular expressions, see `Wikipedia's entry`_ and the
|
||||
`Python documentation`_. Also, the O'Reilly book "Mastering Regular Expressions"
|
||||
by Jeffrey Friedl is fantastic.
|
||||
documentation of the :mod:`re` module. Also, the O'Reilly book "Mastering
|
||||
Regular Expressions" by Jeffrey Friedl is fantastic.
|
||||
|
||||
Finally, a performance note: these regular expressions are compiled the first
|
||||
time the URLconf module is loaded. They're super fast.
|
||||
|
||||
.. _Wikipedia's entry: http://en.wikipedia.org/wiki/Regular_expression
|
||||
.. _Python documentation: http://docs.python.org/library/re.html
|
||||
|
||||
Write your first view
|
||||
=====================
|
||||
|
|
|
|||
|
|
@ -73,13 +73,11 @@ as possible.
|
|||
Explicit is better than implicit
|
||||
--------------------------------
|
||||
|
||||
This, a `core Python principle`_, means Django shouldn't do too much "magic."
|
||||
Magic shouldn't happen unless there's a really good reason for it. Magic is
|
||||
worth using only if it creates a huge convenience unattainable in other ways,
|
||||
and it isn't implemented in a way that confuses developers who are trying to
|
||||
learn how to use the feature.
|
||||
|
||||
.. _`core Python principle`: http://www.python.org/dev/peps/pep-0020/
|
||||
This is a core Python principle listed in :pep:`20`, and it means Django
|
||||
shouldn't do too much "magic." Magic shouldn't happen unless there's a really
|
||||
good reason for it. Magic is worth using only if it creates a huge convenience
|
||||
unattainable in other ways, and it isn't implemented in a way that confuses
|
||||
developers who are trying to learn how to use the feature.
|
||||
|
||||
.. _consistency:
|
||||
|
||||
|
|
|
|||
|
|
@ -586,10 +586,8 @@ YearMixin
|
|||
|
||||
.. attribute:: year_format
|
||||
|
||||
The strftime_ format to use when parsing the year. By default, this is
|
||||
``'%Y'``.
|
||||
|
||||
.. _strftime: http://docs.python.org/library/time.html#time.strftime
|
||||
The :func:`~time.strftime` format to use when parsing the year.
|
||||
By default, this is ``'%Y'``.
|
||||
|
||||
.. attribute:: year
|
||||
|
||||
|
|
@ -598,7 +596,7 @@ YearMixin
|
|||
|
||||
.. method:: get_year_format()
|
||||
|
||||
Returns the strftime_ format to use when parsing the year. Returns
|
||||
Returns the :func:`~time.strftime` format to use when parsing the year. Returns
|
||||
:attr:`YearMixin.year_format` by default.
|
||||
|
||||
.. method:: get_year()
|
||||
|
|
@ -621,7 +619,7 @@ MonthMixin
|
|||
|
||||
.. attribute:: month_format
|
||||
|
||||
The strftime_ format to use when parsing the month. By default, this is
|
||||
The :func:`~time.strftime` format to use when parsing the month. By default, this is
|
||||
``'%b'``.
|
||||
|
||||
.. attribute:: month
|
||||
|
|
@ -631,7 +629,7 @@ MonthMixin
|
|||
|
||||
.. method:: get_month_format()
|
||||
|
||||
Returns the strftime_ format to use when parsing the month. Returns
|
||||
Returns the :func:`~time.strftime` format to use when parsing the month. Returns
|
||||
:attr:`MonthMixin.month_format` by default.
|
||||
|
||||
.. method:: get_month()
|
||||
|
|
@ -667,7 +665,7 @@ DayMixin
|
|||
|
||||
.. attribute:: day_format
|
||||
|
||||
The strftime_ format to use when parsing the day. By default, this is
|
||||
The :func:`~time.strftime` format to use when parsing the day. By default, this is
|
||||
``'%d'``.
|
||||
|
||||
.. attribute:: day
|
||||
|
|
@ -677,7 +675,7 @@ DayMixin
|
|||
|
||||
.. method:: get_day_format()
|
||||
|
||||
Returns the strftime_ format to use when parsing the day. Returns
|
||||
Returns the :func:`~time.strftime` format to use when parsing the day. Returns
|
||||
:attr:`DayMixin.day_format` by default.
|
||||
|
||||
.. method:: get_day()
|
||||
|
|
@ -712,7 +710,7 @@ WeekMixin
|
|||
|
||||
.. attribute:: week_format
|
||||
|
||||
The strftime_ format to use when parsing the week. By default, this is
|
||||
The :func:`~time.strftime` format to use when parsing the week. By default, this is
|
||||
``'%U'``.
|
||||
|
||||
.. attribute:: week
|
||||
|
|
@ -722,7 +720,7 @@ WeekMixin
|
|||
|
||||
.. method:: get_week_format()
|
||||
|
||||
Returns the strftime_ format to use when parsing the week. Returns
|
||||
Returns the :func:`~time.strftime` format to use when parsing the week. Returns
|
||||
:attr:`WeekMixin.week_format` by default.
|
||||
|
||||
.. method:: get_week()
|
||||
|
|
|
|||
|
|
@ -14,12 +14,12 @@ who visits the malicious site in their browser. A related type of attack,
|
|||
a site with someone else's credentials, is also covered.
|
||||
|
||||
The first defense against CSRF attacks is to ensure that GET requests (and other
|
||||
'safe' methods, as defined by `9.1.1 Safe Methods, HTTP 1.1, RFC 2616`_) are
|
||||
side-effect free. Requests via 'unsafe' methods, such as POST, PUT and DELETE,
|
||||
can then be protected by following the steps below.
|
||||
'safe' methods, as defined by 9.1.1 Safe Methods, HTTP 1.1,
|
||||
:rfc:`2616#section-9.1.1`) are side-effect free. Requests via 'unsafe' methods,
|
||||
such as POST, PUT and DELETE, can then be protected by following the steps
|
||||
below.
|
||||
|
||||
.. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF
|
||||
.. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
|
||||
|
||||
.. _using-csrf:
|
||||
|
||||
|
|
@ -228,9 +228,9 @@ This ensures that only forms that have originated from your Web site can be used
|
|||
to POST data back.
|
||||
|
||||
It deliberately ignores GET requests (and other requests that are defined as
|
||||
'safe' by RFC 2616). These requests ought never to have any potentially
|
||||
'safe' by :rfc:`2616`). These requests ought never to have any potentially
|
||||
dangerous side effects , and so a CSRF attack with a GET request ought to be
|
||||
harmless. RFC 2616 defines POST, PUT and DELETE as 'unsafe', and all other
|
||||
harmless. :rfc:`2616` defines POST, PUT and DELETE as 'unsafe', and all other
|
||||
methods are assumed to be unsafe, for maximum protection.
|
||||
|
||||
Caching
|
||||
|
|
|
|||
|
|
@ -1235,13 +1235,17 @@ may be executed from the SQL Shell as the ``postgres`` user::
|
|||
postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8';
|
||||
|
||||
.. rubric:: Footnotes
|
||||
.. [#] The datum shifting files are needed for converting data to and from certain projections.
|
||||
For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_
|
||||
requires the ``null`` grid file only included in the extra datum shifting files.
|
||||
It is easier to install the shifting files now, then to have debug a problem caused by their absence later.
|
||||
.. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL.
|
||||
.. [#] The datum shifting files are needed for converting data to and from
|
||||
certain projections.
|
||||
For example, the PROJ.4 string for the `Google projection (900913)
|
||||
<http://spatialreference.org/ref/epsg/900913/proj4>`_ requires the
|
||||
``null`` grid file only included in the extra datum shifting files.
|
||||
It is easier to install the shifting files now, then to have debug a
|
||||
problem caused by their absence later.
|
||||
.. [#] Specifically, GeoDjango provides support for the `OGR
|
||||
<http://gdal.org/ogr>`_ library, a component of GDAL.
|
||||
.. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_.
|
||||
.. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_
|
||||
routine from ``ctypes.util`` to locate shared libraries.
|
||||
.. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from
|
||||
:mod:`ctypes.util` to locate shared libraries.
|
||||
.. [#] The ``psycopg2`` Windows installers are packaged and maintained by
|
||||
`Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_.
|
||||
|
|
|
|||
|
|
@ -852,8 +852,9 @@ They share this interface:
|
|||
|
||||
All parameters, if given, should be Unicode objects, except:
|
||||
|
||||
* ``pubdate`` should be a `Python datetime object`_.
|
||||
* ``enclosure`` should be an instance of ``feedgenerator.Enclosure``.
|
||||
* ``pubdate`` should be a Python :class:`~datetime.datetime` object.
|
||||
* ``enclosure`` should be an instance of
|
||||
:class:`django.utils.feedgenerator.Enclosure`.
|
||||
* ``categories`` should be a sequence of Unicode objects.
|
||||
|
||||
:meth:`.SyndicationFeed.write`
|
||||
|
|
@ -884,7 +885,6 @@ For example, to create an Atom 1.0 feed and print it to standard output::
|
|||
</feed>
|
||||
|
||||
.. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py
|
||||
.. _Python datetime object: http://docs.python.org/library/datetime.html#datetime-objects
|
||||
|
||||
.. currentmodule:: django.contrib.syndication
|
||||
|
||||
|
|
@ -913,9 +913,9 @@ attributes. Thus, you can subclass the appropriate feed generator class
|
|||
|
||||
``SyndicationFeed.add_root_elements(self, handler)``
|
||||
Callback to add elements inside the root feed element
|
||||
(``feed``/``channel``). ``handler`` is an `XMLGenerator`_ from Python's
|
||||
built-in SAX library; you'll call methods on it to add to the XML
|
||||
document in process.
|
||||
(``feed``/``channel``). ``handler`` is an
|
||||
:class:`~xml.sax.saxutils.XMLGenerator` from Python's built-in SAX library;
|
||||
you'll call methods on it to add to the XML document in process.
|
||||
|
||||
``SyndicationFeed.item_attributes(self, item)``
|
||||
Return a ``dict`` of attributes to add to each item (``item``/``entry``)
|
||||
|
|
@ -945,5 +945,3 @@ For example, you might start implementing an iTunes RSS feed generator like so::
|
|||
|
||||
Obviously there's a lot more work to be done for a complete custom feed class,
|
||||
but the above example should demonstrate the basic idea.
|
||||
|
||||
.. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator
|
||||
|
|
|
|||
|
|
@ -455,7 +455,7 @@ Example usage::
|
|||
.. django-admin-option:: --ignore
|
||||
|
||||
Use the ``--ignore`` or ``-i`` option to ignore files or directories matching
|
||||
the given `glob-style pattern`_. Use multiple times to ignore more.
|
||||
the given :mod:`glob`-style pattern. Use multiple times to ignore more.
|
||||
|
||||
These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'``
|
||||
|
||||
|
|
@ -463,8 +463,6 @@ Example usage::
|
|||
|
||||
django-admin.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html
|
||||
|
||||
.. _`glob-style pattern`: http://docs.python.org/library/glob.html
|
||||
|
||||
.. django-admin-option:: --no-default-ignore
|
||||
|
||||
Use the ``--no-default-ignore`` option to disable the default values of
|
||||
|
|
|
|||
|
|
@ -128,10 +128,8 @@ provided in :mod:`django.db`.
|
|||
.. exception:: IntegrityError
|
||||
|
||||
The Django wrappers for database exceptions behave exactly the same as
|
||||
the underlying database exceptions. See `PEP 249 - Python Database API
|
||||
Specification v2.0`_ for further information.
|
||||
|
||||
.. _`PEP 249 - Python Database API Specification v2.0`: http://www.python.org/dev/peps/pep-0249/
|
||||
the underlying database exceptions. See :pep:`249`, the Python Database API
|
||||
Specification v2.0, for further information.
|
||||
|
||||
.. currentmodule:: django.db.transaction
|
||||
|
||||
|
|
@ -147,8 +145,6 @@ Transaction Exceptions
|
|||
Python Exceptions
|
||||
=================
|
||||
|
||||
Django raises built-in Python exceptions when appropriate as well. See
|
||||
the Python `documentation`_ for further information on the built-in
|
||||
exceptions.
|
||||
|
||||
.. _`documentation`: http://docs.python.org/lib/module-exceptions.html
|
||||
Django raises built-in Python exceptions when appropriate as well. See the
|
||||
Python documentation for further information on the
|
||||
built-in :mod:`exceptions`.
|
||||
|
|
|
|||
|
|
@ -639,13 +639,11 @@ A field containing either an IPv4 or an IPv6 address.
|
|||
* Validates that the given value is a valid IP address.
|
||||
* Error message keys: ``required``, ``invalid``
|
||||
|
||||
The IPv6 address normalization follows `RFC4291 section 2.2`_, including using
|
||||
the IPv4 format suggested in paragraph 3 of that section, like
|
||||
The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2,
|
||||
including using the IPv4 format suggested in paragraph 3 of that section, like
|
||||
``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to
|
||||
``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All
|
||||
characters are converted to lowercase.
|
||||
|
||||
.. _RFC4291 section 2.2: http://tools.ietf.org/html/rfc4291#section-2.2
|
||||
``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters
|
||||
are converted to lowercase.
|
||||
|
||||
Takes two optional arguments:
|
||||
|
||||
|
|
|
|||
|
|
@ -346,11 +346,11 @@ date in the *future* are not displayed unless you set ``allow_future`` to
|
|||
|
||||
**Optional arguments:**
|
||||
|
||||
* ``month_format``: A format string that regulates what format the
|
||||
``month`` parameter uses. This should be in the syntax accepted by
|
||||
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
|
||||
``"%b"`` by default, which is a three-letter month abbreviation. To
|
||||
change it to use numbers, use ``"%m"``.
|
||||
* ``month_format``: A format string that regulates what format the ``month``
|
||||
parameter uses. This should be in the syntax accepted by Python's
|
||||
:func:`~time.strftime`. It's set to ``"%b"`` by default, which is a
|
||||
three-letter month abbreviation. To change it to use numbers, use
|
||||
``"%m"``.
|
||||
|
||||
* ``template_name``: The full name of a template to use in rendering the
|
||||
page. This lets you override the default template name (see below).
|
||||
|
|
@ -415,8 +415,6 @@ In addition to ``extra_context``, the template's context will be:
|
|||
is ``'object'`` by default. If ``template_object_name`` is ``'foo'``,
|
||||
this variable's name will be ``foo_list``.
|
||||
|
||||
.. _strftime docs: http://docs.python.org/library/time.html#time.strftime
|
||||
|
||||
``django.views.generic.date_based.archive_week``
|
||||
------------------------------------------------
|
||||
|
||||
|
|
@ -516,11 +514,11 @@ you set ``allow_future`` to ``True``.
|
|||
|
||||
**Optional arguments:**
|
||||
|
||||
* ``month_format``: A format string that regulates what format the
|
||||
``month`` parameter uses. This should be in the syntax accepted by
|
||||
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
|
||||
``"%b"`` by default, which is a three-letter month abbreviation. To
|
||||
change it to use numbers, use ``"%m"``.
|
||||
* ``month_format``: A format string that regulates what format the ``month``
|
||||
parameter uses. This should be in the syntax accepted by Python's
|
||||
:func:`~time.strftime`. It's set to ``"%b"`` by default, which is a
|
||||
three-letter month abbreviation. To change it to use numbers, use
|
||||
``"%m"``.
|
||||
|
||||
* ``day_format``: Like ``month_format``, but for the ``day`` parameter.
|
||||
It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
|
||||
|
|
@ -624,11 +622,11 @@ future, the view will throw a 404 error by default, unless you set
|
|||
|
||||
**Optional arguments:**
|
||||
|
||||
* ``month_format``: A format string that regulates what format the
|
||||
``month`` parameter uses. This should be in the syntax accepted by
|
||||
Python's ``time.strftime``. (See the `strftime docs`_.) It's set to
|
||||
``"%b"`` by default, which is a three-letter month abbreviation. To
|
||||
change it to use numbers, use ``"%m"``.
|
||||
* ``month_format``: A format string that regulates what format the ``month``
|
||||
parameter uses. This should be in the syntax accepted by Python's
|
||||
:func:`~time.strftime`. It's set to ``"%b"`` by default, which is a
|
||||
three-letter month abbreviation. To change it to use numbers, use
|
||||
``"%m"``.
|
||||
|
||||
* ``day_format``: Like ``month_format``, but for the ``day`` parameter.
|
||||
It defaults to ``"%d"`` (day of the month as a decimal number, 01-31).
|
||||
|
|
|
|||
|
|
@ -500,9 +500,9 @@ Has one **required** argument:
|
|||
setting to determine the value of the :attr:`~django.core.files.File.url`
|
||||
attribute.
|
||||
|
||||
This path may contain `strftime formatting`_, which will be replaced by the
|
||||
date/time of the file upload (so that uploaded files don't fill up the given
|
||||
directory).
|
||||
This path may contain :func:`~time.strftime` formatting, which will be
|
||||
replaced by the date/time of the file upload (so that uploaded files don't
|
||||
fill up the given directory).
|
||||
|
||||
This may also be a callable, such as a function, which will be called to
|
||||
obtain the upload path, including the filename. This callable must be able
|
||||
|
|
@ -560,10 +560,10 @@ takes a few steps:
|
|||
|
||||
For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and
|
||||
:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'``
|
||||
part of :attr:`~FileField.upload_to` is `strftime formatting`_; ``'%Y'`` is the
|
||||
four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is the two-digit
|
||||
day. If you upload a file on Jan. 15, 2007, it will be saved in the directory
|
||||
``/home/media/photos/2007/01/15``.
|
||||
part of :attr:`~FileField.upload_to` is :func:`~time.strftime` formatting;
|
||||
``'%Y'`` is the four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is
|
||||
the two-digit day. If you upload a file on Jan. 15, 2007, it will be saved in
|
||||
the directory ``/home/media/photos/2007/01/15``.
|
||||
|
||||
If you wanted to retrieve the uploaded file's on-disk filename, or the file's
|
||||
size, you could use the :attr:`~django.core.files.File.name` and
|
||||
|
|
@ -595,8 +595,6 @@ By default, :class:`FileField` instances are
|
|||
created as ``varchar(100)`` columns in your database. As with other fields, you
|
||||
can change the maximum length using the :attr:`~CharField.max_length` argument.
|
||||
|
||||
.. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime
|
||||
|
||||
FileField and FieldFile
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
@ -711,11 +709,8 @@ The admin represents this as an ``<input type="text">`` (a single-line input).
|
|||
:class:`DecimalField` class. Although they both represent real numbers, they
|
||||
represent those numbers differently. ``FloatField`` uses Python's ``float``
|
||||
type internally, while ``DecimalField`` uses Python's ``Decimal`` type. For
|
||||
information on the difference between the two, see Python's documentation on
|
||||
`Decimal fixed point and floating point arithmetic`_.
|
||||
|
||||
.. _Decimal fixed point and floating point arithmetic: http://docs.python.org/library/decimal.html
|
||||
|
||||
information on the difference between the two, see Python's documentation
|
||||
for the :mod:`decimal` module.
|
||||
|
||||
``ImageField``
|
||||
--------------
|
||||
|
|
@ -777,13 +772,11 @@ An IPv4 or IPv6 address, in string format (e.g. ``192.0.2.30`` or
|
|||
``2a02:42fe::4``). The admin represents this as an ``<input type="text">``
|
||||
(a single-line input).
|
||||
|
||||
The IPv6 address normalization follows `RFC4291 section 2.2`_, including using
|
||||
the IPv4 format suggested in paragraph 3 of that section, like
|
||||
The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2,
|
||||
including using the IPv4 format suggested in paragraph 3 of that section, like
|
||||
``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to
|
||||
``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All
|
||||
characters are converted to lowercase.
|
||||
|
||||
.. _RFC4291 section 2.2: http://tools.ietf.org/html/rfc4291#section-2.2
|
||||
``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters
|
||||
are converted to lowercase.
|
||||
|
||||
.. attribute:: GenericIPAddressField.protocol
|
||||
|
||||
|
|
|
|||
|
|
@ -454,7 +454,7 @@ in ``get_absolute_url()`` and have all your other code call that one place.
|
|||
|
||||
.. note::
|
||||
The string you return from ``get_absolute_url()`` **must** contain only
|
||||
ASCII characters (required by the URI specfication, `RFC 2396`_) and be
|
||||
ASCII characters (required by the URI specfication, :rfc:`2396`) and be
|
||||
URL-encoded, if necessary.
|
||||
|
||||
Code and templates calling ``get_absolute_url()`` should be able to use the
|
||||
|
|
@ -463,8 +463,6 @@ in ``get_absolute_url()`` and have all your other code call that one place.
|
|||
are using unicode strings containing characters outside the ASCII range at
|
||||
all.
|
||||
|
||||
.. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt
|
||||
|
||||
The ``permalink`` decorator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
|
|||
|
|
@ -81,7 +81,7 @@ You can evaluate a ``QuerySet`` in the following ways:
|
|||
Pickling QuerySets
|
||||
------------------
|
||||
|
||||
If you pickle_ a ``QuerySet``, this will force all the results to be loaded
|
||||
If you :mod:`pickle` a ``QuerySet``, this will force all the results to be loaded
|
||||
into memory prior to pickling. Pickling is usually used as a precursor to
|
||||
caching and when the cached queryset is reloaded, you want the results to
|
||||
already be present and ready for use (reading from the database can take some
|
||||
|
|
@ -112,8 +112,6 @@ described here.
|
|||
Django version N+1. Pickles should not be used as part of a long-term
|
||||
archival strategy.
|
||||
|
||||
.. _pickle: http://docs.python.org/library/pickle.html
|
||||
|
||||
.. _queryset-api:
|
||||
|
||||
QuerySet API
|
||||
|
|
@ -1210,20 +1208,18 @@ iterator
|
|||
|
||||
.. method:: iterator()
|
||||
|
||||
Evaluates the ``QuerySet`` (by performing the query) and returns an `iterator`_
|
||||
over the results. A ``QuerySet`` typically caches its results internally so
|
||||
that repeated evaluations do not result in additional queries. In contrast,
|
||||
``iterator()`` will read results directly, without doing any caching at the
|
||||
``QuerySet`` level (internally, the default iterator calls ``iterator()`` and
|
||||
caches the return value). For a ``QuerySet`` which returns a large number of
|
||||
Evaluates the ``QuerySet`` (by performing the query) and returns an iterator
|
||||
(see :pep:`234`) over the results. A ``QuerySet`` typically caches its results
|
||||
internally so that repeated evaluations do not result in additional queries. In
|
||||
contrast, ``iterator()`` will read results directly, without doing any caching
|
||||
at the ``QuerySet`` level (internally, the default iterator calls ``iterator()``
|
||||
and caches the return value). For a ``QuerySet`` which returns a large number of
|
||||
objects that you only need to access once, this can results in better
|
||||
performance and a significant reduction in memory.
|
||||
|
||||
Note that using ``iterator()`` on a ``QuerySet`` which has already been
|
||||
evaluated will force it to evaluate again, repeating the query.
|
||||
|
||||
.. _iterator: http://www.python.org/dev/peps/pep-0234/
|
||||
|
||||
latest
|
||||
~~~~~~
|
||||
|
||||
|
|
|
|||
|
|
@ -196,9 +196,7 @@ Methods
|
|||
Returns the originating host of the request using information from the
|
||||
``HTTP_X_FORWARDED_HOST`` and ``HTTP_HOST`` headers (in that order). If
|
||||
they don't provide a value, the method uses a combination of
|
||||
``SERVER_NAME`` and ``SERVER_PORT`` as detailed in `PEP 333`_.
|
||||
|
||||
.. _PEP 333: http://www.python.org/dev/peps/pep-0333/
|
||||
``SERVER_NAME`` and ``SERVER_PORT`` as detailed in :pep:`3333`.
|
||||
|
||||
Example: ``"127.0.0.1:8000"``
|
||||
|
||||
|
|
@ -645,7 +643,7 @@ Methods
|
|||
``expires``, and the auto-calculation of ``max_age`` in such case
|
||||
was added. The ``httponly`` argument was also added.
|
||||
|
||||
Sets a cookie. The parameters are the same as in the `cookie Morsel`_
|
||||
Sets a cookie. The parameters are the same as in the :class:`Cookie.Morsel`
|
||||
object in the Python standard library.
|
||||
|
||||
* ``max_age`` should be a number of seconds, or ``None`` (default) if
|
||||
|
|
@ -664,13 +662,12 @@ Methods
|
|||
JavaScript from having access to the cookie.
|
||||
|
||||
HTTPOnly_ is a flag included in a Set-Cookie HTTP response
|
||||
header. It is not part of the RFC2109 standard for cookies,
|
||||
header. It is not part of the :rfc:`2109` standard for cookies,
|
||||
and it isn't honored consistently by all browsers. However,
|
||||
when it is honored, it can be a useful way to mitigate the
|
||||
risk of client side script accessing the protected cookie
|
||||
data.
|
||||
|
||||
.. _`cookie Morsel`: http://docs.python.org/library/cookie.html#Cookie.Morsel
|
||||
.. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly
|
||||
|
||||
.. method:: HttpResponse.set_signed_cookie(key, value='', salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=False)
|
||||
|
|
|
|||
|
|
@ -1010,8 +1010,8 @@ FILE_UPLOAD_PERMISSIONS
|
|||
Default: ``None``
|
||||
|
||||
The numeric mode (i.e. ``0644``) to set newly uploaded files to. For
|
||||
more information about what these modes mean, see the `documentation for
|
||||
os.chmod`_
|
||||
more information about what these modes mean, see the documentation for
|
||||
:func:`os.chmod`.
|
||||
|
||||
If this isn't given or is ``None``, you'll get operating-system
|
||||
dependent behavior. On most platforms, temporary files will have a mode
|
||||
|
|
@ -1028,8 +1028,6 @@ system's standard umask.
|
|||
get totally incorrect behavior.
|
||||
|
||||
|
||||
.. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod
|
||||
|
||||
.. setting:: FILE_UPLOAD_TEMP_DIR
|
||||
|
||||
FILE_UPLOAD_TEMP_DIR
|
||||
|
|
@ -1586,7 +1584,7 @@ Whether to use HTTPOnly flag on the session cookie. If this is set to
|
|||
session cookie.
|
||||
|
||||
HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It
|
||||
is not part of the RFC2109 standard for cookies, and it isn't honored
|
||||
is not part of the :rfc:`2109` standard for cookies, and it isn't honored
|
||||
consistently by all browsers. However, when it is honored, it can be a
|
||||
useful way to mitigate the risk of client side script accessing the
|
||||
protected cookie data.
|
||||
|
|
|
|||
|
|
@ -1254,7 +1254,8 @@ Available format strings:
|
|||
c ISO 8601 format. (Note: unlike others ``2008-01-02T10:30:00.000123+02:00``,
|
||||
formatters, such as "Z", "O" or "r", or ``2008-01-02T10:30:00.000123`` if the datetime is naive
|
||||
the "c" formatter will not add timezone
|
||||
offset if value is a `naive datetime`_.)
|
||||
offset if value is a naive datetime
|
||||
(see :class:`datetime.tzinfo`).
|
||||
d Day of the month, 2 digits with ``'01'`` to ``'31'``
|
||||
leading zeros.
|
||||
D Day of the week, textual, 3 letters. ``'Fri'``
|
||||
|
|
@ -1288,7 +1289,7 @@ Available format strings:
|
|||
if they're zero and the special-case
|
||||
strings 'midnight' and 'noon' if
|
||||
appropriate. Proprietary extension.
|
||||
r RFC 2822 formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'``
|
||||
r :rfc:`2822` formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'``
|
||||
s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'``
|
||||
S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'``
|
||||
month, 2 characters.
|
||||
|
|
@ -1346,8 +1347,6 @@ used, without applying any localization.
|
|||
.. versionchanged:: 1.2
|
||||
Predefined formats can now be influenced by the current locale.
|
||||
|
||||
.. _naive datetime: http://docs.python.org/library/datetime.html#datetime.tzinfo
|
||||
|
||||
.. templatefilter:: default
|
||||
|
||||
default
|
||||
|
|
@ -1815,9 +1814,7 @@ Example::
|
|||
pprint
|
||||
^^^^^^
|
||||
|
||||
A wrapper around `pprint.pprint`__ -- for debugging, really.
|
||||
|
||||
__ http://docs.python.org/library/pprint.html
|
||||
A wrapper around :func:`pprint.pprint` -- for debugging, really.
|
||||
|
||||
.. templatefilter:: random
|
||||
|
||||
|
|
|
|||
|
|
@ -148,13 +148,12 @@ URI and IRI handling
|
|||
Web frameworks have to deal with URLs (which are a type of IRI_). One
|
||||
requirement of URLs is that they are encoded using only ASCII characters.
|
||||
However, in an international environment, you might need to construct a
|
||||
URL from an IRI_ -- very loosely speaking, a URI that can contain Unicode
|
||||
URL from an IRI_ -- very loosely speaking, a URI_ that can contain Unicode
|
||||
characters. Quoting and converting an IRI to URI can be a little tricky, so
|
||||
Django provides some assistance.
|
||||
|
||||
* The function ``django.utils.encoding.iri_to_uri()`` implements the
|
||||
conversion from IRI to URI as required by the specification (`RFC
|
||||
3987`_).
|
||||
conversion from IRI to URI as required by the specification (:rfc:`3987`).
|
||||
|
||||
* The functions ``django.utils.http.urlquote()`` and
|
||||
``django.utils.http.urlquote_plus()`` are versions of Python's standard
|
||||
|
|
@ -203,7 +202,6 @@ double-quoting problems.
|
|||
|
||||
.. _URI: http://www.ietf.org/rfc/rfc2396.txt
|
||||
.. _IRI: http://www.ietf.org/rfc/rfc3987.txt
|
||||
.. _RFC 3987: IRI_
|
||||
|
||||
Models
|
||||
======
|
||||
|
|
|
|||
|
|
@ -21,9 +21,8 @@ managing the ``Vary`` header of responses. It includes functions to patch the
|
|||
header of response objects directly and decorators that change functions to do
|
||||
that header-patching themselves.
|
||||
|
||||
For information on the ``Vary`` header, see `RFC 2616 section 14.44`_.
|
||||
|
||||
.. _RFC 2616 section 14.44: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44
|
||||
For information on the ``Vary`` header, see :rfc:`2616#section-14.44` section
|
||||
14.44.
|
||||
|
||||
Essentially, the ``Vary`` HTTP header defines which headers a cache should take
|
||||
into account when building its cache key. Requests with the same path but
|
||||
|
|
@ -179,11 +178,9 @@ results. Instead do::
|
|||
Convert an Internationalized Resource Identifier (IRI) portion to a URI
|
||||
portion that is suitable for inclusion in a URL.
|
||||
|
||||
This is the algorithm from section 3.1 of `RFC 3987`_. However, since we
|
||||
are assuming input is either UTF-8 or unicode already, we can simplify
|
||||
things a little from the full method.
|
||||
|
||||
.. _RFC 3987: http://www.ietf.org/rfc/rfc3987.txt
|
||||
This is the algorithm from section 3.1 of :rfc:`3987#section-3.1`. However,
|
||||
since we are assuming input is either UTF-8 or unicode already, we can
|
||||
simplify things a little from the full method.
|
||||
|
||||
Returns an ASCII string containing the encoded result.
|
||||
|
||||
|
|
@ -397,10 +394,8 @@ Atom1Feed
|
|||
|
||||
.. function:: http_date(epoch_seconds=None)
|
||||
|
||||
Formats the time to match the RFC 1123 date format as specified by HTTP
|
||||
`RFC 2616`_ section 3.3.1.
|
||||
|
||||
.. _RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616.txt
|
||||
Formats the time to match the :rfc:`1123` date format as specified by HTTP
|
||||
:rfc:`2616#section-3.3.1` section 3.3.1.
|
||||
|
||||
Accepts a floating point number expressed in seconds since the epoch in
|
||||
UTC--such as that outputted by ``time.time()``. If set to ``None``,
|
||||
|
|
|
|||
|
|
@ -216,8 +216,8 @@ The test framework
|
|||
------------------
|
||||
|
||||
Django now includes a test framework so you can start transmuting fear into
|
||||
boredom (with apologies to Kent Beck). You can write tests based on doctest_
|
||||
or unittest_ and test your views with a simple test client.
|
||||
boredom (with apologies to Kent Beck). You can write tests based on
|
||||
:mod:`doctest` or :mod:`unittest` and test your views with a simple test client.
|
||||
|
||||
There is also new support for "fixtures" -- initial data, stored in any of the
|
||||
supported `serialization formats`_, that will be loaded into your database at the
|
||||
|
|
@ -225,8 +225,6 @@ start of your tests. This makes testing with real data much easier.
|
|||
|
||||
See `the testing documentation`_ for the full details.
|
||||
|
||||
.. _doctest: http://docs.python.org/library/doctest.html
|
||||
.. _unittest: http://docs.python.org/library/unittest.html
|
||||
.. _the testing documentation: http://www.djangoproject.com/documentation/0.96/testing/
|
||||
.. _serialization formats: http://www.djangoproject.com/documentation/0.96/serialization/
|
||||
|
||||
|
|
|
|||
|
|
@ -764,10 +764,8 @@ over the next few release cycles.
|
|||
|
||||
Code taking advantage of any of the features below will raise a
|
||||
``PendingDeprecationWarning`` in Django 1.2. This warning will be
|
||||
silent by default, but may be turned on using Python's `warnings
|
||||
module`_, or by running Python with a ``-Wd`` or `-Wall` flag.
|
||||
|
||||
.. _warnings module: http://docs.python.org/library/warnings.html
|
||||
silent by default, but may be turned on using Python's :mod:`warnings`
|
||||
module, or by running Python with a ``-Wd`` or `-Wall` flag.
|
||||
|
||||
In Django 1.3, these warnings will become a ``DeprecationWarning``,
|
||||
which is *not* silent. In Django 1.4 support for these features will
|
||||
|
|
|
|||
|
|
@ -279,10 +279,8 @@ over the next few release cycles.
|
|||
|
||||
Code taking advantage of any of the features below will raise a
|
||||
``PendingDeprecationWarning`` in Django 1.3. This warning will be
|
||||
silent by default, but may be turned on using Python's `warnings
|
||||
module`_, or by running Python with a ``-Wd`` or `-Wall` flag.
|
||||
|
||||
.. _warnings module: http://docs.python.org/library/warnings.html
|
||||
silent by default, but may be turned on using Python's :mod:`warnings`
|
||||
module, or by running Python with a ``-Wd`` or `-Wall` flag.
|
||||
|
||||
In Django 1.4, these warnings will become a ``DeprecationWarning``,
|
||||
which is *not* silent. In Django 1.5 support for these features will
|
||||
|
|
|
|||
|
|
@ -664,10 +664,8 @@ over the next few release cycles.
|
|||
|
||||
Code taking advantage of any of the features below will raise a
|
||||
``PendingDeprecationWarning`` in Django 1.3. This warning will be
|
||||
silent by default, but may be turned on using Python's `warnings
|
||||
module`_, or by running Python with a ``-Wd`` or `-Wall` flag.
|
||||
|
||||
.. _warnings module: http://docs.python.org/library/warnings.html
|
||||
silent by default, but may be turned on using Python's :mod:`warnings`
|
||||
module, or by running Python with a ``-Wd`` or `-Wall` flag.
|
||||
|
||||
In Django 1.4, these warnings will become a ``DeprecationWarning``,
|
||||
which is *not* silent. In Django 1.5 support for these features will
|
||||
|
|
|
|||
|
|
@ -495,7 +495,7 @@ CSRF protection extended to PUT and DELETE
|
|||
Previously, Django's :doc:`CSRF protection </ref/contrib/csrf/>` provided
|
||||
protection against only POST requests. Since use of PUT and DELETE methods in
|
||||
AJAX applications is becoming more common, we now protect all methods not
|
||||
defined as safe by RFC 2616 i.e. we exempt GET, HEAD, OPTIONS and TRACE, and
|
||||
defined as safe by :rfc:`2616` i.e. we exempt GET, HEAD, OPTIONS and TRACE, and
|
||||
enforce protection on everything else.
|
||||
|
||||
If you using PUT or DELETE methods in AJAX applications, please see the
|
||||
|
|
|
|||
|
|
@ -676,10 +676,7 @@ For example, this model has a few custom methods::
|
|||
return '%s %s' % (self.first_name, self.last_name)
|
||||
full_name = property(_get_full_name)
|
||||
|
||||
The last method in this example is a :term:`property`. `Read more about
|
||||
properties`_.
|
||||
|
||||
.. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property
|
||||
The last method in this example is a :term:`property`.
|
||||
|
||||
The :doc:`model instance reference </ref/models/instances>` has a complete list
|
||||
of :ref:`methods automatically given to each model <model-instance-methods>`.
|
||||
|
|
|
|||
|
|
@ -259,14 +259,12 @@ as dirty using ``transaction.set_dirty()`` when using raw SQL calls.
|
|||
Connections and cursors
|
||||
-----------------------
|
||||
|
||||
``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_
|
||||
(except when it comes to :doc:`transaction handling </topics/db/transactions>`).
|
||||
If you're not familiar with the Python DB-API, note that the SQL statement in
|
||||
``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters
|
||||
directly within the SQL. If you use this technique, the underlying database
|
||||
library will automatically add quotes and escaping to your parameter(s) as
|
||||
necessary. (Also note that Django expects the ``"%s"`` placeholder, *not* the
|
||||
``"?"`` placeholder, which is used by the SQLite Python bindings. This is for
|
||||
the sake of consistency and sanity.)
|
||||
|
||||
.. _Python DB-API: http://www.python.org/dev/peps/pep-0249/
|
||||
``connection`` and ``cursor`` mostly implement the standard Python DB-API
|
||||
described in :pep:`249` (except when it comes to :doc:`transaction handling
|
||||
</topics/db/transactions>`). If you're not familiar with the Python DB-API, note
|
||||
that the SQL statement in ``cursor.execute()`` uses placeholders, ``"%s"``,
|
||||
rather than adding parameters directly within the SQL. If you use this
|
||||
technique, the underlying database library will automatically add quotes and
|
||||
escaping to your parameter(s) as necessary. (Also note that Django expects the
|
||||
``"%s"`` placeholder, *not* the ``"?"`` placeholder, which is used by the SQLite
|
||||
Python bindings. This is for the sake of consistency and sanity.)
|
||||
|
|
|
|||
|
|
@ -5,16 +5,14 @@ Sending email
|
|||
.. module:: django.core.mail
|
||||
:synopsis: Helpers to easily send email.
|
||||
|
||||
Although Python makes sending email relatively easy via the `smtplib
|
||||
library`_, Django provides a couple of light wrappers over it. These wrappers
|
||||
are provided to make sending email extra quick, to make it easy to test
|
||||
email sending during development, and to provide support for platforms that
|
||||
can't use SMTP.
|
||||
Although Python makes sending email relatively easy via the :mod:`smtplib`
|
||||
module, Django provides a couple of light wrappers over it. These wrappers are
|
||||
provided to make sending email extra quick, to make it easy to test email
|
||||
sending during development, and to provide support for platforms that can't use
|
||||
SMTP.
|
||||
|
||||
The code lives in the ``django.core.mail`` module.
|
||||
|
||||
.. _smtplib library: http://docs.python.org/library/smtplib.html
|
||||
|
||||
Quick example
|
||||
=============
|
||||
|
||||
|
|
@ -54,8 +52,9 @@ are required.
|
|||
member of ``recipient_list`` will see the other recipients in the "To:"
|
||||
field of the email message.
|
||||
* ``fail_silently``: A boolean. If it's ``False``, ``send_mail`` will raise
|
||||
an ``smtplib.SMTPException``. See the `smtplib docs`_ for a list of
|
||||
possible exceptions, all of which are subclasses of ``SMTPException``.
|
||||
an :exc:`smtplib.SMTPException`. See the :mod:`smtplib` docs for a list of
|
||||
possible exceptions, all of which are subclasses of
|
||||
:exc:`~smtplib.SMTPException`.
|
||||
* ``auth_user``: The optional username to use to authenticate to the SMTP
|
||||
server. If this isn't provided, Django will use the value of the
|
||||
:setting:`EMAIL_HOST_USER` setting.
|
||||
|
|
@ -67,8 +66,6 @@ are required.
|
|||
See the documentation on :ref:`Email backends <topic-email-backends>`
|
||||
for more details.
|
||||
|
||||
.. _smtplib docs: http://docs.python.org/library/smtplib.html
|
||||
|
||||
send_mass_mail()
|
||||
================
|
||||
|
||||
|
|
@ -125,8 +122,9 @@ This method exists for convenience and readability.
|
|||
.. versionchanged:: 1.3
|
||||
|
||||
If ``html_message`` is provided, the resulting email will be a
|
||||
multipart/alternative email with ``message`` as the "text/plain"
|
||||
content type and ``html_message`` as the "text/html" content type.
|
||||
:mimetype:`multipart/alternative` email with ``message`` as the
|
||||
:mimetype:`text/plain` content type and ``html_message`` as the
|
||||
:mimetype:`text/html` content type.
|
||||
|
||||
mail_managers()
|
||||
===============
|
||||
|
|
@ -608,9 +606,7 @@ the email body. You then only need to set the :setting:`EMAIL_HOST` and
|
|||
:setting:`EMAIL_PORT` accordingly, and you are set.
|
||||
|
||||
For a more detailed discussion of testing and processing of emails locally,
|
||||
see the Python documentation on the `SMTP Server`_.
|
||||
|
||||
.. _SMTP Server: http://docs.python.org/library/smtpd.html
|
||||
see the Python documentation for the :mod:`smtpd` module.
|
||||
|
||||
SMTPConnection
|
||||
==============
|
||||
|
|
|
|||
|
|
@ -149,8 +149,8 @@ Three settings control Django's file upload behavior:
|
|||
|
||||
:setting:`FILE_UPLOAD_PERMISSIONS`
|
||||
The numeric mode (i.e. ``0644``) to set newly uploaded files to. For
|
||||
more information about what these modes mean, see the `documentation for
|
||||
os.chmod`_
|
||||
more information about what these modes mean, see the documentation for
|
||||
:func:`os.chmod`.
|
||||
|
||||
If this isn't given or is ``None``, you'll get operating-system
|
||||
dependent behavior. On most platforms, temporary files will have a mode
|
||||
|
|
@ -179,8 +179,6 @@ Three settings control Django's file upload behavior:
|
|||
Which means "try to upload to memory first, then fall back to temporary
|
||||
files."
|
||||
|
||||
.. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod
|
||||
|
||||
``UploadedFile`` objects
|
||||
========================
|
||||
|
||||
|
|
@ -189,16 +187,16 @@ define the following methods/attributes:
|
|||
|
||||
.. attribute:: UploadedFile.content_type
|
||||
|
||||
The content-type header uploaded with the file (e.g. ``text/plain`` or
|
||||
``application/pdf``). Like any data supplied by the user, you shouldn't
|
||||
trust that the uploaded file is actually this type. You'll still need to
|
||||
validate that the file contains the content that the content-type header
|
||||
claims -- "trust but verify."
|
||||
The content-type header uploaded with the file (e.g. :mimetype:`text/plain`
|
||||
or :mimetype:`application/pdf`). Like any data supplied by the user, you
|
||||
shouldn't trust that the uploaded file is actually this type. You'll still
|
||||
need to validate that the file contains the content that the content-type
|
||||
header claims -- "trust but verify."
|
||||
|
||||
.. attribute:: UploadedFile.charset
|
||||
|
||||
For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied
|
||||
by the browser. Again, "trust but verify" is the best policy here.
|
||||
For :mimetype:`text/*` content-types, the character set (i.e. ``utf8``)
|
||||
supplied by the browser. Again, "trust but verify" is the best policy here.
|
||||
|
||||
.. attribute:: UploadedFile.temporary_file_path()
|
||||
|
||||
|
|
|
|||
|
|
@ -495,7 +495,7 @@ Whether to use HTTPOnly flag on the session cookie. If this is set to
|
|||
session cookie.
|
||||
|
||||
HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It
|
||||
is not part of the RFC2109 standard for cookies, and it isn't honored
|
||||
is not part of the :rfc:`2109` standard for cookies, and it isn't honored
|
||||
consistently by all browsers. However, when it is honored, it can be a
|
||||
useful way to mitigate the risk of client side script accessing the
|
||||
protected cookie data.
|
||||
|
|
@ -553,15 +553,13 @@ Technical details
|
|||
=================
|
||||
|
||||
* The session dictionary should accept any pickleable Python object. See
|
||||
`the pickle module`_ for more information.
|
||||
the :mod:`pickle` module for more information.
|
||||
|
||||
* Session data is stored in a database table named ``django_session`` .
|
||||
|
||||
* Django only sends a cookie if it needs to. If you don't set any session
|
||||
data, it won't send a session cookie.
|
||||
|
||||
.. _`the pickle module`: http://docs.python.org/library/pickle.html
|
||||
|
||||
Session IDs in URLs
|
||||
===================
|
||||
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ Example
|
|||
-------
|
||||
|
||||
The following example renders the template ``myapp/index.html`` with the
|
||||
MIME type ``application/xhtml+xml``::
|
||||
MIME type :mimetype:`application/xhtml+xml`::
|
||||
|
||||
from django.shortcuts import render
|
||||
|
||||
|
|
@ -131,7 +131,7 @@ Example
|
|||
-------
|
||||
|
||||
The following example renders the template ``myapp/index.html`` with the
|
||||
MIME type ``application/xhtml+xml``::
|
||||
MIME type :mimetype:`application/xhtml+xml`::
|
||||
|
||||
from django.shortcuts import render_to_response
|
||||
|
||||
|
|
|
|||
|
|
@ -211,7 +211,7 @@ default, call the view ``django.views.defaults.permission_denied``.
|
|||
|
||||
This view loads and renders the template ``403.html`` in your root template
|
||||
directory, or if this file does not exist, instead serves the text
|
||||
"403 Forbidden", as per RFC 2616 (the HTTP 1.1 Specification).
|
||||
"403 Forbidden", as per :rfc:`2616` (the HTTP 1.1 Specification).
|
||||
|
||||
It is possible to override ``django.views.defaults.permission_denied`` in the
|
||||
same way you can for the 404 and 500 views by specifying a ``handler403`` in
|
||||
|
|
|
|||
|
|
@ -52,19 +52,17 @@ See :doc:`How to use Django with mod_wsgi </howto/deployment/modwsgi>`
|
|||
for information on how to configure mod_wsgi once you have it
|
||||
installed.
|
||||
|
||||
If you can't use mod_wsgi for some reason, fear not: Django supports
|
||||
many other deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`;
|
||||
it works very well with `nginx`_. Another is :doc:`FastCGI
|
||||
</howto/deployment/fastcgi>`, perfect for using Django with servers
|
||||
other than Apache. Additionally, Django follows the WSGI_ spec, which
|
||||
allows it to run on a variety of server platforms. See the
|
||||
`server-arrangements wiki page`_ for specific installation
|
||||
instructions for each platform.
|
||||
If you can't use mod_wsgi for some reason, fear not: Django supports many other
|
||||
deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`; it works
|
||||
very well with `nginx`_. Another is :doc:`FastCGI </howto/deployment/fastcgi>`,
|
||||
perfect for using Django with servers other than Apache. Additionally, Django
|
||||
follows the WSGI spec (:pep:`3333`), which allows it to run on a variety of
|
||||
server platforms. See the `server-arrangements wiki page`_ for specific
|
||||
installation instructions for each platform.
|
||||
|
||||
.. _Apache: http://httpd.apache.org/
|
||||
.. _nginx: http://nginx.net/
|
||||
.. _mod_wsgi: http://code.google.com/p/modwsgi/
|
||||
.. _WSGI: http://www.python.org/dev/peps/pep-0333/
|
||||
.. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
|
||||
|
||||
.. _database-installation:
|
||||
|
|
|
|||
|
|
@ -10,12 +10,10 @@ Logging
|
|||
A quick logging primer
|
||||
======================
|
||||
|
||||
Django uses Python's builtin logging module to perform system logging.
|
||||
The usage of the logging module is discussed in detail in `Python's
|
||||
own documentation`_. However, if you've never used Python's logging
|
||||
framework (or even if you have), here's a quick primer.
|
||||
|
||||
.. _Python's own documentation: http://docs.python.org/library/logging.html
|
||||
Django uses Python's builtin :mod:`logging` module to perform system logging.
|
||||
The usage of this module is discussed in detail in Python's own documentation.
|
||||
However, if you've never used Python's logging framework (or even if you have),
|
||||
here's a quick primer.
|
||||
|
||||
The cast of players
|
||||
-------------------
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ two test frameworks that ship in the Python standard library. The two
|
|||
frameworks are:
|
||||
|
||||
* **Unit tests** -- tests that are expressed as methods on a Python class
|
||||
that subclasses ``unittest.TestCase`` or Django's customized
|
||||
that subclasses :class:`unittest.TestCase` or Django's customized
|
||||
:class:`TestCase`. For example::
|
||||
|
||||
import unittest
|
||||
|
|
@ -68,7 +68,7 @@ test framework, as we'll explain in a bit.
|
|||
Writing unit tests
|
||||
------------------
|
||||
|
||||
Django's unit tests use a Python standard library module: unittest_. This
|
||||
Django's unit tests use a Python standard library module: :mod:`unittest`. This
|
||||
module defines tests in class-based approach.
|
||||
|
||||
.. admonition:: unittest2
|
||||
|
|
@ -82,7 +82,7 @@ module defines tests in class-based approach.
|
|||
backported for Python 2.5 compatibility.
|
||||
|
||||
To access this library, Django provides the
|
||||
``django.utils.unittest`` module alias. If you are using Python
|
||||
:mod:`django.utils.unittest` module alias. If you are using Python
|
||||
2.7, or you have installed unittest2 locally, Django will map the
|
||||
alias to the installed version of the unittest library. Otherwise,
|
||||
Django will use it's own bundled version of unittest2.
|
||||
|
|
@ -104,13 +104,13 @@ For a given Django application, the test runner looks for unit tests in two
|
|||
places:
|
||||
|
||||
* The ``models.py`` file. The test runner looks for any subclass of
|
||||
``unittest.TestCase`` in this module.
|
||||
:class:`unittest.TestCase` in this module.
|
||||
|
||||
* A file called ``tests.py`` in the application directory -- i.e., the
|
||||
directory that holds ``models.py``. Again, the test runner looks for any
|
||||
subclass of ``unittest.TestCase`` in this module.
|
||||
subclass of :class:`unittest.TestCase` in this module.
|
||||
|
||||
Here is an example ``unittest.TestCase`` subclass::
|
||||
Here is an example :class:`unittest.TestCase` subclass::
|
||||
|
||||
from django.utils import unittest
|
||||
from myapp.models import Animal
|
||||
|
|
@ -124,10 +124,10 @@ Here is an example ``unittest.TestCase`` subclass::
|
|||
self.assertEqual(self.lion.speak(), 'The lion says "roar"')
|
||||
self.assertEqual(self.cat.speak(), 'The cat says "meow"')
|
||||
|
||||
When you :ref:`run your tests <running-tests>`, the default behavior of the
|
||||
test utility is to find all the test cases (that is, subclasses of
|
||||
``unittest.TestCase``) in ``models.py`` and ``tests.py``, automatically build a
|
||||
test suite out of those test cases, and run that suite.
|
||||
When you :ref:`run your tests <running-tests>`, the default behavior of the test
|
||||
utility is to find all the test cases (that is, subclasses of
|
||||
:class:`unittest.TestCase`) in ``models.py`` and ``tests.py``, automatically
|
||||
build a test suite out of those test cases, and run that suite.
|
||||
|
||||
There is a second way to define the test suite for a module: if you define a
|
||||
function called ``suite()`` in either ``models.py`` or ``tests.py``, the
|
||||
|
|
@ -136,20 +136,17 @@ module. This follows the `suggested organization`_ for unit tests. See the
|
|||
Python documentation for more details on how to construct a complex test
|
||||
suite.
|
||||
|
||||
For more details about ``unittest``, see the `standard library unittest
|
||||
documentation`_.
|
||||
For more details about :mod:`unittest`, see the Python documentation.
|
||||
|
||||
.. _unittest: http://docs.python.org/library/unittest.html
|
||||
.. _standard library unittest documentation: unittest_
|
||||
.. _suggested organization: http://docs.python.org/library/unittest.html#organizing-tests
|
||||
|
||||
Writing doctests
|
||||
----------------
|
||||
|
||||
Doctests use Python's standard doctest_ module, which searches your docstrings
|
||||
for statements that resemble a session of the Python interactive interpreter.
|
||||
A full explanation of how doctest works is out of the scope of this document;
|
||||
read Python's official documentation for the details.
|
||||
Doctests use Python's standard :mod:`doctest` module, which searches your
|
||||
docstrings for statements that resemble a session of the Python interactive
|
||||
interpreter. A full explanation of how :mod:`doctest` works is out of the scope
|
||||
of this document; read Python's official documentation for the details.
|
||||
|
||||
.. admonition:: What's a **docstring**?
|
||||
|
||||
|
|
@ -221,12 +218,7 @@ database or loading a fixture. (See the section on fixtures, below, for more
|
|||
on this.) Note that to use this feature, the database user Django is connecting
|
||||
as must have ``CREATE DATABASE`` rights.
|
||||
|
||||
For more details about how doctest works, see the `standard library
|
||||
documentation for doctest`_.
|
||||
|
||||
.. _doctest: http://docs.python.org/library/doctest.html
|
||||
.. _standard library documentation for doctest: doctest_
|
||||
|
||||
For more details about :mod:`doctest`, see the Python documentation.
|
||||
|
||||
Which should I use?
|
||||
-------------------
|
||||
|
|
@ -239,7 +231,7 @@ For developers new to testing, however, this choice can seem confusing. Here,
|
|||
then, are a few key differences to help you decide which approach is right for
|
||||
you:
|
||||
|
||||
* If you've been using Python for a while, ``doctest`` will probably feel
|
||||
* If you've been using Python for a while, :mod:`doctest` will probably feel
|
||||
more "pythonic". It's designed to make writing tests as easy as possible,
|
||||
so it requires no overhead of writing classes or methods. You simply put
|
||||
tests in docstrings. This has the added advantage of serving as
|
||||
|
|
@ -250,19 +242,19 @@ you:
|
|||
as it can be unclear exactly why the test failed. Thus, doctests should
|
||||
generally be avoided and used primarily for documentation examples only.
|
||||
|
||||
* The ``unittest`` framework will probably feel very familiar to developers
|
||||
coming from Java. ``unittest`` is inspired by Java's JUnit, so you'll
|
||||
feel at home with this method if you've used JUnit or any test framework
|
||||
inspired by JUnit.
|
||||
* The :mod:`unittest` framework will probably feel very familiar to
|
||||
developers coming from Java. :mod:`unittest` is inspired by Java's JUnit,
|
||||
so you'll feel at home with this method if you've used JUnit or any test
|
||||
framework inspired by JUnit.
|
||||
|
||||
* If you need to write a bunch of tests that share similar code, then
|
||||
you'll appreciate the ``unittest`` framework's organization around
|
||||
you'll appreciate the :mod:`unittest` framework's organization around
|
||||
classes and methods. This makes it easy to abstract common tasks into
|
||||
common methods. The framework also supports explicit setup and/or cleanup
|
||||
routines, which give you a high level of control over the environment
|
||||
in which your test cases are run.
|
||||
|
||||
* If you're writing tests for Django itself, you should use ``unittest``.
|
||||
* If you're writing tests for Django itself, you should use :mod:`unittest`.
|
||||
|
||||
.. _running-tests:
|
||||
|
||||
|
|
@ -553,7 +545,7 @@ failed::
|
|||
|
||||
A full explanation of this error output is beyond the scope of this document,
|
||||
but it's pretty intuitive. You can consult the documentation of Python's
|
||||
``unittest`` library for details.
|
||||
:mod:`unittest` library for details.
|
||||
|
||||
Note that the return code for the test-runner script is 1 for any number of
|
||||
failed and erroneous tests. If all the tests pass, the return code is 0. This
|
||||
|
|
@ -639,7 +631,8 @@ Note a few important things about how the test client works:
|
|||
|
||||
The test client is not capable of retrieving Web pages that are not
|
||||
powered by your Django project. If you need to retrieve other Web pages,
|
||||
use a Python standard library module such as urllib_ or urllib2_.
|
||||
use a Python standard library module such as :mod:`urllib` or
|
||||
:mod:`urllib2`.
|
||||
|
||||
* To resolve URLs, the test client uses whatever URLconf is pointed-to by
|
||||
your :setting:`ROOT_URLCONF` setting.
|
||||
|
|
@ -668,10 +661,6 @@ Note a few important things about how the test client works:
|
|||
>>> from django.test import Client
|
||||
>>> csrf_client = Client(enforce_csrf_checks=True)
|
||||
|
||||
|
||||
.. _urllib: http://docs.python.org/library/urllib.html
|
||||
.. _urllib2: http://docs.python.org/library/urllib2.html
|
||||
|
||||
Making requests
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
@ -759,15 +748,15 @@ arguments at time of construction:
|
|||
|
||||
name=fred&passwd=secret
|
||||
|
||||
If you provide ``content_type`` (e.g., ``text/xml`` for an XML
|
||||
If you provide ``content_type`` (e.g. :mimetype:`text/xml` for an XML
|
||||
payload), the contents of ``data`` will be sent as-is in the POST
|
||||
request, using ``content_type`` in the HTTP ``Content-Type`` header.
|
||||
|
||||
If you don't provide a value for ``content_type``, the values in
|
||||
``data`` will be transmitted with a content type of
|
||||
``multipart/form-data``. In this case, the key-value pairs in ``data``
|
||||
will be encoded as a multipart message and used to create the POST data
|
||||
payload.
|
||||
:mimetype:`multipart/form-data`. In this case, the key-value pairs in
|
||||
``data`` will be encoded as a multipart message and used to create the
|
||||
POST data payload.
|
||||
|
||||
To submit multiple values for a given key -- for example, to specify
|
||||
the selections for a ``<select multiple>`` -- provide the values as a
|
||||
|
|
@ -955,8 +944,8 @@ Specifically, a ``Response`` object has the following attributes:
|
|||
|
||||
.. attribute:: status_code
|
||||
|
||||
The HTTP status of the response, as an integer. See RFC2616_ for a full
|
||||
list of HTTP status codes.
|
||||
The HTTP status of the response, as an integer. See
|
||||
:rfc:`2616#section-10` for a full list of HTTP status codes.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
|
|
@ -972,14 +961,12 @@ You can also use dictionary syntax on the response object to query the value
|
|||
of any settings in the HTTP headers. For example, you could determine the
|
||||
content type of a response using ``response['Content-Type']``.
|
||||
|
||||
.. _RFC2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
|
||||
|
||||
Exceptions
|
||||
~~~~~~~~~~
|
||||
|
||||
If you point the test client at a view that raises an exception, that exception
|
||||
will be visible in the test case. You can then use a standard ``try ... except``
|
||||
block or ``unittest.TestCase.assertRaises()`` to test for exceptions.
|
||||
block or :meth:`~unittest.TestCase.assertRaises` to test for exceptions.
|
||||
|
||||
The only exceptions that are not visible to the test client are ``Http404``,
|
||||
``PermissionDenied`` and ``SystemExit``. Django catches these exceptions
|
||||
|
|
@ -1002,8 +989,9 @@ can access these properties as part of a test condition.
|
|||
|
||||
.. attribute:: Client.cookies
|
||||
|
||||
A Python ``SimpleCookie`` object, containing the current values of all the
|
||||
client cookies. See the `Cookie module documentation`_ for more.
|
||||
A Python :class:`~Cookie.SimpleCookie` object, containing the current values
|
||||
of all the client cookies. See the documentation of the :mod:`Cookie` module
|
||||
for more.
|
||||
|
||||
.. attribute:: Client.session
|
||||
|
||||
|
|
@ -1019,8 +1007,6 @@ can access these properties as part of a test condition.
|
|||
session['somekey'] = 'test'
|
||||
session.save()
|
||||
|
||||
.. _Cookie module documentation: http://docs.python.org/library/cookie.html
|
||||
|
||||
Example
|
||||
~~~~~~~
|
||||
|
||||
|
|
@ -1100,19 +1086,19 @@ TestCase
|
|||
|
||||
.. currentmodule:: django.test
|
||||
|
||||
Normal Python unit test classes extend a base class of ``unittest.TestCase``.
|
||||
Django provides a few extensions of this base class:
|
||||
Normal Python unit test classes extend a base class of
|
||||
:class:`unittest.TestCase`. Django provides a few extensions of this base class:
|
||||
|
||||
.. class:: TestCase()
|
||||
|
||||
This class provides some additional capabilities that can be useful for testing
|
||||
Web sites.
|
||||
|
||||
Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:
|
||||
just change the base class of your test from ``unittest.TestCase`` to
|
||||
``django.test.TestCase``. All of the standard Python unit test functionality
|
||||
will continue to be available, but it will be augmented with some useful
|
||||
additions, including:
|
||||
Converting a normal :class:`unittest.TestCase` to a Django :class:`TestCase` is
|
||||
easy: just change the base class of your test from :class:`unittest.TestCase` to
|
||||
:class:`django.test.TestCase`. All of the standard Python unit test
|
||||
functionality will continue to be available, but it will be augmented with some
|
||||
useful additions, including:
|
||||
|
||||
* Automatic loading of fixtures.
|
||||
|
||||
|
|
@ -1409,9 +1395,9 @@ Overriding settings
|
|||
|
||||
.. versionadded:: 1.4
|
||||
|
||||
For testing purposes it's often useful to change a setting temporarily
|
||||
and revert to the original value after running the testing code. For
|
||||
this use case Django provides a standard `Python context manager`_
|
||||
For testing purposes it's often useful to change a setting temporarily and
|
||||
revert to the original value after running the testing code. For this use case
|
||||
Django provides a standard Python context manager (see :pep:`343`)
|
||||
:meth:`~django.test.TestCase.settings`, which can be used like this::
|
||||
|
||||
from django.test import TestCase
|
||||
|
|
@ -1437,8 +1423,9 @@ in the ``with`` block and reset its value to the previous state afterwards.
|
|||
.. function:: override_settings
|
||||
|
||||
In case you want to override a setting for just one test method or even the
|
||||
whole TestCase class, Django provides the
|
||||
:func:`django.test.utils.override_settings` decorator_. It's used like this::
|
||||
whole :class:`TestCase` class, Django provides the
|
||||
:func:`~django.test.utils.override_settings` decorator (see :pep:`318`). It's
|
||||
used like this::
|
||||
|
||||
from django.test import TestCase
|
||||
from django.test.utils import override_settings
|
||||
|
|
@ -1484,9 +1471,6 @@ decorate the class::
|
|||
:data:`django.test.signals.setting_changed` signal to connect cleanup
|
||||
and other state-resetting callbacks to.
|
||||
|
||||
.. _`Python context manager`: http://www.python.org/dev/peps/pep-0343/
|
||||
.. _`decorator`: http://www.python.org/dev/peps/pep-0318/
|
||||
|
||||
Emptying the test outbox
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
|
@ -1505,8 +1489,9 @@ Assertions
|
|||
.. versionchanged:: 1.2
|
||||
Addded ``msg_prefix`` argument.
|
||||
|
||||
As Python's normal ``unittest.TestCase`` class implements assertion methods
|
||||
such as ``assertTrue`` and ``assertEqual``, Django's custom ``TestCase`` class
|
||||
As Python's normal :class:`unittest.TestCase` class implements assertion methods
|
||||
such as :meth:`~unittest.TestCase.assertTrue` and
|
||||
:meth:`~unittest.TestCase.assertEqual`, Django's custom :class:`TestCase` class
|
||||
provides a number of custom assertion methods that are useful for testing Web
|
||||
applications:
|
||||
|
||||
|
|
@ -1521,8 +1506,8 @@ your test suite.
|
|||
Asserts that execution of callable ``callable_obj`` raised the
|
||||
``expected_exception`` exception and that such exception has an
|
||||
``expected_message`` representation. Any other outcome is reported as a
|
||||
failure. Similar to unittest's ``assertRaisesRegexp`` with the difference
|
||||
that ``expected_message`` isn't a regular expression.
|
||||
failure. Similar to unittest's :meth:`~unittest.TestCase.assertRaisesRegexp`
|
||||
with the difference that ``expected_message`` isn't a regular expression.
|
||||
|
||||
.. method:: assertFieldOutput(self, fieldclass, valid, invalid, field_args=None, field_kwargs=None, empty_value=u'')
|
||||
|
||||
|
|
@ -1706,14 +1691,15 @@ Skipping tests
|
|||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
The unittest library provides the ``@skipIf`` and ``@skipUnless``
|
||||
decorators to allow you to skip tests if you know ahead of time that
|
||||
those tests are going to fail under certain conditions.
|
||||
The unittest library provides the :func:`@skipIf <unittest.skipIf>` and
|
||||
:func:`@skipUnless <unittest.skipUnless>` decorators to allow you to skip tests
|
||||
if you know ahead of time that those tests are going to fail under certain
|
||||
conditions.
|
||||
|
||||
For example, if your test requires a particular optional library in
|
||||
order to succeed, you could decorate the test case with ``@skipIf``.
|
||||
Then, the test runner will report that the test wasn't executed and
|
||||
why, instead of failing the test or omitting the test altogether.
|
||||
For example, if your test requires a particular optional library in order to
|
||||
succeed, you could decorate the test case with :func:`@skipIf
|
||||
<unittest.skipIf>`. Then, the test runner will report that the test wasn't
|
||||
executed and why, instead of failing the test or omitting the test altogether.
|
||||
|
||||
To supplement these test skipping behaviors, Django provides two
|
||||
additional skip decorators. Instead of testing a generic boolean,
|
||||
|
|
@ -1757,7 +1743,7 @@ under MySQL with MyISAM tables)::
|
|||
Using different testing frameworks
|
||||
==================================
|
||||
|
||||
Clearly, ``doctest`` and ``unittest`` are not the only Python testing
|
||||
Clearly, :mod:`doctest` and :mod:`unittest` are not the only Python testing
|
||||
frameworks. While Django doesn't provide explicit support for alternative
|
||||
frameworks, it does provide a way to invoke tests constructed for an
|
||||
alternative framework as if they were normal Django tests.
|
||||
|
|
|
|||
Loading…
Reference in New Issue