Dec 15, 2023 · Dec 15, 2023 · Dec 15, 2023
diff --git a/Doc/conf.py b/Doc/conf.py
    # Attributes/methods/etc. that definitely should be documented better,
    # but are deferred for now:
    ('py:attr', '__annotations__'),
    ('py:meth', '__missing__'),
    ('py:attr', '__wrapped__'),
    ('py:meth', 'index'),  # list.index, tuple.index, etc.
 ]
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
   American EST and EDT.

   Special requirement for pickling:  A :class:`tzinfo` subclass must have an
   :meth:`__init__` method that can be called with no arguments, otherwise it can be
   :meth:`~object.__init__` method that can be called with no arguments,
   otherwise it can be
   pickled but possibly not unpickled again. This is a technical requirement that
   may be relaxed in the future.

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
         True


   Note that :exc:`BaseExceptionGroup` defines :meth:`__new__`, so
   Note that :exc:`BaseExceptionGroup` defines :meth:`~object.__new__`, so
   subclasses that need a different constructor signature need to
   override that rather than :meth:`__init__`. For example, the following
   override that rather than :meth:`~object.__init__`. For example, the following
   defines an exception group subclass which accepts an exit_code and
   and constructs the group's message from it. ::

diff --git a/Doc/library/test.rst b/Doc/library/test.rst

 .. class:: FakePath(path)

   Simple :term:`path-like object`.  It implements the :meth:`__fspath__`
   Simple :term:`path-like object`.  It implements the
   :meth:`~os.PathLike.__fspath__`
   method which just returns the *path* argument.  If *path* is an exception,
   it will be raised in :meth:`!__fspath__`.

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst

 .. class:: PropertyMock(*args, **kwargs)

   A mock intended to be used as a property, or other descriptor, on a class.
   :class:`PropertyMock` provides :meth:`__get__` and :meth:`__set__` methods
   A mock intended to be used as a :class:`property`, or other
   :term:`descriptor`, on a class. :class:`PropertyMock` provides
   :meth:`~object.__get__` and :meth:`~object.__set__` methods
   so you can specify a return value when it is fetched.

   Fetching a :class:`PropertyMock` instance from an object calls the mock, with
 :func:`patch.dict` can be used with dictionary like objects that aren't actually
 dictionaries. At the very minimum they must support item getting, setting,
 deleting and either iteration or membership test. This corresponds to the
 magic methods :meth:`~object.__getitem__`, :meth:`__setitem__`, :meth:`__delitem__` and either
 :meth:`__iter__` or :meth:`__contains__`.
 magic methods :meth:`~object.__getitem__`, :meth:`~object.__setitem__`,
 :meth:`~object.__delitem__` and either :meth:`~container.__iter__` or
 :meth:`~object.__contains__`.

    >>> class Container:
    ...     def __init__(self):
   >>> object() in mock
   False

 The two equality methods, :meth:`__eq__` and :meth:`__ne__`, are special.
 The two equality methods, :meth:`!__eq__` and :meth:`!__ne__`, are special.
 They do the default equality comparison on identity, using the
 :attr:`~Mock.side_effect` attribute, unless you change their return value to
 return something else::
      *read_data* is now reset on each call to the *mock*.

   .. versionchanged:: 3.8
      Added :meth:`__iter__` to implementation so that iteration (such as in for
      loops) correctly consumes *read_data*.
      Added :meth:`~container.__iter__` to implementation so that iteration
 (such as in forloops) correctly consumes *read_data*.

 Using :func:`open` as a context manager is a great way to ensure your file handles
 are closed properly and is becoming common::
 objects so that introspection is safe [#]_.

 A more serious problem is that it is common for instance attributes to be
 created in the :meth:`__init__` method and not to exist on the class at all.
 created in the :meth:`~object.__init__` method and not to exist on the class at all.
 *autospec* can't know about any dynamically created attributes and restricts
 the api to visible attributes. ::

    AttributeError: Mock object has no attribute 'a'

 Probably the best way of solving the problem is to add class attributes as
 default values for instance members initialised in :meth:`__init__`. Note that if
 you are only setting default attributes in :meth:`__init__` then providing them via
 default values for instance members initialised in :meth:`~object.__init__`.
 Note that if
 you are only setting default attributes in :meth:`!__init__` then providing them via
 class attributes (shared between instances of course) is faster too. e.g.

 .. code-block:: python
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
   .. method:: __iter__()

      Tests grouped by a :class:`TestSuite` are always accessed by iteration.
      Subclasses can lazily provide tests by overriding :meth:`__iter__`. Note
      Subclasses can lazily provide tests by overriding :meth:`!__iter__`. Note
      that this method may be called several times on a single suite (for
      example when counting tests or comparing for equality) so the tests
      returned by repeated iterations before :meth:`TestSuite.run` must be the

      .. versionchanged:: 3.2
         In earlier versions the :class:`TestSuite` accessed tests directly rather
         than through iteration, so overriding :meth:`__iter__` wasn't sufficient
         than through iteration, so overriding :meth:`!__iter__` wasn't sufficient
         for providing tests.

      .. versionchanged:: 3.4
diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst
   an empty list.

   :class:`Headers` objects support typical mapping operations including
   :meth:`~object.__getitem__`, :meth:`get`, :meth:`__setitem__`, :meth:`setdefault`,
   :meth:`__delitem__` and :meth:`__contains__`.  For each of
   :meth:`~object.__getitem__`, :meth:`~dict.get`, :meth:`~object.__setitem__`,
   :meth:`~dict.setdefault`,
   :meth:`~object.__delitem__` and :meth:`~object.__contains__`.  For each of
   these methods, the key is the header name (treated case-insensitively), and the
   value is the first value associated with that header name.  Setting a header
   deletes any existing values for that header, then adds a new value at the end of
   want to subclass this instead of :class:`BaseCGIHandler`.

   This class is a subclass of :class:`BaseHandler`.  It overrides the
   :meth:`__init__`, :meth:`get_stdin`, :meth:`get_stderr`, :meth:`add_cgi_vars`,
   :meth:`_write`, and :meth:`_flush` methods to support explicitly setting the
   :meth:`!__init__`, :meth:`~BaseHandler.get_stdin`,
   :meth:`~BaseHandler.get_stderr`, :meth:`~BaseHandler.add_cgi_vars`,
   :meth:`~BaseHandler._write`, and :meth:`~BaseHandler._flush` methods to
   support explicitly setting the
   environment and streams via the constructor.  The supplied environment and
   streams are stored in the :attr:`stdin`, :attr:`stdout`, :attr:`stderr`, and
   :attr:`environ` attributes.
diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst
      Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream
      object.

   It also supports certain of Python's built-in operators through rich comparison
   and :meth:`__repr__` methods.
   It also supports certain of Python's built-in operators through
   :meth:`rich comparison <object.__lt__>` and :meth:`~object.__repr__`
   methods.

 A working example follows. The server code::

      which was the de facto standard base64 specification when the
      XML-RPC spec was written.

   It also supports certain of Python's built-in operators through :meth:`__eq__`
   and :meth:`__ne__` methods.
   It also supports certain of Python's built-in operators through
 :meth:`~object.__eq__`and :meth:`~object.__ne__` methods.

 Example usage of the binary objects.  We're going to transfer an image over
 XMLRPC::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -234,6 +234,7 @@
		# Attributes/methods/etc. that definitely should be documented better,
		# but are deferred for now:
		('py:attr', '__annotations__'),
		('py:meth', '__missing__'),
		('py:attr', '__wrapped__'),
		('py:meth', 'index'), # list.index, tuple.index, etc.
		]
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1968,7 +1968,8 @@ Examples of working with a :class:`.time` object::
		American EST and EDT.

		Special requirement for pickling: A :class:`tzinfo` subclass must have an
		:meth:`__init__` method that can be called with no arguments, otherwise it can be
		:meth:`~object.__init__` method that can be called with no arguments,
		otherwise it can be
		pickled but possibly not unpickled again. This is a technical requirement that
		may be relaxed in the future.

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1005,9 +1005,9 @@ their subgroups based on the types of the contained exceptions.
		True


		Note that :exc:`BaseExceptionGroup` defines :meth:`__new__`, so
		Note that :exc:`BaseExceptionGroup` defines :meth:`~object.__new__`, so
		subclasses that need a different constructor signature need to
		override that rather than :meth:`__init__`. For example, the following
		override that rather than :meth:`~object.__init__`. For example, the following
		defines an exception group subclass which accepts an exit_code and
		and constructs the group's message from it. ::

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1386,7 +1386,8 @@ The :mod:`test.support.os_helper` module provides support for os tests.

		.. class:: FakePath(path)

		Simple :term:`path-like object`. It implements the :meth:`__fspath__`
		Simple :term:`path-like object`. It implements the
		:meth:`~os.PathLike.__fspath__`
		method which just returns the path argument. If path is an exception,
		it will be raised in :meth:`!__fspath__`.

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -819,8 +819,9 @@ apply to method calls on the mock object.

		.. class:: PropertyMock(args, *kwargs)

		A mock intended to be used as a property, or other descriptor, on a class.
		:class:`PropertyMock` provides :meth:`__get__` and :meth:`__set__` methods
		A mock intended to be used as a :class:`property`, or other
		:term:`descriptor`, on a class. :class:`PropertyMock` provides
		:meth:`~object.__get__` and :meth:`~object.__set__` methods
		so you can specify a return value when it is fetched.

		Fetching a :class:`PropertyMock` instance from an object calls the mock, with
Expand DownExpand Up		@@ -1656,8 +1657,9 @@ Keywords can be used in the :func:`patch.dict` call to set values in the diction
		:func:`patch.dict` can be used with dictionary like objects that aren't actually
		dictionaries. At the very minimum they must support item getting, setting,
		deleting and either iteration or membership test. This corresponds to the
		magic methods :meth:`~object.__getitem__`, :meth:`__setitem__`, :meth:`__delitem__` and either
		:meth:`__iter__` or :meth:`__contains__`.
		magic methods :meth:`~object.__getitem__`, :meth:`~object.__setitem__`,
		:meth:`~object.__delitem__` and either :meth:`~container.__iter__` or
		:meth:`~object.__contains__`.

		>>> class Container:
		... def __init__(self):
Expand DownExpand Up		@@ -2120,7 +2122,7 @@ For example:
		>>> object() in mock
		False

		The two equality methods, :meth:`__eq__` and :meth:`__ne__`, are special.
		The two equality methods, :meth:`!__eq__` and :meth:`!__ne__`, are special.
		They do the default equality comparison on identity, using the
		:attr:`~Mock.side_effect` attribute, unless you change their return value to
		return something else::
Expand DownExpand Up		@@ -2470,8 +2472,8 @@ mock_open
		read_data is now reset on each call to the mock.

		.. versionchanged:: 3.8
		Added :meth:`__iter__` to implementation so that iteration (such as in for
		loops) correctly consumes read_data.
		Added :meth:`~container.__iter__` to implementation so that iteration
		(such as in forloops) correctly consumes read_data.

		Using :func:`open` as a context manager is a great way to ensure your file handles
		are closed properly and is becoming common::
Expand DownExpand Up		@@ -2653,7 +2655,7 @@ able to use autospec. On the other hand it is much better to design your
		objects so that introspection is safe [#]_.

		A more serious problem is that it is common for instance attributes to be
		created in the :meth:`__init__` method and not to exist on the class at all.
		created in the :meth:`~object.__init__` method and not to exist on the class at all.
		autospec can't know about any dynamically created attributes and restricts
		the api to visible attributes. ::

Expand DownExpand Up		@@ -2694,8 +2696,9 @@ this particular scenario:
		AttributeError: Mock object has no attribute 'a'

		Probably the best way of solving the problem is to add class attributes as
		default values for instance members initialised in :meth:`__init__`. Note that if
		you are only setting default attributes in :meth:`__init__` then providing them via
		default values for instance members initialised in :meth:`~object.__init__`.
		Note that if
		you are only setting default attributes in :meth:`!__init__` then providing them via
		class attributes (shared between instances of course) is faster too. e.g.

		.. code-block:: python
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1756,7 +1756,7 @@ Grouping tests
		.. method:: __iter__()

		Tests grouped by a :class:`TestSuite` are always accessed by iteration.
		Subclasses can lazily provide tests by overriding :meth:`__iter__`. Note
		Subclasses can lazily provide tests by overriding :meth:`!__iter__`. Note
		that this method may be called several times on a single suite (for
		example when counting tests or comparing for equality) so the tests
		returned by repeated iterations before :meth:`TestSuite.run` must be the
Expand All		@@ -1767,7 +1767,7 @@ Grouping tests

		.. versionchanged:: 3.2
		In earlier versions the :class:`TestSuite` accessed tests directly rather
		than through iteration, so overriding :meth:`__iter__` wasn't sufficient
		than through iteration, so overriding :meth:`!__iter__` wasn't sufficient
		for providing tests.

		.. versionchanged:: 3.4
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -201,8 +201,9 @@ manipulation of WSGI response headers using a mapping-like interface.
		an empty list.

		:class:`Headers` objects support typical mapping operations including
		:meth:`~object.__getitem__`, :meth:`get`, :meth:`__setitem__`, :meth:`setdefault`,
		:meth:`__delitem__` and :meth:`__contains__`. For each of
		:meth:`~object.__getitem__`, :meth:`~dict.get`, :meth:`~object.__setitem__`,
		:meth:`~dict.setdefault`,
		:meth:`~object.__delitem__` and :meth:`~object.__contains__`. For each of
		these methods, the key is the header name (treated case-insensitively), and the
		value is the first value associated with that header name. Setting a header
		deletes any existing values for that header, then adds a new value at the end of
Expand DownExpand Up		@@ -520,8 +521,10 @@ input, output, and error streams.
		want to subclass this instead of :class:`BaseCGIHandler`.

		This class is a subclass of :class:`BaseHandler`. It overrides the
		:meth:`__init__`, :meth:`get_stdin`, :meth:`get_stderr`, :meth:`add_cgi_vars`,
		:meth:`_write`, and :meth:`_flush` methods to support explicitly setting the
		:meth:`!__init__`, :meth:`~BaseHandler.get_stdin`,
		:meth:`~BaseHandler.get_stderr`, :meth:`~BaseHandler.add_cgi_vars`,
		:meth:`~BaseHandler._write`, and :meth:`~BaseHandler._flush` methods to
		support explicitly setting the
		environment and streams via the constructor. The supplied environment and
		streams are stored in the :attr:`stdin`, :attr:`stdout`, :attr:`stderr`, and
		:attr:`environ` attributes.
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -269,8 +269,9 @@ DateTime Objects
		Write the XML-RPC encoding of this :class:`DateTime` item to the out stream
		object.

		It also supports certain of Python's built-in operators through rich comparison
		and :meth:`__repr__` methods.
		It also supports certain of Python's built-in operators through
		:meth:`rich comparison <object.__lt__>` and :meth:`~object.__repr__`
		methods.

		A working example follows. The server code::

Expand DownExpand Up		@@ -334,8 +335,8 @@ Binary Objects
		which was the de facto standard base64 specification when the
		XML-RPC spec was written.

		It also supports certain of Python's built-in operators through :meth:`__eq__`
		and :meth:`__ne__` methods.
		It also supports certain of Python's built-in operators through
		:meth:`~object.__eq__`and :meth:`~object.__ne__` methods.

		Example usage of the binary objects. We're going to transfer an image over
		XMLRPC::
Expand Down