diff --git a/django/template/defaultfilters.py b/django/template/defaultfilters.py index eba65e5ed9..dc7ba32e8e 100644 --- a/django/template/defaultfilters.py +++ b/django/template/defaultfilters.py @@ -246,8 +246,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 diff --git a/docs/howto/deployment/checklist.txt b/docs/howto/deployment/checklist.txt index fe3692bf06..156617c48f 100644 --- a/docs/howto/deployment/checklist.txt +++ b/docs/howto/deployment/checklist.txt @@ -264,4 +264,4 @@ drastically increase CPU usage by causing worst-case performance when creating ``dict`` instances. See `oCERT advisory #2011-003 `_ for more information. -.. _-r: https://docs.python.org/using/cmdline.html#cmdoption-R +.. _-r: https://docs.python.org/2/using/cmdline.html#cmdoption-R diff --git a/docs/howto/outputting-csv.txt b/docs/howto/outputting-csv.txt index 2d9fded5c2..26a0c4eb1f 100644 --- a/docs/howto/outputting-csv.txt +++ b/docs/howto/outputting-csv.txt @@ -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: diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt index ab183896ae..ac06c1cae3 100644 --- a/docs/intro/contributing.txt +++ b/docs/intro/contributing.txt @@ -370,10 +370,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 --------------------- diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 8b5846f4ed..2324ef8ce5 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -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 `, +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 -- diff --git a/docs/intro/reusable-apps.txt b/docs/intro/reusable-apps.txt index fee59a37fa..c0e5e086f6 100644 --- a/docs/intro/reusable-apps.txt +++ b/docs/intro/reusable-apps.txt @@ -34,9 +34,9 @@ projects and ready to publish for others to install and use. .. admonition:: Package? App? - A Python `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 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 diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index de86571df3..ba50451d95 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -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 ` 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 `. 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 ===================== diff --git a/docs/ref/contrib/index.txt b/docs/ref/contrib/index.txt index 9df41e4419..deb718b472 100644 --- a/docs/ref/contrib/index.txt +++ b/docs/ref/contrib/index.txt @@ -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 +`. 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 diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 7909d9d5c6..5145088401 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -596,8 +596,8 @@ Other model instance methods A few object methods have special purposes. -``__str__`` ------------ +``__str__()`` +------------- .. method:: Model.__str__() @@ -623,8 +623,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__() @@ -652,22 +652,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() diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 6044c4f7cf..a139f21eba 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -954,16 +954,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 +`, 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`` @@ -1002,16 +1001,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 +`, 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`` @@ -1765,14 +1763,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 +` 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`` @@ -2528,16 +2524,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 +`, 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`` diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 12a7b6efb8..0835a50f94 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -2055,11 +2055,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:: diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index ee3054f181..3d6b792263 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -590,14 +590,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:: @@ -614,8 +614,8 @@ 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. diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 18f87fc0fd..fc6fe1acb2 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -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 --------------------------- diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index a1087768ab..91530d3b68 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -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 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`` ------------------------------------------------------------- diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index 9b7a17e95a..3443123875 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -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 + `. 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 --------------------------------------------------------------------------------------------- diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index f64496fc2e..6d2cbd9175 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -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 diff --git a/docs/topics/files.txt b/docs/topics/files.txt index 7a8ce0e801..d9b2adbdf5 100644 --- a/docs/topics/files.txt +++ b/docs/topics/files.txt @@ -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). diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt index 99fdad0463..c58e5c13d6 100644 --- a/docs/topics/logging.txt +++ b/docs/topics/logging.txt @@ -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 +`. 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 ` +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 ---------------------------- diff --git a/docs/topics/python3.txt b/docs/topics/python3.txt index 003dd0ebc5..04a975d8f2 100644 --- a/docs/topics/python3.txt +++ b/docs/topics/python3.txt @@ -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 +` 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 diff --git a/docs/topics/serialization.txt b/docs/topics/serialization.txt index 398880ca93..75a1eaa9cd 100644 --- a/docs/topics/serialization.txt +++ b/docs/topics/serialization.txt @@ -258,7 +258,7 @@ serializer to make the format compatible with `ECMA-262`_. Be aware that not all Django output can be passed unmodified to :mod:`json`. In particular, :ref:`lazy translation objects ` need a -`special encoder`_ written for them. Something like this will work:: +custom :mod:`json` encoder. Something like this will work:: from django.utils.functional import Promise from django.utils.encoding import force_text @@ -273,7 +273,6 @@ In particular, :ref:`lazy translation objects ` need a Also note that GeoDjango provides a :doc:`customized GeoJSON serializer `. -.. _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 @@ -481,7 +480,8 @@ command line flags to generate natural keys. You don't need to define both ``natural_key()`` and ``get_by_natural_key()``. If you don't want Django to output natural keys during serialization, but you want to retain the - ability to load natural keys, then you can opt to not implement + ability to load natural keys, then you can + opt to not implement the ``natural_key()`` method. Conversely, if (for some strange reason) you want Django to output