bpo-32377: improve del docs and fix mention about resurrection (#… · python/cpython@4b96593 (original) (raw)

`@@ -1173,61 +1173,69 @@ Basic customization

1173

1174

` .. index::

1175

` single: destructor

1176

single: finalizer

1176

1177

` statement: del

1177

1178

1179

` Called when the instance is about to be destroyed. This is also called a

1179

`` -

destructor. If a base class has a :meth:__del__ method, the derived class's

1180

`` -

:meth:__del__ method, if any, must explicitly call it to ensure proper

1181

deletion of the base class part of the instance. Note that it is possible

1182

`` -

(though not recommended!) for the :meth:__del__ method to postpone destruction

1183

of the instance by creating a new reference to it. It may then be called at a

1184

later time when this new reference is deleted. It is not guaranteed that

1185

`` -

:meth:__del__ methods are called for objects that still exist when the

1186

interpreter exits.

1180

finalizer or (improperly) a destructor. If a base class has a

1181

`` +

:meth:__del__ method, the derived class's :meth:__del__ method,

1182

if any, must explicitly call it to ensure proper deletion of the base

1183

class part of the instance.

1184

+

1185

`` +

It is possible (though not recommended!) for the :meth:__del__ method

1186

to postpone destruction of the instance by creating a new reference to

1187

it. This is called object resurrection. It is implementation-dependent

1188

`` +

whether :meth:__del__ is called a second time when a resurrected object

1189

`` +

is about to be destroyed; the current :term:CPython implementation

1190

only calls it once.

1191

+

1192

`` +

It is not guaranteed that :meth:__del__ methods are called for objects

1193

that still exist when the interpreter exits.

1187

1194

1188

1195

` .. note::

1189

1196

1190

1197

``` del x doesn't directly call x.__del__() --- the former decrements


`1191`

`1198`

```  the reference count for ``x`` by one, and the latter is only called when

1192


 ``x``'s reference count reaches zero. Some common situations that may

1193

prevent the reference count of an object from going to zero include:

1194

circular references between objects (e.g., a doubly-linked list or a tree

1195

data structure with parent and child pointers); a reference to the object

1196

on the stack frame of a function that caught an exception (the traceback

1197


 stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a

1198

reference to the object on the stack frame that raised an unhandled

1199

exception in interactive mode (the traceback stored in

1200


 ``sys.last_traceback`` keeps the stack frame alive). The first situation

1201

can only be remedied by explicitly breaking the cycles; the second can be

1202

resolved by freeing the reference to the traceback object when it is no

1203


 longer useful, and the third can be resolved by storing ``None`` in

1204


 ``sys.last_traceback``.

1205

Circular references which are garbage are detected and cleaned up when

1206

the cyclic garbage collector is enabled (it's on by default). Refer to the

1207

`` -

documentation for the :mod:gc module for more information about this

1208

topic.

1199


 ``x``'s reference count reaches zero.

1200

+

1201

.. impl-detail::

1202

It is possible for a reference cycle to prevent the reference count

1203

of an object from going to zero. In this case, the cycle will be

1204

`` +

later detected and deleted by the :term:`cyclic garbage collector

1205

`` +

`. A common cause of reference cycles is when

1206

an exception has been caught in a local variable. The frame's

1207

locals then reference the exception, which references its own

1208

traceback, which references the locals of all frames caught in the

1209

traceback.

1210

+

1211

.. seealso::

1212

`` +

Documentation for the :mod:gc module.

1209

1213

1210

1214

` .. warning::

1211

1215

1212

1216

`` Due to the precarious circumstances under which :meth:__del__ methods are

1213

1217

` invoked, exceptions that occur during their execution are ignored, and a warning

1214


 is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in

1215

response to a module being deleted (e.g., when execution of the program is

1216

`` -

done), other globals referenced by the :meth:__del__ method may already have

1217

been deleted or in the process of being torn down (e.g. the import

1218

`` -

machinery shutting down). For this reason, :meth:__del__ methods

1219

should do the absolute

1220

minimum needed to maintain external invariants. Starting with version 1.5,

1221

Python guarantees that globals whose name begins with a single underscore are

1222

deleted from their module before other globals are deleted; if no other

1223

references to such globals exist, this may help in assuring that imported

1224

`` -

modules are still available at the time when the :meth:__del__ method is

1225

called.

1218


 is printed to ``sys.stderr`` instead. In particular:

1226

1219

1227

.. index::

1228

single: repr() (built-in function); repr() (object method)

1220

`` +

:meth:__del__ can be invoked when arbitrary code is being executed,

1221

`` +

including from any arbitrary thread. If :meth:__del__ needs to take

1222

a lock or invoke any other blocking resource, it may deadlock as

1223

the resource may already be taken by the code that gets interrupted

1224

`` +

to execute :meth:__del__.

1225

+

1226

`` +

:meth:__del__ can be executed during interpreter shutdown. As a

1227

consequence, the global variables it needs to access (including other

1228


 modules) may already have been deleted or set to ``None``. Python

1229

guarantees that globals whose name begins with a single underscore

1230

are deleted from their module before other globals are deleted; if

1231

no other references to such globals exist, this may help in assuring

1232

that imported modules are still available at the time when the

1233

`` +

:meth:__del__ method is called.

1229

1234

1230

1235

1236

.. index::

1237

single: repr() (built-in function); repr() (object method)

1238

+

1231

1239

`.. method:: object.repr(self)

1232

1240

1233

1241

`` Called by the :func:repr built-in function to compute the "official" string