Update pydoc topics for 3.6.0b1

1 files changed, 226 insertions, 87 deletions

diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py
index 590f6135cfb..3579484fd0e 100644
--- a/Lib/pydoc_data/topics.py
+++ b/Lib/pydoc_data/topics.py
@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Autogenerated by Sphinx on Mon Aug 15 16:11:20 2016
+# Autogenerated by Sphinx on Mon Sep 12 10:47:11 2016
 topics = {'assert': '\n'
            'The "assert" statement\n'
            '**********************\n'
@@ -353,7 +353,58 @@ topics = {'assert': '\n'
                'For targets which are attribute references, the same caveat '
                'about\n'
                'class and instance attributes applies as for regular '
-               'assignments.\n',
+               'assignments.\n'
+               '\n'
+               '\n'
+               'Annotated assignment statements\n'
+               '===============================\n'
+               '\n'
+               'Annotation assignment is the combination, in a single '
+               'statement, of a\n'
+               'variable or attribute annotation and an optional assignment '
+               'statement:\n'
+               '\n'
+               '   annotated_assignment_stmt ::= augtarget ":" expression ["=" '
+               'expression]\n'
+               '\n'
+               'The difference from normal Assignment statements is that only '
+               'single\n'
+               'target and only single right hand side value is allowed.\n'
+               '\n'
+               'For simple names as assignment targets, if in class or module '
+               'scope,\n'
+               'the annotations are evaluated and stored in a special class or '
+               'module\n'
+               'attribute "__annotations__" that is a dictionary mapping from '
+               'variable\n'
+               'names (mangled if private) to evaluated annotations. This '
+               'attribute is\n'
+               'writable and is automatically created at the start of class or '
+               'module\n'
+               'body execution, if annotations are found statically.\n'
+               '\n'
+               'For expressions as assignment targets, the annotations are '
+               'evaluated\n'
+               'if in class or module scope, but not stored.\n'
+               '\n'
+               'If a name is annotated in a function scope, then this name is '
+               'local\n'
+               'for that scope. Annotations are never evaluated and stored in '
+               'function\n'
+               'scopes.\n'
+               '\n'
+               'If the right hand side is present, an annotated assignment '
+               'performs\n'
+               'the actual assignment before evaluating annotations (where\n'
+               'applicable). If the right hand side is not present for an '
+               'expression\n'
+               'target, then the interpreter evaluates the target except for '
+               'the last\n'
+               '"__setitem__()" or "__setattr__()" call.\n'
+               '\n'
+               'See also: **PEP 526** - Variable and attribute annotation '
+               'syntax\n'
+               '  **PEP 484** - Type hints\n',
  'atom-identifiers': '\n'
                      'Identifiers (Names)\n'
                      '*******************\n'
@@ -1375,6 +1426,13 @@ topics = {'assert': '\n'
           'The class name is bound to this class object in the original local\n'
           'namespace.\n'
           '\n'
+          'The order in which attributes are defined in the class body is\n'
+          'preserved in the new class\'s "__dict__".  Note that this is '
+          'reliable\n'
+          'only right after the class is created and only for classes that '
+          'were\n'
+          'defined using the definition syntax.\n'
+          '\n'
           'Class creation can be customized heavily using metaclasses.\n'
           '\n'
           'Classes can also be decorated: just like when decorating '
@@ -1770,9 +1828,11 @@ topics = {'assert': '\n'
                 '\n'
                 'The operators "is" and "is not" test for object identity: "x '
                 'is y" is\n'
-                'true if and only if *x* and *y* are the same object.  "x is '
-                'not y"\n'
-                'yields the inverse truth value. [4]\n',
+                'true if and only if *x* and *y* are the same object.  Object '
+                'identity\n'
+                'is determined using the "id()" function.  "x is not y" yields '
+                'the\n'
+                'inverse truth value. [4]\n',
  'compound': '\n'
              'Compound statements\n'
              '*******************\n'
@@ -2375,14 +2435,14 @@ topics = {'assert': '\n'
              'is\n'
              'present, it is initialized to a tuple receiving any excess '
              'positional\n'
-             'parameters, defaulting to the empty tuple.  If the form\n'
-             '""**identifier"" is present, it is initialized to a new '
-             'dictionary\n'
-             'receiving any excess keyword arguments, defaulting to a new '
-             'empty\n'
-             'dictionary. Parameters after ""*"" or ""*identifier"" are '
-             'keyword-only\n'
-             'parameters and may only be passed used keyword arguments.\n'
+             'parameters, defaulting to the empty tuple. If the form\n'
+             '""**identifier"" is present, it is initialized to a new ordered\n'
+             'mapping receiving any excess keyword arguments, defaulting to a '
+             'new\n'
+             'empty mapping of the same type.  Parameters after ""*"" or\n'
+             '""*identifier"" are keyword-only parameters and may only be '
+             'passed\n'
+             'used keyword arguments.\n'
              '\n'
              'Parameters may have annotations of the form "": expression"" '
              'following\n'
@@ -2481,6 +2541,13 @@ topics = {'assert': '\n'
              'local\n'
              'namespace.\n'
              '\n'
+             'The order in which attributes are defined in the class body is\n'
+             'preserved in the new class\'s "__dict__".  Note that this is '
+             'reliable\n'
+             'only right after the class is created and only for classes that '
+             'were\n'
+             'defined using the definition syntax.\n'
+             '\n'
              'Class creation can be customized heavily using metaclasses.\n'
              '\n'
              'Classes can also be decorated: just like when decorating '
@@ -2832,7 +2899,7 @@ topics = {'assert': '\n'
                   '   Because "__new__()" and "__init__()" work together in '
                   'constructing\n'
                   '   objects ("__new__()" to create it, and "__init__()" to '
-                  'customise\n'
+                  'customize\n'
                   '   it), no non-"None" value may be returned by '
                   '"__init__()"; doing so\n'
                   '   will cause a "TypeError" to be raised at runtime.\n'
@@ -3376,7 +3443,7 @@ topics = {'assert': '\n'
              'to access further features, you have to do this yourself:\n'
              '\n'
              "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, "
-             'skip=None, nosigint=False)\n'
+             'skip=None, nosigint=False, readrc=True)\n'
              '\n'
              '   "Pdb" is the debugger class.\n'
              '\n'
@@ -3399,7 +3466,11 @@ topics = {'assert': '\n'
              'debugger\n'
              '   again by pressing "Ctrl-C".  If you want Pdb not to touch '
              'the\n'
-             '   SIGINT handler, set *nosigint* tot true.\n'
+             '   SIGINT handler, set *nosigint* to true.\n'
+             '\n'
+             '   The *readrc* argument defaults to true and controls whether '
+             'Pdb\n'
+             '   will load .pdbrc files from the filesystem.\n'
              '\n'
              '   Example call to enable tracing with *skip*:\n'
              '\n'
@@ -3411,6 +3482,8 @@ topics = {'assert': '\n'
              'SIGINT\n'
              '   handler was never set by Pdb.\n'
              '\n'
+             '   Changed in version 3.6: The *readrc* argument.\n'
+             '\n'
              '   run(statement, globals=None, locals=None)\n'
              '   runeval(expression, globals=None, locals=None)\n'
              '   runcall(function, *args, **kwds)\n'
@@ -4450,27 +4523,35 @@ topics = {'assert': '\n'
              'definitions:\n'
              '\n'
              '   floatnumber   ::= pointfloat | exponentfloat\n'
-             '   pointfloat    ::= [intpart] fraction | intpart "."\n'
-             '   exponentfloat ::= (intpart | pointfloat) exponent\n'
-             '   intpart       ::= digit+\n'
-             '   fraction      ::= "." digit+\n'
-             '   exponent      ::= ("e" | "E") ["+" | "-"] digit+\n'
+             '   pointfloat    ::= [digitpart] fraction | digitpart "."\n'
+             '   exponentfloat ::= (digitpart | pointfloat) exponent\n'
+             '   digitpart     ::= digit (["_"] digit)*\n'
+             '   fraction      ::= "." digitpart\n'
+             '   exponent      ::= ("e" | "E") ["+" | "-"] digitpart\n'
              '\n'
              'Note that the integer and exponent parts are always interpreted '
              'using\n'
              'radix 10. For example, "077e010" is legal, and denotes the same '
              'number\n'
              'as "77e10". The allowed range of floating point literals is\n'
-             'implementation-dependent. Some examples of floating point '
-             'literals:\n'
+             'implementation-dependent.  As in integer literals, underscores '
+             'are\n'
+             'supported for digit grouping.\n'
              '\n'
-             '   3.14    10.    .001    1e100    3.14e-10    0e0\n'
+             'Some examples of floating point literals:\n'
+             '\n'
+             '   3.14    10.    .001    1e100    3.14e-10    0e0    '
+             '3.14_15_93\n'
              '\n'
              'Note that numeric literals do not include a sign; a phrase like '
              '"-1"\n'
              'is actually an expression composed of the unary operator "-" and '
              'the\n'
-             'literal "1".\n',
+             'literal "1".\n'
+             '\n'
+             'Changed in version 3.6: Underscores are now allowed for '
+             'grouping\n'
+             'purposes in literals.\n',
  'for': '\n'
         'The "for" statement\n'
         '*******************\n'
@@ -4730,15 +4811,16 @@ topics = {'assert': '\n'
                   '\n'
                   'The general form of a *standard format specifier* is:\n'
                   '\n'
-                  '   format_spec ::= '
-                  '[[fill]align][sign][#][0][width][,][.precision][type]\n'
-                  '   fill        ::= <any character>\n'
-                  '   align       ::= "<" | ">" | "=" | "^"\n'
-                  '   sign        ::= "+" | "-" | " "\n'
-                  '   width       ::= integer\n'
-                  '   precision   ::= integer\n'
-                  '   type        ::= "b" | "c" | "d" | "e" | "E" | "f" | "F" '
-                  '| "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n'
+                  '   format_spec     ::= '
+                  '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n'
+                  '   fill            ::= <any character>\n'
+                  '   align           ::= "<" | ">" | "=" | "^"\n'
+                  '   sign            ::= "+" | "-" | " "\n'
+                  '   width           ::= integer\n'
+                  '   grouping_option ::= "_" | ","\n'
+                  '   precision       ::= integer\n'
+                  '   type            ::= "b" | "c" | "d" | "e" | "E" | "f" | '
+                  '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n'
                   '\n'
                   'If a valid *align* value is specified, it can be preceded '
                   'by a *fill*\n'
@@ -4864,6 +4946,20 @@ topics = {'assert': '\n'
                   'Changed in version 3.1: Added the "\',\'" option (see also '
                   '**PEP 378**).\n'
                   '\n'
+                  'The "\'_\'" option signals the use of an underscore for a '
+                  'thousands\n'
+                  'separator for floating point presentation types and for '
+                  'integer\n'
+                  'presentation type "\'d\'".  For integer presentation types '
+                  '"\'b\'", "\'o\'",\n'
+                  '"\'x\'", and "\'X\'", underscores will be inserted every 4 '
+                  'digits.  For\n'
+                  'other presentation types, specifying this option is an '
+                  'error.\n'
+                  '\n'
+                  'Changed in version 3.6: Added the "\'_\'" option (see also '
+                  '**PEP 515**).\n'
+                  '\n'
                   '*width* is a decimal integer defining the minimum field '
                   'width.  If not\n'
                   'specified, then the field width will be determined by the '
@@ -5361,14 +5457,14 @@ topics = {'assert': '\n'
              'is\n'
              'present, it is initialized to a tuple receiving any excess '
              'positional\n'
-             'parameters, defaulting to the empty tuple.  If the form\n'
-             '""**identifier"" is present, it is initialized to a new '
-             'dictionary\n'
-             'receiving any excess keyword arguments, defaulting to a new '
-             'empty\n'
-             'dictionary. Parameters after ""*"" or ""*identifier"" are '
-             'keyword-only\n'
-             'parameters and may only be passed used keyword arguments.\n'
+             'parameters, defaulting to the empty tuple. If the form\n'
+             '""**identifier"" is present, it is initialized to a new ordered\n'
+             'mapping receiving any excess keyword arguments, defaulting to a '
+             'new\n'
+             'empty mapping of the same type.  Parameters after ""*"" or\n'
+             '""*identifier"" are keyword-only parameters and may only be '
+             'passed\n'
+             'used keyword arguments.\n'
              '\n'
              'Parameters may have annotations of the form "": expression"" '
              'following\n'
@@ -5441,11 +5537,12 @@ topics = {'assert': '\n'
            'Names listed in a "global" statement must not be defined as '
            'formal\n'
            'parameters or in a "for" loop control target, "class" definition,\n'
-           'function definition, or "import" statement.\n'
+           'function definition, "import" statement, or variable annotation.\n'
            '\n'
            '**CPython implementation detail:** The current implementation does '
            'not\n'
-           'enforce the two restrictions, but programs should not abuse this\n'
+           'enforce some of these restriction, but programs should not abuse '
+           'this\n'
            'freedom, as future implementations may enforce them or silently '
            'change\n'
            'the meaning of the program.\n'
@@ -5685,7 +5782,7 @@ topics = {'assert': '\n'
               'Imaginary literals are described by the following lexical '
               'definitions:\n'
               '\n'
-              '   imagnumber ::= (floatnumber | intpart) ("j" | "J")\n'
+              '   imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n'
               '\n'
               'An imaginary literal yields a complex number with a real part '
               'of 0.0.\n'
@@ -5697,7 +5794,8 @@ topics = {'assert': '\n'
               'it,\n'
               'e.g., "(3+4j)".  Some examples of imaginary literals:\n'
               '\n'
-              '   3.14j   10.j    10j     .001j   1e100j  3.14e-10j\n',
+              '   3.14j   10.j    10j     .001j   1e100j   3.14e-10j   '
+              '3.14_15_93j\n',
  'import': '\n'
            'The "import" statement\n'
            '**********************\n'
@@ -6003,22 +6101,31 @@ topics = {'assert': '\n'
              'Integer literals are described by the following lexical '
              'definitions:\n'
              '\n'
-             '   integer        ::= decimalinteger | octinteger | hexinteger | '
-             'bininteger\n'
-             '   decimalinteger ::= nonzerodigit digit* | "0"+\n'
-             '   nonzerodigit   ::= "1"..."9"\n'
-             '   digit          ::= "0"..."9"\n'
-             '   octinteger     ::= "0" ("o" | "O") octdigit+\n'
-             '   hexinteger     ::= "0" ("x" | "X") hexdigit+\n'
-             '   bininteger     ::= "0" ("b" | "B") bindigit+\n'
-             '   octdigit       ::= "0"..."7"\n'
-             '   hexdigit       ::= digit | "a"..."f" | "A"..."F"\n'
-             '   bindigit       ::= "0" | "1"\n'
+             '   integer      ::= decinteger | bininteger | octinteger | '
+             'hexinteger\n'
+             '   decinteger   ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] '
+             '"0")*\n'
+             '   bininteger   ::= "0" ("b" | "B") (["_"] bindigit)+\n'
+             '   octinteger   ::= "0" ("o" | "O") (["_"] octdigit)+\n'
+             '   hexinteger   ::= "0" ("x" | "X") (["_"] hexdigit)+\n'
+             '   nonzerodigit ::= "1"..."9"\n'
+             '   digit        ::= "0"..."9"\n'
+             '   bindigit     ::= "0" | "1"\n'
+             '   octdigit     ::= "0"..."7"\n'
+             '   hexdigit     ::= digit | "a"..."f" | "A"..."F"\n'
              '\n'
              'There is no limit for the length of integer literals apart from '
              'what\n'
              'can be stored in available memory.\n'
              '\n'
+             'Underscores are ignored for determining the numeric value of '
+             'the\n'
+             'literal.  They can be used to group digits for enhanced '
+             'readability.\n'
+             'One underscore can occur between digits, and after base '
+             'specifiers\n'
+             'like "0x".\n'
+             '\n'
              'Note that leading zeros in a non-zero decimal number are not '
              'allowed.\n'
              'This is for disambiguation with C-style octal literals, which '
@@ -6028,7 +6135,12 @@ topics = {'assert': '\n'
              'Some examples of integer literals:\n'
              '\n'
              '   7     2147483647                        0o177    0b100110111\n'
-             '   3     79228162514264337593543950336     0o377    0xdeadbeef\n',
+             '   3     79228162514264337593543950336     0o377    0xdeadbeef\n'
+             '         100_000_000_000                   0b_1110_0101\n'
+             '\n'
+             'Changed in version 3.6: Underscores are now allowed for '
+             'grouping\n'
+             'purposes in literals.\n',
  'lambda': '\n'
            'Lambdas\n'
            '*******\n'
@@ -6406,9 +6518,9 @@ topics = {'assert': '\n'
                   '(swapped)\n'
                   '   operands.  These functions are only called if the left '
                   'operand does\n'
-                  '   not support the corresponding operation and the operands '
-                  'are of\n'
-                  '   different types. [2] For instance, to evaluate the '
+                  '   not support the corresponding operation [3] and the '
+                  'operands are of\n'
+                  '   different types. [4] For instance, to evaluate the '
                   'expression "x -\n'
                   '   y", where *y* is an instance of a class that has an '
                   '"__rsub__()"\n'
@@ -7384,6 +7496,15 @@ topics = {'assert': '\n'
                  'exception when no appropriate method is defined (typically\n'
                  '"AttributeError" or "TypeError").\n'
                  '\n'
+                 'Setting a special method to "None" indicates that the '
+                 'corresponding\n'
+                 'operation is not available.  For example, if a class sets '
+                 '"__iter__()"\n'
+                 'to "None", the class is not iterable, so calling "iter()" on '
+                 'its\n'
+                 'instances will raise a "TypeError" (without falling back to\n'
+                 '"__getitem__()"). [2]\n'
+                 '\n'
                  'When implementing a class that emulates any built-in type, '
                  'it is\n'
                  'important that the emulation only be implemented to the '
@@ -7463,7 +7584,7 @@ topics = {'assert': '\n'
                  '   Because "__new__()" and "__init__()" work together in '
                  'constructing\n'
                  '   objects ("__new__()" to create it, and "__init__()" to '
-                 'customise\n'
+                 'customize\n'
                  '   it), no non-"None" value may be returned by "__init__()"; '
                  'doing so\n'
                  '   will cause a "TypeError" to be raised at runtime.\n'
@@ -8272,7 +8393,7 @@ topics = {'assert': '\n'
                  'locally to the\n'
                  'result of "type(name, bases, namespace)".\n'
                  '\n'
-                 'The class creation process can be customised by passing the\n'
+                 'The class creation process can be customized by passing the\n'
                  '"metaclass" keyword argument in the class definition line, '
                  'or by\n'
                  'inheriting from an existing class that included such an '
@@ -8355,7 +8476,7 @@ topics = {'assert': '\n'
                  '\n'
                  'If the metaclass has no "__prepare__" attribute, then the '
                  'class\n'
-                 'namespace is initialised as an empty "dict()" instance.\n'
+                 'namespace is initialised as an empty ordered mapping.\n'
                  '\n'
                  'See also:\n'
                  '\n'
@@ -8423,11 +8544,12 @@ topics = {'assert': '\n'
                  '\n'
                  'When a new class is created by "type.__new__", the object '
                  'provided as\n'
-                 'the namespace parameter is copied to a standard Python '
-                 'dictionary and\n'
-                 'the original object is discarded. The new copy becomes the '
-                 '"__dict__"\n'
-                 'attribute of the class object.\n'
+                 'the namespace parameter is copied to a new ordered mapping '
+                 'and the\n'
+                 'original object is discarded. The new copy is wrapped in a '
+                 'read-only\n'
+                 'proxy, which becomes the "__dict__" attribute of the class '
+                 'object.\n'
                  '\n'
                  'See also:\n'
                  '\n'
@@ -8849,9 +8971,9 @@ topics = {'assert': '\n'
                  '(swapped)\n'
                  '   operands.  These functions are only called if the left '
                  'operand does\n'
-                 '   not support the corresponding operation and the operands '
-                 'are of\n'
-                 '   different types. [2] For instance, to evaluate the '
+                 '   not support the corresponding operation [3] and the '
+                 'operands are of\n'
+                 '   different types. [4] For instance, to evaluate the '
                  'expression "x -\n'
                  '   y", where *y* is an instance of a class that has an '
                  '"__rsub__()"\n'
@@ -10121,6 +10243,12 @@ topics = {'assert': '\n'
             'bytes\n'
             'literals.\n'
             '\n'
+            '   Changed in version 3.6: Unrecognized escape sequences produce '
+            'a\n'
+            '   DeprecationWarning.  In some future version of Python they '
+            'will be\n'
+            '   a SyntaxError.\n'
+            '\n'
             'Even in a raw literal, quotes can be escaped with a backslash, '
             'but the\n'
             'backslash remains in the result; for example, "r"\\""" is a '
@@ -10995,6 +11123,21 @@ topics = {'assert': '\n'
           "   Attribute assignment updates the module's namespace dictionary,\n"
           '   e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n'
           '\n'
+          '   Predefined (writable) attributes: "__name__" is the module\'s '
+          'name;\n'
+          '   "__doc__" is the module\'s documentation string, or "None" if\n'
+          '   unavailable; "__annotations__" (optional) is a dictionary\n'
+          '   containing *variable annotations* collected during module body\n'
+          '   execution; "__file__" is the pathname of the file from which '
+          'the\n'
+          '   module was loaded, if it was loaded from a file. The "__file__"\n'
+          '   attribute may be missing for certain types of modules, such as '
+          'C\n'
+          '   modules that are statically linked into the interpreter; for\n'
+          '   extension modules loaded dynamically from a shared library, it '
+          'is\n'
+          '   the pathname of the shared library file.\n'
+          '\n'
           '   Special read-only attribute: "__dict__" is the module\'s '
           'namespace\n'
           '   as a dictionary object.\n'
@@ -11008,19 +11151,6 @@ topics = {'assert': '\n'
           'the\n'
           '   module around while using its dictionary directly.\n'
           '\n'
-          '   Predefined (writable) attributes: "__name__" is the module\'s '
-          'name;\n'
-          '   "__doc__" is the module\'s documentation string, or "None" if\n'
-          '   unavailable; "__file__" is the pathname of the file from which '
-          'the\n'
-          '   module was loaded, if it was loaded from a file. The "__file__"\n'
-          '   attribute may be missing for certain types of modules, such as '
-          'C\n'
-          '   modules that are statically linked into the interpreter; for\n'
-          '   extension modules loaded dynamically from a shared library, it '
-          'is\n'
-          '   the pathname of the shared library file.\n'
-          '\n'
           'Custom classes\n'
           '   Custom class types are typically created by class definitions '
           '(see\n'
@@ -11074,7 +11204,10 @@ topics = {'assert': '\n'
           'the\n'
           '   order of their occurrence in the base class list; "__doc__" is '
           'the\n'
-          "   class's documentation string, or None if undefined.\n"
+          "   class's documentation string, or None if undefined;\n"
+          '   "__annotations__" (optional) is a dictionary containing '
+          '*variable\n'
+          '   annotations* collected during class body execution.\n'
           '\n'
           'Class instances\n'
           '   A class instance is created by calling a class object (see '
@@ -12512,7 +12645,13 @@ topics = {'assert': '\n'
              'comparing\n'
              'based on object identity).\n'
              '\n'
-             'New in version 3.3: The "start", "stop" and "step" attributes.\n',
+             'New in version 3.3: The "start", "stop" and "step" attributes.\n'
+             '\n'
+             'See also:\n'
+             '\n'
+             '  * The linspace recipe shows how to implement a lazy version '
+             'of\n'
+             '    range that suitable for floating point applications.\n',
  'typesseq-mutable': '\n'
                      'Mutable Sequence Types\n'
                      '**********************\n'