Fix reference warnings for __enter__

python · hugovk · Oct 19, 2023 · Sep 29, 2023 · Sep 29, 2023 · Sep 29, 2023
commit 4b7f23fdb58dfd8ce8868d4682ceea1681f9f63e
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
@@ -239,7 +239,7 @@ Glossary
 
    context manager
       An object which controls the environment seen in a :keyword:`with`
-      statement by defining :meth:`__enter__` and :meth:`~object.__exit__` methods.
+      statement by defining :meth:`~object.__enter__` and :meth:`~object.__exit__` methods.
       See :pep:`343`.
 
    context variable

@@ -45,7 +45,7 @@ Functions and classes provided:
 
    This function is a :term:`decorator` that can be used to define a factory
    function for :keyword:`with` statement context managers, without needing to
-   create a class or separate :meth:`__enter__` and :meth:`~object.__exit__` methods.
+   create a class or separate :meth:`~object.__enter__` and :meth:`~object.__exit__` methods.
 
    While many objects natively support use in with statements, sometimes a
    resource needs to be managed that isn't a context manager in its own right,
@@ -515,7 +515,7 @@ Functions and classes provided:
           # the with statement, even if attempts to open files later
           # in the list raise an exception
 
-   The :meth:`__enter__` method returns the :class:`ExitStack` instance, and
+   The :meth:`~object.__enter__` method returns the :class:`ExitStack` instance, and
    performs no additional operations.
 
    Each instance maintains a stack of registered callbacks that are called in
@@ -545,7 +545,7 @@ Functions and classes provided:
 
       Enters a new context manager and adds its :meth:`~object.__exit__` method to
       the callback stack. The return value is the result of the context
-      manager's own :meth:`__enter__` method.
+      manager's own :meth:`~object.__enter__` method.
 
       These context managers may suppress exceptions just as they normally
       would if used directly as part of a :keyword:`with` statement.
@@ -559,7 +559,7 @@ Functions and classes provided:
       Adds a context manager's :meth:`~object.__exit__` method to the callback stack.
 
       As ``__enter__`` is *not* invoked, this method can be used to cover
-      part of an :meth:`__enter__` implementation with a context manager's own
+      part of an :meth:`~object.__enter__` implementation with a context manager's own
       :meth:`~object.__exit__` method.
 
       If passed an object that is not a context manager, this method assumes
@@ -714,7 +714,7 @@ Cleaning up in an ``__enter__`` implementation
 
 As noted in the documentation of :meth:`ExitStack.push`, this
 method can be useful in cleaning up an already allocated resource if later
-steps in the :meth:`__enter__` implementation fail.
+steps in the :meth:`~object.__enter__` implementation fail.
 
 Here's an example of doing this for a context manager that accepts resource
 acquisition and release functions, along with an optional validation function,
@@ -871,7 +871,7 @@ And also as a function decorator::
 
 Note that there is one additional limitation when using context managers
 as function decorators: there's no way to access the return value of
-:meth:`__enter__`. If that value is needed, then it is still necessary to use
+:meth:`~object.__enter__`. If that value is needed, then it is still necessary to use
 an explicit ``with`` statement.
 
 .. seealso::

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
@@ -2531,7 +2531,7 @@ are closed properly and is becoming common::
         f.write('something')
 
 The issue is that even if you mock out the call to :func:`open` it is the
-*returned object* that is used as a context manager (and has :meth:`__enter__` and
+*returned object* that is used as a context manager (and has :meth:`~object.__enter__` and
 :meth:`~object.__exit__` called).
 
 Mocking context managers with a :class:`MagicMock` is common enough and fiddly

@@ -489,18 +489,18 @@ The execution of the :keyword:`with` statement with one "item" proceeds as follo
 #. The context expression (the expression given in the
    :token:`~python-grammar:with_item`) is evaluated to obtain a context manager.
 
-#. The context manager's :meth:`__enter__` is loaded for later use.
+#. The context manager's :meth:`~object.__enter__` is loaded for later use.
 
 #. The context manager's :meth:`~object.__exit__` is loaded for later use.
 
-#. The context manager's :meth:`__enter__` method is invoked.
+#. The context manager's :meth:`~object.__enter__` method is invoked.
 
 #. If a target was included in the :keyword:`with` statement, the return value
-   from :meth:`__enter__` is assigned to it.
+   from :meth:`~object.__enter__` is assigned to it.
 
    .. note::
 
-      The :keyword:`with` statement guarantees that if the :meth:`__enter__`
+      The :keyword:`with` statement guarantees that if the :meth:`~object.__enter__`
       method returns without an error, then :meth:`~object.__exit__` will always be
       called. Thus, if an error occurs during the assignment to the target list,
       it will be treated the same as an error occurring within the suite would

@@ -3257,7 +3257,7 @@ Asynchronous context managers can be used in an :keyword:`async with` statement.
 
 .. method:: object.__aenter__(self)
 
-   Semantically similar to :meth:`__enter__`, the only
+   Semantically similar to :meth:`~object.__enter__`, the only
    difference being that it must return an *awaitable*.
 
 .. method:: object.__aexit__(self, exc_type, exc_value, traceback)

diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst
@@ -575,10 +575,10 @@ structure is::
        with-block
 
 The expression is evaluated, and it should result in an object that supports the
-context management protocol (that is, has :meth:`__enter__` and :meth:`~object.__exit__`
+context management protocol (that is, has :meth:`~object.__enter__` and :meth:`~object.__exit__`
 methods.
 
-The object's :meth:`__enter__` is called before *with-block* is executed and
+The object's :meth:`~object.__enter__` is called before *with-block* is executed and
 therefore can run set-up code. It also may return a value that is bound to the
 name *variable*, if given.  (Note carefully that *variable* is *not* assigned
 the result of *expression*.)
@@ -652,10 +652,10 @@ underlying implementation and should keep reading.
 A high-level explanation of the context management protocol is:
 
 * The expression is evaluated and should result in an object called a "context
-  manager".  The context manager must have :meth:`__enter__` and :meth:`~object.__exit__`
+  manager".  The context manager must have :meth:`~object.__enter__` and :meth:`~object.__exit__`
   methods.
 
-* The context manager's :meth:`__enter__` method is called.  The value returned
+* The context manager's :meth:`~object.__enter__` method is called.  The value returned
   is assigned to *VAR*.  If no ``'as VAR'`` clause is present, the value is simply
   discarded.
 
@@ -703,7 +703,7 @@ rolled back if there's an exception. Here's the basic interface for
        def rollback (self):
            "Rolls back current transaction"
 
-The :meth:`__enter__` method is pretty easy, having only to start a new
+The :meth:`~object.__enter__` method is pretty easy, having only to start a new
 transaction.  For this application the resulting cursor object would be a useful
 result, so the method will return it.  The user can then add ``as cursor`` to
 their ':keyword:`with`' statement to bind the cursor to a variable name. ::
@@ -748,7 +748,7 @@ are useful for writing objects for use with the ':keyword:`with`' statement.
 The decorator is called :func:`contextmanager`, and lets you write a single
 generator function instead of defining a new class.  The generator should yield
 exactly one value.  The code up to the :keyword:`yield` will be executed as the
-:meth:`__enter__` method, and the value yielded will be the method's return
+:meth:`~object.__enter__` method, and the value yielded will be the method's return
 value that will get bound to the variable in the ':keyword:`with`' statement's
 :keyword:`!as` clause, if any.  The code after the :keyword:`yield` will be
 executed in the :meth:`~object.__exit__` method.  Any exception raised in the block will

diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
@@ -269,10 +269,10 @@ structure is::
        with-block
 
 The expression is evaluated, and it should result in an object that supports the
-context management protocol (that is, has :meth:`__enter__` and :meth:`~object.__exit__`
+context management protocol (that is, has :meth:`~object.__enter__` and :meth:`~object.__exit__`
 methods).
 
-The object's :meth:`__enter__` is called before *with-block* is executed and
+The object's :meth:`~object.__enter__` is called before *with-block* is executed and
 therefore can run set-up code. It also may return a value that is bound to the
 name *variable*, if given.  (Note carefully that *variable* is *not* assigned
 the result of *expression*.)
@@ -339,10 +339,10 @@ underlying implementation and should keep reading.
 A high-level explanation of the context management protocol is:
 
 * The expression is evaluated and should result in an object called a "context
-  manager".  The context manager must have :meth:`__enter__` and :meth:`~object.__exit__`
+  manager".  The context manager must have :meth:`~object.__enter__` and :meth:`~object.__exit__`
   methods.
 
-* The context manager's :meth:`__enter__` method is called.  The value returned
+* The context manager's :meth:`~object.__enter__` method is called.  The value returned
   is assigned to *VAR*.  If no ``as VAR`` clause is present, the value is simply
   discarded.
 
@@ -391,7 +391,7 @@ rolled back if there's an exception. Here's the basic interface for
        def rollback(self):
            "Rolls back current transaction"
 
-The :meth:`__enter__` method is pretty easy, having only to start a new
+The :meth:`~object.__enter__` method is pretty easy, having only to start a new
 transaction.  For this application the resulting cursor object would be a useful
 result, so the method will return it.  The user can then add ``as cursor`` to
 their ':keyword:`with`' statement to bind the cursor to a variable name. ::
@@ -436,7 +436,7 @@ are useful when writing objects for use with the ':keyword:`with`' statement.
 The decorator is called :func:`contextmanager`, and lets you write a single
 generator function instead of defining a new class.  The generator should yield
 exactly one value.  The code up to the :keyword:`yield` will be executed as the
-:meth:`__enter__` method, and the value yielded will be the method's return
+:meth:`~object.__enter__` method, and the value yielded will be the method's return
 value that will get bound to the variable in the ':keyword:`with`' statement's
 :keyword:`!as` clause, if any.  The code after the :keyword:`!yield` will be
 executed in the :meth:`~object.__exit__` method.  Any exception raised in the block will

diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
@@ -930,7 +930,7 @@ Optimizations
 Several performance enhancements have been added:
 
 * A new opcode was added to perform the initial setup for
-  :keyword:`with` statements, looking up the :meth:`__enter__` and
+  :keyword:`with` statements, looking up the :meth:`~object.__enter__` and
   :meth:`~object.__exit__` methods.  (Contributed by Benjamin Peterson.)
 
 * The garbage collector now performs better for one common usage
@@ -2449,7 +2449,7 @@ that may require changes to your code:
   (Changed by Eric Smith; :issue:`5920`.)
 
 * Because of an optimization for the :keyword:`with` statement, the special
-  methods :meth:`__enter__` and :meth:`~object.__exit__` must belong to the object's
+  methods :meth:`~object.__enter__` and :meth:`~object.__exit__` must belong to the object's
   type, and cannot be directly attached to the object's instance.  This
   affects new-style classes (derived from :class:`object`) and C extension
   types.  (:issue:`6101`.)