Skip to content
Snippets Groups Projects
topics.py 669 KiB
Newer Older
  • Learn to ignore specific revisions
  •              '   If a second argument is present, it is an expression which '
                 'must\n'
                 '   evaluate to true before the breakpoint is honored.\n'
                 '\n'
                 '   Without argument, list all breaks, including for each '
                 'breakpoint,\n'
                 '   the number of times that breakpoint has been hit, the '
                 'current\n'
                 '   ignore count, and the associated condition if any.\n'
                 '\n'
                 'tbreak [([filename:]lineno | function) [, condition]]\n'
                 '\n'
                 '   Temporary breakpoint, which is removed automatically when it '
                 'is\n'
                 '   first hit. The arguments are the same as for "break".\n'
                 '\n'
                 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n'
                 '\n'
                 '   With a *filename:lineno* argument, clear all the breakpoints '
                 'at\n'
                 '   this line. With a space separated list of breakpoint numbers, '
                 'clear\n'
                 '   those breakpoints. Without argument, clear all breaks (but '
                 'first\n'
                 '   ask confirmation).\n'
                 '\n'
                 'disable [bpnumber [bpnumber ...]]\n'
                 '\n'
                 '   Disable the breakpoints given as a space separated list of\n'
                 '   breakpoint numbers.  Disabling a breakpoint means it cannot '
                 'cause\n'
                 '   the program to stop execution, but unlike clearing a '
                 'breakpoint, it\n'
                 '   remains in the list of breakpoints and can be (re-)enabled.\n'
                 '\n'
                 'enable [bpnumber [bpnumber ...]]\n'
                 '\n'
                 '   Enable the breakpoints specified.\n'
                 '\n'
                 'ignore bpnumber [count]\n'
                 '\n'
                 '   Set the ignore count for the given breakpoint number.  If '
                 'count is\n'
                 '   omitted, the ignore count is set to 0.  A breakpoint becomes '
                 'active\n'
                 '   when the ignore count is zero.  When non-zero, the count is\n'
                 '   decremented each time the breakpoint is reached and the '
                 'breakpoint\n'
                 '   is not disabled and any associated condition evaluates to '
                 'true.\n'
                 '\n'
                 'condition bpnumber [condition]\n'
                 '\n'
                 '   Set a new *condition* for the breakpoint, an expression which '
                 'must\n'
                 '   evaluate to true before the breakpoint is honored.  If '
                 '*condition*\n'
                 '   is absent, any existing condition is removed; i.e., the '
                 'breakpoint\n'
                 '   is made unconditional.\n'
                 '\n'
                 'commands [bpnumber]\n'
                 '\n'
                 '   Specify a list of commands for breakpoint number *bpnumber*.  '
                 'The\n'
                 '   commands themselves appear on the following lines.  Type a '
                 'line\n'
                 '   containing just "end" to terminate the commands. An example:\n'
                 '\n'
                 '      (Pdb) commands 1\n'
                 '      (com) p some_variable\n'
                 '      (com) end\n'
                 '      (Pdb)\n'
                 '\n'
    
                 '   To remove all commands from a breakpoint, type "commands" '
                 'and\n'
                 '   follow it immediately with "end"; that is, give no commands.\n'
    
                 '   With no *bpnumber* argument, "commands" refers to the last\n'
                 '   breakpoint set.\n'
    
                 '\n'
                 '   You can use breakpoint commands to start your program up '
                 'again.\n'
    
                 '   Simply use the "continue" command, or "step", or any other '
                 'command\n'
                 '   that resumes execution.\n'
    
                 '\n'
                 '   Specifying any command resuming execution (currently '
    
                 '"continue",\n'
                 '   "step", "next", "return", "jump", "quit" and their '
                 'abbreviations)\n'
    
                 '   terminates the command list (as if that command was '
    
                 'immediately\n'
                 '   followed by end). This is because any time you resume '
                 'execution\n'
                 '   (even with a simple next or step), you may encounter another\n'
                 '   breakpoint—which could have its own command list, leading to\n'
                 '   ambiguities about which list to execute.\n'
    
                 '   If you use the ‘silent’ command in the command list, the '
    
                 'usual\n'
                 '   message about stopping at a breakpoint is not printed.  This '
                 'may be\n'
                 '   desirable for breakpoints that are to print a specific '
                 'message and\n'
                 '   then continue.  If none of the other commands print anything, '
                 'you\n'
                 '   see no sign that the breakpoint was reached.\n'
                 '\n'
                 's(tep)\n'
                 '\n'
                 '   Execute the current line, stop at the first possible '
                 'occasion\n'
                 '   (either in a function that is called or on the next line in '
                 'the\n'
                 '   current function).\n'
                 '\n'
                 'n(ext)\n'
                 '\n'
                 '   Continue execution until the next line in the current '
                 'function is\n'
                 '   reached or it returns.  (The difference between "next" and '
                 '"step"\n'
                 '   is that "step" stops inside a called function, while "next"\n'
                 '   executes called functions at (nearly) full speed, only '
                 'stopping at\n'
                 '   the next line in the current function.)\n'
                 '\n'
                 'unt(il) [lineno]\n'
                 '\n'
                 '   Without argument, continue execution until the line with a '
                 'number\n'
                 '   greater than the current one is reached.\n'
                 '\n'
                 '   With a line number, continue execution until a line with a '
                 'number\n'
                 '   greater or equal to that is reached.  In both cases, also '
                 'stop when\n'
                 '   the current frame returns.\n'
                 '\n'
                 '   Changed in version 3.2: Allow giving an explicit line '
                 'number.\n'
                 '\n'
                 'r(eturn)\n'
                 '\n'
                 '   Continue execution until the current function returns.\n'
                 '\n'
                 'c(ont(inue))\n'
                 '\n'
                 '   Continue execution, only stop when a breakpoint is '
                 'encountered.\n'
                 '\n'
                 'j(ump) lineno\n'
                 '\n'
                 '   Set the next line that will be executed.  Only available in '
                 'the\n'
                 '   bottom-most frame.  This lets you jump back and execute code '
                 'again,\n'
    
                 '   or jump forward to skip code that you don’t want to run.\n'
    
                 '   It should be noted that not all jumps are allowed – for '
                 'instance it\n'
                 '   is not possible to jump into the middle of a "for" loop or '
                 'out of a\n'
                 '   "finally" clause.\n'
    
                 '\n'
                 'l(ist) [first[, last]]\n'
                 '\n'
                 '   List source code for the current file.  Without arguments, '
                 'list 11\n'
                 '   lines around the current line or continue the previous '
                 'listing.\n'
                 '   With "." as argument, list 11 lines around the current line.  '
                 'With\n'
                 '   one argument, list 11 lines around at that line.  With two\n'
                 '   arguments, list the given range; if the second argument is '
                 'less\n'
                 '   than the first, it is interpreted as a count.\n'
                 '\n'
                 '   The current line in the current frame is indicated by "->".  '
                 'If an\n'
                 '   exception is being debugged, the line where the exception '
                 'was\n'
                 '   originally raised or propagated is indicated by ">>", if it '
                 'differs\n'
                 '   from the current line.\n'
                 '\n'
                 '   New in version 3.2: The ">>" marker.\n'
                 '\n'
                 'll | longlist\n'
                 '\n'
                 '   List all source code for the current function or frame.\n'
                 '   Interesting lines are marked as for "list".\n'
                 '\n'
                 '   New in version 3.2.\n'
                 '\n'
                 'a(rgs)\n'
                 '\n'
                 '   Print the argument list of the current function.\n'
                 '\n'
                 'p expression\n'
                 '\n'
                 '   Evaluate the *expression* in the current context and print '
                 'its\n'
                 '   value.\n'
                 '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   Note:\n'
                 '\n'
                 '     "print()" can also be used, but is not a debugger command — '
                 'this\n'
                 '     executes the Python "print()" function.\n'
    
                 '\n'
                 'pp expression\n'
                 '\n'
                 '   Like the "p" command, except the value of the expression is '
                 'pretty-\n'
                 '   printed using the "pprint" module.\n'
                 '\n'
                 'whatis expression\n'
                 '\n'
                 '   Print the type of the *expression*.\n'
                 '\n'
                 'source expression\n'
                 '\n'
                 '   Try to get source code for the given object and display it.\n'
                 '\n'
                 '   New in version 3.2.\n'
                 '\n'
                 'display [expression]\n'
                 '\n'
                 '   Display the value of the expression if it changed, each time\n'
                 '   execution stops in the current frame.\n'
                 '\n'
                 '   Without expression, list all display expressions for the '
                 'current\n'
                 '   frame.\n'
                 '\n'
                 '   New in version 3.2.\n'
                 '\n'
                 'undisplay [expression]\n'
                 '\n'
                 '   Do not display the expression any more in the current frame.\n'
                 '   Without expression, clear all display expressions for the '
                 'current\n'
                 '   frame.\n'
                 '\n'
                 '   New in version 3.2.\n'
                 '\n'
                 'interact\n'
                 '\n'
    
                 '   Start an interactive interpreter (using the "code" module) '
    
                 'whose\n'
                 '   global namespace contains all the (global and local) names '
                 'found in\n'
                 '   the current scope.\n'
                 '\n'
                 '   New in version 3.2.\n'
                 '\n'
                 'alias [name [command]]\n'
                 '\n'
                 '   Create an alias called *name* that executes *command*.  The '
                 'command\n'
                 '   must *not* be enclosed in quotes.  Replaceable parameters can '
                 'be\n'
                 '   indicated by "%1", "%2", and so on, while "%*" is replaced by '
                 'all\n'
                 '   the parameters. If no command is given, the current alias '
                 'for\n'
                 '   *name* is shown. If no arguments are given, all aliases are '
                 'listed.\n'
                 '\n'
                 '   Aliases may be nested and can contain anything that can be '
                 'legally\n'
                 '   typed at the pdb prompt.  Note that internal pdb commands '
                 '*can* be\n'
                 '   overridden by aliases.  Such a command is then hidden until '
                 'the\n'
                 '   alias is removed.  Aliasing is recursively applied to the '
                 'first\n'
                 '   word of the command line; all other words in the line are '
                 'left\n'
                 '   alone.\n'
                 '\n'
                 '   As an example, here are two useful aliases (especially when '
                 'placed\n'
                 '   in the ".pdbrc" file):\n'
                 '\n'
                 '      # Print instance variables (usage "pi classInst")\n'
                 '      alias pi for k in %1.__dict__.keys(): '
                 'print("%1.",k,"=",%1.__dict__[k])\n'
                 '      # Print instance variables in self\n'
                 '      alias ps pi self\n'
                 '\n'
                 'unalias name\n'
                 '\n'
                 '   Delete the specified alias.\n'
                 '\n'
                 '! statement\n'
                 '\n'
                 '   Execute the (one-line) *statement* in the context of the '
                 'current\n'
                 '   stack frame. The exclamation point can be omitted unless the '
                 'first\n'
                 '   word of the statement resembles a debugger command.  To set '
                 'a\n'
                 '   global variable, you can prefix the assignment command with '
                 'a\n'
                 '   "global" statement on the same line, e.g.:\n'
                 '\n'
                 "      (Pdb) global list_options; list_options = ['-l']\n"
                 '      (Pdb)\n'
                 '\n'
                 'run [args ...]\n'
                 'restart [args ...]\n'
                 '\n'
                 '   Restart the debugged Python program.  If an argument is '
                 'supplied,\n'
                 '   it is split with "shlex" and the result is used as the new\n'
                 '   "sys.argv". History, breakpoints, actions and debugger '
                 'options are\n'
                 '   preserved. "restart" is an alias for "run".\n'
                 '\n'
                 'q(uit)\n'
                 '\n'
                 '   Quit from the debugger.  The program being executed is '
                 'aborted.\n'
                 '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'debug code\n'
                 '\n'
                 '   Enter a recursive debugger that steps through the code '
                 'argument\n'
                 '   (which is an arbitrary expression or statement to be executed '
                 'in\n'
                 '   the current environment).\n'
                 '\n'
                 'retval\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '\n'
                 '   Print the return value for the last return of a function.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '\n'
    
                 '-[ Footnotes ]-\n'
                 '\n'
                 '[1] Whether a frame is considered to originate in a certain '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'module is\n'
                 '    determined by the "__name__" in the frame globals.\n',
    
     'del': 'The "del" statement\n'
    
            '*******************\n'
            '\n'
            '   del_stmt ::= "del" target_list\n'
            '\n'
            'Deletion is recursively defined very similar to the way assignment '
            'is\n'
            'defined. Rather than spelling it out in full details, here are some\n'
            'hints.\n'
            '\n'
            'Deletion of a target list recursively deletes each target, from left\n'
            'to right.\n'
            '\n'
            'Deletion of a name removes the binding of that name from the local '
            'or\n'
            'global namespace, depending on whether the name occurs in a "global"\n'
            'statement in the same code block.  If the name is unbound, a\n'
            '"NameError" exception will be raised.\n'
            '\n'
            'Deletion of attribute references, subscriptions and slicings is '
            'passed\n'
            'to the primary object involved; deletion of a slicing is in general\n'
            'equivalent to assignment of an empty slice of the right type (but '
            'even\n'
            'this is determined by the sliced object).\n'
            '\n'
            'Changed in version 3.2: Previously it was illegal to delete a name\n'
            'from the local namespace if it occurs as a free variable in a nested\n'
            'block.\n',
    
     'dict': 'Dictionary displays\n'
    
             '*******************\n'
             '\n'
             'A dictionary display is a possibly empty series of key/datum pairs\n'
             'enclosed in curly braces:\n'
             '\n'
             '   dict_display       ::= "{" [key_datum_list | dict_comprehension] '
             '"}"\n'
             '   key_datum_list     ::= key_datum ("," key_datum)* [","]\n'
    
             '   key_datum          ::= expression ":" expression | "**" or_expr\n'
    
             '   dict_comprehension ::= expression ":" expression comp_for\n'
             '\n'
             'A dictionary display yields a new dictionary object.\n'
             '\n'
             'If a comma-separated sequence of key/datum pairs is given, they are\n'
             'evaluated from left to right to define the entries of the '
             'dictionary:\n'
             'each key object is used as a key into the dictionary to store the\n'
             'corresponding datum.  This means that you can specify the same key\n'
    
             'multiple times in the key/datum list, and the final dictionary’s '
    
             'value\n'
             'for that key will be the last one given.\n'
             '\n'
    
             'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n'
             'must be a *mapping*.  Each mapping item is added to the new\n'
             'dictionary.  Later values replace values already set by earlier\n'
             'key/datum pairs and earlier dictionary unpackings.\n'
             '\n'
             'New in version 3.5: Unpacking into dictionary displays, originally\n'
             'proposed by **PEP 448**.\n'
             '\n'
    
             'A dict comprehension, in contrast to list and set comprehensions,\n'
             'needs two expressions separated with a colon followed by the usual\n'
    
             '“for” and “if” clauses. When the comprehension is run, the '
    
             'resulting\n'
             'key and value elements are inserted in the new dictionary in the '
             'order\n'
             'they are produced.\n'
             '\n'
             'Restrictions on the types of the key values are listed earlier in\n'
             'section The standard type hierarchy.  (To summarize, the key type\n'
             'should be *hashable*, which excludes all mutable objects.)  Clashes\n'
             'between duplicate keys are not detected; the last datum (textually\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             'rightmost in the display) stored for a given key value prevails.\n'
             '\n'
             'Changed in version 3.8: Prior to Python 3.8, in dict '
             'comprehensions,\n'
             'the evaluation order of key and value was not well-defined.  In\n'
             'CPython, the value was evaluated before the key.  Starting with '
             '3.8,\n'
             'the key is evaluated before the value, as proposed by **PEP 572**.\n',
    
     'dynamic-features': 'Interaction with dynamic features\n'
    
                         '*********************************\n'
                         '\n'
                         'Name resolution of free variables occurs at runtime, not '
                         'at compile\n'
                         'time. This means that the following code will print 42:\n'
                         '\n'
                         '   i = 10\n'
                         '   def f():\n'
                         '       print(i)\n'
                         '   i = 42\n'
                         '   f()\n'
                         '\n'
                         'The "eval()" and "exec()" functions do not have access '
                         'to the full\n'
                         'environment for resolving names.  Names may be resolved '
                         'in the local\n'
                         'and global namespaces of the caller.  Free variables are '
                         'not resolved\n'
                         'in the nearest enclosing namespace, but in the global '
                         'namespace.  [1]\n'
                         'The "exec()" and "eval()" functions have optional '
                         'arguments to\n'
                         'override the global and local namespace.  If only one '
                         'namespace is\n'
                         'specified, it is used for both.\n',
    
     'else': 'The "if" statement\n'
    
             '******************\n'
             '\n'
             'The "if" statement is used for conditional execution:\n'
             '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
             '   if_stmt ::= "if" assignment_expression ":" suite\n'
             '               ("elif" assignment_expression ":" suite)*\n'
    
             '               ["else" ":" suite]\n'
             '\n'
             'It selects exactly one of the suites by evaluating the expressions '
             'one\n'
             'by one until one is found to be true (see section Boolean '
             'operations\n'
             'for the definition of true and false); then that suite is executed\n'
             '(and no other part of the "if" statement is executed or evaluated).\n'
             'If all expressions are false, the suite of the "else" clause, if\n'
             'present, is executed.\n',
    
     'exceptions': 'Exceptions\n'
    
                   '**********\n'
                   '\n'
                   'Exceptions are a means of breaking out of the normal flow of '
                   'control\n'
                   'of a code block in order to handle errors or other '
                   'exceptional\n'
                   'conditions.  An exception is *raised* at the point where the '
                   'error is\n'
                   'detected; it may be *handled* by the surrounding code block or '
                   'by any\n'
                   'code block that directly or indirectly invoked the code block '
                   'where\n'
                   'the error occurred.\n'
                   '\n'
                   'The Python interpreter raises an exception when it detects a '
                   'run-time\n'
                   'error (such as division by zero).  A Python program can also\n'
                   'explicitly raise an exception with the "raise" statement. '
                   'Exception\n'
    
                   'handlers are specified with the "try" … "except" statement.  '
    
                   'The\n'
                   '"finally" clause of such a statement can be used to specify '
                   'cleanup\n'
                   'code which does not handle the exception, but is executed '
                   'whether an\n'
                   'exception occurred or not in the preceding code.\n'
                   '\n'
    
                   'Python uses the “termination” model of error handling: an '
    
                   'exception\n'
                   'handler can find out what happened and continue execution at '
                   'an outer\n'
                   'level, but it cannot repair the cause of the error and retry '
                   'the\n'
                   'failing operation (except by re-entering the offending piece '
                   'of code\n'
                   'from the top).\n'
                   '\n'
                   'When an exception is not handled at all, the interpreter '
                   'terminates\n'
                   'execution of the program, or returns to its interactive main '
                   'loop.  In\n'
    
                   'either case, it prints a stack traceback, except when the '
    
                   'exception is\n'
                   '"SystemExit".\n'
                   '\n'
                   'Exceptions are identified by class instances.  The "except" '
                   'clause is\n'
                   'selected depending on the class of the instance: it must '
                   'reference the\n'
                   'class of the instance or a base class thereof.  The instance '
                   'can be\n'
                   'received by the handler and can carry additional information '
                   'about the\n'
                   'exceptional condition.\n'
                   '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                   'Note:\n'
                   '\n'
                   '  Exception messages are not part of the Python API.  Their '
                   'contents\n'
                   '  may change from one version of Python to the next without '
                   'warning\n'
                   '  and should not be relied on by code which will run under '
                   'multiple\n'
                   '  versions of the interpreter.\n'
    
                   '\n'
                   'See also the description of the "try" statement in section The '
                   'try\n'
                   'statement and "raise" statement in section The raise '
                   'statement.\n'
                   '\n'
                   '-[ Footnotes ]-\n'
                   '\n'
                   '[1] This limitation occurs because the code that is executed '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                   'by these\n'
                   '    operations is not available at the time the module is '
                   'compiled.\n',
    
     'execmodel': 'Execution model\n'
    
                  '***************\n'
                  '\n'
                  '\n'
                  'Structure of a program\n'
                  '======================\n'
                  '\n'
                  'A Python program is constructed from code blocks. A *block* is '
                  'a piece\n'
                  'of Python program text that is executed as a unit. The '
                  'following are\n'
                  'blocks: a module, a function body, and a class definition. '
                  'Each\n'
                  'command typed interactively is a block.  A script file (a file '
                  'given\n'
                  'as standard input to the interpreter or specified as a command '
                  'line\n'
                  'argument to the interpreter) is a code block.  A script command '
                  '(a\n'
                  'command specified on the interpreter command line with the '
    
                  'option) is a code block.  The string argument passed to the '
                  'built-in\n'
                  'functions "eval()" and "exec()" is a code block.\n'
                  '\n'
                  'A code block is executed in an *execution frame*.  A frame '
                  'contains\n'
                  'some administrative information (used for debugging) and '
                  'determines\n'
    
                  'where and how execution continues after the code block’s '
    
                  'execution has\n'
                  'completed.\n'
                  '\n'
                  '\n'
                  'Naming and binding\n'
                  '==================\n'
                  '\n'
                  '\n'
                  'Binding of names\n'
                  '----------------\n'
                  '\n'
                  '*Names* refer to objects.  Names are introduced by name '
                  'binding\n'
                  'operations.\n'
                  '\n'
                  'The following constructs bind names: formal parameters to '
                  'functions,\n'
                  '"import" statements, class and function definitions (these bind '
                  'the\n'
                  'class or function name in the defining block), and targets that '
                  'are\n'
                  'identifiers if occurring in an assignment, "for" loop header, '
                  'or after\n'
                  '"as" in a "with" statement or "except" clause. The "import" '
                  'statement\n'
                  'of the form "from ... import *" binds all names defined in the\n'
                  'imported module, except those beginning with an underscore.  '
                  'This form\n'
                  'may only be used at the module level.\n'
                  '\n'
                  'A target occurring in a "del" statement is also considered '
                  'bound for\n'
                  'this purpose (though the actual semantics are to unbind the '
                  'name).\n'
                  '\n'
                  'Each assignment or import statement occurs within a block '
                  'defined by a\n'
                  'class or function definition or at the module level (the '
                  'top-level\n'
                  'code block).\n'
                  '\n'
                  'If a name is bound in a block, it is a local variable of that '
                  'block,\n'
                  'unless declared as "nonlocal" or "global".  If a name is bound '
                  'at the\n'
                  'module level, it is a global variable.  (The variables of the '
                  'module\n'
                  'code block are local and global.)  If a variable is used in a '
                  'code\n'
                  'block but not defined there, it is a *free variable*.\n'
                  '\n'
                  'Each occurrence of a name in the program text refers to the '
                  '*binding*\n'
                  'of that name established by the following name resolution '
                  'rules.\n'
                  '\n'
                  '\n'
                  'Resolution of names\n'
                  '-------------------\n'
                  '\n'
                  'A *scope* defines the visibility of a name within a block.  If '
                  'a local\n'
                  'variable is defined in a block, its scope includes that block.  '
                  'If the\n'
                  'definition occurs in a function block, the scope extends to any '
                  'blocks\n'
                  'contained within the defining one, unless a contained block '
                  'introduces\n'
                  'a different binding for the name.\n'
                  '\n'
                  'When a name is used in a code block, it is resolved using the '
                  'nearest\n'
                  'enclosing scope.  The set of all such scopes visible to a code '
                  'block\n'
    
                  'is called the block’s *environment*.\n'
    
                  '\n'
                  'When a name is not found at all, a "NameError" exception is '
                  'raised. If\n'
                  'the current scope is a function scope, and the name refers to a '
                  'local\n'
                  'variable that has not yet been bound to a value at the point '
                  'where the\n'
                  'name is used, an "UnboundLocalError" exception is raised.\n'
                  '"UnboundLocalError" is a subclass of "NameError".\n'
                  '\n'
                  'If a name binding operation occurs anywhere within a code '
                  'block, all\n'
                  'uses of the name within the block are treated as references to '
                  'the\n'
                  'current block.  This can lead to errors when a name is used '
                  'within a\n'
                  'block before it is bound.  This rule is subtle.  Python lacks\n'
                  'declarations and allows name binding operations to occur '
                  'anywhere\n'
                  'within a code block.  The local variables of a code block can '
                  'be\n'
                  'determined by scanning the entire text of the block for name '
                  'binding\n'
                  'operations.\n'
                  '\n'
                  'If the "global" statement occurs within a block, all uses of '
                  'the name\n'
                  'specified in the statement refer to the binding of that name in '
                  'the\n'
                  'top-level namespace.  Names are resolved in the top-level '
                  'namespace by\n'
                  'searching the global namespace, i.e. the namespace of the '
                  'module\n'
                  'containing the code block, and the builtins namespace, the '
                  'namespace\n'
                  'of the module "builtins".  The global namespace is searched '
                  'first.  If\n'
                  'the name is not found there, the builtins namespace is '
                  'searched.  The\n'
                  '"global" statement must precede all uses of the name.\n'
                  '\n'
                  'The "global" statement has the same scope as a name binding '
                  'operation\n'
                  'in the same block.  If the nearest enclosing scope for a free '
                  'variable\n'
                  'contains a global statement, the free variable is treated as a '
                  'global.\n'
                  '\n'
                  'The "nonlocal" statement causes corresponding names to refer '
                  'to\n'
                  'previously bound variables in the nearest enclosing function '
                  'scope.\n'
                  '"SyntaxError" is raised at compile time if the given name does '
                  'not\n'
                  'exist in any enclosing function scope.\n'
                  '\n'
                  'The namespace for a module is automatically created the first '
                  'time a\n'
                  'module is imported.  The main module for a script is always '
                  'called\n'
                  '"__main__".\n'
                  '\n'
                  'Class definition blocks and arguments to "exec()" and "eval()" '
                  'are\n'
                  'special in the context of name resolution. A class definition '
                  'is an\n'
                  'executable statement that may use and define names. These '
                  'references\n'
                  'follow the normal rules for name resolution with an exception '
                  'that\n'
                  'unbound local variables are looked up in the global namespace. '
                  'The\n'
                  'namespace of the class definition becomes the attribute '
                  'dictionary of\n'
                  'the class. The scope of names defined in a class block is '
                  'limited to\n'
                  'the class block; it does not extend to the code blocks of '
    
                  'methods –\n'
    
                  'this includes comprehensions and generator expressions since '
                  'they are\n'
                  'implemented using a function scope.  This means that the '
                  'following\n'
                  'will fail:\n'
                  '\n'
                  '   class A:\n'
                  '       a = 42\n'
                  '       b = list(a + i for i in range(10))\n'
                  '\n'
                  '\n'
                  'Builtins and restricted execution\n'
                  '---------------------------------\n'
                  '\n'
    
                  '**CPython implementation detail:** Users should not touch\n'
                  '"__builtins__"; it is strictly an implementation detail.  '
                  'Users\n'
                  'wanting to override values in the builtins namespace should '
                  '"import"\n'
                  'the "builtins" module and modify its attributes appropriately.\n'
                  '\n'
    
                  'The builtins namespace associated with the execution of a code '
                  'block\n'
                  'is actually found by looking up the name "__builtins__" in its '
                  'global\n'
                  'namespace; this should be a dictionary or a module (in the '
                  'latter case\n'
    
                  'the module’s dictionary is used).  By default, when in the '
    
                  '"__main__"\n'
                  'module, "__builtins__" is the built-in module "builtins"; when '
                  'in any\n'
                  'other module, "__builtins__" is an alias for the dictionary of '
                  'the\n'
    
                  '"builtins" module itself.\n'
    
                  '\n'
                  '\n'
                  'Interaction with dynamic features\n'
                  '---------------------------------\n'
                  '\n'
                  'Name resolution of free variables occurs at runtime, not at '
                  'compile\n'
                  'time. This means that the following code will print 42:\n'
                  '\n'
                  '   i = 10\n'
                  '   def f():\n'
                  '       print(i)\n'
                  '   i = 42\n'
                  '   f()\n'
                  '\n'
                  'The "eval()" and "exec()" functions do not have access to the '
                  'full\n'
                  'environment for resolving names.  Names may be resolved in the '
                  'local\n'
                  'and global namespaces of the caller.  Free variables are not '
                  'resolved\n'
                  'in the nearest enclosing namespace, but in the global '
                  'namespace.  [1]\n'
                  'The "exec()" and "eval()" functions have optional arguments to\n'
                  'override the global and local namespace.  If only one namespace '
                  'is\n'
                  'specified, it is used for both.\n'
                  '\n'
                  '\n'
                  'Exceptions\n'
                  '==========\n'
                  '\n'
                  'Exceptions are a means of breaking out of the normal flow of '
                  'control\n'
                  'of a code block in order to handle errors or other exceptional\n'
                  'conditions.  An exception is *raised* at the point where the '
                  'error is\n'
                  'detected; it may be *handled* by the surrounding code block or '
                  'by any\n'
                  'code block that directly or indirectly invoked the code block '
                  'where\n'
                  'the error occurred.\n'
                  '\n'
                  'The Python interpreter raises an exception when it detects a '
                  'run-time\n'
                  'error (such as division by zero).  A Python program can also\n'
                  'explicitly raise an exception with the "raise" statement. '
                  'Exception\n'
    
                  'handlers are specified with the "try" … "except" statement.  '
    
                  'The\n'
                  '"finally" clause of such a statement can be used to specify '
                  'cleanup\n'
                  'code which does not handle the exception, but is executed '
                  'whether an\n'
                  'exception occurred or not in the preceding code.\n'
                  '\n'
    
                  'Python uses the “termination” model of error handling: an '
    
                  'exception\n'
                  'handler can find out what happened and continue execution at an '
                  'outer\n'
                  'level, but it cannot repair the cause of the error and retry '
                  'the\n'
                  'failing operation (except by re-entering the offending piece of '
                  'code\n'
                  'from the top).\n'
                  '\n'
                  'When an exception is not handled at all, the interpreter '
                  'terminates\n'
                  'execution of the program, or returns to its interactive main '
                  'loop.  In\n'
    
                  'either case, it prints a stack traceback, except when the '
    
                  'exception is\n'
                  '"SystemExit".\n'
                  '\n'
                  'Exceptions are identified by class instances.  The "except" '
                  'clause is\n'
                  'selected depending on the class of the instance: it must '
                  'reference the\n'
                  'class of the instance or a base class thereof.  The instance '
                  'can be\n'
                  'received by the handler and can carry additional information '
                  'about the\n'
                  'exceptional condition.\n'
                  '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                  'Note:\n'
                  '\n'
                  '  Exception messages are not part of the Python API.  Their '
                  'contents\n'
                  '  may change from one version of Python to the next without '
                  'warning\n'
                  '  and should not be relied on by code which will run under '
                  'multiple\n'
                  '  versions of the interpreter.\n'
    
                  '\n'
                  'See also the description of the "try" statement in section The '
                  'try\n'
                  'statement and "raise" statement in section The raise '
                  'statement.\n'
                  '\n'
                  '-[ Footnotes ]-\n'
                  '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                  '[1] This limitation occurs because the code that is executed by '
                  'these\n'
                  '    operations is not available at the time the module is '
                  'compiled.\n',
    
     'exprlists': 'Expression lists\n'
    
                  '****************\n'
                  '\n'
    
                  '   expression_list    ::= expression ("," expression)* [","]\n'
                  '   starred_list       ::= starred_item ("," starred_item)* '
    
                  '[","]\n'
    
                  '   starred_expression ::= expression | (starred_item ",")* '
    
                  '[starred_item]\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                  '   starred_item       ::= assignment_expression | "*" or_expr\n'
    
                  'Except when part of a list or set display, an expression list\n'
                  'containing at least one comma yields a tuple.  The length of '
                  'the tuple\n'
                  'is the number of expressions in the list.  The expressions are\n'
                  'evaluated from left to right.\n'
                  '\n'
                  'An asterisk "*" denotes *iterable unpacking*.  Its operand must '
                  'be an\n'
                  '*iterable*.  The iterable is expanded into a sequence of items, '
                  'which\n'
                  'are included in the new tuple, list, or set, at the site of '
                  'the\n'
                  'unpacking.\n'
                  '\n'
                  'New in version 3.5: Iterable unpacking in expression lists, '
                  'originally\n'
                  'proposed by **PEP 448**.\n'
    
                  '\n'
                  'The trailing comma is required only to create a single tuple '
                  '(a.k.a. a\n'
                  '*singleton*); it is optional in all other cases.  A single '
                  'expression\n'
    
                  'without a trailing comma doesn’t create a tuple, but rather '
    
                  'yields the\n'
                  'value of that expression. (To create an empty tuple, use an '
                  'empty pair\n'
                  'of parentheses: "()".)\n',
    
     'floating': 'Floating point literals\n'
    
                 '***********************\n'
                 '\n'
                 'Floating point literals are described by the following lexical\n'
                 'definitions:\n'
                 '\n'
                 '   floatnumber   ::= pointfloat | exponentfloat\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.  As in integer literals, underscores '
                 'are\n'
                 'supported for digit grouping.\n'
    
                 'Some examples of floating point literals:\n'
                 '\n'
                 '   3.14    10.    .001    1e100    3.14e-10    0e0    '
                 '3.14_15_93\n'
    
                 'Changed in version 3.6: Underscores are now allowed for '
                 'grouping\n'
                 'purposes in literals.\n',
    
     'for': 'The "for" statement\n'
    
            '*******************\n'
            '\n'
            'The "for" statement is used to iterate over the elements of a '
            'sequence\n'
            '(such as a string, tuple or list) or other iterable object:\n'
            '\n'
            '   for_stmt ::= "for" target_list "in" expression_list ":" suite\n'
            '                ["else" ":" suite]\n'
            '\n'
            'The expression list is evaluated once; it should yield an iterable\n'
            'object.  An iterator is created for the result of the\n'
            '"expression_list".  The suite is then executed once for each item\n'
            'provided by the iterator, in the order returned by the iterator.  '
            'Each\n'
            'item in turn is assigned to the target list using the standard rules\n'
            'for assignments (see Assignment statements), and then the suite is\n'
            'executed.  When the items are exhausted (which is immediately when '
            'the\n'
            'sequence is empty or an iterator raises a "StopIteration" '
            'exception),\n'
            'the suite in the "else" clause, if present, is executed, and the '
            'loop\n'
            'terminates.\n'
            '\n'
            'A "break" statement executed in the first suite terminates the loop\n'
    
            'without executing the "else" clause’s suite.  A "continue" statement\n'
    
            'executed in the first suite skips the rest of the suite and '
            'continues\n'
            'with the next item, or with the "else" clause if there is no next\n'
            'item.\n'
            '\n'
    
            'The for-loop makes assignments to the variables in the target list.\n'
    
            'This overwrites all previous assignments to those variables '
            'including\n'
            'those made in the suite of the for-loop:\n'
            '\n'
            '   for i in range(10):\n'
            '       print(i)\n'
            '       i = 5             # this will not affect the for-loop\n'
            '                         # because i will be overwritten with the '
            'next\n'
            '                         # index in the range\n'
            '\n'
            'Names in the target list are not deleted when the loop is finished,\n'
            'but if the sequence is empty, they will not have been assigned to at\n'
            'all by the loop.  Hint: the built-in function "range()" returns an\n'
    
            'iterator of integers suitable to emulate the effect of Pascal’s "for '
    
            'i\n'
            ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n'
            '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
            'Note:\n'
            '\n'
            '  There is a subtlety when the sequence is being modified by the '
            'loop\n'
            '  (this can only occur for mutable sequences, e.g. lists).  An\n'
    
            '  internal counter is used to keep track of which item is used next,\n'
            '  and this is incremented on each iteration.  When this counter has\n'
            '  reached the length of the sequence the loop terminates.  This '
            'means\n'
            '  that if the suite deletes the current (or a previous) item from '
            'the\n'
            '  sequence, the next item will be skipped (since it gets the index '
            'of\n'
            '  the current item which has already been treated).  Likewise, if '
            'the\n'
            '  suite inserts an item in the sequence before the current item, the\n'