mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2024-12-23 01:25:58 +00:00
Code Issues 25 Releases Wiki Activity

Fixed #26483 -- Updated docs.python.org links to use Intersphinx.

Browse Source
This commit is contained in:
Tim Graham 2016-05-08 18:07:43 -04:00
parent 413f3bb5c8
commit f5ff5010cd
20 changed files with 75 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
django/template/defaultfilters.py
View File

@ -243,8 +243,8 @@ def stringformat(value, arg):
This specifier uses Python string formating syntax, with the exception that
the leading "%" is dropped.
See http://docs.python.org/lib/typesseq-strings.html for documentation
of Python string formatting
See https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting
for documentation of Python string formatting.
"""
try:
return ("%" + six.text_type(arg)) % value

2
docs/howto/deployment/checklist.txt
View File

@ -264,4 +264,4 @@ drastically increase CPU usage by causing worst-case performance when
creating ``dict`` instances. See `oCERT advisory #2011-003
<http://www.ocert.org/advisories/ocert-2011-003.html>`_ for more information.
.. _-r: https://docs.python.org/using/cmdline.html#cmdoption-R
.. _-r: https://docs.python.org/2/using/cmdline.html#cmdoption-R

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

@ -70,7 +70,7 @@ mention:
For more information, see the Python documentation of the :mod:`csv` module.
.. _`csv module's examples section`: https://docs.python.org/library/csv.html#examples
.. _`csv module's examples section`: https://docs.python.org/2/library/csv.html#examples
.. _`python-unicodecsv module`: https://github.com/jdunck/python-unicodecsv
.. _streaming-csv-files:

3
docs/intro/contributing.txt
View File

@ -373,10 +373,9 @@ that passing a ``prefix`` parameter when creating an instance still works too.
* Dive Into Python (a free online book for beginning Python developers)
includes a great `introduction to Unit Testing`__.
* After reading those, if you want something a little meatier to sink
your teeth into, there's always the `Python unittest documentation`__.
your teeth into, there's always the Python :mod:`unittest` documentation.
__ http://www.diveintopython.net/unit_testing/index.html
__ https://docs.python.org/library/unittest.html
Running your new test
---------------------

16
docs/intro/overview.txt
View File

@ -201,15 +201,13 @@ example above:
url(r'^articles/([0-9]{4})/([0-9]{2})/([0-9]+)/$', views.article_detail),
]
The code above maps URLs, as simple `regular expressions`_, to the location of
Python callback functions ("views"). The regular expressions use parenthesis to
"capture" values from the URLs. When a user requests a page, Django runs
through each pattern, in order, and stops at the first one that matches the
requested URL. (If none of them matches, Django calls a special-case 404 view.)
This is blazingly fast, because the regular expressions are compiled at load
time.
.. _regular expressions: https://docs.python.org/howto/regex.html
The code above maps URLs, as simple :ref:`regular expressions <regex-howto>`,
to the location of Python callback functions ("views"). The regular expressions
use parenthesis to "capture" values from the URLs. When a user requests a page,
Django runs through each pattern, in order, and stops at the first one that
matches the requested URL. (If none of them matches, Django calls a
special-case 404 view.) This is blazingly fast, because the regular expressions
are compiled at load time.
Once one of the regexes matches, Django imports and calls the given view, which
is a simple Python function. Each view gets passed a request object --

6
docs/intro/reusable-apps.txt
View File

@ -34,9 +34,9 @@ projects and ready to publish for others to install and use.
.. admonition:: Package? App?
A Python `package <https://docs.python.org/tutorial/modules.html#packages>`_
provides a way of grouping related Python code for easy reuse. A package
contains one or more files of Python code (also known as "modules").
A Python :term:`package` provides a way of grouping related Python code for
easy reuse. A package contains one or more files of Python code (also known
as "modules").
A package can be imported with ``import foo.bar`` or ``from foo import
bar``. For a directory (like ``polls``) to form a package, it must contain

15
docs/intro/tutorial01.txt
View File

@ -102,8 +102,8 @@ These files are:
anything inside it (e.g. ``mysite.urls``).
* :file:`mysite/__init__.py`: An empty file that tells Python that this
directory should be considered a Python package. (Read `more about
packages`_ in the official Python docs if you're a Python beginner.)
directory should be considered a Python package. If you're a Python beginner,
read :ref:`more about packages <tut-packages>` in the official Python docs.
* :file:`mysite/settings.py`: Settings/configuration for this Django
project. :doc:`/topics/settings` will tell you all about how settings
@ -116,8 +116,6 @@ These files are:
* :file:`mysite/wsgi.py`: An entry-point for WSGI-compatible web servers to
serve your project. See :doc:`/howto/deployment/wsgi/index` for more details.
.. _more about packages: https://docs.python.org/tutorial/modules.html#packages
The development server
======================
@ -211,9 +209,10 @@ rather than creating directories.
configuration and apps for a particular website. A project can contain
multiple apps. An app can be in multiple projects.
Your apps can live anywhere on your `Python path`_. In this tutorial, we'll
create our poll app right next to your :file:`manage.py` file so that it can be
imported as its own top-level module, rather than a submodule of ``mysite``.
Your apps can live anywhere on your :ref:`Python path <tut-searchpath>`. In
this tutorial, we'll create our poll app right next to your :file:`manage.py`
file so that it can be imported as its own top-level module, rather than a
submodule of ``mysite``.
To create your app, make sure you're in the same directory as :file:`manage.py`
and type this command:
@ -236,8 +235,6 @@ That'll create a directory :file:`polls`, which is laid out like this::
This directory structure will house the poll application.
.. _`Python path`: https://docs.python.org/tutorial/modules.html#the-module-search-path
Write your first view
=====================

8
docs/ref/contrib/index.txt
View File

@ -2,9 +2,9 @@
``contrib`` packages
====================
Django aims to follow Python's `"batteries included" philosophy`_. It ships
with a variety of extra, optional tools that solve common Web-development
problems.
Django aims to follow Python's :ref:`"batteries included" philosophy
<tut-batteries-included>`. It ships with a variety of extra, optional tools
that solve common Web-development problems.
This code lives in ``django/contrib`` in the Django distribution. This document
gives a rundown of the packages in ``contrib``, along with any dependencies
@ -17,8 +17,6 @@ those packages have.
``'django.contrib.redirects'``) to your :setting:`INSTALLED_APPS` setting
and re-run ``manage.py migrate``.
.. _"batteries included" philosophy: https://docs.python.org/tutorial/stdlib.html#batteries-included
.. toctree::
:maxdepth: 1

28
docs/ref/models/instances.txt
View File

@ -599,8 +599,8 @@ Other model instance methods
A few object methods have special purposes.
``__str__``
-----------
``__str__()``
-------------
.. method:: Model.__str__()
@ -626,8 +626,8 @@ For example::
If you'd like compatibility with Python 2, you can decorate your model class
with :func:`~django.utils.encoding.python_2_unicode_compatible` as shown above.
``__eq__``
----------
``__eq__()``
------------
.. method:: Model.__eq__()
@ -655,22 +655,20 @@ For example::
MyModel(id=1) != MultitableInherited(id=1)
MyModel(id=1) != MyModel(id=2)
``__hash__``
------------
``__hash__()``
--------------
.. method:: Model.__hash__()
The ``__hash__`` method is based on the instance's primary key value. It
is effectively hash(obj.pk). If the instance doesn't have a primary key
value then a ``TypeError`` will be raised (otherwise the ``__hash__``
The ``__hash__()`` method is based on the instance's primary key value. It
is effectively ``hash(obj.pk)``. If the instance doesn't have a primary key
value then a ``TypeError`` will be raised (otherwise the ``__hash__()``
method would return different values before and after the instance is
saved, but changing the ``__hash__`` value of an instance `is forbidden
in Python`_).
saved, but changing the :meth:`~object.__hash__` value of an instance is
forbidden in Python.
.. _is forbidden in Python: https://docs.python.org/reference/datamodel.html#object.__hash__
``get_absolute_url``
--------------------
``get_absolute_url()``
----------------------
.. method:: Model.get_absolute_url()

27
docs/ref/settings.txt
View File

@ -924,16 +924,15 @@ Default::
A list of formats that will be accepted when inputting data on a date field.
Formats will be tried in order, using the first valid one. Note that these
format strings use Python's datetime_ module syntax, not the format strings
from the ``date`` Django template tag.
format strings use Python's :ref:`datetime module syntax
<strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
template filter.
When :setting:`USE_L10N` is ``True``, the locale-dictated format has higher
precedence and will be applied instead.
See also :setting:`DATETIME_INPUT_FORMATS` and :setting:`TIME_INPUT_FORMATS`.
.. _datetime: https://docs.python.org/library/datetime.html#strftime-strptime-behavior
.. setting:: DATETIME_FORMAT
``DATETIME_FORMAT``
@ -972,16 +971,15 @@ Default::
A list of formats that will be accepted when inputting data on a datetime
field. Formats will be tried in order, using the first valid one. Note that
these format strings use Python's datetime_ module syntax, not the format
strings from the ``date`` Django template tag.
these format strings use Python's :ref:`datetime module syntax
<strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
template filter.
When :setting:`USE_L10N` is ``True``, the locale-dictated format has higher
precedence and will be applied instead.
See also :setting:`DATE_INPUT_FORMATS` and :setting:`TIME_INPUT_FORMATS`.
.. _datetime: https://docs.python.org/library/datetime.html#strftime-strptime-behavior
.. setting:: DEBUG
``DEBUG``
@ -1730,14 +1728,12 @@ __ https://github.com/django/django/blob/master/django/utils/log.py
Default: ``'logging.config.dictConfig'``
A path to a callable that will be used to configure logging in the
Django project. Points at a instance of Python's `dictConfig`_
configuration method by default.
Django project. Points at a instance of Python's :ref:`dictConfig
<logging-config-dictschema>` configuration method by default.
If you set :setting:`LOGGING_CONFIG` to ``None``, the logging
configuration process will be skipped.
.. _dictConfig: https://docs.python.org/library/logging.config.html#configuration-dictionary-schema
.. setting:: MANAGERS
``MANAGERS``
@ -2368,16 +2364,15 @@ Default::
A list of formats that will be accepted when inputting data on a time field.
Formats will be tried in order, using the first valid one. Note that these
format strings use Python's datetime_ module syntax, not the format strings
from the ``date`` Django template tag.
format strings use Python's :ref:`datetime module syntax
<strftime-strptime-behavior>`, not the format strings from the :tfilter:`date`
template filter.
When :setting:`USE_L10N` is ``True``, the locale-dictated format has higher
precedence and will be applied instead.
See also :setting:`DATE_INPUT_FORMATS` and :setting:`DATETIME_INPUT_FORMATS`.
.. _datetime: https://docs.python.org/library/datetime.html#strftime-strptime-behavior
.. setting:: TIME_ZONE
``TIME_ZONE``

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

@ -2044,11 +2044,8 @@ If ``value`` is ``"Joel is a slug"``, the output will be ``"joel-is-a-slug"``.
----------------
Formats the variable according to the argument, a string formatting specifier.
This specifier uses Python string formatting syntax, with the exception that
the leading "%" is dropped.
See https://docs.python.org/library/stdtypes.html#string-formatting-operations
for documentation of Python string formatting
This specifier uses the :ref:`old-string-formatting` syntax, with the exception
that the leading "%" is dropped.
For example::

16
docs/ref/utils.txt
View File

@ -618,14 +618,14 @@ escaping HTML.
.. function:: format_html(format_string, *args, **kwargs)
This is similar to `str.format`_, except that it is appropriate for
This is similar to :meth:`str.format`, except that it is appropriate for
building up HTML fragments. All args and kwargs are passed through
:func:`conditional_escape` before being passed to ``str.format``.
:func:`conditional_escape` before being passed to ``str.format()``.
For the case of building up small HTML fragments, this function is to be
preferred over string interpolation using ``%`` or ``str.format`` directly,
because it applies escaping to all arguments - just like the Template system
applies escaping by default.
preferred over string interpolation using ``%`` or ``str.format()``
directly, because it applies escaping to all arguments - just like the
template system applies escaping by default.
So, instead of writing::
@ -642,14 +642,12 @@ escaping HTML.
This has the advantage that you don't need to apply :func:`escape` to each
argument and risk a bug and an XSS vulnerability if you forget one.
Note that although this function uses ``str.format`` to do the
interpolation, some of the formatting options provided by `str.format`_
Note that although this function uses ``str.format()`` to do the
interpolation, some of the formatting options provided by ``str.format()``
(e.g. number formatting) will not work, since all arguments are passed
through :func:`conditional_escape` which (ultimately) calls
:func:`~django.utils.encoding.force_text` on the values.
.. _str.format: https://docs.python.org/library/stdtypes.html#str.format
.. function:: format_html_join(sep, format_string, args_generator)
A wrapper of :func:`format_html`, for the common case of a group of

4
docs/releases/1.3.txt
View File

@ -149,13 +149,11 @@ Transaction context managers
----------------------------
Users of Python 2.5 and above may now use transaction management functions as
`context managers`_. For example::
context managers. For example::
with transaction.autocommit():
# ...
.. _context managers: https://docs.python.org/glossary.html#term-context-manager
Configurable delete-cascade
---------------------------

4
docs/releases/1.4.txt
View File

@ -1304,14 +1304,12 @@ Wildcard expansion of application names in `INSTALLED_APPS`
Until Django 1.3, :setting:`INSTALLED_APPS` accepted wildcards in application
names, like ``django.contrib.*``. The expansion was performed by a
filesystem-based implementation of ``from <package> import *``. Unfortunately,
`this can't be done reliably`_.
this can't be done reliably.
This behavior was never documented. Since it is unpythonic and not obviously
useful, it was removed in Django 1.4. If you relied on it, you must edit your
settings file to list all your applications explicitly.
.. _this can't be done reliably: https://docs.python.org/tutorial/modules.html#importing-from-a-package
``HttpRequest.raw_post_data`` renamed to ``HttpRequest.body``
-------------------------------------------------------------

5
docs/releases/1.6.txt
View File

@ -422,7 +422,8 @@ support some types of tests that were supported by the previous runner:
found and run. Move them to a file whose name begins with ``test``.
* Doctests will no longer be automatically discovered. To integrate doctests in
your test suite, follow the `recommendations in the Python documentation`_.
your test suite, follow the :ref:`recommendations in the Python documentation
<doctest-unittest-api>`.
Django bundles a modified version of the :mod:`doctest` module from the Python
standard library (in ``django.test._doctest``) and includes some additional
@ -435,8 +436,6 @@ If you wish to delay updates to your test suite, you can set your
to fully restore the old test behavior. ``DjangoTestSuiteRunner`` is deprecated
but will not be removed from Django until version 1.8.
.. _recommendations in the Python documentation: https://docs.python.org/library/doctest.html#unittest-api
Removal of ``django.contrib.gis.tests.GeoDjangoTestSuiteRunner`` GeoDjango custom test runner
---------------------------------------------------------------------------------------------

4
docs/topics/db/queries.txt
View File

@ -402,9 +402,7 @@ translates (roughly) into the following SQL:
Python has the ability to define functions that accept arbitrary name-value
arguments whose names and values are evaluated at runtime. For more
information, see `Keyword Arguments`_ in the official Python tutorial.
.. _`Keyword Arguments`: https://docs.python.org/tutorial/controlflow.html#keyword-arguments
information, see :ref:`tut-keywordargs` in the official Python tutorial.
The field specified in a lookup has to be the name of a model field. There's
one exception though, in case of a :class:`~django.db.models.ForeignKey` you

5
docs/topics/files.txt
View File

@ -77,10 +77,7 @@ The ``File`` object
===================
Internally, Django uses a :class:`django.core.files.File` instance any time it
needs to represent a file. This object is a thin wrapper around Python's
`built-in file object`_ with some Django-specific additions.
.. _built-in file object: https://docs.python.org/library/stdtypes.html#bltin-file-objects
needs to represent a file.
Most of the time you'll simply use a ``File`` that Django's given you (i.e. a
file attached to a model as above, or perhaps an uploaded file).

15
docs/topics/logging.txt
View File

@ -204,7 +204,8 @@ formatters to ensure that logging output is output in a useful way.
Python's logging library provides several techniques to configure
logging, ranging from a programmatic interface to configuration files.
By default, Django uses the `dictConfig format`_.
By default, Django uses the :ref:`dictConfig format
<logging-config-dictschema>`.
In order to configure logging, you use :setting:`LOGGING` to define a
dictionary of logging settings. These settings describes the loggers,
@ -231,14 +232,12 @@ Logging is configured as part of the general Django ``setup()`` function.
Therefore, you can be certain that loggers are always ready for use in your
project code.
.. _dictConfig format: https://docs.python.org/library/logging.config.html#configuration-dictionary-schema
Examples
--------
The full documentation for `dictConfig format`_ is the best source of
information about logging configuration dictionaries. However, to give
you a taste of what is possible, here are several examples.
The full documentation for :ref:`dictConfig format <logging-config-dictschema>`
is the best source of information about logging configuration dictionaries.
However, to give you a taste of what is possible, here are several examples.
First, here's a simple configuration which writes all logging from the
:ref:`django-logger` logger to a local file::
@ -364,7 +363,7 @@ This logging configuration does the following things:
The ``format`` string is a normal Python formatting string
describing the details that are to be output on each logging
line. The full list of detail that can be output can be
found in the `formatter documentation`_.
found in :ref:`formatter-objects`.
* ``verbose``, that outputs the log level name, the log
message, plus the time, process, thread and module that
@ -408,8 +407,6 @@ This logging configuration does the following things:
printed to the console; ``ERROR`` and ``CRITICAL``
messages will also be output via email.
.. _formatter documentation: https://docs.python.org/library/logging.html#formatter-objects
Custom logging configuration
----------------------------

8
docs/topics/python3.txt
View File

@ -16,9 +16,10 @@ Philosophy
==========
This document assumes that you are familiar with the changes between Python 2
and Python 3. If you aren't, read `Python's official porting guide`_ first.
Refreshing your knowledge of unicode handling on Python 2 and 3 will help; the
`Pragmatic Unicode`_ presentation is a good resource.
and Python 3. If you aren't, read :ref:`Python's official porting guide
<pyporting-howto>` first. Refreshing your knowledge of unicode handling on
Python 2 and 3 will help; the `Pragmatic Unicode`_ presentation is a good
resource.
Django uses the *Python 2/3 Compatible Source* strategy. Of course, you're
free to chose another strategy for your own code, especially if you don't need
@ -42,7 +43,6 @@ developers are used to dealing with such constraints.
Porting tools provided by Django are inspired by this philosophy, and it's
reflected throughout this guide.
.. _Python's official porting guide: https://docs.python.org/3/howto/pyporting.html
.. _Pragmatic Unicode: http://nedbatchelder.com/text/unipain.html
Porting tips

4
docs/topics/serialization.txt
View File

@ -258,7 +258,8 @@ serializer to make the format compatible with `ECMA-262`_.
Be aware that not all Django output can be passed unmodified to :mod:`json`.
For example, if you have some custom type in an object to be serialized, you'll
have to write a `special encoder`_ for it. Something like this will work::
have to write a custom :mod:`json` encoder for it. Something like this will
work::
from django.utils.encoding import force_text
from django.core.serializers.json import DjangoJSONEncoder
@ -272,7 +273,6 @@ have to write a `special encoder`_ for it. Something like this will work::
Also note that GeoDjango provides a :doc:`customized GeoJSON serializer
</ref/contrib/gis/serializers>`.
.. _special encoder: https://docs.python.org/library/json.html#encoders-and-decoders
.. _ecma-262: http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15
YAML