Update docs for 3.7.0a4

1 files changed, 272 insertions, 156 deletions

diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py
index bb9c1ef..dc9591a 100644
--- a/Lib/pydoc_data/topics.py
+++ b/Lib/pydoc_data/topics.py
@@ -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'