mirror of
https://github.com/python/cpython.git
synced 2025-08-22 17:55:18 +00:00
Update docs for 3.7.0a4
This commit is contained in:
Ned Deily
parent
ca0c5f2656
commit
3b43bfaae6
86 changed files with 1119 additions and 351 deletions
|
|
@ -1,5 +1,5 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
# Autogenerated by Sphinx on Tue Dec 5 03:14:53 2017
|
||||
# Autogenerated by Sphinx on Mon Jan 8 21:23:03 2018
|
||||
topics = {'assert': 'The "assert" statement\n'
|
||||
'**********************\n'
|
||||
'\n'
|
||||
|
|
@ -571,6 +571,65 @@ topics = {'assert': 'The "assert" statement\n'
|
|||
' sorts it.\n'
|
||||
'\n'
|
||||
'\n'
|
||||
'Customizing module attribute access\n'
|
||||
'===================================\n'
|
||||
'\n'
|
||||
'Special names "__getattr__" and "__dir__" can be also '
|
||||
'used to\n'
|
||||
'customize access to module attributes. The "__getattr__" '
|
||||
'function at\n'
|
||||
'the module level should accept one argument which is the '
|
||||
'name of an\n'
|
||||
'attribute and return the computed value or raise an '
|
||||
'"AttributeError".\n'
|
||||
'If an attribute is not found on a module object through '
|
||||
'the normal\n'
|
||||
'lookup, i.e. "object.__getattribute__()", then '
|
||||
'"__getattr__" is\n'
|
||||
'searched in the module "__dict__" before raising an '
|
||||
'"AttributeError".\n'
|
||||
'If found, it is called with the attribute name and the '
|
||||
'result is\n'
|
||||
'returned.\n'
|
||||
'\n'
|
||||
'The "__dir__" function should accept no arguments, and '
|
||||
'return a list\n'
|
||||
'of strings that represents the names accessible on '
|
||||
'module. If present,\n'
|
||||
'this function overrides the standard "dir()" search on a '
|
||||
'module.\n'
|
||||
'\n'
|
||||
'For a more fine grained customization of the module '
|
||||
'behavior (setting\n'
|
||||
'attributes, properties, etc.), one can set the '
|
||||
'"__class__" attribute\n'
|
||||
'of a module object to a subclass of "types.ModuleType". '
|
||||
'For example:\n'
|
||||
'\n'
|
||||
' import sys\n'
|
||||
' from types import ModuleType\n'
|
||||
'\n'
|
||||
' class VerboseModule(ModuleType):\n'
|
||||
' def __repr__(self):\n'
|
||||
" return f'Verbose {self.__name__}'\n"
|
||||
'\n'
|
||||
' def __setattr__(self, attr, value):\n'
|
||||
" print(f'Setting {attr}...')\n"
|
||||
' setattr(self, attr, value)\n'
|
||||
'\n'
|
||||
' sys.modules[__name__].__class__ = VerboseModule\n'
|
||||
'\n'
|
||||
'Note: Defining module "__getattr__" and setting module '
|
||||
'"__class__"\n'
|
||||
' only affect lookups made using the attribute access '
|
||||
'syntax --\n'
|
||||
' directly accessing the module globals (whether by code '
|
||||
'within the\n'
|
||||
" module, or via a reference to the module's globals "
|
||||
'dictionary) is\n'
|
||||
' unaffected.\n'
|
||||
'\n'
|
||||
'\n'
|
||||
'Implementing Descriptors\n'
|
||||
'========================\n'
|
||||
'\n'
|
||||
|
|
@ -2905,63 +2964,52 @@ topics = {'assert': 'The "assert" statement\n'
|
|||
'\n'
|
||||
' Called when the instance is about to be destroyed. This '
|
||||
'is also\n'
|
||||
' called a destructor. If a base class has a "__del__()" '
|
||||
'method, the\n'
|
||||
' derived class\'s "__del__()" method, if any, must '
|
||||
'explicitly call it\n'
|
||||
' to ensure proper deletion of the base class part of the '
|
||||
'instance.\n'
|
||||
' Note that it is possible (though not recommended!) for '
|
||||
' called a finalizer or (improperly) a destructor. If a '
|
||||
'base class\n'
|
||||
' has a "__del__()" method, the derived class\'s '
|
||||
'"__del__()" method,\n'
|
||||
' if any, must explicitly call it to ensure proper '
|
||||
'deletion of the\n'
|
||||
' base class part of the instance.\n'
|
||||
'\n'
|
||||
' It is possible (though not recommended!) for the '
|
||||
'"__del__()" method\n'
|
||||
' to postpone destruction of the instance by creating a '
|
||||
'new reference\n'
|
||||
' to it. This is called object *resurrection*. It is\n'
|
||||
' implementation-dependent whether "__del__()" is called a '
|
||||
'second\n'
|
||||
' time when a resurrected object is about to be destroyed; '
|
||||
'the\n'
|
||||
' "__del__()" method to postpone destruction of the '
|
||||
'instance by\n'
|
||||
' creating a new reference to it. It may then be called '
|
||||
'at a later\n'
|
||||
' time when this new reference is deleted. It is not '
|
||||
'guaranteed that\n'
|
||||
' "__del__()" methods are called for objects that still '
|
||||
'exist when\n'
|
||||
' the interpreter exits.\n'
|
||||
' current *CPython* implementation only calls it once.\n'
|
||||
'\n'
|
||||
' It is not guaranteed that "__del__()" methods are called '
|
||||
'for\n'
|
||||
' objects that still exist when the interpreter exits.\n'
|
||||
'\n'
|
||||
' Note: "del x" doesn\'t directly call "x.__del__()" --- '
|
||||
'the former\n'
|
||||
' decrements the reference count for "x" by one, and the '
|
||||
'latter is\n'
|
||||
' only called when "x"\'s reference count reaches zero. '
|
||||
'Some common\n'
|
||||
' situations that may prevent the reference count of an '
|
||||
'object from\n'
|
||||
' going to zero include: circular references between '
|
||||
'objects (e.g.,\n'
|
||||
' a doubly-linked list or a tree data structure with '
|
||||
'parent and\n'
|
||||
' child pointers); a reference to the object on the '
|
||||
'stack frame of\n'
|
||||
' a function that caught an exception (the traceback '
|
||||
'stored in\n'
|
||||
' "sys.exc_info()[2]" keeps the stack frame alive); or a '
|
||||
' only called when "x"\'s reference count reaches zero.\n'
|
||||
'\n'
|
||||
' **CPython implementation detail:** It is possible for a '
|
||||
'reference\n'
|
||||
' to the object on the stack frame that raised an '
|
||||
'unhandled\n'
|
||||
' exception in interactive mode (the traceback stored '
|
||||
'in\n'
|
||||
' "sys.last_traceback" keeps the stack frame alive). '
|
||||
'The first\n'
|
||||
' situation can only be remedied by explicitly breaking '
|
||||
'the cycles;\n'
|
||||
' the second can be resolved by freeing the reference to '
|
||||
'the\n'
|
||||
' traceback object when it is no longer useful, and the '
|
||||
'third can\n'
|
||||
' be resolved by storing "None" in "sys.last_traceback". '
|
||||
'Circular\n'
|
||||
' references which are garbage are detected and cleaned '
|
||||
'up when the\n'
|
||||
" cyclic garbage collector is enabled (it's on by "
|
||||
'default). Refer\n'
|
||||
' to the documentation for the "gc" module for more '
|
||||
'information\n'
|
||||
' about this topic.\n'
|
||||
' cycle to prevent the reference count of an object from '
|
||||
'going to\n'
|
||||
' zero. In this case, the cycle will be later detected '
|
||||
'and deleted\n'
|
||||
' by the *cyclic garbage collector*. A common cause of '
|
||||
'reference\n'
|
||||
' cycles is when an exception has been caught in a local '
|
||||
'variable.\n'
|
||||
" The frame's locals then reference the exception, which "
|
||||
'references\n'
|
||||
' its own traceback, which references the locals of all '
|
||||
'frames caught\n'
|
||||
' in the traceback.\n'
|
||||
'\n'
|
||||
' See also: Documentation for the "gc" module.\n'
|
||||
'\n'
|
||||
' Warning: Due to the precarious circumstances under '
|
||||
'which\n'
|
||||
|
|
@ -2969,29 +3017,35 @@ topics = {'assert': 'The "assert" statement\n'
|
|||
'during\n'
|
||||
' their execution are ignored, and a warning is printed '
|
||||
'to\n'
|
||||
' "sys.stderr" instead. Also, when "__del__()" is '
|
||||
'invoked in\n'
|
||||
' response to a module being deleted (e.g., when '
|
||||
'execution of the\n'
|
||||
' program is done), other globals referenced by the '
|
||||
' "sys.stderr" instead. In particular:\n'
|
||||
'\n'
|
||||
' * "__del__()" can be invoked when arbitrary code is '
|
||||
'being\n'
|
||||
' executed, including from any arbitrary thread. If '
|
||||
'"__del__()"\n'
|
||||
' method may already have been deleted or in the process '
|
||||
'of being\n'
|
||||
' torn down (e.g. the import machinery shutting down). '
|
||||
'For this\n'
|
||||
' reason, "__del__()" methods should do the absolute '
|
||||
'minimum needed\n'
|
||||
' to maintain external invariants. Starting with '
|
||||
'version 1.5,\n'
|
||||
' Python guarantees that globals whose name begins with '
|
||||
'a single\n'
|
||||
' underscore are deleted from their module before other '
|
||||
'globals are\n'
|
||||
' deleted; if no other references to such globals exist, '
|
||||
'this may\n'
|
||||
' help in assuring that imported modules are still '
|
||||
'available at the\n'
|
||||
' time when the "__del__()" method is called.\n'
|
||||
' needs to take a lock or invoke any other blocking '
|
||||
'resource, it\n'
|
||||
' may deadlock as the resource may already be taken by '
|
||||
'the code\n'
|
||||
' that gets interrupted to execute "__del__()".\n'
|
||||
'\n'
|
||||
' * "__del__()" can be executed during interpreter '
|
||||
'shutdown. As\n'
|
||||
' a consequence, the global variables it needs to '
|
||||
'access\n'
|
||||
' (including other modules) may already have been '
|
||||
'deleted or set\n'
|
||||
' to "None". Python guarantees that globals whose name '
|
||||
'begins\n'
|
||||
' with a single underscore are deleted from their '
|
||||
'module before\n'
|
||||
' other globals are deleted; if no other references to '
|
||||
'such\n'
|
||||
' globals exist, this may help in assuring that '
|
||||
'imported modules\n'
|
||||
' are still available at the time when the "__del__()" '
|
||||
'method is\n'
|
||||
' called.\n'
|
||||
'\n'
|
||||
'object.__repr__(self)\n'
|
||||
'\n'
|
||||
|
|
@ -3346,6 +3400,13 @@ topics = {'assert': 'The "assert" statement\n'
|
|||
'executes\n'
|
||||
'commands as if given in a ".pdbrc" file, see Debugger Commands.\n'
|
||||
'\n'
|
||||
'New in version 3.7: "pdb.py" now accepts a "-m" option that '
|
||||
'execute\n'
|
||||
'modules similar to the way "python3 -m" does. As with a script, '
|
||||
'the\n'
|
||||
'debugger will pause execution just before the first line of the\n'
|
||||
'module.\n'
|
||||
'\n'
|
||||
'The typical usage to break into the debugger from a running '
|
||||
'program is\n'
|
||||
'to insert\n'
|
||||
|
|
@ -7563,91 +7624,87 @@ topics = {'assert': 'The "assert" statement\n'
|
|||
'\n'
|
||||
' Called when the instance is about to be destroyed. This '
|
||||
'is also\n'
|
||||
' called a destructor. If a base class has a "__del__()" '
|
||||
'method, the\n'
|
||||
' derived class\'s "__del__()" method, if any, must '
|
||||
'explicitly call it\n'
|
||||
' to ensure proper deletion of the base class part of the '
|
||||
'instance.\n'
|
||||
' Note that it is possible (though not recommended!) for '
|
||||
' called a finalizer or (improperly) a destructor. If a '
|
||||
'base class\n'
|
||||
' has a "__del__()" method, the derived class\'s '
|
||||
'"__del__()" method,\n'
|
||||
' if any, must explicitly call it to ensure proper deletion '
|
||||
'of the\n'
|
||||
' base class part of the instance.\n'
|
||||
'\n'
|
||||
' It is possible (though not recommended!) for the '
|
||||
'"__del__()" method\n'
|
||||
' to postpone destruction of the instance by creating a new '
|
||||
'reference\n'
|
||||
' to it. This is called object *resurrection*. It is\n'
|
||||
' implementation-dependent whether "__del__()" is called a '
|
||||
'second\n'
|
||||
' time when a resurrected object is about to be destroyed; '
|
||||
'the\n'
|
||||
' "__del__()" method to postpone destruction of the '
|
||||
'instance by\n'
|
||||
' creating a new reference to it. It may then be called at '
|
||||
'a later\n'
|
||||
' time when this new reference is deleted. It is not '
|
||||
'guaranteed that\n'
|
||||
' "__del__()" methods are called for objects that still '
|
||||
'exist when\n'
|
||||
' the interpreter exits.\n'
|
||||
' current *CPython* implementation only calls it once.\n'
|
||||
'\n'
|
||||
' It is not guaranteed that "__del__()" methods are called '
|
||||
'for\n'
|
||||
' objects that still exist when the interpreter exits.\n'
|
||||
'\n'
|
||||
' Note: "del x" doesn\'t directly call "x.__del__()" --- '
|
||||
'the former\n'
|
||||
' decrements the reference count for "x" by one, and the '
|
||||
'latter is\n'
|
||||
' only called when "x"\'s reference count reaches zero. '
|
||||
'Some common\n'
|
||||
' situations that may prevent the reference count of an '
|
||||
'object from\n'
|
||||
' going to zero include: circular references between '
|
||||
'objects (e.g.,\n'
|
||||
' a doubly-linked list or a tree data structure with '
|
||||
'parent and\n'
|
||||
' child pointers); a reference to the object on the stack '
|
||||
'frame of\n'
|
||||
' a function that caught an exception (the traceback '
|
||||
'stored in\n'
|
||||
' "sys.exc_info()[2]" keeps the stack frame alive); or a '
|
||||
' only called when "x"\'s reference count reaches zero.\n'
|
||||
'\n'
|
||||
' **CPython implementation detail:** It is possible for a '
|
||||
'reference\n'
|
||||
' to the object on the stack frame that raised an '
|
||||
'unhandled\n'
|
||||
' exception in interactive mode (the traceback stored in\n'
|
||||
' "sys.last_traceback" keeps the stack frame alive). The '
|
||||
'first\n'
|
||||
' situation can only be remedied by explicitly breaking '
|
||||
'the cycles;\n'
|
||||
' the second can be resolved by freeing the reference to '
|
||||
'the\n'
|
||||
' traceback object when it is no longer useful, and the '
|
||||
'third can\n'
|
||||
' be resolved by storing "None" in "sys.last_traceback". '
|
||||
'Circular\n'
|
||||
' references which are garbage are detected and cleaned '
|
||||
'up when the\n'
|
||||
" cyclic garbage collector is enabled (it's on by "
|
||||
'default). Refer\n'
|
||||
' to the documentation for the "gc" module for more '
|
||||
'information\n'
|
||||
' about this topic.\n'
|
||||
' cycle to prevent the reference count of an object from '
|
||||
'going to\n'
|
||||
' zero. In this case, the cycle will be later detected and '
|
||||
'deleted\n'
|
||||
' by the *cyclic garbage collector*. A common cause of '
|
||||
'reference\n'
|
||||
' cycles is when an exception has been caught in a local '
|
||||
'variable.\n'
|
||||
" The frame's locals then reference the exception, which "
|
||||
'references\n'
|
||||
' its own traceback, which references the locals of all '
|
||||
'frames caught\n'
|
||||
' in the traceback.\n'
|
||||
'\n'
|
||||
' See also: Documentation for the "gc" module.\n'
|
||||
'\n'
|
||||
' Warning: Due to the precarious circumstances under which\n'
|
||||
' "__del__()" methods are invoked, exceptions that occur '
|
||||
'during\n'
|
||||
' their execution are ignored, and a warning is printed '
|
||||
'to\n'
|
||||
' "sys.stderr" instead. Also, when "__del__()" is invoked '
|
||||
'in\n'
|
||||
' response to a module being deleted (e.g., when '
|
||||
'execution of the\n'
|
||||
' program is done), other globals referenced by the '
|
||||
' "sys.stderr" instead. In particular:\n'
|
||||
'\n'
|
||||
' * "__del__()" can be invoked when arbitrary code is '
|
||||
'being\n'
|
||||
' executed, including from any arbitrary thread. If '
|
||||
'"__del__()"\n'
|
||||
' method may already have been deleted or in the process '
|
||||
'of being\n'
|
||||
' torn down (e.g. the import machinery shutting down). '
|
||||
'For this\n'
|
||||
' reason, "__del__()" methods should do the absolute '
|
||||
'minimum needed\n'
|
||||
' to maintain external invariants. Starting with version '
|
||||
'1.5,\n'
|
||||
' Python guarantees that globals whose name begins with a '
|
||||
'single\n'
|
||||
' underscore are deleted from their module before other '
|
||||
'globals are\n'
|
||||
' deleted; if no other references to such globals exist, '
|
||||
'this may\n'
|
||||
' help in assuring that imported modules are still '
|
||||
'available at the\n'
|
||||
' time when the "__del__()" method is called.\n'
|
||||
' needs to take a lock or invoke any other blocking '
|
||||
'resource, it\n'
|
||||
' may deadlock as the resource may already be taken by '
|
||||
'the code\n'
|
||||
' that gets interrupted to execute "__del__()".\n'
|
||||
'\n'
|
||||
' * "__del__()" can be executed during interpreter '
|
||||
'shutdown. As\n'
|
||||
' a consequence, the global variables it needs to '
|
||||
'access\n'
|
||||
' (including other modules) may already have been '
|
||||
'deleted or set\n'
|
||||
' to "None". Python guarantees that globals whose name '
|
||||
'begins\n'
|
||||
' with a single underscore are deleted from their '
|
||||
'module before\n'
|
||||
' other globals are deleted; if no other references to '
|
||||
'such\n'
|
||||
' globals exist, this may help in assuring that '
|
||||
'imported modules\n'
|
||||
' are still available at the time when the "__del__()" '
|
||||
'method is\n'
|
||||
' called.\n'
|
||||
'\n'
|
||||
'object.__repr__(self)\n'
|
||||
'\n'
|
||||
|
|
@ -8031,6 +8088,65 @@ topics = {'assert': 'The "assert" statement\n'
|
|||
' sorts it.\n'
|
||||
'\n'
|
||||
'\n'
|
||||
'Customizing module attribute access\n'
|
||||
'-----------------------------------\n'
|
||||
'\n'
|
||||
'Special names "__getattr__" and "__dir__" can be also used '
|
||||
'to\n'
|
||||
'customize access to module attributes. The "__getattr__" '
|
||||
'function at\n'
|
||||
'the module level should accept one argument which is the '
|
||||
'name of an\n'
|
||||
'attribute and return the computed value or raise an '
|
||||
'"AttributeError".\n'
|
||||
'If an attribute is not found on a module object through the '
|
||||
'normal\n'
|
||||
'lookup, i.e. "object.__getattribute__()", then "__getattr__" '
|
||||
'is\n'
|
||||
'searched in the module "__dict__" before raising an '
|
||||
'"AttributeError".\n'
|
||||
'If found, it is called with the attribute name and the '
|
||||
'result is\n'
|
||||
'returned.\n'
|
||||
'\n'
|
||||
'The "__dir__" function should accept no arguments, and '
|
||||
'return a list\n'
|
||||
'of strings that represents the names accessible on module. '
|
||||
'If present,\n'
|
||||
'this function overrides the standard "dir()" search on a '
|
||||
'module.\n'
|
||||
'\n'
|
||||
'For a more fine grained customization of the module behavior '
|
||||
'(setting\n'
|
||||
'attributes, properties, etc.), one can set the "__class__" '
|
||||
'attribute\n'
|
||||
'of a module object to a subclass of "types.ModuleType". For '
|
||||
'example:\n'
|
||||
'\n'
|
||||
' import sys\n'
|
||||
' from types import ModuleType\n'
|
||||
'\n'
|
||||
' class VerboseModule(ModuleType):\n'
|
||||
' def __repr__(self):\n'
|
||||
" return f'Verbose {self.__name__}'\n"
|
||||
'\n'
|
||||
' def __setattr__(self, attr, value):\n'
|
||||
" print(f'Setting {attr}...')\n"
|
||||
' setattr(self, attr, value)\n'
|
||||
'\n'
|
||||
' sys.modules[__name__].__class__ = VerboseModule\n'
|
||||
'\n'
|
||||
'Note: Defining module "__getattr__" and setting module '
|
||||
'"__class__"\n'
|
||||
' only affect lookups made using the attribute access syntax '
|
||||
'--\n'
|
||||
' directly accessing the module globals (whether by code '
|
||||
'within the\n'
|
||||
" module, or via a reference to the module's globals "
|
||||
'dictionary) is\n'
|
||||
' unaffected.\n'
|
||||
'\n'
|
||||
'\n'
|
||||
'Implementing Descriptors\n'
|
||||
'------------------------\n'
|
||||
'\n'
|
||||
|
|
@ -12211,18 +12327,18 @@ topics = {'assert': 'The "assert" statement\n'
|
|||
' sequence concatenation or repetition.\n'
|
||||
'\n'
|
||||
'8. "index" raises "ValueError" when *x* is not found in *s*. '
|
||||
'When\n'
|
||||
' supported, the additional arguments to the index method '
|
||||
'allow\n'
|
||||
' efficient searching of subsections of the sequence. Passing '
|
||||
'the\n'
|
||||
' extra arguments is roughly equivalent to using '
|
||||
'"s[i:j].index(x)",\n'
|
||||
' only without copying any data and with the returned index '
|
||||
'being\n'
|
||||
' relative to the start of the sequence rather than the start '
|
||||
'of the\n'
|
||||
' slice.\n'
|
||||
'Not\n'
|
||||
' all implementations support passing the additional arguments '
|
||||
'*i*\n'
|
||||
' and *j*. These arguments allow efficient searching of '
|
||||
'subsections\n'
|
||||
' of the sequence. Passing the extra arguments is roughly '
|
||||
'equivalent\n'
|
||||
' to using "s[i:j].index(x)", only without copying any data and '
|
||||
'with\n'
|
||||
' the returned index being relative to the start of the '
|
||||
'sequence\n'
|
||||
' rather than the start of the slice.\n'
|
||||
'\n'
|
||||
'\n'
|
||||
'Immutable Sequence Types\n'
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue