Used auto-numbered lists in documentation.
This commit is contained in:
François Freitag
Tim Graham
parent
cf915cb513
commit
9b15ff08ba
|
|
@ -699,12 +699,12 @@ complex conversions between your Python types and your database and
|
|||
serialization formats. Here are a couple of tips to make things go more
|
||||
smoothly:
|
||||
|
||||
1. Look at the existing Django fields (in
|
||||
#. Look at the existing Django fields (in
|
||||
:file:`django/db/models/fields/__init__.py`) for inspiration. Try to find
|
||||
a field that's similar to what you want and extend it a little bit,
|
||||
instead of creating an entirely new field from scratch.
|
||||
|
||||
2. Put a ``__str__()`` method on the class you're wrapping up as a field. There
|
||||
#. Put a ``__str__()`` method on the class you're wrapping up as a field. There
|
||||
are a lot of places where the default behavior of the field code is to call
|
||||
``str()`` on the value. (In our examples in this document, ``value`` would
|
||||
be a ``Hand`` instance, not a ``HandField``). So if your ``__str__()``
|
||||
|
|
@ -736,12 +736,12 @@ A few suggestions
|
|||
In addition to the above details, there are a few guidelines which can greatly
|
||||
improve the efficiency and readability of the field's code.
|
||||
|
||||
1. The source for Django's own ``ImageField`` (in
|
||||
#. The source for Django's own ``ImageField`` (in
|
||||
``django/db/models/fields/files.py``) is a great example of how to
|
||||
subclass ``FileField`` to support a particular type of file, as it
|
||||
incorporates all of the techniques described above.
|
||||
|
||||
2. Cache file attributes wherever possible. Since files may be stored in
|
||||
#. Cache file attributes wherever possible. Since files may be stored in
|
||||
remote storage systems, retrieving them may cost extra time, or even
|
||||
money, that isn't always necessary. Once a file is retrieved to obtain
|
||||
some data about its content, cache as much of that data as possible to
|
||||
|
|
|
|||
|
|
@ -842,13 +842,13 @@ A naive implementation of ``CycleNode`` might look something like this::
|
|||
But, suppose we have two templates rendering the template snippet from above at
|
||||
the same time:
|
||||
|
||||
1. Thread 1 performs its first loop iteration, ``CycleNode.render()``
|
||||
#. Thread 1 performs its first loop iteration, ``CycleNode.render()``
|
||||
returns 'row1'
|
||||
2. Thread 2 performs its first loop iteration, ``CycleNode.render()``
|
||||
#. Thread 2 performs its first loop iteration, ``CycleNode.render()``
|
||||
returns 'row2'
|
||||
3. Thread 1 performs its second loop iteration, ``CycleNode.render()``
|
||||
#. Thread 1 performs its second loop iteration, ``CycleNode.render()``
|
||||
returns 'row1'
|
||||
4. Thread 2 performs its second loop iteration, ``CycleNode.render()``
|
||||
#. Thread 2 performs its second loop iteration, ``CycleNode.render()``
|
||||
returns 'row2'
|
||||
|
||||
The CycleNode is iterating, but it's iterating globally. As far as Thread 1
|
||||
|
|
|
|||
|
|
@ -11,14 +11,14 @@ This page describes how you can serve these static files.
|
|||
Configuring static files
|
||||
========================
|
||||
|
||||
1. Make sure that ``django.contrib.staticfiles`` is included in your
|
||||
#. Make sure that ``django.contrib.staticfiles`` is included in your
|
||||
:setting:`INSTALLED_APPS`.
|
||||
|
||||
2. In your settings file, define :setting:`STATIC_URL`, for example::
|
||||
#. In your settings file, define :setting:`STATIC_URL`, for example::
|
||||
|
||||
STATIC_URL = '/static/'
|
||||
|
||||
3. In your templates, use the :ttag:`static` template tag to build the URL for
|
||||
#. In your templates, use the :ttag:`static` template tag to build the URL for
|
||||
the given relative path using the configured :setting:`STATICFILES_STORAGE`.
|
||||
|
||||
.. _staticfiles-in-templates:
|
||||
|
|
@ -28,7 +28,7 @@ Configuring static files
|
|||
{% load static %}
|
||||
<img src="{% static "my_app/example.jpg" %}" alt="My image">
|
||||
|
||||
4. Store your static files in a folder called ``static`` in your app. For
|
||||
#. Store your static files in a folder called ``static`` in your app. For
|
||||
example ``my_app/static/my_app/example.jpg``.
|
||||
|
||||
.. admonition:: Serving the files
|
||||
|
|
@ -159,19 +159,19 @@ Deployment
|
|||
:mod:`django.contrib.staticfiles` provides a convenience management command
|
||||
for gathering static files in a single directory so you can serve them easily.
|
||||
|
||||
1. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd
|
||||
#. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd
|
||||
like to serve these files, for example::
|
||||
|
||||
STATIC_ROOT = "/var/www/example.com/static/"
|
||||
|
||||
2. Run the :djadmin:`collectstatic` management command::
|
||||
#. Run the :djadmin:`collectstatic` management command::
|
||||
|
||||
$ python manage.py collectstatic
|
||||
|
||||
This will copy all files from your static folders into the
|
||||
:setting:`STATIC_ROOT` directory.
|
||||
|
||||
3. Use a web server of your choice to serve the
|
||||
#. Use a web server of your choice to serve the
|
||||
files. :doc:`/howto/static-files/deployment` covers some common deployment
|
||||
strategies for static files.
|
||||
|
||||
|
|
|
|||
|
|
@ -168,12 +168,12 @@ A new board is elected after each feature release of Django. The election
|
|||
process is managed by a returns officer nominated by the outgoing technical
|
||||
board. The election process works as follows:
|
||||
|
||||
1. Candidates advertise their application for the technical board to the team.
|
||||
#. Candidates advertise their application for the technical board to the team.
|
||||
|
||||
They must be committers already. There's no term limit for technical board
|
||||
members.
|
||||
|
||||
2. Each team member can vote for zero to five people among the candidates.
|
||||
#. Each team member can vote for zero to five people among the candidates.
|
||||
Candidates are ranked by the total number of votes they received.
|
||||
|
||||
In case of a tie, the person who joined the core team earlier wins.
|
||||
|
|
|
|||
|
|
@ -119,18 +119,18 @@ from `Django's release team`_ and consists of:
|
|||
|
||||
On the day of disclosure, we will take the following steps:
|
||||
|
||||
1. Apply the relevant patch(es) to Django's codebase.
|
||||
#. Apply the relevant patch(es) to Django's codebase.
|
||||
|
||||
2. Issue the relevant release(s), by placing new packages on `the
|
||||
#. Issue the relevant release(s), by placing new packages on `the
|
||||
Python Package Index`_ and on the Django website, and tagging the
|
||||
new release(s) in Django's git repository.
|
||||
|
||||
3. Post a public entry on `the official Django development blog`_,
|
||||
#. Post a public entry on `the official Django development blog`_,
|
||||
describing the issue and its resolution in detail, pointing to the
|
||||
relevant patches and new releases, and crediting the reporter of
|
||||
the issue (if the reporter wishes to be publicly identified).
|
||||
|
||||
4. Post a notice to the |django-announce| and oss-security@lists.openwall.com
|
||||
#. Post a notice to the |django-announce| and oss-security@lists.openwall.com
|
||||
mailing lists that links to the blog post.
|
||||
|
||||
.. _the Python Package Index: https://pypi.org/
|
||||
|
|
|
|||
|
|
@ -120,7 +120,7 @@ Python *packaging* refers to preparing your app in a specific format that can
|
|||
be easily installed and used. Django itself is packaged very much like
|
||||
this. For a small app like polls, this process isn't too difficult.
|
||||
|
||||
1. First, create a parent directory for ``polls``, outside of your Django
|
||||
#. First, create a parent directory for ``polls``, outside of your Django
|
||||
project. Call this directory ``django-polls``.
|
||||
|
||||
.. admonition:: Choosing a name for your app
|
||||
|
|
@ -137,9 +137,9 @@ this. For a small app like polls, this process isn't too difficult.
|
|||
</ref/contrib/index>`, for example ``auth``, ``admin``, or
|
||||
``messages``.
|
||||
|
||||
2. Move the ``polls`` directory into the ``django-polls`` directory.
|
||||
#. Move the ``polls`` directory into the ``django-polls`` directory.
|
||||
|
||||
3. Create a file ``django-polls/README.rst`` with the following contents:
|
||||
#. Create a file ``django-polls/README.rst`` with the following contents:
|
||||
|
||||
.. code-block:: rst
|
||||
:caption: django-polls/README.rst
|
||||
|
|
@ -174,14 +174,14 @@ this. For a small app like polls, this process isn't too difficult.
|
|||
|
||||
5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.
|
||||
|
||||
4. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the
|
||||
#. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the
|
||||
scope of this tutorial, but suffice it to say that code released publicly
|
||||
without a license is *useless*. Django and many Django-compatible apps are
|
||||
distributed under the BSD license; however, you're free to pick your own
|
||||
license. Just be aware that your licensing choice will affect who is able
|
||||
to use your code.
|
||||
|
||||
5. Next we'll create a ``setup.py`` file which provides details about how to
|
||||
#. Next we'll create a ``setup.py`` file which provides details about how to
|
||||
build and install the app. A full explanation of this file is beyond the
|
||||
scope of this tutorial, but the `setuptools docs
|
||||
<https://setuptools.readthedocs.io/en/latest/>`_ have a good
|
||||
|
|
@ -226,7 +226,7 @@ this. For a small app like polls, this process isn't too difficult.
|
|||
],
|
||||
)
|
||||
|
||||
6. Only Python modules and packages are included in the package by default. To
|
||||
#. Only Python modules and packages are included in the package by default. To
|
||||
include additional files, we'll need to create a ``MANIFEST.in`` file. The
|
||||
setuptools docs referred to in the previous step discuss this file in more
|
||||
details. To include the templates, the ``README.rst`` and our ``LICENSE``
|
||||
|
|
@ -241,7 +241,7 @@ this. For a small app like polls, this process isn't too difficult.
|
|||
recursive-include polls/static *
|
||||
recursive-include polls/templates *
|
||||
|
||||
7. It's optional, but recommended, to include detailed documentation with your
|
||||
#. It's optional, but recommended, to include detailed documentation with your
|
||||
app. Create an empty directory ``django-polls/docs`` for future
|
||||
documentation. Add an additional line to ``django-polls/MANIFEST.in``::
|
||||
|
||||
|
|
@ -251,7 +251,7 @@ this. For a small app like polls, this process isn't too difficult.
|
|||
you add some files to it. Many Django apps also provide their documentation
|
||||
online through sites like `readthedocs.org <https://readthedocs.org>`_.
|
||||
|
||||
8. Try building your package with ``python setup.py sdist`` (run from inside
|
||||
#. Try building your package with ``python setup.py sdist`` (run from inside
|
||||
``django-polls``). This creates a directory called ``dist`` and builds your
|
||||
new package, ``django-polls-0.1.tar.gz``.
|
||||
|
||||
|
|
@ -276,15 +276,15 @@ working. We'll now fix this by installing our new ``django-polls`` package.
|
|||
tools that run as that user, so ``virtualenv`` is a more robust solution
|
||||
(see below).
|
||||
|
||||
1. To install the package, use pip (you already :ref:`installed it
|
||||
#. To install the package, use pip (you already :ref:`installed it
|
||||
<installing-reusable-apps-prerequisites>`, right?)::
|
||||
|
||||
pip install --user django-polls/dist/django-polls-0.1.tar.gz
|
||||
|
||||
2. With luck, your Django project should now work correctly again. Run the
|
||||
#. With luck, your Django project should now work correctly again. Run the
|
||||
server again to confirm this.
|
||||
|
||||
3. To uninstall the package, use pip::
|
||||
#. To uninstall the package, use pip::
|
||||
|
||||
pip uninstall django-polls
|
||||
|
||||
|
|
|
|||
|
|
@ -211,11 +211,11 @@ Let's convert our poll app to use the generic views system, so we can delete a
|
|||
bunch of our own code. We'll just have to take a few steps to make the
|
||||
conversion. We will:
|
||||
|
||||
1. Convert the URLconf.
|
||||
#. Convert the URLconf.
|
||||
|
||||
2. Delete some of the old, unneeded views.
|
||||
#. Delete some of the old, unneeded views.
|
||||
|
||||
3. Introduce new views based on Django's generic views.
|
||||
#. Introduce new views based on Django's generic views.
|
||||
|
||||
Read on for details.
|
||||
|
||||
|
|
|
|||
|
|
@ -303,10 +303,10 @@ Django applications require a single base filesystem path where Django
|
|||
etc. Thus, namespace packages may only be Django applications if one of the
|
||||
following is true:
|
||||
|
||||
1. The namespace package actually has only a single location (i.e. is not
|
||||
#. The namespace package actually has only a single location (i.e. is not
|
||||
spread across more than one directory.)
|
||||
|
||||
2. The :class:`~django.apps.AppConfig` class used to configure the application
|
||||
#. The :class:`~django.apps.AppConfig` class used to configure the application
|
||||
has a :attr:`~django.apps.AppConfig.path` class attribute, which is the
|
||||
absolute directory path Django will use as the single base path for the
|
||||
application.
|
||||
|
|
|
|||
|
|
@ -24,9 +24,9 @@ MRO is an acronym for Method Resolution Order.
|
|||
|
||||
**Method Flowchart**
|
||||
|
||||
1. :meth:`dispatch()`
|
||||
2. :meth:`http_method_not_allowed()`
|
||||
3. :meth:`options()`
|
||||
#. :meth:`dispatch()`
|
||||
#. :meth:`http_method_not_allowed()`
|
||||
#. :meth:`options()`
|
||||
|
||||
**Example views.py**::
|
||||
|
||||
|
|
@ -123,9 +123,9 @@ MRO is an acronym for Method Resolution Order.
|
|||
|
||||
**Method Flowchart**
|
||||
|
||||
1. :meth:`~django.views.generic.base.View.dispatch()`
|
||||
2. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
||||
3. :meth:`~django.views.generic.base.ContextMixin.get_context_data()`
|
||||
#. :meth:`~django.views.generic.base.View.dispatch()`
|
||||
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
||||
#. :meth:`~django.views.generic.base.ContextMixin.get_context_data()`
|
||||
|
||||
**Example views.py**::
|
||||
|
||||
|
|
@ -184,9 +184,9 @@ MRO is an acronym for Method Resolution Order.
|
|||
|
||||
**Method Flowchart**
|
||||
|
||||
1. :meth:`~django.views.generic.base.View.dispatch()`
|
||||
2. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
||||
3. :meth:`get_redirect_url()`
|
||||
#. :meth:`~django.views.generic.base.View.dispatch()`
|
||||
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
||||
#. :meth:`get_redirect_url()`
|
||||
|
||||
**Example views.py**::
|
||||
|
||||
|
|
|
|||
|
|
@ -25,16 +25,16 @@ many projects they are typically the most commonly used views.
|
|||
|
||||
**Method Flowchart**
|
||||
|
||||
1. :meth:`~django.views.generic.base.View.dispatch()`
|
||||
2. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
||||
3. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()`
|
||||
4. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field()`
|
||||
5. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset()`
|
||||
6. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()`
|
||||
7. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name()`
|
||||
8. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data()`
|
||||
9. ``get()``
|
||||
10. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()`
|
||||
#. :meth:`~django.views.generic.base.View.dispatch()`
|
||||
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
||||
#. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()`
|
||||
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field()`
|
||||
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset()`
|
||||
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()`
|
||||
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name()`
|
||||
#. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data()`
|
||||
#. ``get()``
|
||||
#. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()`
|
||||
|
||||
**Example myapp/views.py**::
|
||||
|
||||
|
|
@ -95,15 +95,14 @@ many projects they are typically the most commonly used views.
|
|||
|
||||
**Method Flowchart**
|
||||
|
||||
1. :meth:`~django.views.generic.base.View.dispatch()`
|
||||
2. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
||||
3. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()`
|
||||
4. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset()`
|
||||
5. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name()`
|
||||
6. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data()`
|
||||
7. ``get()``
|
||||
8. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()`
|
||||
|
||||
#. :meth:`~django.views.generic.base.View.dispatch()`
|
||||
#. :meth:`~django.views.generic.base.View.http_method_not_allowed()`
|
||||
#. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()`
|
||||
#. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset()`
|
||||
#. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name()`
|
||||
#. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data()`
|
||||
#. ``get()``
|
||||
#. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()`
|
||||
|
||||
**Example views.py**::
|
||||
|
||||
|
|
|
|||
|
|
@ -40,9 +40,9 @@ loading in a frame no matter which site made the request.
|
|||
Django provides a few simple ways to include this header in responses from your
|
||||
site:
|
||||
|
||||
1. A simple middleware that sets the header in all responses.
|
||||
#. A simple middleware that sets the header in all responses.
|
||||
|
||||
2. A set of view decorators that can be used to override the middleware or to
|
||||
#. A set of view decorators that can be used to override the middleware or to
|
||||
only set the header for certain views.
|
||||
|
||||
The ``X-Frame-Options`` HTTP header will only be set by the middleware or view
|
||||
|
|
|
|||
|
|
@ -8,9 +8,9 @@ Overview
|
|||
========
|
||||
In general, GeoDjango installation requires:
|
||||
|
||||
1. :ref:`Python and Django <django>`
|
||||
2. :ref:`spatial_database`
|
||||
3. :doc:`geolibs`
|
||||
#. :ref:`Python and Django <django>`
|
||||
#. :ref:`spatial_database`
|
||||
#. :doc:`geolibs`
|
||||
|
||||
Details for each of the requirements and installation instructions
|
||||
are provided in the sections below. In addition, platform-specific
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ then inserting into a GeoDjango model.
|
|||
Example
|
||||
=======
|
||||
|
||||
1. You need a GDAL-supported data source, like a shapefile (here we're using
|
||||
#. You need a GDAL-supported data source, like a shapefile (here we're using
|
||||
a simple polygon shapefile, ``test_poly.shp``, with three features)::
|
||||
|
||||
>>> from django.contrib.gis.gdal import DataSource
|
||||
|
|
@ -50,7 +50,7 @@ Example
|
|||
PRIMEM["Greenwich",0],
|
||||
UNIT["Degree",0.017453292519943295]]
|
||||
|
||||
2. Now we define our corresponding Django model (make sure to use :djadmin:`migrate`)::
|
||||
#. Now we define our corresponding Django model (make sure to use :djadmin:`migrate`)::
|
||||
|
||||
from django.contrib.gis.db import models
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ Example
|
|||
def __str__(self):
|
||||
return 'Name: %s' % self.name
|
||||
|
||||
3. Use :class:`LayerMapping` to extract all the features and place them in the
|
||||
#. Use :class:`LayerMapping` to extract all the features and place them in the
|
||||
database::
|
||||
|
||||
>>> from django.contrib.gis.utils import LayerMapping
|
||||
|
|
|
|||
|
|
@ -292,8 +292,8 @@ transform do not change. For example::
|
|||
|
||||
To use this field, you'll need to:
|
||||
|
||||
1. Add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`.
|
||||
2. :ref:`Setup the hstore extension <create-postgresql-extensions>` in
|
||||
#. Add ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`.
|
||||
#. :ref:`Setup the hstore extension <create-postgresql-extensions>` in
|
||||
PostgreSQL.
|
||||
|
||||
You'll see an error like ``can't adapt type 'dict'`` if you skip the first
|
||||
|
|
|
|||
|
|
@ -14,12 +14,12 @@ Installation
|
|||
|
||||
To install the redirects app, follow these steps:
|
||||
|
||||
1. Ensure that the ``django.contrib.sites`` framework
|
||||
#. Ensure that the ``django.contrib.sites`` framework
|
||||
:ref:`is installed <enabling-the-sites-framework>`.
|
||||
2. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting.
|
||||
3. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
|
||||
#. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting.
|
||||
#. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
|
||||
to your :setting:`MIDDLEWARE` setting.
|
||||
4. Run the command :djadmin:`manage.py migrate <migrate>`.
|
||||
#. Run the command :djadmin:`manage.py migrate <migrate>`.
|
||||
|
||||
How it works
|
||||
============
|
||||
|
|
|
|||
|
|
@ -31,15 +31,13 @@ Installation
|
|||
|
||||
To install the sitemap app, follow these steps:
|
||||
|
||||
1. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS`
|
||||
setting.
|
||||
#. Add ``'django.contrib.sitemaps'`` to your :setting:`INSTALLED_APPS` setting.
|
||||
|
||||
2. Make sure your :setting:`TEMPLATES` setting contains a ``DjangoTemplates``
|
||||
#. Make sure your :setting:`TEMPLATES` setting contains a ``DjangoTemplates``
|
||||
backend whose ``APP_DIRS`` options is set to ``True``. It's in there by
|
||||
default, so you'll only need to change this if you've changed that setting.
|
||||
|
||||
3. Make sure you've installed the
|
||||
:mod:`sites framework <django.contrib.sites>`.
|
||||
#. Make sure you've installed the :mod:`sites framework<django.contrib.sites>`.
|
||||
|
||||
(Note: The sitemap application doesn't install any database tables. The only
|
||||
reason it needs to go into :setting:`INSTALLED_APPS` is so that the
|
||||
|
|
|
|||
|
|
@ -261,14 +261,13 @@ Enabling the sites framework
|
|||
|
||||
To enable the sites framework, follow these steps:
|
||||
|
||||
1. Add ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS`
|
||||
setting.
|
||||
#. Add ``'django.contrib.sites'`` to your :setting:`INSTALLED_APPS` setting.
|
||||
|
||||
2. Define a :setting:`SITE_ID` setting::
|
||||
#. Define a :setting:`SITE_ID` setting::
|
||||
|
||||
SITE_ID = 1
|
||||
|
||||
3. Run :djadmin:`migrate`.
|
||||
#. Run :djadmin:`migrate`.
|
||||
|
||||
``django.contrib.sites`` registers a
|
||||
:data:`~django.db.models.signals.post_migrate` signal handler which creates a
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ How to use it
|
|||
|
||||
To take advantage of CSRF protection in your views, follow these steps:
|
||||
|
||||
1. The CSRF middleware is activated by default in the :setting:`MIDDLEWARE`
|
||||
#. The CSRF middleware is activated by default in the :setting:`MIDDLEWARE`
|
||||
setting. If you override that setting, remember that
|
||||
``'django.middleware.csrf.CsrfViewMiddleware'`` should come before any view
|
||||
middleware that assume that CSRF attacks have been dealt with.
|
||||
|
|
@ -36,7 +36,7 @@ To take advantage of CSRF protection in your views, follow these steps:
|
|||
:func:`~django.views.decorators.csrf.csrf_protect` on particular views
|
||||
you want to protect (see below).
|
||||
|
||||
2. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside
|
||||
#. In any template that uses a POST form, use the :ttag:`csrf_token` tag inside
|
||||
the ``<form>`` element if the form is for an internal URL, e.g.:
|
||||
|
||||
.. code-block:: html+django
|
||||
|
|
@ -46,7 +46,7 @@ To take advantage of CSRF protection in your views, follow these steps:
|
|||
This should not be done for POST forms that target external URLs, since
|
||||
that would cause the CSRF token to be leaked, leading to a vulnerability.
|
||||
|
||||
3. In the corresponding view functions, ensure that
|
||||
#. In the corresponding view functions, ensure that
|
||||
:class:`~django.template.RequestContext` is used to render the response so
|
||||
that ``{% csrf_token %}`` will work properly. If you're using the
|
||||
:func:`~django.shortcuts.render` function, generic views, or contrib apps,
|
||||
|
|
@ -241,7 +241,7 @@ How it works
|
|||
|
||||
The CSRF protection is based on the following things:
|
||||
|
||||
1. A CSRF cookie that is based on a random secret value, which other sites
|
||||
#. A CSRF cookie that is based on a random secret value, which other sites
|
||||
will not have access to.
|
||||
|
||||
This cookie is set by ``CsrfViewMiddleware``. It is sent with every
|
||||
|
|
@ -255,7 +255,7 @@ The CSRF protection is based on the following things:
|
|||
For security reasons, the value of the secret is changed each time a
|
||||
user logs in.
|
||||
|
||||
2. A hidden form field with the name 'csrfmiddlewaretoken' present in all
|
||||
#. A hidden form field with the name 'csrfmiddlewaretoken' present in all
|
||||
outgoing POST forms. The value of this field is, again, the value of the
|
||||
secret, with a salt which is both added to it and used to scramble it. The
|
||||
salt is regenerated on every call to ``get_token()`` so that the form field
|
||||
|
|
@ -263,7 +263,7 @@ The CSRF protection is based on the following things:
|
|||
|
||||
This part is done by the template tag.
|
||||
|
||||
3. For all incoming requests that are not using HTTP GET, HEAD, OPTIONS or
|
||||
#. For all incoming requests that are not using HTTP GET, HEAD, OPTIONS or
|
||||
TRACE, a CSRF cookie must be present, and the 'csrfmiddlewaretoken' field
|
||||
must be present and correct. If it isn't, the user will get a 403 error.
|
||||
|
||||
|
|
@ -274,7 +274,7 @@ The CSRF protection is based on the following things:
|
|||
|
||||
This check is done by ``CsrfViewMiddleware``.
|
||||
|
||||
4. In addition, for HTTPS requests, strict referer checking is done by
|
||||
#. In addition, for HTTPS requests, strict referer checking is done by
|
||||
``CsrfViewMiddleware``. This means that even if a subdomain can set or
|
||||
modify cookies on your domain, it can't force a user to post to your
|
||||
application since that request won't come from your own exact domain.
|
||||
|
|
|
|||
|
|
@ -415,10 +415,10 @@ Refer to the :doc:`settings documentation </ref/settings>`.
|
|||
|
||||
Connection settings are used in this order:
|
||||
|
||||
1. :setting:`OPTIONS`.
|
||||
2. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`,
|
||||
:setting:`HOST`, :setting:`PORT`
|
||||
3. MySQL option files.
|
||||
#. :setting:`OPTIONS`.
|
||||
#. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`, :setting:`HOST`,
|
||||
:setting:`PORT`
|
||||
#. MySQL option files.
|
||||
|
||||
In other words, if you set the name of the database in :setting:`OPTIONS`,
|
||||
this will take precedence over :setting:`NAME`, which would override
|
||||
|
|
|
|||
|
|
@ -1400,10 +1400,10 @@ For example, this command::
|
|||
|
||||
...would perform the following steps:
|
||||
|
||||
1. Create a test database, as described in :ref:`the-test-database`.
|
||||
2. Populate the test database with fixture data from the given fixtures.
|
||||
#. Create a test database, as described in :ref:`the-test-database`.
|
||||
#. Populate the test database with fixture data from the given fixtures.
|
||||
(For more on fixtures, see the documentation for :djadmin:`loaddata` above.)
|
||||
3. Runs the Django development server (as in :djadmin:`runserver`), pointed at
|
||||
#. Runs the Django development server (as in :djadmin:`runserver`), pointed at
|
||||
this newly created test database instead of your production database.
|
||||
|
||||
This is useful in a number of ways:
|
||||
|
|
|
|||
|
|
@ -697,17 +697,17 @@ The default form widget for this field is a
|
|||
Using a :class:`FileField` or an :class:`ImageField` (see below) in a model
|
||||
takes a few steps:
|
||||
|
||||
1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the
|
||||
#. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the
|
||||
full path to a directory where you'd like Django to store uploaded files.
|
||||
(For performance, these files are not stored in the database.) Define
|
||||
:setting:`MEDIA_URL` as the base public URL of that directory. Make sure
|
||||
that this directory is writable by the Web server's user account.
|
||||
|
||||
2. Add the :class:`FileField` or :class:`ImageField` to your model, defining
|
||||
#. Add the :class:`FileField` or :class:`ImageField` to your model, defining
|
||||
the :attr:`~FileField.upload_to` option to specify a subdirectory of
|
||||
:setting:`MEDIA_ROOT` to use for uploaded files.
|
||||
|
||||
3. All that will be stored in your database is a path to the file
|
||||
#. All that will be stored in your database is a path to the file
|
||||
(relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the
|
||||
convenience :attr:`~django.db.models.fields.files.FieldFile.url` attribute
|
||||
provided by Django. For example, if your :class:`ImageField` is called
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ that, you need to :meth:`~Model.save()`.
|
|||
signature as any change may prevent the model instance from being saved.
|
||||
Rather than overriding ``__init__``, try using one of these approaches:
|
||||
|
||||
1. Add a classmethod on the model class::
|
||||
#. Add a classmethod on the model class::
|
||||
|
||||
from django.db import models
|
||||
|
||||
|
|
@ -47,7 +47,7 @@ that, you need to :meth:`~Model.save()`.
|
|||
|
||||
book = Book.create("Pride and Prejudice")
|
||||
|
||||
2. Add a method on a custom manager (usually preferred)::
|
||||
#. Add a method on a custom manager (usually preferred)::
|
||||
|
||||
class BookManager(models.Manager):
|
||||
def create_book(self, title):
|
||||
|
|
@ -135,9 +135,9 @@ If you need to reload a model's values from the database, you can use the
|
|||
``refresh_from_db()`` method. When this method is called without arguments the
|
||||
following is done:
|
||||
|
||||
1. All non-deferred fields of the model are updated to the values currently
|
||||
#. All non-deferred fields of the model are updated to the values currently
|
||||
present in the database.
|
||||
2. Any cached relations are cleared from the reloaded instance.
|
||||
#. Any cached relations are cleared from the reloaded instance.
|
||||
|
||||
Only fields of the model are reloaded from the database. Other
|
||||
database-dependent values such as annotations aren't reloaded. Any
|
||||
|
|
|
|||
|
|
@ -163,12 +163,12 @@ Django quotes column and table names behind the scenes.
|
|||
the *only* difference when ``managed=False``. All other aspects of
|
||||
model handling are exactly the same as normal. This includes
|
||||
|
||||
1. Adding an automatic primary key field to the model if you don't
|
||||
#. Adding an automatic primary key field to the model if you don't
|
||||
declare it. To avoid confusion for later code readers, it's
|
||||
recommended to specify all the columns from the database table you
|
||||
are modeling when using unmanaged models.
|
||||
|
||||
2. If a model with ``managed=False`` contains a
|
||||
#. If a model with ``managed=False`` contains a
|
||||
:class:`~django.db.models.ManyToManyField` that points to another
|
||||
unmanaged model, then the intermediate table for the many-to-many
|
||||
join will also not be created. However, the intermediary table
|
||||
|
|
|
|||
|
|
@ -62,9 +62,9 @@ startproject <startproject>`, these consist of two items listed in your
|
|||
|
||||
and these items in your :setting:`MIDDLEWARE` setting:
|
||||
|
||||
1. :class:`~django.contrib.sessions.middleware.SessionMiddleware` manages
|
||||
#. :class:`~django.contrib.sessions.middleware.SessionMiddleware` manages
|
||||
:doc:`sessions </topics/http/sessions>` across requests.
|
||||
2. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` associates
|
||||
#. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` associates
|
||||
users with requests using sessions.
|
||||
|
||||
With these settings in place, running the command ``manage.py migrate`` creates
|
||||
|
|
|
|||
|
|
@ -86,11 +86,11 @@ use of Argon2 rather than the other algorithms supported by Django.
|
|||
|
||||
To use Argon2 as your default storage algorithm, do the following:
|
||||
|
||||
1. Install the `argon2-cffi library`_. This can be done by running ``pip
|
||||
#. Install the `argon2-cffi library`_. This can be done by running ``pip
|
||||
install django[argon2]``, which is equivalent to ``pip install argon2-cffi``
|
||||
(along with any version requirement from Django's ``setup.py``).
|
||||
|
||||
2. Modify :setting:`PASSWORD_HASHERS` to list ``Argon2PasswordHasher`` first.
|
||||
#. Modify :setting:`PASSWORD_HASHERS` to list ``Argon2PasswordHasher`` first.
|
||||
That is, in your settings file, you'd put::
|
||||
|
||||
PASSWORD_HASHERS = [
|
||||
|
|
@ -115,11 +115,11 @@ use it Django supports bcrypt with minimal effort.
|
|||
|
||||
To use Bcrypt as your default storage algorithm, do the following:
|
||||
|
||||
1. Install the `bcrypt library`_. This can be done by running ``pip install
|
||||
#. Install the `bcrypt library`_. This can be done by running ``pip install
|
||||
django[bcrypt]``, which is equivalent to ``pip install bcrypt`` (along with
|
||||
any version requirement from Django's ``setup.py``).
|
||||
|
||||
2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptSHA256PasswordHasher``
|
||||
#. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptSHA256PasswordHasher``
|
||||
first. That is, in your settings file, you'd put::
|
||||
|
||||
PASSWORD_HASHERS = [
|
||||
|
|
@ -153,7 +153,7 @@ you'll subclass the appropriate algorithm and override the ``iterations``
|
|||
parameters. For example, to increase the number of iterations used by the
|
||||
default PBKDF2 algorithm:
|
||||
|
||||
1. Create a subclass of ``django.contrib.auth.hashers.PBKDF2PasswordHasher``::
|
||||
#. Create a subclass of ``django.contrib.auth.hashers.PBKDF2PasswordHasher``::
|
||||
|
||||
from django.contrib.auth.hashers import PBKDF2PasswordHasher
|
||||
|
||||
|
|
@ -166,7 +166,7 @@ default PBKDF2 algorithm:
|
|||
Save this somewhere in your project. For example, you might put this in
|
||||
a file like ``myproject/hashers.py``.
|
||||
|
||||
2. Add your new hasher as the first entry in :setting:`PASSWORD_HASHERS`::
|
||||
#. Add your new hasher as the first entry in :setting:`PASSWORD_HASHERS`::
|
||||
|
||||
PASSWORD_HASHERS = [
|
||||
'myproject.hashers.MyPBKDF2PasswordHasher',
|
||||
|
|
|
|||
|
|
@ -176,16 +176,16 @@ trying to change has been altered in the meantime.
|
|||
|
||||
For example, consider the following exchange between the client and server:
|
||||
|
||||
1. Client requests ``/foo/``.
|
||||
2. Server responds with some content with an ETag of ``"abcd1234"``.
|
||||
3. Client sends an HTTP ``PUT`` request to ``/foo/`` to update the
|
||||
#. Client requests ``/foo/``.
|
||||
#. Server responds with some content with an ETag of ``"abcd1234"``.
|
||||
#. Client sends an HTTP ``PUT`` request to ``/foo/`` to update the
|
||||
resource. It also sends an ``If-Match: "abcd1234"`` header to specify
|
||||
the version it is trying to update.
|
||||
4. Server checks to see if the resource has changed, by computing the ETag
|
||||
#. Server checks to see if the resource has changed, by computing the ETag
|
||||
the same way it does for a ``GET`` request (using the same function).
|
||||
If the resource *has* changed, it will return a 412 status code,
|
||||
meaning "precondition failed".
|
||||
5. Client sends a ``GET`` request to ``/foo/``, after receiving a 412
|
||||
#. Client sends a ``GET`` request to ``/foo/``, after receiving a 412
|
||||
response, to retrieve an updated version of the content before updating
|
||||
it.
|
||||
|
||||
|
|
|
|||
|
|
@ -651,19 +651,19 @@ Field name restrictions
|
|||
|
||||
Django places some restrictions on model field names:
|
||||
|
||||
1. A field name cannot be a Python reserved word, because that would result
|
||||
#. A field name cannot be a Python reserved word, because that would result
|
||||
in a Python syntax error. For example::
|
||||
|
||||
class Example(models.Model):
|
||||
pass = models.IntegerField() # 'pass' is a reserved word!
|
||||
|
||||
2. A field name cannot contain more than one underscore in a row, due to
|
||||
#. A field name cannot contain more than one underscore in a row, due to
|
||||
the way Django's query lookup syntax works. For example::
|
||||
|
||||
class Example(models.Model):
|
||||
foo__bar = models.IntegerField() # 'foo__bar' has two underscores!
|
||||
|
||||
3. A field name cannot end with an underscore, for similar reasons.
|
||||
#. A field name cannot end with an underscore, for similar reasons.
|
||||
|
||||
These limitations can be worked around, though, because your field name doesn't
|
||||
necessarily have to match your database column name. See the
|
||||
|
|
@ -1307,11 +1307,11 @@ directly inherit its fields and managers.
|
|||
|
||||
The general rules are:
|
||||
|
||||
1. If you are mirroring an existing model or database table and don't want
|
||||
#. If you are mirroring an existing model or database table and don't want
|
||||
all the original database table columns, use ``Meta.managed=False``.
|
||||
That option is normally useful for modeling database views and tables
|
||||
not under the control of Django.
|
||||
2. If you are wanting to change the Python-only behavior of a model, but
|
||||
#. If you are wanting to change the Python-only behavior of a model, but
|
||||
keep all the same fields as in the original, use ``Meta.proxy=True``.
|
||||
This sets things up so that the proxy model is an exact copy of the
|
||||
storage structure of the original model when data is saved.
|
||||
|
|
|
|||
|
|
@ -283,7 +283,7 @@ many-to-many relation to User, the following template code is optimal:
|
|||
|
||||
It is optimal because:
|
||||
|
||||
1. Since QuerySets are lazy, this does no database queries if 'display_inbox'
|
||||
#. Since QuerySets are lazy, this does no database queries if 'display_inbox'
|
||||
is False.
|
||||
|
||||
#. Use of :ttag:`with` means that we store ``user.emails.all`` in a variable
|
||||
|
|
|
|||
|
|
@ -148,9 +148,9 @@ Instantiating, processing, and rendering forms
|
|||
|
||||
When rendering an object in Django, we generally:
|
||||
|
||||
1. get hold of it in the view (fetch it from the database, for example)
|
||||
2. pass it to the template context
|
||||
3. expand it to HTML markup using template variables
|
||||
#. get hold of it in the view (fetch it from the database, for example)
|
||||
#. pass it to the template context
|
||||
#. expand it to HTML markup using template variables
|
||||
|
||||
Rendering a form in a template involves nearly the same work as rendering any
|
||||
other kind of object, but there are some key differences.
|
||||
|
|
|
|||
|
|
@ -319,7 +319,7 @@ may need some changes to adjust to the new semantics.
|
|||
These are the behavioral differences between using :setting:`MIDDLEWARE` and
|
||||
``MIDDLEWARE_CLASSES``:
|
||||
|
||||
1. Under ``MIDDLEWARE_CLASSES``, every middleware will always have its
|
||||
#. Under ``MIDDLEWARE_CLASSES``, every middleware will always have its
|
||||
``process_response`` method called, even if an earlier middleware
|
||||
short-circuited by returning a response from its ``process_request``
|
||||
method. Under :setting:`MIDDLEWARE`, middleware behaves more like an onion:
|
||||
|
|
@ -328,7 +328,7 @@ These are the behavioral differences between using :setting:`MIDDLEWARE` and
|
|||
that middleware and the ones before it in :setting:`MIDDLEWARE` will see the
|
||||
response.
|
||||
|
||||
2. Under ``MIDDLEWARE_CLASSES``, ``process_exception`` is applied to
|
||||
#. Under ``MIDDLEWARE_CLASSES``, ``process_exception`` is applied to
|
||||
exceptions raised from a middleware ``process_request`` method. Under
|
||||
:setting:`MIDDLEWARE`, ``process_exception`` applies only to exceptions
|
||||
raised from the view (or from the ``render`` method of a
|
||||
|
|
@ -336,7 +336,7 @@ These are the behavioral differences between using :setting:`MIDDLEWARE` and
|
|||
a middleware are converted to the appropriate HTTP response and then passed
|
||||
to the next middleware.
|
||||
|
||||
3. Under ``MIDDLEWARE_CLASSES``, if a ``process_response`` method raises
|
||||
#. Under ``MIDDLEWARE_CLASSES``, if a ``process_response`` method raises
|
||||
an exception, the ``process_response`` methods of all earlier middleware are
|
||||
skipped and a ``500 Internal Server Error`` HTTP response is always
|
||||
returned (even if the exception raised was e.g. an
|
||||
|
|
|
|||
|
|
@ -119,7 +119,7 @@ Examples
|
|||
|
||||
You can use the :func:`redirect` function in a number of ways.
|
||||
|
||||
1. By passing some object; that object's
|
||||
#. By passing some object; that object's
|
||||
:meth:`~django.db.models.Model.get_absolute_url` method will be called
|
||||
to figure out the redirect URL::
|
||||
|
||||
|
|
@ -130,7 +130,7 @@ You can use the :func:`redirect` function in a number of ways.
|
|||
obj = MyModel.objects.get(...)
|
||||
return redirect(obj)
|
||||
|
||||
2. By passing the name of a view and optionally some positional or
|
||||
#. By passing the name of a view and optionally some positional or
|
||||
keyword arguments; the URL will be reverse resolved using the
|
||||
:func:`~django.urls.reverse` method::
|
||||
|
||||
|
|
@ -138,7 +138,7 @@ You can use the :func:`redirect` function in a number of ways.
|
|||
...
|
||||
return redirect('some-view-name', foo='bar')
|
||||
|
||||
3. By passing a hardcoded URL to redirect to::
|
||||
#. By passing a hardcoded URL to redirect to::
|
||||
|
||||
def my_view(request):
|
||||
...
|
||||
|
|
|
|||
|
|
@ -34,20 +34,20 @@ How Django processes a request
|
|||
When a user requests a page from your Django-powered site, this is the
|
||||
algorithm the system follows to determine which Python code to execute:
|
||||
|
||||
1. Django determines the root URLconf module to use. Ordinarily,
|
||||
#. Django determines the root URLconf module to use. Ordinarily,
|
||||
this is the value of the :setting:`ROOT_URLCONF` setting, but if the incoming
|
||||
``HttpRequest`` object has a :attr:`~django.http.HttpRequest.urlconf`
|
||||
attribute (set by middleware), its value will be used in place of the
|
||||
:setting:`ROOT_URLCONF` setting.
|
||||
|
||||
2. Django loads that Python module and looks for the variable
|
||||
#. Django loads that Python module and looks for the variable
|
||||
``urlpatterns``. This should be a Python list of :func:`django.urls.path`
|
||||
and/or :func:`django.urls.re_path` instances.
|
||||
|
||||
3. Django runs through each URL pattern, in order, and stops at the first
|
||||
#. Django runs through each URL pattern, in order, and stops at the first
|
||||
one that matches the requested URL.
|
||||
|
||||
4. Once one of the URL patterns matches, Django imports and calls the given
|
||||
#. Once one of the URL patterns matches, Django imports and calls the given
|
||||
view, which is a simple Python function (or a :doc:`class-based view
|
||||
</topics/class-based-views/index>`). The view gets passed the following
|
||||
arguments:
|
||||
|
|
@ -60,7 +60,7 @@ algorithm the system follows to determine which Python code to execute:
|
|||
``kwargs`` argument to :func:`django.urls.path` or
|
||||
:func:`django.urls.re_path`.
|
||||
|
||||
5. If no URL pattern matches, or if an exception is raised during any
|
||||
#. If no URL pattern matches, or if an exception is raised during any
|
||||
point in this process, Django invokes an appropriate
|
||||
error-handling view. See `Error handling`_ below.
|
||||
|
||||
|
|
@ -718,11 +718,11 @@ Reversing namespaced URLs
|
|||
When given a namespaced URL (e.g. ``'polls:index'``) to resolve, Django splits
|
||||
the fully qualified name into parts and then tries the following lookup:
|
||||
|
||||
1. First, Django looks for a matching :term:`application namespace` (in this
|
||||
#. First, Django looks for a matching :term:`application namespace` (in this
|
||||
example, ``'polls'``). This will yield a list of instances of that
|
||||
application.
|
||||
|
||||
2. If there is a current application defined, Django finds and returns the URL
|
||||
#. If there is a current application defined, Django finds and returns the URL
|
||||
resolver for that instance. The current application can be specified with
|
||||
the ``current_app`` argument to the :func:`~django.urls.reverse()`
|
||||
function.
|
||||
|
|
@ -733,15 +733,15 @@ the fully qualified name into parts and then tries the following lookup:
|
|||
setting the current application on the :attr:`request.current_app
|
||||
<django.http.HttpRequest.current_app>` attribute.
|
||||
|
||||
3. If there is no current application, Django looks for a default
|
||||
#. If there is no current application, Django looks for a default
|
||||
application instance. The default application instance is the instance
|
||||
that has an :term:`instance namespace` matching the :term:`application
|
||||
namespace` (in this example, an instance of ``polls`` called ``'polls'``).
|
||||
|
||||
4. If there is no default application instance, Django will pick the last
|
||||
#. If there is no default application instance, Django will pick the last
|
||||
deployed instance of the application, whatever its instance name may be.
|
||||
|
||||
5. If the provided namespace doesn't match an :term:`application namespace` in
|
||||
#. If the provided namespace doesn't match an :term:`application namespace` in
|
||||
step 1, Django will attempt a direct lookup of the namespace as an
|
||||
:term:`instance namespace`.
|
||||
|
||||
|
|
|
|||
|
|
@ -462,7 +462,7 @@ FAQ
|
|||
Setup
|
||||
-----
|
||||
|
||||
1. **I don't need multiple time zones. Should I enable time zone support?**
|
||||
#. **I don't need multiple time zones. Should I enable time zone support?**
|
||||
|
||||
Yes. When time zone support is enabled, Django uses a more accurate model
|
||||
of local time. This shields you from subtle and unreproducible bugs around
|
||||
|
|
@ -481,7 +481,7 @@ Setup
|
|||
For these reasons, time zone support is enabled by default in new projects,
|
||||
and you should keep it unless you have a very good reason not to.
|
||||
|
||||
2. **I've enabled time zone support. Am I safe?**
|
||||
#. **I've enabled time zone support. Am I safe?**
|
||||
|
||||
Maybe. You're better protected from DST-related bugs, but you can still
|
||||
shoot yourself in the foot by carelessly turning naive datetimes into aware
|
||||
|
|
@ -508,7 +508,7 @@ Setup
|
|||
one year is 2011-02-28 or 2011-03-01, which depends on your business
|
||||
requirements.)
|
||||
|
||||
3. **How do I interact with a database that stores datetimes in local time?**
|
||||
#. **How do I interact with a database that stores datetimes in local time?**
|
||||
|
||||
Set the :setting:`TIME_ZONE <DATABASE-TIME_ZONE>` option to the appropriate
|
||||
time zone for this database in the :setting:`DATABASES` setting.
|
||||
|
|
@ -519,7 +519,7 @@ Setup
|
|||
Troubleshooting
|
||||
---------------
|
||||
|
||||
1. **My application crashes with** ``TypeError: can't compare offset-naive``
|
||||
#. **My application crashes with** ``TypeError: can't compare offset-naive``
|
||||
``and offset-aware datetimes`` **-- what's wrong?**
|
||||
|
||||
Let's reproduce this error by comparing a naive and an aware datetime::
|
||||
|
|
@ -551,7 +551,7 @@ Troubleshooting
|
|||
datetime when ``USE_TZ = True``. You can add or subtract
|
||||
:class:`datetime.timedelta` as needed.
|
||||
|
||||
2. **I see lots of** ``RuntimeWarning: DateTimeField received a naive
|
||||
#. **I see lots of** ``RuntimeWarning: DateTimeField received a naive
|
||||
datetime`` ``(YYYY-MM-DD HH:MM:SS)`` ``while time zone support is active``
|
||||
**-- is that bad?**
|
||||
|
||||
|
|
@ -564,7 +564,7 @@ Troubleshooting
|
|||
In the meantime, for backwards compatibility, the datetime is considered to
|
||||
be in the default time zone, which is generally what you expect.
|
||||
|
||||
3. ``now.date()`` **is yesterday! (or tomorrow)**
|
||||
#. ``now.date()`` **is yesterday! (or tomorrow)**
|
||||
|
||||
If you've always used naive datetimes, you probably believe that you can
|
||||
convert a datetime to a date by calling its :meth:`~datetime.datetime.date`
|
||||
|
|
@ -623,7 +623,7 @@ Troubleshooting
|
|||
>>> local.date()
|
||||
datetime.date(2012, 3, 3)
|
||||
|
||||
4. **I get an error** "``Are time zone definitions for your database
|
||||
#. **I get an error** "``Are time zone definitions for your database
|
||||
installed?``"
|
||||
|
||||
If you are using MySQL, see the :ref:`mysql-time-zone-definitions` section
|
||||
|
|
@ -632,7 +632,7 @@ Troubleshooting
|
|||
Usage
|
||||
-----
|
||||
|
||||
1. **I have a string** ``"2012-02-21 10:28:45"`` **and I know it's in the**
|
||||
#. **I have a string** ``"2012-02-21 10:28:45"`` **and I know it's in the**
|
||||
``"Europe/Helsinki"`` **time zone. How do I turn that into an aware
|
||||
datetime?**
|
||||
|
||||
|
|
@ -649,7 +649,7 @@ Usage
|
|||
documentation of pytz contains `more examples`_. You should review it
|
||||
before attempting to manipulate aware datetimes.
|
||||
|
||||
2. **How can I obtain the local time in the current time zone?**
|
||||
#. **How can I obtain the local time in the current time zone?**
|
||||
|
||||
Well, the first question is, do you really need to?
|
||||
|
||||
|
|
@ -672,7 +672,7 @@ Usage
|
|||
|
||||
In this example, the current time zone is ``"Europe/Paris"``.
|
||||
|
||||
3. **How can I see all available time zones?**
|
||||
#. **How can I see all available time zones?**
|
||||
|
||||
pytz_ provides helpers_, including a list of current time zones and a list
|
||||
of all available time zones -- some of which are only of historical
|
||||
|
|
|
|||
|
|
@ -63,12 +63,12 @@ as a shorter alias, ``_``, to save typing.
|
|||
global namespace, as an alias for ``gettext()``. In Django, we have chosen
|
||||
not to follow this practice, for a couple of reasons:
|
||||
|
||||
1. Sometimes, you should use :func:`~django.utils.translation.gettext_lazy`
|
||||
#. Sometimes, you should use :func:`~django.utils.translation.gettext_lazy`
|
||||
as the default translation method for a particular file. Without ``_()``
|
||||
in the global namespace, the developer has to think about which is the
|
||||
most appropriate translation function.
|
||||
|
||||
2. The underscore character (``_``) is used to represent "the previous
|
||||
#. The underscore character (``_``) is used to represent "the previous
|
||||
result" in Python's interactive shell and doctest tests. Installing a
|
||||
global ``_()`` function causes interference. Explicitly importing
|
||||
``gettext()`` as ``_()`` avoids this problem.
|
||||
|
|
@ -2073,13 +2073,13 @@ the order in which it examines the different file paths to load the compiled
|
|||
:term:`message files <message file>` (``.mo``) and the precedence of multiple
|
||||
translations for the same literal:
|
||||
|
||||
1. The directories listed in :setting:`LOCALE_PATHS` have the highest
|
||||
#. The directories listed in :setting:`LOCALE_PATHS` have the highest
|
||||
precedence, with the ones appearing first having higher precedence than
|
||||
the ones appearing later.
|
||||
2. Then, it looks for and uses if it exists a ``locale`` directory in each
|
||||
#. Then, it looks for and uses if it exists a ``locale`` directory in each
|
||||
of the installed apps listed in :setting:`INSTALLED_APPS`. The ones
|
||||
appearing first have higher precedence than the ones appearing later.
|
||||
3. Finally, the Django-provided base translation in ``django/conf/locale``
|
||||
#. Finally, the Django-provided base translation in ``django/conf/locale``
|
||||
is used as a fallback.
|
||||
|
||||
.. seealso::
|
||||
|
|
|
|||
|
|
@ -140,18 +140,18 @@ Installing an official release with ``pip``
|
|||
|
||||
This is the recommended way to install Django.
|
||||
|
||||
1. Install pip_. The easiest is to use the `standalone pip installer`_. If your
|
||||
#. Install pip_. The easiest is to use the `standalone pip installer`_. If your
|
||||
distribution already has ``pip`` installed, you might need to update it if
|
||||
it's outdated. If it's outdated, you'll know because installation won't
|
||||
work.
|
||||
|
||||
2. Take a look at virtualenv_ and virtualenvwrapper_. These tools provide
|
||||
#. Take a look at virtualenv_ and virtualenvwrapper_. These tools provide
|
||||
isolated Python environments, which are more practical than installing
|
||||
packages systemwide. They also allow installing packages without
|
||||
administrator privileges. The :doc:`contributing tutorial
|
||||
</intro/contributing>` walks through how to create a virtualenv.
|
||||
|
||||
3. After you've created and activated a virtual environment, enter the command
|
||||
#. After you've created and activated a virtual environment, enter the command
|
||||
``pip install Django`` at the shell prompt.
|
||||
|
||||
.. _pip: https://pip.pypa.io/
|
||||
|
|
@ -191,10 +191,10 @@ Installing the development version
|
|||
If you'd like to be able to update your Django code occasionally with the
|
||||
latest bug fixes and improvements, follow these instructions:
|
||||
|
||||
1. Make sure that you have Git_ installed and that you can run its commands
|
||||
#. Make sure that you have Git_ installed and that you can run its commands
|
||||
from a shell. (Enter ``git help`` at a shell prompt to test this.)
|
||||
|
||||
2. Check out Django's main development branch like so:
|
||||
#. Check out Django's main development branch like so:
|
||||
|
||||
.. console::
|
||||
|
||||
|
|
@ -202,12 +202,12 @@ latest bug fixes and improvements, follow these instructions:
|
|||
|
||||
This will create a directory ``django`` in your current directory.
|
||||
|
||||
3. Make sure that the Python interpreter can load Django's code. The most
|
||||
#. Make sure that the Python interpreter can load Django's code. The most
|
||||
convenient way to do this is to use virtualenv_, virtualenvwrapper_, and
|
||||
pip_. The :doc:`contributing tutorial </intro/contributing>` walks through
|
||||
how to create a virtualenv.
|
||||
|
||||
4. After setting up and activating the virtualenv, run the following command:
|
||||
#. After setting up and activating the virtualenv, run the following command:
|
||||
|
||||
.. console::
|
||||
|
||||
|
|
|
|||
|
|
@ -244,7 +244,7 @@ User-uploaded content
|
|||
validate all user uploaded file content, however, there are some other steps
|
||||
you can take to mitigate these attacks:
|
||||
|
||||
1. One class of attacks can be prevented by always serving user uploaded
|
||||
#. One class of attacks can be prevented by always serving user uploaded
|
||||
content from a distinct top-level or second-level domain. This prevents
|
||||
any exploit blocked by `same-origin policy`_ protections such as cross
|
||||
site scripting. For example, if your site runs on ``example.com``, you
|
||||
|
|
@ -252,7 +252,7 @@ User-uploaded content
|
|||
from something like ``usercontent-example.com``. It's *not* sufficient to
|
||||
serve content from a subdomain like ``usercontent.example.com``.
|
||||
|
||||
2. Beyond this, applications may choose to define a whitelist of allowable
|
||||
#. Beyond this, applications may choose to define a whitelist of allowable
|
||||
file extensions for user uploaded files and configure the web server
|
||||
to only serve such files.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue