Skip to content
Snippets Groups Projects
topics.py 669 KiB
Newer Older
  • Learn to ignore specific revisions
  •              '   async for TARGET in ITER:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '       SUITE\n'
    
                 '   else:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '       SUITE2\n'
    
                 '\n'
                 'Is semantically equivalent to:\n'
                 '\n'
                 '   iter = (ITER)\n'
    
                 '   iter = type(iter).__aiter__(iter)\n'
    
                 '   running = True\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '\n'
    
                 '   while running:\n'
                 '       try:\n'
                 '           TARGET = await type(iter).__anext__(iter)\n'
                 '       except StopAsyncIteration:\n'
                 '           running = False\n'
                 '       else:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '           SUITE\n'
    
                 '   else:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '       SUITE2\n'
    
                 '\n'
                 'See also "__aiter__()" and "__anext__()" for details.\n'
                 '\n'
    
                 'It is a "SyntaxError" to use an "async for" statement outside '
                 'the body\n'
                 'of a coroutine function.\n'
    
                 '\n'
                 '\n'
                 'The "async with" statement\n'
                 '--------------------------\n'
                 '\n'
                 '   async_with_stmt ::= "async" with_stmt\n'
                 '\n'
                 'An *asynchronous context manager* is a *context manager* that is '
                 'able\n'
                 'to suspend execution in its *enter* and *exit* methods.\n'
                 '\n'
                 'The following code:\n'
                 '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   async with EXPRESSION as TARGET:\n'
                 '       SUITE\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 'is semantically equivalent to:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   manager = (EXPRESSION)\n'
                 '   aexit = type(manager).__aexit__\n'
                 '   aenter = type(manager).__aenter__\n'
                 '   value = await aenter(manager)\n'
                 '   hit_except = False\n'
    
                 '\n'
                 '   try:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '       TARGET = value\n'
                 '       SUITE\n'
    
                 '   except:\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '       hit_except = True\n'
                 '       if not await aexit(manager, *sys.exc_info()):\n'
    
                 '           raise\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   finally:\n'
                 '       if not hit_except:\n'
                 '           await aexit(manager, None, None, None)\n'
    
                 '\n'
                 'See also "__aenter__()" and "__aexit__()" for details.\n'
                 '\n'
    
                 'It is a "SyntaxError" to use an "async with" statement outside '
                 'the\n'
                 'body of a coroutine function.\n'
    
                 'See also:\n'
                 '\n'
                 '  **PEP 492** - Coroutines with async and await syntax\n'
                 '     The proposal that made coroutines a proper standalone '
                 'concept in\n'
                 '     Python, and added supporting syntax.\n'
    
                 '\n'
                 '-[ Footnotes ]-\n'
                 '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '[1] The exception is propagated to the invocation stack unless '
                 'there\n'
                 '    is a "finally" clause which happens to raise another '
                 'exception.\n'
                 '    That new exception causes the old one to be lost.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '[2] A string literal appearing as the first statement in the '
                 'function\n'
                 '    body is transformed into the function’s "__doc__" attribute '
                 'and\n'
                 '    therefore the function’s *docstring*.\n'
    
                 '[3] A string literal appearing as the first statement in the '
    
                 'class\n'
    
                 '    body is transformed into the namespace’s "__doc__" item and\n'
                 '    therefore the class’s *docstring*.\n',
    
     'context-managers': 'With Statement Context Managers\n'
    
                         '*******************************\n'
                         '\n'
                         'A *context manager* is an object that defines the '
                         'runtime context to\n'
                         'be established when executing a "with" statement. The '
                         'context manager\n'
                         'handles the entry into, and the exit from, the desired '
                         'runtime context\n'
                         'for the execution of the block of code.  Context '
                         'managers are normally\n'
                         'invoked using the "with" statement (described in section '
                         'The with\n'
                         'statement), but can also be used by directly invoking '
                         'their methods.\n'
                         '\n'
                         'Typical uses of context managers include saving and '
                         'restoring various\n'
                         'kinds of global state, locking and unlocking resources, '
                         'closing opened\n'
                         'files, etc.\n'
                         '\n'
                         'For more information on context managers, see Context '
                         'Manager Types.\n'
                         '\n'
                         'object.__enter__(self)\n'
                         '\n'
                         '   Enter the runtime context related to this object. The '
                         '"with"\n'
    
                         '   statement will bind this method’s return value to the '
    
                         'target(s)\n'
                         '   specified in the "as" clause of the statement, if '
                         'any.\n'
                         '\n'
                         'object.__exit__(self, exc_type, exc_value, traceback)\n'
                         '\n'
                         '   Exit the runtime context related to this object. The '
                         'parameters\n'
                         '   describe the exception that caused the context to be '
                         'exited. If the\n'
                         '   context was exited without an exception, all three '
                         'arguments will\n'
                         '   be "None".\n'
                         '\n'
                         '   If an exception is supplied, and the method wishes to '
                         'suppress the\n'
                         '   exception (i.e., prevent it from being propagated), '
                         'it should\n'
                         '   return a true value. Otherwise, the exception will be '
                         'processed\n'
                         '   normally upon exit from this method.\n'
                         '\n'
                         '   Note that "__exit__()" methods should not reraise the '
                         'passed-in\n'
    
                         '   exception; this is the caller’s responsibility.\n'
    
                         '\n'
                         'See also:\n'
                         '\n'
    
                         '  **PEP 343** - The “with” statement\n'
    
                         '     The specification, background, and examples for the '
                         'Python "with"\n'
                         '     statement.\n',
    
     'continue': 'The "continue" statement\n'
    
                 '************************\n'
                 '\n'
                 '   continue_stmt ::= "continue"\n'
                 '\n'
                 '"continue" may only occur syntactically nested in a "for" or '
                 '"while"\n'
    
                 'loop, but not nested in a function or class definition within '
                 'that\n'
                 'loop.  It continues with the next cycle of the nearest enclosing '
                 'loop.\n'
    
                 '\n'
                 'When "continue" passes control out of a "try" statement with a\n'
                 '"finally" clause, that "finally" clause is executed before '
                 'really\n'
                 'starting the next loop cycle.\n',
    
     'conversions': 'Arithmetic conversions\n'
    
                    '**********************\n'
                    '\n'
                    'When a description of an arithmetic operator below uses the '
                    'phrase\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    '“the numeric arguments are converted to a common type”, this '
    
                    'means\n'
                    'that the operator implementation for built-in types works as '
                    'follows:\n'
                    '\n'
                    '* If either argument is a complex number, the other is '
                    'converted to\n'
                    '  complex;\n'
                    '\n'
                    '* otherwise, if either argument is a floating point number, '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                    'the other\n'
                    '  is converted to floating point;\n'
    
                    '\n'
                    '* otherwise, both must be integers and no conversion is '
                    'necessary.\n'
                    '\n'
                    'Some additional rules apply for certain operators (e.g., a '
                    'string as a\n'
    
                    'left argument to the ‘%’ operator).  Extensions must define '
    
                    'their own\n'
                    'conversion behavior.\n',
    
     'customization': 'Basic customization\n'
    
                      '*******************\n'
                      '\n'
                      'object.__new__(cls[, ...])\n'
                      '\n'
                      '   Called to create a new instance of class *cls*.  '
                      '"__new__()" is a\n'
                      '   static method (special-cased so you need not declare it '
                      'as such)\n'
                      '   that takes the class of which an instance was requested '
                      'as its\n'
                      '   first argument.  The remaining arguments are those '
                      'passed to the\n'
                      '   object constructor expression (the call to the class).  '
                      'The return\n'
                      '   value of "__new__()" should be the new object instance '
                      '(usually an\n'
                      '   instance of *cls*).\n'
                      '\n'
                      '   Typical implementations create a new instance of the '
                      'class by\n'
    
                      '   invoking the superclass’s "__new__()" method using\n'
    
                      '   "super().__new__(cls[, ...])" with appropriate arguments '
                      'and then\n'
                      '   modifying the newly-created instance as necessary before '
                      'returning\n'
                      '   it.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   If "__new__()" is invoked during object construction and '
                      'it returns\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   an instance of *cls*, then the new instance’s '
                      '"__init__()" method\n'
                      '   will be invoked like "__init__(self[, ...])", where '
                      '*self* is the\n'
                      '   new instance and the remaining arguments are the same as '
                      'were\n'
                      '   passed to the object constructor.\n'
    
                      '\n'
                      '   If "__new__()" does not return an instance of *cls*, '
                      'then the new\n'
    
                      '   instance’s "__init__()" method will not be invoked.\n'
    
                      '\n'
                      '   "__new__()" is intended mainly to allow subclasses of '
                      'immutable\n'
                      '   types (like int, str, or tuple) to customize instance '
                      'creation.  It\n'
                      '   is also commonly overridden in custom metaclasses in '
                      'order to\n'
                      '   customize class creation.\n'
                      '\n'
                      'object.__init__(self[, ...])\n'
                      '\n'
                      '   Called after the instance has been created (by '
                      '"__new__()"), but\n'
                      '   before it is returned to the caller.  The arguments are '
                      'those\n'
                      '   passed to the class constructor expression.  If a base '
                      'class has an\n'
    
                      '   "__init__()" method, the derived class’s "__init__()" '
    
                      'method, if\n'
                      '   any, must explicitly call it to ensure proper '
                      'initialization of the\n'
                      '   base class part of the instance; for example:\n'
    
                      '   "super().__init__([args...])".\n'
    
                      '\n'
                      '   Because "__new__()" and "__init__()" work together in '
                      'constructing\n'
                      '   objects ("__new__()" to create it, and "__init__()" to '
    
                      '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'
                      '\n'
                      'object.__del__(self)\n'
                      '\n'
                      '   Called when the instance is about to be destroyed.  This '
                      'is also\n'
    
    Ned Deily's avatar
    Ned Deily committed
                      '   called a finalizer or (improperly) a destructor.  If a '
                      'base class\n'
    
                      '   has a "__del__()" method, the derived class’s '
    
    Ned Deily's avatar
    Ned Deily committed
                      '"__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'
    
    Ned Deily's avatar
    Ned Deily committed
                      '   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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   Note:\n'
                      '\n'
                      '     "del x" doesn’t directly call "x.__del__()" — the '
    
                      '     decrements the reference count for "x" by one, and the '
                      'latter is\n'
    
                      '     only called when "x"’s reference count reaches zero.\n'
    
    Ned Deily's avatar
    Ned Deily committed
                      '\n'
                      '   **CPython implementation detail:** It is possible for a '
    
                      'reference\n'
    
    Ned Deily's avatar
    Ned Deily committed
                      '   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 '
    
    Ned Deily's avatar
    Ned Deily committed
                      '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'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   Warning:\n'
                      '\n'
                      '     Due to the precarious circumstances under which '
                      '"__del__()"\n'
                      '     methods are invoked, exceptions that occur during '
                      'their execution\n'
                      '     are ignored, and a warning is printed to "sys.stderr" '
                      'instead.\n'
                      '     In particular:\n'
    
    Ned Deily's avatar
    Ned Deily committed
                      '\n'
                      '     * "__del__()" can be invoked when arbitrary code is '
                      'being\n'
                      '       executed, including from any arbitrary thread.  If '
    
                      '"__del__()"\n'
    
    Ned Deily's avatar
    Ned Deily committed
                      '       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 '
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      'shutdown.  As a\n'
                      '       consequence, the global variables it needs to access '
                      '(including\n'
                      '       other modules) may already have been deleted or set '
                      'to "None".\n'
                      '       Python guarantees that globals whose name begins '
                      'with a single\n'
                      '       underscore are deleted from their module before '
                      'other globals\n'
                      '       are deleted; if no other references to such globals '
                      'exist, this\n'
                      '       may help in assuring that imported modules are still '
                      'available\n'
                      '       at the time when the "__del__()" method is called.\n'
    
                      '\n'
                      'object.__repr__(self)\n'
                      '\n'
                      '   Called by the "repr()" built-in function to compute the '
    
                      '“official”\n'
    
                      '   string representation of an object.  If at all possible, '
                      'this\n'
                      '   should look like a valid Python expression that could be '
                      'used to\n'
                      '   recreate an object with the same value (given an '
                      'appropriate\n'
                      '   environment).  If this is not possible, a string of the '
                      'form\n'
                      '   "<...some useful description...>" should be returned. '
                      'The return\n'
                      '   value must be a string object. If a class defines '
                      '"__repr__()" but\n'
                      '   not "__str__()", then "__repr__()" is also used when an '
    
                      '“informal”\n'
    
                      '   string representation of instances of that class is '
                      'required.\n'
                      '\n'
                      '   This is typically used for debugging, so it is important '
                      'that the\n'
                      '   representation is information-rich and unambiguous.\n'
                      '\n'
                      'object.__str__(self)\n'
                      '\n'
                      '   Called by "str(object)" and the built-in functions '
                      '"format()" and\n'
    
                      '   "print()" to compute the “informal” or nicely printable '
    
                      'string\n'
                      '   representation of an object.  The return value must be a '
                      'string\n'
                      '   object.\n'
                      '\n'
                      '   This method differs from "object.__repr__()" in that '
                      'there is no\n'
                      '   expectation that "__str__()" return a valid Python '
                      'expression: a\n'
                      '   more convenient or concise representation can be used.\n'
                      '\n'
                      '   The default implementation defined by the built-in type '
                      '"object"\n'
                      '   calls "object.__repr__()".\n'
                      '\n'
                      'object.__bytes__(self)\n'
                      '\n'
    
                      '   Called by bytes to compute a byte-string representation '
                      'of an\n'
    
                      '   object. This should return a "bytes" object.\n'
                      '\n'
                      'object.__format__(self, format_spec)\n'
                      '\n'
                      '   Called by the "format()" built-in function, and by '
                      'extension,\n'
                      '   evaluation of formatted string literals and the '
                      '"str.format()"\n'
    
                      '   method, to produce a “formatted” string representation '
    
                      'of an\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   object. The *format_spec* argument is a string that '
    
                      'contains a\n'
                      '   description of the formatting options desired. The '
                      'interpretation\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   of the *format_spec* argument is up to the type '
    
                      'implementing\n'
                      '   "__format__()", however most classes will either '
                      'delegate\n'
                      '   formatting to one of the built-in types, or use a '
                      'similar\n'
                      '   formatting option syntax.\n'
                      '\n'
                      '   See Format Specification Mini-Language for a description '
                      'of the\n'
                      '   standard formatting syntax.\n'
                      '\n'
                      '   The return value must be a string object.\n'
                      '\n'
                      '   Changed in version 3.4: The __format__ method of '
                      '"object" itself\n'
                      '   raises a "TypeError" if passed any non-empty string.\n'
                      '\n'
    
                      '   Changed in version 3.7: "object.__format__(x, \'\')" is '
                      'now\n'
                      '   equivalent to "str(x)" rather than "format(str(self), '
                      '\'\')".\n'
                      '\n'
    
                      'object.__lt__(self, other)\n'
                      'object.__le__(self, other)\n'
                      'object.__eq__(self, other)\n'
                      'object.__ne__(self, other)\n'
                      'object.__gt__(self, other)\n'
                      'object.__ge__(self, other)\n'
                      '\n'
    
                      '   These are the so-called “rich comparison” methods. The\n'
    
                      '   correspondence between operator symbols and method names '
                      'is as\n'
                      '   follows: "x<y" calls "x.__lt__(y)", "x<=y" calls '
                      '"x.__le__(y)",\n'
                      '   "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", '
                      '"x>y" calls\n'
                      '   "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n'
                      '\n'
                      '   A rich comparison method may return the singleton '
                      '"NotImplemented"\n'
                      '   if it does not implement the operation for a given pair '
                      'of\n'
                      '   arguments. By convention, "False" and "True" are '
                      'returned for a\n'
                      '   successful comparison. However, these methods can return '
                      'any value,\n'
                      '   so if the comparison operator is used in a Boolean '
                      'context (e.g.,\n'
                      '   in the condition of an "if" statement), Python will call '
                      '"bool()"\n'
                      '   on the value to determine if the result is true or '
                      'false.\n'
                      '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   By default, "object" implements "__eq__()" by using '
                      '"is", returning\n'
                      '   "NotImplemented" in the case of a false comparison: '
                      '"True if x is y\n'
                      '   else NotImplemented". For "__ne__()", by default it '
                      'delegates to\n'
                      '   "__eq__()" and inverts the result unless it is '
                      '"NotImplemented".\n'
                      '   There are no other implied relationships among the '
                      'comparison\n'
                      '   operators or default implementations; for example, the '
                      'truth of\n'
                      '   "(x<y or x==y)" does not imply "x<=y". To automatically '
                      'generate\n'
                      '   ordering operations from a single root operation, see\n'
    
                      '   "functools.total_ordering()".\n'
                      '\n'
                      '   See the paragraph on "__hash__()" for some important '
                      'notes on\n'
                      '   creating *hashable* objects which support custom '
                      'comparison\n'
                      '   operations and are usable as dictionary keys.\n'
                      '\n'
                      '   There are no swapped-argument versions of these methods '
                      '(to be used\n'
                      '   when the left argument does not support the operation '
                      'but the right\n'
                      '   argument does); rather, "__lt__()" and "__gt__()" are '
    
                      'each other’s\n'
                      '   reflection, "__le__()" and "__ge__()" are each other’s '
    
                      'reflection,\n'
                      '   and "__eq__()" and "__ne__()" are their own reflection. '
                      'If the\n'
    
                      '   operands are of different types, and right operand’s '
    
                      'type is a\n'
    
                      '   direct or indirect subclass of the left operand’s type, '
    
                      'the\n'
                      '   reflected method of the right operand has priority, '
                      'otherwise the\n'
    
                      '   left operand’s method has priority.  Virtual subclassing '
    
                      'is not\n'
                      '   considered.\n'
                      '\n'
                      'object.__hash__(self)\n'
                      '\n'
                      '   Called by built-in function "hash()" and for operations '
                      'on members\n'
                      '   of hashed collections including "set", "frozenset", and '
                      '"dict".\n'
    
                      '   "__hash__()" should return an integer. The only required '
                      'property\n'
    
                      '   is that objects which compare equal have the same hash '
                      'value; it is\n'
    
                      '   advised to mix together the hash values of the '
                      'components of the\n'
                      '   object that also play a part in comparison of objects by '
                      'packing\n'
                      '   them into a tuple and hashing the tuple. Example:\n'
                      '\n'
                      '      def __hash__(self):\n'
                      '          return hash((self.name, self.nick, self.color))\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   Note:\n'
                      '\n'
                      '     "hash()" truncates the value returned from an object’s '
                      'custom\n'
                      '     "__hash__()" method to the size of a "Py_ssize_t".  '
                      'This is\n'
                      '     typically 8 bytes on 64-bit builds and 4 bytes on '
                      '32-bit builds.\n'
                      '     If an object’s   "__hash__()" must interoperate on '
                      'builds of\n'
                      '     different bit sizes, be sure to check the width on all '
                      'supported\n'
                      '     builds.  An easy way to do this is with "python -c '
                      '"import sys;\n'
                      '     print(sys.hash_info.width)"".\n'
    
                      '\n'
                      '   If a class does not define an "__eq__()" method it '
                      'should not\n'
                      '   define a "__hash__()" operation either; if it defines '
                      '"__eq__()"\n'
                      '   but not "__hash__()", its instances will not be usable '
                      'as items in\n'
                      '   hashable collections.  If a class defines mutable '
                      'objects and\n'
                      '   implements an "__eq__()" method, it should not '
                      'implement\n'
                      '   "__hash__()", since the implementation of hashable '
                      'collections\n'
    
                      '   requires that a key’s hash value is immutable (if the '
                      'object’s hash\n'
    
                      '   value changes, it will be in the wrong hash bucket).\n'
                      '\n'
                      '   User-defined classes have "__eq__()" and "__hash__()" '
                      'methods by\n'
                      '   default; with them, all objects compare unequal (except '
                      'with\n'
                      '   themselves) and "x.__hash__()" returns an appropriate '
                      'value such\n'
                      '   that "x == y" implies both that "x is y" and "hash(x) == '
                      'hash(y)".\n'
                      '\n'
                      '   A class that overrides "__eq__()" and does not define '
                      '"__hash__()"\n'
                      '   will have its "__hash__()" implicitly set to "None".  '
                      'When the\n'
                      '   "__hash__()" method of a class is "None", instances of '
                      'the class\n'
                      '   will raise an appropriate "TypeError" when a program '
                      'attempts to\n'
                      '   retrieve their hash value, and will also be correctly '
                      'identified as\n'
    
                      '   unhashable when checking "isinstance(obj,\n'
                      '   collections.abc.Hashable)".\n'
    
                      '\n'
                      '   If a class that overrides "__eq__()" needs to retain '
                      'the\n'
                      '   implementation of "__hash__()" from a parent class, the '
                      'interpreter\n'
                      '   must be told this explicitly by setting "__hash__ =\n'
                      '   <ParentClass>.__hash__".\n'
                      '\n'
                      '   If a class that does not override "__eq__()" wishes to '
                      'suppress\n'
                      '   hash support, it should include "__hash__ = None" in the '
                      'class\n'
                      '   definition. A class which defines its own "__hash__()" '
                      'that\n'
                      '   explicitly raises a "TypeError" would be incorrectly '
                      'identified as\n'
    
                      '   hashable by an "isinstance(obj, '
                      'collections.abc.Hashable)" call.\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                      '   Note:\n'
                      '\n'
                      '     By default, the "__hash__()" values of str and bytes '
                      'objects are\n'
                      '     “salted” with an unpredictable random value.  Although '
                      'they\n'
                      '     remain constant within an individual Python process, '
                      'they are not\n'
                      '     predictable between repeated invocations of '
                      'Python.This is\n'
                      '     intended to provide protection against a '
                      'denial-of-service caused\n'
                      '     by carefully-chosen inputs that exploit the worst '
                      'case\n'
                      '     performance of a dict insertion, O(n^2) complexity.  '
                      'See\n'
                      '     http://www.ocert.org/advisories/ocert-2011-003.html '
                      'for\n'
    
                      '     details.Changing hash values affects the iteration '
    
                      'order of sets.\n'
                      '     Python has never made guarantees about this ordering '
                      '(and it\n'
                      '     typically varies between 32-bit and 64-bit builds).See '
                      'also\n'
                      '     "PYTHONHASHSEED".\n'
    
                      '\n'
                      '   Changed in version 3.3: Hash randomization is enabled by '
                      'default.\n'
                      '\n'
                      'object.__bool__(self)\n'
                      '\n'
                      '   Called to implement truth value testing and the built-in '
                      'operation\n'
                      '   "bool()"; should return "False" or "True".  When this '
                      'method is not\n'
                      '   defined, "__len__()" is called, if it is defined, and '
                      'the object is\n'
                      '   considered true if its result is nonzero.  If a class '
                      'defines\n'
                      '   neither "__len__()" nor "__bool__()", all its instances '
                      'are\n'
                      '   considered true.\n',
    
     'debugger': '"pdb" — The Python Debugger\n'
                 '***************************\n'
    
                 '\n'
                 '**Source code:** Lib/pdb.py\n'
                 '\n'
                 '======================================================================\n'
                 '\n'
                 'The module "pdb" defines an interactive source code debugger '
                 'for\n'
                 'Python programs.  It supports setting (conditional) breakpoints '
                 'and\n'
                 'single stepping at the source line level, inspection of stack '
                 'frames,\n'
                 'source code listing, and evaluation of arbitrary Python code in '
                 'the\n'
                 'context of any stack frame.  It also supports post-mortem '
                 'debugging\n'
                 'and can be called under program control.\n'
                 '\n'
    
                 'The debugger is extensible – it is actually defined as the '
    
                 'class\n'
                 '"Pdb". This is currently undocumented but easily understood by '
                 'reading\n'
                 'the source.  The extension interface uses the modules "bdb" and '
                 '"cmd".\n'
                 '\n'
    
                 'The debugger’s prompt is "(Pdb)". Typical usage to run a program '
                 'under\n'
    
                 'control of the debugger is:\n'
                 '\n'
                 '   >>> import pdb\n'
                 '   >>> import mymodule\n'
                 "   >>> pdb.run('mymodule.test()')\n"
                 '   > <string>(0)?()\n'
                 '   (Pdb) continue\n'
                 '   > <string>(1)?()\n'
                 '   (Pdb) continue\n'
                 "   NameError: 'spam'\n"
                 '   > <string>(1)?()\n'
                 '   (Pdb)\n'
                 '\n'
                 'Changed in version 3.3: Tab-completion via the "readline" module '
                 'is\n'
                 'available for commands and command arguments, e.g. the current '
                 'global\n'
                 'and local names are offered as arguments of the "p" command.\n'
                 '\n'
                 '"pdb.py" can also be invoked as a script to debug other '
                 'scripts.  For\n'
                 'example:\n'
                 '\n'
                 '   python3 -m pdb myscript.py\n'
                 '\n'
                 'When invoked as a script, pdb will automatically enter '
                 'post-mortem\n'
                 'debugging if the program being debugged exits abnormally.  After '
                 'post-\n'
                 'mortem debugging (or after normal exit of the program), pdb '
                 'will\n'
    
                 'restart the program.  Automatic restarting preserves pdb’s state '
    
                 '(such\n'
                 'as breakpoints) and in most cases is more useful than quitting '
                 'the\n'
    
                 'debugger upon program’s exit.\n'
    
                 '\n'
                 'New in version 3.2: "pdb.py" now accepts a "-c" option that '
                 'executes\n'
                 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n'
                 '\n'
    
    Ned Deily's avatar
    Ned Deily committed
                 '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'
                 '\n'
                 '   import pdb; pdb.set_trace()\n'
                 '\n'
                 'at the location you want to break into the debugger.  You can '
                 'then\n'
                 'step through the code following this statement, and continue '
                 'running\n'
                 'without the debugger using the "continue" command.\n'
                 '\n'
    
                 'New in version 3.7: The built-in "breakpoint()", when called '
                 'with\n'
                 'defaults, can be used instead of "import pdb; pdb.set_trace()".\n'
                 '\n'
    
                 'The typical usage to inspect a crashed program is:\n'
                 '\n'
                 '   >>> import pdb\n'
                 '   >>> import mymodule\n'
                 '   >>> mymodule.test()\n'
                 '   Traceback (most recent call last):\n'
    
                 '     File "<stdin>", line 1, in <module>\n'
    
                 '     File "./mymodule.py", line 4, in test\n'
                 '       test2()\n'
                 '     File "./mymodule.py", line 3, in test2\n'
                 '       print(spam)\n'
                 '   NameError: spam\n'
                 '   >>> pdb.pm()\n'
                 '   > ./mymodule.py(3)test2()\n'
                 '   -> print(spam)\n'
                 '   (Pdb)\n'
                 '\n'
                 'The module defines the following functions; each enters the '
                 'debugger\n'
                 'in a slightly different way:\n'
                 '\n'
                 'pdb.run(statement, globals=None, locals=None)\n'
                 '\n'
                 '   Execute the *statement* (given as a string or a code object) '
                 'under\n'
                 '   debugger control.  The debugger prompt appears before any '
                 'code is\n'
                 '   executed; you can set breakpoints and type "continue", or you '
                 'can\n'
                 '   step through the statement using "step" or "next" (all these\n'
                 '   commands are explained below).  The optional *globals* and '
                 '*locals*\n'
                 '   arguments specify the environment in which the code is '
                 'executed; by\n'
                 '   default the dictionary of the module "__main__" is used.  '
                 '(See the\n'
                 '   explanation of the built-in "exec()" or "eval()" functions.)\n'
                 '\n'
                 'pdb.runeval(expression, globals=None, locals=None)\n'
                 '\n'
                 '   Evaluate the *expression* (given as a string or a code '
                 'object)\n'
                 '   under debugger control.  When "runeval()" returns, it returns '
                 'the\n'
                 '   value of the expression.  Otherwise this function is similar '
                 'to\n'
                 '   "run()".\n'
                 '\n'
                 'pdb.runcall(function, *args, **kwds)\n'
                 '\n'
                 '   Call the *function* (a function or method object, not a '
                 'string)\n'
                 '   with the given arguments.  When "runcall()" returns, it '
                 'returns\n'
                 '   whatever the function call returned.  The debugger prompt '
                 'appears\n'
                 '   as soon as the function is entered.\n'
                 '\n'
    
                 'pdb.set_trace(*, header=None)\n'
    
                 '\n'
                 '   Enter the debugger at the calling stack frame.  This is '
                 'useful to\n'
                 '   hard-code a breakpoint at a given point in a program, even if '
                 'the\n'
                 '   code is not otherwise being debugged (e.g. when an assertion\n'
    
                 '   fails).  If given, *header* is printed to the console just '
    
                 'before\n'
                 '   debugging begins.\n'
                 '\n'
    
                 '   Changed in version 3.7: The keyword-only argument *header*.\n'
    
                 '\n'
                 'pdb.post_mortem(traceback=None)\n'
                 '\n'
                 '   Enter post-mortem debugging of the given *traceback* object.  '
                 'If no\n'
                 '   *traceback* is given, it uses the one of the exception that '
                 'is\n'
                 '   currently being handled (an exception must be being handled '
                 'if the\n'
                 '   default is to be used).\n'
                 '\n'
                 'pdb.pm()\n'
                 '\n'
                 '   Enter post-mortem debugging of the traceback found in\n'
                 '   "sys.last_traceback".\n'
                 '\n'
                 'The "run*" functions and "set_trace()" are aliases for '
                 'instantiating\n'
                 'the "Pdb" class and calling the method of the same name.  If you '
                 'want\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, readrc=True)\n'
    
                 '\n'
                 '   "Pdb" is the debugger class.\n'
                 '\n'
                 '   The *completekey*, *stdin* and *stdout* arguments are passed '
                 'to the\n'
                 '   underlying "cmd.Cmd" class; see the description there.\n'
                 '\n'
                 '   The *skip* argument, if given, must be an iterable of '
                 'glob-style\n'
                 '   module name patterns.  The debugger will not step into frames '
                 'that\n'
                 '   originate in a module that matches one of these patterns. '
                 '[1]\n'
                 '\n'
                 '   By default, Pdb sets a handler for the SIGINT signal (which '
                 'is sent\n'
                 '   when the user presses "Ctrl-C" on the console) when you give '
                 'a\n'
                 '   "continue" command. This allows you to break into the '
                 'debugger\n'
                 '   again by pressing "Ctrl-C".  If you want Pdb not to touch '
                 'the\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'
                 "      import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n"
                 '\n'
    
    Łukasz Langa's avatar
    Łukasz Langa committed
                 '   Raises an auditing event "pdb.Pdb" with no arguments.\n'
                 '\n'
    
                 '   New in version 3.1: The *skip* argument.\n'
                 '\n'
                 '   New in version 3.2: The *nosigint* argument.  Previously, a '
                 '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'
                 '   set_trace()\n'
                 '\n'
                 '      See the documentation for the functions explained above.\n'
                 '\n'
                 '\n'
                 'Debugger Commands\n'
                 '=================\n'
                 '\n'
                 'The commands recognized by the debugger are listed below.  Most\n'
                 'commands can be abbreviated to one or two letters as indicated; '
                 'e.g.\n'
                 '"h(elp)" means that either "h" or "help" can be used to enter '
                 'the help\n'
                 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n'
                 'Arguments to commands must be separated by whitespace (spaces '
                 'or\n'
                 'tabs).  Optional arguments are enclosed in square brackets '
                 '("[]") in\n'
                 'the command syntax; the square brackets must not be typed.\n'
                 'Alternatives in the command syntax are separated by a vertical '
                 'bar\n'
                 '("|").\n'
                 '\n'
                 'Entering a blank line repeats the last command entered.  '
                 'Exception: if\n'
                 'the last command was a "list" command, the next 11 lines are '
                 'listed.\n'
                 '\n'
    
                 'Commands that the debugger doesn’t recognize are assumed to be '
    
                 'Python\n'
                 'statements and are executed in the context of the program being\n'
                 'debugged.  Python statements can also be prefixed with an '
                 'exclamation\n'
                 'point ("!").  This is a powerful way to inspect the program '
                 'being\n'
                 'debugged; it is even possible to change a variable or call a '
                 'function.\n'
                 'When an exception occurs in such a statement, the exception name '
                 'is\n'
    
                 'printed but the debugger’s state is not changed.\n'
    
                 '\n'
                 'The debugger supports aliases.  Aliases can have parameters '
                 'which\n'
                 'allows one a certain level of adaptability to the context under\n'
                 'examination.\n'
                 '\n'
                 'Multiple commands may be entered on a single line, separated by '
                 '";;".\n'
                 '(A single ";" is not used as it is the separator for multiple '
                 'commands\n'
                 'in a line that is passed to the Python parser.)  No intelligence '
                 'is\n'
                 'applied to separating the commands; the input is split at the '
                 'first\n'
                 '";;" pair, even if it is in the middle of a quoted string.\n'
                 '\n'
    
                 'If a file ".pdbrc" exists in the user’s home directory or in '
    
                 'the\n'
                 'current directory, it is read in and executed as if it had been '
                 'typed\n'
                 'at the debugger prompt.  This is particularly useful for '
                 'aliases.  If\n'
                 'both files exist, the one in the home directory is read first '
                 'and\n'
                 'aliases defined there can be overridden by the local file.\n'
                 '\n'
                 'Changed in version 3.2: ".pdbrc" can now contain commands that\n'
                 'continue debugging, such as "continue" or "next".  Previously, '
                 'these\n'
                 'commands had no effect.\n'
                 '\n'
                 'h(elp) [command]\n'
                 '\n'
                 '   Without argument, print the list of available commands.  With '
                 'a\n'
                 '   *command* as argument, print help about that command.  "help '
                 'pdb"\n'
                 '   displays the full documentation (the docstring of the "pdb"\n'
                 '   module).  Since the *command* argument must be an identifier, '
                 '"help\n'
                 '   exec" must be entered to get help on the "!" command.\n'
                 '\n'
                 'w(here)\n'
                 '\n'
                 '   Print a stack trace, with the most recent frame at the '
                 'bottom.  An\n'
                 '   arrow indicates the current frame, which determines the '
                 'context of\n'
                 '   most commands.\n'
                 '\n'
                 'd(own) [count]\n'
                 '\n'
                 '   Move the current frame *count* (default one) levels down in '
                 'the\n'
                 '   stack trace (to a newer frame).\n'
                 '\n'
                 'u(p) [count]\n'
                 '\n'
                 '   Move the current frame *count* (default one) levels up in the '
                 'stack\n'
                 '   trace (to an older frame).\n'
                 '\n'
                 'b(reak) [([filename:]lineno | function) [, condition]]\n'
                 '\n'
                 '   With a *lineno* argument, set a break there in the current '
                 'file.\n'
                 '   With a *function* argument, set a break at the first '
                 'executable\n'
                 '   statement within that function.  The line number may be '
                 'prefixed\n'
                 '   with a filename and a colon, to specify a breakpoint in '
                 'another\n'
    
                 '   file (probably one that hasn’t been loaded yet).  The file '
    
                 'is\n'
                 '   searched on "sys.path".  Note that each breakpoint is '
                 'assigned a\n'
                 '   number to which all the other breakpoint commands refer.\n'
                 '\n'