From 680a0f08b1ace39f995fce975caabb1875b07c6f Mon Sep 17 00:00:00 2001 From: Claude Paroz Date: Sat, 26 Apr 2014 16:00:15 +0200 Subject: [PATCH] Updated doc links to point to Python 3 documentation --- docs/conf.py | 4 +-- docs/intro/tutorial01.txt | 2 +- docs/intro/tutorial04.txt | 4 +-- docs/ref/applications.txt | 14 +++++------ docs/ref/contrib/auth.txt | 3 +-- docs/ref/contrib/sites.txt | 2 +- docs/ref/exceptions.txt | 3 +-- docs/ref/files/file.txt | 7 +++--- docs/ref/request-response.txt | 8 +++--- docs/ref/templates/builtins.txt | 2 +- docs/ref/utils.txt | 8 +++--- docs/ref/validators.txt | 4 +-- docs/releases/1.0-porting-guide.txt | 8 +++--- docs/releases/1.5-alpha-1.txt | 3 +-- docs/releases/1.5-beta-1.txt | 3 +-- docs/releases/1.5.txt | 3 +-- docs/releases/1.6.txt | 2 +- docs/releases/1.7.txt | 10 ++++---- docs/topics/db/examples/many_to_many.txt | 2 +- docs/topics/i18n/timezones.txt | 5 ++-- docs/topics/python3.txt | 31 +++++++++++++----------- docs/topics/testing/tools.txt | 11 ++++----- 22 files changed, 68 insertions(+), 71 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 30e57aee15..095a2eacb7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -118,10 +118,10 @@ show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'trac' -# Links to Python's docs should reference the most recent version of the 2.x +# Links to Python's docs should reference the most recent version of the 3.x # branch, which is located at this URL. intersphinx_mapping = { - 'python': ('http://docs.python.org/', None), + 'python': ('http://docs.python.org/3/', None), 'sphinx': ('http://sphinx-doc.org/', None), 'six': ('http://pythonhosted.org/six/', None), 'simplejson': ('http://simplejson.readthedocs.org/en/latest/', None), diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 3211bb873f..cce3d9aa65 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -637,7 +637,7 @@ the Python import path to your :file:`mysite/settings.py` file. >>> import django >>> django.setup() - If this raises an :exc:`~exceptions.AttributeError`, you're probably using + If this raises an :exc:`AttributeError`, you're probably using a version of Django that doesn't match this tutorial version. You'll want to either switch to the older tutorial or the newer Django version. diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt index a4863fe73d..dc6f621ff3 100644 --- a/docs/intro/tutorial04.txt +++ b/docs/intro/tutorial04.txt @@ -106,9 +106,9 @@ This code includes a few things we haven't covered yet in this tutorial: ` in our code, to ensure that data is only altered via a POST call. -* ``request.POST['choice']`` will raise :exc:`~exceptions.KeyError` if +* ``request.POST['choice']`` will raise :exc:`KeyError` if ``choice`` wasn't provided in POST data. The above code checks for - :exc:`~exceptions.KeyError` and redisplays the question form with an error + :exc:`KeyError` and redisplays the question form with an error message if ``choice`` isn't given. * After incrementing the choice count, the code returns an diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt index 489d39c2c5..0a7a0c991d 100644 --- a/docs/ref/applications.txt +++ b/docs/ref/applications.txt @@ -209,8 +209,8 @@ Methods .. method:: AppConfig.get_model(model_name) Returns the :class:`~django.db.models.Model` with the given - ``model_name``. Raises :exc:`~exceptions.LookupError` if no such model - exists. ``model_name`` is case-insensitive. + ``model_name``. Raises :exc:`LookupError` if no such model exists. + ``model_name`` is case-insensitive. .. method:: AppConfig.ready() @@ -284,8 +284,8 @@ Application registry .. method:: apps.get_app_config(app_label) Returns an :class:`~django.apps.AppConfig` for the application with the - given ``app_label``. Raises :exc:`~exceptions.LookupError` if no such - application exists. + given ``app_label``. Raises :exc:`LookupError` if no such application + exists. .. method:: apps.is_installed(app_name) @@ -303,9 +303,9 @@ Application registry argument in the form ``app_label.model_name``. ``model_name`` is case- insensitive. - Raises :exc:`~exceptions.LookupError` if no such application or model - exists. Raises :exc:`~exceptions.ValueError` when called with a single - argument that doesn't contain exactly one dot. + Raises :exc:`LookupError` if no such application or model exists. Raises + :exc:`ValueError` when called with a single argument that doesn't contain + exactly one dot. .. _applications-troubleshooting: diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index f80193c4cc..0f60ba0cfd 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -279,8 +279,7 @@ Anonymous users * :meth:`~django.contrib.auth.models.User.set_password()`, :meth:`~django.contrib.auth.models.User.check_password()`, :meth:`~django.db.models.Model.save` and - :meth:`~django.db.models.Model.delete()` raise - :exc:`~exceptions.NotImplementedError`. + :meth:`~django.db.models.Model.delete()` raise :exc:`NotImplementedError`. In practice, you probably won't need to use :class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index d0281cbe96..76862000ea 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -474,7 +474,7 @@ method takes an :class:`~django.http.HttpRequest` object. It's able to deduce the ``domain`` and ``name`` by looking at the request's domain. It has ``save()`` and ``delete()`` methods to match the interface of :class:`~django.contrib.sites.models.Site`, but the methods raise -:exc:`~exceptions.NotImplementedError`.. +:exc:`NotImplementedError`. ``get_current_site`` shortcut ============================= diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index 6d545bfc13..3b8b644c76 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -220,5 +220,4 @@ Python Exceptions ================= Django raises built-in Python exceptions when appropriate as well. See the -Python documentation for further information on the -built-in :mod:`exceptions`. +Python documentation for further information on the :ref:`bltin-exceptions`. diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index c2208baa47..6874936eab 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -11,8 +11,8 @@ The ``File`` Class .. class:: File(file_object) - The :class:`File` class is a thin wrapper around Python's :py:ref:`built-in - file object` with some Django-specific additions. + The :class:`File` class is a thin wrapper around a Python + :py:term:`file object` with some Django-specific additions. Internally, Django uses this class when it needs to represent a file. :class:`File` objects have the following attributes and methods: @@ -28,8 +28,7 @@ The ``File`` Class .. attribute:: file - The underlying :py:ref:`built-in file object` that - this class wraps. + The underlying :py:term:`file object` that this class wraps. .. attribute:: mode diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 929882989a..5029854569 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -662,8 +662,8 @@ Methods .. method:: HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=False) - Sets a cookie. The parameters are the same as in the :class:`Cookie.Morsel` - object in the Python standard library. + Sets a cookie. The parameters are the same as in the + :class:`~http.cookies.Morsel` cookie object in the Python standard library. * ``max_age`` should be a number of seconds, or ``None`` (default) if the cookie should last only as long as the client's browser session. @@ -822,7 +822,7 @@ JsonResponse objects The ``safe`` boolean parameter defaults to ``True``. If it's set to ``False``, any object can be passed for serialization (otherwise only ``dict`` instances are allowed). If ``safe`` is ``True`` and a non-``dict`` object is passed as - the first argument, a :exc:`~exceptions.TypeError` will be raised. + the first argument, a :exc:`TypeError` will be raised. Usage ----- @@ -843,7 +843,7 @@ parameter to ``False``:: >>> response = JsonResponse([1, 2, 3], safe=False) -Without passing ``safe=False``, a :exc:`~exceptions.TypeError` will be raised. +Without passing ``safe=False``, a :exc:`TypeError` will be raised. .. warning:: diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index a78fd49548..0a5a64f782 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -2465,7 +2465,7 @@ slightly different call: The :mod:`staticfiles` contrib app also ships with a :ttag:`static template tag` which uses ``staticfiles'`` :setting:`STATICFILES_STORAGE` to build the URL of the - given path (rather than simply using :func:`urlparse.urljoin` with the + given path (rather than simply using :func:`urllib.parse.urljoin` with the :setting:`STATIC_URL` setting and the given path). Use that instead if you have an advanced use case such as :ref:`using a cloud service to serve static files`:: diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index dcd5a18208..952cbac8a2 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -133,8 +133,8 @@ results. Instead do:: The functions defined in this module share the following properties: -- They raise :exc:`~exceptions.ValueError` if their input is well formatted but - isn't a valid date or time. +- They raise :exc:`ValueError` if their input is well formatted but isn't a + valid date or time. - They return ``None`` if it isn't well formatted at all. - They accept up to picosecond resolution in input, but they truncate it to microseconds, since that's what Python supports. @@ -688,7 +688,9 @@ escaping HTML. .. function:: int_to_base36(i) Converts a positive integer to a base 36 string. On Python 2 ``i`` must be - smaller than :data:`sys.maxint`. + smaller than `sys.maxint`_. + + .. _sys.maxint: http://docs.python.org/2/library/sys.html#sys.maxint .. function:: urlsafe_base64_encode(s) diff --git a/docs/ref/validators.txt b/docs/ref/validators.txt index 364606666b..20368916ab 100644 --- a/docs/ref/validators.txt +++ b/docs/ref/validators.txt @@ -68,7 +68,7 @@ to, or in lieu of custom ``field.clean()`` methods. :param inverse_match: If not ``None``, overrides :attr:`inverse_match`. :param flags: If not ``None``, overrides :attr:`flags`. In that case, :attr:`regex` must be a regular expression string, or - :exc:`~exceptions.TypeError` is raised. + :exc:`TypeError` is raised. .. attribute:: regex @@ -102,7 +102,7 @@ to, or in lieu of custom ``field.clean()`` methods. The flags used when compiling the regular expression string :attr:`regex`. If :attr:`regex` is a pre-compiled regular expression, and :attr:`flags` is overridden, - :exc:`~exceptions.TypeError` is raised. + :exc:`TypeError` is raised. Defaults to `0`. ``URLValidator`` diff --git a/docs/releases/1.0-porting-guide.txt b/docs/releases/1.0-porting-guide.txt index 5983e365fe..a3c1a95702 100644 --- a/docs/releases/1.0-porting-guide.txt +++ b/docs/releases/1.0-porting-guide.txt @@ -440,9 +440,9 @@ Settings Better exceptions ~~~~~~~~~~~~~~~~~ -The old :exc:`~exceptions.EnvironmentError` has split into an -:exc:`~exceptions.ImportError` when Django fails to find the settings module -and a :exc:`~exceptions.RuntimeError` when you try to reconfigure settings +The old :exc:`EnvironmentError` has split into an +:exc:`ImportError` when Django fails to find the settings module +and a :exc:`RuntimeError` when you try to reconfigure settings after having already used them. :setting:`LOGIN_URL` has moved @@ -479,7 +479,7 @@ Different exception from ``get()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Managers now return a :exc:`~django.core.exceptions.MultipleObjectsReturned` -exception instead of :exc:`~exceptions.AssertionError`: +exception instead of :exc:`AssertionError`: Old (0.96):: diff --git a/docs/releases/1.5-alpha-1.txt b/docs/releases/1.5-alpha-1.txt index df3df81d82..ac539e1dd0 100644 --- a/docs/releases/1.5-alpha-1.txt +++ b/docs/releases/1.5-alpha-1.txt @@ -550,8 +550,7 @@ Miscellaneous ``QuerySet`` as the empty value instead of an empty list. * :func:`~django.utils.http.int_to_base36` properly raises a - :exc:`~exceptions.TypeError` instead of :exc:`~exceptions.ValueError` for - non-integer inputs. + :exc:`TypeError` instead of :exc:`ValueError` for non-integer inputs. * The ``slugify`` template filter is now available as a standard python function at :func:`django.utils.text.slugify`. Similarly, ``remove_tags`` is diff --git a/docs/releases/1.5-beta-1.txt b/docs/releases/1.5-beta-1.txt index 8aa80ab6c1..89ca1a2b14 100644 --- a/docs/releases/1.5-beta-1.txt +++ b/docs/releases/1.5-beta-1.txt @@ -589,8 +589,7 @@ Miscellaneous ``QuerySet`` as the empty value instead of an empty list. * :func:`~django.utils.http.int_to_base36` properly raises a - :exc:`~exceptions.TypeError` instead of :exc:`~exceptions.ValueError` for - non-integer inputs. + :exc:`TypeError` instead of :exc:`ValueError` for non-integer inputs. * The ``slugify`` template filter is now available as a standard python function at :func:`django.utils.text.slugify`. Similarly, ``remove_tags`` is diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt index 4a5cf27565..5047a4b4ff 100644 --- a/docs/releases/1.5.txt +++ b/docs/releases/1.5.txt @@ -667,8 +667,7 @@ Miscellaneous ``QuerySet`` as the empty value instead of an empty list. * :func:`~django.utils.http.int_to_base36` properly raises a - :exc:`~exceptions.TypeError` instead of :exc:`~exceptions.ValueError` for - non-integer inputs. + :exc:`TypeError` instead of :exc:`ValueError` for non-integer inputs. * The ``slugify`` template filter is now available as a standard python function at :func:`django.utils.text.slugify`. Similarly, ``remove_tags`` is diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index 3d851a736c..171e599b8f 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -168,7 +168,7 @@ Minor features :setting:`CSRF_COOKIE_HTTPONLY`. * The :meth:`~django.test.TransactionTestCase.assertQuerysetEqual` now checks - for undefined order and raises :exc:`~exceptions.ValueError` if undefined + for undefined order and raises :exc:`ValueError` if undefined order is spotted. The order is seen as undefined if the given ``QuerySet`` isn't ordered and there are more than one ordered values to compare against. diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index 4223660751..0828585550 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -944,8 +944,8 @@ the app cache was a private API, obsolete methods and arguments will be removed through a standard deprecation path, with the exception of the following changes that take effect immediately: -* ``get_model`` raises :exc:`~exceptions.LookupError` instead of returning - ``None`` when no model is found. +* ``get_model`` raises :exc:`LookupError` instead of returning ``None`` when no + model is found. * The ``only_installed`` argument of ``get_model`` and ``get_models`` no longer exists, nor does the ``seed_cache`` argument of ``get_model``. @@ -1005,9 +1005,9 @@ pytz may be required ~~~~~~~~~~~~~~~~~~~~ If your project handles datetimes before 1970 or after 2037 and Django raises -a :exc:`~exceptions.ValueError` when encountering them, you will have to -install pytz_. You may be affected by this problem if you use Django's time -zone-related date formats or :mod:`django.contrib.syndication`. +a :exc:`ValueError` when encountering them, you will have to install pytz_. You +may be affected by this problem if you use Django's time zone-related date +formats or :mod:`django.contrib.syndication`. .. _pytz: https://pypi.python.org/pypi/pytz/ diff --git a/docs/topics/db/examples/many_to_many.txt b/docs/topics/db/examples/many_to_many.txt index cd38d57b45..79605ac158 100644 --- a/docs/topics/db/examples/many_to_many.txt +++ b/docs/topics/db/examples/many_to_many.txt @@ -78,7 +78,7 @@ Adding a second time is OK:: >>> a2.publications.add(p3) -Adding an object of the wrong type raises :exc:`~exceptions.TypeError`:: +Adding an object of the wrong type raises :exc:`TypeError`:: >>> a2.publications.add(a1) Traceback (most recent call last): diff --git a/docs/topics/i18n/timezones.txt b/docs/topics/i18n/timezones.txt index 839813a823..23b0f197a1 100644 --- a/docs/topics/i18n/timezones.txt +++ b/docs/topics/i18n/timezones.txt @@ -460,9 +460,8 @@ zone support. Fixtures generated with ``USE_TZ = False``, or before Django 1.4, use the "naive" format. If your project contains such fixtures, after you enable time -zone support, you'll see :exc:`~exceptions.RuntimeWarning`\ s when you load -them. To get rid of the warnings, you must convert your fixtures to the "aware" -format. +zone support, you'll see :exc:`RuntimeWarning`\ s when you load them. To get +rid of the warnings, you must convert your fixtures to the "aware" format. You can regenerate fixtures with :djadmin:`loaddata` then :djadmin:`dumpdata`. Or, if they're small enough, you can simply edit them to add the UTC offset diff --git a/docs/topics/python3.txt b/docs/topics/python3.txt index 15c07ccbf0..c10f2b42ab 100644 --- a/docs/topics/python3.txt +++ b/docs/topics/python3.txt @@ -78,8 +78,8 @@ wherever possible and avoid the ``b`` prefixes. String handling --------------- -Python 2's :func:`unicode` type was renamed :func:`str` in Python 3, -:func:`str` was renamed ``bytes()``, and :func:`basestring` disappeared. +Python 2's `unicode`_ type was renamed :class:`str` in Python 3, +``str()`` was renamed :func:`bytes`, and `basestring`_ disappeared. six_ provides :ref:`tools ` to deal with these changes. @@ -131,35 +131,34 @@ and ``SafeText`` respectively. For forwards compatibility, the new names work as of Django 1.4.2. -:meth:`~object.__str__` and :meth:`~object.__unicode__` methods ---------------------------------------------------------------- +:meth:`~object.__str__` and ` __unicode__()`_ methods +----------------------------------------------------- In Python 2, the object model specifies :meth:`~object.__str__` and -:meth:`~object.__unicode__` methods. If these methods exist, they must return +` __unicode__()`_ methods. If these methods exist, they must return ``str`` (bytes) and ``unicode`` (text) respectively. -The ``print`` statement and the :func:`str` built-in call +The ``print`` statement and the :class:`str` built-in call :meth:`~object.__str__` to determine the human-readable representation of an -object. The :func:`unicode` built-in calls :meth:`~object.__unicode__` if it +object. The ``unicode`` built-in calls ` __unicode__()`_ if it exists, and otherwise falls back to :meth:`~object.__str__` and decodes the result with the system encoding. Conversely, the :class:`~django.db.models.Model` base class automatically derives -:meth:`~object.__str__` from :meth:`~object.__unicode__` by encoding to UTF-8. +:meth:`~object.__str__` from ` __unicode__()`_ by encoding to UTF-8. In Python 3, there's simply :meth:`~object.__str__`, which must return ``str`` (text). -(It is also possible to define ``__bytes__()``, but Django application have -little use for that method, because they hardly ever deal with -``bytes``.) +(It is also possible to define :meth:`~object.__bytes__`, but Django application +have little use for that method, because they hardly ever deal with ``bytes``.) Django provides a simple way to define :meth:`~object.__str__` and -:meth:`~object.__unicode__` methods that work on Python 2 and 3: you must +` __unicode__()`_ methods that work on Python 2 and 3: you must define a :meth:`~object.__str__` method returning text and to apply the :func:`~django.utils.encoding.python_2_unicode_compatible` decorator. On Python 3, the decorator is a no-op. On Python 2, it defines appropriate -:meth:`~object.__unicode__` and :meth:`~object.__str__` methods (replacing the +` __unicode__()`_ and :meth:`~object.__str__` methods (replacing the original :meth:`~object.__str__` method in the process). Here's an example:: from __future__ import unicode_literals @@ -233,7 +232,7 @@ In order to enable the same behavior in Python 2, every module must import my_bytestring = b"This is a bytestring" If you need a byte string literal under Python 2 and a unicode string literal -under Python 3, use the :func:`str` builtin:: +under Python 3, use the :class:`str` builtin:: str('my string') @@ -402,3 +401,7 @@ extras. In addition to six' defaults moves, Django's version provides ``thread`` as ``_thread`` and ``dummy_thread`` as ``_dummy_thread``. + +.. _unicode: http://docs.python.org/2/library/functions.html#unicode +.. _ __unicode__(): https://docs.python.org/2/reference/datamodel.html#object.__unicode__ +.. _basestring: http://docs.python.org/2/library/functions.html#basestring diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index 62e4605ba1..883bfaf9cd 100644 --- a/docs/topics/testing/tools.txt +++ b/docs/topics/testing/tools.txt @@ -77,8 +77,7 @@ Note a few important things about how the test client works: The test client is not capable of retrieving Web pages that are not powered by your Django project. If you need to retrieve other Web pages, - use a Python standard library module such as :mod:`urllib` or - :mod:`urllib2`. + use a Python standard library module such as :mod:`urllib`. * To resolve URLs, the test client uses whatever URLconf is pointed-to by your :setting:`ROOT_URLCONF` setting. @@ -479,9 +478,9 @@ can access these properties as part of a test condition. .. attribute:: Client.cookies - A Python :class:`~Cookie.SimpleCookie` object, containing the current values - of all the client cookies. See the documentation of the :mod:`Cookie` module - for more. + A Python :class:`~http.cookies.SimpleCookie` object, containing the current + values of all the client cookies. See the documentation of the + :mod:`http.cookies` module for more. .. attribute:: Client.session @@ -1247,7 +1246,7 @@ your test suite. Asserts that execution of callable ``callable_obj`` raised the ``expected_exception`` exception and that such exception has an ``expected_message`` representation. Any other outcome is reported as a - failure. Similar to unittest's :meth:`~unittest.TestCase.assertRaisesRegexp` + failure. Similar to unittest's :meth:`~unittest.TestCase.assertRaisesRegex` with the difference that ``expected_message`` isn't a regular expression. .. method:: SimpleTestCase.assertFieldOutput(fieldclass, valid, invalid, field_args=None, field_kwargs=None, empty_value='')