From 4d950a83fcbc74285cfaa975331b924e5d981ff6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Tue, 20 Apr 2021 23:56:50 +0200 Subject: [PATCH 01/13] Update weakref.rst --- Doc/library/weakref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index d3c3a070f38af0..a2d3ec41f06f1d 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -137,7 +137,7 @@ Extension types can easily be made to support weak references; see ``ProxyType`` or ``CallableProxyType``, depending on whether *object* is callable. Proxy objects are not :term:`hashable` regardless of the referent; this avoids a number of problems related to their fundamentally mutable nature, and - prevent their use as dictionary keys. *callback* is the same as the parameter + prevents their use as dictionary keys. *callback* is the same as the parameter of the same name to the :func:`ref` function. .. versionchanged:: 3.8 From c2d8a6bc239d11744213ca74d610a181cbff8dc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Thu, 22 Apr 2021 12:15:39 +0200 Subject: [PATCH 02/13] Update weakref.rst --- Doc/library/weakref.rst | 60 ++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index a2d3ec41f06f1d..fc1ffc8cd8e30a 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -91,13 +91,13 @@ Extension types can easily be made to support weak references; see .. class:: ref(object[, callback]) - Return a weak reference to *object*. The original object can be retrieved by - calling the reference object if the referent is still alive; if the referent is - no longer alive, calling the reference object will cause :const:`None` to be - returned. If *callback* is provided and not :const:`None`, and the returned - weakref object is still alive, the callback will be called when the object is - about to be finalized; the weak reference object will be passed as the only - parameter to the callback; the referent will no longer be available. + Return a weak reference to *object*. The referent can be retrieved by + calling the weak reference if the referent is still alive; if the referent is + no longer alive, calling the weak reference will cause :const:`None` to be + returned. If *callback* is provided and not :const:`None`, and the weak + reference is still alive, the callback will be called when the referent is + about to be finalized; the weak reference will be passed as the only + argument to the callback; the referent will no longer be available. It is allowable for many weak references to be constructed for the same object. Callbacks registered for each weak reference will be called from the most @@ -113,9 +113,9 @@ Extension types can easily be made to support weak references; see the call will raise :exc:`TypeError`. Weak references support tests for equality, but not ordering. If the referents - are still alive, two references have the same equality relationship as their + are still alive, two weak references have the same equality relationship as their referents (regardless of the *callback*). If either referent has been deleted, - the references are equal only if the reference objects are the same object. + two weak references are equal only if the weak references are the same object. This is a subclassable type rather than a factory function. @@ -133,15 +133,15 @@ Extension types can easily be made to support weak references; see Return a proxy to *object* which uses a weak reference. This supports use of the proxy in most contexts instead of requiring the explicit dereferencing used - with weak reference objects. The returned object will have a type of either + with weak references. The returned object will have a type of either ``ProxyType`` or ``CallableProxyType``, depending on whether *object* is - callable. Proxy objects are not :term:`hashable` regardless of the referent; this + callable. Proxies are not :term:`hashable` regardless of the referent; this avoids a number of problems related to their fundamentally mutable nature, and prevents their use as dictionary keys. *callback* is the same as the parameter of the same name to the :func:`ref` function. .. versionchanged:: 3.8 - Extended the operator support on proxy objects to include the matrix + Extended the operator support on proxies to include the matrix multiplication operators ``@`` and ``@=``. @@ -152,7 +152,7 @@ Extension types can easily be made to support weak references; see .. function:: getweakrefs(object) - Return a list of all weak reference and proxy objects which refer to *object*. + Return a list of all weak references and proxies which refer to *object*. .. class:: WeakKeyDictionary([dict]) @@ -233,9 +233,9 @@ objects. .. class:: finalize(obj, func, /, *args, **kwargs) - Return a callable finalizer object which will be called when *obj* - is garbage collected. Unlike an ordinary weak reference, a finalizer - will always survive until the reference object is collected, greatly + Return a callable finalizer which will be called when *obj* + is garbage collected. Unlike an ordinary weak reference, a finalizer + will always survive until the referent is collected, greatly simplifying lifecycle management. A finalizer is considered *alive* until it is called (either explicitly @@ -297,17 +297,17 @@ objects. .. data:: ReferenceType - The type object for weak references objects. + The type object for weak references. .. data:: ProxyType - The type object for proxies of objects which are not callable. + The type object for proxies to objects which are not callable. .. data:: CallableProxyType - The type object for proxies of callable objects. + The type object for proxies to callable objects. .. data:: ProxyTypes @@ -329,8 +329,8 @@ objects. Weak Reference Objects ---------------------- -Weak reference objects have no methods and no attributes besides -:attr:`ref.__callback__`. A weak reference object allows the referent to be +Weak references have no methods and no attributes besides +:attr:`ref.__callback__`. A weak reference allows the referent to be obtained, if it still exists, by calling it: >>> import weakref @@ -350,11 +350,11 @@ If the referent no longer exists, calling the reference object returns >>> print(r()) None -Testing that a weak reference object is still live should be done using the +Testing that a weak reference is still live should be done using the expression ``ref() is not None``. Normally, application code that needs to use -a reference object should follow this pattern:: +a weak reference should follow this pattern:: - # r is a weak reference object + # r is a weak reference o = r() if o is None: # referent has been garbage collected @@ -431,8 +431,8 @@ Finalizer Objects ----------------- The main benefit of using :class:`finalize` is that it makes it simple -to register a callback without needing to preserve the returned finalizer -object. For instance +to register a callback without needing to preserve the returned finalizer. +For instance >>> import weakref >>> class Object: @@ -488,7 +488,7 @@ is still alive. For instance obj dead or exiting -Comparing finalizers with :meth:`__del__` methods +Comparing Finalizers with :meth:`__del__` Methods ------------------------------------------------- Suppose we want to create a class whose instances represent temporary @@ -547,8 +547,8 @@ Defined like this, our finalizer only receives a reference to the details it needs to clean up the directory appropriately. If the object never gets garbage collected the finalizer will still be called at exit. -The other advantage of weakref based finalizers is that they can be used to -register finalizers for classes where the definition is controlled by a +The other advantage of finalizers is that they can be used +for classes where the definition is controlled by a third party, such as running code when a module is unloaded:: import weakref, sys @@ -559,7 +559,7 @@ third party, such as running code when a module is unloaded:: .. note:: - If you create a finalizer object in a daemonic thread just as the program + If you create a finalizer in a daemonic thread just as the program exits then there is the possibility that the finalizer does not get called at exit. However, in a daemonic thread :func:`atexit.register`, ``try: ... finally: ...`` and ``with: ...`` From 0897c446cac0d1b0f9e7d5c460c18cb29331cb7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Thu, 22 Apr 2021 15:28:18 +0200 Subject: [PATCH 03/13] Add the undocumented optional callback parameter to WeakMethod --- Doc/library/weakref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index fc1ffc8cd8e30a..4dffde7841f5a5 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -203,7 +203,7 @@ objects. discarded when no strong reference to it exists any more. -.. class:: WeakMethod(method) +.. class:: WeakMethod(method[, callback]) A custom :class:`ref` subclass which simulates a weak reference to a bound method (i.e., a method defined on a class and looked up on an instance). From 819a5835ab6ac257dd0c36eeea66aedcb1900e03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 4 Apr 2022 22:51:56 +0200 Subject: [PATCH 04/13] Document the callback parameter to WeakMethod --- Doc/library/weakref.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 97ffa5eeb47a53..8914b148f45bf0 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -233,6 +233,8 @@ objects. >>> r() >>> + *callback* is the same as the parameter of the same name to the :func:`ref` function. + .. versionadded:: 3.4 .. class:: finalize(obj, func, /, *args, **kwargs) From 7e437b57e2db30f715d1abb527c5869f181a89d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 4 Apr 2022 22:59:47 +0200 Subject: [PATCH 05/13] Create 2022-04-04-22-54-11.bpo-47167.nCNHsB.rst --- .../NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47167.nCNHsB.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47167.nCNHsB.rst diff --git a/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47167.nCNHsB.rst b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47167.nCNHsB.rst new file mode 100644 index 00000000000000..325ab70920a1e6 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47167.nCNHsB.rst @@ -0,0 +1 @@ +Document the optional *callback* parameter of :class:`WeakMethod`. Patch by Géry Ogam. From 52a0e64245439d4145811c03f0b40f8553bc700c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 4 Apr 2022 23:07:34 +0200 Subject: [PATCH 06/13] Rename 2022-04-04-22-54-11.bpo-47167.nCNHsB.rst to 2022-04-04-22-54-11.bpo-47220.L9jYu4.rst --- ...-47167.nCNHsB.rst => 2022-04-04-22-54-11.bpo-47220.L9jYu4.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Misc/NEWS.d/next/Library/{2022-04-04-22-54-11.bpo-47167.nCNHsB.rst => 2022-04-04-22-54-11.bpo-47220.L9jYu4.rst} (100%) diff --git a/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47167.nCNHsB.rst b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst similarity index 100% rename from Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47167.nCNHsB.rst rename to Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst From afcabaeca425e475e5063e07cfd084f99e0d4fc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 4 Apr 2022 23:09:51 +0200 Subject: [PATCH 07/13] Update 2022-04-04-22-54-11.bpo-47220.L9jYu4.rst --- .../next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst index 325ab70920a1e6..54665f446ef1ac 100644 --- a/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst +++ b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst @@ -1 +1 @@ -Document the optional *callback* parameter of :class:`WeakMethod`. Patch by Géry Ogam. +Document the optional *callback* parameter of :class:`weakref.WeakMethod`. Patch by Géry Ogam. From da83bd69e991091c7eb97a03d353af81032e6063 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 4 Apr 2022 23:10:23 +0200 Subject: [PATCH 08/13] Update 2022-04-04-22-54-11.bpo-47220.L9jYu4.rst --- .../next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst index 54665f446ef1ac..a19cc7b75f4f09 100644 --- a/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst +++ b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst @@ -1 +1,2 @@ -Document the optional *callback* parameter of :class:`weakref.WeakMethod`. Patch by Géry Ogam. +Document the optional *callback* parameter of :class:`WeakMethod`. Patch by +Géry Ogam. From b8a0169f1a0d5f5225b13770464e994b0368053c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 4 Apr 2022 23:38:34 +0200 Subject: [PATCH 09/13] Update 2022-04-04-22-54-11.bpo-47220.L9jYu4.rst --- .../next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst index a19cc7b75f4f09..6e2af088640b55 100644 --- a/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst +++ b/Misc/NEWS.d/next/Library/2022-04-04-22-54-11.bpo-47220.L9jYu4.rst @@ -1,2 +1,2 @@ -Document the optional *callback* parameter of :class:`WeakMethod`. Patch by +Document the optional *callback* parameter of :class:`WeakMethod`. Patch by Géry Ogam. From 7a78eebf3767d5c3abb638e0bc58623ed664e7cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Thu, 12 May 2022 23:18:04 +0200 Subject: [PATCH 10/13] Normalise and disambiguate --- Doc/library/weakref.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 8914b148f45bf0..a5f430a870cb68 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -171,10 +171,10 @@ See :ref:`__slots__ documentation ` for details. Added support for ``|`` and ``|=`` operators, specified in :pep:`584`. :class:`WeakKeyDictionary` objects have an additional method that -exposes the internal references directly. The references are not guaranteed to -be "live" at the time they are used, so the result of calling the references +exposes the internal weak references directly. The weak references are not guaranteed to +be "live" at the time they are used, so the result of calling them needs to be checked before being used. This can be used to avoid creating -references that will cause the garbage collector to keep the keys around longer +strong references that will cause the garbage collector to keep the keys around longer than needed. @@ -294,7 +294,7 @@ objects. .. note:: It is important to ensure that *func*, *args* and *kwargs* do - not own any references to *obj*, either directly or indirectly, + not own any strong references to *obj*, either directly or indirectly, since otherwise *obj* will never be garbage collected. In particular, *func* should not be a bound method of *obj*. @@ -336,7 +336,7 @@ Weak Reference Objects ---------------------- Weak references have no methods and no attributes besides -:attr:`ref.__callback__`. A weak reference allows the referent to be +:attr:`ref.__callback__`. A weak reference allows the referent to be obtained, if it still exists, by calling it: >>> import weakref @@ -349,7 +349,7 @@ obtained, if it still exists, by calling it: >>> o is o2 True -If the referent no longer exists, calling the reference object returns +If the referent no longer exists, calling the weak reference returns :const:`None`: >>> del o, o2 @@ -377,7 +377,7 @@ applications as well as single-threaded applications. Specialized versions of :class:`ref` objects can be created through subclassing. This is used in the implementation of the :class:`WeakValueDictionary` to reduce the memory overhead for each entry in the mapping. This may be most useful to -associate additional information with a reference, but could also be used to +associate additional information with a weak reference, but could also be used to insert additional processing on calls to retrieve the referent. This example shows how a subclass of :class:`ref` can be used to store @@ -395,7 +395,7 @@ the referent is accessed:: def __call__(self): """Return a pair containing the referent and the number of - times the reference has been called. + times the weak reference has been called. """ ob = super().__call__() if ob is not None: @@ -533,7 +533,7 @@ However, handling of :meth:`__del__` methods is notoriously implementation specific, since it depends on internal details of the interpreter's garbage collector implementation. -A more robust alternative can be to define a finalizer which only references +A more robust alternative can be used to define a finalizer which only references the specific functions and objects that it needs, rather than having access to the full state of the object:: From fd8b0a983b75e1c2ab5b25649fdddc7008e816ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Fri, 13 May 2022 13:20:10 +0200 Subject: [PATCH 11/13] Update weakref.rst --- Doc/library/weakref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index a5f430a870cb68..86f34033302c41 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -533,7 +533,7 @@ However, handling of :meth:`__del__` methods is notoriously implementation specific, since it depends on internal details of the interpreter's garbage collector implementation. -A more robust alternative can be used to define a finalizer which only references +A more robust alternative can be to define a finalizer which only references the specific functions and objects that it needs, rather than having access to the full state of the object:: From f19e8a1b03c685515f94ac30dc1c7baee9db00ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 28 Nov 2022 17:07:02 +0100 Subject: [PATCH 12/13] Revert "Update weakref.rst" This reverts commit c2d8a6bc239d11744213ca74d610a181cbff8dc0. --- Doc/library/weakref.rst | 60 ++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 86f34033302c41..75ae9fe40a2156 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -95,13 +95,13 @@ See :ref:`__slots__ documentation ` for details. .. class:: ref(object[, callback]) - Return a weak reference to *object*. The referent can be retrieved by - calling the weak reference if the referent is still alive; if the referent is - no longer alive, calling the weak reference will cause :const:`None` to be - returned. If *callback* is provided and not :const:`None`, and the weak - reference is still alive, the callback will be called when the referent is - about to be finalized; the weak reference will be passed as the only - argument to the callback; the referent will no longer be available. + Return a weak reference to *object*. The original object can be retrieved by + calling the reference object if the referent is still alive; if the referent is + no longer alive, calling the reference object will cause :const:`None` to be + returned. If *callback* is provided and not :const:`None`, and the returned + weakref object is still alive, the callback will be called when the object is + about to be finalized; the weak reference object will be passed as the only + parameter to the callback; the referent will no longer be available. It is allowable for many weak references to be constructed for the same object. Callbacks registered for each weak reference will be called from the most @@ -117,9 +117,9 @@ See :ref:`__slots__ documentation ` for details. the call will raise :exc:`TypeError`. Weak references support tests for equality, but not ordering. If the referents - are still alive, two weak references have the same equality relationship as their + are still alive, two references have the same equality relationship as their referents (regardless of the *callback*). If either referent has been deleted, - two weak references are equal only if the weak references are the same object. + the references are equal only if the reference objects are the same object. This is a subclassable type rather than a factory function. @@ -137,15 +137,15 @@ See :ref:`__slots__ documentation ` for details. Return a proxy to *object* which uses a weak reference. This supports use of the proxy in most contexts instead of requiring the explicit dereferencing used - with weak references. The returned object will have a type of either + with weak reference objects. The returned object will have a type of either ``ProxyType`` or ``CallableProxyType``, depending on whether *object* is - callable. Proxies are not :term:`hashable` regardless of the referent; this + callable. Proxy objects are not :term:`hashable` regardless of the referent; this avoids a number of problems related to their fundamentally mutable nature, and prevents their use as dictionary keys. *callback* is the same as the parameter of the same name to the :func:`ref` function. .. versionchanged:: 3.8 - Extended the operator support on proxies to include the matrix + Extended the operator support on proxy objects to include the matrix multiplication operators ``@`` and ``@=``. @@ -156,7 +156,7 @@ See :ref:`__slots__ documentation ` for details. .. function:: getweakrefs(object) - Return a list of all weak references and proxies which refer to *object*. + Return a list of all weak reference and proxy objects which refer to *object*. .. class:: WeakKeyDictionary([dict]) @@ -239,9 +239,9 @@ objects. .. class:: finalize(obj, func, /, *args, **kwargs) - Return a callable finalizer which will be called when *obj* - is garbage collected. Unlike an ordinary weak reference, a finalizer - will always survive until the referent is collected, greatly + Return a callable finalizer object which will be called when *obj* + is garbage collected. Unlike an ordinary weak reference, a finalizer + will always survive until the reference object is collected, greatly simplifying lifecycle management. A finalizer is considered *alive* until it is called (either explicitly @@ -303,17 +303,17 @@ objects. .. data:: ReferenceType - The type object for weak references. + The type object for weak references objects. .. data:: ProxyType - The type object for proxies to objects which are not callable. + The type object for proxies of objects which are not callable. .. data:: CallableProxyType - The type object for proxies to callable objects. + The type object for proxies of callable objects. .. data:: ProxyTypes @@ -335,8 +335,8 @@ objects. Weak Reference Objects ---------------------- -Weak references have no methods and no attributes besides -:attr:`ref.__callback__`. A weak reference allows the referent to be +Weak reference objects have no methods and no attributes besides +:attr:`ref.__callback__`. A weak reference object allows the referent to be obtained, if it still exists, by calling it: >>> import weakref @@ -356,11 +356,11 @@ If the referent no longer exists, calling the weak reference returns >>> print(r()) None -Testing that a weak reference is still live should be done using the +Testing that a weak reference object is still live should be done using the expression ``ref() is not None``. Normally, application code that needs to use -a weak reference should follow this pattern:: +a reference object should follow this pattern:: - # r is a weak reference + # r is a weak reference object o = r() if o is None: # referent has been garbage collected @@ -437,8 +437,8 @@ Finalizer Objects ----------------- The main benefit of using :class:`finalize` is that it makes it simple -to register a callback without needing to preserve the returned finalizer. -For instance +to register a callback without needing to preserve the returned finalizer +object. For instance >>> import weakref >>> class Object: @@ -494,7 +494,7 @@ is still alive. For instance obj dead or exiting -Comparing Finalizers with :meth:`__del__` Methods +Comparing finalizers with :meth:`__del__` methods ------------------------------------------------- Suppose we want to create a class whose instances represent temporary @@ -553,8 +553,8 @@ Defined like this, our finalizer only receives a reference to the details it needs to clean up the directory appropriately. If the object never gets garbage collected the finalizer will still be called at exit. -The other advantage of finalizers is that they can be used -for classes where the definition is controlled by a +The other advantage of weakref based finalizers is that they can be used to +register finalizers for classes where the definition is controlled by a third party, such as running code when a module is unloaded:: import weakref, sys @@ -565,7 +565,7 @@ third party, such as running code when a module is unloaded:: .. note:: - If you create a finalizer in a daemonic thread just as the program + If you create a finalizer object in a daemonic thread just as the program exits then there is the possibility that the finalizer does not get called at exit. However, in a daemonic thread :func:`atexit.register`, ``try: ... finally: ...`` and ``with: ...`` From b60d38b9f31b8e16b2722c3baf15c8c9e9481ecf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Ogam?= Date: Mon, 28 Nov 2022 17:08:13 +0100 Subject: [PATCH 13/13] Revert "Normalise and disambiguate" This reverts commit 7a78eebf3767d5c3abb638e0bc58623ed664e7cb. --- Doc/library/weakref.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 75ae9fe40a2156..58654f9c04349b 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -171,10 +171,10 @@ See :ref:`__slots__ documentation ` for details. Added support for ``|`` and ``|=`` operators, specified in :pep:`584`. :class:`WeakKeyDictionary` objects have an additional method that -exposes the internal weak references directly. The weak references are not guaranteed to -be "live" at the time they are used, so the result of calling them +exposes the internal references directly. The references are not guaranteed to +be "live" at the time they are used, so the result of calling the references needs to be checked before being used. This can be used to avoid creating -strong references that will cause the garbage collector to keep the keys around longer +references that will cause the garbage collector to keep the keys around longer than needed. @@ -294,7 +294,7 @@ objects. .. note:: It is important to ensure that *func*, *args* and *kwargs* do - not own any strong references to *obj*, either directly or indirectly, + not own any references to *obj*, either directly or indirectly, since otherwise *obj* will never be garbage collected. In particular, *func* should not be a bound method of *obj*. @@ -349,7 +349,7 @@ obtained, if it still exists, by calling it: >>> o is o2 True -If the referent no longer exists, calling the weak reference returns +If the referent no longer exists, calling the reference object returns :const:`None`: >>> del o, o2 @@ -377,7 +377,7 @@ applications as well as single-threaded applications. Specialized versions of :class:`ref` objects can be created through subclassing. This is used in the implementation of the :class:`WeakValueDictionary` to reduce the memory overhead for each entry in the mapping. This may be most useful to -associate additional information with a weak reference, but could also be used to +associate additional information with a reference, but could also be used to insert additional processing on calls to retrieve the referent. This example shows how a subclass of :class:`ref` can be used to store @@ -395,7 +395,7 @@ the referent is accessed:: def __call__(self): """Return a pair containing the referent and the number of - times the weak reference has been called. + times the reference has been called. """ ob = super().__call__() if ob is not None: