From 6f8e23d1c10c7ce32cea82b65ad2af640015f147 Mon Sep 17 00:00:00 2001 From: David Smith Date: Tue, 27 May 2025 17:37:22 +0100 Subject: [PATCH] Refs #36485 -- Removed unnecessary parentheses in :meth: and :func: roles in docs. --- docs/howto/custom-file-storage.txt | 2 +- docs/howto/custom-template-tags.txt | 2 +- docs/howto/writing-migrations.txt | 4 +- docs/internals/deprecation.txt | 2 +- docs/intro/tutorial01.txt | 2 +- docs/intro/tutorial05.txt | 4 +- docs/ref/applications.txt | 26 +++---- docs/ref/class-based-views/base.txt | 24 +++--- .../ref/class-based-views/generic-display.txt | 36 ++++----- docs/ref/class-based-views/index.txt | 4 +- docs/ref/class-based-views/mixins-simple.txt | 2 +- .../mixins-single-object.txt | 2 +- docs/ref/contrib/admin/actions.txt | 6 +- docs/ref/contrib/admin/index.txt | 10 +-- docs/ref/contrib/auth.txt | 20 ++--- docs/ref/contrib/contenttypes.txt | 2 +- docs/ref/contrib/postgres/functions.txt | 2 +- docs/ref/contrib/sitemaps.txt | 30 +++---- docs/ref/contrib/sites.txt | 2 +- docs/ref/contrib/syndication.txt | 2 +- docs/ref/django-admin.txt | 8 +- docs/ref/exceptions.txt | 8 +- docs/ref/files/file.txt | 2 +- docs/ref/files/storage.txt | 4 +- docs/ref/forms/api.txt | 14 ++-- docs/ref/forms/fields.txt | 4 +- docs/ref/forms/validation.txt | 8 +- docs/ref/forms/widgets.txt | 2 +- docs/ref/middleware.txt | 6 +- docs/ref/models/expressions.txt | 12 +-- docs/ref/models/fields.txt | 12 +-- docs/ref/models/instances.txt | 36 ++++----- docs/ref/models/options.txt | 4 +- docs/ref/models/querysets.txt | 78 +++++++++---------- docs/ref/models/relations.txt | 2 +- docs/ref/request-response.txt | 14 ++-- docs/ref/settings.txt | 10 +-- docs/ref/template-response.txt | 12 +-- docs/ref/unicode.txt | 4 +- docs/ref/urls.txt | 8 +- docs/ref/utils.txt | 10 +-- docs/releases/1.10.txt | 12 +-- docs/releases/1.11.1.txt | 2 +- docs/releases/1.11.txt | 6 +- docs/releases/1.2.txt | 4 +- docs/releases/1.3.txt | 6 +- docs/releases/1.4.12.txt | 2 +- docs/releases/1.4.txt | 2 +- docs/releases/1.5.7.txt | 2 +- docs/releases/1.5.txt | 8 +- docs/releases/1.6.3.txt | 2 +- docs/releases/1.6.4.txt | 2 +- docs/releases/1.6.txt | 8 +- docs/releases/1.7.1.txt | 6 +- docs/releases/1.7.txt | 24 +++--- docs/releases/1.8.txt | 32 ++++---- docs/releases/1.9.txt | 8 +- docs/releases/2.0.txt | 10 +-- docs/releases/2.1.15.txt | 2 +- docs/releases/2.1.txt | 2 +- docs/releases/2.2.16.txt | 2 +- docs/releases/2.2.8.txt | 2 +- docs/releases/3.0.10.txt | 2 +- docs/releases/3.0.txt | 10 +-- docs/releases/3.1.1.txt | 2 +- docs/releases/3.1.txt | 2 +- docs/releases/3.2.txt | 6 +- docs/releases/4.0.txt | 2 +- docs/releases/4.1.txt | 2 +- docs/releases/4.2.14.txt | 2 +- docs/releases/5.0.7.txt | 2 +- docs/releases/5.2.txt | 2 +- docs/topics/auth/customizing.txt | 24 +++--- docs/topics/auth/default.txt | 46 +++++------ .../class-based-views/generic-editing.txt | 12 +-- docs/topics/class-based-views/mixins.txt | 22 +++--- docs/topics/db/models.txt | 4 +- docs/topics/db/optimization.txt | 22 +++--- docs/topics/db/queries.txt | 2 +- docs/topics/db/sql.txt | 4 +- docs/topics/email.txt | 26 +++---- docs/topics/forms/index.txt | 2 +- docs/topics/forms/modelforms.txt | 8 +- docs/topics/http/sessions.txt | 8 +- docs/topics/http/shortcuts.txt | 8 +- docs/topics/http/urls.txt | 10 +-- docs/topics/i18n/translation.txt | 32 ++++---- docs/topics/logging.txt | 2 +- docs/topics/migrations.txt | 2 +- docs/topics/security.txt | 4 +- docs/topics/settings.txt | 2 +- docs/topics/templates.txt | 6 +- docs/topics/testing/advanced.txt | 14 ++-- docs/topics/testing/overview.txt | 2 +- docs/topics/testing/tools.txt | 10 +-- 95 files changed, 445 insertions(+), 445 deletions(-) diff --git a/docs/howto/custom-file-storage.txt b/docs/howto/custom-file-storage.txt index 4c9d164a0a..3f9f732e0b 100644 --- a/docs/howto/custom-file-storage.txt +++ b/docs/howto/custom-file-storage.txt @@ -29,7 +29,7 @@ You'll need to follow these steps: option = settings.CUSTOM_STORAGE_OPTIONS ... -#. Your storage class must implement the :meth:`_open()` and :meth:`_save()` +#. Your storage class must implement the :meth:`_open` and :meth:`_save` methods, along with any other methods appropriate to your storage class. See below for more on these methods. diff --git a/docs/howto/custom-template-tags.txt b/docs/howto/custom-template-tags.txt index e56ef54f02..4038bb5184 100644 --- a/docs/howto/custom-template-tags.txt +++ b/docs/howto/custom-template-tags.txt @@ -509,7 +509,7 @@ Simple block tags When a section of rendered template needs to be passed into a custom tag, Django provides the ``simple_block_tag`` helper function to accomplish this. -Similar to :meth:`~django.template.Library.simple_tag()`, this function accepts +Similar to :meth:`~django.template.Library.simple_tag`, this function accepts a custom tag function, but with the additional ``content`` argument, which contains the rendered content as defined inside the tag. This allows dynamic template sections to be easily incorporated into custom tags. diff --git a/docs/howto/writing-migrations.txt b/docs/howto/writing-migrations.txt index 2c52eccbad..dee42ac14e 100644 --- a/docs/howto/writing-migrations.txt +++ b/docs/howto/writing-migrations.txt @@ -37,7 +37,7 @@ attribute:: migrations.RunPython(forwards), ] -You can also provide hints that will be passed to the :meth:`allow_migrate()` +You can also provide hints that will be passed to the :meth:`allow_migrate` method of database routers as ``**hints``: .. code-block:: python @@ -197,7 +197,7 @@ a transaction by setting the ``atomic`` attribute to ``False``:: Within such a migration, all operations are run without a transaction. It's possible to execute parts of the migration inside a transaction using -:func:`~django.db.transaction.atomic()` or by passing ``atomic=True`` to +:func:`~django.db.transaction.atomic` or by passing ``atomic=True`` to ``RunPython``. Here's an example of a non-atomic data migration that updates a large table in diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 43c78ca041..031074c3fa 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -823,7 +823,7 @@ details on these changes. :func:`~django.template.loader.get_template` and :func:`~django.template.loader.select_template` won't accept a :class:`~django.template.Context` in their - :meth:`~django.template.backends.base.Template.render()` method anymore. + :meth:`~django.template.backends.base.Template.render` method anymore. * :doc:`Template response APIs ` will enforce the use of :class:`dict` and backend-dependent template objects instead of diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 1318c5aa08..504480acb1 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -282,7 +282,7 @@ plug-and-play URLs. Since polls are in their own URLconf "/fun_polls/", or under "/content/polls/", or any other path root, and the app will still work. -.. admonition:: When to use :func:`~django.urls.include()` +.. admonition:: When to use :func:`~django.urls.include` You should always use ``include()`` when you include other URL patterns. The only exception is ``admin.site.urls``, which is a pre-built URLconf diff --git a/docs/intro/tutorial05.txt b/docs/intro/tutorial05.txt index 034c37ea54..599f81f85c 100644 --- a/docs/intro/tutorial05.txt +++ b/docs/intro/tutorial05.txt @@ -557,8 +557,8 @@ repetition out of the process of creating questions. "No polls are available." and verifies the ``latest_question_list`` is empty. Note that the :class:`django.test.TestCase` class provides some additional assertion methods. In these examples, we use -:meth:`~django.test.SimpleTestCase.assertContains()` and -:meth:`~django.test.TransactionTestCase.assertQuerySetEqual()`. +:meth:`~django.test.SimpleTestCase.assertContains` and +:meth:`~django.test.TransactionTestCase.assertQuerySetEqual`. In ``test_past_question``, we create a question and verify that it appears in the list. diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt index eecaa9e323..22ea204801 100644 --- a/docs/ref/applications.txt +++ b/docs/ref/applications.txt @@ -271,7 +271,7 @@ Methods Requires the app registry to be fully populated unless the ``require_ready`` argument is set to ``False``. ``require_ready`` behaves - exactly as in :meth:`apps.get_model()`. + exactly as in :meth:`apps.get_model`. .. method:: AppConfig.ready() @@ -309,12 +309,12 @@ Methods .. warning:: Although you can access model classes as described above, avoid - interacting with the database in your :meth:`ready()` implementation. + interacting with the database in your :meth:`ready` implementation. This includes model methods that execute queries - (:meth:`~django.db.models.Model.save()`, - :meth:`~django.db.models.Model.delete()`, manager methods etc.), and + (:meth:`~django.db.models.Model.save`, + :meth:`~django.db.models.Model.delete`, manager methods etc.), and also raw SQL queries via ``django.db.connection``. Your - :meth:`ready()` method will run during startup of every management + :meth:`ready` method will run during startup of every management command. For example, even though the test database configuration is separate from the production settings, ``manage.py test`` would still execute some queries against your **production** database! @@ -416,7 +416,7 @@ Initialization process How applications are loaded --------------------------- -When Django starts, :func:`django.setup()` is responsible for populating the +When Django starts, :func:`django.setup` is responsible for populating the application registry. .. currentmodule:: django @@ -463,7 +463,7 @@ processes all applications in the order of :setting:`INSTALLED_APPS`. import any models at this stage. Once this stage completes, APIs that operate on application configurations - such as :meth:`~apps.get_app_config()` become usable. + such as :meth:`~apps.get_app_config` become usable. #. Then Django attempts to import the ``models`` submodule of each application, if there is one. @@ -473,9 +473,9 @@ processes all applications in the order of :setting:`INSTALLED_APPS`. populated at this point, which could cause the ORM to malfunction. Once this stage completes, APIs that operate on models such as - :meth:`~apps.get_model()` become usable. + :meth:`~apps.get_model` become usable. -#. Finally Django runs the :meth:`~AppConfig.ready()` method of each application +#. Finally Django runs the :meth:`~AppConfig.ready` method of each application configuration. .. _applications-troubleshooting: @@ -489,10 +489,10 @@ Here are some common problems that you may encounter during initialization: importing an application configuration or a models module triggers code that depends on the app registry. - For example, :func:`~django.utils.translation.gettext()` uses the app + For example, :func:`~django.utils.translation.gettext` uses the app registry to look up translation catalogs in applications. To translate at - import time, you need :func:`~django.utils.translation.gettext_lazy()` - instead. (Using :func:`~django.utils.translation.gettext()` would be a bug, + import time, you need :func:`~django.utils.translation.gettext_lazy` + instead. (Using :func:`~django.utils.translation.gettext` would be a bug, because the translation would happen at import time, rather than at each request depending on the active language.) @@ -500,7 +500,7 @@ Here are some common problems that you may encounter during initialization: will also trigger this exception. The ORM cannot function properly until all models are available. - This exception also happens if you forget to call :func:`django.setup()` in + This exception also happens if you forget to call :func:`django.setup` in a standalone Python script. * ``ImportError: cannot import name ...`` This happens if the import sequence diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt index 7f0212b757..9dc939606d 100644 --- a/docs/ref/class-based-views/base.txt +++ b/docs/ref/class-based-views/base.txt @@ -24,10 +24,10 @@ MRO is an acronym for Method Resolution Order. **Method Flowchart** - #. :meth:`setup()` - #. :meth:`dispatch()` - #. :meth:`http_method_not_allowed()` - #. :meth:`options()` + #. :meth:`setup` + #. :meth:`dispatch` + #. :meth:`http_method_not_allowed` + #. :meth:`options` **Example views.py**:: @@ -144,10 +144,10 @@ MRO is an acronym for Method Resolution Order. **Method Flowchart** - #. :meth:`~django.views.generic.base.View.setup()` - #. :meth:`~django.views.generic.base.View.dispatch()` - #. :meth:`~django.views.generic.base.View.http_method_not_allowed()` - #. :meth:`~django.views.generic.base.ContextMixin.get_context_data()` + #. :meth:`~django.views.generic.base.View.setup` + #. :meth:`~django.views.generic.base.View.dispatch` + #. :meth:`~django.views.generic.base.View.http_method_not_allowed` + #. :meth:`~django.views.generic.base.ContextMixin.get_context_data` **Example views.py**:: @@ -206,10 +206,10 @@ MRO is an acronym for Method Resolution Order. **Method Flowchart** - #. :meth:`~django.views.generic.base.View.setup()` - #. :meth:`~django.views.generic.base.View.dispatch()` - #. :meth:`~django.views.generic.base.View.http_method_not_allowed()` - #. :meth:`get_redirect_url()` + #. :meth:`~django.views.generic.base.View.setup` + #. :meth:`~django.views.generic.base.View.dispatch` + #. :meth:`~django.views.generic.base.View.http_method_not_allowed` + #. :meth:`get_redirect_url` **Example views.py**:: diff --git a/docs/ref/class-based-views/generic-display.txt b/docs/ref/class-based-views/generic-display.txt index 731197da4b..a74b9722c6 100644 --- a/docs/ref/class-based-views/generic-display.txt +++ b/docs/ref/class-based-views/generic-display.txt @@ -25,17 +25,17 @@ many projects they are typically the most commonly used views. **Method Flowchart** - #. :meth:`~django.views.generic.base.View.setup()` - #. :meth:`~django.views.generic.base.View.dispatch()` - #. :meth:`~django.views.generic.base.View.http_method_not_allowed()` - #. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` - #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field()` - #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset()` - #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` - #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name()` - #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data()` + #. :meth:`~django.views.generic.base.View.setup` + #. :meth:`~django.views.generic.base.View.dispatch` + #. :meth:`~django.views.generic.base.View.http_method_not_allowed` + #. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_slug_field` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_queryset` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_object_name` + #. :meth:`~django.views.generic.detail.SingleObjectMixin.get_context_data` #. :meth:`~django.views.generic.detail.BaseDetailView.get` - #. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` + #. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` **Example myapp/views.py**:: @@ -116,15 +116,15 @@ many projects they are typically the most commonly used views. **Method Flowchart** - #. :meth:`~django.views.generic.base.View.setup()` - #. :meth:`~django.views.generic.base.View.dispatch()` - #. :meth:`~django.views.generic.base.View.http_method_not_allowed()` - #. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` - #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset()` - #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name()` - #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data()` + #. :meth:`~django.views.generic.base.View.setup` + #. :meth:`~django.views.generic.base.View.dispatch` + #. :meth:`~django.views.generic.base.View.http_method_not_allowed` + #. :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names` + #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_queryset` + #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_object_name` + #. :meth:`~django.views.generic.list.MultipleObjectMixin.get_context_data` #. :meth:`~django.views.generic.list.BaseListView.get` - #. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` + #. :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` **Example views.py**:: diff --git a/docs/ref/class-based-views/index.txt b/docs/ref/class-based-views/index.txt index 0c2f20aee5..162f295ef0 100644 --- a/docs/ref/class-based-views/index.txt +++ b/docs/ref/class-based-views/index.txt @@ -23,7 +23,7 @@ it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is a thread-safe operation). A class-based view is deployed into a URL pattern using the -:meth:`~django.views.generic.base.View.as_view()` classmethod:: +:meth:`~django.views.generic.base.View.as_view` classmethod:: urlpatterns = [ path("view/", MyView.as_view(size=42)), @@ -37,7 +37,7 @@ A class-based view is deployed into a URL pattern using the is modified, the actions of one user visiting your view could have an effect on subsequent users visiting the same view. -Arguments passed into :meth:`~django.views.generic.base.View.as_view()` will +Arguments passed into :meth:`~django.views.generic.base.View.as_view` will be assigned onto the instance that is used to service a request. Using the previous example, this means that every request on ``MyView`` is able to use ``self.size``. Arguments must correspond to attributes that already exist on diff --git a/docs/ref/class-based-views/mixins-simple.txt b/docs/ref/class-based-views/mixins-simple.txt index bbd0875e75..f0a23ffc7b 100644 --- a/docs/ref/class-based-views/mixins-simple.txt +++ b/docs/ref/class-based-views/mixins-simple.txt @@ -95,7 +95,7 @@ Simple mixins If any keyword arguments are provided, they will be passed to the constructor of the response class. - Calls :meth:`get_template_names()` to obtain the list of template names + Calls :meth:`get_template_names` to obtain the list of template names that will be searched looking for an existent template. .. method:: get_template_names() diff --git a/docs/ref/class-based-views/mixins-single-object.txt b/docs/ref/class-based-views/mixins-single-object.txt index 2e96422fc7..d4cbc70fbd 100644 --- a/docs/ref/class-based-views/mixins-single-object.txt +++ b/docs/ref/class-based-views/mixins-single-object.txt @@ -53,7 +53,7 @@ Single object mixins .. attribute:: query_pk_and_slug - If ``True``, causes :meth:`get_object()` to perform its lookup using + If ``True``, causes :meth:`get_object` to perform its lookup using both the primary key and the slug. Defaults to ``False``. This attribute can help mitigate `insecure direct object reference`_ diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index 263d43f8a3..738f64f70b 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/docs/ref/contrib/admin/actions.txt @@ -288,7 +288,7 @@ Making actions available site-wide Some actions are best if they're made available to *any* object in the admin site -- the export action defined above would be a good candidate. You can - make an action globally available using :meth:`AdminSite.add_action()`. For + make an action globally available using :meth:`AdminSite.add_action`. For example:: from django.contrib import admin @@ -299,7 +299,7 @@ Making actions available site-wide action named "export_selected_objects". You can explicitly give the action a name -- good if you later want to programmatically :ref:`remove the action ` -- by passing a second argument to - :meth:`AdminSite.add_action()`:: + :meth:`AdminSite.add_action`:: admin.site.add_action(export_selected_objects, "export_selected") @@ -318,7 +318,7 @@ Disabling a site-wide action .. method:: AdminSite.disable_action(name) If you need to disable a :ref:`site-wide action ` you can - call :meth:`AdminSite.disable_action()`. + call :meth:`AdminSite.disable_action`. For example, you can use this method to remove the built-in "delete selected objects" action:: diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index d15b44d083..34bbb7942d 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -154,12 +154,12 @@ application and imports it. .. class:: apps.AdminConfig This is the default :class:`~django.apps.AppConfig` class for the admin. - It calls :func:`~django.contrib.admin.autodiscover()` when Django starts. + It calls :func:`~django.contrib.admin.autodiscover` when Django starts. .. class:: apps.SimpleAdminConfig This class works like :class:`~django.contrib.admin.apps.AdminConfig`, - except it doesn't call :func:`~django.contrib.admin.autodiscover()`. + except it doesn't call :func:`~django.contrib.admin.autodiscover`. .. attribute:: default_site @@ -3119,7 +3119,7 @@ Hooking ``AdminSite`` instances into your URLconf The last step in setting up the Django admin is to hook your ``AdminSite`` instance into your URLconf. Do this by pointing a given URL at the ``AdminSite.urls`` method. It is not necessary to use -:func:`~django.urls.include()`. +:func:`~django.urls.include`. In this example, we register the default ``AdminSite`` instance ``django.contrib.admin.site`` at the URL ``/admin/`` :: @@ -3245,10 +3245,10 @@ Adding views to admin sites --------------------------- Just like :class:`ModelAdmin`, :class:`AdminSite` provides a -:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method +:meth:`~django.contrib.admin.ModelAdmin.get_urls` method that can be overridden to define additional views for the site. To add a new view to your admin site, extend the base -:meth:`~django.contrib.admin.ModelAdmin.get_urls()` method to include +:meth:`~django.contrib.admin.ModelAdmin.get_urls` method to include a pattern for your new view. .. note:: diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index 56d7cea7b9..56c33c40b6 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -159,7 +159,7 @@ Methods When the ``raw_password`` is ``None``, the password will be set to an unusable password, as if - :meth:`~django.contrib.auth.models.User.set_unusable_password()` + :meth:`~django.contrib.auth.models.User.set_unusable_password` were used. .. method:: check_password(raw_password) @@ -176,7 +176,7 @@ Methods Marks the user as having no password set by updating the metadata in the :attr:`~django.contrib.auth.models.User.password` field. This isn't the same as having a blank string for a password. - :meth:`~django.contrib.auth.models.User.check_password()` for this user + :meth:`~django.contrib.auth.models.User.check_password` for this user will never return ``True``. Doesn't save the :class:`~django.contrib.auth.models.User` object. @@ -192,7 +192,7 @@ Methods .. method:: has_usable_password() Returns ``False`` if - :meth:`~django.contrib.auth.models.User.set_unusable_password()` has + :meth:`~django.contrib.auth.models.User.set_unusable_password` has been called for this user. .. method:: get_user_permissions(obj=None) @@ -293,7 +293,7 @@ Methods Sends an email to the user. If ``from_email`` is ``None``, Django uses the :setting:`DEFAULT_FROM_EMAIL`. Any ``**kwargs`` are passed to the - underlying :meth:`~django.core.mail.send_mail()` call. + underlying :meth:`~django.core.mail.send_mail` call. Manager methods --------------- @@ -319,7 +319,7 @@ Manager methods :attr:`~django.contrib.auth.models.User.is_active` set to ``True``. If no password is provided, - :meth:`~django.contrib.auth.models.User.set_unusable_password()` will + :meth:`~django.contrib.auth.models.User.set_unusable_password` will be called. If no email is provided, :attr:`~django.contrib.auth.models.User.email` @@ -380,7 +380,7 @@ Manager methods * :ref:`id ` is always ``None``. * :attr:`~django.contrib.auth.models.User.username` is always the empty string. - * :meth:`~django.contrib.auth.models.User.get_username()` always returns + * :meth:`~django.contrib.auth.models.User.get_username` always returns the empty string. * :attr:`~django.contrib.auth.models.User.is_anonymous` is ``True`` instead of ``False``. @@ -393,10 +393,10 @@ Manager methods * :attr:`~django.contrib.auth.models.User.groups` and :attr:`~django.contrib.auth.models.User.user_permissions` are always empty. - * :meth:`~django.contrib.auth.models.User.set_password()`, - :meth:`~django.contrib.auth.models.User.check_password()`, + * :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:`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 @@ -524,7 +524,7 @@ can be used for notification when a user logs in or out. ``credentials`` A dictionary of keyword arguments containing the user credentials that were - passed to :func:`~django.contrib.auth.authenticate()` or your own custom + passed to :func:`~django.contrib.auth.authenticate` or your own custom authentication backend. Credentials matching a set of 'sensitive' patterns, (including password) will not be sent in the clear as part of the signal. diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index d8f4b24753..f8232cec1d 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -220,7 +220,7 @@ The ``ContentTypeManager`` referenced via a :ref:`natural key` during deserialization. -The :meth:`~ContentTypeManager.get_for_model()` method is especially +The :meth:`~ContentTypeManager.get_for_model` method is especially useful when you know you need to work with a :class:`ContentType ` but don't want to go to the trouble of obtaining the model's metadata to perform a manual diff --git a/docs/ref/contrib/postgres/functions.txt b/docs/ref/contrib/postgres/functions.txt index 4602f7fd9d..39d74917da 100644 --- a/docs/ref/contrib/postgres/functions.txt +++ b/docs/ref/contrib/postgres/functions.txt @@ -32,7 +32,7 @@ the current statement. This is a complement to :class:`django.db.models.functions.Now`, which returns the date and time of the current statement. -Note that only the outermost call to :func:`~django.db.transaction.atomic()` +Note that only the outermost call to :func:`~django.db.transaction.atomic` sets up a transaction and thus sets the time that ``TransactionNow()`` will return; nested calls create savepoints which do not affect the transaction time. diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index 5628edd183..bb4b66c4f9 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -121,7 +121,7 @@ Note: attributes corresponding to ```` and ```` elements, respectively. They can be made callable as functions, as :attr:`~Sitemap.lastmod` was in the example. -* :attr:`~Sitemap.items()` is a method that returns a :term:`sequence` or +* :attr:`~Sitemap.items` is a method that returns a :term:`sequence` or ``QuerySet`` of objects. The objects returned will get passed to any callable methods corresponding to a sitemap property (:attr:`~Sitemap.location`, :attr:`~Sitemap.lastmod`, :attr:`~Sitemap.changefreq`, and @@ -129,7 +129,7 @@ Note: * :attr:`~Sitemap.lastmod` should return a :class:`~datetime.datetime`. * There is no :attr:`~Sitemap.location` method in this example, but you can provide it in order to specify the URL for your object. By default, - :attr:`~Sitemap.location()` calls ``get_absolute_url()`` on each object + :attr:`~Sitemap.location` calls ``get_absolute_url()`` on each object and returns the result. ``Sitemap`` class reference @@ -144,19 +144,19 @@ Note: **Required.** A method that returns a :term:`sequence` or ``QuerySet`` of objects. The framework doesn't care what *type* of objects they are; all that matters is that these objects get passed to the - :attr:`~Sitemap.location()`, :attr:`~Sitemap.lastmod()`, - :attr:`~Sitemap.changefreq()` and :attr:`~Sitemap.priority()` methods. + :attr:`~Sitemap.location`, :attr:`~Sitemap.lastmod`, + :attr:`~Sitemap.changefreq` and :attr:`~Sitemap.priority` methods. .. attribute:: Sitemap.location **Optional.** Either a method or attribute. If it's a method, it should return the absolute path for a given object - as returned by :attr:`~Sitemap.items()`. + as returned by :attr:`~Sitemap.items`. If it's an attribute, its value should be a string representing an absolute path to use for *every* object returned by - :attr:`~Sitemap.items()`. + :attr:`~Sitemap.items`. In both cases, "absolute path" means a URL that doesn't include the protocol or domain. Examples: @@ -167,7 +167,7 @@ Note: If :attr:`~Sitemap.location` isn't provided, the framework will call the ``get_absolute_url()`` method on each object as returned by - :attr:`~Sitemap.items()`. + :attr:`~Sitemap.items`. To specify a protocol other than ``'http'``, use :attr:`~Sitemap.protocol`. @@ -177,12 +177,12 @@ Note: **Optional.** Either a method or attribute. If it's a method, it should take one argument -- an object as returned - by :attr:`~Sitemap.items()` -- and return that object's last-modified + by :attr:`~Sitemap.items` -- and return that object's last-modified date/time as a :class:`~datetime.datetime`. If it's an attribute, its value should be a :class:`~datetime.datetime` representing the last-modified date/time for *every* object returned by - :attr:`~Sitemap.items()`. + :attr:`~Sitemap.items`. If all items in a sitemap have a :attr:`~Sitemap.lastmod`, the sitemap generated by :func:`views.sitemap` will have a ``Last-Modified`` @@ -196,7 +196,7 @@ Note: **Optional.** This property returns a :class:`~django.core.paginator.Paginator` for - :attr:`~Sitemap.items()`. If you generate sitemaps in a batch you may + :attr:`~Sitemap.items`. If you generate sitemaps in a batch you may want to override this as a cached property in order to avoid multiple ``items()`` calls. @@ -205,11 +205,11 @@ Note: **Optional.** Either a method or attribute. If it's a method, it should take one argument -- an object as returned - by :attr:`~Sitemap.items()` -- and return that object's change + by :attr:`~Sitemap.items` -- and return that object's change frequency as a string. If it's an attribute, its value should be a string representing the - change frequency of *every* object returned by :attr:`~Sitemap.items()`. + change frequency of *every* object returned by :attr:`~Sitemap.items`. Possible values for :attr:`~Sitemap.changefreq`, whether you use a method or attribute, are: @@ -227,12 +227,12 @@ Note: **Optional.** Either a method or attribute. If it's a method, it should take one argument -- an object as returned - by :attr:`~Sitemap.items()` -- and return that object's priority as + by :attr:`~Sitemap.items` -- and return that object's priority as either a string or float. If it's an attribute, its value should be either a string or float representing the priority of *every* object returned by - :attr:`~Sitemap.items()`. + :attr:`~Sitemap.items`. Example values for :attr:`~Sitemap.priority`: ``0.4``, ``1.0``. The default priority of a page is ``0.5``. See the `sitemaps.org @@ -554,7 +554,7 @@ URL. Each alternate is a dictionary with ``location`` and ``lang_code`` keys. The ``item`` attribute has been added for each URL to allow more flexible customization of the templates, such as `Google news sitemaps`_. Assuming -Sitemap's :attr:`~Sitemap.items()` would return a list of items with +Sitemap's :attr:`~Sitemap.items` would return a list of items with ``publication_data`` and a ``tags`` field something like this would generate a Google News compatible sitemap: diff --git a/docs/ref/contrib/sites.txt b/docs/ref/contrib/sites.txt index f6c39feff7..fc279e943b 100644 --- a/docs/ref/contrib/sites.txt +++ b/docs/ref/contrib/sites.txt @@ -485,7 +485,7 @@ a fallback when the database-backed sites framework is not available. A :class:`~django.contrib.sites.requests.RequestSite` object has a similar interface to a normal :class:`~django.contrib.sites.models.Site` object, -except its :meth:`~django.contrib.sites.requests.RequestSite.__init__()` +except its :meth:`~django.contrib.sites.requests.RequestSite.__init__` 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 diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index a81b428d45..c57a373932 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -311,7 +311,7 @@ Language Feeds created by the syndication framework automatically include the appropriate ```` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). By -default, this is :func:`django.utils.translation.get_language()`. You can change it +default, this is :func:`django.utils.translation.get_language`. You can change it by setting the ``language`` class attribute. URLs diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 22a7c0a10c..64819af1ab 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -1051,12 +1051,12 @@ together: .. django-admin-option:: --managers Mails the email addresses specified in :setting:`MANAGERS` using -:meth:`~django.core.mail.mail_managers()`. +:meth:`~django.core.mail.mail_managers`. .. django-admin-option:: --admins Mails the email addresses specified in :setting:`ADMINS` using -:meth:`~django.core.mail.mail_admins()`. +:meth:`~django.core.mail.mail_admins`. ``shell`` --------- @@ -1524,7 +1524,7 @@ Runs tests in separate parallel processes. Since modern processors have multiple cores, this allows running tests significantly faster. Using ``--parallel`` without a value, or with the value ``auto``, runs one test -process per core according to :func:`multiprocessing.cpu_count()`. You can +process per core according to :func:`multiprocessing.cpu_count`. You can override this by passing the desired number of processes, e.g. ``--parallel 4``, or by setting the :envvar:`DJANGO_TEST_PROCESSES` environment variable. @@ -1597,7 +1597,7 @@ as :option:`unittest's --buffer option`. .. django-admin-option:: --no-faulthandler -Django automatically calls :func:`faulthandler.enable()` when starting the +Django automatically calls :func:`faulthandler.enable` when starting the tests, which allows it to print a traceback if the interpreter crashes. Pass ``--no-faulthandler`` to disable this behavior. diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index a105679a9b..bbd959e95d 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -31,7 +31,7 @@ Django core exception classes are defined in ``django.core.exceptions``. ``ObjectDoesNotExist`` will catch :exc:`~django.db.models.Model.DoesNotExist` exceptions for all models. - See :meth:`~django.db.models.query.QuerySet.get()`. + See :meth:`~django.db.models.query.QuerySet.get`. ``ObjectNotUpdated`` -------------------- @@ -45,7 +45,7 @@ Django core exception classes are defined in ``django.core.exceptions``. ``ObjectNotUpdated`` will catch :exc:`~django.db.models.Model.NotUpdated` exceptions for all models. - See :meth:`~django.db.models.Model.save()`. + See :meth:`~django.db.models.Model.save`. ``EmptyResultSet`` ------------------ @@ -85,7 +85,7 @@ Django core exception classes are defined in ``django.core.exceptions``. :exc:`~django.db.models.Model.MultipleObjectsReturned` exceptions for all models. - See :meth:`~django.db.models.query.QuerySet.get()`. + See :meth:`~django.db.models.query.QuerySet.get`. ``SuspiciousOperation`` ----------------------- @@ -239,7 +239,7 @@ URL Resolver exceptions are defined in ``django.urls``. .. exception:: Resolver404 The :exc:`Resolver404` exception is raised by - :func:`~django.urls.resolve()` if the path passed to ``resolve()`` doesn't + :func:`~django.urls.resolve` if the path passed to ``resolve()`` doesn't map to a view. It's a subclass of :class:`django.http.Http404`. ``NoReverseMatch`` diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index d0b0cdd786..23a3814f5d 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -50,7 +50,7 @@ The ``File`` class Open or reopen the file (which also does ``File.seek(0)``). The ``mode`` argument allows the same values - as Python's built-in :func:`python:open()`. ``*args`` and ``**kwargs`` + as Python's built-in :func:`python:open`. ``*args`` and ``**kwargs`` are passed after ``mode`` to Python's built-in :func:`python:open`. When reopening a file, ``mode`` will override whatever mode the file diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt index 228025fe3a..85a1e3b926 100644 --- a/docs/ref/files/storage.txt +++ b/docs/ref/files/storage.txt @@ -201,12 +201,12 @@ The ``Storage`` class .. method:: generate_filename(filename) - Validates the ``filename`` by calling :attr:`get_valid_name()` and + Validates the ``filename`` by calling :attr:`get_valid_name` and returns a filename to be passed to the :meth:`save` method. The ``filename`` argument may include a path as returned by :attr:`FileField.upload_to `. - In that case, the path won't be passed to :attr:`get_valid_name()` but + In that case, the path won't be passed to :attr:`get_valid_name` but will be prepended back to the resulting name. The default implementation uses :mod:`os.path` operations. Override diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 9b827ca69a..399c8f3728 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -157,7 +157,7 @@ instances. Use this method anytime you need to identify an error by its ``code``. This enables things like rewriting the error's message or writing custom logic in a view when a given error is present. It can also be used to serialize the errors -in a custom format (e.g. XML); for instance, :meth:`~Form.errors.as_json()` +in a custom format (e.g. XML); for instance, :meth:`~Form.errors.as_json` relies on ``as_data()``. The need for the ``as_data()`` method is due to backwards compatibility. @@ -193,11 +193,11 @@ directly in HTML. .. method:: Form.errors.get_json_data(escape_html=False) Returns the errors as a dictionary suitable for serializing to JSON. -:meth:`Form.errors.as_json()` returns serialized JSON, while this returns the +:meth:`Form.errors.as_json` returns serialized JSON, while this returns the error data before it's serialized. The ``escape_html`` parameter behaves as described in -:meth:`Form.errors.as_json()`. +:meth:`Form.errors.as_json`. .. method:: Form.add_error(field, error) @@ -298,8 +298,8 @@ Returns the initial data for a form field. It retrieves the data from Callable values are evaluated. It is recommended to use :attr:`BoundField.initial` over -:meth:`~Form.get_initial_for_field()` because ``BoundField.initial`` has a -simpler interface. Also, unlike :meth:`~Form.get_initial_for_field()`, +:meth:`~Form.get_initial_for_field` because ``BoundField.initial`` has a +simpler interface. Also, unlike :meth:`~Form.get_initial_for_field`, :attr:`BoundField.initial` caches its values. This is useful especially when dealing with callables whose return values can change (e.g. ``datetime.now`` or ``uuid.uuid4``): @@ -1315,7 +1315,7 @@ Attributes of ``BoundField`` datetime.datetime(2021, 7, 27, 9, 5, 54) Using :attr:`BoundField.initial` is recommended over - :meth:`~Form.get_initial_for_field()`. + :meth:`~Form.get_initial_for_field`. .. attribute:: BoundField.is_hidden @@ -1517,7 +1517,7 @@ If not defined as a class variable, ``bound_field_class`` can be set via the constructor. For compatibility reasons, a custom form field can still override -:meth:`.Field.get_bound_field()` to use a custom class, though any of the +:meth:`.Field.get_bound_field` to use a custom class, though any of the previous options are preferred. You may want to use a custom :class:`.BoundField` if you need to access some diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 8d2ed2d404..b09a43f47c 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -414,7 +414,7 @@ Checking if the field data has changed The ``has_changed()`` method is used to determine if the field value has changed from the initial value. Returns ``True`` or ``False``. -See the :class:`Form.has_changed()` documentation for more information. +See the :class:`Form.has_changed` documentation for more information. .. _built-in-fields: @@ -1631,7 +1631,7 @@ only requirements are that it implement a ``clean()`` method and that its You can also customize how a field will be accessed by overriding :attr:`~django.forms.Field.bound_field_class` or override -:meth:`.Field.get_bound_field()` if you need more flexibility when creating +:meth:`.Field.get_bound_field` if you need more flexibility when creating the ``BoundField``: .. method:: Field.get_bound_field(form, field_name) diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index b857795e7a..52206dea2a 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -83,12 +83,12 @@ overridden: called, you also have access to the form's ``errors`` attribute which contains all the errors raised by cleaning of individual fields. - Note that any errors raised by your :meth:`Form.clean()` override will not + Note that any errors raised by your :meth:`Form.clean` override will not be associated with any field in particular. They go into a special "field" (called ``__all__``), which you can access via the :meth:`~django.forms.Form.non_field_errors` method if you need to. If you want to attach errors to a specific field in the form, you need to call - :meth:`~django.forms.Form.add_error()`. + :meth:`~django.forms.Form.add_error`. Also note that there are special considerations when overriding the ``clean()`` method of a ``ModelForm`` subclass. (see the @@ -99,7 +99,7 @@ These methods are run in the order given above, one field at a time. That is, for each field in the form (in the order they are declared in the form definition), the ``Field.clean()`` method (or its override) is run, then ``clean_()``. Finally, once those two methods are run for every -field, the :meth:`Form.clean()` method, or its override, is executed whether +field, the :meth:`Form.clean` method, or its override, is executed whether or not the previous methods have raised errors. Examples of each of these methods are provided below. @@ -335,7 +335,7 @@ Cleaning and validating fields that depend on each other Suppose we add another requirement to our contact form: if the ``cc_myself`` field is ``True``, the ``subject`` must contain the word ``"help"``. We are performing validation on more than one field at a time, so the form's -:meth:`~Form.clean()` method is a good spot to do this. Notice that we are +:meth:`~Form.clean` method is a good spot to do this. Notice that we are talking about the ``clean()`` method on the form here, whereas earlier we were writing a ``clean()`` method on a field. It's important to keep the field and form difference clear when working out where to validate things. Fields are diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 2488ba66a3..2c277f4587 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -226,7 +226,7 @@ foundation for custom widgets. This abstract class cannot be rendered, but provides the basic attribute :attr:`~Widget.attrs`. You may also implement or override the - :meth:`~Widget.render()` method on custom widgets. + :meth:`~Widget.render` method on custom widgets. .. attribute:: Widget.attrs diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt index de78ef833f..6879d5e726 100644 --- a/docs/ref/middleware.txt +++ b/docs/ref/middleware.txt @@ -137,7 +137,7 @@ If the response has an ``ETag`` header, the ETag is made weak to comply with :rfc:`9110#section-8.8.1`. You can apply GZip compression to individual views using the -:func:`~django.views.decorators.gzip.gzip_page()` decorator. +:func:`~django.views.decorators.gzip.gzip_page` decorator. Conditional GET middleware -------------------------- @@ -154,7 +154,7 @@ header, the middleware adds one if needed. If the response has an ``ETag`` or :class:`~django.http.HttpResponseNotModified`. You can handle conditional GET operations with individual views using the -:func:`~django.views.decorators.http.conditional_page()` decorator. +:func:`~django.views.decorators.http.conditional_page` decorator. Locale middleware ----------------- @@ -596,7 +596,7 @@ fields to POST forms and checking requests for the correct value. See the :doc:`Cross Site Request Forgery protection documentation `. You can add Cross Site Request Forgery protection to individual views using the -:func:`~django.views.decorators.csrf.csrf_protect()` decorator. +:func:`~django.views.decorators.csrf.csrf_protect` decorator. ``X-Frame-Options`` middleware ------------------------------ diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt index 9e0eb3ba65..0d0e82df13 100644 --- a/docs/ref/models/expressions.txt +++ b/docs/ref/models/expressions.txt @@ -166,12 +166,12 @@ To access the new value saved this way, the object must be reloaded:: As well as being used in operations on single instances as above, ``F()`` can be used with ``update()`` to perform bulk updates on a ``QuerySet``. This reduces the two queries we were using above - the ``get()`` and the -:meth:`~Model.save()` - to just one:: +:meth:`~Model.save` - to just one:: reporter = Reporters.objects.filter(name="Tintin") reporter.update(stories_filed=F("stories_filed") + 1) -We can also use :meth:`~django.db.models.query.QuerySet.update()` to increment +We can also use :meth:`~django.db.models.query.QuerySet.update` to increment the field value on multiple objects - which could be very much faster than pulling them all into Python from the database, looping over them, incrementing the field value of each one, and saving each one back to the database:: @@ -218,14 +218,14 @@ based on the original value; the work of the first thread will be lost. If the database is responsible for updating the field, the process is more robust: it will only ever update the field based on the value of the field in -the database when the :meth:`~Model.save()` or ``update()`` is executed, rather +the database when the :meth:`~Model.save` or ``update()`` is executed, rather than based on its value when the instance was retrieved. ``F()`` assignments persist after ``Model.save()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``F()`` objects assigned to model fields persist after saving the model -instance and will be applied on each :meth:`~Model.save()`. For example:: +instance and will be applied on each :meth:`~Model.save`. For example:: reporter = Reporters.objects.get(name="Tintin") reporter.stories_filed = F("stories_filed") + 1 @@ -237,7 +237,7 @@ instance and will be applied on each :meth:`~Model.save()`. For example:: ``stories_filed`` will be updated twice in this case. If it's initially ``1``, the final value will be ``3``. This persistence can be avoided by reloading the model object after saving it, for example, by using -:meth:`~Model.refresh_from_db()`. +:meth:`~Model.refresh_from_db`. Using ``F()`` in filters ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1199,7 +1199,7 @@ calling the appropriate methods on the wrapped expression. implementing ``NULLS LAST`` would change its value to be ``NULLS FIRST``. Modifications are only required for expressions that implement sort order like ``OrderBy``. This method is called when - :meth:`~django.db.models.query.QuerySet.reverse()` is called on a + :meth:`~django.db.models.query.QuerySet.reverse` is called on a queryset. .. _writing-your-own-query-expressions: diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 372f86657f..430efcd446 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -292,7 +292,7 @@ modifications: These property names cannot be used as member names as they would conflict. -* The use of :func:`enum.unique()` is enforced to ensure that values cannot be +* The use of :func:`enum.unique` is enforced to ensure that values cannot be defined multiple times. This is unlikely to be expected in choices for a field. @@ -603,11 +603,11 @@ portion of the field will be considered. Besides, when :setting:`USE_TZ` is ``True``, the check will be performed in the :ref:`current time zone ` at the time the object gets saved. -This is enforced by :meth:`Model.validate_unique()` during model validation +This is enforced by :meth:`Model.validate_unique` during model validation but not at the database level. If any :attr:`~Field.unique_for_date` constraint involves fields that are not part of a :class:`~django.forms.ModelForm` (for example, if one of the fields is listed in ``exclude`` or has -:attr:`editable=False`), :meth:`Model.validate_unique()` will +:attr:`editable=False`), :meth:`Model.validate_unique` will skip validation for that particular constraint. ``unique_for_month`` @@ -1316,8 +1316,8 @@ materialized view. .. admonition:: Refresh the data Since the database computes the value, the object must be reloaded to - access the new value after :meth:`~Model.save()`, for example, by using - :meth:`~Model.refresh_from_db()`. + access the new value after :meth:`~Model.save`, for example, by using + :meth:`~Model.refresh_from_db`. .. admonition:: Database limitations @@ -1796,7 +1796,7 @@ The possible values for :attr:`~ForeignKey.on_delete` are found in * .. function:: SET() Set the :class:`ForeignKey` to the value passed to - :func:`~django.db.models.SET()`, or if a callable is passed in, + :func:`~django.db.models.SET`, or if a callable is passed in, the result of calling it. In most cases, passing a callable will be necessary to avoid executing queries at the time your ``models.py`` is imported:: diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index da440f1ba9..6baa0cb27d 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -23,7 +23,7 @@ class: The keyword arguments are the names of the fields you've defined on your model. Note that instantiating a model in no way touches your database; for that, you -need to :meth:`~Model.save()`. +need to :meth:`~Model.save`. .. note:: @@ -226,27 +226,27 @@ Validating objects There are four steps involved in validating a model: -1. Validate the model fields - :meth:`Model.clean_fields()` -2. Validate the model as a whole - :meth:`Model.clean()` -3. Validate the field uniqueness - :meth:`Model.validate_unique()` +1. Validate the model fields - :meth:`Model.clean_fields` +2. Validate the model as a whole - :meth:`Model.clean` +3. Validate the field uniqueness - :meth:`Model.validate_unique` 4. Validate the constraints - :meth:`Model.validate_constraints` All four steps are performed when you call a model's :meth:`~Model.full_clean` method. When you use a :class:`~django.forms.ModelForm`, the call to -:meth:`~django.forms.Form.is_valid()` will perform these validation steps for +:meth:`~django.forms.Form.is_valid` will perform these validation steps for all the fields that are included on the form. See the :doc:`ModelForm documentation ` for more information. You should only -need to call a model's :meth:`~Model.full_clean()` method if you plan to handle +need to call a model's :meth:`~Model.full_clean` method if you plan to handle validation errors yourself, or if you have excluded fields from the :class:`~django.forms.ModelForm` that require validation. .. method:: Model.full_clean(exclude=None, validate_unique=True, validate_constraints=True) -This method calls :meth:`Model.clean_fields()`, :meth:`Model.clean()`, -:meth:`Model.validate_unique()` (if ``validate_unique`` is ``True``), and -:meth:`Model.validate_constraints()` (if ``validate_constraints`` is ``True``) +This method calls :meth:`Model.clean_fields`, :meth:`Model.clean`, +:meth:`Model.validate_unique` (if ``validate_unique`` is ``True``), and +:meth:`Model.validate_constraints` (if ``validate_constraints`` is ``True``) in that order and raises a :exc:`~django.core.exceptions.ValidationError` that has a ``message_dict`` attribute containing errors from all four stages. @@ -257,7 +257,7 @@ aren't present on your form from being validated since any errors raised could not be corrected by the user. Note that ``full_clean()`` will *not* be called automatically when you call -your model's :meth:`~Model.save()` method. You'll need to call it manually +your model's :meth:`~Model.save` method. You'll need to call it manually when you want to run one-step model validation for your own manually created models. For example:: @@ -279,7 +279,7 @@ argument lets you provide a ``set`` of field names to exclude from validation. It will raise a :exc:`~django.core.exceptions.ValidationError` if any fields fail validation. -The second step ``full_clean()`` performs is to call :meth:`Model.clean()`. +The second step ``full_clean()`` performs is to call :meth:`Model.clean`. This method should be overridden to perform custom validation on your model. .. method:: Model.clean() @@ -306,8 +306,8 @@ access to more than a single field:: if self.status == "published" and self.pub_date is None: self.pub_date = datetime.date.today() -Note, however, that like :meth:`Model.full_clean()`, a model's ``clean()`` -method is not invoked when you call your model's :meth:`~Model.save()` method. +Note, however, that like :meth:`Model.full_clean`, a model's ``clean()`` +method is not invoked when you call your model's :meth:`~Model.save` method. In the above example, the :exc:`~django.core.exceptions.ValidationError` exception raised by ``Model.clean()`` was instantiated with a string, so it @@ -582,10 +582,10 @@ Forcing an INSERT or UPDATE ~~~~~~~~~~~~~~~~~~~~~~~~~~~ In some rare circumstances, it's necessary to be able to force the -:meth:`~Model.save()` method to perform an SQL ``INSERT`` and not fall back to +:meth:`~Model.save` method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``. Or vice-versa: update, if possible, but not insert a new row. In these cases you can pass the ``force_insert=True`` or -``force_update=True`` parameters to the :meth:`~Model.save()` method. +``force_update=True`` parameters to the :meth:`~Model.save` method. Passing both parameters is an error: you cannot both insert *and* update at the same time! @@ -672,8 +672,8 @@ perform an update on all fields. Specifying ``update_fields`` will force an update. When saving a model fetched through deferred model loading -(:meth:`~django.db.models.query.QuerySet.only()` or -:meth:`~django.db.models.query.QuerySet.defer()`) only the fields loaded +(:meth:`~django.db.models.query.QuerySet.only` or +:meth:`~django.db.models.query.QuerySet.defer`) only the fields loaded from the DB will get updated. In effect there is an automatic ``update_fields`` in this case. If you assign or change any deferred field value, the field will be added to the updated fields. @@ -894,7 +894,7 @@ track down every place that the URL might be created. Specify it once, in Extra instance methods ====================== -In addition to :meth:`~Model.save()`, :meth:`~Model.delete()`, a model object +In addition to :meth:`~Model.save`, :meth:`~Model.delete`, a model object might have some of the following methods: .. method:: Model.get_FOO_display() diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index 30fa3cc374..fce426ac97 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -382,7 +382,7 @@ not be looking at your Django code. For example:: .. attribute:: Options.select_on_save Determines if Django will use the pre-1.6 - :meth:`django.db.models.Model.save()` algorithm. The old algorithm + :meth:`django.db.models.Model.save` algorithm. The old algorithm uses ``SELECT`` to determine if there is an existing row to be updated. The new algorithm tries an ``UPDATE`` directly. In some rare cases the ``UPDATE`` of an existing row isn't visible to Django. An example is the @@ -393,7 +393,7 @@ not be looking at your Django code. For example:: Usually there is no need to set this attribute. The default is ``False``. - See :meth:`django.db.models.Model.save()` for more about the old and + See :meth:`django.db.models.Model.save` for more about the old and new saving algorithm. ``indexes`` diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index ef6ceb36ad..fc568422b6 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -166,7 +166,7 @@ Here's the formal declaration of a ``QuerySet``: .. attribute:: ordered ``True`` if the ``QuerySet`` is ordered — i.e. has an - :meth:`order_by()` clause or a default ordering on the model. + :meth:`order_by` clause or a default ordering on the model. ``False`` otherwise. .. attribute:: db @@ -401,7 +401,7 @@ expression:: (``nulls_first`` and ``nulls_last``) that control how null values are sorted. Be cautious when ordering by fields in related models if you are also using -:meth:`distinct()`. See the note in :meth:`distinct` for an explanation of how +:meth:`distinct`. See the note in :meth:`distinct` for an explanation of how related model ordering can change the expected results. .. note:: @@ -445,7 +445,7 @@ ordering:: Entry.objects.order_by(Lower("headline").desc()) If you don't want any ordering to be applied to a query, not even the default -ordering, call :meth:`order_by()` with no parameters. +ordering, call :meth:`order_by` with no parameters. You can tell if a query is ordered or not by checking the :attr:`.QuerySet.ordered` attribute, which will be ``True`` if the @@ -490,7 +490,7 @@ efficiently in SQL. Also, note that ``reverse()`` should generally only be called on a ``QuerySet`` which has a defined ordering (e.g., when querying against a model which defines -a default ordering, or when using :meth:`order_by()`). If no such ordering is +a default ordering, or when using :meth:`order_by`). If no such ordering is defined for a given ``QuerySet``, calling ``reverse()`` on it has no real effect (the ordering was undefined prior to calling ``reverse()``, and will remain undefined afterward). @@ -518,14 +518,14 @@ query spans multiple tables, it's possible to get duplicate results when a don't appear in the returned results (they are only there to support ordering), it sometimes looks like non-distinct results are being returned. - Similarly, if you use a :meth:`values()` query to restrict the columns - selected, the columns used in any :meth:`order_by()` (or default model + Similarly, if you use a :meth:`values` query to restrict the columns + selected, the columns used in any :meth:`order_by` (or default model ordering) will still be involved and may affect uniqueness of the results. The moral here is that if you are using ``distinct()`` be careful about ordering by related models. Similarly, when using ``distinct()`` and - :meth:`values()` together, be careful when ordering by fields not in the - :meth:`values()` call. + :meth:`values` together, be careful when ordering by fields not in the + :meth:`values` call. On PostgreSQL only, you can pass positional arguments (``*fields``) in order to specify the names of fields to which the ``DISTINCT`` should apply. This @@ -675,17 +675,17 @@ A few subtleties that are worth mentioning: >>> Entry.objects.values("blog_id") -* When using ``values()`` together with :meth:`distinct()`, be aware that +* When using ``values()`` together with :meth:`distinct`, be aware that ordering can affect the results. See the note in :meth:`distinct` for details. -* If you use a ``values()`` clause after an :meth:`extra()` call, - any fields defined by a ``select`` argument in the :meth:`extra()` must - be explicitly included in the ``values()`` call. Any :meth:`extra()` call +* If you use a ``values()`` clause after an :meth:`extra` call, + any fields defined by a ``select`` argument in the :meth:`extra` must + be explicitly included in the ``values()`` call. Any :meth:`extra` call made after a ``values()`` call will have its extra selected fields ignored. -* Calling :meth:`only()` and :meth:`defer()` after ``values()`` doesn't make +* Calling :meth:`only` and :meth:`defer` after ``values()`` doesn't make sense, so doing so will raise a ``TypeError``. * Combining transforms and aggregates requires the use of two :meth:`annotate` @@ -998,7 +998,7 @@ resulting ``QuerySet``. For example: In addition, only ``LIMIT``, ``OFFSET``, ``COUNT(*)``, ``ORDER BY``, and specifying columns (i.e. slicing, :meth:`count`, :meth:`exists`, -:meth:`order_by`, and :meth:`values()`/:meth:`values_list()`) are allowed +:meth:`order_by`, and :meth:`values`/:meth:`values_list`) are allowed on the resulting ``QuerySet``. Further, databases place restrictions on what operations are allowed in the combined queries. For example, most databases don't allow ``LIMIT`` or ``OFFSET`` in the combined queries. @@ -1363,7 +1363,7 @@ This can be used to change the default ordering of the queryset: ... Prefetch("pizzas__toppings", queryset=Toppings.objects.order_by("name")) ... ) -Or to call :meth:`~django.db.models.query.QuerySet.select_related()` when +Or to call :meth:`~django.db.models.query.QuerySet.select_related` when applicable to reduce the number of queries even further: .. code-block:: pycon @@ -1418,7 +1418,7 @@ less ambiguous than storing a filtered result in the related manager's cache: Custom prefetching also works with single related relations like forward ``ForeignKey`` or ``OneToOneField``. Generally you'll want to use -:meth:`select_related()` for these relations, but there are a number of cases +:meth:`select_related` for these relations, but there are a number of cases where prefetching with a custom ``QuerySet`` is useful: * You want to use a ``QuerySet`` that performs further prefetching @@ -1665,7 +1665,7 @@ of the arguments is required, but you should use at least one of them. fields or tables you have included via ``extra()`` use the ``order_by`` parameter to ``extra()`` and pass in a sequence of strings. These strings should either be model fields (as in the normal - :meth:`order_by()` method on querysets), of the form + :meth:`order_by` method on querysets), of the form ``table_name.column_name`` or an alias for a column that you specified in the ``select`` parameter to ``extra()``. @@ -1753,7 +1753,7 @@ Calling ``defer()`` with a field name that has already been deferred is harmless (the field will still be deferred). You can defer loading of fields in related models (if the related models are -loading via :meth:`select_related()`) by using the standard double-underscore +loading via :meth:`select_related`) by using the standard double-underscore notation to separate related fields:: Blog.objects.select_related().defer("entry__headline", "entry__body") @@ -1766,18 +1766,18 @@ to ``defer()``:: Some fields in a model won't be deferred, even if you ask for them. You can never defer the loading of the primary key. If you are using -:meth:`select_related()` to retrieve related models, you shouldn't defer the +:meth:`select_related` to retrieve related models, you shouldn't defer the loading of the field that connects from the primary model to the related one, doing so will result in an error. -Similarly, calling ``defer()`` (or its counterpart :meth:`only()`) including an -argument from an aggregation (e.g. using the result of :meth:`annotate()`) +Similarly, calling ``defer()`` (or its counterpart :meth:`only`) including an +argument from an aggregation (e.g. using the result of :meth:`annotate`) doesn't make sense: doing so will raise an exception. The aggregated values will always be fetched into the resulting queryset. .. note:: - The ``defer()`` method (and its cousin, :meth:`only()`, below) are only for + The ``defer()`` method (and its cousin, :meth:`only`, below) are only for advanced use-cases. They provide an optimization for when you have analyzed your queries closely and understand *exactly* what information you need and have measured that the difference between returning the fields you need and @@ -1824,9 +1824,9 @@ will always be fetched into the resulting queryset. .. note:: - When calling :meth:`~django.db.models.Model.save()` for instances with + When calling :meth:`~django.db.models.Model.save` for instances with deferred fields, only the loaded fields will be saved. See - :meth:`~django.db.models.Model.save()` for more details. + :meth:`~django.db.models.Model.save` for more details. ``only()`` ~~~~~~~~~~ @@ -1880,9 +1880,9 @@ are in your ``only()`` call. .. note:: - When calling :meth:`~django.db.models.Model.save()` for instances with + When calling :meth:`~django.db.models.Model.save` for instances with deferred fields, only the loaded fields will be saved. See - :meth:`~django.db.models.Model.save()` for more details. + :meth:`~django.db.models.Model.save` for more details. .. note:: @@ -2014,7 +2014,7 @@ raised if ``select_for_update()`` is used in autocommit mode. Although ``select_for_update()`` normally fails in autocommit mode, since :class:`~django.test.TestCase` automatically wraps each test in a transaction, calling ``select_for_update()`` in a ``TestCase`` even outside - an :func:`~django.db.transaction.atomic()` block will (perhaps unexpectedly) + an :func:`~django.db.transaction.atomic` block will (perhaps unexpectedly) pass without raising a ``TransactionManagementError``. To properly test ``select_for_update()`` you should use :class:`~django.test.TransactionTestCase`. @@ -2245,7 +2245,7 @@ example can be rewritten using ``get_or_create()`` like so:: ) Any keyword arguments passed to ``get_or_create()`` — *except* an optional one -called ``defaults`` — will be used in a :meth:`get()` call. If an object is +called ``defaults`` — will be used in a :meth:`get` call. If an object is found, ``get_or_create()`` returns a tuple of that object and ``False``. .. warning:: @@ -2293,7 +2293,7 @@ If you have a field named ``defaults`` and want to use it as an exact lookup in Foo.objects.get_or_create(defaults__exact="bar", defaults={"defaults": "baz"}) -The ``get_or_create()`` method has similar error behavior to :meth:`create()` +The ``get_or_create()`` method has similar error behavior to :meth:`create` when you're using manually specified primary keys. If an object needs to be created and the key already exists in the database, an :exc:`~django.db.IntegrityError` will be raised. @@ -2712,7 +2712,7 @@ If your model's :ref:`Meta ` specifies ``earliest()`` or ``latest()``. The fields specified in :attr:`~django.db.models.Options.get_latest_by` will be used by default. -Like :meth:`get()`, ``earliest()`` and ``latest()`` raise +Like :meth:`get`, ``earliest()`` and ``latest()`` raise :exc:`~django.db.models.Model.DoesNotExist` if there is no object with the given parameters. @@ -2774,7 +2774,7 @@ equivalent to the above example:: *Asynchronous version*: ``alast()`` -Works like :meth:`first()`, but returns the last object in the queryset. +Works like :meth:`first`, but returns the last object in the queryset. ``aggregate()`` ~~~~~~~~~~~~~~~ @@ -2975,8 +2975,8 @@ does not call any ``save()`` methods on your models, nor does it emit the :attr:`~django.db.models.signals.post_save` signals (which are a consequence of calling :meth:`Model.save() `). If you want to update a bunch of records for a model that has a custom -:meth:`~django.db.models.Model.save()` method, loop over them and call -:meth:`~django.db.models.Model.save()`, like this:: +:meth:`~django.db.models.Model.save` method, loop over them and call +:meth:`~django.db.models.Model.save`, like this:: for e in Entry.objects.filter(pub_date__year=2010): e.comments_on = False @@ -3130,8 +3130,8 @@ there are triggers or if a function is called, even for a ``SELECT`` query. ----------------- Field lookups are how you specify the meat of an SQL ``WHERE`` clause. They're -specified as keyword arguments to the ``QuerySet`` methods :meth:`filter()`, -:meth:`exclude()` and :meth:`get()`. +specified as keyword arguments to the ``QuerySet`` methods :meth:`filter`, +:meth:`exclude` and :meth:`get`. For an introduction, see :ref:`models and database queries documentation `. @@ -4157,11 +4157,11 @@ such as ``|`` (``OR``), ``&`` (``AND``), and ``^`` (``XOR``). See .. class:: Prefetch(lookup, queryset=None, to_attr=None) The ``Prefetch()`` object can be used to control the operation of -:meth:`~django.db.models.query.QuerySet.prefetch_related()`. +:meth:`~django.db.models.query.QuerySet.prefetch_related`. The ``lookup`` argument describes the relations to follow and works the same as the string based lookups passed to -:meth:`~django.db.models.query.QuerySet.prefetch_related()`. For example: +:meth:`~django.db.models.query.QuerySet.prefetch_related`. For example: .. code-block:: pycon @@ -4175,7 +4175,7 @@ as the string based lookups passed to The ``queryset`` argument supplies a base ``QuerySet`` for the given lookup. This is useful to further filter down the prefetch operation, or to call -:meth:`~django.db.models.query.QuerySet.select_related()` from the prefetched +:meth:`~django.db.models.query.QuerySet.select_related` from the prefetched relation, hence reducing the number of queries even further: .. code-block:: pycon @@ -4243,7 +4243,7 @@ overridden by using a custom queryset in a related lookup. A :class:`~django.db.models.Q` object to control the filtering. -``FilteredRelation`` is used with :meth:`~.QuerySet.annotate()` to create an +``FilteredRelation`` is used with :meth:`~.QuerySet.annotate` to create an ``ON`` clause when a ``JOIN`` is performed. It doesn't act on the default relationship but on the annotation name (``pizzas_vegetarian`` in example below). diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index f941b435cc..2abe90c68c 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -132,7 +132,7 @@ Related objects reference >>> e = Entry.objects.get(id=234) >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b. - Similar to :meth:`add()`, ``e.save()`` is called in the example above + Similar to :meth:`add`, ``e.save()`` is called in the example above to perform the update. Using ``remove()`` with a many-to-many relationship, however, will delete the relationships using :meth:`QuerySet.delete()` which diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 9354505a9f..21848494f7 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -225,7 +225,7 @@ application. .. attribute:: HttpRequest.current_app The :ttag:`url` template tag will use its value as the ``current_app`` - argument to :func:`~django.urls.reverse()`. + argument to :func:`~django.urls.reverse`. .. attribute:: HttpRequest.urlconf @@ -264,7 +264,7 @@ middleware class is listed in :setting:`MIDDLEWARE`. From the :class:`~django.contrib.sites.middleware.CurrentSiteMiddleware`: An instance of :class:`~django.contrib.sites.models.Site` or :class:`~django.contrib.sites.requests.RequestSite` as returned by - :func:`~django.contrib.sites.shortcuts.get_current_site()` + :func:`~django.contrib.sites.shortcuts.get_current_site` representing the current site. .. attribute:: HttpRequest.user @@ -310,7 +310,7 @@ Methods :setting:`ALLOWED_HOSTS` or the domain name is invalid according to :rfc:`1034`/:rfc:`1035 <1035>`. - .. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is + .. note:: The :meth:`~HttpRequest.get_host` method fails when the host is behind multiple proxies. One solution is to use middleware to rewrite the proxy headers, as in the following example:: @@ -337,7 +337,7 @@ Methods return self.get_response(request) This middleware should be positioned before any other middleware that - relies on the value of :meth:`~HttpRequest.get_host()` -- for instance, + relies on the value of :meth:`~HttpRequest.get_host` -- for instance, :class:`~django.middleware.common.CommonMiddleware` or :class:`~django.middleware.csrf.CsrfViewMiddleware`. @@ -381,7 +381,7 @@ Methods .. note:: Mixing HTTP and HTTPS on the same site is discouraged, therefore - :meth:`~HttpRequest.build_absolute_uri()` will always generate an + :meth:`~HttpRequest.build_absolute_uri` will always generate an absolute URI with the same scheme the current request has. If you need to redirect users to HTTPS, it's best to let your web server redirect all HTTP traffic to HTTPS. @@ -692,7 +692,7 @@ In addition, ``QueryDict`` has the following methods: .. method:: QueryDict.lists() - Like :meth:`items()`, except it includes all values, as a list, for each + Like :meth:`items`, except it includes all values, as a list, for each member of the dictionary. For example: .. code-block:: pycon @@ -1040,7 +1040,7 @@ Methods .. method:: HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None) - Like :meth:`~HttpResponse.set_cookie()`, but + Like :meth:`~HttpResponse.set_cookie`, but :doc:`cryptographic signing ` the cookie before setting it. Use in conjunction with :meth:`HttpRequest.get_signed_cookie`. You can use the optional ``salt`` argument for added key strength, but diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 133916f60a..7bb836f42d 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -90,7 +90,7 @@ strips when performing host validation. If the ``Host`` header (or ``X-Forwarded-Host`` if :setting:`USE_X_FORWARDED_HOST` is enabled) does not match any value in this -list, the :meth:`django.http.HttpRequest.get_host()` method will raise +list, the :meth:`django.http.HttpRequest.get_host` method will raise :exc:`~django.core.exceptions.SuspiciousOperation`. When :setting:`DEBUG` is ``True`` and ``ALLOWED_HOSTS`` is empty, the host @@ -99,7 +99,7 @@ is validated against ``['.localhost', '127.0.0.1', '[::1]']``. ``ALLOWED_HOSTS`` is also :ref:`checked when running tests `. -This validation only applies via :meth:`~django.http.HttpRequest.get_host()`; +This validation only applies via :meth:`~django.http.HttpRequest.get_host`; if your code accesses the ``Host`` header directly from ``request.META`` you are bypassing this security protection. @@ -1684,7 +1684,7 @@ If not ``None``, this will be used as the value of the ``SCRIPT_NAME`` environment variable in any HTTP request. This setting can be used to override the server-provided value of ``SCRIPT_NAME``, which may be a rewritten version of the preferred value or not supplied at all. It is also used by -:func:`django.setup()` to set the URL resolver script prefix outside of the +:func:`django.setup` to set the URL resolver script prefix outside of the request/response cycle (e.g. in management commands and standalone scripts) to generate correct URLs when ``FORCE_SCRIPT_NAME`` is provided. @@ -2292,7 +2292,7 @@ The secret key is used for: * All :doc:`sessions ` if you are using any other session backend than ``django.contrib.sessions.backends.cache``, or are using the default - :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()`. + :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash`. * All :doc:`messages ` if you are using :class:`~django.contrib.messages.storage.cookie.CookieStorage` or :class:`~django.contrib.messages.storage.fallback.FallbackStorage`. @@ -2648,7 +2648,7 @@ protocol. .. admonition:: Why are my emails sent from a different address? This address is used only for error messages. It is *not* the address that - regular email messages sent with :meth:`~django.core.mail.send_mail()` + regular email messages sent with :meth:`~django.core.mail.send_mail` come from; for that, see :setting:`DEFAULT_FROM_EMAIL`. .. setting:: SHORT_DATE_FORMAT diff --git a/docs/ref/template-response.txt b/docs/ref/template-response.txt index a9b9feeb59..e36ed0cef9 100644 --- a/docs/ref/template-response.txt +++ b/docs/ref/template-response.txt @@ -33,7 +33,7 @@ Attributes The name of the template to be rendered. Accepts a backend-dependent template object (such as those returned by - :func:`~django.template.loader.get_template()`), the name of a template, + :func:`~django.template.loader.get_template`), the name of a template, or a list of template names. Example: ``['foo.html', 'path/to/bar.html']`` @@ -65,7 +65,7 @@ Methods ``template`` A backend-dependent template object (such as those returned by - :func:`~django.template.loader.get_template()`), the name of a template, + :func:`~django.template.loader.get_template`), the name of a template, or a list of template names. ``context`` @@ -105,7 +105,7 @@ Methods Resolves the template instance to use for rendering. Accepts a backend-dependent template object (such as those returned by - :func:`~django.template.loader.get_template()`), the name of a template, + :func:`~django.template.loader.get_template`), the name of a template, or a list of template names. Returns the backend-dependent template object instance to be rendered. @@ -163,7 +163,7 @@ Methods ``template`` A backend-dependent template object (such as those returned by - :func:`~django.template.loader.get_template()`), the name of a template, + :func:`~django.template.loader.get_template`), the name of a template, or a list of template names. ``context`` @@ -203,7 +203,7 @@ There are three circumstances under which a ``TemplateResponse`` will be rendered: * When the ``TemplateResponse`` instance is explicitly rendered, using - the :meth:`SimpleTemplateResponse.render()` method. + the :meth:`SimpleTemplateResponse.render` method. * When the content of the response is explicitly set by assigning ``response.content``. @@ -293,7 +293,7 @@ Using ``TemplateResponse`` and ``SimpleTemplateResponse`` A :class:`TemplateResponse` object can be used anywhere that a normal :class:`django.http.HttpResponse` can be used. It can also be used as an -alternative to calling :func:`~django.shortcuts.render()`. +alternative to calling :func:`~django.shortcuts.render`. For example, the following view returns a :class:`TemplateResponse` with a template and a context containing a queryset:: diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index dfd10b19db..087e349c95 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -150,7 +150,7 @@ URL from an :rfc:`IRI <3987>` -- very loosely speaking, a :rfc:`URI <3986>` that can contain Unicode characters. Use these functions for quoting and converting an IRI to a URI: -* The :func:`django.utils.encoding.iri_to_uri()` function, which implements the +* The :func:`django.utils.encoding.iri_to_uri` function, which implements the conversion from IRI to URI as required by :rfc:`3987#section-3.1`. * The :func:`urllib.parse.quote` and :func:`urllib.parse.quote_plus` @@ -192,7 +192,7 @@ you can construct your IRI without worrying about whether it contains non-ASCII characters and then, right at the end, call ``iri_to_uri()`` on the result. -Similarly, Django provides :func:`django.utils.encoding.uri_to_iri()` which +Similarly, Django provides :func:`django.utils.encoding.uri_to_iri` which implements the conversion from URI to IRI as per :rfc:`3987#section-3.2`. An example to demonstrate: diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt index ac55bde575..676350c44f 100644 --- a/docs/ref/urls.txt +++ b/docs/ref/urls.txt @@ -29,7 +29,7 @@ Returns an element for inclusion in ``urlpatterns``. For example:: --------- The ``route`` argument should be a string or -:func:`~django.utils.translation.gettext_lazy()` (see +:func:`~django.utils.translation.gettext_lazy` (see :ref:`translating-urlpatterns`) that contains a URL pattern. The string may contain angle brackets (like ```` above) to capture part of the URL and send it as a keyword argument to the view. The angle brackets may @@ -93,7 +93,7 @@ Returns an element for inclusion in ``urlpatterns``. For example:: ] The ``route`` argument should be a string or -:func:`~django.utils.translation.gettext_lazy()` (see +:func:`~django.utils.translation.gettext_lazy` (see :ref:`translating-urlpatterns`) that contains a regular expression compatible with Python's :py:mod:`re` module. Strings typically use raw string syntax (``r''``) so that they can contain sequences like ``\d`` without the need to @@ -107,7 +107,7 @@ When a ``route`` ends with ``$`` the whole requested URL, matching against pattern (:py:func:`re.fullmatch` is used). The ``view``, ``kwargs`` and ``name`` arguments are the same as for -:func:`~django.urls.path()`. +:func:`~django.urls.path`. ``include()`` ============= @@ -143,7 +143,7 @@ See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`. .. function:: register_converter(converter, type_name) -The function for registering a converter for use in :func:`~django.urls.path()` +The function for registering a converter for use in :func:`~django.urls.path` ``route``\s. The ``converter`` argument is a converter class, and ``type_name`` is the diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 63f98dc2c3..18c5681515 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -348,7 +348,7 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004 An optional string containing the MIME type of the stylesheet. If not specified, Django will attempt to guess it by using Python's - :py:func:`mimetypes.guess_type()`. Use ``mimetype=None`` if you don't + :py:func:`mimetypes.guess_type`. Use ``mimetype=None`` if you don't want your stylesheet to have a MIME type specified. .. attribute:: media @@ -977,10 +977,10 @@ appropriate entities. .. function:: override(timezone) This is a Python context manager that sets the :ref:`current time zone - ` on entry with :func:`activate()`, and restores + ` on entry with :func:`activate`, and restores the previously active time zone on exit. If the ``timezone`` argument is ``None``, the :ref:`current time zone ` is unset - on entry with :func:`deactivate()` instead. + on entry with :func:`deactivate` instead. ``override`` is also usable as a function decorator. @@ -1133,8 +1133,8 @@ For a complete discussion on the usage of the following see the .. function:: get_language() Returns the currently selected language code. Returns ``None`` if - translations are temporarily deactivated (by :func:`deactivate_all()` or - when ``None`` is passed to :func:`override()`). + translations are temporarily deactivated (by :func:`deactivate_all` or + when ``None`` is passed to :func:`override`). .. function:: get_language_bidi() diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt index 8a4e9be161..a2bc457a8d 100644 --- a/docs/releases/1.10.txt +++ b/docs/releases/1.10.txt @@ -445,8 +445,8 @@ Requests and Responses * Added ``request.user`` to the debug view. * Added :class:`~django.http.HttpResponse` methods - :meth:`~django.http.HttpResponse.readable()` and - :meth:`~django.http.HttpResponse.seekable()` to make an instance a + :meth:`~django.http.HttpResponse.readable` and + :meth:`~django.http.HttpResponse.seekable` to make an instance a stream-like object and allow wrapping it with :py:class:`io.TextIOWrapper`. * Added the :attr:`HttpRequest.content_type @@ -498,7 +498,7 @@ Tests URLs ~~~~ -* An addition in :func:`django.setup()` allows URL resolving that happens +* An addition in :func:`django.setup` allows URL resolving that happens outside of the request/response cycle (e.g. in management commands and standalone scripts) to take :setting:`FORCE_SCRIPT_NAME` into account when it is set. @@ -839,9 +839,9 @@ Miscellaneous in :setting:`AUTHENTICATION_BACKENDS` instead. * In light of the previous change, the test client's - :meth:`~django.test.Client.login()` method no longer always rejects inactive + :meth:`~django.test.Client.login` method no longer always rejects inactive users but instead delegates this decision to the authentication backend. - :meth:`~django.test.Client.force_login()` also delegates the decision to the + :meth:`~django.test.Client.force_login` also delegates the decision to the authentication backend, so if you're using the default backends, you need to use an active user. @@ -1317,7 +1317,7 @@ to remove usage of these features. :func:`~django.template.loader.get_template` and :func:`~django.template.loader.select_template` no longer accept a :class:`~django.template.Context` in their - :meth:`~django.template.backends.base.Template.render()` method. + :meth:`~django.template.backends.base.Template.render` method. * :doc:`Template response APIs ` enforce the use of :class:`dict` and backend-dependent template objects instead of diff --git a/docs/releases/1.11.1.txt b/docs/releases/1.11.1.txt index 382fedba2c..60a78b4c1a 100644 --- a/docs/releases/1.11.1.txt +++ b/docs/releases/1.11.1.txt @@ -9,7 +9,7 @@ Django 1.11.1 adds a minor feature and fixes several bugs in 1.11. Allowed disabling server-side cursors on PostgreSQL =================================================== -The change in Django 1.11 to make :meth:`.QuerySet.iterator()` use server-side +The change in Django 1.11 to make :meth:`.QuerySet.iterator` use server-side cursors on PostgreSQL prevents running Django with PgBouncer in transaction pooling mode. To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS ` setting in :setting:`DATABASES`. diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt index a178257cd0..4eb244c336 100644 --- a/docs/releases/1.11.txt +++ b/docs/releases/1.11.txt @@ -249,14 +249,14 @@ CSRF Database backends ~~~~~~~~~~~~~~~~~ -* Added the ``skip_locked`` argument to :meth:`.QuerySet.select_for_update()` +* Added the ``skip_locked`` argument to :meth:`.QuerySet.select_for_update` on PostgreSQL 9.5+ and Oracle to execute queries with ``FOR UPDATE SKIP LOCKED``. * Added the :setting:`TEST['TEMPLATE'] ` setting to let PostgreSQL users specify a template for creating the test database. -* :meth:`.QuerySet.iterator()` now uses `server-side cursors`_ on PostgreSQL. +* :meth:`.QuerySet.iterator` now uses `server-side cursors`_ on PostgreSQL. This feature transfers some of the worker memory load (used to hold query results) to the database and might increase database memory usage. @@ -646,7 +646,7 @@ described in :ref:`writing your own migration operation Server-side cursors on PostgreSQL --------------------------------- -The change to make :meth:`.QuerySet.iterator()` use server-side cursors on +The change to make :meth:`.QuerySet.iterator` use server-side cursors on PostgreSQL prevents running Django with PgBouncer in transaction pooling mode. To reallow that, use the :setting:`DISABLE_SERVER_SIDE_CURSORS ` setting (added in Django 1.11.1) in diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt index 526bb1d66e..6666596872 100644 --- a/docs/releases/1.2.txt +++ b/docs/releases/1.2.txt @@ -878,7 +878,7 @@ of an SMTPConnection:: messages = get_notification_email() connection.send_messages(messages) -...should now call :meth:`~django.core.mail.get_connection()` to +...should now call :meth:`~django.core.mail.get_connection` to instantiate a generic email connection:: from django.core.mail import get_connection @@ -900,7 +900,7 @@ SMTP connection:: If your call to construct an instance of ``SMTPConnection`` required additional arguments, those arguments can be passed to the -:meth:`~django.core.mail.get_connection()` call:: +:meth:`~django.core.mail.get_connection` call:: connection = get_connection( "django.core.mail.backends.smtp.EmailBackend", hostname="localhost", port=1234 diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 46bd886c67..52780d548b 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -292,8 +292,8 @@ requests. These include: * Support for HttpOnly_ cookies. -* :meth:`~django.core.mail.mail_admins()` and - :meth:`~django.core.mail.mail_managers()` now support easily attaching +* :meth:`~django.core.mail.mail_admins` and + :meth:`~django.core.mail.mail_managers` now support easily attaching HTML content to messages. * :class:`~django.core.mail.EmailMessage` now supports CC's. @@ -305,7 +305,7 @@ requests. These include: ``takes_context`` argument, making it easier to write simple template tags that require access to template context. -* A new :meth:`~django.shortcuts.render()` shortcut -- an alternative +* A new :meth:`~django.shortcuts.render` shortcut -- an alternative to ``django.shortcuts.render_to_response()`` providing a :class:`~django.template.RequestContext` by default. diff --git a/docs/releases/1.4.12.txt b/docs/releases/1.4.12.txt index 7c7e65a577..4abefdb426 100644 --- a/docs/releases/1.4.12.txt +++ b/docs/releases/1.4.12.txt @@ -10,4 +10,4 @@ Bugfixes ======== * Restored the ability to ``reverse()`` views created using - :func:`functools.partial()` (:ticket:`22486`). + :func:`functools.partial` (:ticket:`22486`). diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index 7f4aca8f28..c5dd134f36 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -1348,7 +1348,7 @@ actually provided the body of the HTTP request. It's been renamed to In previous versions, ``Paginator`` objects used in sitemap classes were cached, which could result in stale site maps. We've removed the caching, so each request to a site map now creates a new Paginator object and calls the -:attr:`~django.contrib.sitemaps.Sitemap.items()` method of the +:attr:`~django.contrib.sitemaps.Sitemap.items` method of the :class:`~django.contrib.sitemaps.Sitemap` subclass. Depending on what your ``items()`` method is doing, this may have a negative performance impact. To mitigate the performance impact, consider using the :doc:`caching diff --git a/docs/releases/1.5.7.txt b/docs/releases/1.5.7.txt index 30611527d7..7e06391ce9 100644 --- a/docs/releases/1.5.7.txt +++ b/docs/releases/1.5.7.txt @@ -10,4 +10,4 @@ Bugfixes ======== * Restored the ability to ``reverse()`` views created using - :func:`functools.partial()` (:ticket:`22486`). + :func:`functools.partial` (:ticket:`22486`). diff --git a/docs/releases/1.5.txt b/docs/releases/1.5.txt index ac3be6cfbd..d756ddc868 100644 --- a/docs/releases/1.5.txt +++ b/docs/releases/1.5.txt @@ -219,8 +219,8 @@ GeoDjango * :class:`~django.contrib.gis.geos.LineString` and :class:`~django.contrib.gis.geos.MultiLineString` GEOS objects now support the - :meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate()` and - :meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods + :meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate` and + :meth:`~django.contrib.gis.geos.GEOSGeometry.project` methods (so-called linear referencing). * The ``wkb`` and ``hex`` properties of @@ -365,7 +365,7 @@ Backwards incompatible changes in 1.5 The new :setting:`ALLOWED_HOSTS` setting validates the request's ``Host`` header and protects against host-poisoning attacks. This setting is now required whenever :setting:`DEBUG` is ``False``, or else -:meth:`django.http.HttpRequest.get_host()` will raise +:meth:`django.http.HttpRequest.get_host` will raise :exc:`~django.core.exceptions.SuspiciousOperation`. For more details see the :setting:`full documentation` for the new setting. @@ -624,7 +624,7 @@ fragile, and must now be changed to be able to run independently. The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present after form validation. When the form doesn't validate, it contains only the fields that passed validation. You should test the success of the validation -with the :meth:`~django.forms.Form.is_valid()` method and not with the +with the :meth:`~django.forms.Form.is_valid` method and not with the presence or absence of the :attr:`~django.forms.Form.cleaned_data` attribute on the form. diff --git a/docs/releases/1.6.3.txt b/docs/releases/1.6.3.txt index 4091e793c5..0b5dbd549b 100644 --- a/docs/releases/1.6.3.txt +++ b/docs/releases/1.6.3.txt @@ -110,7 +110,7 @@ perform appropriate manual type conversions prior to executing queries. ============================================== Historically, queries that use -:meth:`~django.db.models.query.QuerySet.select_for_update()` could be +:meth:`~django.db.models.query.QuerySet.select_for_update` could be executed in autocommit mode, outside of a transaction. Before Django 1.6, Django's automatic transactions mode allowed this to be used to lock records until the next write operation. Django 1.6 introduced diff --git a/docs/releases/1.6.4.txt b/docs/releases/1.6.4.txt index bd437650f6..10e263259a 100644 --- a/docs/releases/1.6.4.txt +++ b/docs/releases/1.6.4.txt @@ -14,7 +14,7 @@ Bugfixes 1.4 (:ticket:`22426`). * Restored the ability to ``reverse()`` views created using - :func:`functools.partial()` (:ticket:`22486`). + :func:`functools.partial` (:ticket:`22486`). * Fixed the ``object_id`` of the ``LogEntry`` that's created after a user password change in the admin (:ticket:`22515`). diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index f066f877c5..5f6f378d20 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -693,7 +693,7 @@ Notably most database backends did fetch all the rows in one go already in 1.5. It is still possible to convert the fetched rows to ``Model`` objects -lazily by using the :meth:`~django.db.models.query.QuerySet.iterator()` +lazily by using the :meth:`~django.db.models.query.QuerySet.iterator` method. :meth:`BoundField.label_tag` now includes the form's :attr:`~django.forms.Form.label_suffix` @@ -941,10 +941,10 @@ Miscellaneous * In Django 1.4 and 1.5, a blank string was unintentionally not considered to be a valid password. This meant - :meth:`~django.contrib.auth.models.User.set_password()` would save a blank + :meth:`~django.contrib.auth.models.User.set_password` would save a blank password as an unusable password like - :meth:`~django.contrib.auth.models.User.set_unusable_password()` does, and - thus :meth:`~django.contrib.auth.models.User.check_password()` always + :meth:`~django.contrib.auth.models.User.set_unusable_password` does, and + thus :meth:`~django.contrib.auth.models.User.check_password` always returned ``False`` for blank passwords. This has been corrected in this release: blank passwords are now valid. diff --git a/docs/releases/1.7.1.txt b/docs/releases/1.7.1.txt index 640dfd3a43..9783921659 100644 --- a/docs/releases/1.7.1.txt +++ b/docs/releases/1.7.1.txt @@ -62,9 +62,9 @@ Bugfixes * Fixed renaming of models with a self-referential many-to-many field (``ManyToManyField('self')``) (:ticket:`23503`). -* Added the :meth:`~django.contrib.admin.InlineModelAdmin.get_extra()`, - :meth:`~django.contrib.admin.InlineModelAdmin.get_max_num()`, and - :meth:`~django.contrib.admin.InlineModelAdmin.get_min_num()` hooks to +* Added the :meth:`~django.contrib.admin.InlineModelAdmin.get_extra`, + :meth:`~django.contrib.admin.InlineModelAdmin.get_max_num`, and + :meth:`~django.contrib.admin.InlineModelAdmin.get_min_num` hooks to :class:`~django.contrib.contenttypes.admin.GenericInlineModelAdmin` (:ticket:`23539`). diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index 87246be6e4..3ab1b0b52a 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -109,7 +109,7 @@ Improvements thus far include: * The name of applications can be customized in the admin with the :attr:`~django.apps.AppConfig.verbose_name` of application configurations. -* The admin automatically calls :func:`~django.contrib.admin.autodiscover()` +* The admin automatically calls :func:`~django.contrib.admin.autodiscover` when Django starts. You can consequently remove this line from your URLconf. @@ -233,9 +233,9 @@ You can specify the ``QuerySet`` used to traverse a given relation or customize the storage location of prefetch results. This enables things like filtering prefetched relations, calling -:meth:`~django.db.models.query.QuerySet.select_related()` from a prefetched +:meth:`~django.db.models.query.QuerySet.select_related` from a prefetched relation, or prefetching the same relation multiple times with different -querysets. See :meth:`~django.db.models.query.QuerySet.prefetch_related()` +querysets. See :meth:`~django.db.models.query.QuerySet.prefetch_related` for more details. Admin shortcuts support time zones @@ -316,7 +316,7 @@ automatically process them. This remains the canonical way of adding errors when possible. However the latter was fiddly and error-prone, since the burden of handling edge cases fell on the user. -The new :meth:`~django.forms.Form.add_error()` method allows adding errors +The new :meth:`~django.forms.Form.add_error` method allows adding errors to specific form fields from anywhere without having to worry about the details such as creating instances of ``django.forms.utils.ErrorList`` or dealing with ``Form.cleaned_data``. This new API replaces manipulating ``Form._errors`` @@ -416,8 +416,8 @@ Minor features ~~~~~~~~~~~~~~~~~~~~~~~~~~ * Any ``**kwargs`` passed to - :meth:`~django.contrib.auth.models.User.email_user()` are passed to the - underlying :meth:`~django.core.mail.send_mail()` call. + :meth:`~django.contrib.auth.models.User.email_user` are passed to the + underlying :meth:`~django.core.mail.send_mail` call. * The :func:`~django.contrib.auth.decorators.permission_required` decorator can take a list of permissions as well as a single permission. @@ -847,9 +847,9 @@ Templates * The following functions now accept a ``dirs`` parameter which is a list or tuple to override ``TEMPLATE_DIRS``: - * :func:`django.template.loader.get_template()` - * :func:`django.template.loader.select_template()` - * :func:`django.shortcuts.render()` + * :func:`django.template.loader.get_template` + * :func:`django.template.loader.select_template` + * :func:`django.shortcuts.render` * ``django.shortcuts.render_to_response()`` * The :tfilter:`time` filter now accepts timezone-related :ref:`format @@ -1252,7 +1252,7 @@ has been set to the more regular ``invalid_login`` key. ---------------------------------------------- Historically, queries that use -:meth:`~django.db.models.query.QuerySet.select_for_update()` could be +:meth:`~django.db.models.query.QuerySet.select_for_update` could be executed in autocommit mode, outside of a transaction. Before Django 1.6, Django's automatic transactions mode allowed this to be used to lock records until the next write operation. Django 1.6 introduced @@ -1296,7 +1296,7 @@ project's needs. You should also check for any code that accesses Miscellaneous ------------- -* The :meth:`django.core.files.uploadhandler.FileUploadHandler.new_file()` +* The :meth:`django.core.files.uploadhandler.FileUploadHandler.new_file` method is now passed an additional ``content_type_extra`` parameter. If you have a custom :class:`~django.core.files.uploadhandler.FileUploadHandler` that implements ``new_file()``, be sure it accepts this new parameter. @@ -1344,7 +1344,7 @@ Miscellaneous #) Use :djadmin:`loaddata` to import the fixtures you exported in (1). * ``django.contrib.auth.models.AbstractUser`` no longer defines a - :meth:`~django.db.models.Model.get_absolute_url()` method. The old definition + :meth:`~django.db.models.Model.get_absolute_url` method. The old definition returned ``"/users/%s/" % urlquote(self.username)`` which was arbitrary since applications may or may not define such a url in ``urlpatterns``. Define a ``get_absolute_url()`` method on your own custom user object or use diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt index d222888cbf..e9dabbbdb7 100644 --- a/docs/releases/1.8.txt +++ b/docs/releases/1.8.txt @@ -123,7 +123,7 @@ initialization at the class level using transactions and savepoints. Database backends which do not support transactions, like MySQL with the MyISAM storage engine, will still be able to run these tests but won't benefit from the improvements. Tests are now run within two nested -:func:`~django.db.transaction.atomic()` blocks: one for the whole class and one +:func:`~django.db.transaction.atomic` blocks: one for the whole class and one for each test. * The class method @@ -242,7 +242,7 @@ Minor features ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Session cookie is now deleted after - :meth:`~django.contrib.sessions.backends.base.SessionBase.flush()` is called. + :meth:`~django.contrib.sessions.backends.base.SessionBase.flush` is called. :mod:`django.contrib.sitemaps` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -327,7 +327,7 @@ Forms * Form widgets now render attributes with a value of ``True`` or ``False`` as HTML5 boolean attributes. -* The new :meth:`~django.forms.Form.has_error()` method allows checking +* The new :meth:`~django.forms.Form.has_error` method allows checking if a specific error has happened. * If :attr:`~django.forms.Form.required_css_class` is defined on a form, then @@ -366,21 +366,21 @@ Generic Views may now specify the ordering applied to the :attr:`~django.views.generic.list.MultipleObjectMixin.queryset` by setting :attr:`~django.views.generic.list.MultipleObjectMixin.ordering` or overriding - :meth:`~django.views.generic.list.MultipleObjectMixin.get_ordering()`. + :meth:`~django.views.generic.list.MultipleObjectMixin.get_ordering`. * The new :attr:`SingleObjectMixin.query_pk_and_slug ` attribute allows changing the behavior of - :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` + :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` so that it'll perform its lookup using both the primary key and the slug. -* The :meth:`~django.views.generic.edit.FormMixin.get_form()` method doesn't +* The :meth:`~django.views.generic.edit.FormMixin.get_form` method doesn't require a ``form_class`` to be provided anymore. If not provided ``form_class`` - defaults to :meth:`~django.views.generic.edit.FormMixin.get_form_class()`. + defaults to :meth:`~django.views.generic.edit.FormMixin.get_form_class`. * Placeholders in :attr:`ModelFormMixin.success_url ` now support the Python - :py:meth:`str.format()` syntax. The legacy ``%()s`` syntax is still + :py:meth:`str.format` syntax. The legacy ``%()s`` syntax is still supported but will be removed in Django 1.10. Internationalization @@ -675,7 +675,7 @@ Related object operations are run in a transaction -------------------------------------------------- Some operations on related objects such as -:meth:`~django.db.models.fields.related.RelatedManager.add()` or direct +:meth:`~django.db.models.fields.related.RelatedManager.add` or direct assignment ran multiple data modifying queries without wrapping them in transactions. To reduce the risk of data corruption, all data modifying methods that affect multiple related objects (i.e. ``add()``, ``remove()``, @@ -1182,7 +1182,7 @@ Miscellaneous this will not happen any longer. It might be that new database migrations are generated (once) after migrating to 1.8. -* :func:`django.utils.translation.get_language()` now returns ``None`` instead +* :func:`django.utils.translation.get_language` now returns ``None`` instead of :setting:`LANGUAGE_CODE` when translations are temporarily deactivated. * When a translation doesn't exist for a specific literal, the fallback is now @@ -1521,10 +1521,10 @@ to construct the "view on site" URL. This URL is now accessible using the sure to provide a default value for the ``form_class`` argument since it's now optional. -Rendering templates loaded by :func:`~django.template.loader.get_template()` with a :class:`~django.template.Context` +Rendering templates loaded by :func:`~django.template.loader.get_template` with a :class:`~django.template.Context` --------------------------------------------------------------------------------------------------------------------- -The return type of :func:`~django.template.loader.get_template()` has changed +The return type of :func:`~django.template.loader.get_template` has changed in Django 1.8: instead of a :class:`django.template.Template`, it returns a ``Template`` instance whose exact type depends on which backend loaded it. @@ -1533,7 +1533,7 @@ Both classes provide a ``render()`` method, however, the former takes a :class:`dict`. This change is enforced through a deprecation path for Django templates. -All this also applies to :func:`~django.template.loader.select_template()`. +All this also applies to :func:`~django.template.loader.select_template`. :class:`~django.template.Template` and :class:`~django.template.Context` classes in template responses ------------------------------------------------------------------------------------------------------ @@ -1589,9 +1589,9 @@ pass a :class:`dict` in the ``context`` parameter instead. If you're passing a The following functions will no longer accept a ``dirs`` parameter to override ``TEMPLATE_DIRS`` in Django 1.10: -* :func:`django.template.loader.get_template()` -* :func:`django.template.loader.select_template()` -* :func:`django.shortcuts.render()` +* :func:`django.template.loader.get_template` +* :func:`django.template.loader.select_template` +* :func:`django.shortcuts.render` * ``django.shortcuts.render_to_response()`` The parameter didn't work consistently across different template loaders and diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt index a692065abb..b37d256d90 100644 --- a/docs/releases/1.9.txt +++ b/docs/releases/1.9.txt @@ -207,7 +207,7 @@ Minor features Django 1.9). * The permission argument of - :func:`~django.contrib.auth.decorators.permission_required()` accepts all + :func:`~django.contrib.auth.decorators.permission_required` accepts all kinds of iterables, not only list and tuples. * The new :class:`~django.contrib.auth.middleware.PersistentRemoteUserMiddleware` @@ -364,7 +364,7 @@ Forms allowing the field widget to be displayed disabled by browsers. * It's now possible to customize bound fields by overriding a field's - :meth:`~django.forms.Field.get_bound_field()` method. + :meth:`~django.forms.Field.get_bound_field` method. Generic Views ~~~~~~~~~~~~~ @@ -642,10 +642,10 @@ Tests * Added the :meth:`json() ` method to test client responses to give access to the response body as JSON. -* Added the :meth:`~django.test.Client.force_login()` method to the test +* Added the :meth:`~django.test.Client.force_login` method to the test client. Use this method to simulate the effect of a user logging into the site while skipping the authentication and verification steps of - :meth:`~django.test.Client.login()`. + :meth:`~django.test.Client.login`. URLs ~~~~ diff --git a/docs/releases/2.0.txt b/docs/releases/2.0.txt index cedf239a54..cc30a64769 100644 --- a/docs/releases/2.0.txt +++ b/docs/releases/2.0.txt @@ -51,7 +51,7 @@ What's new in Django 2.0 Simplified URL routing syntax ----------------------------- -The new :func:`django.urls.path()` function allows a simpler, more readable URL +The new :func:`django.urls.path` function allows a simpler, more readable URL routing syntax. For example, this example from previous Django releases:: url(r"^articles/(?P[0-9]{4})/$", views.year_archive), @@ -266,16 +266,16 @@ Models :class:`~django.db.models.functions.Extract` now works with :class:`~django.db.models.DurationField`. -* Added the ``of`` argument to :meth:`.QuerySet.select_for_update()`, supported +* Added the ``of`` argument to :meth:`.QuerySet.select_for_update`, supported on PostgreSQL and Oracle, to lock only rows from specific tables rather than all selected tables. It may be helpful particularly when - :meth:`~.QuerySet.select_for_update()` is used in conjunction with - :meth:`~.QuerySet.select_related()`. + :meth:`~.QuerySet.select_for_update` is used in conjunction with + :meth:`~.QuerySet.select_related`. * The new ``field_name`` parameter of :meth:`.QuerySet.in_bulk` allows fetching results based on any unique model field. -* :meth:`.CursorWrapper.callproc()` now takes an optional dictionary of keyword +* :meth:`.CursorWrapper.callproc` now takes an optional dictionary of keyword parameters, if the backend supports this feature. Of Django's built-in backends, only Oracle supports it. diff --git a/docs/releases/2.1.15.txt b/docs/releases/2.1.15.txt index bb15f33d17..3c36b6b065 100644 --- a/docs/releases/2.1.15.txt +++ b/docs/releases/2.1.15.txt @@ -47,7 +47,7 @@ Bugfixes ======== * Fixed a data loss possibility in the - :meth:`~django.db.models.query.QuerySet.select_for_update()`. When using + :meth:`~django.db.models.query.QuerySet.select_for_update`. When using ``'self'`` in the ``of`` argument with :ref:`multi-table inheritance `, a parent model was locked instead of the queryset's model (:ticket:`30953`). diff --git a/docs/releases/2.1.txt b/docs/releases/2.1.txt index e4a2788c86..2ed9152e21 100644 --- a/docs/releases/2.1.txt +++ b/docs/releases/2.1.txt @@ -67,7 +67,7 @@ Minor features * The ``admin_order_field`` attribute for elements in :attr:`.ModelAdmin.list_display` may now be a query expression. -* The new :meth:`.ModelAdmin.get_deleted_objects()` method allows customizing +* The new :meth:`.ModelAdmin.get_deleted_objects` method allows customizing the deletion process of the delete view and the "delete selected" action. * The ``actions.html``, ``change_list_results.html``, ``date_hierarchy.html``, diff --git a/docs/releases/2.2.16.txt b/docs/releases/2.2.16.txt index 31231fb065..44c8cf6865 100644 --- a/docs/releases/2.2.16.txt +++ b/docs/releases/2.2.16.txt @@ -28,7 +28,7 @@ Bugfixes ======== * Fixed a data loss possibility in the - :meth:`~django.db.models.query.QuerySet.select_for_update()`. When using + :meth:`~django.db.models.query.QuerySet.select_for_update`. When using related fields pointing to a proxy model in the ``of`` argument, the corresponding model was not locked (:ticket:`31866`). diff --git a/docs/releases/2.2.8.txt b/docs/releases/2.2.8.txt index 857ffff048..5fa1639bc6 100644 --- a/docs/releases/2.2.8.txt +++ b/docs/releases/2.2.8.txt @@ -56,7 +56,7 @@ Bugfixes ``default`` entry was empty (:ticket:`31021`). * Fixed a data loss possibility in the - :meth:`~django.db.models.query.QuerySet.select_for_update()`. When using + :meth:`~django.db.models.query.QuerySet.select_for_update`. When using ``'self'`` in the ``of`` argument with :ref:`multi-table inheritance `, a parent model was locked instead of the queryset's model (:ticket:`30953`). diff --git a/docs/releases/3.0.10.txt b/docs/releases/3.0.10.txt index 0583f8d5aa..52003de055 100644 --- a/docs/releases/3.0.10.txt +++ b/docs/releases/3.0.10.txt @@ -28,7 +28,7 @@ Bugfixes ======== * Fixed a data loss possibility in the - :meth:`~django.db.models.query.QuerySet.select_for_update()`. When using + :meth:`~django.db.models.query.QuerySet.select_for_update`. When using related fields pointing to a proxy model in the ``of`` argument, the corresponding model was not locked (:ticket:`31866`). diff --git a/docs/releases/3.0.txt b/docs/releases/3.0.txt index eb043710c1..3fa3cd8410 100644 --- a/docs/releases/3.0.txt +++ b/docs/releases/3.0.txt @@ -126,9 +126,9 @@ Minor features * Added :class:`~django.contrib.auth.backends.BaseBackend` class to ease customization of authentication backends. -* Added :meth:`~django.contrib.auth.models.User.get_user_permissions()` method +* Added :meth:`~django.contrib.auth.models.User.get_user_permissions` method to mirror the existing - :meth:`~django.contrib.auth.models.User.get_group_permissions()` method. + :meth:`~django.contrib.auth.models.User.get_group_permissions` method. * Added HTML ``autocomplete`` attribute to widgets of username, email, and password fields in :mod:`django.contrib.auth.forms` for better interaction @@ -182,7 +182,7 @@ Minor features ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The new - :meth:`~django.contrib.sessions.backends.base.SessionBase.get_session_cookie_age()` + :meth:`~django.contrib.sessions.backends.base.SessionBase.get_session_cookie_age` method allows dynamically specifying the session cookie age. :mod:`django.contrib.syndication` @@ -190,7 +190,7 @@ Minor features * Added the ``language`` class attribute to the :class:`django.contrib.syndication.views.Feed` to customize a feed language. - The default value is :func:`~django.utils.translation.get_language()` instead + The default value is :func:`~django.utils.translation.get_language` instead of :setting:`LANGUAGE_CODE`. Cache @@ -213,7 +213,7 @@ Forms * Formsets may control the widget used when ordering forms via :attr:`~django.forms.formsets.BaseFormSet.can_order` by setting the :attr:`~django.forms.formsets.BaseFormSet.ordering_widget` attribute or - overriding :attr:`~django.forms.formsets.BaseFormSet.get_ordering_widget()`. + overriding :attr:`~django.forms.formsets.BaseFormSet.get_ordering_widget`. Internationalization ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/3.1.1.txt b/docs/releases/3.1.1.txt index c833807338..32050c31b8 100644 --- a/docs/releases/3.1.1.txt +++ b/docs/releases/3.1.1.txt @@ -40,7 +40,7 @@ Bugfixes rendering (:ticket:`31865`). * Fixed a data loss possibility in the - :meth:`~django.db.models.query.QuerySet.select_for_update()`. When using + :meth:`~django.db.models.query.QuerySet.select_for_update`. When using related fields pointing to a proxy model in the ``of`` argument, the corresponding model was not locked (:ticket:`31866`). diff --git a/docs/releases/3.1.txt b/docs/releases/3.1.txt index 704cf3e6d1..0c2041c5a2 100644 --- a/docs/releases/3.1.txt +++ b/docs/releases/3.1.txt @@ -654,7 +654,7 @@ Miscellaneous :attr:`~django.http.HttpResponse.content`. * ``django.utils.decorators.classproperty()`` decorator is made public and - moved to :class:`django.utils.functional.classproperty()`. + moved to :class:`django.utils.functional.classproperty`. * :tfilter:`floatformat` template filter now outputs (positive) ``0`` for negative numbers which round to zero. diff --git a/docs/releases/3.2.txt b/docs/releases/3.2.txt index 0b695ef19e..9a49075d37 100644 --- a/docs/releases/3.2.txt +++ b/docs/releases/3.2.txt @@ -380,7 +380,7 @@ Migrations Models ~~~~~~ -* The new ``no_key`` parameter for :meth:`.QuerySet.select_for_update()`, +* The new ``no_key`` parameter for :meth:`.QuerySet.select_for_update`, supported on PostgreSQL, allows acquiring weaker locks that don't block the creation of rows that reference locked rows through a foreign key. @@ -400,7 +400,7 @@ Models * :class:`FilteredRelation() ` now supports nested relations. -* The ``of`` argument of :meth:`.QuerySet.select_for_update()` is now allowed +* The ``of`` argument of :meth:`.QuerySet.select_for_update` is now allowed on MySQL 8.0.1+. * :class:`Value() ` expression now @@ -422,7 +422,7 @@ Models * The new :class:`~django.db.models.functions.Collate` function allows filtering and ordering by specified database collations. -* The ``field_name`` argument of :meth:`.QuerySet.in_bulk()` now accepts +* The ``field_name`` argument of :meth:`.QuerySet.in_bulk` now accepts distinct fields if there's only one field specified in :meth:`.QuerySet.distinct`. diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt index 8fb11451a6..c7d63ee293 100644 --- a/docs/releases/4.0.txt +++ b/docs/releases/4.0.txt @@ -324,7 +324,7 @@ Models specifying a value to return when the function is used over an empty result set. -* The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update()` is now +* The ``skip_locked`` argument of :meth:`.QuerySet.select_for_update` is now allowed on MariaDB 10.6+. * :class:`~django.db.models.Lookup` expressions may now be used in ``QuerySet`` diff --git a/docs/releases/4.1.txt b/docs/releases/4.1.txt index 3986774013..8a3a7984a1 100644 --- a/docs/releases/4.1.txt +++ b/docs/releases/4.1.txt @@ -145,7 +145,7 @@ Minor features :mod:`django.contrib.gis` ~~~~~~~~~~~~~~~~~~~~~~~~~ -* The new :meth:`.GEOSGeometry.make_valid()` method allows converting invalid +* The new :meth:`.GEOSGeometry.make_valid` method allows converting invalid geometries to valid ones. * The new ``clone`` argument for :meth:`.GEOSGeometry.normalize` allows diff --git a/docs/releases/4.2.14.txt b/docs/releases/4.2.14.txt index 08523e27fd..57d96c563c 100644 --- a/docs/releases/4.2.14.txt +++ b/docs/releases/4.2.14.txt @@ -17,7 +17,7 @@ brackets. CVE-2024-39329: Username enumeration through timing difference for users with unusable passwords ================================================================================================ -The :meth:`~django.contrib.auth.backends.ModelBackend.authenticate()` method +The :meth:`~django.contrib.auth.backends.ModelBackend.authenticate` method allowed remote attackers to enumerate users via a timing attack involving login requests for users with unusable passwords. diff --git a/docs/releases/5.0.7.txt b/docs/releases/5.0.7.txt index fa1fd41961..7f5c1c478f 100644 --- a/docs/releases/5.0.7.txt +++ b/docs/releases/5.0.7.txt @@ -17,7 +17,7 @@ brackets. CVE-2024-39329: Username enumeration through timing difference for users with unusable passwords ================================================================================================ -The :meth:`~django.contrib.auth.backends.ModelBackend.authenticate()` method +The :meth:`~django.contrib.auth.backends.ModelBackend.authenticate` method allowed remote attackers to enumerate users via a timing attack involving login requests for users with unusable passwords. diff --git a/docs/releases/5.2.txt b/docs/releases/5.2.txt index 20d82db98e..d5ecce48d7 100644 --- a/docs/releases/5.2.txt +++ b/docs/releases/5.2.txt @@ -73,7 +73,7 @@ See :doc:`/topics/composite-primary-key` for more details. Simplified override of :class:`~django.forms.BoundField` -------------------------------------------------------- -Prior to version 5.2, overriding :meth:`.Field.get_bound_field()` was the only +Prior to version 5.2, overriding :meth:`.Field.get_bound_field` was the only option to use a custom :class:`~django.forms.BoundField`. Django now supports specifying the following attributes to customize form rendering: diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt index 4874f199f6..1a713003a3 100644 --- a/docs/topics/auth/customizing.txt +++ b/docs/topics/auth/customizing.txt @@ -46,7 +46,7 @@ Specifying authentication backends Behind the scenes, Django maintains a list of "authentication backends" that it checks for authentication. When somebody calls -:func:`django.contrib.auth.authenticate()` -- as described in :ref:`How to log +:func:`django.contrib.auth.authenticate` -- as described in :ref:`How to log a user in ` -- Django tries authenticating across all of its authentication backends. If the first authentication method fails, Django tries the second one, and so on, until all backends have been attempted. @@ -187,12 +187,12 @@ Handling authorization in custom backends Custom auth backends can provide their own permissions. The user model and its manager will delegate permission lookup functions -(:meth:`~django.contrib.auth.models.User.get_user_permissions()`, -:meth:`~django.contrib.auth.models.User.get_group_permissions()`, -:meth:`~django.contrib.auth.models.User.get_all_permissions()`, -:meth:`~django.contrib.auth.models.User.has_perm()`, -:meth:`~django.contrib.auth.models.User.has_module_perms()`, and -:meth:`~django.contrib.auth.models.UserManager.with_perm()`) to any +(:meth:`~django.contrib.auth.models.User.get_user_permissions`, +:meth:`~django.contrib.auth.models.User.get_group_permissions`, +:meth:`~django.contrib.auth.models.User.get_all_permissions`, +:meth:`~django.contrib.auth.models.User.has_perm`, +:meth:`~django.contrib.auth.models.User.has_module_perms`, and +:meth:`~django.contrib.auth.models.UserManager.with_perm`) to any authentication backend that implements these functions. The permissions given to the user will be the superset of all permissions @@ -200,8 +200,8 @@ returned by all backends. That is, Django grants a permission to a user that any one backend grants. If a backend raises a :class:`~django.core.exceptions.PermissionDenied` -exception in :meth:`~django.contrib.auth.models.User.has_perm()` or -:meth:`~django.contrib.auth.models.User.has_module_perms()`, the authorization +exception in :meth:`~django.contrib.auth.models.User.has_perm` or +:meth:`~django.contrib.auth.models.User.has_module_perms`, the authorization will immediately fail and Django won't check the backends that follow. A backend could implement permissions for the magic admin like this:: @@ -694,7 +694,7 @@ The following attributes and methods are available on any subclass of When the raw_password is ``None``, the password will be set to an unusable password, as if - :meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()` + :meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password` were used. .. method:: models.AbstractBaseUser.check_password(raw_password) @@ -710,7 +710,7 @@ The following attributes and methods are available on any subclass of Marks the user as having no password set. This isn't the same as having a blank string for a password. - :meth:`~django.contrib.auth.models.AbstractBaseUser.check_password()` for this user + :meth:`~django.contrib.auth.models.AbstractBaseUser.check_password` for this user will never return ``True``. Doesn't save the :class:`~django.contrib.auth.models.AbstractBaseUser` object. @@ -720,7 +720,7 @@ The following attributes and methods are available on any subclass of .. method:: models.AbstractBaseUser.has_usable_password() Returns ``False`` if - :meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()` has + :meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password` has been called for this user. .. method:: models.AbstractBaseUser.get_session_auth_hash() diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index 06d7c2fc26..af09c43eb2 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -97,7 +97,7 @@ do not supply a user, the command will attempt to change the password whose username matches the current system user. You can also change a password programmatically, using -:meth:`~django.contrib.auth.models.User.set_password()`: +:meth:`~django.contrib.auth.models.User.set_password`: .. code-block:: pycon @@ -124,7 +124,7 @@ Authenticating users *Asynchronous version*: ``aauthenticate()`` - Use :func:`~django.contrib.auth.authenticate()` to verify a set of + Use :func:`~django.contrib.auth.authenticate` to verify a set of credentials. It takes credentials as keyword arguments, ``username`` and ``password`` for the default case, checks them against each :ref:`authentication backend `, and returns a @@ -410,18 +410,18 @@ If you have an authenticated user you want to attach to the current session *Asynchronous version*: ``alogin()`` - To log a user in, from a view, use :func:`~django.contrib.auth.login()`. It + To log a user in, from a view, use :func:`~django.contrib.auth.login`. It takes an :class:`~django.http.HttpRequest` object and a :class:`~django.contrib.auth.models.User` object. - :func:`~django.contrib.auth.login()` saves the user's ID in the session, + :func:`~django.contrib.auth.login` saves the user's ID in the session, using Django's session framework. Note that any data set during the anonymous session is retained in the session after a user logs in. This example shows how you might use both - :func:`~django.contrib.auth.authenticate()` and - :func:`~django.contrib.auth.login()`:: + :func:`~django.contrib.auth.authenticate` and + :func:`~django.contrib.auth.login`:: from django.contrib.auth import authenticate, login @@ -449,9 +449,9 @@ is selected as follows: #. Use the value of the optional ``backend`` argument, if provided. #. Use the value of the ``user.backend`` attribute, if present. This allows - pairing :func:`~django.contrib.auth.authenticate()` and - :func:`~django.contrib.auth.login()`: - :func:`~django.contrib.auth.authenticate()` + pairing :func:`~django.contrib.auth.authenticate` and + :func:`~django.contrib.auth.login`: + :func:`~django.contrib.auth.authenticate` sets the ``user.backend`` attribute on the user object it returns. #. Use the ``backend`` in :setting:`AUTHENTICATION_BACKENDS`, if there is only one. @@ -470,8 +470,8 @@ How to log a user out *Asynchronous version*: ``alogout()`` To log out a user who has been logged in via - :func:`django.contrib.auth.login()`, use - :func:`django.contrib.auth.logout()` within your view. It takes an + :func:`django.contrib.auth.login`, use + :func:`django.contrib.auth.logout` within your view. It takes an :class:`~django.http.HttpRequest` object and has no return value. Example:: @@ -482,16 +482,16 @@ How to log a user out logout(request) # Redirect to a success page. - Note that :func:`~django.contrib.auth.logout()` doesn't throw any errors if + Note that :func:`~django.contrib.auth.logout` doesn't throw any errors if the user wasn't logged in. - When you call :func:`~django.contrib.auth.logout()`, the session data for + When you call :func:`~django.contrib.auth.logout`, the session data for the current request is completely cleaned out. All existing data is removed. This is to prevent another person from using the same web browser to log in and have access to the previous user's session data. If you want to put anything into the session that will be available to the user immediately after logging out, do that *after* calling - :func:`django.contrib.auth.logout()`. + :func:`django.contrib.auth.logout`. Limiting access to logged-in users ---------------------------------- @@ -769,7 +769,7 @@ The ``permission_required`` decorator It's a relatively common task to check whether a user has a particular permission. For that reason, Django provides a shortcut for that case: the - :func:`~django.contrib.auth.decorators.permission_required()` decorator:: + :func:`~django.contrib.auth.decorators.permission_required` decorator:: from django.contrib.auth.decorators import permission_required @@ -785,7 +785,7 @@ The ``permission_required`` decorator The decorator may also take an iterable of permissions, in which case the user must have all of the permissions in order to access the view. - Note that :func:`~django.contrib.auth.decorators.permission_required()` + Note that :func:`~django.contrib.auth.decorators.permission_required` also takes an optional ``login_url`` parameter:: from django.contrib.auth.decorators import permission_required @@ -856,8 +856,8 @@ To apply permission checks to :doc:`class-based views Returns a boolean denoting whether the current user has permission to execute the decorated view. By default, this returns the result of - calling :meth:`~django.contrib.auth.models.User.has_perms()` with the - list of permissions returned by :meth:`get_permission_required()`. + calling :meth:`~django.contrib.auth.models.User.has_perms` with the + list of permissions returned by :meth:`get_permission_required`. Redirecting unauthorized requests in class-based views ------------------------------------------------------ @@ -930,7 +930,7 @@ Session invalidation on password change If your :setting:`AUTH_USER_MODEL` inherits from :class:`~django.contrib.auth.models.AbstractBaseUser` or implements its own -:meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()` +:meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash` method, authenticated sessions will include the hash returned by this function. In the :class:`~django.contrib.auth.models.AbstractBaseUser` case, this is an HMAC of the password field. Django verifies that the hash in the session for @@ -972,7 +972,7 @@ function. .. note:: Since - :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash()` + :meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash` is based on :setting:`SECRET_KEY`, secret key values must be rotated to avoid invalidating existing sessions when updating your site to use a new secret. See :setting:`SECRET_KEY_FALLBACKS` for details. @@ -1635,10 +1635,10 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`: ``password2`` are non empty and match, validates the password using :func:`~django.contrib.auth.password_validation.validate_password`, and sets the user's password using - :meth:`~django.contrib.auth.models.User.set_password()`. + :meth:`~django.contrib.auth.models.User.set_password`. If ``usable_password`` is disabled, no password validation is done, and password-based authentication is disabled for the user by calling - :meth:`~django.contrib.auth.models.User.set_unusable_password()`. + :meth:`~django.contrib.auth.models.User.set_unusable_password`. .. class:: AuthenticationForm @@ -1696,7 +1696,7 @@ provides several built-in forms located in :mod:`django.contrib.auth.forms`: validates the password using :func:`~django.contrib.auth.password_validation.validate_password`, and sets the user's password using - :meth:`~django.contrib.auth.models.User.set_password()`. + :meth:`~django.contrib.auth.models.User.set_password`. .. class:: PasswordChangeForm diff --git a/docs/topics/class-based-views/generic-editing.txt b/docs/topics/class-based-views/generic-editing.txt index 24b617c418..173f862891 100644 --- a/docs/topics/class-based-views/generic-editing.txt +++ b/docs/topics/class-based-views/generic-editing.txt @@ -71,20 +71,20 @@ they can work out which model class to use: * If the :attr:`~django.views.generic.edit.ModelFormMixin.model` attribute is given, that model class will be used. -* If :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` +* If :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` returns an object, the class of that object will be used. * If a :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` is given, the model for that queryset will be used. Model form views provide a -:meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` implementation +:meth:`~django.views.generic.edit.ModelFormMixin.form_valid` implementation that saves the model automatically. You can override this if you have any special requirements; see below for examples. You don't even need to provide a ``success_url`` for :class:`~django.views.generic.edit.CreateView` or :class:`~django.views.generic.edit.UpdateView` - they will use -:meth:`~django.db.models.Model.get_absolute_url()` on the model object if available. +:meth:`~django.db.models.Model.get_absolute_url` on the model object if available. If you want to use a custom :class:`~django.forms.ModelForm` (for instance to add extra validation), set @@ -95,7 +95,7 @@ add extra validation), set even though the :attr:`~django.views.generic.edit.FormMixin.form_class` may be a :class:`~django.forms.ModelForm`. -First we need to add :meth:`~django.db.models.Model.get_absolute_url()` to our +First we need to add :meth:`~django.db.models.Model.get_absolute_url` to our ``Author`` class: .. code-block:: python @@ -208,7 +208,7 @@ the foreign key relation to the model: In the view, ensure that you don't include ``created_by`` in the list of fields to edit, and override -:meth:`~django.views.generic.edit.ModelFormMixin.form_valid()` to add the user: +:meth:`~django.views.generic.edit.ModelFormMixin.form_valid` to add the user: .. code-block:: python :caption: ``views.py`` @@ -228,7 +228,7 @@ to edit, and override :class:`~django.contrib.auth.mixins.LoginRequiredMixin` prevents users who aren't logged in from accessing the form. If you omit that, you'll need to -handle unauthorized users in :meth:`~.ModelFormMixin.form_valid()`. +handle unauthorized users in :meth:`~.ModelFormMixin.form_valid`. .. _content-negotiation-example: diff --git a/docs/topics/class-based-views/mixins.txt b/docs/topics/class-based-views/mixins.txt index c51c03bd80..bb1a6349dc 100644 --- a/docs/topics/class-based-views/mixins.txt +++ b/docs/topics/class-based-views/mixins.txt @@ -34,7 +34,7 @@ interface to working with templates in class-based views. :class:`~django.views.generic.base.TemplateResponseMixin` Every built in view which returns a :class:`~django.template.response.TemplateResponse` will call the - :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` + :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` method that ``TemplateResponseMixin`` provides. Most of the time this will be called for you (for instance, it is called by the ``get()`` method implemented by both :class:`~django.views.generic.base.TemplateView` and @@ -58,7 +58,7 @@ interface to working with templates in class-based views. :class:`~django.views.generic.base.ContextMixin` Every built in view which needs context data, such as for rendering a template (including ``TemplateResponseMixin`` above), should call - :meth:`~django.views.generic.base.ContextMixin.get_context_data()` passing + :meth:`~django.views.generic.base.ContextMixin.get_context_data` passing any data they want to ensure is in there as keyword arguments. ``get_context_data()`` returns a dictionary; in ``ContextMixin`` it returns its keyword arguments, but it is common to override this to add @@ -106,7 +106,7 @@ URLConf, and looks the object up either from the on the view, or the :attr:`~django.views.generic.detail.SingleObjectMixin.queryset` attribute if that's provided). ``SingleObjectMixin`` also overrides -:meth:`~django.views.generic.base.ContextMixin.get_context_data()`, +:meth:`~django.views.generic.base.ContextMixin.get_context_data`, which is used across all Django's built in class-based views to supply context data for template renders. @@ -115,7 +115,7 @@ To then make a :class:`~django.template.response.TemplateResponse`, :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`, which extends :class:`~django.views.generic.base.TemplateResponseMixin`, overriding -:meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names()` +:meth:`~django.views.generic.base.TemplateResponseMixin.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 @@ -151,7 +151,7 @@ here would be to dynamically vary the objects, such as depending on the current user or to exclude posts in the future for a blog. :class:`~django.views.generic.list.MultipleObjectMixin` also overrides -:meth:`~django.views.generic.base.ContextMixin.get_context_data()` to +:meth:`~django.views.generic.base.ContextMixin.get_context_data` to include appropriate context variables for pagination (providing dummies if pagination is disabled). It relies on ``object_list`` being passed in as a keyword argument, which :class:`ListView` arranges for @@ -296,7 +296,7 @@ object. In order to do this, we need to have two different querysets: override ``get_queryset()`` and use the ``Publisher``’s :ref:`reverse foreign key manager`. -``Publisher`` queryset for use in :meth:`~django.views.generic.detail.SingleObjectMixin.get_object()` +``Publisher`` queryset for use in :meth:`~django.views.generic.detail.SingleObjectMixin.get_object` We'll rely on the default implementation of ``get_object()`` to fetch the correct ``Publisher`` object. However, we need to explicitly pass a ``queryset`` argument because @@ -565,12 +565,12 @@ the author we're talking about, and we have to remember to set return reverse("author-detail", kwargs={"pk": self.object.pk}) Finally we bring this together in a new ``AuthorView`` view. We -already know that calling :meth:`~django.views.generic.base.View.as_view()` on +already know that calling :meth:`~django.views.generic.base.View.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 pass through keyword arguments to -:meth:`~django.views.generic.base.View.as_view()` in the same way you +:meth:`~django.views.generic.base.View.as_view` in the same way you would in your URLconf, such as if you wanted the ``AuthorInterestFormView`` behavior to also appear at another URL but using a different template:: @@ -636,7 +636,7 @@ For example, a JSON mixin might look something like this:: JSON. This mixin provides a ``render_to_json_response()`` method with the same signature -as :func:`~django.views.generic.base.TemplateResponseMixin.render_to_response()`. +as :func:`~django.views.generic.base.TemplateResponseMixin.render_to_response`. To use it, we need to mix it into a ``TemplateView`` for example, and override ``render_to_response()`` to call ``render_to_json_response()`` instead:: @@ -672,7 +672,7 @@ the HTTP request, such as a query argument or an HTTP header. Mix in both the ``JSONResponseMixin`` and a :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`, and override the implementation of -:func:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` +:func:`~django.views.generic.base.TemplateResponseMixin.render_to_response` to defer to the appropriate rendering method depending on the type of response that the user requested:: @@ -691,5 +691,5 @@ that the user requested:: Because of the way that Python resolves method overloading, the call to ``super().render_to_response(context)`` ends up calling the -:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response()` +:meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response` implementation of :class:`~django.views.generic.base.TemplateResponseMixin`. diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 14233cbefd..9360c42109 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -966,7 +966,7 @@ See :ref:`ref-models-update-fields` for more details. .. admonition:: Overridden model methods are not called on bulk operations - Note that the :meth:`~Model.delete()` method for an object is not + Note that the :meth:`~Model.delete` method for an object is not necessarily called when :ref:`deleting objects in bulk using a QuerySet ` or as a result of a :attr:`cascading delete `. To ensure customized @@ -977,7 +977,7 @@ See :ref:`ref-models-update-fields` for more details. Unfortunately, there isn't a workaround when :meth:`creating` or :meth:`updating` objects in bulk, - since none of :meth:`~Model.save()`, + since none of :meth:`~Model.save`, :data:`~django.db.models.signals.pre_save`, and :data:`~django.db.models.signals.post_save` are called. diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt index 8e54ad4ff8..c40456d3f2 100644 --- a/docs/topics/db/optimization.txt +++ b/docs/topics/db/optimization.txt @@ -40,9 +40,9 @@ Use standard DB optimization techniques :attr:`Meta.indexes ` or :attr:`Field.db_index ` to add these from Django. Consider adding indexes to fields that you frequently query using - :meth:`~django.db.models.query.QuerySet.filter()`, - :meth:`~django.db.models.query.QuerySet.exclude()`, - :meth:`~django.db.models.query.QuerySet.order_by()`, etc. as indexes may help + :meth:`~django.db.models.query.QuerySet.filter`, + :meth:`~django.db.models.query.QuerySet.exclude`, + :meth:`~django.db.models.query.QuerySet.order_by`, etc. as indexes may help to speed up lookups. Note that determining the best indexes is a complex database-dependent topic that will depend on your particular application. The overhead of maintaining an index may outweigh any gains in query speed. @@ -115,7 +115,7 @@ Use ``iterator()`` When you have a lot of objects, the caching behavior of the ``QuerySet`` can cause a large amount of memory to be used. In this case, -:meth:`~django.db.models.query.QuerySet.iterator()` may help. +:meth:`~django.db.models.query.QuerySet.iterator` may help. Use ``explain()`` ----------------- @@ -227,7 +227,7 @@ Use ``QuerySet.values()`` and ``values_list()`` When you only want a ``dict`` or ``list`` of values, and don't need ORM model objects, make appropriate usage of -:meth:`~django.db.models.query.QuerySet.values()`. +:meth:`~django.db.models.query.QuerySet.values`. These can be useful for replacing model objects in template code - as long as the dicts you supply have the same attributes as those used in the template, you are fine. @@ -235,8 +235,8 @@ you are fine. Use ``QuerySet.defer()`` and ``only()`` --------------------------------------- -Use :meth:`~django.db.models.query.QuerySet.defer()` and -:meth:`~django.db.models.query.QuerySet.only()` if there are database columns +Use :meth:`~django.db.models.query.QuerySet.defer` and +:meth:`~django.db.models.query.QuerySet.only` if there are database columns you know that you won't need (or won't need in most cases) to avoid loading them. Note that if you *do* use them, the ORM will have to go and get them in a separate query, making this a pessimization if you use it inappropriately. @@ -349,7 +349,7 @@ Ordering is not free; each field to order by is an operation the database must perform. If a model has a default ordering (:attr:`Meta.ordering `) and you don't need it, remove it on a ``QuerySet`` by calling -:meth:`~django.db.models.query.QuerySet.order_by()` with no parameters. +:meth:`~django.db.models.query.QuerySet.order_by` with no parameters. Adding an index to your database may help to improve ordering performance. @@ -362,7 +362,7 @@ Create in bulk -------------- When creating objects, where possible, use the -:meth:`~django.db.models.query.QuerySet.bulk_create()` method to reduce the +:meth:`~django.db.models.query.QuerySet.bulk_create` method to reduce the number of SQL queries. For example:: Entry.objects.bulk_create( @@ -385,7 +385,7 @@ Update in bulk -------------- When updating objects, where possible, use the -:meth:`~django.db.models.query.QuerySet.bulk_update()` method to reduce the +:meth:`~django.db.models.query.QuerySet.bulk_update` method to reduce the number of SQL queries. Given a list or queryset of objects:: entries = Entry.objects.bulk_create( @@ -432,7 +432,7 @@ objects to reduce the number of SQL queries. For example:: When inserting different pairs of objects into :class:`~django.db.models.ManyToManyField` or when the custom :attr:`~django.db.models.ManyToManyField.through` table is defined, use -:meth:`~django.db.models.query.QuerySet.bulk_create()` method to reduce the +:meth:`~django.db.models.query.QuerySet.bulk_create` method to reduce the number of SQL queries. For example:: PizzaToppingRelationship = Pizza.toppings.through diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 007d55a79c..68bd237340 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -83,7 +83,7 @@ The :meth:`~django.db.models.Model.save` method has no return value. :meth:`~django.db.models.Model.save` for complete details. To create and save an object in a single step, use the - :meth:`~django.db.models.query.QuerySet.create()` method. + :meth:`~django.db.models.query.QuerySet.create` method. Saving changes to objects ========================= diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index 42143fd118..4504eb6fce 100644 --- a/docs/topics/db/sql.txt +++ b/docs/topics/db/sql.txt @@ -5,7 +5,7 @@ Performing raw SQL queries .. currentmodule:: django.db.models Django gives you two ways of performing raw SQL queries: you can use -:meth:`Manager.raw()` to `perform raw queries and return model instances`__, or +:meth:`Manager.raw` to `perform raw queries and return model instances`__, or you can avoid the model layer entirely and `execute custom SQL directly`__. __ `performing raw queries`_ @@ -170,7 +170,7 @@ Fields may also be left out: >>> people = Person.objects.raw("SELECT id, first_name FROM myapp_person") The ``Person`` objects returned by this query will be deferred model instances -(see :meth:`~django.db.models.query.QuerySet.defer()`). This means that the +(see :meth:`~django.db.models.query.QuerySet.defer`). This means that the fields that are omitted from the query will be loaded on demand. For example: .. code-block:: pycon diff --git a/docs/topics/email.txt b/docs/topics/email.txt index 6c39560c6a..945d5d8794 100644 --- a/docs/topics/email.txt +++ b/docs/topics/email.txt @@ -133,11 +133,11 @@ can be ``0`` or ``1`` since it can only send one message). (subject, message, from_email, recipient_list) ``fail_silently``, ``auth_user``, ``auth_password`` and ``connection`` have the -same functions as in :meth:`~django.core.mail.send_mail()`. They must be given +same functions as in :meth:`~django.core.mail.send_mail`. They must be given as keyword arguments if used. Each separate element of ``datatuple`` results in a separate email message. -As in :meth:`~django.core.mail.send_mail()`, recipients in the same +As in :meth:`~django.core.mail.send_mail`, recipients in the same ``recipient_list`` will all see the other addresses in the email messages' "To:" field. @@ -169,12 +169,12 @@ The return value will be the number of successfully delivered messages. ``send_mass_mail()`` vs. ``send_mail()`` ---------------------------------------- -The main difference between :meth:`~django.core.mail.send_mass_mail()` and -:meth:`~django.core.mail.send_mail()` is that -:meth:`~django.core.mail.send_mail()` opens a connection to the mail server -each time it's executed, while :meth:`~django.core.mail.send_mass_mail()` uses +The main difference between :meth:`~django.core.mail.send_mass_mail` and +:meth:`~django.core.mail.send_mail` is that +:meth:`~django.core.mail.send_mail` opens a connection to the mail server +each time it's executed, while :meth:`~django.core.mail.send_mass_mail` uses a single connection for all of its messages. This makes -:meth:`~django.core.mail.send_mass_mail()` slightly more efficient. +:meth:`~django.core.mail.send_mass_mail` slightly more efficient. ``mail_admins()`` ================= @@ -248,7 +248,7 @@ scripts generate. The Django email functions outlined above all protect against header injection by forbidding newlines in header values. If any ``subject``, ``from_email`` or ``recipient_list`` contains a newline (in either Unix, Windows or Mac style), -the email function (e.g. :meth:`~django.core.mail.send_mail()`) will raise +the email function (e.g. :meth:`~django.core.mail.send_mail`) will raise :exc:`ValueError` and, hence, will not send the email. It's your responsibility to validate all data before passing it to the email functions. @@ -291,18 +291,18 @@ from the request's POST data, sends that to admin@example.com and redirects to The ``EmailMessage`` class ========================== -Django's :meth:`~django.core.mail.send_mail()` and -:meth:`~django.core.mail.send_mass_mail()` functions are actually thin +Django's :meth:`~django.core.mail.send_mail` and +:meth:`~django.core.mail.send_mass_mail` functions are actually thin wrappers that make use of the :class:`~django.core.mail.EmailMessage` class. Not all features of the :class:`~django.core.mail.EmailMessage` class are -available through the :meth:`~django.core.mail.send_mail()` and related +available through the :meth:`~django.core.mail.send_mail` and related wrapper functions. If you wish to use advanced features, such as BCC'ed recipients, file attachments, or multi-part email, you'll need to create :class:`~django.core.mail.EmailMessage` instances directly. .. note:: - This is a design feature. :meth:`~django.core.mail.send_mail()` and + This is a design feature. :meth:`~django.core.mail.send_mail` and related functions were originally the only interface Django provided. However, the list of parameters they accepted was slowly growing over time. It made sense to move to a more object-oriented design for email @@ -714,7 +714,7 @@ SMTP backend EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend" If unspecified, the default ``timeout`` will be the one provided by - :func:`socket.getdefaulttimeout()`, which defaults to ``None`` (no timeout). + :func:`socket.getdefaulttimeout`, which defaults to ``None`` (no timeout). .. _topic-email-console-backend: diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 71d443f7d1..b54231d48e 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -248,7 +248,7 @@ user from entering more than that number of characters in the first place). It also means that when Django receives the form back from the browser, it will validate the length of the data. -A :class:`Form` instance has an :meth:`~Form.is_valid()` method, which runs +A :class:`Form` instance has an :meth:`~Form.is_valid` method, which runs validation routines for all its fields. When this method is called, if all fields contain valid data, it will: diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index b320d7fc04..c02d4d7809 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -237,17 +237,17 @@ There are two main steps involved in validating a ``ModelForm``: 2. :ref:`Validating the model instance ` Just like normal form validation, model form validation is triggered implicitly -when calling :meth:`~django.forms.Form.is_valid()` or accessing the +when calling :meth:`~django.forms.Form.is_valid` or accessing the :attr:`~django.forms.Form.errors` attribute and explicitly when calling ``full_clean()``, although you will typically not use the latter method in practice. ``Model`` validation is triggered from within the form validation step right after the form's ``clean()`` method is called. First, the model's -:meth:`~django.db.models.Model.full_clean()` is called with +:meth:`~django.db.models.Model.full_clean` is called with ``validate_unique=False`` and ``validate_constraints=False``, then the model's -:meth:`~django.db.models.Model.validate_unique()` and -:meth:`~django.db.models.Model.validate_constraints()` methods are called in +:meth:`~django.db.models.Model.validate_unique` and +:meth:`~django.db.models.Model.validate_constraints` methods are called in order. .. warning:: diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index 03559da3ed..4ec196a2ec 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -253,7 +253,7 @@ You can edit it multiple times. Deletes the current session data from the session and deletes the session cookie. This is used if you want to ensure that the previous session data can't be accessed again from the user's browser (for example, the - :func:`django.contrib.auth.logout()` function calls it). + :func:`django.contrib.auth.logout` function calls it). .. method:: set_test_cookie() .. method:: aset_test_cookie() @@ -380,7 +380,7 @@ You can edit it multiple times. *Asynchronous version*: ``acycle_key()`` Creates a new session key while retaining the current session data. - :func:`django.contrib.auth.login()` calls this method to mitigate against + :func:`django.contrib.auth.login` calls this method to mitigate against session fixation. .. _session_serialization: @@ -519,7 +519,7 @@ is necessary due to the way cookies work. When you set a cookie, you can't actually tell whether a browser accepted it until the browser's next request. It's good practice to use -:meth:`~backends.base.SessionBase.delete_test_cookie()` to clean up after +:meth:`~backends.base.SessionBase.delete_test_cookie` to clean up after yourself. Do this after you've verified that the test cookie worked. Here's a typical usage example:: @@ -589,7 +589,7 @@ access sessions using the normal Django database API: datetime.datetime(2005, 8, 20, 13, 35, 12) Note that you'll need to call -:meth:`~base_session.AbstractBaseSession.get_decoded()` to get the session +:meth:`~base_session.AbstractBaseSession.get_decoded` to get the session dictionary. This is necessary because the dictionary is stored in an encoded format: diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt index 308eae0855..e5da762d78 100644 --- a/docs/topics/http/shortcuts.txt +++ b/docs/topics/http/shortcuts.txt @@ -23,7 +23,7 @@ introduce controlled coupling for convenience's sake. Django does not provide a shortcut function which returns a :class:`~django.template.response.TemplateResponse` because the constructor of :class:`~django.template.response.TemplateResponse` offers the same level - of convenience as :func:`render()`. + of convenience as :func:`render`. Required arguments ------------------ @@ -98,7 +98,7 @@ This example is equivalent to:: The arguments could be: - * A model: the model's :meth:`~django.db.models.Model.get_absolute_url()` + * A model: the model's :meth:`~django.db.models.Model.get_absolute_url` function will be called. * A view name, possibly with arguments: :func:`~django.urls.reverse` will be @@ -196,7 +196,7 @@ original HTTP method:: *Asynchronous version*: ``aget_object_or_404()`` - Calls :meth:`~django.db.models.query.QuerySet.get()` on a given model + Calls :meth:`~django.db.models.query.QuerySet.get` on a given model manager, but it raises :class:`~django.http.Http404` instead of the model's :class:`~django.db.models.Model.DoesNotExist` exception. @@ -277,7 +277,7 @@ will be raised if more than one object is found. *Asynchronous version*: ``aget_list_or_404()`` - Returns the result of :meth:`~django.db.models.query.QuerySet.filter()` on + Returns the result of :meth:`~django.db.models.query.QuerySet.filter` on a given model manager cast to a list, raising :class:`~django.http.Http404` if the resulting list is empty. diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index d92beb3394..183ee6d184 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -377,7 +377,7 @@ itself. It includes a number of other URLconfs:: # ... snip ... ] -Whenever Django encounters :func:`~django.urls.include()`, it chops off +Whenever Django encounters :func:`~django.urls.include`, it chops off whatever part of the URL matched up to that point and sends the remaining string to the included URLconf for further processing. @@ -658,7 +658,7 @@ characters you like. You are not restricted to valid Python names. When naming URL patterns, choose names that are unlikely to clash with other applications' choice of names. If you call your URL pattern ``comment`` and another application does the same thing, the URL that -:func:`~django.urls.reverse()` finds depends on whichever pattern is last in +:func:`~django.urls.reverse` finds depends on whichever pattern is last in your project's ``urlpatterns`` list. Putting a prefix on your URL names, perhaps derived from the application @@ -670,12 +670,12 @@ want to override a view. For example, a common use case is to override the :class:`~django.contrib.auth.views.LoginView`. Parts of Django and most third-party apps assume that this view has a URL pattern with the name ``login``. If you have a custom login view and give its URL the name ``login``, -:func:`~django.urls.reverse()` will find your custom view as long as it's in +:func:`~django.urls.reverse` will find your custom view as long as it's in ``urlpatterns`` after ``django.contrib.auth.urls`` is included (if that's included at all). You may also use the same name for multiple URL patterns if they differ in -their arguments. In addition to the URL name, :func:`~django.urls.reverse()` +their arguments. In addition to the URL name, :func:`~django.urls.reverse` matches the number of arguments and the names of the keyword arguments. Path converters can also raise ``ValueError`` to indicate no match, see :ref:`registering-custom-path-converters` for details. @@ -743,7 +743,7 @@ the fully qualified name into parts and then tries the following lookup: #. If there is a current application defined, Django finds and returns the URL resolver for that instance. The current application can be specified with - the ``current_app`` argument to the :func:`~django.urls.reverse()` + the ``current_app`` argument to the :func:`~django.urls.reverse` function. The :ttag:`url` template tag uses the namespace of the currently resolved diff --git a/docs/topics/i18n/translation.txt b/docs/topics/i18n/translation.txt index eacf2a3234..3d6503dfc5 100644 --- a/docs/topics/i18n/translation.txt +++ b/docs/topics/i18n/translation.txt @@ -180,7 +180,7 @@ more details. Marking strings as no-op ------------------------ -Use the function :func:`django.utils.translation.gettext_noop()` to mark a +Use the function :func:`django.utils.translation.gettext_noop` to mark a string as a translation string without translating it. The string is later translated from a variable. @@ -192,7 +192,7 @@ such as when the string is presented to the user. Pluralization ------------- -Use the function :func:`django.utils.translation.ngettext()` to specify +Use the function :func:`django.utils.translation.ngettext` to specify pluralized messages. ``ngettext()`` takes three arguments: the singular translation string, the @@ -290,8 +290,8 @@ Contextual markers Sometimes words have several meanings, such as ``"May"`` in English, which refers to a month name and to a verb. To enable translators to translate these words correctly in different contexts, you can use the -:func:`django.utils.translation.pgettext()` function, or the -:func:`django.utils.translation.npgettext()` function if the string needs +:func:`django.utils.translation.pgettext` function, or the +:func:`django.utils.translation.npgettext` function if the string needs pluralization. Both take a context string as the first variable. In the resulting ``.po`` file, the string will then appear as often as there are @@ -502,10 +502,10 @@ directly with the ``number`` argument:: Formatting strings: ``format_lazy()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Python's :meth:`str.format()` method will not work when either the -``format_string`` or any of the arguments to :meth:`str.format()` +Python's :meth:`str.format` method will not work when either the +``format_string`` or any of the arguments to :meth:`str.format` contains lazy translation objects. Instead, you can use -:func:`django.utils.text.format_lazy()`, which creates a lazy object +:func:`django.utils.text.format_lazy`, which creates a lazy object that runs the ``str.format()`` method only when the result is included in a string. For example:: @@ -1224,7 +1224,7 @@ in the future. ~~~~~~~~~~~~ The ``pgettext`` function behaves like the Python variant -(:func:`~django.utils.translation.pgettext()`), providing a contextually +(:func:`~django.utils.translation.pgettext`), providing a contextually translated word:: document.write(pgettext("month name", "May")) @@ -1233,7 +1233,7 @@ translated word:: ~~~~~~~~~~~~~ The ``npgettext`` function also behaves like the Python variant -(:func:`~django.utils.translation.npgettext()`), providing a **pluralized** +(:func:`~django.utils.translation.npgettext`), providing a **pluralized** contextually translated word: .. code-block:: javascript @@ -1365,7 +1365,7 @@ Django provides two mechanisms to internationalize URL patterns: the language to activate from the requested URL. * Making URL patterns themselves translatable via the - :func:`django.utils.translation.gettext_lazy()` function. + :func:`django.utils.translation.gettext_lazy` function. .. warning:: @@ -1931,7 +1931,7 @@ Explicitly setting the active language You may want to set the active language for the current session explicitly. Perhaps a user's language preference is retrieved from another system, for example. -You've already been introduced to :func:`django.utils.translation.activate()`. That +You've already been introduced to :func:`django.utils.translation.activate`. That applies to the current thread only. To persist the language for the entire session in a cookie, set the :setting:`LANGUAGE_COOKIE_NAME` cookie on the response:: @@ -1945,7 +1945,7 @@ response:: response = HttpResponse(...) response.set_cookie(settings.LANGUAGE_COOKIE_NAME, user_language) -You would typically want to use both: :func:`django.utils.translation.activate()` +You would typically want to use both: :func:`django.utils.translation.activate` changes the language for this thread, and setting the cookie makes this preference persist in future requests. @@ -1979,14 +1979,14 @@ Calling this function with the value ``'de'`` will give you ``"Willkommen"``, regardless of :setting:`LANGUAGE_CODE` and language set by middleware. Functions of particular interest are -:func:`django.utils.translation.get_language()` which returns the language used -in the current thread, :func:`django.utils.translation.activate()` which +:func:`django.utils.translation.get_language` which returns the language used +in the current thread, :func:`django.utils.translation.activate` which activates a translation catalog for the current thread, and -:func:`django.utils.translation.check_for_language()` +:func:`django.utils.translation.check_for_language` which checks if the given language is supported by Django. To help write more concise code, there is also a context manager -:func:`django.utils.translation.override()` that stores the current language on +:func:`django.utils.translation.override` that stores the current language on enter and restores it on exit. With it, the above example becomes:: from django.utils import translation diff --git a/docs/topics/logging.txt b/docs/topics/logging.txt index 4f62121b31..39673a3969 100644 --- a/docs/topics/logging.txt +++ b/docs/topics/logging.txt @@ -419,7 +419,7 @@ logger, you can specify your own configuration scheme. The :setting:`LOGGING_CONFIG` setting defines the callable that will be used to configure Django's loggers. By default, it points at -Python's :func:`logging.config.dictConfig()` function. However, if you want to +Python's :func:`logging.config.dictConfig` function. However, if you want to use a different configuration process, you can use any other callable that takes a single argument. The contents of :setting:`LOGGING` will be provided as the value of that argument when logging is configured. diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt index 21c3bf108f..2f848e20ea 100644 --- a/docs/topics/migrations.txt +++ b/docs/topics/migrations.txt @@ -189,7 +189,7 @@ You can prevent a migration from running in a transaction by setting the atomic = False It's also possible to execute parts of the migration inside a transaction using -:func:`~django.db.transaction.atomic()` or by passing ``atomic=True`` to +:func:`~django.db.transaction.atomic` or by passing ``atomic=True`` to :class:`~django.db.migrations.operations.RunPython`. See :ref:`non-atomic-migrations` for more details. diff --git a/docs/topics/security.txt b/docs/topics/security.txt index 272206da54..754be0b495 100644 --- a/docs/topics/security.txt +++ b/docs/topics/security.txt @@ -188,9 +188,9 @@ cache poisoning attacks, and poisoning links in emails. Because even seemingly-secure web server configurations are susceptible to fake ``Host`` headers, Django validates ``Host`` headers against the :setting:`ALLOWED_HOSTS` setting in the -:meth:`django.http.HttpRequest.get_host()` method. +:meth:`django.http.HttpRequest.get_host` method. -This validation only applies via :meth:`~django.http.HttpRequest.get_host()`; +This validation only applies via :meth:`~django.http.HttpRequest.get_host`; if your code accesses the ``Host`` header directly from ``request.META`` you are bypassing this security protection. diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt index 553f788e61..b969cd8088 100644 --- a/docs/topics/settings.txt +++ b/docs/topics/settings.txt @@ -280,7 +280,7 @@ ORM to fetch some data -- there's one more step you'll need in addition to configuring settings. After you've either set :envvar:`DJANGO_SETTINGS_MODULE` or called -``configure()``, you'll need to call :func:`django.setup()` to load your +``configure()``, you'll need to call :func:`django.setup` to load your settings and populate Django's application registry. For example:: import django diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt index 1b5559db5a..06783f8724 100644 --- a/docs/topics/templates.txt +++ b/docs/topics/templates.txt @@ -425,7 +425,7 @@ When Django finds a template that exists, it stops looking. .. admonition:: Use ``django.template.loader.select_template()`` for more flexibility - You can use :func:`~django.template.loader.select_template()` for flexible + You can use :func:`~django.template.loader.select_template` for flexible template loading. For example, if you've written a news story and want some stories to have custom templates, use something like ``select_template(['story_%s_detail.html' % story.id, @@ -485,8 +485,8 @@ templates, Django provides a shortcut function which automates the process. rendered = render_to_string("my_template.html", {"foo": "bar"}) -See also the :func:`~django.shortcuts.render()` shortcut which calls -:func:`render_to_string()` and feeds the result into an +See also the :func:`~django.shortcuts.render` shortcut which calls +:func:`render_to_string` and feeds the result into an :class:`~django.http.HttpResponse` suitable for returning from a view. Finally, you can use configured engines directly: diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt index 72373c6107..b6146253c1 100644 --- a/docs/topics/testing/advanced.txt +++ b/docs/topics/testing/advanced.txt @@ -19,10 +19,10 @@ a black box, with exactly known inputs, testing for specific outputs. The API for the :class:`~django.test.RequestFactory` is a slightly restricted subset of the test client API: -* It only has access to the HTTP methods :meth:`~Client.get()`, - :meth:`~Client.post()`, :meth:`~Client.put()`, - :meth:`~Client.delete()`, :meth:`~Client.head()`, - :meth:`~Client.options()`, and :meth:`~Client.trace()`. +* It only has access to the HTTP methods :meth:`~Client.get`, + :meth:`~Client.post`, :meth:`~Client.put`, + :meth:`~Client.delete`, :meth:`~Client.head`, + :meth:`~Client.options`, and :meth:`~Client.trace`. * These methods accept all the same arguments *except* for ``follow``. Since this is just a factory for producing @@ -158,8 +158,8 @@ and the settings file includes a list of the domains supported by the project:: ALLOWED_HOSTS = ["www.djangoproject.dev", "docs.djangoproject.dev", ...] Another option is to add the required hosts to :setting:`ALLOWED_HOSTS` using -:meth:`~django.test.override_settings()` or -:attr:`~django.test.SimpleTestCase.modify_settings()`. This option may be +:meth:`~django.test.override_settings` or +:attr:`~django.test.SimpleTestCase.modify_settings`. This option may be preferable in standalone apps that can't package their own settings file or for projects where the list of domains is not static (e.g., subdomains for multitenancy). For example, you could write a test for the domain @@ -661,7 +661,7 @@ Methods Override this class method to add custom arguments accepted by the :djadmin:`test` management command. See - :py:meth:`argparse.ArgumentParser.add_argument()` for details about adding + :py:meth:`argparse.ArgumentParser.add_argument` for details about adding arguments to a parser. .. method:: DiscoverRunner.setup_test_environment(**kwargs) diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index a975ec099d..ac4110943a 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -208,7 +208,7 @@ with ability to share the database between threads. your code* anyway - rewrite your code so that it doesn't do this. This also applies to customized implementations of - :meth:`~django.apps.AppConfig.ready()`. + :meth:`~django.apps.AppConfig.ready`. .. seealso:: diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index dfe92f88eb..7574695b21 100644 --- a/docs/topics/testing/tools.txt +++ b/docs/topics/testing/tools.txt @@ -144,8 +144,8 @@ Use the ``django.test.Client`` class to make requests. but the ``headers`` parameter should be preferred for readability. The values from the ``headers``, ``query_params``, and ``extra`` keyword - arguments passed to :meth:`~django.test.Client.get()`, - :meth:`~django.test.Client.post()`, etc. have precedence over + arguments passed to :meth:`~django.test.Client.get`, + :meth:`~django.test.Client.post`, etc. have precedence over the defaults passed to the class constructor. The ``enforce_csrf_checks`` argument can be used to test CSRF @@ -198,7 +198,7 @@ Use the ``django.test.Client`` class to make requests. ...will send the HTTP header ``HTTP_ACCEPT`` to the details view, which is a good way to test code paths that use the - :meth:`django.http.HttpRequest.accepts()` method. + :meth:`django.http.HttpRequest.accepts` method. Arbitrary keyword arguments set WSGI :pep:`environ variables <3333#environ-variables>`. For example, headers @@ -456,7 +456,7 @@ Use the ``django.test.Client`` class to make requests. fixture. Remember that if you want your test user to have a password, you can't set the user's password by setting the password attribute directly -- you must use the - :meth:`~django.contrib.auth.models.User.set_password()` function to + :meth:`~django.contrib.auth.models.User.set_password` function to store a correctly hashed password. Alternatively, you can use the :meth:`~django.contrib.auth.models.UserManager.create_user` helper method to create a new user with a correctly hashed password. @@ -882,7 +882,7 @@ end of each test. A consequence of this, however, is that some database behaviors cannot be tested within a Django ``TestCase`` class. For instance, you cannot test that a block of code is executing within a transaction, as is required when using -:meth:`~django.db.models.query.QuerySet.select_for_update()`. In those cases, +:meth:`~django.db.models.query.QuerySet.select_for_update`. In those cases, you should use ``TransactionTestCase``. ``TransactionTestCase`` and ``TestCase`` are identical except for the manner