From 067505ad19f088e8db1d8c788ceea388c7241bcd Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Sat, 29 Dec 2012 10:35:12 -0500 Subject: [PATCH] Fixed broken links, round 4. refs #19516 --- docs/howto/auth-remote-user.txt | 2 + docs/howto/custom-management-commands.txt | 9 ++++ docs/howto/custom-model-fields.txt | 20 ++++----- docs/internals/deprecation.txt | 30 +++++++------ docs/ref/contrib/auth.txt | 8 ++-- docs/ref/contrib/gis/testing.txt | 2 + docs/ref/contrib/messages.txt | 2 + docs/ref/signals.txt | 17 ++++---- docs/releases/1.0-porting-guide.txt | 13 +++--- docs/releases/1.1-beta-1.txt | 2 +- docs/releases/1.1.txt | 19 ++++----- docs/releases/1.2.4.txt | 2 +- docs/releases/1.3-alpha-1.txt | 34 +++++++-------- docs/releases/1.3-beta-1.txt | 9 ++-- docs/releases/1.3.txt | 51 ++++++++++------------- docs/releases/1.4-alpha-1.txt | 2 +- docs/releases/1.4-beta-1.txt | 2 +- docs/releases/1.4.txt | 2 +- docs/releases/1.5-alpha-1.txt | 9 ++-- docs/releases/1.5-beta-1.txt | 8 ++-- docs/releases/1.5.txt | 10 ++--- docs/topics/class-based-views/mixins.txt | 39 +++++++++-------- docs/topics/db/queries.txt | 4 ++ docs/topics/forms/formsets.txt | 2 +- docs/topics/forms/index.txt | 6 +-- docs/topics/forms/modelforms.txt | 2 + docs/topics/http/sessions.txt | 2 +- docs/topics/i18n/translation.txt | 2 + docs/topics/pagination.txt | 4 +- docs/topics/testing/overview.txt | 4 +- 30 files changed, 162 insertions(+), 156 deletions(-) diff --git a/docs/howto/auth-remote-user.txt b/docs/howto/auth-remote-user.txt index deab794cb11..d59bb25a853 100644 --- a/docs/howto/auth-remote-user.txt +++ b/docs/howto/auth-remote-user.txt @@ -27,6 +27,8 @@ use of the ``REMOTE_USER`` value using the ``RemoteUserMiddleware`` and Configuration ============= +.. class:: django.contrib.auth.middleware.RemoteUserMiddleware + First, you must add the :class:`django.contrib.auth.middleware.RemoteUserMiddleware` to the :setting:`MIDDLEWARE_CLASSES` setting **after** the diff --git a/docs/howto/custom-management-commands.txt b/docs/howto/custom-management-commands.txt index 12e8ec2494d..6a7f6442186 100644 --- a/docs/howto/custom-management-commands.txt +++ b/docs/howto/custom-management-commands.txt @@ -2,6 +2,8 @@ Writing custom django-admin commands ==================================== +.. module:: django.core.management + Applications can register their own actions with ``manage.py``. For example, you might want to add a ``manage.py`` action for a Django app that you're distributing. In this document, we will be building a custom ``closepoll`` @@ -261,6 +263,13 @@ the :meth:`~BaseCommand.handle` method must be implemented. The actual logic of the command. Subclasses must implement this method. +.. method:: BaseCommand.validate(app=None, display_num_errors=False) + + Validates the given app, raising :class:`CommandError` for any errors. + + If ``app`` is None, then all installed apps are validated. + + .. _ref-basecommand-subclasses: BaseCommand subclasses diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt index 1e9d5d8701c..dd57da5d458 100644 --- a/docs/howto/custom-model-fields.txt +++ b/docs/howto/custom-model-fields.txt @@ -153,8 +153,8 @@ class, from which everything is descended. Initializing your new field is a matter of separating out any arguments that are specific to your case from the common arguments and passing the latter to the -:meth:`~django.db.models.Field.__init__` method of -:class:`~django.db.models.Field` (or your parent class). +``__init__()`` method of :class:`~django.db.models.Field` (or your parent +class). In our example, we'll call our field ``HandField``. (It's a good idea to call your :class:`~django.db.models.Field` subclass ``Field``, so it's @@ -602,11 +602,11 @@ Returns the default form field to use when this field is displayed in a model. This method is called by the :class:`~django.forms.ModelForm` helper. All of the ``kwargs`` dictionary is passed directly to the form field's -:meth:`~django.forms.Field__init__` method. Normally, all you need to do is -set up a good default for the ``form_class`` argument and then delegate further -handling to the parent class. This might require you to write a custom form -field (and even a form widget). See the :doc:`forms documentation -` for information about this, and take a look at the code in +``__init__()`` method. Normally, all you need to do is set up a good default +for the ``form_class`` argument and then delegate further handling to the +parent class. This might require you to write a custom form field (and even a +form widget). See the :doc:`forms documentation ` for +information about this, and take a look at the code in :mod:`django.contrib.localflavor` for some examples of custom widgets. Continuing our ongoing example, we can write the :meth:`.formfield` method as:: @@ -668,7 +668,7 @@ Converting field data for serialization .. method:: Field.value_to_string(self, obj) This method is used by the serializers to convert the field into a string for -output. Calling :meth:`Field._get_val_from_obj(obj)` is the best way to get the +output. Calling ``Field._get_val_from_obj(obj)`` is the best way to get the value to serialize. For example, since our ``HandField`` uses strings for its data storage anyway, we can reuse some existing conversion code:: @@ -692,12 +692,12 @@ smoothly: 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 :meth:`__str__` or :meth:`__unicode__` method on the class you're +2. Put a ``__str__()`` or ``__unicode__()`` 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 :func:`~django.utils.encoding.force_text` on the value. (In our examples in this document, ``value`` would be a ``Hand`` instance, not a - ``HandField``). So if your :meth:`__unicode__` method automatically + ``HandField``). So if your ``__unicode__()`` method automatically converts to the string form of your Python object, you can save yourself a lot of work. diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 77f03ae2c75..74f544c220f 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -20,7 +20,7 @@ these changes. * The old imports for CSRF functionality (``django.contrib.csrf.*``), which moved to core in 1.2, will be removed. -* The :mod:`django.contrib.gis.db.backend` module will be removed in favor +* The ``django.contrib.gis.db.backend`` module will be removed in favor of the specific backends. * ``SMTPConnection`` will be removed in favor of a generic Email backend API. @@ -122,23 +122,23 @@ these changes. The :attr:`~django.test.client.Response.templates` attribute should be used instead. -* The :class:`~django.test.simple.DjangoTestRunner` will be removed. +* The ``django.test.simple.DjangoTestRunner`` will be removed. Instead use a unittest-native class. The features of the - :class:`django.test.simple.DjangoTestRunner` (including fail-fast and + ``django.test.simple.DjangoTestRunner`` (including fail-fast and Ctrl-C test termination) can currently be provided by the unittest-native - :class:`TextTestRunner`. + :class:`~unittest.TextTestRunner`. * The undocumented function - :func:`django.contrib.formtools.utils.security_hash` will be removed, - instead use :func:`django.contrib.formtools.utils.form_hmac` + ``django.contrib.formtools.utils.security_hash`` will be removed, + instead use ``django.contrib.formtools.utils.form_hmac`` * The function-based generic view modules will be removed in favor of their class-based equivalents, outlined :doc:`here `. -* The :class:`~django.core.servers.basehttp.AdminMediaHandler` will be +* The ``django.core.servers.basehttp.AdminMediaHandler`` will be removed. In its place use - :class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`. + ``django.contrib.staticfiles.handlers.StaticFilesHandler``. * The template tags library ``adminmedia`` and the template tag ``{% admin_media_prefix %}`` will be removed in favor of the generic static files @@ -150,8 +150,7 @@ these changes. an implied string. In 1.4, this behavior is provided by a version of the tag in the ``future`` template tag library. -* The :djadmin:`reset` and :djadmin:`sqlreset` management commands - will be removed. +* The ``reset`` and ``sqlreset`` management commands will be removed. * Authentication backends will need to support an inactive user being passed to all methods dealing with permissions. @@ -162,11 +161,11 @@ these changes. a :class:`~django.contrib.gis.geos.GEOSException` when called on a geometry with no SRID value. -* :class:`~django.http.CompatCookie` will be removed in favor of - :class:`~django.http.SimpleCookie`. +* ``django.http.CompatCookie`` will be removed in favor of + ``django.http.SimpleCookie``. -* :class:`django.core.context_processors.PermWrapper` and - :class:`django.core.context_processors.PermLookupDict` will be removed in +* ``django.core.context_processors.PermWrapper`` and + ``django.core.context_processors.PermLookupDict`` will be removed in favor of the corresponding :class:`django.contrib.auth.context_processors.PermWrapper` and :class:`django.contrib.auth.context_processors.PermLookupDict`, @@ -213,8 +212,7 @@ these changes. ``django.utils.itercompat.all`` and ``django.utils.itercompat.any`` will be removed. The Python builtin versions should be used instead. -* The :func:`~django.views.decorators.csrf.csrf_response_exempt` and - :func:`~django.views.decorators.csrf.csrf_view_exempt` decorators will +* The ``csrf_response_exempt`` and ``csrf_view_exempt`` decorators will be removed. Since 1.4 ``csrf_response_exempt`` has been a no-op (it returns the same function), and ``csrf_view_exempt`` has been a synonym for ``django.views.decorators.csrf.csrf_exempt``, which should diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index 41f218b0a44..74a69c1f7d9 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -349,7 +349,7 @@ Login and logout signals The auth framework uses two :doc:`signals ` that can be used for notification when a user logs in or out. -.. function:: django.contrib.auth.signals.user_logged_in +.. function:: user_logged_in Sent when a user logs in successfully. @@ -364,7 +364,7 @@ for notification when a user logs in or out. ``user`` The user instance that just logged in. -.. function:: django.contrib.auth.signals.user_logged_out +.. function:: user_logged_out Sent when the logout method is called. @@ -379,9 +379,9 @@ for notification when a user logs in or out. The user instance that just logged out or ``None`` if the user was not authenticated. -.. function:: django.contrib.auth.signals.user_login_failed +.. function:: user_login_failed -.. versionadded:: 1.5 + .. versionadded:: 1.5 Sent when the user failed to login successfully diff --git a/docs/ref/contrib/gis/testing.txt b/docs/ref/contrib/gis/testing.txt index 86979f0308a..2a6dcef46fb 100644 --- a/docs/ref/contrib/gis/testing.txt +++ b/docs/ref/contrib/gis/testing.txt @@ -140,6 +140,8 @@ with the rest of :ref:`Django's unit tests `. Run only GeoDjango tests ------------------------ +.. class:: django.contrib.gis.tests.GeoDjangoTestSuiteRunner + To run *only* the tests for GeoDjango, the :setting:`TEST_RUNNER` setting must be changed to use the :class:`~django.contrib.gis.tests.GeoDjangoTestSuiteRunner`:: diff --git a/docs/ref/contrib/messages.txt b/docs/ref/contrib/messages.txt index 4fa733edb56..661d7f2103e 100644 --- a/docs/ref/contrib/messages.txt +++ b/docs/ref/contrib/messages.txt @@ -149,6 +149,8 @@ tags for the levels you wish to override:: Using messages in views and templates ===================================== +.. function:: add_message(request, level, message, extra_tags='', fail_silently=False) + Adding a message ---------------- diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index 0671d80b7c6..c31c90f4e8c 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -27,9 +27,8 @@ module system. .. warning:: Many of these signals are sent by various model methods like - :meth:`~django.db.models.Model.__init__` or - :meth:`~django.db.models.Model.save` that you can overwrite in your own - code. + ``__init__()`` or :meth:`~django.db.models.Model.save` that you can + override in your own code. If you override these methods on your model, you must call the parent class' methods for this signals to be sent. @@ -47,7 +46,7 @@ pre_init .. ^^^^^^^ this :module: hack keeps Sphinx from prepending the module. Whenever you instantiate a Django model, this signal is sent at the beginning -of the model's :meth:`~django.db.models.Model.__init__` method. +of the model's ``__init__()`` method. Arguments sent with this signal: @@ -55,12 +54,10 @@ Arguments sent with this signal: The model class that just had an instance created. ``args`` - A list of positional arguments passed to - :meth:`~django.db.models.Model.__init__`: + A list of positional arguments passed to ``__init__()``: ``kwargs`` - A dictionary of keyword arguments passed to - :meth:`~django.db.models.Model.__init__`:. + A dictionary of keyword arguments passed to ``__init__()``: For example, the :doc:`tutorial ` has this line:: @@ -74,7 +71,7 @@ Argument Value ``sender`` ``Poll`` (the class itself) ``args`` ``[]`` (an empty list because there were no positional - arguments passed to ``__init__``.) + arguments passed to ``__init__()``.) ``kwargs`` ``{'question': "What's up?", 'pub_date': datetime.now()}`` ========== =============================================================== @@ -85,7 +82,7 @@ post_init .. data:: django.db.models.signals.post_init :module: -Like pre_init, but this one is sent when the :meth:`~django.db.models.Model.__init__`: method finishes. +Like pre_init, but this one is sent when the ``__init__()`` method finishes. Arguments sent with this signal: diff --git a/docs/releases/1.0-porting-guide.txt b/docs/releases/1.0-porting-guide.txt index ae73baa072a..644350525ca 100644 --- a/docs/releases/1.0-porting-guide.txt +++ b/docs/releases/1.0-porting-guide.txt @@ -277,8 +277,9 @@ Handle uploaded files using the new API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Replace use of uploaded files -- that is, entries in ``request.FILES`` -- as -simple dictionaries with the new :class:`~django.core.files.UploadedFile`. The -old dictionary syntax no longer works. +simple dictionaries with the new +:class:`~django.core.files.uploadedfile.UploadedFile`. The old dictionary +syntax no longer works. Thus, in a view like:: @@ -410,7 +411,7 @@ U.S. local flavor ~~~~~~~~~~~~~~~~~ ``django.contrib.localflavor.usa`` has been renamed to -:mod:`django.contrib.localflavor.us`. This change was made to match the naming +``django.contrib.localflavor.us``. This change was made to match the naming scheme of other local flavors. To migrate your code, all you need to do is change the imports. @@ -642,8 +643,8 @@ The generic relation classes -- ``GenericForeignKey`` and ``GenericRelation`` Testing ------- -:meth:`django.test.Client.login` has changed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:meth:`django.test.client.Client.login` has changed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Old (0.96):: @@ -721,7 +722,7 @@ To update your code: 1. Use :class:`django.utils.datastructures.SortedDict` wherever you were using ``django.newforms.forms.SortedDictFromList``. -2. Because :meth:`django.utils.datastructures.SortedDict.copy` doesn't +2. Because ``django.utils.datastructures.SortedDict.copy`` doesn't return a deepcopy as ``SortedDictFromList.copy()`` did, you will need to update your code if you were relying on a deepcopy. Do this by using ``copy.deepcopy`` directly. diff --git a/docs/releases/1.1-beta-1.txt b/docs/releases/1.1-beta-1.txt index 1555a9464ae..88d8ce5f35c 100644 --- a/docs/releases/1.1-beta-1.txt +++ b/docs/releases/1.1-beta-1.txt @@ -36,7 +36,7 @@ A number of features have been added to Django's model layer: You can now control whether or not Django creates database tables for a model using the :attr:`~Options.managed` model option. This defaults to ``True``, meaning that Django will create the appropriate database tables in -:djadmin:`syncdb` and remove them as part of :djadmin:`reset` command. That +:djadmin:`syncdb` and remove them as part of ``reset`` command. That is, Django *manages* the database table's lifecycle. If you set this to ``False``, however, no database table creating or deletion diff --git a/docs/releases/1.1.txt b/docs/releases/1.1.txt index 68fc6249246..ca8e1fff2a2 100644 --- a/docs/releases/1.1.txt +++ b/docs/releases/1.1.txt @@ -37,7 +37,7 @@ If you are using a 32-bit platform, you're off the hook; you'll observe no differences as a result of this change. However, **users on 64-bit platforms may experience some problems** using the -:djadmin:`reset` management command. Prior to this change, 64-bit platforms +``reset`` management command. Prior to this change, 64-bit platforms would generate a 64-bit, 16 character digest in the constraint name; for example:: @@ -48,14 +48,14 @@ Following this change, all platforms, regardless of word size, will generate a ALTER TABLE myapp_sometable ADD CONSTRAINT object_id_refs_id_32091d1e FOREIGN KEY ... -As a result of this change, you will not be able to use the :djadmin:`reset` +As a result of this change, you will not be able to use the ``reset`` management command on any table made by a 64-bit machine. This is because the the new generated name will not match the historically generated name; as a result, the SQL constructed by the reset command will be invalid. If you need to reset an application that was created with 64-bit constraints, you will need to manually drop the old constraint prior to invoking -:djadmin:`reset`. +``reset``. Test cases are now run in a transaction --------------------------------------- @@ -120,9 +120,8 @@ has been saved. Changes to how model formsets are saved --------------------------------------- -.. currentmodule:: django.forms.models - -In Django 1.1, :class:`BaseModelFormSet` now calls :meth:`ModelForm.save()`. +In Django 1.1, :class:`~django.forms.models.BaseModelFormSet` now calls +``ModelForm.save()``. This is backwards-incompatible if you were modifying ``self.initial`` in a model formset's ``__init__``, or if you relied on the internal ``_total_form_count`` @@ -146,7 +145,7 @@ Permanent redirects and the ``redirect_to()`` generic view ---------------------------------------------------------- Django 1.1 adds a ``permanent`` argument to the -:func:`django.views.generic.simple.redirect_to()` view. This is technically +``django.views.generic.simple.redirect_to()`` view. This is technically backwards-incompatible if you were using the ``redirect_to`` view with a format-string key called 'permanent', which is highly unlikely. @@ -211,8 +210,8 @@ Query expressions Queries can now refer to a another field on the query and can traverse relationships to refer to fields on related models. This is implemented in the -new :class:`F` object; for full details, including examples, consult the -:ref:`documentation for F expressions `. +new :class:`~django.db.models.F` object; for full details, including examples, +consult the :ref:`documentation for F expressions `. Model improvements ------------------ @@ -225,7 +224,7 @@ A number of features have been added to Django's model layer: You can now control whether or not Django manages the life-cycle of the database tables for a model using the :attr:`~Options.managed` model option. This defaults to ``True``, meaning that Django will create the appropriate database -tables in :djadmin:`syncdb` and remove them as part of the :djadmin:`reset` +tables in :djadmin:`syncdb` and remove them as part of the ``reset`` command. That is, Django *manages* the database table's lifecycle. If you set this to ``False``, however, no database table creating or deletion diff --git a/docs/releases/1.2.4.txt b/docs/releases/1.2.4.txt index cd4ab76f555..b74ea9aef2f 100644 --- a/docs/releases/1.2.4.txt +++ b/docs/releases/1.2.4.txt @@ -76,7 +76,7 @@ GeoDjango ========= The function-based :setting:`TEST_RUNNER` previously used to execute -the GeoDjango test suite, :func:`django.contrib.gis.tests.run_gis_tests`, +the GeoDjango test suite, ``django.contrib.gis.tests.run_gis_tests``, was finally deprecated in favor of a class-based test runner, :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`, added in this release. diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt index bb7f2dbb732..e2c52a7264d 100644 --- a/docs/releases/1.3-alpha-1.txt +++ b/docs/releases/1.3-alpha-1.txt @@ -311,37 +311,35 @@ As a result of the introduction of class-based generic views, the function-based generic views provided by Django have been deprecated. The following modules and the views they contain have been deprecated: -* :mod:`django.views.generic.create_update` -* :mod:`django.views.generic.date_based` -* :mod:`django.views.generic.list_detail` -* :mod:`django.views.generic.simple` +* ``django.views.generic.create_update`` +* ``django.views.generic.date_based`` +* ``django.views.generic.list_detail`` +* ``django.views.generic.simple`` Test client response ``template`` attribute ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Django's :ref:`test client ` returns :class:`~django.test.client.Response` objects annotated with extra testing -information. In Django versions prior to 1.3, this included a -:attr:`~django.test.client.Response.template` attribute containing information -about templates rendered in generating the response: either None, a single -:class:`~django.template.Template` object, or a list of -:class:`~django.template.Template` objects. This inconsistency in return values -(sometimes a list, sometimes not) made the attribute difficult to work with. +information. In Django versions prior to 1.3, this included a ``template`` +attribute containing information about templates rendered in generating the +response: either None, a single :class:`~django.template.Template` object, or a +list of :class:`~django.template.Template` objects. This inconsistency in +return values (sometimes a list, sometimes not) made the attribute difficult +to work with. -In Django 1.3 the :attr:`~django.test.client.Response.template` attribute is -deprecated in favor of a new :attr:`~django.test.client.Response.templates` -attribute, which is always a list, even if it has only a single element or no -elements. +In Django 1.3 the ``template`` attribute is deprecated in favor of a new +:attr:`~django.test.client.Response.templates` attribute, which is always a +list, even if it has only a single element or no elements. ``DjangoTestRunner`` ~~~~~~~~~~~~~~~~~~~~ As a result of the introduction of support for unittest2, the features -of :class:`django.test.simple.DjangoTestRunner` (including fail-fast +of ``django.test.simple.DjangoTestRunner`` (including fail-fast and Ctrl-C test termination) have been made redundant. In view of this -redundancy, :class:`~django.test.simple.DjangoTestRunner` has been -turned into an empty placeholder class, and will be removed entirely -in Django 1.5. +redundancy, ``DjangoTestRunner`` has been turned into an empty placeholder +class, and will be removed entirely in Django 1.5. The Django 1.3 roadmap ====================== diff --git a/docs/releases/1.3-beta-1.txt b/docs/releases/1.3-beta-1.txt index 2729c7f2bab..d064063fced 100644 --- a/docs/releases/1.3-beta-1.txt +++ b/docs/releases/1.3-beta-1.txt @@ -142,10 +142,9 @@ Changes to ``USStateField`` The :mod:`django.contrib.localflavor` application contains collections of code relevant to specific countries or cultures. One such is -:class:`~django.contrib.localflavor.us.models.USStateField`, which -provides a field for storing the two-letter postal abbreviation of a -U.S. state. This field has consistently caused problems, however, -because it is often used to store the state portion of a U.S postal +``USStateField``, which provides a field for storing the two-letter postal +abbreviation of a U.S. state. This field has consistently caused problems, +however, because it is often used to store the state portion of a U.S postal address, but not all "states" recognized by the U.S Postal Service are actually states of the U.S. or even U.S. territory. Several compromises over the list of choices resulted in some users feeling @@ -161,7 +160,7 @@ as a pair of changes: choices, plus the U.S. Armed Forces postal codes. * A new model field, - :class:`django.contrib.localflavor.us.models.USPostalCodeField`, has + ``django.contrib.localflavor.us.models.USPostalCodeField``, has been added which draws its choices from a list of all postal abbreviations recognized by the U.S Postal Service. This includes all abbreviations recognized by `USStateField`, plus three diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index d6ef11d1131..6a056532b91 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -700,40 +700,35 @@ As a result of the introduction of class-based generic views, the function-based generic views provided by Django have been deprecated. The following modules and the views they contain have been deprecated: -* :mod:`django.views.generic.create_update` - -* :mod:`django.views.generic.date_based` - -* :mod:`django.views.generic.list_detail` - -* :mod:`django.views.generic.simple` +* ``django.views.generic.create_update`` +* ``django.views.generic.date_based`` +* ``django.views.generic.list_detail`` +* ``django.views.generic.simple`` Test client response ``template`` attribute ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Django's :ref:`test client ` returns :class:`~django.test.client.Response` objects annotated with extra testing -information. In Django versions prior to 1.3, this included a -:attr:`~django.test.client.Response.template` attribute containing information -about templates rendered in generating the response: either None, a single -:class:`~django.template.Template` object, or a list of -:class:`~django.template.Template` objects. This inconsistency in return values -(sometimes a list, sometimes not) made the attribute difficult to work with. +information. In Django versions prior to 1.3, this included a ``template`` +attribute containing information about templates rendered in generating the +response: either None, a single :class:`~django.template.Template` object, or a +list of :class:`~django.template.Template` objects. This inconsistency in +return values (sometimes a list, sometimes not) made the attribute difficult +to work with. -In Django 1.3 the :attr:`~django.test.client.Response.template` attribute is -deprecated in favor of a new :attr:`~django.test.client.Response.templates` -attribute, which is always a list, even if it has only a single element or no -elements. +In Django 1.3 the ``template`` attribute is deprecated in favor of a new +:attr:`~django.test.client.Response.templates` attribute, which is always a +list, even if it has only a single element or no elements. ``DjangoTestRunner`` ~~~~~~~~~~~~~~~~~~~~ As a result of the introduction of support for unittest2, the features -of :class:`django.test.simple.DjangoTestRunner` (including fail-fast +of ``django.test.simple.DjangoTestRunner`` (including fail-fast and Ctrl-C test termination) have been made redundant. In view of this -redundancy, :class:`~django.test.simple.DjangoTestRunner` has been -turned into an empty placeholder class, and will be removed entirely -in Django 1.5. +redundancy, ``DjangoTestRunner`` has been turned into an empty placeholder +class, and will be removed entirely in Django 1.5. Changes to :ttag:`url` and :ttag:`ssi` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -805,9 +800,8 @@ GeoDjango ~~~~~~~~~ * The function-based :setting:`TEST_RUNNER` previously used to execute - the GeoDjango test suite, - :func:`django.contrib.gis.tests.run_gis_tests`, was deprecated for - the class-based runner, + the GeoDjango test suite, ``django.contrib.gis.tests.run_gis_tests``, was + deprecated for the class-based runner, :class:`django.contrib.gis.tests.GeoDjangoTestSuiteRunner`. * Previously, calling @@ -886,11 +880,10 @@ identical to their old versions; only the module location has changed. Removal of ``XMLField`` ~~~~~~~~~~~~~~~~~~~~~~~ -When Django was first released, Django included an -:class:`~django.db.models.XMLField` that performed automatic XML validation -for any field input. However, this validation function hasn't been -performed since the introduction of ``newforms``, prior to the 1.0 release. -As a result, ``XMLField`` as currently implemented is functionally +When Django was first released, Django included an ``XMLField`` that performed +automatic XML validation for any field input. However, this validation function +hasn't been performed since the introduction of ``newforms``, prior to the 1.0 +release. As a result, ``XMLField`` as currently implemented is functionally indistinguishable from a simple :class:`~django.db.models.TextField`. For this reason, Django 1.3 has fast-tracked the deprecation of diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt index 3c6f7e9b271..fc19e903844 100644 --- a/docs/releases/1.4-alpha-1.txt +++ b/docs/releases/1.4-alpha-1.txt @@ -503,7 +503,7 @@ Django 1.4 also includes several smaller improvements worth noting: * In the documentation, a helpful :doc:`security overview ` page. -* The :func:`django.contrib.auth.models.check_password` function has been moved +* The ``django.contrib.auth.models.check_password`` function has been moved to the :mod:`django.contrib.auth.utils` module. Importing it from the old location will still work, but you should update your imports. diff --git a/docs/releases/1.4-beta-1.txt b/docs/releases/1.4-beta-1.txt index 2a1041bcd0c..2c84d21b8d3 100644 --- a/docs/releases/1.4-beta-1.txt +++ b/docs/releases/1.4-beta-1.txt @@ -563,7 +563,7 @@ Django 1.4 also includes several smaller improvements worth noting: * In the documentation, a helpful :doc:`security overview ` page. -* The :func:`django.contrib.auth.models.check_password` function has been moved +* The ``django.contrib.auth.models.check_password`` function has been moved to the :mod:`django.contrib.auth.utils` module. Importing it from the old location will still work, but you should update your imports. diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index 746ed589458..d700ba8b89e 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -585,7 +585,7 @@ Django 1.4 also includes several smaller improvements worth noting: * In the documentation, a helpful :doc:`security overview ` page. -* The :func:`django.contrib.auth.models.check_password` function has been moved +* The ``django.contrib.auth.models.check_password`` function has been moved to the :mod:`django.contrib.auth.hashers` module. Importing it from the old location will still work, but you should update your imports. diff --git a/docs/releases/1.5-alpha-1.txt b/docs/releases/1.5-alpha-1.txt index b167bb1879e..c2ad691a764 100644 --- a/docs/releases/1.5-alpha-1.txt +++ b/docs/releases/1.5-alpha-1.txt @@ -423,7 +423,7 @@ More information on these incompatibilities is available in `ticket #18023`_. The net result is that, if you have installed :mod:`simplejson` and your code uses Django's serialization internals directly -- for instance -:class:`django.core.serializers.json.DjangoJSONEncoder`, the switch from +``django.core.serializers.json.DjangoJSONEncoder``, the switch from :mod:`simplejson` to :mod:`json` could break your code. (In general, changes to internals aren't documented; we're making an exception here.) @@ -449,8 +449,8 @@ When using :doc:`object pagination `, the ``previous_page_number()`` and ``next_page_number()`` methods of the :class:`~django.core.paginator.Page` object did not check if the returned number was inside the existing page range. -It does check it now and raises an :exc:`InvalidPage` exception when the number -is either too low or too high. +It does check it now and raises an :exc:`~django.core.paginator.InvalidPage` +exception when the number is either too low or too high. Behavior of autocommit database option on PostgreSQL changed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -619,10 +619,9 @@ Define a ``__str__`` method and apply the ``django.utils.itercompat.product`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :func:`~django.utils.itercompat.product` function has been deprecated. Use +The ``django.utils.itercompat.product`` function has been deprecated. Use the built-in :func:`itertools.product` instead. - ``django.utils.markup`` ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/1.5-beta-1.txt b/docs/releases/1.5-beta-1.txt index 7208d9657c9..4dbe77f8063 100644 --- a/docs/releases/1.5-beta-1.txt +++ b/docs/releases/1.5-beta-1.txt @@ -448,7 +448,7 @@ More information on these incompatibilities is available in `ticket #18023`_. The net result is that, if you have installed :mod:`simplejson` and your code uses Django's serialization internals directly -- for instance -:class:`django.core.serializers.json.DjangoJSONEncoder`, the switch from +``django.core.serializers.json.DjangoJSONEncoder``, the switch from :mod:`simplejson` to :mod:`json` could break your code. (In general, changes to internals aren't documented; we're making an exception here.) @@ -474,8 +474,8 @@ When using :doc:`object pagination `, the ``previous_page_number()`` and ``next_page_number()`` methods of the :class:`~django.core.paginator.Page` object did not check if the returned number was inside the existing page range. -It does check it now and raises an :exc:`InvalidPage` exception when the number -is either too low or too high. +It does check it now and raises an :exc:`~django.core.paginator.InvalidPage` +exception when the number is either too low or too high. Behavior of autocommit database option on PostgreSQL changed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -672,7 +672,7 @@ Define a ``__str__`` method and apply the ``django.utils.itercompat.product`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :func:`~django.utils.itercompat.product` function has been deprecated. Use +The ``django.utils.itercompat.product`` function has been deprecated. Use the built-in :func:`itertools.product` instead. ``django.utils.markup`` diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt index b0f0bee2939..a449f4ab12f 100644 --- a/docs/releases/1.5.txt +++ b/docs/releases/1.5.txt @@ -100,7 +100,7 @@ Some features of Django aren't available because they depend on third-party software that hasn't been ported to Python 3 yet, including: - the MySQL database backend (depends on MySQLdb) -- :class:`~django.db.models.fields.ImageField` (depends on PIL) +- :class:`~django.db.models.ImageField` (depends on PIL) - :class:`~django.test.LiveServerTestCase` (depends on Selenium WebDriver) Further, Django's more than a web framework; it's an ecosystem of pluggable @@ -469,7 +469,7 @@ More information on these incompatibilities is available in `ticket #18023`_. The net result is that, if you have installed :mod:`simplejson` and your code uses Django's serialization internals directly -- for instance -:class:`django.core.serializers.json.DjangoJSONEncoder`, the switch from +``django.core.serializers.json.DjangoJSONEncoder``, the switch from :mod:`simplejson` to :mod:`json` could break your code. (In general, changes to internals aren't documented; we're making an exception here.) @@ -495,8 +495,8 @@ When using :doc:`object pagination `, the ``previous_page_number()`` and ``next_page_number()`` methods of the :class:`~django.core.paginator.Page` object did not check if the returned number was inside the existing page range. -It does check it now and raises an :exc:`InvalidPage` exception when the number -is either too low or too high. +It does check it now and raises an :exc:`~django.core.paginator.InvalidPage` +exception when the number is either too low or too high. Behavior of autocommit database option on PostgreSQL changed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -714,7 +714,7 @@ Define a ``__str__`` method and apply the ``django.utils.itercompat.product`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :func:`~django.utils.itercompat.product` function has been deprecated. Use +The ``django.utils.itercompat.product`` function has been deprecated. Use the built-in :func:`itertools.product` instead. ``cleanup`` management command diff --git a/docs/topics/class-based-views/mixins.txt b/docs/topics/class-based-views/mixins.txt index f349c236266..923b877cc51 100644 --- a/docs/topics/class-based-views/mixins.txt +++ b/docs/topics/class-based-views/mixins.txt @@ -93,8 +93,8 @@ DetailView: working with a single Django object To show the detail of an object, we basically need to do two things: we need to look up the object and then we need to make a -:class:`TemplateResponse` with a suitable template, and that object as -context. +:class:`~django.template.response.TemplateResponse` with a suitable template, +and that object as context. To get the object, :class:`~django.views.generic.detail.DetailView` relies on :class:`~django.views.generic.detail.SingleObjectMixin`, @@ -111,15 +111,14 @@ attribute if that's provided). :class:`SingleObjectMixin` also overrides which is used across all Django's built in class-based views to supply context data for template renders. -To then make a :class:`TemplateResponse`, :class:`DetailView` uses +To then make a :class:`~django.template.response.TemplateResponse`, +:class:`DetailView` uses :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`, -which extends -:class:`~django.views.generic.base.TemplateResponseMixin`, overriding -:meth:`get_template_names()` as discussed above. It actually provides -a fairly sophisticated set of options, but the main one that most -people are going to use is -``/_detail.html``. The ``_detail`` part can be -changed by setting +which extends :class:`~django.views.generic.base.TemplateResponseMixin`, +overriding :meth:`get_template_names()` as discussed above. It actually +provides a fairly sophisticated set of options, but the main one that most +people are going to use is ``/_detail.html``. The +``_detail`` part can be changed by setting :attr:`~django.views.generic.detail.SingleObjectTemplateResponseMixin.template_name_suffix` on a subclass to something else. (For instance, the :doc:`generic edit views` use ``_form`` for create and update views, and @@ -265,7 +264,7 @@ We can hook this into our URLs easily enough:: Note the ``pk`` named group, which :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` uses -to look up the :class:`Author` instance. You could also use a slug, or +to look up the ``Author`` instance. You could also use a slug, or any of the other features of :class:`SingleObjectMixin`. Using SingleObjectMixin with ListView @@ -299,7 +298,7 @@ object. In order to do this, we need to have two different querysets: will add in the suitable ``page_obj`` and ``paginator`` for us providing we remember to call ``super()``. -Now we can write a new :class:`PublisherDetail`:: +Now we can write a new ``PublisherDetail``:: from django.views.generic import ListView from django.views.generic.detail import SingleObjectMixin @@ -403,7 +402,7 @@ At this point it's natural to reach for a :class:`Form` to encapsulate the information sent from the user's browser to Django. Say also that we're heavily invested in `REST`_, so we want to use the same URL for displaying the author as for capturing the message from the -user. Let's rewrite our :class:`AuthorDetailView` to do that. +user. Let's rewrite our ``AuthorDetailView`` to do that. .. _REST: http://en.wikipedia.org/wiki/Representational_state_transfer @@ -423,7 +422,7 @@ code so that on ``POST`` the form gets called appropriately. .. highlightlang:: python -Our new :class:`AuthorDetail` looks like this:: +Our new ``AuthorDetail`` looks like this:: # CAUTION: you almost certainly do not want to do this. # It is provided as part of a discussion of problems you can @@ -507,10 +506,10 @@ clear division here: ``GET`` requests should get the data), and ``POST`` requests should get the :class:`FormView`. Let's set up those views first. -The :class:`AuthorDisplay` view is almost the same as :ref:`when we +The ``AuthorDisplay`` view is almost the same as :ref:`when we first introduced AuthorDetail`; we have to write our own :meth:`get_context_data()` to make the -:class:`AuthorInterestForm` available to the template. We'll skip the +``AuthorInterestForm`` available to the template. We'll skip the :meth:`get_object()` override from before for clarity. .. code-block:: python @@ -533,11 +532,11 @@ write our own :meth:`get_context_data()` to make the context.update(kwargs) return super(AuthorDisplay, self).get_context_data(**context) -Then the :class:`AuthorInterest` is a simple :class:`FormView`, but we +Then the ``AuthorInterest`` is a simple :class:`FormView`, but we have to bring in :class:`SingleObjectMixin` so we can find the author we're talking about, and we have to remember to set :attr:`template_name` to ensure that form errors will render the same -template as :class:`AuthorDisplay` is using on ``GET``. +template as ``AuthorDisplay`` is using on ``GET``. .. code-block:: python @@ -568,14 +567,14 @@ template as :class:`AuthorDisplay` is using on ``GET``. # record the interest using the message in form.cleaned_data return super(AuthorInterest, self).form_valid(form) -Finally we bring this together in a new :class:`AuthorDetail` view. We +Finally we bring this together in a new ``AuthorDetail`` view. We already know that calling :meth:`as_view()` on a class-based view gives us something that behaves exactly like a function based view, so we can do that at the point we choose between the two subviews. You can of course pass through keyword arguments to :meth:`as_view()` in the same way you would in your URLconf, such as if you wanted the -:class:`AuthorInterest` behaviour to also appear at another URL but +``AuthorInterest`` behaviour to also appear at another URL but using a different template. .. code-block:: python diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index a869b6afadb..046c23bdcdf 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -601,6 +601,8 @@ relation may end up filtering on different linked objects. Filters can reference fields on the model ----------------------------------------- +.. class:: F + In the examples given so far, we have constructed filters that compare the value of a model field with a constant. But what if you want to compare the value of a model field with another field on the same model? @@ -755,6 +757,8 @@ To avoid this problem, simply save the Complex lookups with Q objects ============================== +.. class:: Q + Keyword argument queries -- in :meth:`~django.db.models.query.QuerySet.filter`, etc. -- are "AND"ed together. If you need to execute more complex queries (for example, queries with ``OR`` statements), you can use ``Q`` objects. diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt index 7c1771b758f..76849c8e239 100644 --- a/docs/topics/forms/formsets.txt +++ b/docs/topics/forms/formsets.txt @@ -37,7 +37,7 @@ display two blank forms:: Iterating over the ``formset`` will render the forms in the order they were created. You can change this order by providing an alternate implementation for -the :meth:`__iter__()` method. +the ``__iter__()`` method. Formsets can also be indexed into, which returns the corresponding form. If you override ``__iter__``, you will need to also override ``__getitem__`` to have diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 4693de6c7eb..9b5794a8f2d 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -300,9 +300,9 @@ loop::

-Within this loop, ``{{ field }}`` is an instance of :class:`BoundField`. -``BoundField`` also has the following attributes, which can be useful in your -templates: +Within this loop, ``{{ field }}`` is an instance of +:class:`~django.forms.BoundField`. ``BoundField`` also has the following +attributes, which can be useful in your templates: ``{{ field.label }}`` The label of the field, e.g. ``Email address``. diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index 233346db0d5..67d539447cf 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -549,6 +549,8 @@ model's ``clean()`` hook. Model formsets ============== +.. class:: models.BaseModelFormSet + Like :doc:`regular formsets `, Django provides a couple of enhanced formset classes that make it easy to work with Django models. Let's reuse the ``Author`` model from above:: diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index baf8aa5cb5b..dac146bf3e5 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -264,7 +264,7 @@ You can edit it multiple times. - ``modification``: last modification of the session, as a :class:`~datetime.datetime` object. Defaults to the current time. - ``expiry``: expiry information for the session, as a - :class:`~datetime.datetime` object, an :class:`int` (in seconds), or + :class:`~datetime.datetime` object, an :func:`int` (in seconds), or ``None``. Defaults to the value stored in the session by :meth:`set_expiry`, if there is one, or ``None``. diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index 0b13ea18be6..0b37c25f18a 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -1248,6 +1248,8 @@ The ``set_language`` redirect view .. highlightlang:: python +.. currentmodule:: django.views.i18n + .. function:: set_language(request) As a convenience, Django comes with a view, :func:`django.views.i18n.set_language`, diff --git a/docs/topics/pagination.txt b/docs/topics/pagination.txt index 6c3ab77b112..b504b2a373a 100644 --- a/docs/topics/pagination.txt +++ b/docs/topics/pagination.txt @@ -205,8 +205,8 @@ Attributes .. exception:: InvalidPage - A base class for exceptions raised when a paginator is passed an invalid - page number. + A base class for exceptions raised when a paginator is passed an invalid + page number. The :meth:`Paginator.page` method raises an exception if the requested page is invalid (i.e., not an integer) or contains no objects. Generally, it's enough diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index 0627bd40d7f..0548f664810 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -853,7 +853,7 @@ Normal Python unit test classes extend a base class of Hierarchy of Django unit testing classes Regardless of the version of Python you're using, if you've installed -:mod:`unittest2`, :mod:`django.utils.unittest` will point to that library. +``unittest2``, :mod:`django.utils.unittest` will point to that library. SimpleTestCase ~~~~~~~~~~~~~~ @@ -1376,7 +1376,7 @@ in the ``with`` block and reset its value to the previous state afterwards. .. function:: override_settings In case you want to override a setting for just one test method or even the -whole :class:`TestCase` class, Django provides the +whole :class:`~django.test.TestCase` class, Django provides the :func:`~django.test.utils.override_settings` decorator (see :pep:`318`). It's used like this::