[pull] main from django:main

django/utils/html.py

@@ -10,7 +10,7 @@
 
 from django.conf import settings
 from django.core.exceptions import SuspiciousOperation, ValidationError
-from django.core.validators import EmailValidator
+from django.core.validators import DomainNameValidator, EmailValidator
 from django.utils.deprecation import RemovedInDjango70Warning
 from django.utils.functional import Promise, cached_property, keep_lazy, keep_lazy_text
 from django.utils.http import MAX_URL_LENGTH, RFC3986_GENDELIMS, RFC3986_SUBDELIMS
@@ -296,7 +296,9 @@ class Urlizer:
 
     simple_url_re = _lazy_re_compile(r"^https?://\[?\w", re.IGNORECASE)
     simple_url_2_re = _lazy_re_compile(
-        r"^www\.|^(?!http)\w[^@]+\.(com|edu|gov|int|mil|net|org)($|/.*)$", re.IGNORECASE
+        rf"^www\.|^(?!http)(?:{DomainNameValidator.hostname_re})"
+        r"\.(com|edu|gov|int|mil|net|org)($|/.*)$",
+        re.IGNORECASE,
     )
     word_split_re = _lazy_re_compile(r"""([\s<>"']+)""")
 

docs/howto/custom-management-commands.txt

@@ -120,7 +120,7 @@ this::
             # ...
 
 The option (``delete`` in our example) is available in the options dict
-parameter of the handle method. See the :py:mod:`argparse` Python documentation
+parameter of the handle method. See the :mod:`argparse` Python documentation
 for more about ``add_argument`` usage.
 
 In addition to being able to add custom command line options, all
@@ -208,7 +208,7 @@ All attributes can be set in your derived class and can be used in
 
     If your command defines mandatory positional arguments, you can customize
     the message error returned in the case of missing arguments. The default is
-    output by :py:mod:`argparse` ("too few arguments").
+    output by :mod:`argparse` ("too few arguments").
 
 .. attribute:: BaseCommand.output_transaction
 

docs/howto/logging.txt

@@ -25,7 +25,7 @@ To send a log message from within your code, you place a logging call into it.
     logging, use a view function as suggested in the example below.
 
 First, import the Python logging library, and then obtain a logger instance
-with :py:func:`logging.getLogger`. Provide the ``getLogger()`` method with a
+with :func:`logging.getLogger`. Provide the ``getLogger()`` method with a
 name to identify it and the records it emits. A good option is to use
 ``__name__`` (see :ref:`naming-loggers` below for more on this) which will
 provide the name of the current Python module as a dotted path::
@@ -43,7 +43,7 @@ And then in a function, for example in a view, send a record to the logger::
         if some_risky_state:
             logger.warning("Platform is running at risk")
 
-When this code is executed, a :py:class:`~logging.LogRecord` containing that
+When this code is executed, a :class:`~logging.LogRecord` containing that
 message will be sent to the logger. If you're using Django's default logging
 configuration, the message will appear in the console.
 
@@ -129,7 +129,7 @@ file ``general.log`` (at the project root):
 Different handler classes take different configuration options. For more
 information on available handler classes, see the
 :class:`~django.utils.log.AdminEmailHandler` provided by Django and the various
-:py:mod:`handler classes <logging.handlers>` provided by Python.
+:mod:`handler classes <logging.handlers>` provided by Python.
 
 Logging levels can also be set on the handlers (by default, they accept log
 messages of all levels). Using the example above, adding:
@@ -238,7 +238,7 @@ application. A named logging configuration will capture logs only from loggers
 with matching names.
 
 The namespace of a logger instance is defined using
-:py:func:`~logging.getLogger`. For example in ``views.py`` of ``my_app``::
+:func:`~logging.getLogger`. For example in ``views.py`` of ``my_app``::
 
     logger = logging.getLogger(__name__)
 

docs/internals/contributing/writing-code/coding-style.txt

@@ -56,8 +56,8 @@ Python style
   These limits are checked when ``flake8`` is run.
 
 * String variable interpolation may use
-  :py:ref:`%-formatting <old-string-formatting>`, :py:ref:`f-strings
-  <f-strings>`, or :py:meth:`str.format` as appropriate, with the goal of
+  :ref:`%-formatting <old-string-formatting>`, :ref:`f-strings
+  <f-strings>`, or :meth:`str.format` as appropriate, with the goal of
   maximizing code readability.
 
   Final judgments of readability are left to the Merger's discretion. As a

docs/internals/deprecation.txt

@@ -742,8 +742,8 @@ details on these changes.
 * The ability to use a dotted Python path for the ``LOGIN_URL`` and
   ``LOGIN_REDIRECT_URL`` settings will be removed.
 
-* Support for :py:mod:`optparse` will be dropped for custom management commands
-  (replaced by :py:mod:`argparse`).
+* Support for :mod:`optparse` will be dropped for custom management commands
+  (replaced by :mod:`argparse`).
 
 * The class ``django.core.management.NoArgsCommand`` will be removed. Use
   :class:`~django.core.management.BaseCommand` instead, which takes no

docs/lint.py

@@ -5,12 +5,14 @@
 from unittest import mock
 
 from sphinxlint.checkers import (
+    _ROLE_BODY,
     _is_long_interpreted_text,
     _is_very_long_string_literal,
     _starts_with_anonymous_hyperlink,
     _starts_with_directive_or_hyperlink,
 )
 from sphinxlint.checkers import checker as sphinxlint_checker
+from sphinxlint.rst import SIMPLENAME
 from sphinxlint.sphinxlint import check_text
 from sphinxlint.utils import PER_FILE_CACHES, hide_non_rst_blocks
 
@@ -116,6 +118,24 @@ def is_multiline_block_to_exclude(line):
             yield lno + 1, f"Line too long ({len(line) - 1}/{options.max_line_length})"
 
 
+_PYTHON_DOMAIN = re.compile(f":py:{SIMPLENAME}:`{_ROLE_BODY}`")
+
+
+@sphinxlint_checker(".rst", enabled=False, rst_only=True)
+def check_python_domain_in_roles(file, lines, options=None):
+    """
+    :py: indicates the Python language domain. This means code writen in
+    Python, not Python built-ins in particular.
+
+    Bad:    :py:class:`email.message.EmailMessage`
+    Good:   :class:`email.message.EmailMessage`
+    """
+    for lno, line in enumerate(lines, start=1):
+        role = _PYTHON_DOMAIN.search(line)
+        if role:
+            yield lno, f":py domain is the default and can be omitted {role.group(0)!r}"
+
+
 import sphinxlint  # noqa: E402
 
 sphinxlint.check_file = django_check_file

docs/ref/contrib/staticfiles.txt

@@ -492,7 +492,7 @@ This view function serves static files in development.
 .. note::
 
     To guess the served files' content types, this view relies on the
-    :py:mod:`mimetypes` module from the Python standard library, which itself
+    :mod:`mimetypes` module from the Python standard library, which itself
     relies on the underlying platform's map files. If you find that this view
     doesn't return proper content types for certain files, it is most likely
     that the platform's map files are incorrect or need to be updated. This can

docs/ref/databases.txt

@@ -951,7 +951,7 @@ Enabling JSON1 extension on SQLite
 ----------------------------------
 
 To use :class:`~django.db.models.JSONField` on SQLite, you need to enable the
-`JSON1 extension`_ on Python's :py:mod:`sqlite3` library. If the extension is
+`JSON1 extension`_ on Python's :mod:`sqlite3` library. If the extension is
 not enabled on your installation, a system error (``fields.E180``) will be
 raised.
 

docs/ref/django-admin.txt

@@ -1845,7 +1845,7 @@ allows for the following options by default:
 
 .. django-admin-option:: --pythonpath PYTHONPATH
 
-Adds the given filesystem path to the Python :py:data:`sys.path` module
+Adds the given filesystem path to the Python :data:`sys.path` module
 attribute. If this isn't provided, ``django-admin`` will use the
 :envvar:`PYTHONPATH` environment variable.
 

docs/ref/files/file.txt

@@ -13,7 +13,7 @@ The ``File`` class
 .. class:: File(file_object, name=None)
 
     The :class:`File` class is a thin wrapper around a Python
-    :py:term:`file object` with some Django-specific additions.
+    :term:`file object` with some Django-specific additions.
     Internally, Django uses this class when it needs to represent a file.
 
     :class:`File` objects have the following attributes and methods:
@@ -29,14 +29,14 @@ The ``File`` class
 
     .. attribute:: file
 
-        The underlying :py:term:`file object` that this class wraps.
+        The underlying :term:`file object` that this class wraps.
 
         .. admonition:: Be careful with this attribute in subclasses.
 
             Some subclasses of :class:`File`, including
             :class:`~django.core.files.base.ContentFile` and
             :class:`~django.db.models.fields.files.FieldFile`, may replace this
-            attribute with an object other than a Python :py:term:`file
+            attribute with an object other than a Python :term:`file
             object`. In these cases, this attribute may itself be a
             :class:`File` subclass (and not necessarily the same subclass).
             Whenever possible, use the attributes and methods of the subclass

docs/ref/forms/fields.txt

@@ -919,7 +919,7 @@ For each field, we describe the default widget used if you don't specify
 
     .. attribute:: encoder
 
-        A :py:class:`json.JSONEncoder` subclass to serialize data types not
+        A :class:`json.JSONEncoder` subclass to serialize data types not
         supported by the standard JSON serializer (e.g. ``datetime.datetime``
         or :class:`~python:uuid.UUID`). For example, you can use the
         :class:`~django.core.serializers.json.DjangoJSONEncoder` class.
@@ -928,14 +928,14 @@ For each field, we describe the default widget used if you don't specify
 
     .. attribute:: decoder
 
-        A :py:class:`json.JSONDecoder` subclass to deserialize the input. Your
+        A :class:`json.JSONDecoder` subclass to deserialize the input. Your
         deserialization may need to account for the fact that you can't be
         certain of the input type. For example, you run the risk of returning a
         ``datetime`` that was actually a string that just happened to be in the
         same format chosen for ``datetime``\s.
 
         The ``decoder`` can be used to validate the input. If
-        :py:class:`json.JSONDecodeError` is raised during the deserialization,
+        :class:`json.JSONDecodeError` is raised during the deserialization,
         a ``ValidationError`` will be raised.
 
         Defaults to ``json.JSONDecoder``.

docs/ref/logging.txt

@@ -164,7 +164,7 @@ Messages to this logger have the following extra context:
 
 * ``status_code``: The HTTP response code associated with the request.
 
-* ``request``: The request object (a :py:class:`socket.socket`) that generated
+* ``request``: The request object (a :class:`socket.socket`) that generated
   the logging message.
 
 .. _django-template-logger:

docs/ref/models/expressions.txt

@@ -563,7 +563,7 @@ values into their corresponding database type.
 
 If no :ref:`output_field<output-field>` is specified, it will be inferred from
 the type of the provided ``value`` for many common types. For example, passing
-an instance of :py:class:`datetime.datetime` as ``value`` defaults
+an instance of :class:`datetime.datetime` as ``value`` defaults
 ``output_field`` to :class:`~django.db.models.DateTimeField`.
 
 ``ExpressionWrapper()`` expressions
@@ -1094,7 +1094,7 @@ calling the appropriate methods on the wrapped expression.
 
         Tells Django which value should be returned when the expression is used
         to apply a function over an empty result set. Defaults to
-        :py:data:`NotImplemented` which forces the expression to be computed on
+        :data:`NotImplemented` which forces the expression to be computed on
         the database.
 
     .. attribute:: set_returning

docs/ref/models/fields.txt

@@ -1434,7 +1434,7 @@ Python native format: dictionaries, lists, strings, numbers, booleans and
 
 .. attribute:: JSONField.encoder
 
-    An optional :py:class:`json.JSONEncoder` subclass to serialize data types
+    An optional :class:`json.JSONEncoder` subclass to serialize data types
     not supported by the standard JSON serializer (e.g. ``datetime.datetime``
     or :class:`~python:uuid.UUID`). For example, you can use the
     :class:`~django.core.serializers.json.DjangoJSONEncoder` class.
@@ -1443,7 +1443,7 @@ Python native format: dictionaries, lists, strings, numbers, booleans and
 
 .. attribute:: JSONField.decoder
 
-    An optional :py:class:`json.JSONDecoder` subclass to deserialize the value
+    An optional :class:`json.JSONDecoder` subclass to deserialize the value
     retrieved from the database. The value will be in the format chosen by the
     custom encoder (most often a string). Your deserialization may need to
     account for the fact that you can't be certain of the input type. For
@@ -1458,7 +1458,7 @@ To query ``JSONField`` in the database, see :ref:`querying-jsonfield`.
 .. admonition:: Default value
 
     If you give the field a :attr:`~django.db.models.Field.default`, ensure
-    it's a callable such as the :py:class:`dict` class or a function that
+    it's a callable such as the :class:`dict` class or a function that
     returns a fresh object each time. Incorrectly using a mutable object like
     ``default={}`` or ``default=[]`` creates a mutable default that is shared
     between all instances.
@@ -1483,8 +1483,8 @@ To query ``JSONField`` in the database, see :ref:`querying-jsonfield`.
 .. admonition:: Oracle users
 
     Oracle Database does not support storing JSON scalar values. Only JSON
-    objects and arrays (represented in Python using :py:class:`dict` and
-    :py:class:`list`) are supported.
+    objects and arrays (represented in Python using :class:`dict` and
+    :class:`list`) are supported.
 
 ``PositiveBigIntegerField``
 ---------------------------
@@ -2440,7 +2440,7 @@ Field API reference
 
     .. attribute:: descriptor_class
 
-        A class implementing the :py:ref:`descriptor protocol <descriptors>`
+        A class implementing the :ref:`descriptor protocol <descriptors>`
         that is instantiated and assigned to the model instance attribute. The
         constructor must accept a single argument, the ``Field`` instance.
         Overriding this class attribute allows for customizing the get and set

docs/ref/request-response.txt

@@ -889,7 +889,7 @@ Attributes
 
 .. attribute:: HttpResponse.cookies
 
-    A :py:obj:`http.cookies.SimpleCookie` object holding the cookies included
+    A :obj:`http.cookies.SimpleCookie` object holding the cookies included
     in the response.
 
 .. attribute:: HttpResponse.headers
@@ -952,7 +952,7 @@ Methods
     ``"text/html; charset=utf-8"``.
 
     ``status`` is the :rfc:`HTTP status code <9110#section-15>` for the
-    response. You can use Python's :py:class:`http.HTTPStatus` for meaningful
+    response. You can use Python's :class:`http.HTTPStatus` for meaningful
     aliases, such as ``HTTPStatus.NO_CONTENT``.
 
     ``reason`` is the HTTP response phrase. If not provided, a default phrase
@@ -1187,7 +1187,7 @@ Custom response classes
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 If you find yourself needing a response class that Django doesn't provide, you
-can create it with the help of :py:class:`http.HTTPStatus`. For example::
+can create it with the help of :class:`http.HTTPStatus`. For example::
 
     from http import HTTPStatus
     from django.http import HttpResponse

docs/ref/templates/builtins.txt

@@ -1225,14 +1225,14 @@ attribute and calling the result ``country_list``.
 
 ``{% regroup %}`` produces a list (in this case, ``country_list``) of
 **group objects**. Group objects are instances of
-:py:func:`~collections.namedtuple` with two fields:
+:func:`~collections.namedtuple` with two fields:
 
 * ``grouper`` -- the item that was grouped by (e.g., the string "India" or
   "Japan").
 * ``list`` -- a list of all items in this group (e.g., a list of all cities
   with country='India').
 
-Because ``{% regroup %}`` produces :py:func:`~collections.namedtuple` objects,
+Because ``{% regroup %}`` produces :func:`~collections.namedtuple` objects,
 you can also write the previous example as:
 
 .. code-block:: html+django
@@ -1839,7 +1839,7 @@ For example:
 
     {{ value|date:"D d M Y" }}
 
-If ``value`` is a :py:class:`~datetime.datetime` object (e.g., the result of
+If ``value`` is a :class:`~datetime.datetime` object (e.g., the result of
 ``datetime.datetime.now()``), the output will be the string
 ``'Wed 09 Jan 2008'``.
 
@@ -2736,7 +2736,7 @@ specifier for the ``de`` locale as shipped with Django is ``"H:i"``).
 The ``time`` filter will only accept parameters in the format string that
 relate to the time of day, not the date. If you need to format a ``date``
 value, use the :tfilter:`date` filter instead (or along with :tfilter:`time` if
-you need to render a full :py:class:`~datetime.datetime` value).
+you need to render a full :class:`~datetime.datetime` value).
 
 There is one exception the above rule: When passed a ``datetime`` value with
 attached timezone information (a :ref:`time-zone-aware

docs/ref/unicode.txt

@@ -268,7 +268,7 @@ Use strings when creating templates manually::
 
 But the common case is to read templates from the filesystem. If your template
 files are not stored with a UTF-8 encoding, adjust the :setting:`TEMPLATES`
-setting. The built-in :py:mod:`~django.template.backends.django` backend
+setting. The built-in :mod:`~django.template.backends.django` backend
 provides the ``'file_charset'`` option to change the encoding used to read
 files from disk.
 

docs/ref/urls.txt

@@ -95,7 +95,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
 :ref:`translating-urlpatterns`) that contains a regular expression compatible
-with Python's :py:mod:`re` module. Strings typically use raw string syntax
+with Python's :mod:`re` module. Strings typically use raw string syntax
 (``r''``) so that they can contain sequences like ``\d`` without the need to
 escape the backslash with another backslash. When a match is made, captured
 groups from the regular expression are passed to the view -- as named arguments
@@ -104,7 +104,7 @@ passed as strings, without any type conversion.
 
 When a ``route`` ends with ``$`` the whole requested URL, matching against
 :attr:`~django.http.HttpRequest.path_info`, must match the regular expression
-pattern (:py:func:`re.fullmatch` is used).
+pattern (:func:`re.fullmatch` is used).
 
 The ``view``, ``kwargs`` and ``name`` arguments are the same as for
 :func:`~django.urls.path`.