Merge branch 'main' into ast-deprecation-warnings

Author: iritkatriel

Doc/_static/og-image.png

@@ -13,9 +13,25 @@
 # General configuration
 # ---------------------
 
-extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest',
-              'pyspecific', 'c_annotations', 'escape4chm',
-              'asdl_highlight', 'peg_highlight', 'glossary_search']
+extensions = [
+    'asdl_highlight',
+    'c_annotations',
+    'escape4chm',
+    'glossary_search',
+    'peg_highlight',
+    'pyspecific',
+    'sphinx.ext.coverage',
+    'sphinx.ext.doctest',
+]
+
+# Skip if downstream redistributors haven't installed it
+try:
+    import sphinxext.opengraph
+except ImportError:
+    pass
+else:
+    extensions.append('sphinxext.opengraph')
+
 
 doctest_global_setup = '''
 try:
@@ -89,6 +105,14 @@
 # Short title used e.g. for <title> HTML tags.
 html_short_title = '%s Documentation' % release
 
+# Deployment preview information, from Netlify
+# (See netlify.toml and https://docs.netlify.com/configure-builds/environment-variables/#git-metadata)
+html_context = {
+    "is_deployment_preview": os.getenv("IS_DEPLOYMENT_PREVIEW"),
+    "repository_url": os.getenv("REPOSITORY_URL"),
+    "pr_id": os.getenv("REVIEW_ID")
+}
+
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
@@ -114,7 +138,7 @@
 html_use_opensearch = 'https://docs.python.org/' + version
 
 # Additional static files.
-html_static_path = ['tools/static']
+html_static_path = ['_static', 'tools/static']
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'python' + release.replace('.', '')
@@ -238,3 +262,13 @@
 # Relative filename of the data files
 refcount_file = 'data/refcounts.dat'
 stable_abi_file = 'data/stable_abi.dat'
+
+# sphinxext-opengraph config
+ogp_site_url = 'https://docs.python.org/3/'
+ogp_site_name = 'Python documentation'
+ogp_image = '_static/og-image.png'
+ogp_custom_meta_tags = [
+    '<meta property="og:image:width" content="200">',
+    '<meta property="og:image:height" content="200">',
+    '<meta name="theme-color" content="#3776ab">',
+]

Doc/conf.py

@@ -459,6 +459,31 @@ sense to allow sharing some common behavior between a group of enumerations.
 (See `OrderedEnum`_ for an example.)
 
 
+.. _enum-dataclass-support:
+
+Dataclass support
+-----------------
+
+When inheriting from a :class:`~dataclasses.dataclass`,
+the :meth:`~Enum.__repr__` omits the inherited class' name.  For example::
+
+    >>> @dataclass
+    ... class CreatureDataMixin:
+    ...     size: str
+    ...     legs: int
+    ...     tail: bool = field(repr=False, default=True)
+    ...
+    >>> class Creature(CreatureDataMixin, Enum):
+    ...     BEETLE = 'small', 6
+    ...     DOG = 'medium', 4
+    ...
+    >>> Creature.DOG
+    <Creature.DOG: size='medium', legs=4>
+
+Use the :func:`!dataclass` argument ``repr=False``
+to use the standard :func:`repr`.
+
+
 Pickling
 --------
 

Doc/howto/enum.rst

@@ -33,7 +33,8 @@ an event loop:
 
    Return the running event loop in the current OS thread.
 
-   If there is no running event loop a :exc:`RuntimeError` is raised.
+   Raise a :exc:`RuntimeError` if there is no running event loop.
+
    This function can only be called from a coroutine or a callback.
 
    .. versionadded:: 3.7
@@ -42,27 +43,31 @@ an event loop:
 
    Get the current event loop.
 
-   If there is no current event loop set in the current OS thread,
-   the OS thread is main, and :func:`set_event_loop` has not yet
-   been called, asyncio will create a new event loop and set it as the
-   current one.
+   When called from a coroutine or a callback (e.g. scheduled with
+   call_soon or similar API), this function will always return the
+   running event loop.
+
+   If there is no running event loop set, the function will return
+   the result of calling ``get_event_loop_policy().get_event_loop()``.
 
    Because this function has rather complex behavior (especially
    when custom event loop policies are in use), using the
    :func:`get_running_loop` function is preferred to :func:`get_event_loop`
    in coroutines and callbacks.
 
-   Consider also using the :func:`asyncio.run` function instead of using
-   lower level functions to manually create and close an event loop.
+   As noted above, consider using the higher-level :func:`asyncio.run` function,
+   instead of using these lower level functions to manually create and close an
+   event loop.
 
-   .. deprecated:: 3.10
-      Deprecation warning is emitted if there is no running event loop.
-      In future Python releases, this function will be an alias of
-      :func:`get_running_loop`.
+   .. note::
+      In Python versions 3.10.0--3.10.8 and 3.11.0 this function
+      (and other functions which used it implicitly) emitted a
+      :exc:`DeprecationWarning` if there was no running event loop, even if
+      the current loop was set.
 
 .. function:: set_event_loop(loop)
 
-   Set *loop* as a current event loop for the current OS thread.
+   Set *loop* as the current event loop for the current OS thread.
 
 .. function:: new_event_loop()
 

Doc/library/asyncio-eventloop.rst

@@ -19,7 +19,7 @@ Obtaining the Event Loop
       - The **preferred** function to get the running event loop.
 
     * - :func:`asyncio.get_event_loop`
-      - Get an event loop instance (current or via the policy).
+      - Get an event loop instance (running or current via the current policy).
 
     * - :func:`asyncio.set_event_loop`
       - Set the event loop as current via the current policy.

Doc/library/asyncio-llapi-index.rst

@@ -116,6 +116,10 @@ asyncio ships with the following built-in policies:
 
       On Windows, :class:`ProactorEventLoop` is now used by default.
 
+   .. versionchanged:: 3.12
+      :meth:`get_event_loop` now raises a :exc:`RuntimeError` if there is no
+      current event loop set.
+
 
 .. class:: WindowsSelectorEventLoopPolicy
 

Doc/library/asyncio-policy.rst

@@ -79,7 +79,8 @@ Module contents
      class C:
          ...
 
-     @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False, weakref_slot=False)
+     @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False,
+                match_args=True, kw_only=False, slots=False, weakref_slot=False)
      class C:
          ...
 

Doc/library/dataclasses.rst

@@ -194,7 +194,7 @@ Data Types
 
    .. method:: EnumType.__getitem__(cls, name)
 
-      Returns the Enum member in *cls* matching *name*, or raises an :exc:`KeyError`::
+      Returns the Enum member in *cls* matching *name*, or raises a :exc:`KeyError`::
 
         >>> Color['BLUE']
         <Color.BLUE: 3>
@@ -241,7 +241,7 @@ Data Types
 
       .. note:: Enum member values
 
-         Member values can be anything: :class:`int`, :class:`str`, etc..  If
+         Member values can be anything: :class:`int`, :class:`str`, etc.  If
          the exact value is unimportant you may use :class:`auto` instances and an
          appropriate value will be chosen for you.  See :class:`auto` for the
          details.
@@ -255,7 +255,7 @@ Data Types
       names will also be removed from the completed enumeration.  See
       :ref:`TimePeriod <enum-time-period>` for an example.
 
-   .. method:: Enum.__call__(cls, value, names=None, \*, module=None, qualname=None, type=None, start=1, boundary=None)
+   .. method:: Enum.__call__(cls, value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
 
       This method is called in two different ways:
 
@@ -272,8 +272,8 @@ Data Types
          :module:    The name of the module the new Enum is created in.
          :qualname:  The actual location in the module where this Enum can be found.
          :type:  A mix-in type for the new Enum.
-         :start: The first integer value for the Enum (used by :class:`auto`)
-         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only)
+         :start: The first integer value for the Enum (used by :class:`auto`).
+         :boundary:  How to handle out-of-range values from bit operations (:class:`Flag` only).
 
    .. method:: Enum.__dir__(self)
 
@@ -315,7 +315,7 @@ Data Types
          >>> PowersOfThree.SECOND.value
          6
 
-   .. method:: Enum.__init_subclass__(cls, \**kwds)
+   .. method:: Enum.__init_subclass__(cls, **kwds)
 
       A *classmethod* that is used to further configure subsequent subclasses.
       By default, does nothing.
@@ -373,7 +373,7 @@ Data Types
    .. method:: Enum.__format__(self)
 
       Returns the string used for *format()* and *f-string* calls.  By default,
-      returns :meth:`__str__` returns, but can be overridden::
+      returns :meth:`__str__` return value, but can be overridden::
 
          >>> class OtherStyle(Enum):
          ...     ALTERNATE = auto()
@@ -389,6 +389,8 @@ Data Types
       Using :class:`auto` with :class:`Enum` results in integers of increasing value,
       starting with ``1``.
 
+   .. versionchanged:: 3.12 Added :ref:`enum-dataclass-support`
+
 
 .. class:: IntEnum
 
@@ -552,11 +554,11 @@ Data Types
       Using :class:`auto` with :class:`Flag` results in integers that are powers
       of two, starting with ``1``.
 
-   .. versionchanged:: 3.11  The *repr()* of zero-valued flags has changed.  It
+   .. versionchanged:: 3.11 The *repr()* of zero-valued flags has changed.  It
       is now::
 
-          >>> Color(0) # doctest: +SKIP
-          <Color: 0>
+         >>> Color(0) # doctest: +SKIP
+         <Color: 0>
 
 .. class:: IntFlag
 
@@ -600,7 +602,7 @@ Data Types
       *replacement of existing constants* use-case.  :meth:`~object.__format__` was
       already :meth:`!int.__format__` for that same reason.
 
-      Inversion of a :class:`!IntFlag` now returns a positive value that is the
+      Inversion of an :class:`!IntFlag` now returns a positive value that is the
       union of all flags not in the given flag, rather than a negative value.
       This matches the existing :class:`Flag` behavior.
 
@@ -612,7 +614,7 @@ Data Types
       * :meth:`!int.__str__` for :class:`IntEnum` and :class:`IntFlag`
       * :meth:`!str.__str__` for :class:`StrEnum`
 
-   Inherit from :class:`!ReprEnum` to keep the :class:`str() <str> / :func:`format`
+   Inherit from :class:`!ReprEnum` to keep the :class:`str() <str>` / :func:`format`
    of the mixed-in data type instead of using the
    :class:`Enum`-default :meth:`str() <Enum.__str__>`.
 
@@ -658,7 +660,7 @@ Data Types
    .. attribute:: NAMED_FLAGS
 
       Ensure that any flag groups/masks contain only named flags -- useful when
-      values are specified instead of being generated by :func:`auto`
+      values are specified instead of being generated by :func:`auto`::
 
          >>> from enum import Flag, verify, NAMED_FLAGS
          >>> @verify(NAMED_FLAGS)
@@ -804,6 +806,11 @@ Utilities and Decorators
       * ``THREE = [auto(), -3]`` will *not* work (``<auto instance>, -3`` is used to
         create the ``THREE`` enum member)
 
+   .. versionchanged:: 3.11.1
+
+      In prior versions, ``auto()`` had to be the only thing
+      on the assignment line to work properly.
+
    ``_generate_next_value_`` can be overridden to customize the values used by
    *auto*.
 
@@ -885,23 +892,23 @@ Notes
 
 :class:`IntEnum`, :class:`StrEnum`, and :class:`IntFlag`
 
-    These three enum types are designed to be drop-in replacements for existing
-    integer- and string-based values; as such, they have extra limitations:
+   These three enum types are designed to be drop-in replacements for existing
+   integer- and string-based values; as such, they have extra limitations:
 
-    - ``__str__`` uses the value and not the name of the enum member
+   - ``__str__`` uses the value and not the name of the enum member
 
-    - ``__format__``, because it uses ``__str__``, will also use the value of
-      the enum member instead of its name
+   - ``__format__``, because it uses ``__str__``, will also use the value of
+     the enum member instead of its name
 
-    If you do not need/want those limitations, you can either create your own
-    base class by mixing in the ``int`` or ``str`` type yourself::
+   If you do not need/want those limitations, you can either create your own
+   base class by mixing in the ``int`` or ``str`` type yourself::
 
-        >>> from enum import Enum
-        >>> class MyIntEnum(int, Enum):
-        ...     pass
+       >>> from enum import Enum
+       >>> class MyIntEnum(int, Enum):
+       ...     pass
 
    or you can reassign the appropriate :meth:`str`, etc., in your enum::
 
-        >>> from enum import IntEnum
-        >>> class MyIntEnum(IntEnum):
-        ...     __str__ = IntEnum.__str__
+       >>> from enum import IntEnum
+       >>> class MyIntEnum(IntEnum):
+       ...     __str__ = IntEnum.__str__

Doc/library/enum.rst

@@ -512,3 +512,12 @@ Security Considerations
 :class:`SimpleHTTPRequestHandler` will follow symbolic links when handling
 requests, this makes it possible for files outside of the specified directory
 to be served.
+
+Earlier versions of Python did not scrub control characters from the
+log messages emitted to stderr from ``python -m http.server`` or the
+default :class:`BaseHTTPRequestHandler` ``.log_message``
+implementation. This could allow remote clients connecting to your
+server to send nefarious control codes to your terminal.
+
+.. versionadded:: 3.12
+   Control characters are scrubbed in stderr logs.

Doc/library/http.server.rst

@@ -2575,6 +2575,10 @@ Functions and decorators
      assumed to be True or False if it is omitted by the caller.
    * ``kw_only_default`` indicates whether the ``kw_only`` parameter is
      assumed to be True or False if it is omitted by the caller.
+   * ``frozen_default`` indicates whether the ``frozen`` parameter is
+     assumed to be True or False if it is omitted by the caller.
+
+     .. versionadded:: 3.12
    * ``field_specifiers`` specifies a static list of supported classes
      or functions that describe fields, similar to ``dataclasses.field()``.
    * Arbitrary other keyword arguments are accepted in order to allow for

Doc/library/typing.rst

@@ -8,6 +8,7 @@ sphinx==4.5.0
 blurb
 
 sphinx-lint==0.6.7
+sphinxext-opengraph>=0.7.1
 
 # The theme used by the documentation is stored separately, so we need
 # to install that as well.

Doc/requirements.txt

@@ -8,6 +8,19 @@
     <a href="/3/{{ pagename }}{{ file_suffix }}">{% trans %} Python documentation for the current stable release{% endtrans %}</a>.
 </div>
 {%- endif %}
+
+{%- if is_deployment_preview %}
+<div id="deployment-preview-warning" style="padding: .5em; text-align: center; background-color: #fff2ba; color: #6a580e;">
+  <div style="float: right; margin-top: -10px; margin-left: 10px;">
+    <a href="https://www.netlify.com">
+      <img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" />
+    </a>
+  </div>
+  {% trans %}This is a deploy preview created from a <a href="{{ repository_url }}/pull/{{ pr_id }}">pull request</a>.
+  For authoritative documentation, see the {% endtrans %}
+  <a href="https://docs.python.org/3/{{ pagename }}{{ file_suffix }}">{% trans %} the current stable release{% endtrans %}</a>.
+</div>
+{%- endif %}
 {% endblock %}
 
 {% block rootrellink %}