Spade
Mini Shell
| Directory:~$ /proc/self/root/lib64/python3.6/pydoc_data/ |
| [Home] [System Details] [Kill Me] |
# -*- coding: utf-8 -*-
# Autogenerated by Sphinx on Sun Dec 23 16:24:21 2018
topics = {'assert': 'The "assert"
statement\n'
'**********************\n'
'\n'
'Assert statements are a convenient way to insert debugging
'
'assertions\n'
'into a program:\n'
'\n'
' assert_stmt ::= "assert" expression
["," expression]\n'
'\n'
'The simple form, "assert expression", is
equivalent to\n'
'\n'
' if __debug__:\n'
' if not expression: raise AssertionError\n'
'\n'
'The extended form, "assert expression1,
expression2", is '
'equivalent to\n'
'\n'
' if __debug__:\n'
' if not expression1: raise
AssertionError(expression2)\n'
'\n'
'These equivalences assume that "__debug__" and
"AssertionError" '
'refer\n'
'to the built-in variables with those names. In the
current\n'
'implementation, the built-in variable
"__debug__" is "True" under\n'
'normal circumstances, "False" when optimization
is requested '
'(command\n'
'line option "-O"). The current code generator
emits no code for '
'an\n'
'assert statement when optimization is requested at compile
time. '
'Note\n'
'that it is unnecessary to include the source code for the
'
'expression\n'
'that failed in the error message; it will be displayed as
part of '
'the\n'
'stack trace.\n'
'\n'
'Assignments to "__debug__" are illegal. The
value for the '
'built-in\n'
'variable is determined when the interpreter
starts.\n',
'assignment': 'Assignment statements\n'
'*********************\n'
'\n'
'Assignment statements are used to (re)bind names to
values and '
'to\n'
'modify attributes or items of mutable objects:\n'
'\n'
' assignment_stmt ::= (target_list "=")+
(starred_expression '
'| yield_expression)\n'
' target_list ::= target ("," target)*
[","]\n'
' target ::= identifier\n'
' | "(" [target_list]
")"\n'
' | "[" [target_list]
"]"\n'
' | attributeref\n'
' | subscription\n'
' | slicing\n'
' | "*" target\n'
'\n'
'(See section Primaries for the syntax definitions for
'
'*attributeref*,\n'
'*subscription*, and *slicing*.)\n'
'\n'
'An assignment statement evaluates the expression list
'
'(remember that\n'
'this can be a single expression or a comma-separated
list, the '
'latter\n'
'yielding a tuple) and assigns the single resulting
object to '
'each of\n'
'the target lists, from left to right.\n'
'\n'
'Assignment is defined recursively depending on the
form of the '
'target\n'
'(list). When a target is part of a mutable object (an
'
'attribute\n'
'reference, subscription or slicing), the mutable
object must\n'
'ultimately perform the assignment and decide about its
'
'validity, and\n'
'may raise an exception if the assignment is
unacceptable. The '
'rules\n'
'observed by various types and the exceptions raised
are given '
'with the\n'
'definition of the object types (see section The
standard type\n'
'hierarchy).\n'
'\n'
'Assignment of an object to a target list, optionally
enclosed '
'in\n'
'parentheses or square brackets, is recursively defined
as '
'follows.\n'
'\n'
'* If the target list is a single target with no
trailing '
'comma,\n'
' optionally in parentheses, the object is assigned to
that '
'target.\n'
'\n'
'* Else: The object must be an iterable with the same
number of '
'items\n'
' as there are targets in the target list, and the
items are '
'assigned,\n'
' from left to right, to the corresponding
targets.\n'
'\n'
' * If the target list contains one target prefixed
with an\n'
' asterisk, called a “starred” target: The
object must be '
'an\n'
' iterable with at least as many items as there are
targets '
'in the\n'
' target list, minus one. The first items of the
iterable '
'are\n'
' assigned, from left to right, to the targets
before the '
'starred\n'
' target. The final items of the iterable are
assigned to '
'the\n'
' targets after the starred target. A list of the
remaining '
'items\n'
' in the iterable is then assigned to the starred
target '
'(the list\n'
' can be empty).\n'
'\n'
' * Else: The object must be an iterable with the same
number '
'of\n'
' items as there are targets in the target list, and
the '
'items are\n'
' assigned, from left to right, to the corresponding
'
'targets.\n'
'\n'
'Assignment of an object to a single target is
recursively '
'defined as\n'
'follows.\n'
'\n'
'* If the target is an identifier (name):\n'
'\n'
' * If the name does not occur in a "global"
or "nonlocal" '
'statement\n'
' in the current code block: the name is bound to
the object '
'in the\n'
' current local namespace.\n'
'\n'
' * Otherwise: the name is bound to the object in the
global\n'
' namespace or the outer namespace determined by
'
'"nonlocal",\n'
' respectively.\n'
'\n'
' The name is rebound if it was already bound. This
may cause '
'the\n'
' reference count for the object previously bound to
the name '
'to reach\n'
' zero, causing the object to be deallocated and its
'
'destructor (if it\n'
' has one) to be called.\n'
'\n'
'* If the target is an attribute reference: The primary
'
'expression in\n'
' the reference is evaluated. It should yield an
object with\n'
' assignable attributes; if this is not the case,
"TypeError" '
'is\n'
' raised. That object is then asked to assign the
assigned '
'object to\n'
' the given attribute; if it cannot perform the
assignment, it '
'raises\n'
' an exception (usually but not necessarily '
'"AttributeError").\n'
'\n'
' Note: If the object is a class instance and the
attribute '
'reference\n'
' occurs on both sides of the assignment operator, the
RHS '
'expression,\n'
' "a.x" can access either an instance
attribute or (if no '
'instance\n'
' attribute exists) a class attribute. The LHS target
"a.x" '
'is always\n'
' set as an instance attribute, creating it if
necessary. '
'Thus, the\n'
' two occurrences of "a.x" do not
necessarily refer to the '
'same\n'
' attribute: if the RHS expression refers to a class
'
'attribute, the\n'
' LHS creates a new instance attribute as the target
of the\n'
' assignment:\n'
'\n'
' class Cls:\n'
' x = 3 # class variable\n'
' inst = Cls()\n'
' inst.x = inst.x + 1 # writes inst.x as 4
leaving Cls.x '
'as 3\n'
'\n'
' This description does not necessarily apply to
descriptor\n'
' attributes, such as properties created with
"property()".\n'
'\n'
'* If the target is a subscription: The primary
expression in '
'the\n'
' reference is evaluated. It should yield either a
mutable '
'sequence\n'
' object (such as a list) or a mapping object (such as
a '
'dictionary).\n'
' Next, the subscript expression is evaluated.\n'
'\n'
' If the primary is a mutable sequence object (such as
a '
'list), the\n'
' subscript must yield an integer. If it is negative,
the '
'sequence’s\n'
' length is added to it. The resulting value must be
a '
'nonnegative\n'
' integer less than the sequence’s length, and the
sequence is '
'asked\n'
' to assign the assigned object to its item with that
index. '
'If the\n'
' index is out of range, "IndexError" is
raised (assignment to '
'a\n'
' subscripted sequence cannot add new items to a
list).\n'
'\n'
' If the primary is a mapping object (such as a
dictionary), '
'the\n'
' subscript must have a type compatible with the
mapping’s key '
'type,\n'
' and the mapping is then asked to create a key/datum
pair '
'which maps\n'
' the subscript to the assigned object. This can
either '
'replace an\n'
' existing key/value pair with the same key value, or
insert a '
'new\n'
' key/value pair (if no key with the same value
existed).\n'
'\n'
' For user-defined objects, the
"__setitem__()" method is '
'called with\n'
' appropriate arguments.\n'
'\n'
'* If the target is a slicing: The primary expression
in the\n'
' reference is evaluated. It should yield a mutable
sequence '
'object\n'
' (such as a list). The assigned object should be a
sequence '
'object\n'
' of the same type. Next, the lower and upper bound
'
'expressions are\n'
' evaluated, insofar they are present; defaults are
zero and '
'the\n'
' sequence’s length. The bounds should evaluate to
integers. '
'If\n'
' either bound is negative, the sequence’s length is
added to '
'it. The\n'
' resulting bounds are clipped to lie between zero and
the '
'sequence’s\n'
' length, inclusive. Finally, the sequence object is
asked to '
'replace\n'
' the slice with the items of the assigned sequence.
The '
'length of\n'
' the slice may be different from the length of the
assigned '
'sequence,\n'
' thus changing the length of the target sequence, if
the '
'target\n'
' sequence allows it.\n'
'\n'
'**CPython implementation detail:** In the current
'
'implementation, the\n'
'syntax for targets is taken to be the same as for
expressions, '
'and\n'
'invalid syntax is rejected during the code generation
phase, '
'causing\n'
'less detailed error messages.\n'
'\n'
'Although the definition of assignment implies that
overlaps '
'between\n'
'the left-hand side and the right-hand side are
‘simultaneous’ '
'(for\n'
'example "a, b = b, a" swaps two variables),
overlaps *within* '
'the\n'
'collection of assigned-to variables occur
left-to-right, '
'sometimes\n'
'resulting in confusion. For instance, the following
program '
'prints\n'
'"[0, 2]":\n'
'\n'
' x = [0, 1]\n'
' i = 0\n'
' i, x[i] = 1, 2 # i is updated, then x[i] is
'
'updated\n'
' print(x)\n'
'\n'
'See also:\n'
'\n'
' **PEP 3132** - Extended Iterable Unpacking\n'
' The specification for the "*target"
feature.\n'
'\n'
'\n'
'Augmented assignment statements\n'
'===============================\n'
'\n'
'Augmented assignment is the combination, in a single
'
'statement, of a\n'
'binary operation and an assignment statement:\n'
'\n'
' augmented_assignment_stmt ::= augtarget augop
'
'(expression_list | yield_expression)\n'
' augtarget ::= identifier |
attributeref | '
'subscription | slicing\n'
' augop ::= "+=" |
"-=" | "*=" | "@=" | '
'"/=" | "//=" | "%=" |
"**="\n'
' | ">>=" |
"<<=" | "&=" | "^=" |
"|="\n'
'\n'
'(See section Primaries for the syntax definitions of
the last '
'three\n'
'symbols.)\n'
'\n'
'An augmented assignment evaluates the target (which,
unlike '
'normal\n'
'assignment statements, cannot be an unpacking) and the
'
'expression\n'
'list, performs the binary operation specific to the
type of '
'assignment\n'
'on the two operands, and assigns the result to the
original '
'target.\n'
'The target is only evaluated once.\n'
'\n'
'An augmented assignment expression like "x +=
1" can be '
'rewritten as\n'
'"x = x + 1" to achieve a similar, but not
exactly equal '
'effect. In the\n'
'augmented version, "x" is only evaluated
once. Also, when '
'possible,\n'
'the actual operation is performed *in-place*, meaning
that '
'rather than\n'
'creating a new object and assigning that to the
target, the '
'old object\n'
'is modified instead.\n'
'\n'
'Unlike normal assignments, augmented assignments
evaluate the '
'left-\n'
'hand side *before* evaluating the right-hand side.
For '
'example, "a[i]\n'
'+= f(x)" first looks-up "a[i]", then it
evaluates "f(x)" and '
'performs\n'
'the addition, and lastly, it writes the result back to
'
'"a[i]".\n'
'\n'
'With the exception of assigning to tuples and multiple
targets '
'in a\n'
'single statement, the assignment done by augmented
assignment\n'
'statements is handled the same way as normal
assignments. '
'Similarly,\n'
'with the exception of the possible *in-place*
behavior, the '
'binary\n'
'operation performed by augmented assignment is the
same as the '
'normal\n'
'binary operations.\n'
'\n'
'For targets which are attribute references, the same
caveat '
'about\n'
'class and instance attributes applies as for regular
'
'assignments.\n'
'\n'
'\n'
'Annotated assignment statements\n'
'===============================\n'
'\n'
'Annotation assignment is the combination, in a single
'
'statement, of a\n'
'variable or attribute annotation and an optional
assignment '
'statement:\n'
'\n'
' annotated_assignment_stmt ::= augtarget
":" expression ["=" '
'expression]\n'
'\n'
'The difference from normal Assignment statements is
that only '
'single\n'
'target and only single right hand side value is
allowed.\n'
'\n'
'For simple names as assignment targets, if in class or
module '
'scope,\n'
'the annotations are evaluated and stored in a special
class or '
'module\n'
'attribute "__annotations__" that is a
dictionary mapping from '
'variable\n'
'names (mangled if private) to evaluated annotations.
This '
'attribute is\n'
'writable and is automatically created at the start of
class or '
'module\n'
'body execution, if annotations are found
statically.\n'
'\n'
'For expressions as assignment targets, the annotations
are '
'evaluated\n'
'if in class or module scope, but not stored.\n'
'\n'
'If a name is annotated in a function scope, then this
name is '
'local\n'
'for that scope. Annotations are never evaluated and
stored in '
'function\n'
'scopes.\n'
'\n'
'If the right hand side is present, an annotated
assignment '
'performs\n'
'the actual assignment before evaluating annotations
(where\n'
'applicable). If the right hand side is not present for
an '
'expression\n'
'target, then the interpreter evaluates the target
except for '
'the last\n'
'"__setitem__()" or "__setattr__()"
call.\n'
'\n'
'See also:\n'
'\n'
' **PEP 526** - Syntax for Variable
Annotations\n'
' The proposal that added syntax for annotating the
types '
'of\n'
' variables (including class variables and instance
'
'variables),\n'
' instead of expressing them through
comments.\n'
'\n'
' **PEP 484** - Type hints\n'
' The proposal that added the "typing"
module to provide a '
'standard\n'
' syntax for type annotations that can be used in
static '
'analysis\n'
' tools and IDEs.\n',
'atom-identifiers': 'Identifiers (Names)\n'
'*******************\n'
'\n'
'An identifier occurring as an atom is a name.
See '
'section Identifiers\n'
'and keywords for lexical definition and section
Naming '
'and binding for\n'
'documentation of naming and binding.\n'
'\n'
'When the name is bound to an object, evaluation
of the '
'atom yields\n'
'that object. When a name is not bound, an
attempt to '
'evaluate it\n'
'raises a "NameError"
exception.\n'
'\n'
'**Private name mangling:** When an identifier
that '
'textually occurs in\n'
'a class definition begins with two or more
underscore '
'characters and\n'
'does not end in two or more underscores, it is
'
'considered a *private\n'
'name* of that class. Private names are
transformed to a '
'longer form\n'
'before code is generated for them. The
transformation '
'inserts the\n'
'class name, with leading underscores removed and
a '
'single underscore\n'
'inserted, in front of the name. For example,
the '
'identifier "__spam"\n'
'occurring in a class named "Ham" will
be transformed to '
'"_Ham__spam".\n'
'This transformation is independent of the
syntactical '
'context in which\n'
'the identifier is used. If the transformed name
is '
'extremely long\n'
'(longer than 255 characters), implementation
defined '
'truncation may\n'
'happen. If the class name consists only of
underscores, '
'no\n'
'transformation is done.\n',
'atom-literals': 'Literals\n'
'********\n'
'\n'
'Python supports string and bytes literals and
various '
'numeric\n'
'literals:\n'
'\n'
' literal ::= stringliteral | bytesliteral\n'
' | integer | floatnumber |
imagnumber\n'
'\n'
'Evaluation of a literal yields an object of the
given type '
'(string,\n'
'bytes, integer, floating point number, complex
number) with '
'the given\n'
'value. The value may be approximated in the case
of '
'floating point\n'
'and imaginary (complex) literals. See section
Literals for '
'details.\n'
'\n'
'All literals correspond to immutable data types,
and hence '
'the\n'
'object’s identity is less important than its
value. '
'Multiple\n'
'evaluations of literals with the same value (either
the '
'same\n'
'occurrence in the program text or a different
occurrence) '
'may obtain\n'
'the same object or a different object with the same
'
'value.\n',
'attribute-access': 'Customizing attribute access\n'
'****************************\n'
'\n'
'The following methods can be defined to
customize the '
'meaning of\n'
'attribute access (use of, assignment to, or
deletion of '
'"x.name") for\n'
'class instances.\n'
'\n'
'object.__getattr__(self, name)\n'
'\n'
' Called when the default attribute access
fails with '
'an\n'
' "AttributeError" (either
"__getattribute__()" raises '
'an\n'
' "AttributeError" because *name* is
not an instance '
'attribute or an\n'
' attribute in the class tree for
"self"; or '
'"__get__()" of a *name*\n'
' property raises "AttributeError").
This method '
'should either\n'
' return the (computed) attribute value or
raise an '
'"AttributeError"\n'
' exception.\n'
'\n'
' Note that if the attribute is found through
the '
'normal mechanism,\n'
' "__getattr__()" is not called.
(This is an '
'intentional asymmetry\n'
' between "__getattr__()" and
"__setattr__()".) This is '
'done both for\n'
' efficiency reasons and because otherwise
'
'"__getattr__()" would have\n'
' no way to access other attributes of the
instance. '
'Note that at\n'
' least for instance variables, you can fake
total '
'control by not\n'
' inserting any values in the instance
attribute '
'dictionary (but\n'
' instead inserting them in another object).
See the\n'
' "__getattribute__()" method below
for a way to '
'actually get total\n'
' control over attribute access.\n'
'\n'
'object.__getattribute__(self, name)\n'
'\n'
' Called unconditionally to implement attribute
'
'accesses for\n'
' instances of the class. If the class also
defines '
'"__getattr__()",\n'
' the latter will not be called unless '
'"__getattribute__()" either\n'
' calls it explicitly or raises an
"AttributeError". '
'This method\n'
' should return the (computed) attribute value
or raise '
'an\n'
' "AttributeError" exception. In
order to avoid '
'infinite recursion in\n'
' this method, its implementation should always
call '
'the base class\n'
' method with the same name to access any
attributes it '
'needs, for\n'
' example, "object.__getattribute__(self,
name)".\n'
'\n'
' Note: This method may still be bypassed when
looking '
'up special\n'
' methods as the result of implicit
invocation via '
'language syntax\n'
' or built-in functions. See Special method
lookup.\n'
'\n'
'object.__setattr__(self, name, value)\n'
'\n'
' Called when an attribute assignment is
attempted. '
'This is called\n'
' instead of the normal mechanism (i.e. store
the value '
'in the\n'
' instance dictionary). *name* is the attribute
name, '
'*value* is the\n'
' value to be assigned to it.\n'
'\n'
' If "__setattr__()" wants to assign
to an instance '
'attribute, it\n'
' should call the base class method with the
same name, '
'for example,\n'
' "object.__setattr__(self, name,
value)".\n'
'\n'
'object.__delattr__(self, name)\n'
'\n'
' Like "__setattr__()" but for
attribute deletion '
'instead of\n'
' assignment. This should only be implemented
if "del '
'obj.name" is\n'
' meaningful for the object.\n'
'\n'
'object.__dir__(self)\n'
'\n'
' Called when "dir()" is called on
the object. A '
'sequence must be\n'
' returned. "dir()" converts the
returned sequence to a '
'list and\n'
' sorts it.\n'
'\n'
'\n'
'Customizing module attribute access\n'
'===================================\n'
'\n'
'For a more fine grained customization of the
module '
'behavior (setting\n'
'attributes, properties, etc.), one can set the
'
'"__class__" attribute\n'
'of a module object to a subclass of
"types.ModuleType". '
'For example:\n'
'\n'
' import sys\n'
' from types import ModuleType\n'
'\n'
' class VerboseModule(ModuleType):\n'
' def __repr__(self):\n'
" return f'Verbose
{self.__name__}'\n"
'\n'
' def __setattr__(self, attr,
value):\n'
" print(f'Setting
{attr}...')\n"
' setattr(self, attr, value)\n'
'\n'
' sys.modules[__name__].__class__ =
VerboseModule\n'
'\n'
'Note: Setting module "__class__" only
affects lookups '
'made using the\n'
' attribute access syntax – directly accessing
the '
'module globals\n'
' (whether by code within the module, or via a
reference '
'to the\n'
' module’s globals dictionary) is
unaffected.\n'
'\n'
'Changed in version 3.5: "__class__"
module attribute is '
'now writable.\n'
'\n'
'\n'
'Implementing Descriptors\n'
'========================\n'
'\n'
'The following methods only apply when an
instance of the '
'class\n'
'containing the method (a so-called *descriptor*
class) '
'appears in an\n'
'*owner* class (the descriptor must be in either
the '
'owner’s class\n'
'dictionary or in the class dictionary for one of
its '
'parents). In the\n'
'examples below, “the attribute” refers to
the attribute '
'whose name is\n'
'the key of the property in the owner class’
"__dict__".\n'
'\n'
'object.__get__(self, instance, owner)\n'
'\n'
' Called to get the attribute of the owner
class (class '
'attribute\n'
' access) or of an instance of that class
(instance '
'attribute\n'
' access). *owner* is always the owner class,
while '
'*instance* is the\n'
' instance that the attribute was accessed
through, or '
'"None" when\n'
' the attribute is accessed through the
*owner*. This '
'method should\n'
' return the (computed) attribute value or
raise an '
'"AttributeError"\n'
' exception.\n'
'\n'
'object.__set__(self, instance, value)\n'
'\n'
' Called to set the attribute on an instance
*instance* '
'of the owner\n'
' class to a new value, *value*.\n'
'\n'
'object.__delete__(self, instance)\n'
'\n'
' Called to delete the attribute on an instance
'
'*instance* of the\n'
' owner class.\n'
'\n'
'object.__set_name__(self, owner, name)\n'
'\n'
' Called at the time the owning class *owner*
is '
'created. The\n'
' descriptor has been assigned to
*name*.\n'
'\n'
' New in version 3.6.\n'
'\n'
'The attribute "__objclass__" is
interpreted by the '
'"inspect" module as\n'
'specifying the class where this object was
defined '
'(setting this\n'
'appropriately can assist in runtime
introspection of '
'dynamic class\n'
'attributes). For callables, it may indicate that
an '
'instance of the\n'
'given type (or a subclass) is expected or
required as '
'the first\n'
'positional argument (for example, CPython sets
this '
'attribute for\n'
'unbound methods that are implemented in
C).\n'
'\n'
'\n'
'Invoking Descriptors\n'
'====================\n'
'\n'
'In general, a descriptor is an object attribute
with '
'“binding\n'
'behavior”, one whose attribute access has been
'
'overridden by methods\n'
'in the descriptor protocol:
"__get__()", "__set__()", '
'and\n'
'"__delete__()". If any of those
methods are defined for '
'an object, it\n'
'is said to be a descriptor.\n'
'\n'
'The default behavior for attribute access is to
get, '
'set, or delete\n'
'the attribute from an object’s dictionary. For
instance, '
'"a.x" has a\n'
'lookup chain starting with
"a.__dict__[\'x\']", then\n'
'"type(a).__dict__[\'x\']",
and continuing through the '
'base classes of\n'
'"type(a)" excluding
metaclasses.\n'
'\n'
'However, if the looked-up value is an object
defining '
'one of the\n'
'descriptor methods, then Python may override the
default '
'behavior and\n'
'invoke the descriptor method instead. Where
this occurs '
'in the\n'
'precedence chain depends on which descriptor
methods '
'were defined and\n'
'how they were called.\n'
'\n'
'The starting point for descriptor invocation is
a '
'binding, "a.x". How\n'
'the arguments are assembled depends on
"a":\n'
'\n'
'Direct Call\n'
' The simplest and least common call is when
user code '
'directly\n'
' invokes a descriptor method:
"x.__get__(a)".\n'
'\n'
'Instance Binding\n'
' If binding to an object instance,
"a.x" is '
'transformed into the\n'
' call:
"type(a).__dict__[\'x\'].__get__(a, type(a))".\n'
'\n'
'Class Binding\n'
' If binding to a class, "A.x" is
transformed into the '
'call:\n'
'
"A.__dict__[\'x\'].__get__(None, A)".\n'
'\n'
'Super Binding\n'
' If "a" is an instance of
"super", then the binding '
'"super(B,\n'
' obj).m()" searches
"obj.__class__.__mro__" for the '
'base class "A"\n'
' immediately preceding "B" and then
invokes the '
'descriptor with the\n'
' call:
"A.__dict__[\'m\'].__get__(obj, '
'obj.__class__)".\n'
'\n'
'For instance bindings, the precedence of
descriptor '
'invocation depends\n'
'on the which descriptor methods are defined. A
'
'descriptor can define\n'
'any combination of "__get__()",
"__set__()" and '
'"__delete__()". If it\n'
'does not define "__get__()", then
accessing the '
'attribute will return\n'
'the descriptor object itself unless there is a
value in '
'the object’s\n'
'instance dictionary. If the descriptor defines
'
'"__set__()" and/or\n'
'"__delete__()", it is a data
descriptor; if it defines '
'neither, it is\n'
'a non-data descriptor. Normally, data
descriptors '
'define both\n'
'"__get__()" and "__set__()",
while non-data descriptors '
'have just the\n'
'"__get__()" method. Data descriptors
with "__set__()" '
'and "__get__()"\n'
'defined always override a redefinition in an
instance '
'dictionary. In\n'
'contrast, non-data descriptors can be overridden
by '
'instances.\n'
'\n'
'Python methods (including
"staticmethod()" and '
'"classmethod()") are\n'
'implemented as non-data descriptors.
Accordingly, '
'instances can\n'
'redefine and override methods. This allows
individual '
'instances to\n'
'acquire behaviors that differ from other
instances of '
'the same class.\n'
'\n'
'The "property()" function is
implemented as a data '
'descriptor.\n'
'Accordingly, instances cannot override the
behavior of a '
'property.\n'
'\n'
'\n'
'__slots__\n'
'=========\n'
'\n'
'*__slots__* allow us to explicitly declare data
members '
'(like\n'
'properties) and deny the creation of *__dict__*
and '
'*__weakref__*\n'
'(unless explicitly declared in *__slots__* or
available '
'in a parent.)\n'
'\n'
'The space saved over using *__dict__* can be
'
'significant.\n'
'\n'
'object.__slots__\n'
'\n'
' This class variable can be assigned a string,
'
'iterable, or sequence\n'
' of strings with variable names used by
instances. '
'*__slots__*\n'
' reserves space for the declared variables and
'
'prevents the\n'
' automatic creation of *__dict__* and
*__weakref__* '
'for each\n'
' instance.\n'
'\n'
'\n'
'Notes on using *__slots__*\n'
'--------------------------\n'
'\n'
'* When inheriting from a class without
*__slots__*, the '
'*__dict__*\n'
' and *__weakref__* attribute of the instances
will '
'always be\n'
' accessible.\n'
'\n'
'* Without a *__dict__* variable, instances
cannot be '
'assigned new\n'
' variables not listed in the *__slots__*
definition. '
'Attempts to\n'
' assign to an unlisted variable name raises
'
'"AttributeError". If\n'
' dynamic assignment of new variables is
desired, then '
'add\n'
' "\'__dict__\'" to the
sequence of strings in the '
'*__slots__*\n'
' declaration.\n'
'\n'
'* Without a *__weakref__* variable for each
instance, '
'classes\n'
' defining *__slots__* do not support weak
references to '
'its\n'
' instances. If weak reference support is
needed, then '
'add\n'
' "\'__weakref__\'" to the
sequence of strings in the '
'*__slots__*\n'
' declaration.\n'
'\n'
'* *__slots__* are implemented at the class level
by '
'creating\n'
' descriptors (Implementing Descriptors) for
each '
'variable name. As a\n'
' result, class attributes cannot be used to set
default '
'values for\n'
' instance variables defined by *__slots__*;
otherwise, '
'the class\n'
' attribute would overwrite the descriptor
assignment.\n'
'\n'
'* The action of a *__slots__* declaration is not
limited '
'to the\n'
' class where it is defined. *__slots__*
declared in '
'parents are\n'
' available in child classes. However, child
subclasses '
'will get a\n'
' *__dict__* and *__weakref__* unless they also
define '
'*__slots__*\n'
' (which should only contain names of any
*additional* '
'slots).\n'
'\n'
'* If a class defines a slot also defined in a
base '
'class, the\n'
' instance variable defined by the base class
slot is '
'inaccessible\n'
' (except by retrieving its descriptor directly
from the '
'base class).\n'
' This renders the meaning of the program
undefined. In '
'the future, a\n'
' check may be added to prevent this.\n'
'\n'
'* Nonempty *__slots__* does not work for classes
derived '
'from\n'
' “variable-length” built-in types such as
"int", '
'"bytes" and "tuple".\n'
'\n'
'* Any non-string iterable may be assigned to
'
'*__slots__*. Mappings\n'
' may also be used; however, in the future,
special '
'meaning may be\n'
' assigned to the values corresponding to each
key.\n'
'\n'
'* *__class__* assignment works only if both
classes have '
'the same\n'
' *__slots__*.\n'
'\n'
'* Multiple inheritance with multiple slotted
parent '
'classes can be\n'
' used, but only one parent is allowed to have
'
'attributes created by\n'
' slots (the other bases must have empty slot
layouts) - '
'violations\n'
' raise "TypeError".\n',
'attribute-references': 'Attribute references\n'
'********************\n'
'\n'
'An attribute reference is a primary followed
by a '
'period and a name:\n'
'\n'
' attributeref ::= primary "."
identifier\n'
'\n'
'The primary must evaluate to an object of a
type '
'that supports\n'
'attribute references, which most objects do.
This '
'object is then\n'
'asked to produce the attribute whose name is
the '
'identifier. This\n'
'production can be customized by overriding
the '
'"__getattr__()" method.\n'
'If this attribute is not available, the
exception '
'"AttributeError" is\n'
'raised. Otherwise, the type and value of
the object '
'produced is\n'
'determined by the object. Multiple
evaluations of '
'the same attribute\n'
'reference may yield different
objects.\n',
'augassign': 'Augmented assignment statements\n'
'*******************************\n'
'\n'
'Augmented assignment is the combination, in a single
statement, '
'of a\n'
'binary operation and an assignment statement:\n'
'\n'
' augmented_assignment_stmt ::= augtarget augop '
'(expression_list | yield_expression)\n'
' augtarget ::= identifier |
attributeref | '
'subscription | slicing\n'
' augop ::= "+=" |
"-=" | "*=" | "@=" | '
'"/=" | "//=" | "%=" |
"**="\n'
' | ">>=" |
"<<=" | "&=" | "^=" |
"|="\n'
'\n'
'(See section Primaries for the syntax definitions of
the last '
'three\n'
'symbols.)\n'
'\n'
'An augmented assignment evaluates the target (which,
unlike '
'normal\n'
'assignment statements, cannot be an unpacking) and the
'
'expression\n'
'list, performs the binary operation specific to the
type of '
'assignment\n'
'on the two operands, and assigns the result to the
original '
'target.\n'
'The target is only evaluated once.\n'
'\n'
'An augmented assignment expression like "x +=
1" can be '
'rewritten as\n'
'"x = x + 1" to achieve a similar, but not
exactly equal effect. '
'In the\n'
'augmented version, "x" is only evaluated
once. Also, when '
'possible,\n'
'the actual operation is performed *in-place*, meaning
that '
'rather than\n'
'creating a new object and assigning that to the target,
the old '
'object\n'
'is modified instead.\n'
'\n'
'Unlike normal assignments, augmented assignments
evaluate the '
'left-\n'
'hand side *before* evaluating the right-hand side. For
'
'example, "a[i]\n'
'+= f(x)" first looks-up "a[i]", then it
evaluates "f(x)" and '
'performs\n'
'the addition, and lastly, it writes the result back to
"a[i]".\n'
'\n'
'With the exception of assigning to tuples and multiple
targets '
'in a\n'
'single statement, the assignment done by augmented
assignment\n'
'statements is handled the same way as normal
assignments. '
'Similarly,\n'
'with the exception of the possible *in-place* behavior,
the '
'binary\n'
'operation performed by augmented assignment is the same
as the '
'normal\n'
'binary operations.\n'
'\n'
'For targets which are attribute references, the same
caveat '
'about\n'
'class and instance attributes applies as for regular
'
'assignments.\n',
'binary': 'Binary arithmetic operations\n'
'****************************\n'
'\n'
'The binary arithmetic operations have the conventional
priority\n'
'levels. Note that some of these operations also apply to
certain '
'non-\n'
'numeric types. Apart from the power operator, there are
only two\n'
'levels, one for multiplicative operators and one for
additive\n'
'operators:\n'
'\n'
' m_expr ::= u_expr | m_expr "*" u_expr |
m_expr "@" m_expr |\n'
' m_expr "//" u_expr | m_expr
"/" u_expr |\n'
' m_expr "%" u_expr\n'
' a_expr ::= m_expr | a_expr "+" m_expr |
a_expr "-" m_expr\n'
'\n'
'The "*" (multiplication) operator yields the
product of its '
'arguments.\n'
'The arguments must either both be numbers, or one argument
must be '
'an\n'
'integer and the other must be a sequence. In the former
case, the\n'
'numbers are converted to a common type and then multiplied
'
'together.\n'
'In the latter case, sequence repetition is performed; a
negative\n'
'repetition factor yields an empty sequence.\n'
'\n'
'The "@" (at) operator is intended to be used for
matrix\n'
'multiplication. No builtin Python types implement this
operator.\n'
'\n'
'New in version 3.5.\n'
'\n'
'The "/" (division) and "//" (floor
division) operators yield the\n'
'quotient of their arguments. The numeric arguments are
first\n'
'converted to a common type. Division of integers yields a
float, '
'while\n'
'floor division of integers results in an integer; the
result is '
'that\n'
'of mathematical division with the ‘floor’ function
applied to the\n'
'result. Division by zero raises the
"ZeroDivisionError" '
'exception.\n'
'\n'
'The "%" (modulo) operator yields the remainder
from the division '
'of\n'
'the first argument by the second. The numeric arguments
are '
'first\n'
'converted to a common type. A zero right argument raises
the\n'
'"ZeroDivisionError" exception. The arguments
may be floating '
'point\n'
'numbers, e.g., "3.14%0.7" equals
"0.34" (since "3.14" equals '
'"4*0.7 +\n'
'0.34".) The modulo operator always yields a result
with the same '
'sign\n'
'as its second operand (or zero); the absolute value of the
result '
'is\n'
'strictly smaller than the absolute value of the second
operand '
'[1].\n'
'\n'
'The floor division and modulo operators are connected by
the '
'following\n'
'identity: "x == (x//y)*y + (x%y)". Floor
division and modulo are '
'also\n'
'connected with the built-in function "divmod()":
"divmod(x, y) ==\n'
'(x//y, x%y)". [2].\n'
'\n'
'In addition to performing the modulo operation on numbers,
the '
'"%"\n'
'operator is also overloaded by string objects to perform
'
'old-style\n'
'string formatting (also known as interpolation). The
syntax for\n'
'string formatting is described in the Python Library
Reference,\n'
'section printf-style String Formatting.\n'
'\n'
'The floor division operator, the modulo operator, and the
'
'"divmod()"\n'
'function are not defined for complex numbers. Instead,
convert to '
'a\n'
'floating point number using the "abs()" function
if appropriate.\n'
'\n'
'The "+" (addition) operator yields the sum of
its arguments. The\n'
'arguments must either both be numbers or both be sequences
of the '
'same\n'
'type. In the former case, the numbers are converted to a
common '
'type\n'
'and then added together. In the latter case, the sequences
are\n'
'concatenated.\n'
'\n'
'The "-" (subtraction) operator yields the
difference of its '
'arguments.\n'
'The numeric arguments are first converted to a common
type.\n',
'bitwise': 'Binary bitwise operations\n'
'*************************\n'
'\n'
'Each of the three bitwise operations has a different
priority '
'level:\n'
'\n'
' and_expr ::= shift_expr | and_expr "&"
shift_expr\n'
' xor_expr ::= and_expr | xor_expr "^"
and_expr\n'
' or_expr ::= xor_expr | or_expr "|"
xor_expr\n'
'\n'
'The "&" operator yields the bitwise AND of
its arguments, which '
'must\n'
'be integers.\n'
'\n'
'The "^" operator yields the bitwise XOR
(exclusive OR) of its\n'
'arguments, which must be integers.\n'
'\n'
'The "|" operator yields the bitwise (inclusive)
OR of its '
'arguments,\n'
'which must be integers.\n',
'bltin-code-objects': 'Code Objects\n'
'************\n'
'\n'
'Code objects are used by the implementation to
'
'represent “pseudo-\n'
'compiled” executable Python code such as a
function '
'body. They differ\n'
'from function objects because they don’t
contain a '
'reference to their\n'
'global execution environment. Code objects
are '
'returned by the built-\n'
'in "compile()" function and can be
extracted from '
'function objects\n'
'through their "__code__" attribute.
See also the '
'"code" module.\n'
'\n'
'A code object can be executed or evaluated by
passing '
'it (instead of a\n'
'source string) to the "exec()" or
"eval()" built-in '
'functions.\n'
'\n'
'See The standard type hierarchy for more
'
'information.\n',
'bltin-ellipsis-object': 'The Ellipsis Object\n'
'*******************\n'
'\n'
'This object is commonly used by slicing
(see '
'Slicings). It supports\n'
'no special operations. There is exactly
one '
'ellipsis object, named\n'
'"Ellipsis" (a built-in name).
"type(Ellipsis)()" '
'produces the\n'
'"Ellipsis" singleton.\n'
'\n'
'It is written as "Ellipsis" or
"...".\n',
'bltin-null-object': 'The Null Object\n'
'***************\n'
'\n'
'This object is returned by functions that
don’t '
'explicitly return a\n'
'value. It supports no special operations.
There is '
'exactly one null\n'
'object, named "None" (a built-in
name). "type(None)()" '
'produces the\n'
'same singleton.\n'
'\n'
'It is written as "None".\n',
'bltin-type-objects': 'Type Objects\n'
'************\n'
'\n'
'Type objects represent the various object
types. An '
'object’s type is\n'
'accessed by the built-in function
"type()". There are '
'no special\n'
'operations on types. The standard module
"types" '
'defines names for\n'
'all standard built-in types.\n'
'\n'
'Types are written like this: "<class
\'int\'>".\n',
'booleans': 'Boolean operations\n'
'******************\n'
'\n'
' or_test ::= and_test | or_test "or"
and_test\n'
' and_test ::= not_test | and_test "and"
not_test\n'
' not_test ::= comparison | "not"
not_test\n'
'\n'
'In the context of Boolean operations, and also when
expressions '
'are\n'
'used by control flow statements, the following values
are '
'interpreted\n'
'as false: "False", "None", numeric
zero of all types, and empty\n'
'strings and containers (including strings, tuples,
lists,\n'
'dictionaries, sets and frozensets). All other values
are '
'interpreted\n'
'as true. User-defined objects can customize their truth
value '
'by\n'
'providing a "__bool__()" method.\n'
'\n'
'The operator "not" yields "True" if
its argument is false, '
'"False"\n'
'otherwise.\n'
'\n'
'The expression "x and y" first evaluates *x*;
if *x* is false, '
'its\n'
'value is returned; otherwise, *y* is evaluated and the
resulting '
'value\n'
'is returned.\n'
'\n'
'The expression "x or y" first evaluates *x*;
if *x* is true, its '
'value\n'
'is returned; otherwise, *y* is evaluated and the
resulting value '
'is\n'
'returned.\n'
'\n'
'Note that neither "and" nor "or"
restrict the value and type '
'they\n'
'return to "False" and "True", but
rather return the last '
'evaluated\n'
'argument. This is sometimes useful, e.g., if
"s" is a string '
'that\n'
'should be replaced by a default value if it is empty,
the '
'expression\n'
'"s or \'foo\'" yields the desired
value. Because "not" has to '
'create a\n'
'new value, it returns a boolean value regardless of the
type of '
'its\n'
'argument (for example, "not \'foo\'"
produces "False" rather '
'than "\'\'".)\n',
'break': 'The "break" statement\n'
'*********************\n'
'\n'
' break_stmt ::= "break"\n'
'\n'
'"break" 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.\n'
'\n'
'It terminates the nearest enclosing loop, skipping the
optional '
'"else"\n'
'clause if the loop has one.\n'
'\n'
'If a "for" loop is terminated by
"break", the loop control target\n'
'keeps its current value.\n'
'\n'
'When "break" passes control out of a
"try" statement with a '
'"finally"\n'
'clause, that "finally" clause is executed before
really leaving '
'the\n'
'loop.\n',
'callable-types': 'Emulating callable objects\n'
'**************************\n'
'\n'
'object.__call__(self[, args...])\n'
'\n'
' Called when the instance is “called” as a
function; if '
'this method\n'
' is defined, "x(arg1, arg2, ...)" is a
shorthand for\n'
' "x.__call__(arg1, arg2,
...)".\n',
'calls': 'Calls\n'
'*****\n'
'\n'
'A call calls a callable object (e.g., a *function*) with a
'
'possibly\n'
'empty series of *arguments*:\n'
'\n'
' call ::= primary "("
[argument_list [","] | '
'comprehension] ")"\n'
' argument_list ::= positional_arguments
["," '
'starred_and_keywords]\n'
' [","
keywords_arguments]\n'
' | starred_and_keywords [","
'
'keywords_arguments]\n'
' | keywords_arguments\n'
' positional_arguments ::= ["*"] expression
("," ["*"] '
'expression)*\n'
' starred_and_keywords ::= ("*" expression |
keyword_item)\n'
' ("," "*"
expression | "," '
'keyword_item)*\n'
' keywords_arguments ::= (keyword_item | "**"
expression)\n'
' ("," keyword_item |
"," "**" '
'expression)*\n'
' keyword_item ::= identifier "="
expression\n'
'\n'
'An optional trailing comma may be present after the
positional and\n'
'keyword arguments but does not affect the
semantics.\n'
'\n'
'The primary must evaluate to a callable object
(user-defined\n'
'functions, built-in functions, methods of built-in objects,
class\n'
'objects, methods of class instances, and all objects having
a\n'
'"__call__()" method are callable). All argument
expressions are\n'
'evaluated before the call is attempted. Please refer to
section\n'
'Function definitions for the syntax of formal *parameter*
lists.\n'
'\n'
'If keyword arguments are present, they are first converted
to\n'
'positional arguments, as follows. First, a list of
unfilled slots '
'is\n'
'created for the formal parameters. If there are N
positional\n'
'arguments, they are placed in the first N slots. Next, for
each\n'
'keyword argument, the identifier is used to determine
the\n'
'corresponding slot (if the identifier is the same as the
first '
'formal\n'
'parameter name, the first slot is used, and so on). If the
slot '
'is\n'
'already filled, a "TypeError" exception is
raised. Otherwise, the\n'
'value of the argument is placed in the slot, filling it
(even if '
'the\n'
'expression is "None", it fills the slot). When
all arguments have\n'
'been processed, the slots that are still unfilled are
filled with '
'the\n'
'corresponding default value from the function definition.
'
'(Default\n'
'values are calculated, once, when the function is defined;
thus, a\n'
'mutable object such as a list or dictionary used as default
value '
'will\n'
'be shared by all calls that don’t specify an argument
value for '
'the\n'
'corresponding slot; this should usually be avoided.) If
there are '
'any\n'
'unfilled slots for which no default value is specified, a
'
'"TypeError"\n'
'exception is raised. Otherwise, the list of filled slots
is used '
'as\n'
'the argument list for the call.\n'
'\n'
'**CPython implementation detail:** An implementation may
provide\n'
'built-in functions whose positional parameters do not have
names, '
'even\n'
'if they are ‘named’ for the purpose of documentation,
and which\n'
'therefore cannot be supplied by keyword. In CPython, this
is the '
'case\n'
'for functions implemented in C that use
"PyArg_ParseTuple()" to '
'parse\n'
'their arguments.\n'
'\n'
'If there are more positional arguments than there are
formal '
'parameter\n'
'slots, a "TypeError" exception is raised, unless
a formal '
'parameter\n'
'using the syntax "*identifier" is present; in
this case, that '
'formal\n'
'parameter receives a tuple containing the excess positional
'
'arguments\n'
'(or an empty tuple if there were no excess positional
arguments).\n'
'\n'
'If any keyword argument does not correspond to a formal
parameter\n'
'name, a "TypeError" exception is raised, unless a
formal parameter\n'
'using the syntax "**identifier" is present; in
this case, that '
'formal\n'
'parameter receives a dictionary containing the excess
keyword\n'
'arguments (using the keywords as keys and the argument
values as\n'
'corresponding values), or a (new) empty dictionary if there
were '
'no\n'
'excess keyword arguments.\n'
'\n'
'If the syntax "*expression" appears in the
function call, '
'"expression"\n'
'must evaluate to an *iterable*. Elements from these
iterables are\n'
'treated as if they were additional positional arguments.
For the '
'call\n'
'"f(x1, x2, *y, x3, x4)", if *y* evaluates to a
sequence *y1*, …, '
'*yM*,\n'
'this is equivalent to a call with M+4 positional arguments
*x1*, '
'*x2*,\n'
'*y1*, …, *yM*, *x3*, *x4*.\n'
'\n'
'A consequence of this is that although the
"*expression" syntax '
'may\n'
'appear *after* explicit keyword arguments, it is processed
'
'*before*\n'
'the keyword arguments (and any "**expression"
arguments – see '
'below).\n'
'So:\n'
'\n'
' >>> def f(a, b):\n'
' ... print(a, b)\n'
' ...\n'
' >>> f(b=1, *(2,))\n'
' 2 1\n'
' >>> f(a=1, *(2,))\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 1, in
<module>\n'
" TypeError: f() got multiple values for keyword argument
'a'\n"
' >>> f(1, *(2,))\n'
' 1 2\n'
'\n'
'It is unusual for both keyword arguments and the
"*expression" '
'syntax\n'
'to be used in the same call, so in practice this confusion
does '
'not\n'
'arise.\n'
'\n'
'If the syntax "**expression" appears in the
function call,\n'
'"expression" must evaluate to a *mapping*, the
contents of which '
'are\n'
'treated as additional keyword arguments. If a keyword is
already\n'
'present (as an explicit keyword argument, or from another
'
'unpacking),\n'
'a "TypeError" exception is raised.\n'
'\n'
'Formal parameters using the syntax "*identifier"
or "**identifier"\n'
'cannot be used as positional argument slots or as keyword
argument\n'
'names.\n'
'\n'
'Changed in version 3.5: Function calls accept any number of
"*" '
'and\n'
'"**" unpackings, positional arguments may follow
iterable '
'unpackings\n'
'("*"), and keyword arguments may follow
dictionary unpackings '
'("**").\n'
'Originally proposed by **PEP 448**.\n'
'\n'
'A call always returns some value, possibly
"None", unless it raises '
'an\n'
'exception. How this value is computed depends on the type
of the\n'
'callable object.\n'
'\n'
'If it is—\n'
'\n'
'a user-defined function:\n'
' The code block for the function is executed, passing it
the\n'
' argument list. The first thing the code block will do
is bind '
'the\n'
' formal parameters to the arguments; this is described in
'
'section\n'
' Function definitions. When the code block executes a
"return"\n'
' statement, this specifies the return value of the
function '
'call.\n'
'\n'
'a built-in function or method:\n'
' The result is up to the interpreter; see Built-in
Functions for '
'the\n'
' descriptions of built-in functions and methods.\n'
'\n'
'a class object:\n'
' A new instance of that class is returned.\n'
'\n'
'a class instance method:\n'
' The corresponding user-defined function is called, with
an '
'argument\n'
' list that is one longer than the argument list of the
call: the\n'
' instance becomes the first argument.\n'
'\n'
'a class instance:\n'
' The class must define a "__call__()" method;
the effect is then '
'the\n'
' same as if that method was called.\n',
'class': 'Class definitions\n'
'*****************\n'
'\n'
'A class definition defines a class object (see section The
'
'standard\n'
'type hierarchy):\n'
'\n'
' classdef ::= [decorators] "class" classname
[inheritance] ":" '
'suite\n'
' inheritance ::= "(" [argument_list]
")"\n'
' classname ::= identifier\n'
'\n'
'A class definition is an executable statement. The
inheritance '
'list\n'
'usually gives a list of base classes (see Metaclasses for
more\n'
'advanced uses), so each item in the list should evaluate to
a '
'class\n'
'object which allows subclassing. Classes without an
inheritance '
'list\n'
'inherit, by default, from the base class
"object"; hence,\n'
'\n'
' class Foo:\n'
' pass\n'
'\n'
'is equivalent to\n'
'\n'
' class Foo(object):\n'
' pass\n'
'\n'
'The class’s suite is then executed in a new execution
frame (see\n'
'Naming and binding), using a newly created local namespace
and the\n'
'original global namespace. (Usually, the suite contains
mostly\n'
'function definitions.) When the class’s suite finishes
execution, '
'its\n'
'execution frame is discarded but its local namespace is
saved. [3] '
'A\n'
'class object is then created using the inheritance list for
the '
'base\n'
'classes and the saved local namespace for the attribute
'
'dictionary.\n'
'The class name is bound to this class object in the
original local\n'
'namespace.\n'
'\n'
'The order in which attributes are defined in the class body
is\n'
'preserved in the new class’s "__dict__". Note
that this is '
'reliable\n'
'only right after the class is created and only for classes
that '
'were\n'
'defined using the definition syntax.\n'
'\n'
'Class creation can be customized heavily using
metaclasses.\n'
'\n'
'Classes can also be decorated: just like when decorating
'
'functions,\n'
'\n'
' @f1(arg)\n'
' @f2\n'
' class Foo: pass\n'
'\n'
'is roughly equivalent to\n'
'\n'
' class Foo: pass\n'
' Foo = f1(arg)(f2(Foo))\n'
'\n'
'The evaluation rules for the decorator expressions are the
same as '
'for\n'
'function decorators. The result is then bound to the class
name.\n'
'\n'
'**Programmer’s note:** Variables defined in the class
definition '
'are\n'
'class attributes; they are shared by instances. Instance
'
'attributes\n'
'can be set in a method with "self.name = value".
Both class and\n'
'instance attributes are accessible through the notation
'
'“"self.name"”,\n'
'and an instance attribute hides a class attribute with the
same '
'name\n'
'when accessed in this way. Class attributes can be used as
'
'defaults\n'
'for instance attributes, but using mutable values there can
lead '
'to\n'
'unexpected results. Descriptors can be used to create
instance\n'
'variables with different implementation details.\n'
'\n'
'See also:\n'
'\n'
' **PEP 3115** - Metaclasses in Python 3000\n'
' The proposal that changed the declaration of
metaclasses to '
'the\n'
' current syntax, and the semantics for how classes
with\n'
' metaclasses are constructed.\n'
'\n'
' **PEP 3129** - Class Decorators\n'
' The proposal that added class decorators. Function
and '
'method\n'
' decorators were introduced in **PEP 318**.\n',
'comparisons': 'Comparisons\n'
'***********\n'
'\n'
'Unlike C, all comparison operations in Python have
the same '
'priority,\n'
'which is lower than that of any arithmetic, shifting
or '
'bitwise\n'
'operation. Also unlike C, expressions like "a
< b < c" have '
'the\n'
'interpretation that is conventional in
mathematics:\n'
'\n'
' comparison ::= or_expr (comp_operator
or_expr)*\n'
' comp_operator ::= "<" |
">" | "==" | ">=" | "<=" |
"!="\n'
' | "is"
["not"] | ["not"] "in"\n'
'\n'
'Comparisons yield boolean values: "True" or
"False".\n'
'\n'
'Comparisons can be chained arbitrarily, e.g., "x
< y <= z" '
'is\n'
'equivalent to "x < y and y <= z",
except that "y" is '
'evaluated only\n'
'once (but in both cases "z" is not
evaluated at all when "x < '
'y" is\n'
'found to be false).\n'
'\n'
'Formally, if *a*, *b*, *c*, …, *y*, *z* are
expressions and '
'*op1*,\n'
'*op2*, …, *opN* are comparison operators, then
"a op1 b op2 c '
'... y\n'
'opN z" is equivalent to "a op1 b and b op2
c and ... y opN '
'z", except\n'
'that each expression is evaluated at most
once.\n'
'\n'
'Note that "a op1 b op2 c" doesn’t imply
any kind of '
'comparison between\n'
'*a* and *c*, so that, e.g., "x < y >
z" is perfectly legal '
'(though\n'
'perhaps not pretty).\n'
'\n'
'\n'
'Value comparisons\n'
'=================\n'
'\n'
'The operators "<", ">",
"==", ">=", "<=", and "!="
compare '
'the values\n'
'of two objects. The objects do not need to have the
same '
'type.\n'
'\n'
'Chapter Objects, values and types states that objects
have a '
'value (in\n'
'addition to type and identity). The value of an
object is a '
'rather\n'
'abstract notion in Python: For example, there is no
canonical '
'access\n'
'method for an object’s value. Also, there is no
requirement '
'that the\n'
'value of an object should be constructed in a
particular way, '
'e.g.\n'
'comprised of all its data attributes. Comparison
operators '
'implement a\n'
'particular notion of what the value of an object is.
One can '
'think of\n'
'them as defining the value of an object indirectly,
by means '
'of their\n'
'comparison implementation.\n'
'\n'
'Because all types are (direct or indirect) subtypes
of '
'"object", they\n'
'inherit the default comparison behavior from
"object". Types '
'can\n'
'customize their comparison behavior by implementing
*rich '
'comparison\n'
'methods* like "__lt__()", described in
Basic customization.\n'
'\n'
'The default behavior for equality comparison
("==" and "!=") '
'is based\n'
'on the identity of the objects. Hence, equality
comparison '
'of\n'
'instances with the same identity results in equality,
and '
'equality\n'
'comparison of instances with different identities
results in\n'
'inequality. A motivation for this default behavior
is the '
'desire that\n'
'all objects should be reflexive (i.e. "x is
y" implies "x == '
'y").\n'
'\n'
'A default order comparison ("<",
">", "<=", and ">=") is not '
'provided;\n'
'an attempt raises "TypeError". A
motivation for this default '
'behavior\n'
'is the lack of a similar invariant as for
equality.\n'
'\n'
'The behavior of the default equality comparison, that
'
'instances with\n'
'different identities are always unequal, may be in
contrast '
'to what\n'
'types will need that have a sensible definition of
object '
'value and\n'
'value-based equality. Such types will need to
customize '
'their\n'
'comparison behavior, and in fact, a number of
built-in types '
'have done\n'
'that.\n'
'\n'
'The following list describes the comparison behavior
of the '
'most\n'
'important built-in types.\n'
'\n'
'* Numbers of built-in numeric types (Numeric Types
— int, '
'float,\n'
' complex) and of the standard library types '
'"fractions.Fraction" and\n'
' "decimal.Decimal" can be compared within
and across their '
'types,\n'
' with the restriction that complex numbers do not
support '
'order\n'
' comparison. Within the limits of the types
involved, they '
'compare\n'
' mathematically (algorithmically) correct without
loss of '
'precision.\n'
'\n'
' The not-a-number values
"float(\'NaN\')" and '
'"Decimal(\'NaN\')" are\n'
' special. They are identical to themselves ("x
is x" is '
'true) but\n'
' are not equal to themselves ("x == x" is
false). '
'Additionally,\n'
' comparing any number to a not-a-number value will
return '
'"False".\n'
' For example, both "3 <
float(\'NaN\')" and "float(\'NaN\') '
'< 3" will\n'
' return "False".\n'
'\n'
'* Binary sequences (instances of "bytes" or
"bytearray") can '
'be\n'
' compared within and across their types. They
compare\n'
' lexicographically using the numeric values of their
'
'elements.\n'
'\n'
'* Strings (instances of "str") compare
lexicographically '
'using the\n'
' numerical Unicode code points (the result of the
built-in '
'function\n'
' "ord()") of their characters. [3]\n'
'\n'
' Strings and binary sequences cannot be directly
compared.\n'
'\n'
'* Sequences (instances of "tuple",
"list", or "range") can '
'be\n'
' compared only within each of their types, with the
'
'restriction that\n'
' ranges do not support order comparison. Equality
'
'comparison across\n'
' these types results in inequality, and ordering
comparison '
'across\n'
' these types raises "TypeError".\n'
'\n'
' Sequences compare lexicographically using
comparison of\n'
' corresponding elements, whereby reflexivity of the
elements '
'is\n'
' enforced.\n'
'\n'
' In enforcing reflexivity of elements, the
comparison of '
'collections\n'
' assumes that for a collection element
"x", "x == x" is '
'always true.\n'
' Based on that assumption, element identity is
compared '
'first, and\n'
' element comparison is performed only for distinct
'
'elements. This\n'
' approach yields the same result as a strict element
'
'comparison\n'
' would, if the compared elements are reflexive. For
'
'non-reflexive\n'
' elements, the result is different than for strict
element\n'
' comparison, and may be surprising: The
non-reflexive '
'not-a-number\n'
' values for example result in the following
comparison '
'behavior when\n'
' used in a list:\n'
'\n'
" >>> nan =
float('NaN')\n"
' >>> nan is nan\n'
' True\n'
' >>> nan == nan\n'
' False <-- the defined
non-reflexive '
'behavior of NaN\n'
' >>> [nan] == [nan]\n'
' True <-- list enforces
reflexivity and '
'tests identity first\n'
'\n'
' Lexicographical comparison between built-in
collections '
'works as\n'
' follows:\n'
'\n'
' * For two collections to compare equal, they must
be of the '
'same\n'
' type, have the same length, and each pair of
'
'corresponding\n'
' elements must compare equal (for example,
"[1,2] == '
'(1,2)" is\n'
' false because the type is not the same).\n'
'\n'
' * Collections that support order comparison are
ordered the '
'same\n'
' as their first unequal elements (for example,
"[1,2,x] <= '
'[1,2,y]"\n'
' has the same value as "x <= y"). If
a corresponding '
'element does\n'
' not exist, the shorter collection is ordered
first (for '
'example,\n'
' "[1,2] < [1,2,3]" is true).\n'
'\n'
'* Mappings (instances of "dict") compare
equal if and only if '
'they\n'
' have equal *(key, value)* pairs. Equality
comparison of the '
'keys and\n'
' values enforces reflexivity.\n'
'\n'
' Order comparisons ("<",
">", "<=", and ">=") raise '
'"TypeError".\n'
'\n'
'* Sets (instances of "set" or
"frozenset") can be compared '
'within\n'
' and across their types.\n'
'\n'
' They define order comparison operators to mean
subset and '
'superset\n'
' tests. Those relations do not define total
orderings (for '
'example,\n'
' the two sets "{1,2}" and
"{2,3}" are not equal, nor subsets '
'of one\n'
' another, nor supersets of one another).
Accordingly, sets '
'are not\n'
' appropriate arguments for functions which depend on
total '
'ordering\n'
' (for example, "min()", "max()",
and "sorted()" produce '
'undefined\n'
' results given a list of sets as inputs).\n'
'\n'
' Comparison of sets enforces reflexivity of its
elements.\n'
'\n'
'* Most other built-in types have no comparison
methods '
'implemented,\n'
' so they inherit the default comparison
behavior.\n'
'\n'
'User-defined classes that customize their comparison
behavior '
'should\n'
'follow some consistency rules, if possible:\n'
'\n'
'* Equality comparison should be reflexive. In other
words, '
'identical\n'
' objects should compare equal:\n'
'\n'
' "x is y" implies "x ==
y"\n'
'\n'
'* Comparison should be symmetric. In other words, the
'
'following\n'
' expressions should have the same result:\n'
'\n'
' "x == y" and "y ==
x"\n'
'\n'
' "x != y" and "y !=
x"\n'
'\n'
' "x < y" and "y >
x"\n'
'\n'
' "x <= y" and "y >=
x"\n'
'\n'
'* Comparison should be transitive. The following
'
'(non-exhaustive)\n'
' examples illustrate that:\n'
'\n'
' "x > y and y > z" implies
"x > z"\n'
'\n'
' "x < y and y <= z" implies
"x < z"\n'
'\n'
'* Inverse comparison should result in the boolean
negation. '
'In other\n'
' words, the following expressions should have the
same '
'result:\n'
'\n'
' "x == y" and "not x !=
y"\n'
'\n'
' "x < y" and "not x >=
y" (for total ordering)\n'
'\n'
' "x > y" and "not x <=
y" (for total ordering)\n'
'\n'
' The last two expressions apply to totally ordered
'
'collections (e.g.\n'
' to sequences, but not to sets or mappings). See
also the\n'
' "total_ordering()" decorator.\n'
'\n'
'* The "hash()" result should be consistent
with equality. '
'Objects\n'
' that are equal should either have the same hash
value, or '
'be marked\n'
' as unhashable.\n'
'\n'
'Python does not enforce these consistency rules. In
fact, '
'the\n'
'not-a-number values are an example for not following
these '
'rules.\n'
'\n'
'\n'
'Membership test operations\n'
'==========================\n'
'\n'
'The operators "in" and "not in"
test for membership. "x in '
's"\n'
'evaluates to "True" if *x* is a member of
*s*, and "False" '
'otherwise.\n'
'"x not in s" returns the negation of
"x in s". All built-in '
'sequences\n'
'and set types support this as well as dictionary, for
which '
'"in" tests\n'
'whether the dictionary has a given key. For container
types '
'such as\n'
'list, tuple, set, frozenset, dict, or
collections.deque, the\n'
'expression "x in y" is equivalent to
"any(x is e or x == e '
'for e in\n'
'y)".\n'
'\n'
'For the string and bytes types, "x in y" is
"True" if and '
'only if *x*\n'
'is a substring of *y*. An equivalent test is
"y.find(x) != '
'-1".\n'
'Empty strings are always considered to be a substring
of any '
'other\n'
'string, so """ in
"abc"" will return "True".\n'
'\n'
'For user-defined classes which define the
"__contains__()" '
'method, "x\n'
'in y" returns "True" if
"y.__contains__(x)" returns a true '
'value, and\n'
'"False" otherwise.\n'
'\n'
'For user-defined classes which do not define
"__contains__()" '
'but do\n'
'define "__iter__()", "x in y" is
"True" if some value "z" '
'with "x ==\n'
'z" is produced while iterating over
"y". If an exception is '
'raised\n'
'during the iteration, it is as if "in"
raised that '
'exception.\n'
'\n'
'Lastly, the old-style iteration protocol is tried: if
a class '
'defines\n'
'"__getitem__()", "x in y" is
"True" if and only if there is a '
'non-\n'
'negative integer index *i* such that "x ==
y[i]", and all '
'lower\n'
'integer indices do not raise "IndexError"
exception. (If any '
'other\n'
'exception is raised, it is as if "in"
raised that '
'exception).\n'
'\n'
'The operator "not in" is defined to have
the inverse true '
'value of\n'
'"in".\n'
'\n'
'\n'
'Identity comparisons\n'
'====================\n'
'\n'
'The operators "is" and "is not"
test for object identity: "x '
'is y" is\n'
'true if and only if *x* and *y* are the same object.
Object '
'identity\n'
'is determined using the "id()" function.
"x is not y" yields '
'the\n'
'inverse truth value. [4]\n',
'compound': 'Compound statements\n'
'*******************\n'
'\n'
'Compound statements contain (groups of) other
statements; they '
'affect\n'
'or control the execution of those other statements in
some way. '
'In\n'
'general, compound statements span multiple lines,
although in '
'simple\n'
'incarnations a whole compound statement may be contained
in one '
'line.\n'
'\n'
'The "if", "while" and
"for" statements implement traditional '
'control\n'
'flow constructs. "try" specifies exception
handlers and/or '
'cleanup\n'
'code for a group of statements, while the
"with" statement '
'allows the\n'
'execution of initialization and finalization code around
a block '
'of\n'
'code. Function and class definitions are also
syntactically '
'compound\n'
'statements.\n'
'\n'
'A compound statement consists of one or more
‘clauses.’ A '
'clause\n'
'consists of a header and a ‘suite.’ The clause
headers of a\n'
'particular compound statement are all at the same
indentation '
'level.\n'
'Each clause header begins with a uniquely identifying
keyword '
'and ends\n'
'with a colon. A suite is a group of statements
controlled by a\n'
'clause. A suite can be one or more semicolon-separated
simple\n'
'statements on the same line as the header, following the
'
'header’s\n'
'colon, or it can be one or more indented statements on
'
'subsequent\n'
'lines. Only the latter form of a suite can contain
nested '
'compound\n'
'statements; the following is illegal, mostly because it
wouldn’t '
'be\n'
'clear to which "if" clause a following
"else" clause would '
'belong:\n'
'\n'
' if test1: if test2: print(x)\n'
'\n'
'Also note that the semicolon binds tighter than the
colon in '
'this\n'
'context, so that in the following example, either all or
none of '
'the\n'
'"print()" calls are executed:\n'
'\n'
' if x < y < z: print(x); print(y);
print(z)\n'
'\n'
'Summarizing:\n'
'\n'
' compound_stmt ::= if_stmt\n'
' | while_stmt\n'
' | for_stmt\n'
' | try_stmt\n'
' | with_stmt\n'
' | funcdef\n'
' | classdef\n'
' | async_with_stmt\n'
' | async_for_stmt\n'
' | async_funcdef\n'
' suite ::= stmt_list NEWLINE | NEWLINE INDENT
'
'statement+ DEDENT\n'
' statement ::= stmt_list NEWLINE |
compound_stmt\n'
' stmt_list ::= simple_stmt (";"
simple_stmt)* [";"]\n'
'\n'
'Note that statements always end in a "NEWLINE"
possibly followed '
'by a\n'
'"DEDENT". Also note that optional
continuation clauses always '
'begin\n'
'with a keyword that cannot start a statement, thus there
are no\n'
'ambiguities (the ‘dangling "else"’ problem
is solved in Python '
'by\n'
'requiring nested "if" statements to be
indented).\n'
'\n'
'The formatting of the grammar rules in the following
sections '
'places\n'
'each clause on a separate line for clarity.\n'
'\n'
'\n'
'The "if" statement\n'
'==================\n'
'\n'
'The "if" statement is used for conditional
execution:\n'
'\n'
' if_stmt ::= "if" expression ":"
suite\n'
' ("elif" 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'
'\n'
'\n'
'The "while" statement\n'
'=====================\n'
'\n'
'The "while" statement is used for repeated
execution as long as '
'an\n'
'expression is true:\n'
'\n'
' while_stmt ::= "while" expression
":" suite\n'
' ["else" ":"
suite]\n'
'\n'
'This repeatedly tests the expression and, if it is true,
'
'executes the\n'
'first suite; if the expression is false (which may be
the first '
'time\n'
'it is tested) the suite of the "else" clause,
if present, is '
'executed\n'
'and the loop 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 goes '
'back\n'
'to testing the expression.\n'
'\n'
'\n'
'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(s) 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'
'Note: There is a subtlety when the sequence is being
modified by '
'the\n'
' loop (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'
' current item will be treated again the next time
through the '
'loop.\n'
' This can lead to nasty bugs that can be avoided by
making a\n'
' temporary copy using a slice of the whole sequence,
e.g.,\n'
'\n'
' for x in a[:]:\n'
' if x < 0: a.remove(x)\n'
'\n'
'\n'
'The "try" statement\n'
'===================\n'
'\n'
'The "try" statement specifies exception
handlers and/or cleanup '
'code\n'
'for a group of statements:\n'
'\n'
' try_stmt ::= try1_stmt | try2_stmt\n'
' try1_stmt ::= "try" ":"
suite\n'
' ("except" [expression
["as" identifier]] ":" '
'suite)+\n'
' ["else" ":"
suite]\n'
' ["finally" ":"
suite]\n'
' try2_stmt ::= "try" ":"
suite\n'
' "finally" ":"
suite\n'
'\n'
'The "except" clause(s) specify one or more
exception handlers. '
'When no\n'
'exception occurs in the "try" clause, no
exception handler is\n'
'executed. When an exception occurs in the
"try" suite, a search '
'for an\n'
'exception handler is started. This search inspects the
except '
'clauses\n'
'in turn until one is found that matches the exception.
An '
'expression-\n'
'less except clause, if present, must be last; it matches
any\n'
'exception. For an except clause with an expression,
that '
'expression\n'
'is evaluated, and the clause matches the exception if
the '
'resulting\n'
'object is “compatible” with the exception. An
object is '
'compatible\n'
'with an exception if it is the class or a base class of
the '
'exception\n'
'object or a tuple containing an item compatible with the
'
'exception.\n'
'\n'
'If no except clause matches the exception, the search
for an '
'exception\n'
'handler continues in the surrounding code and on the
invocation '
'stack.\n'
'[1]\n'
'\n'
'If the evaluation of an expression in the header of an
except '
'clause\n'
'raises an exception, the original search for a handler
is '
'canceled and\n'
'a search starts for the new exception in the surrounding
code '
'and on\n'
'the call stack (it is treated as if the entire
"try" statement '
'raised\n'
'the exception).\n'
'\n'
'When a matching except clause is found, the exception is
'
'assigned to\n'
'the target specified after the "as" keyword in
that except '
'clause, if\n'
'present, and the except clause’s suite is executed.
All except\n'
'clauses must have an executable block. When the end of
this '
'block is\n'
'reached, execution continues normally after the entire
try '
'statement.\n'
'(This means that if two nested handlers exist for the
same '
'exception,\n'
'and the exception occurs in the try clause of the inner
handler, '
'the\n'
'outer handler will not handle the exception.)\n'
'\n'
'When an exception has been assigned using "as
target", it is '
'cleared\n'
'at the end of the except clause. This is as if\n'
'\n'
' except E as N:\n'
' foo\n'
'\n'
'was translated to\n'
'\n'
' except E as N:\n'
' try:\n'
' foo\n'
' finally:\n'
' del N\n'
'\n'
'This means the exception must be assigned to a different
name to '
'be\n'
'able to refer to it after the except clause. Exceptions
are '
'cleared\n'
'because with the traceback attached to them, they form a
'
'reference\n'
'cycle with the stack frame, keeping all locals in that
frame '
'alive\n'
'until the next garbage collection occurs.\n'
'\n'
'Before an except clause’s suite is executed, details
about the\n'
'exception are stored in the "sys" module and
can be accessed '
'via\n'
'"sys.exc_info()". "sys.exc_info()"
returns a 3-tuple consisting '
'of the\n'
'exception class, the exception instance and a traceback
object '
'(see\n'
'section The standard type hierarchy) identifying the
point in '
'the\n'
'program where the exception occurred.
"sys.exc_info()" values '
'are\n'
'restored to their previous values (before the call) when
'
'returning\n'
'from a function that handled an exception.\n'
'\n'
'The optional "else" clause is executed if the
control flow '
'leaves the\n'
'"try" suite, no exception was raised, and no
"return", '
'"continue", or\n'
'"break" statement was executed. Exceptions in
the "else" clause '
'are\n'
'not handled by the preceding "except"
clauses.\n'
'\n'
'If "finally" is present, it specifies a
‘cleanup’ handler. The '
'"try"\n'
'clause is executed, including any "except" and
"else" clauses. '
'If an\n'
'exception occurs in any of the clauses and is not
handled, the\n'
'exception is temporarily saved. The "finally"
clause is '
'executed. If\n'
'there is a saved exception it is re-raised at the end of
the '
'"finally"\n'
'clause. If the "finally" clause raises
another exception, the '
'saved\n'
'exception is set as the context of the new exception. If
the '
'"finally"\n'
'clause executes a "return" or
"break" statement, the saved '
'exception\n'
'is discarded:\n'
'\n'
' >>> def f():\n'
' ... try:\n'
' ... 1/0\n'
' ... finally:\n'
' ... return 42\n'
' ...\n'
' >>> f()\n'
' 42\n'
'\n'
'The exception information is not available to the
program '
'during\n'
'execution of the "finally" clause.\n'
'\n'
'When a "return", "break" or
"continue" statement is executed in '
'the\n'
'"try" suite of a
"try"…"finally" statement, the "finally"
clause '
'is\n'
'also executed ‘on the way out.’ A
"continue" statement is '
'illegal in\n'
'the "finally" clause. (The reason is a problem
with the current\n'
'implementation — this restriction may be lifted in the
future).\n'
'\n'
'The return value of a function is determined by the last
'
'"return"\n'
'statement executed. Since the "finally"
clause always executes, '
'a\n'
'"return" statement executed in the
"finally" clause will always '
'be the\n'
'last one executed:\n'
'\n'
' >>> def foo():\n'
' ... try:\n'
" ... return 'try'\n"
' ... finally:\n'
" ... return 'finally'\n"
' ...\n'
' >>> foo()\n'
" 'finally'\n"
'\n'
'Additional information on exceptions can be found in
section\n'
'Exceptions, and information on using the
"raise" statement to '
'generate\n'
'exceptions may be found in section The raise
statement.\n'
'\n'
'\n'
'The "with" statement\n'
'====================\n'
'\n'
'The "with" statement is used to wrap the
execution of a block '
'with\n'
'methods defined by a context manager (see section With
'
'Statement\n'
'Context Managers). This allows common
"try"…"except"…"finally" '
'usage\n'
'patterns to be encapsulated for convenient
reuse.\n'
'\n'
' with_stmt ::= "with" with_item
("," with_item)* ":" suite\n'
' with_item ::= expression ["as"
target]\n'
'\n'
'The execution of the "with" statement with one
“item” proceeds '
'as\n'
'follows:\n'
'\n'
'1. The context expression (the expression given in the
'
'"with_item")\n'
' is evaluated to obtain a context manager.\n'
'\n'
'2. The context manager’s "__exit__()" is
loaded for later use.\n'
'\n'
'3. The context manager’s "__enter__()"
method is invoked.\n'
'\n'
'4. If a target was included in the "with"
statement, the return\n'
' value from "__enter__()" is assigned to
it.\n'
'\n'
' Note: The "with" statement guarantees that
if the '
'"__enter__()"\n'
' method returns without an error, then
"__exit__()" will '
'always be\n'
' called. Thus, if an error occurs during the
assignment to '
'the\n'
' target list, it will be treated the same as an
error '
'occurring\n'
' within the suite would be. See step 6
below.\n'
'\n'
'5. The suite is executed.\n'
'\n'
'6. The context manager’s "__exit__()" method
is invoked. If an\n'
' exception caused the suite to be exited, its type,
value, '
'and\n'
' traceback are passed as arguments to
"__exit__()". Otherwise, '
'three\n'
' "None" arguments are supplied.\n'
'\n'
' If the suite was exited due to an exception, and the
return '
'value\n'
' from the "__exit__()" method was false, the
exception is '
'reraised.\n'
' If the return value was true, the exception is
suppressed, '
'and\n'
' execution continues with the statement following the
"with"\n'
' statement.\n'
'\n'
' If the suite was exited for any reason other than an
'
'exception, the\n'
' return value from "__exit__()" is ignored,
and execution '
'proceeds\n'
' at the normal location for the kind of exit that was
taken.\n'
'\n'
'With more than one item, the context managers are
processed as '
'if\n'
'multiple "with" statements were
nested:\n'
'\n'
' with A() as a, B() as b:\n'
' suite\n'
'\n'
'is equivalent to\n'
'\n'
' with A() as a:\n'
' with B() as b:\n'
' suite\n'
'\n'
'Changed in version 3.1: Support for multiple context
'
'expressions.\n'
'\n'
'See also:\n'
'\n'
' **PEP 343** - The “with” statement\n'
' The specification, background, and examples for the
Python '
'"with"\n'
' statement.\n'
'\n'
'\n'
'Function definitions\n'
'====================\n'
'\n'
'A function definition defines a user-defined function
object '
'(see\n'
'section The standard type hierarchy):\n'
'\n'
' funcdef ::= [decorators]
"def" funcname "(" '
'[parameter_list] ")"\n'
' ["->" expression]
":" suite\n'
' decorators ::= decorator+\n'
' decorator ::= "@" dotted_name
["(" '
'[argument_list [","]] ")"]
NEWLINE\n'
' dotted_name ::= identifier ("."
identifier)*\n'
' parameter_list ::= defparameter
("," defparameter)* '
'["," [parameter_list_starargs]]\n'
' | parameter_list_starargs\n'
' parameter_list_starargs ::= "*" [parameter]
("," '
'defparameter)* ["," ["**" parameter
[","]]]\n'
' | "**"
parameter [","]\n'
' parameter ::= identifier [":"
expression]\n'
' defparameter ::= parameter ["="
expression]\n'
' funcname ::= identifier\n'
'\n'
'A function definition is an executable statement. Its
execution '
'binds\n'
'the function name in the current local namespace to a
function '
'object\n'
'(a wrapper around the executable code for the function).
This\n'
'function object contains a reference to the current
global '
'namespace\n'
'as the global namespace to be used when the function is
called.\n'
'\n'
'The function definition does not execute the function
body; this '
'gets\n'
'executed only when the function is called. [2]\n'
'\n'
'A function definition may be wrapped by one or more
*decorator*\n'
'expressions. Decorator expressions are evaluated when
the '
'function is\n'
'defined, in the scope that contains the function
definition. '
'The\n'
'result must be a callable, which is invoked with the
function '
'object\n'
'as the only argument. The returned value is bound to the
'
'function name\n'
'instead of the function object. Multiple decorators are
applied '
'in\n'
'nested fashion. For example, the following code\n'
'\n'
' @f1(arg)\n'
' @f2\n'
' def func(): pass\n'
'\n'
'is roughly equivalent to\n'
'\n'
' def func(): pass\n'
' func = f1(arg)(f2(func))\n'
'\n'
'except that the original function is not temporarily
bound to '
'the name\n'
'"func".\n'
'\n'
'When one or more *parameters* have the form *parameter*
"="\n'
'*expression*, the function is said to have “default
parameter '
'values.”\n'
'For a parameter with a default value, the corresponding
'
'*argument* may\n'
'be omitted from a call, in which case the parameter’s
default '
'value is\n'
'substituted. If a parameter has a default value, all
following\n'
'parameters up until the “"*"” must also
have a default value — '
'this is\n'
'a syntactic restriction that is not expressed by the
grammar.\n'
'\n'
'**Default parameter values are evaluated from left to
right when '
'the\n'
'function definition is executed.** This means that the
'
'expression is\n'
'evaluated once, when the function is defined, and that
the same '
'“pre-\n'
'computed” value is used for each call. This is
especially '
'important\n'
'to understand when a default parameter is a mutable
object, such '
'as a\n'
'list or a dictionary: if the function modifies the
object (e.g. '
'by\n'
'appending an item to a list), the default value is in
effect '
'modified.\n'
'This is generally not what was intended. A way around
this is '
'to use\n'
'"None" as the default, and explicitly test for
it in the body of '
'the\n'
'function, e.g.:\n'
'\n'
' def whats_on_the_telly(penguin=None):\n'
' if penguin is None:\n'
' penguin = []\n'
' penguin.append("property of the
zoo")\n'
' return penguin\n'
'\n'
'Function call semantics are described in more detail in
section '
'Calls.\n'
'A function call always assigns values to all parameters
'
'mentioned in\n'
'the parameter list, either from position arguments, from
'
'keyword\n'
'arguments, or from default values. If the form
“"*identifier"” '
'is\n'
'present, it is initialized to a tuple receiving any
excess '
'positional\n'
'parameters, defaulting to the empty tuple. If the
form\n'
'“"**identifier"” is present, it is
initialized to a new ordered\n'
'mapping receiving any excess keyword arguments,
defaulting to a '
'new\n'
'empty mapping of the same type. Parameters after
“"*"” or\n'
'“"*identifier"” are keyword-only
parameters and may only be '
'passed\n'
'used keyword arguments.\n'
'\n'
'Parameters may have annotations of the form “":
expression"” '
'following\n'
'the parameter name. Any parameter may have an
annotation even '
'those\n'
'of the form "*identifier" or
"**identifier". Functions may '
'have\n'
'“return” annotation of the form “"->
expression"” after the '
'parameter\n'
'list. These annotations can be any valid Python
expression and '
'are\n'
'evaluated when the function definition is executed.
Annotations '
'may\n'
'be evaluated in a different order than they appear in
the source '
'code.\n'
'The presence of annotations does not change the
semantics of a\n'
'function. The annotation values are available as values
of a\n'
'dictionary keyed by the parameters’ names in the
'
'"__annotations__"\n'
'attribute of the function object.\n'
'\n'
'It is also possible to create anonymous functions
(functions not '
'bound\n'
'to a name), for immediate use in expressions. This uses
lambda\n'
'expressions, described in section Lambdas. Note that
the '
'lambda\n'
'expression is merely a shorthand for a simplified
function '
'definition;\n'
'a function defined in a “"def"” statement
can be passed around '
'or\n'
'assigned to another name just like a function defined by
a '
'lambda\n'
'expression. The “"def"” form is actually
more powerful since '
'it\n'
'allows the execution of multiple statements and
annotations.\n'
'\n'
'**Programmer’s note:** Functions are first-class
objects. A '
'“"def"”\n'
'statement executed inside a function definition defines
a local\n'
'function that can be returned or passed around. Free
variables '
'used\n'
'in the nested function can access the local variables of
the '
'function\n'
'containing the def. See section Naming and binding for
'
'details.\n'
'\n'
'See also:\n'
'\n'
' **PEP 3107** - Function Annotations\n'
' The original specification for function
annotations.\n'
'\n'
'\n'
'Class definitions\n'
'=================\n'
'\n'
'A class definition defines a class object (see section
The '
'standard\n'
'type hierarchy):\n'
'\n'
' classdef ::= [decorators] "class"
classname [inheritance] '
'":" suite\n'
' inheritance ::= "(" [argument_list]
")"\n'
' classname ::= identifier\n'
'\n'
'A class definition is an executable statement. The
inheritance '
'list\n'
'usually gives a list of base classes (see Metaclasses
for more\n'
'advanced uses), so each item in the list should evaluate
to a '
'class\n'
'object which allows subclassing. Classes without an
inheritance '
'list\n'
'inherit, by default, from the base class
"object"; hence,\n'
'\n'
' class Foo:\n'
' pass\n'
'\n'
'is equivalent to\n'
'\n'
' class Foo(object):\n'
' pass\n'
'\n'
'The class’s suite is then executed in a new execution
frame '
'(see\n'
'Naming and binding), using a newly created local
namespace and '
'the\n'
'original global namespace. (Usually, the suite contains
mostly\n'
'function definitions.) When the class’s suite
finishes '
'execution, its\n'
'execution frame is discarded but its local namespace is
saved. '
'[3] A\n'
'class object is then created using the inheritance list
for the '
'base\n'
'classes and the saved local namespace for the attribute
'
'dictionary.\n'
'The class name is bound to this class object in the
original '
'local\n'
'namespace.\n'
'\n'
'The order in which attributes are defined in the class
body is\n'
'preserved in the new class’s "__dict__".
Note that this is '
'reliable\n'
'only right after the class is created and only for
classes that '
'were\n'
'defined using the definition syntax.\n'
'\n'
'Class creation can be customized heavily using
metaclasses.\n'
'\n'
'Classes can also be decorated: just like when decorating
'
'functions,\n'
'\n'
' @f1(arg)\n'
' @f2\n'
' class Foo: pass\n'
'\n'
'is roughly equivalent to\n'
'\n'
' class Foo: pass\n'
' Foo = f1(arg)(f2(Foo))\n'
'\n'
'The evaluation rules for the decorator expressions are
the same '
'as for\n'
'function decorators. The result is then bound to the
class '
'name.\n'
'\n'
'**Programmer’s note:** Variables defined in the class
definition '
'are\n'
'class attributes; they are shared by instances.
Instance '
'attributes\n'
'can be set in a method with "self.name =
value". Both class '
'and\n'
'instance attributes are accessible through the notation
'
'“"self.name"”,\n'
'and an instance attribute hides a class attribute with
the same '
'name\n'
'when accessed in this way. Class attributes can be used
as '
'defaults\n'
'for instance attributes, but using mutable values there
can lead '
'to\n'
'unexpected results. Descriptors can be used to create
instance\n'
'variables with different implementation details.\n'
'\n'
'See also:\n'
'\n'
' **PEP 3115** - Metaclasses in Python 3000\n'
' The proposal that changed the declaration of
metaclasses to '
'the\n'
' current syntax, and the semantics for how classes
with\n'
' metaclasses are constructed.\n'
'\n'
' **PEP 3129** - Class Decorators\n'
' The proposal that added class decorators. Function
and '
'method\n'
' decorators were introduced in **PEP 318**.\n'
'\n'
'\n'
'Coroutines\n'
'==========\n'
'\n'
'New in version 3.5.\n'
'\n'
'\n'
'Coroutine function definition\n'
'-----------------------------\n'
'\n'
' async_funcdef ::= [decorators] "async"
"def" funcname "(" '
'[parameter_list] ")"\n'
' ["->" expression]
":" suite\n'
'\n'
'Execution of Python coroutines can be suspended and
resumed at '
'many\n'
'points (see *coroutine*). In the body of a coroutine,
any '
'"await" and\n'
'"async" identifiers become reserved keywords;
"await" '
'expressions,\n'
'"async for" and "async with" can
only be used in coroutine '
'bodies.\n'
'\n'
'Functions defined with "async def" syntax are
always coroutine\n'
'functions, even if they do not contain "await"
or "async" '
'keywords.\n'
'\n'
'It is a "SyntaxError" to use "yield
from" expressions in "async '
'def"\n'
'coroutines.\n'
'\n'
'An example of a coroutine function:\n'
'\n'
' async def func(param1, param2):\n'
' do_stuff()\n'
' await some_coroutine()\n'
'\n'
'\n'
'The "async for" statement\n'
'-------------------------\n'
'\n'
' async_for_stmt ::= "async" for_stmt\n'
'\n'
'An *asynchronous iterable* is able to call asynchronous
code in '
'its\n'
'*iter* implementation, and *asynchronous iterator* can
call\n'
'asynchronous code in its *next* method.\n'
'\n'
'The "async for" statement allows convenient
iteration over\n'
'asynchronous iterators.\n'
'\n'
'The following code:\n'
'\n'
' async for TARGET in ITER:\n'
' BLOCK\n'
' else:\n'
' BLOCK2\n'
'\n'
'Is semantically equivalent to:\n'
'\n'
' iter = (ITER)\n'
' iter = type(iter).__aiter__(iter)\n'
' running = True\n'
' while running:\n'
' try:\n'
' TARGET = await
type(iter).__anext__(iter)\n'
' except StopAsyncIteration:\n'
' running = False\n'
' else:\n'
' BLOCK\n'
' else:\n'
' BLOCK2\n'
'\n'
'See also "__aiter__()" and
"__anext__()" for details.\n'
'\n'
'It is a "SyntaxError" to use "async
for" statement outside of '
'an\n'
'"async def" 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'
' async with EXPR as VAR:\n'
' BLOCK\n'
'\n'
'Is semantically equivalent to:\n'
'\n'
' mgr = (EXPR)\n'
' aexit = type(mgr).__aexit__\n'
' aenter = type(mgr).__aenter__(mgr)\n'
'\n'
' VAR = await aenter\n'
' try:\n'
' BLOCK\n'
' except:\n'
' if not await aexit(mgr, *sys.exc_info()):\n'
' raise\n'
' else:\n'
' await aexit(mgr, None, None, None)\n'
'\n'
'See also "__aenter__()" and
"__aexit__()" for details.\n'
'\n'
'It is a "SyntaxError" to use "async
with" statement outside of '
'an\n'
'"async def" function.\n'
'\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'
'[1] The exception is propagated to the invocation stack
unless\n'
' there is a "finally" clause which happens
to raise another\n'
' exception. That new exception causes the old one to
be '
'lost.\n'
'\n'
'[2] A string literal appearing as the first statement in
the\n'
' function body is transformed into the function’s
"__doc__"\n'
' attribute and therefore the function’s
*docstring*.\n'
'\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
or '
'"finally"\n'
'clause within that loop. It continues with the next
cycle of '
'the\n'
'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'
'“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, '
'the\n'
' other 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'
'\n'
' If "__new__()" returns an instance of
*cls*, then the '
'new\n'
' instance’s "__init__()" method will
be invoked like\n'
' "__init__(self[, ...])", where *self*
is the new '
'instance and the\n'
' remaining arguments are the same as were passed
to '
'"__new__()".\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'
' called a finalizer or (improperly) a destructor.
If a '
'base class\n'
' has a "__del__()" method, the derived
class’s '
'"__del__()" method,\n'
' if any, must explicitly call it to ensure proper
'
'deletion of the\n'
' base class part of the instance.\n'
'\n'
' It is possible (though not recommended!) for the
'
'"__del__()" method\n'
' to postpone destruction of the instance by
creating a '
'new reference\n'
' to it. This is called object *resurrection*.
It is\n'
' implementation-dependent whether
"__del__()" is called a '
'second\n'
' time when a resurrected object is about to be
destroyed; '
'the\n'
' current *CPython* implementation only calls it
once.\n'
'\n'
' It is not guaranteed that "__del__()"
methods are called '
'for\n'
' objects that still exist when the interpreter
exits.\n'
'\n'
' Note: "del x" doesn’t directly call
"x.__del__()" — the '
'former\n'
' decrements the reference count for
"x" by one, and the '
'latter is\n'
' only called when "x"’s reference
count reaches zero.\n'
'\n'
' **CPython implementation detail:** It is
possible for a '
'reference\n'
' cycle to prevent the reference count of an
object from '
'going to\n'
' zero. In this case, the cycle will be later
detected '
'and deleted\n'
' by the *cyclic garbage collector*. A common
cause of '
'reference\n'
' cycles is when an exception has been caught in a
local '
'variable.\n'
' The frame’s locals then reference the
exception, which '
'references\n'
' its own traceback, which references the locals
of all '
'frames caught\n'
' in the traceback.\n'
'\n'
' See also: Documentation for the "gc"
module.\n'
'\n'
' Warning: Due to the precarious circumstances
under '
'which\n'
' "__del__()" methods are invoked,
exceptions that occur '
'during\n'
' their execution are ignored, and a warning is
printed '
'to\n'
' "sys.stderr" instead. In
particular:\n'
'\n'
' * "__del__()" can be invoked when
arbitrary code is '
'being\n'
' executed, including from any arbitrary
thread. If '
'"__del__()"\n'
' needs to take a lock or invoke any other
blocking '
'resource, it\n'
' may deadlock as the resource may already be
taken by '
'the code\n'
' that gets interrupted to execute
"__del__()".\n'
'\n'
' * "__del__()" can be executed during
interpreter '
'shutdown. As\n'
' a consequence, the global variables it needs
to '
'access\n'
' (including other modules) may already have
been '
'deleted or set\n'
' to "None". Python guarantees that
globals whose name '
'begins\n'
' with a single underscore are deleted from
their '
'module before\n'
' other globals are deleted; if no other
references to '
'such\n'
' globals exist, this may help in assuring
that '
'imported modules\n'
' are still available at the time when the
"__del__()" '
'method is\n'
' called.\n'
'\n'
'object.__repr__(self)\n'
'\n'
' 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'
' object. The "format_spec" argument is
a string that '
'contains a\n'
' description of the formatting options desired.
The '
'interpretation\n'
' 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'
'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'
' By default, "__ne__()" delegates to
"__eq__()" and '
'inverts the\n'
' result unless it is "NotImplemented".
There are no '
'other implied\n'
' relationships among the comparison operators,
for '
'example, the\n'
' truth of "(x<y or x==y)" does not
imply "x<=y". To '
'automatically\n'
' generate 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'
'\n'
' Note: "hash()" truncates the value
returned from an '
'object’s\n'
' custom "__hash__()" method to the
size of a '
'"Py_ssize_t". This\n'
' is typically 8 bytes on 64-bit builds and 4
bytes on '
'32-bit\n'
' builds. If an object’s
"__hash__()" must '
'interoperate on builds\n'
' of different bit sizes, be sure to check the
width on '
'all\n'
' supported builds. An easy way to do this is
with '
'"python -c\n'
' "import sys;
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,
'
'collections.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.Hashable)" '
'call.\n'
'\n'
' Note: By default, the "__hash__()"
values of str, bytes '
'and\n'
' datetime objects are “salted” with an
unpredictable '
'random value.\n'
' Although they remain constant within an
individual '
'Python\n'
' process, they are not predictable between
repeated '
'invocations of\n'
' Python.This is intended to provide protection
against '
'a denial-\n'
' of-service caused by carefully-chosen inputs
that '
'exploit the\n'
' worst case performance of a dict insertion,
O(n^2) '
'complexity.\n'
' See '
'http://www.ocert.org/advisories/ocert-2011-003.html
for\n'
' details.Changing hash values affects the
iteration '
'order of\n'
' dicts, sets and other mappings. Python has
never made '
'guarantees\n'
' about this ordering (and it typically varies
between '
'32-bit and\n'
' 64-bit builds).See also
"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'
'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'
'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()\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).\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'
' 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'
' 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 '
'follow\n'
' it immediately with "end"; that is, give no
commands.\n'
'\n'
' With no *bpnumber* argument, commands refers to the
last '
'breakpoint\n'
' 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 that\n'
' resumes execution.\n'
'\n'
' Specifying any command resuming execution (currently
'
'continue,\n'
' step, next, return, jump, quit and their
abbreviations) '
'terminates\n'
' the command list (as if that command was immediately
followed '
'by\n'
' end). This is because any time you resume execution
(even '
'with a\n'
' simple next or step), you may encounter another
'
'breakpoint—which\n'
' could have its own command list, leading to
ambiguities about '
'which\n'
' list to execute.\n'
'\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'
'\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'
' Note: "print()" can also be used, but is
not a debugger '
'command —\n'
' this 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'
'-[ Footnotes ]-\n'
'\n'
'[1] Whether a frame is considered to originate in a
certain '
'module\n'
' is 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'
'rightmost in the display) stored for a given key value
prevails.\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'
' if_stmt ::= "if" expression ":"
suite\n'
' ("elif" 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 backtrace, 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'
'Note: Exception messages are not part of the Python
API. '
'Their\n'
' contents may change from one version of Python to
the next '
'without\n'
' warning and should not be relied on by code which
will run '
'under\n'
' multiple 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 '
'by\n'
' these operations is not available at the time the
module '
'is\n'
' 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 '
'"-c"\n'
'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 backtrace, 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'
'Note: Exception messages are not part of the Python
API. '
'Their\n'
' contents may change from one version of Python to the
next '
'without\n'
' warning and should not be relied on by code which
will run '
'under\n'
' multiple 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 '
'by\n'
' these operations is not available at the time the
module '
'is\n'
' 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'
' starred_item ::= expression | "*"
or_expr\n'
'\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'
'\n'
'Some examples of floating point literals:\n'
'\n'
' 3.14 10. .001 1e100 3.14e-10 0e0
'
'3.14_15_93\n'
'\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(s) 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'
'Note: There is a subtlety when the sequence is being modified
by the\n'
' loop (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'
' current item will be treated again the next time through
the loop.\n'
' This can lead to nasty bugs that can be avoided by making
a\n'
' temporary copy using a slice of the whole sequence,
e.g.,\n'
'\n'
' for x in a[:]:\n'
' if x < 0: a.remove(x)\n',
'formatstrings': 'Format String Syntax\n'
'********************\n'
'\n'
'The "str.format()" method and the
"Formatter" class share '
'the same\n'
'syntax for format strings (although in the case of
'
'"Formatter",\n'
'subclasses can define their own format string
syntax). The '
'syntax is\n'
'related to that of formatted string literals, but
there '
'are\n'
'differences.\n'
'\n'
'Format strings contain “replacement fields”
surrounded by '
'curly braces\n'
'"{}". Anything that is not contained in
braces is '
'considered literal\n'
'text, which is copied unchanged to the output. If
you need '
'to include\n'
'a brace character in the literal text, it can be
escaped by '
'doubling:\n'
'"{{" and "}}".\n'
'\n'
'The grammar for a replacement field is as
follows:\n'
'\n'
' replacement_field ::= "{"
[field_name] ["!" '
'conversion] [":" format_spec]
"}"\n'
' field_name ::= arg_name ("."
attribute_name | '
'"[" element_index "]")*\n'
' arg_name ::= [identifier |
digit+]\n'
' attribute_name ::= identifier\n'
' element_index ::= digit+ |
index_string\n'
' index_string ::= <any source
character except '
'"]"> +\n'
' conversion ::= "r" |
"s" | "a"\n'
' format_spec ::= <described in the
next '
'section>\n'
'\n'
'In less formal terms, the replacement field can
start with '
'a\n'
'*field_name* that specifies the object whose value
is to be '
'formatted\n'
'and inserted into the output instead of the
replacement '
'field. The\n'
'*field_name* is optionally followed by a
*conversion* '
'field, which is\n'
'preceded by an exclamation point
"\'!\'", and a '
'*format_spec*, which is\n'
'preceded by a colon "\':\'".
These specify a non-default '
'format for the\n'
'replacement value.\n'
'\n'
'See also the Format Specification Mini-Language
section.\n'
'\n'
'The *field_name* itself begins with an *arg_name*
that is '
'either a\n'
'number or a keyword. If it’s a number, it refers
to a '
'positional\n'
'argument, and if it’s a keyword, it refers to a
named '
'keyword\n'
'argument. If the numerical arg_names in a format
string '
'are 0, 1, 2,\n'
'… in sequence, they can all be omitted (not just
some) and '
'the numbers\n'
'0, 1, 2, … will be automatically inserted in that
order. '
'Because\n'
'*arg_name* is not quote-delimited, it is not
possible to '
'specify\n'
'arbitrary dictionary keys (e.g., the strings
"\'10\'" or '
'"\':-]\'") within\n'
'a format string. The *arg_name* can be followed by
any '
'number of index\n'
'or attribute expressions. An expression of the form
'
'"\'.name\'" selects\n'
'the named attribute using "getattr()",
while an expression '
'of the form\n'
'"\'[index]\'" does an index
lookup using "__getitem__()".\n'
'\n'
'Changed in version 3.1: The positional argument
specifiers '
'can be\n'
'omitted for "str.format()", so
"\'{} {}\'.format(a, b)" is '
'equivalent to\n'
'"\'{0} {1}\'.format(a,
b)".\n'
'\n'
'Changed in version 3.4: The positional argument
specifiers '
'can be\n'
'omitted for "Formatter".\n'
'\n'
'Some simple format string examples:\n'
'\n'
' "First, thou shalt count to {0}" #
References first '
'positional argument\n'
' "Bring me a {}" #
Implicitly '
'references the first positional argument\n'
' "From {} to {}" #
Same as "From {0} to '
'{1}"\n'
' "My quest is {name}" #
References keyword '
"argument 'name'\n"
' "Weight in tons {0.weight}" #
\'weight\' attribute '
'of first positional arg\n'
' "Units destroyed: {players[0]}" #
First element of '
"keyword argument 'players'.\n"
'\n'
'The *conversion* field causes a type coercion
before '
'formatting.\n'
'Normally, the job of formatting a value is done by
the '
'"__format__()"\n'
'method of the value itself. However, in some cases
it is '
'desirable to\n'
'force a type to be formatted as a string,
overriding its '
'own\n'
'definition of formatting. By converting the value
to a '
'string before\n'
'calling "__format__()", the normal
formatting logic is '
'bypassed.\n'
'\n'
'Three conversion flags are currently supported:
"\'!s\'" '
'which calls\n'
'"str()" on the value,
"\'!r\'" which calls "repr()" and '
'"\'!a\'" which\n'
'calls "ascii()".\n'
'\n'
'Some examples:\n'
'\n'
' "Harold\'s a clever {0!s}"
# Calls str() on the '
'argument first\n'
' "Bring out the holy {name!r}" #
Calls repr() on the '
'argument first\n'
' "More {!a}" #
Calls ascii() on the '
'argument first\n'
'\n'
'The *format_spec* field contains a specification of
how the '
'value\n'
'should be presented, including such details as
field width, '
'alignment,\n'
'padding, decimal precision and so on. Each value
type can '
'define its\n'
'own “formatting mini-language” or
interpretation of the '
'*format_spec*.\n'
'\n'
'Most built-in types support a common formatting
'
'mini-language, which\n'
'is described in the next section.\n'
'\n'
'A *format_spec* field can also include nested
replacement '
'fields\n'
'within it. These nested replacement fields may
contain a '
'field name,\n'
'conversion flag and format specification, but
deeper '
'nesting is not\n'
'allowed. The replacement fields within the
format_spec '
'are\n'
'substituted before the *format_spec* string is
interpreted. '
'This\n'
'allows the formatting of a value to be dynamically
'
'specified.\n'
'\n'
'See the Format examples section for some
examples.\n'
'\n'
'\n'
'Format Specification Mini-Language\n'
'==================================\n'
'\n'
'“Format specifications” are used within
replacement fields '
'contained\n'
'within a format string to define how individual
values are '
'presented\n'
'(see Format String Syntax and Formatted string
literals). '
'They can\n'
'also be passed directly to the built-in
"format()" '
'function. Each\n'
'formattable type may define how the format
specification is '
'to be\n'
'interpreted.\n'
'\n'
'Most built-in types implement the following options
for '
'format\n'
'specifications, although some of the formatting
options are '
'only\n'
'supported by the numeric types.\n'
'\n'
'A general convention is that an empty format string
("""") '
'produces\n'
'the same result as if you had called
"str()" on the value. '
'A non-empty\n'
'format string typically modifies the
result.\n'
'\n'
'The general form of a *standard format specifier*
is:\n'
'\n'
' format_spec ::= '
'[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n'
' fill ::= <any
character>\n'
' align ::= "<" |
">" | "=" | "^"\n'
' sign ::= "+" |
"-" | " "\n'
' width ::= digit+\n'
' grouping_option ::= "_" |
","\n'
' precision ::= digit+\n'
' type ::= "b" |
"c" | "d" | "e" | "E" |
"f" | '
'"F" | "g" | "G" |
"n" | "o" | "s" | "x" |
"X" | "%"\n'
'\n'
'If a valid *align* value is specified, it can be
preceded '
'by a *fill*\n'
'character that can be any character and defaults to
a space '
'if\n'
'omitted. It is not possible to use a literal curly
brace '
'(“"{"” or\n'
'“"}"”) as the *fill* character in a
formatted string '
'literal or when\n'
'using the "str.format()" method.
However, it is possible '
'to insert a\n'
'curly brace with a nested replacement field. This
'
'limitation doesn’t\n'
'affect the "format()" function.\n'
'\n'
'The meaning of the various alignment options is as
'
'follows:\n'
'\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | Option | '
'Meaning
'
'|\n'
' '
'+===========+============================================================+\n'
' | "\'<\'" | Forces
the field to be left-aligned '
'within the available |\n'
' | | space (this is the default for
most '
'objects). |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'>\'" | Forces
the field to be right-aligned '
'within the available |\n'
' | | space (this is the default for
'
'numbers). |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'=\'" | Forces the
padding to be placed after '
'the sign (if any) |\n'
' | | but before the digits. This is
used for '
'printing fields |\n'
' | | in the form ‘+000000120’. This
alignment '
'option is only |\n'
' | | valid for numeric types. It
becomes the '
'default when ‘0’ |\n'
' | | immediately precedes the field
'
'width. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'^\'" | Forces the
field to be centered within '
'the available |\n'
' | | '
'space.
'
'|\n'
' '
'+-----------+------------------------------------------------------------+\n'
'\n'
'Note that unless a minimum field width is defined,
the '
'field width\n'
'will always be the same size as the data to fill
it, so '
'that the\n'
'alignment option has no meaning in this
case.\n'
'\n'
'The *sign* option is only valid for number types,
and can '
'be one of\n'
'the following:\n'
'\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | Option | '
'Meaning
'
'|\n'
' '
'+===========+============================================================+\n'
' | "\'+\'" | indicates
that a sign should be used for '
'both positive as |\n'
' | | well as negative '
'numbers. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'-\'" | indicates
that a sign should be used '
'only for negative |\n'
' | | numbers (this is the default
'
'behavior). |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | space | indicates that a leading space
should be '
'used on positive |\n'
' | | numbers, and a minus sign on
negative '
'numbers. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
'\n'
'The "\'#\'" option causes the
“alternate form” to be used '
'for the\n'
'conversion. The alternate form is defined
differently for '
'different\n'
'types. This option is only valid for integer,
float, '
'complex and\n'
'Decimal types. For integers, when binary, octal, or
'
'hexadecimal output\n'
'is used, this option adds the prefix respective
"\'0b\'", '
'"\'0o\'", or\n'
'"\'0x\'" to the output value.
For floats, complex and '
'Decimal the\n'
'alternate form causes the result of the conversion
to '
'always contain a\n'
'decimal-point character, even if no digits follow
it. '
'Normally, a\n'
'decimal-point character appears in the result of
these '
'conversions\n'
'only if a digit follows it. In addition, for
"\'g\'" and '
'"\'G\'"\n'
'conversions, trailing zeros are not removed from
the '
'result.\n'
'\n'
'The "\',\'" option signals the
use of a comma for a '
'thousands separator.\n'
'For a locale aware separator, use the
"\'n\'" integer '
'presentation type\n'
'instead.\n'
'\n'
'Changed in version 3.1: Added the
"\',\'" option (see also '
'**PEP 378**).\n'
'\n'
'The "\'_\'" option signals the
use of an underscore for a '
'thousands\n'
'separator for floating point presentation types and
for '
'integer\n'
'presentation type "\'d\'". For
integer presentation types '
'"\'b\'",
"\'o\'",\n'
'"\'x\'", and
"\'X\'", underscores will be inserted every 4 '
'digits. For\n'
'other presentation types, specifying this option is
an '
'error.\n'
'\n'
'Changed in version 3.6: Added the
"\'_\'" option (see also '
'**PEP 515**).\n'
'\n'
'*width* is a decimal integer defining the minimum
field '
'width. If not\n'
'specified, then the field width will be determined
by the '
'content.\n'
'\n'
'When no explicit alignment is given, preceding the
*width* '
'field by a\n'
'zero ("\'0\'") character
enables sign-aware zero-padding '
'for numeric\n'
'types. This is equivalent to a *fill* character of
"\'0\'" '
'with an\n'
'*alignment* type of
"\'=\'".\n'
'\n'
'The *precision* is a decimal number indicating how
many '
'digits should\n'
'be displayed after the decimal point for a floating
point '
'value\n'
'formatted with "\'f\'" and
"\'F\'", or before and after the '
'decimal point\n'
'for a floating point value formatted with
"\'g\'" or '
'"\'G\'". For non-\n'
'number types the field indicates the maximum field
size - '
'in other\n'
'words, how many characters will be used from the
field '
'content. The\n'
'*precision* is not allowed for integer
values.\n'
'\n'
'Finally, the *type* determines how the data should
be '
'presented.\n'
'\n'
'The available string presentation types
are:\n'
'\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | Type | '
'Meaning
'
'|\n'
' '
'+===========+============================================================+\n'
' | "\'s\'" | String
format. This is the default type '
'for strings and |\n'
' | | may be '
'omitted.
|\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | None | The same as '
'"\'s\'".
|\n'
' '
'+-----------+------------------------------------------------------------+\n'
'\n'
'The available integer presentation types
are:\n'
'\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | Type | '
'Meaning
'
'|\n'
' '
'+===========+============================================================+\n'
' | "\'b\'" | Binary
format. Outputs the number in '
'base 2. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'c\'" | Character.
Converts the integer to the '
'corresponding |\n'
' | | unicode character before '
'printing. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'d\'" | Decimal
Integer. Outputs the number in '
'base 10. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'o\'" | Octal
format. Outputs the number in base '
'8. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'x\'" | Hex format.
Outputs the number in base '
'16, using lower- |\n'
' | | case letters for the digits above
'
'9. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'X\'" | Hex format.
Outputs the number in base '
'16, using upper- |\n'
' | | case letters for the digits above
'
'9. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'n\'" | Number. This
is the same as "\'d\'", '
'except that it uses the |\n'
' | | current locale setting to insert
the '
'appropriate number |\n'
' | | separator '
'characters.
|\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | None | The same as '
'"\'d\'".
|\n'
' '
'+-----------+------------------------------------------------------------+\n'
'\n'
'In addition to the above presentation types,
integers can '
'be formatted\n'
'with the floating point presentation types listed
below '
'(except "\'n\'"\n'
'and "None"). When doing so,
"float()" is used to convert '
'the integer\n'
'to a floating point number before
formatting.\n'
'\n'
'The available presentation types for floating point
and '
'decimal values\n'
'are:\n'
'\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | Type | '
'Meaning
'
'|\n'
' '
'+===========+============================================================+\n'
' | "\'e\'" | Exponent
notation. Prints the number in '
'scientific |\n'
' | | notation using the letter ‘e’
to indicate '
'the exponent. |\n'
' | | The default precision is '
'"6".
|\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'E\'" | Exponent
notation. Same as "\'e\'" '
'except it uses an upper |\n'
' | | case ‘E’ as the separator
'
'character. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'f\'" | Fixed-point
notation. Displays the '
'number as a fixed-point |\n'
' | | number. The default precision is
'
'"6". |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'F\'" | Fixed-point
notation. Same as "\'f\'", '
'but converts "nan" to |\n'
' | | "NAN" and
"inf" to '
'"INF".
|\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'g\'" | General
format. For a given precision '
'"p >= 1", this |\n'
' | | rounds the number to "p"
significant '
'digits and then |\n'
' | | formats the result in either
fixed-point '
'format or in |\n'
' | | scientific notation, depending on
its '
'magnitude. The |\n'
' | | precise rules are as follows:
suppose that '
'the result |\n'
' | | formatted with presentation type
"\'e\'" '
'and precision "p-1" |\n'
' | | would have exponent
"exp". Then if "-4 <= '
'exp < p", the |\n'
' | | number is formatted with
presentation type '
'"\'f\'" and |\n'
' | | precision "p-1-exp".
Otherwise, the '
'number is formatted |\n'
' | | with presentation type
"\'e\'" and '
'precision "p-1". In both |\n'
' | | cases insignificant trailing zeros
are '
'removed from the |\n'
' | | significand, and the decimal point
is also '
'removed if |\n'
' | | there are no remaining digits
following '
'it. Positive and |\n'
' | | negative infinity, positive and
negative '
'zero, and nans, |\n'
' | | are formatted as "inf",
"-inf", "0", "-0" '
'and "nan" |\n'
' | | respectively, regardless of the
'
'precision. A precision of |\n'
' | | "0" is treated as
equivalent to a '
'precision of "1". The |\n'
' | | default precision is '
'"6".
|\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'G\'" | General
format. Same as "\'g\'" except '
'switches to "\'E\'" if
|\n'
' | | the number gets too large. The
'
'representations of infinity |\n'
' | | and NaN are uppercased, '
'too. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'n\'" | Number. This
is the same as "\'g\'", '
'except that it uses the |\n'
' | | current locale setting to insert
the '
'appropriate number |\n'
' | | separator '
'characters.
|\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | "\'%\'" | Percentage.
Multiplies the number by 100 '
'and displays in |\n'
' | | fixed
("\'f\'") format, followed by a '
'percent sign. |\n'
' '
'+-----------+------------------------------------------------------------+\n'
' | None | Similar to
"\'g\'", except that '
'fixed-point notation, when |\n'
' | | used, has at least one digit past
the '
'decimal point. The |\n'
' | | default precision is as high as
needed to '
'represent the |\n'
' | | particular value. The overall
effect is to '
'match the |\n'
' | | output of "str()" as
altered by the other '
'format |\n'
' | | '
'modifiers.
'
'|\n'
' '
'+-----------+------------------------------------------------------------+\n'
'\n'
'\n'
'Format examples\n'
'===============\n'
'\n'
'This section contains examples of the
"str.format()" syntax '
'and\n'
'comparison with the old
"%"-formatting.\n'
'\n'
'In most of the cases the syntax is similar to the
old '
'"%"-formatting,\n'
'with the addition of the "{}" and with
":" used instead of '
'"%". For\n'
'example, "\'%03.2f\'" can be
translated to "\'{:03.2f}\'".\n'
'\n'
'The new format syntax also supports new and
different '
'options, shown\n'
'in the following examples.\n'
'\n'
'Accessing arguments by position:\n'
'\n'
" >>> '{0}, {1},
{2}'.format('a', 'b', 'c')\n"
" 'a, b, c'\n"
" >>> '{}, {},
{}'.format('a', 'b', 'c') # 3.1+
only\n"
" 'a, b, c'\n"
" >>> '{2}, {1},
{0}'.format('a', 'b', 'c')\n"
" 'c, b, a'\n"
" >>> '{2}, {1},
{0}'.format(*'abc') # unpacking "
'argument sequence\n'
" 'c, b, a'\n"
" >>>
'{0}{1}{0}'.format('abra', 'cad') #
arguments' "
'indices can be repeated\n'
" 'abracadabra'\n"
'\n'
'Accessing arguments by name:\n'
'\n'
" >>> 'Coordinates: {latitude},
"
"{longitude}'.format(latitude='37.24N', "
"longitude='-115.81W')\n"
" 'Coordinates: 37.24N,
-115.81W'\n"
" >>> coord = {'latitude':
'37.24N', 'longitude': "
"'-115.81W'}\n"
" >>> 'Coordinates: {latitude},
"
"{longitude}'.format(**coord)\n"
" 'Coordinates: 37.24N,
-115.81W'\n"
'\n'
'Accessing arguments’ attributes:\n'
'\n'
' >>> c = 3-5j\n'
" >>> ('The complex number {0} is
formed from the real "
"part {0.real} '\n"
" ... 'and the imaginary part
{0.imag}.').format(c)\n"
" 'The complex number (3-5j) is formed from
the real part "
"3.0 and the imaginary part -5.0.'\n"
' >>> class Point:\n'
' ... def __init__(self, x, y):\n'
' ... self.x, self.y = x, y\n'
' ... def __str__(self):\n'
" ... return 'Point({self.x}, "
"{self.y})'.format(self=self)\n"
' ...\n'
' >>> str(Point(4, 2))\n'
" 'Point(4, 2)'\n"
'\n'
'Accessing arguments’ items:\n'
'\n'
' >>> coord = (3, 5)\n'
" >>> 'X: {0[0]}; Y:
{0[1]}'.format(coord)\n"
" 'X: 3; Y: 5'\n"
'\n'
'Replacing "%s" and
"%r":\n'
'\n'
' >>> "repr() shows quotes: {!r};
str() doesn\'t: '
'{!s}".format(\'test1\',
\'test2\')\n'
' "repr() shows quotes: \'test1\';
str() doesn\'t: test2"\n'
'\n'
'Aligning the text and specifying a width:\n'
'\n'
" >>>
'{:<30}'.format('left aligned')\n"
" 'left aligned
'\n"
" >>>
'{:>30}'.format('right aligned')\n"
" ' right
aligned'\n"
" >>>
'{:^30}'.format('centered')\n"
" ' centered
'\n"
" >>>
'{:*^30}'.format('centered') # use '*' as a
fill "
'char\n'
"
'***********centered***********'\n"
'\n'
'Replacing "%+f", "%-f", and
"% f" and specifying a sign:\n'
'\n'
" >>> '{:+f};
{:+f}'.format(3.14, -3.14) # show it "
'always\n'
" '+3.140000; -3.140000'\n"
" >>> '{: f}; {:
f}'.format(3.14, -3.14) # show a space "
'for positive numbers\n'
" ' 3.140000; -3.140000'\n"
" >>> '{:-f};
{:-f}'.format(3.14, -3.14) # show only the "
"minus -- same as '{:f}; {:f}'\n"
" '3.140000; -3.140000'\n"
'\n'
'Replacing "%x" and "%o" and
converting the value to '
'different bases:\n'
'\n'
' >>> # format also supports binary
numbers\n'
' >>> "int: {0:d}; hex: {0:x};
oct: {0:o}; bin: '
'{0:b}".format(42)\n'
" 'int: 42; hex: 2a; oct: 52; bin:
101010'\n"
' >>> # with 0x, 0o, or 0b as
prefix:\n'
' >>> "int: {0:d}; hex: {0:#x};
oct: {0:#o}; bin: '
'{0:#b}".format(42)\n'
" 'int: 42; hex: 0x2a; oct: 0o52; bin:
0b101010'\n"
'\n'
'Using the comma as a thousands separator:\n'
'\n'
" >>>
'{:,}'.format(1234567890)\n"
" '1,234,567,890'\n"
'\n'
'Expressing a percentage:\n'
'\n'
' >>> points = 19\n'
' >>> total = 22\n'
" >>> 'Correct answers:
{:.2%}'.format(points/total)\n"
" 'Correct answers: 86.36%'\n"
'\n'
'Using type-specific formatting:\n'
'\n'
' >>> import datetime\n'
' >>> d = datetime.datetime(2010, 7, 4,
12, 15, 58)\n'
" >>> '{:%Y-%m-%d
%H:%M:%S}'.format(d)\n"
" '2010-07-04 12:15:58'\n"
'\n'
'Nesting arguments and more complex
examples:\n'
'\n'
" >>> for align, text in
zip('<^>', ['left', 'center', "
"'right']):\n"
" ...
'{0:{fill}{align}16}'.format(text, fill=align, "
'align=align)\n'
' ...\n'
"
'left<<<<<<<<<<<<'\n"
" '^^^^^center^^^^^'\n"
"
'>>>>>>>>>>>right'\n"
' >>>\n'
' >>> octets = [192, 168, 0, 1]\n'
" >>>
'{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n"
" 'C0A80001'\n"
' >>> int(_, 16)\n'
' 3232235521\n'
' >>>\n'
' >>> width = 5\n'
' >>> for num in range(5,12): \n'
" ... for base in 'dXob':\n"
" ...
print('{0:{width}{base}}'.format(num, "
"base=base, width=width), end=' ')\n"
' ... print()\n'
' ...\n'
' 5 5 5 101\n'
' 6 6 6 110\n'
' 7 7 7 111\n'
' 8 8 10 1000\n'
' 9 9 11 1001\n'
' 10 A 12 1010\n'
' 11 B 13 1011\n',
'function': 'Function definitions\n'
'********************\n'
'\n'
'A function definition defines a user-defined function
object '
'(see\n'
'section The standard type hierarchy):\n'
'\n'
' funcdef ::= [decorators]
"def" funcname "(" '
'[parameter_list] ")"\n'
' ["->" expression]
":" suite\n'
' decorators ::= decorator+\n'
' decorator ::= "@" dotted_name
["(" '
'[argument_list [","]] ")"]
NEWLINE\n'
' dotted_name ::= identifier ("."
identifier)*\n'
' parameter_list ::= defparameter
("," defparameter)* '
'["," [parameter_list_starargs]]\n'
' | parameter_list_starargs\n'
' parameter_list_starargs ::= "*" [parameter]
("," '
'defparameter)* ["," ["**" parameter
[","]]]\n'
' | "**"
parameter [","]\n'
' parameter ::= identifier [":"
expression]\n'
' defparameter ::= parameter ["="
expression]\n'
' funcname ::= identifier\n'
'\n'
'A function definition is an executable statement. Its
execution '
'binds\n'
'the function name in the current local namespace to a
function '
'object\n'
'(a wrapper around the executable code for the function).
This\n'
'function object contains a reference to the current
global '
'namespace\n'
'as the global namespace to be used when the function is
called.\n'
'\n'
'The function definition does not execute the function
body; this '
'gets\n'
'executed only when the function is called. [2]\n'
'\n'
'A function definition may be wrapped by one or more
*decorator*\n'
'expressions. Decorator expressions are evaluated when
the '
'function is\n'
'defined, in the scope that contains the function
definition. '
'The\n'
'result must be a callable, which is invoked with the
function '
'object\n'
'as the only argument. The returned value is bound to the
'
'function name\n'
'instead of the function object. Multiple decorators are
applied '
'in\n'
'nested fashion. For example, the following code\n'
'\n'
' @f1(arg)\n'
' @f2\n'
' def func(): pass\n'
'\n'
'is roughly equivalent to\n'
'\n'
' def func(): pass\n'
' func = f1(arg)(f2(func))\n'
'\n'
'except that the original function is not temporarily
bound to '
'the name\n'
'"func".\n'
'\n'
'When one or more *parameters* have the form *parameter*
"="\n'
'*expression*, the function is said to have “default
parameter '
'values.”\n'
'For a parameter with a default value, the corresponding
'
'*argument* may\n'
'be omitted from a call, in which case the parameter’s
default '
'value is\n'
'substituted. If a parameter has a default value, all
following\n'
'parameters up until the “"*"” must also
have a default value — '
'this is\n'
'a syntactic restriction that is not expressed by the
grammar.\n'
'\n'
'**Default parameter values are evaluated from left to
right when '
'the\n'
'function definition is executed.** This means that the
'
'expression is\n'
'evaluated once, when the function is defined, and that
the same '
'“pre-\n'
'computed” value is used for each call. This is
especially '
'important\n'
'to understand when a default parameter is a mutable
object, such '
'as a\n'
'list or a dictionary: if the function modifies the
object (e.g. '
'by\n'
'appending an item to a list), the default value is in
effect '
'modified.\n'
'This is generally not what was intended. A way around
this is '
'to use\n'
'"None" as the default, and explicitly test for
it in the body of '
'the\n'
'function, e.g.:\n'
'\n'
' def whats_on_the_telly(penguin=None):\n'
' if penguin is None:\n'
' penguin = []\n'
' penguin.append("property of the
zoo")\n'
' return penguin\n'
'\n'
'Function call semantics are described in more detail in
section '
'Calls.\n'
'A function call always assigns values to all parameters
'
'mentioned in\n'
'the parameter list, either from position arguments, from
'
'keyword\n'
'arguments, or from default values. If the form
“"*identifier"” '
'is\n'
'present, it is initialized to a tuple receiving any
excess '
'positional\n'
'parameters, defaulting to the empty tuple. If the
form\n'
'“"**identifier"” is present, it is
initialized to a new ordered\n'
'mapping receiving any excess keyword arguments,
defaulting to a '
'new\n'
'empty mapping of the same type. Parameters after
“"*"” or\n'
'“"*identifier"” are keyword-only
parameters and may only be '
'passed\n'
'used keyword arguments.\n'
'\n'
'Parameters may have annotations of the form “":
expression"” '
'following\n'
'the parameter name. Any parameter may have an
annotation even '
'those\n'
'of the form "*identifier" or
"**identifier". Functions may '
'have\n'
'“return” annotation of the form “"->
expression"” after the '
'parameter\n'
'list. These annotations can be any valid Python
expression and '
'are\n'
'evaluated when the function definition is executed.
Annotations '
'may\n'
'be evaluated in a different order than they appear in
the source '
'code.\n'
'The presence of annotations does not change the
semantics of a\n'
'function. The annotation values are available as values
of a\n'
'dictionary keyed by the parameters’ names in the
'
'"__annotations__"\n'
'attribute of the function object.\n'
'\n'
'It is also possible to create anonymous functions
(functions not '
'bound\n'
'to a name), for immediate use in expressions. This uses
lambda\n'
'expressions, described in section Lambdas. Note that
the '
'lambda\n'
'expression is merely a shorthand for a simplified
function '
'definition;\n'
'a function defined in a “"def"” statement
can be passed around '
'or\n'
'assigned to another name just like a function defined by
a '
'lambda\n'
'expression. The “"def"” form is actually
more powerful since '
'it\n'
'allows the execution of multiple statements and
annotations.\n'
'\n'
'**Programmer’s note:** Functions are first-class
objects. A '
'“"def"”\n'
'statement executed inside a function definition defines
a local\n'
'function that can be returned or passed around. Free
variables '
'used\n'
'in the nested function can access the local variables of
the '
'function\n'
'containing the def. See section Naming and binding for
'
'details.\n'
'\n'
'See also:\n'
'\n'
' **PEP 3107** - Function Annotations\n'
' The original specification for function
annotations.\n',
'global': 'The "global" statement\n'
'**********************\n'
'\n'
' global_stmt ::= "global" identifier
("," identifier)*\n'
'\n'
'The "global" statement is a declaration which
holds for the '
'entire\n'
'current code block. It means that the listed identifiers
are to '
'be\n'
'interpreted as globals. It would be impossible to assign
to a '
'global\n'
'variable without "global", although free
variables may refer to\n'
'globals without being declared global.\n'
'\n'
'Names listed in a "global" statement must not be
used in the same '
'code\n'
'block textually preceding that "global"
statement.\n'
'\n'
'Names listed in a "global" statement must not be
defined as '
'formal\n'
'parameters or in a "for" loop control target,
"class" definition,\n'
'function definition, "import" statement, or
variable annotation.\n'
'\n'
'**CPython implementation detail:** The current
implementation does '
'not\n'
'enforce some of these restrictions, but programs should
not abuse '
'this\n'
'freedom, as future implementations may enforce them or
silently '
'change\n'
'the meaning of the program.\n'
'\n'
'**Programmer’s note:** "global" is a directive
to the parser. It\n'
'applies only to code parsed at the same time as the
"global"\n'
'statement. In particular, a "global" statement
contained in a '
'string\n'
'or code object supplied to the built-in "exec()"
function does '
'not\n'
'affect the code block *containing* the function call, and
code\n'
'contained in such a string is unaffected by
"global" statements in '
'the\n'
'code containing the function call. The same applies to
the '
'"eval()"\n'
'and "compile()" functions.\n',
'id-classes': 'Reserved classes of identifiers\n'
'*******************************\n'
'\n'
'Certain classes of identifiers (besides keywords) have
'
'special\n'
'meanings. These classes are identified by the
patterns of '
'leading and\n'
'trailing underscore characters:\n'
'\n'
'"_*"\n'
' Not imported by "from module import *".
The special '
'identifier "_"\n'
' is used in the interactive interpreter to store the
result '
'of the\n'
' last evaluation; it is stored in the
"builtins" module. '
'When not\n'
' in interactive mode, "_" has no special
meaning and is not '
'defined.\n'
' See section The import statement.\n'
'\n'
' Note: The name "_" is often used in
conjunction with\n'
' internationalization; refer to the documentation
for the\n'
' "gettext" module for more information
on this '
'convention.\n'
'\n'
'"__*__"\n'
' System-defined names. These names are defined by
the '
'interpreter\n'
' and its implementation (including the standard
library). '
'Current\n'
' system names are discussed in the Special method
names '
'section and\n'
' elsewhere. More will likely be defined in future
versions '
'of\n'
' Python. *Any* use of "__*__" names, in
any context, that '
'does not\n'
' follow explicitly documented use, is subject to
breakage '
'without\n'
' warning.\n'
'\n'
'"__*"\n'
' Class-private names. Names in this category, when
used '
'within the\n'
' context of a class definition, are re-written to
use a '
'mangled form\n'
' to help avoid name clashes between “private”
attributes of '
'base and\n'
' derived classes. See section Identifiers
(Names).\n',
'identifiers': 'Identifiers and keywords\n'
'************************\n'
'\n'
'Identifiers (also referred to as *names*) are
described by '
'the\n'
'following lexical definitions.\n'
'\n'
'The syntax of identifiers in Python is based on the
Unicode '
'standard\n'
'annex UAX-31, with elaboration and changes as defined
below; '
'see also\n'
'**PEP 3131** for further details.\n'
'\n'
'Within the ASCII range (U+0001..U+007F), the valid
characters '
'for\n'
'identifiers are the same as in Python 2.x: the
uppercase and '
'lowercase\n'
'letters "A" through "Z", the
underscore "_" and, except for '
'the first\n'
'character, the digits "0" through
"9".\n'
'\n'
'Python 3.0 introduces additional characters from
outside the '
'ASCII\n'
'range (see **PEP 3131**). For these characters, the
'
'classification\n'
'uses the version of the Unicode Character Database as
'
'included in the\n'
'"unicodedata" module.\n'
'\n'
'Identifiers are unlimited in length. Case is
significant.\n'
'\n'
' identifier ::= xid_start xid_continue*\n'
' id_start ::= <all characters in general
categories Lu, '
'Ll, Lt, Lm, Lo, Nl, the underscore, and characters
with the '
'Other_ID_Start property>\n'
' id_continue ::= <all characters in id_start,
plus '
'characters in the categories Mn, Mc, Nd, Pc and
others with '
'the Other_ID_Continue property>\n'
' xid_start ::= <all characters in id_start
whose NFKC '
'normalization is in "id_start
xid_continue*">\n'
' xid_continue ::= <all characters in id_continue
whose NFKC '
'normalization is in
"id_continue*">\n'
'\n'
'The Unicode category codes mentioned above stand
for:\n'
'\n'
'* *Lu* - uppercase letters\n'
'\n'
'* *Ll* - lowercase letters\n'
'\n'
'* *Lt* - titlecase letters\n'
'\n'
'* *Lm* - modifier letters\n'
'\n'
'* *Lo* - other letters\n'
'\n'
'* *Nl* - letter numbers\n'
'\n'
'* *Mn* - nonspacing marks\n'
'\n'
'* *Mc* - spacing combining marks\n'
'\n'
'* *Nd* - decimal numbers\n'
'\n'
'* *Pc* - connector punctuations\n'
'\n'
'* *Other_ID_Start* - explicit list of characters in
'
'PropList.txt to\n'
' support backwards compatibility\n'
'\n'
'* *Other_ID_Continue* - likewise\n'
'\n'
'All identifiers are converted into the normal form
NFKC while '
'parsing;\n'
'comparison of identifiers is based on NFKC.\n'
'\n'
'A non-normative HTML file listing all valid
identifier '
'characters for\n'
'Unicode 4.1 can be found at
https://www.dcl.hpi.uni-\n'
'potsdam.de/home/loewis/table-3131.html.\n'
'\n'
'\n'
'Keywords\n'
'========\n'
'\n'
'The following identifiers are used as reserved words,
or '
'*keywords* of\n'
'the language, and cannot be used as ordinary
identifiers. '
'They must\n'
'be spelled exactly as written here:\n'
'\n'
' False class finally is
return\n'
' None continue for lambda
try\n'
' True def from nonlocal
while\n'
' and del global not
with\n'
' as elif if or
yield\n'
' assert else import pass\n'
' break except in raise\n'
'\n'
'\n'
'Reserved classes of identifiers\n'
'===============================\n'
'\n'
'Certain classes of identifiers (besides keywords)
have '
'special\n'
'meanings. These classes are identified by the
patterns of '
'leading and\n'
'trailing underscore characters:\n'
'\n'
'"_*"\n'
' Not imported by "from module import *".
The special '
'identifier "_"\n'
' is used in the interactive interpreter to store
the result '
'of the\n'
' last evaluation; it is stored in the
"builtins" module. '
'When not\n'
' in interactive mode, "_" has no special
meaning and is not '
'defined.\n'
' See section The import statement.\n'
'\n'
' Note: The name "_" is often used in
conjunction with\n'
' internationalization; refer to the documentation
for '
'the\n'
' "gettext" module for more information
on this '
'convention.\n'
'\n'
'"__*__"\n'
' System-defined names. These names are defined by
the '
'interpreter\n'
' and its implementation (including the standard
library). '
'Current\n'
' system names are discussed in the Special method
names '
'section and\n'
' elsewhere. More will likely be defined in future
versions '
'of\n'
' Python. *Any* use of "__*__" names, in
any context, that '
'does not\n'
' follow explicitly documented use, is subject to
breakage '
'without\n'
' warning.\n'
'\n'
'"__*"\n'
' Class-private names. Names in this category, when
used '
'within the\n'
' context of a class definition, are re-written to
use a '
'mangled form\n'
' to help avoid name clashes between “private”
attributes of '
'base and\n'
' derived classes. See section Identifiers
(Names).\n',
'if': 'The "if" statement\n'
'******************\n'
'\n'
'The "if" statement is used for conditional
execution:\n'
'\n'
' if_stmt ::= "if" expression ":"
suite\n'
' ("elif" 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',
'imaginary': 'Imaginary literals\n'
'******************\n'
'\n'
'Imaginary literals are described by the following
lexical '
'definitions:\n'
'\n'
' imagnumber ::= (floatnumber | digitpart)
("j" | "J")\n'
'\n'
'An imaginary literal yields a complex number with a
real part '
'of 0.0.\n'
'Complex numbers are represented as a pair of floating
point '
'numbers\n'
'and have the same restrictions on their range. To
create a '
'complex\n'
'number with a nonzero real part, add a floating point
number to '
'it,\n'
'e.g., "(3+4j)". Some examples of imaginary
literals:\n'
'\n'
' 3.14j 10.j 10j .001j 1e100j 3.14e-10j
'
'3.14_15_93j\n',
'import': 'The "import" statement\n'
'**********************\n'
'\n'
' import_stmt ::= "import" module
["as" identifier] ("," '
'module ["as" identifier])*\n'
' | "from" relative_module
"import" identifier '
'["as" identifier]\n'
' ("," identifier
["as" identifier])*\n'
' | "from" relative_module
"import" "(" '
'identifier ["as" identifier]\n'
' ("," identifier
["as" identifier])* [","] ")"\n'
' | "from" module
"import" "*"\n'
' module ::= (identifier ".")*
identifier\n'
' relative_module ::= "."* module |
"."+\n'
'\n'
'The basic import statement (no "from" clause) is
executed in two\n'
'steps:\n'
'\n'
'1. find a module, loading and initializing it if
necessary\n'
'\n'
'2. define a name or names in the local namespace for the
scope\n'
' where the "import" statement occurs.\n'
'\n'
'When the statement contains multiple clauses (separated by
commas) '
'the\n'
'two steps are carried out separately for each clause, just
as '
'though\n'
'the clauses had been separated out into individual import
'
'statements.\n'
'\n'
'The details of the first step, finding and loading modules
are\n'
'described in greater detail in the section on the import
system, '
'which\n'
'also describes the various types of packages and modules
that can '
'be\n'
'imported, as well as all the hooks that can be used to
customize '
'the\n'
'import system. Note that failures in this step may
indicate '
'either\n'
'that the module could not be located, *or* that an error
occurred\n'
'while initializing the module, which includes execution of
the\n'
'module’s code.\n'
'\n'
'If the requested module is retrieved successfully, it will
be '
'made\n'
'available in the local namespace in one of three
ways:\n'
'\n'
'* If the module name is followed by "as", then
the name following\n'
' "as" is bound directly to the imported
module.\n'
'\n'
'* If no other name is specified, and the module being
imported is '
'a\n'
' top level module, the module’s name is bound in the
local '
'namespace\n'
' as a reference to the imported module\n'
'\n'
'* If the module being imported is *not* a top level
module, then '
'the\n'
' name of the top level package that contains the module
is bound '
'in\n'
' the local namespace as a reference to the top level
package. '
'The\n'
' imported module must be accessed using its full
qualified name\n'
' rather than directly\n'
'\n'
'The "from" form uses a slightly more complex
process:\n'
'\n'
'1. find the module specified in the "from"
clause, loading and\n'
' initializing it if necessary;\n'
'\n'
'2. for each of the identifiers specified in the
"import" clauses:\n'
'\n'
' 1. check if the imported module has an attribute by
that name\n'
'\n'
' 2. if not, attempt to import a submodule with that name
and '
'then\n'
' check the imported module again for that
attribute\n'
'\n'
' 3. if the attribute is not found,
"ImportError" is raised.\n'
'\n'
' 4. otherwise, a reference to that value is stored in
the local\n'
' namespace, using the name in the "as"
clause if it is '
'present,\n'
' otherwise using the attribute name\n'
'\n'
'Examples:\n'
'\n'
' import foo # foo imported and bound
locally\n'
' import foo.bar.baz # foo.bar.baz imported, foo
bound '
'locally\n'
' import foo.bar.baz as fbb # foo.bar.baz imported and
bound as '
'fbb\n'
' from foo.bar import baz # foo.bar.baz imported and
bound as '
'baz\n'
' from foo import attr # foo imported and foo.attr
bound as '
'attr\n'
'\n'
'If the list of identifiers is replaced by a star
("\'*\'"), all '
'public\n'
'names defined in the module are bound in the local
namespace for '
'the\n'
'scope where the "import" statement
occurs.\n'
'\n'
'The *public names* defined by a module are determined by
checking '
'the\n'
'module’s namespace for a variable named
"__all__"; if defined, it '
'must\n'
'be a sequence of strings which are names defined or
imported by '
'that\n'
'module. The names given in "__all__" are all
considered public '
'and\n'
'are required to exist. If "__all__" is not
defined, the set of '
'public\n'
'names includes all names found in the module’s namespace
which do '
'not\n'
'begin with an underscore character
("\'_\'"). "__all__" should '
'contain\n'
'the entire public API. It is intended to avoid
accidentally '
'exporting\n'
'items that are not part of the API (such as library
modules which '
'were\n'
'imported and used within the module).\n'
'\n'
'The wild card form of import — "from module import
*" — is only\n'
'allowed at the module level. Attempting to use it in
class or\n'
'function definitions will raise a
"SyntaxError".\n'
'\n'
'When specifying what module to import you do not have to
specify '
'the\n'
'absolute name of the module. When a module or package is
'
'contained\n'
'within another package it is possible to make a relative
import '
'within\n'
'the same top package without having to mention the package
name. '
'By\n'
'using leading dots in the specified module or package
after "from" '
'you\n'
'can specify how high to traverse up the current package
hierarchy\n'
'without specifying exact names. One leading dot means the
current\n'
'package where the module making the import exists. Two
dots means '
'up\n'
'one package level. Three dots is up two levels, etc. So if
you '
'execute\n'
'"from . import mod" from a module in the
"pkg" package then you '
'will\n'
'end up importing "pkg.mod". If you execute
"from ..subpkg2 import '
'mod"\n'
'from within "pkg.subpkg1" you will import
"pkg.subpkg2.mod". The\n'
'specification for relative imports is contained within
**PEP '
'328**.\n'
'\n'
'"importlib.import_module()" is provided to
support applications '
'that\n'
'determine dynamically the modules to be loaded.\n'
'\n'
'\n'
'Future statements\n'
'=================\n'
'\n'
'A *future statement* is a directive to the compiler that a
'
'particular\n'
'module should be compiled using syntax or semantics that
will be\n'
'available in a specified future release of Python where
the '
'feature\n'
'becomes standard.\n'
'\n'
'The future statement is intended to ease migration to
future '
'versions\n'
'of Python that introduce incompatible changes to the
language. '
'It\n'
'allows use of the new features on a per-module basis
before the\n'
'release in which the feature becomes standard.\n'
'\n'
' future_stmt ::= "from" "__future__"
"import" feature ["as" '
'identifier]\n'
' ("," feature ["as"
identifier])*\n'
' | "from"
"__future__" "import" "(" feature '
'["as" identifier]\n'
' ("," feature ["as"
identifier])* [","] ")"\n'
' feature ::= identifier\n'
'\n'
'A future statement must appear near the top of the module.
The '
'only\n'
'lines that can appear before a future statement
are:\n'
'\n'
'* the module docstring (if any),\n'
'\n'
'* comments,\n'
'\n'
'* blank lines, and\n'
'\n'
'* other future statements.\n'
'\n'
'The features recognized by Python 3.0 are
"absolute_import",\n'
'"division", "generators",
"unicode_literals", "print_function",\n'
'"nested_scopes" and "with_statement".
They are all redundant '
'because\n'
'they are always enabled, and only kept for backwards
'
'compatibility.\n'
'\n'
'A future statement is recognized and treated specially at
compile\n'
'time: Changes to the semantics of core constructs are
often\n'
'implemented by generating different code. It may even be
the '
'case\n'
'that a new feature introduces new incompatible syntax
(such as a '
'new\n'
'reserved word), in which case the compiler may need to
parse the\n'
'module differently. Such decisions cannot be pushed off
until\n'
'runtime.\n'
'\n'
'For any given release, the compiler knows which feature
names '
'have\n'
'been defined, and raises a compile-time error if a future
'
'statement\n'
'contains a feature not known to it.\n'
'\n'
'The direct runtime semantics are the same as for any
import '
'statement:\n'
'there is a standard module "__future__",
described later, and it '
'will\n'
'be imported in the usual way at the time the future
statement is\n'
'executed.\n'
'\n'
'The interesting runtime semantics depend on the specific
feature\n'
'enabled by the future statement.\n'
'\n'
'Note that there is nothing special about the
statement:\n'
'\n'
' import __future__ [as name]\n'
'\n'
'That is not a future statement; it’s an ordinary import
statement '
'with\n'
'no special semantics or syntax restrictions.\n'
'\n'
'Code compiled by calls to the built-in functions
"exec()" and\n'
'"compile()" that occur in a module "M"
containing a future '
'statement\n'
'will, by default, use the new syntax or semantics
associated with '
'the\n'
'future statement. This can be controlled by optional
arguments '
'to\n'
'"compile()" — see the documentation of that
function for details.\n'
'\n'
'A future statement typed at an interactive interpreter
prompt '
'will\n'
'take effect for the rest of the interpreter session. If
an\n'
'interpreter is started with the "-i" option, is
passed a script '
'name\n'
'to execute, and the script includes a future statement, it
will be '
'in\n'
'effect in the interactive session started after the script
is\n'
'executed.\n'
'\n'
'See also:\n'
'\n'
' **PEP 236** - Back to the __future__\n'
' The original proposal for the __future__
mechanism.\n',
'in': 'Membership test operations\n'
'**************************\n'
'\n'
'The operators "in" and "not in" test for
membership. "x in s"\n'
'evaluates to "True" if *x* is a member of *s*, and
"False" otherwise.\n'
'"x not in s" returns the negation of "x in
s". All built-in '
'sequences\n'
'and set types support this as well as dictionary, for which
"in" '
'tests\n'
'whether the dictionary has a given key. For container types
such as\n'
'list, tuple, set, frozenset, dict, or collections.deque,
the\n'
'expression "x in y" is equivalent to "any(x is
e or x == e for e in\n'
'y)".\n'
'\n'
'For the string and bytes types, "x in y" is
"True" if and only if *x*\n'
'is a substring of *y*. An equivalent test is "y.find(x)
!= -1".\n'
'Empty strings are always considered to be a substring of any
other\n'
'string, so """ in "abc"" will
return "True".\n'
'\n'
'For user-defined classes which define the
"__contains__()" method, "x\n'
'in y" returns "True" if
"y.__contains__(x)" returns a true value, and\n'
'"False" otherwise.\n'
'\n'
'For user-defined classes which do not define
"__contains__()" but do\n'
'define "__iter__()", "x in y" is
"True" if some value "z" with "x ==\n'
'z" is produced while iterating over "y". If an
exception is raised\n'
'during the iteration, it is as if "in" raised that
exception.\n'
'\n'
'Lastly, the old-style iteration protocol is tried: if a class
defines\n'
'"__getitem__()", "x in y" is
"True" if and only if there is a non-\n'
'negative integer index *i* such that "x == y[i]",
and all lower\n'
'integer indices do not raise "IndexError" exception.
(If any other\n'
'exception is raised, it is as if "in" raised that
exception).\n'
'\n'
'The operator "not in" is defined to have the inverse
true value of\n'
'"in".\n',
'integers': 'Integer literals\n'
'****************\n'
'\n'
'Integer literals are described by the following lexical
'
'definitions:\n'
'\n'
' integer ::= decinteger | bininteger | octinteger
| '
'hexinteger\n'
' decinteger ::= nonzerodigit (["_"]
digit)* | "0"+ (["_"] '
'"0")*\n'
' bininteger ::= "0" ("b" |
"B") (["_"] bindigit)+\n'
' octinteger ::= "0" ("o" |
"O") (["_"] octdigit)+\n'
' hexinteger ::= "0" ("x" |
"X") (["_"] hexdigit)+\n'
' nonzerodigit ::=
"1"..."9"\n'
' digit ::=
"0"..."9"\n'
' bindigit ::= "0" |
"1"\n'
' octdigit ::=
"0"..."7"\n'
' hexdigit ::= digit |
"a"..."f" | "A"..."F"\n'
'\n'
'There is no limit for the length of integer literals
apart from '
'what\n'
'can be stored in available memory.\n'
'\n'
'Underscores are ignored for determining the numeric
value of '
'the\n'
'literal. They can be used to group digits for enhanced
'
'readability.\n'
'One underscore can occur between digits, and after base
'
'specifiers\n'
'like "0x".\n'
'\n'
'Note that leading zeros in a non-zero decimal number are
not '
'allowed.\n'
'This is for disambiguation with C-style octal literals,
which '
'Python\n'
'used before version 3.0.\n'
'\n'
'Some examples of integer literals:\n'
'\n'
' 7 2147483647 0o177
0b100110111\n'
' 3 79228162514264337593543950336 0o377
0xdeadbeef\n'
' 100_000_000_000
0b_1110_0101\n'
'\n'
'Changed in version 3.6: Underscores are now allowed for
'
'grouping\n'
'purposes in literals.\n',
'lambda': 'Lambdas\n'
'*******\n'
'\n'
' lambda_expr ::= "lambda"
[parameter_list] ":" '
'expression\n'
' lambda_expr_nocond ::= "lambda"
[parameter_list] ":" '
'expression_nocond\n'
'\n'
'Lambda expressions (sometimes called lambda forms) are
used to '
'create\n'
'anonymous functions. The expression "lambda
parameters: '
'expression"\n'
'yields a function object. The unnamed object behaves like
a '
'function\n'
'object defined with:\n'
'\n'
' def <lambda>(parameters):\n'
' return expression\n'
'\n'
'See section Function definitions for the syntax of
parameter '
'lists.\n'
'Note that functions created with lambda expressions cannot
'
'contain\n'
'statements or annotations.\n',
'lists': 'List displays\n'
'*************\n'
'\n'
'A list display is a possibly empty series of expressions
enclosed '
'in\n'
'square brackets:\n'
'\n'
' list_display ::= "[" [starred_list |
comprehension] "]"\n'
'\n'
'A list display yields a new list object, the contents being
'
'specified\n'
'by either a list of expressions or a comprehension. When a
comma-\n'
'separated list of expressions is supplied, its elements are
'
'evaluated\n'
'from left to right and placed into the list object in that
order.\n'
'When a comprehension is supplied, the list is constructed
from the\n'
'elements resulting from the comprehension.\n',
'naming': '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',
'nonlocal': 'The "nonlocal" statement\n'
'************************\n'
'\n'
' nonlocal_stmt ::= "nonlocal" identifier
("," identifier)*\n'
'\n'
'The "nonlocal" statement causes the listed
identifiers to refer '
'to\n'
'previously bound variables in the nearest enclosing
scope '
'excluding\n'
'globals. This is important because the default behavior
for '
'binding is\n'
'to search the local namespace first. The statement
allows\n'
'encapsulated code to rebind variables outside of the
local '
'scope\n'
'besides the global (module) scope.\n'
'\n'
'Names listed in a "nonlocal" statement, unlike
those listed in '
'a\n'
'"global" statement, must refer to pre-existing
bindings in an\n'
'enclosing scope (the scope in which a new binding should
be '
'created\n'
'cannot be determined unambiguously).\n'
'\n'
'Names listed in a "nonlocal" statement must
not collide with '
'pre-\n'
'existing bindings in the local scope.\n'
'\n'
'See also:\n'
'\n'
' **PEP 3104** - Access to Names in Outer Scopes\n'
' The specification for the "nonlocal"
statement.\n',
'numbers': 'Numeric literals\n'
'****************\n'
'\n'
'There are three types of numeric literals: integers,
floating '
'point\n'
'numbers, and imaginary numbers. There are no complex
literals\n'
'(complex numbers can be formed by adding a real number
and an\n'
'imaginary number).\n'
'\n'
'Note that numeric literals do not include a sign; a
phrase like '
'"-1"\n'
'is actually an expression composed of the unary operator
‘"-"‘ '
'and the\n'
'literal "1".\n',
'numeric-types': 'Emulating numeric types\n'
'***********************\n'
'\n'
'The following methods can be defined to emulate
numeric '
'objects.\n'
'Methods corresponding to operations that are not
supported '
'by the\n'
'particular kind of number implemented (e.g.,
bitwise '
'operations for\n'
'non-integral numbers) should be left
undefined.\n'
'\n'
'object.__add__(self, other)\n'
'object.__sub__(self, other)\n'
'object.__mul__(self, other)\n'
'object.__matmul__(self, other)\n'
'object.__truediv__(self, other)\n'
'object.__floordiv__(self, other)\n'
'object.__mod__(self, other)\n'
'object.__divmod__(self, other)\n'
'object.__pow__(self, other[, modulo])\n'
'object.__lshift__(self, other)\n'
'object.__rshift__(self, other)\n'
'object.__and__(self, other)\n'
'object.__xor__(self, other)\n'
'object.__or__(self, other)\n'
'\n'
' These methods are called to implement the binary
'
'arithmetic\n'
' operations ("+", "-",
"*", "@", "/", "//", "%",
'
'"divmod()",\n'
' "pow()", "**",
"<<", ">>", "&",
"^", "|"). For '
'instance, to\n'
' evaluate the expression "x + y", where
*x* is an '
'instance of a\n'
' class that has an "__add__()" method,
"x.__add__(y)" is '
'called.\n'
' The "__divmod__()" method should be
the equivalent to '
'using\n'
' "__floordiv__()" and
"__mod__()"; it should not be '
'related to\n'
' "__truediv__()". Note that
"__pow__()" should be '
'defined to accept\n'
' an optional third argument if the ternary
version of the '
'built-in\n'
' "pow()" function is to be
supported.\n'
'\n'
' If one of those methods does not support the
operation '
'with the\n'
' supplied arguments, it should return
"NotImplemented".\n'
'\n'
'object.__radd__(self, other)\n'
'object.__rsub__(self, other)\n'
'object.__rmul__(self, other)\n'
'object.__rmatmul__(self, other)\n'
'object.__rtruediv__(self, other)\n'
'object.__rfloordiv__(self, other)\n'
'object.__rmod__(self, other)\n'
'object.__rdivmod__(self, other)\n'
'object.__rpow__(self, other)\n'
'object.__rlshift__(self, other)\n'
'object.__rrshift__(self, other)\n'
'object.__rand__(self, other)\n'
'object.__rxor__(self, other)\n'
'object.__ror__(self, other)\n'
'\n'
' These methods are called to implement the binary
'
'arithmetic\n'
' operations ("+", "-",
"*", "@", "/", "//", "%",
'
'"divmod()",\n'
' "pow()", "**",
"<<", ">>", "&",
"^", "|") with reflected '
'(swapped)\n'
' operands. These functions are only called if
the left '
'operand does\n'
' not support the corresponding operation [3] and
the '
'operands are of\n'
' different types. [4] For instance, to evaluate
the '
'expression "x -\n'
' y", where *y* is an instance of a class
that has an '
'"__rsub__()"\n'
' method, "y.__rsub__(x)" is called if
"x.__sub__(y)" '
'returns\n'
' *NotImplemented*.\n'
'\n'
' Note that ternary "pow()" will not try
calling '
'"__rpow__()" (the\n'
' coercion rules would become too
complicated).\n'
'\n'
' Note: If the right operand’s type is a
subclass of the '
'left\n'
' operand’s type and that subclass provides
the '
'reflected method\n'
' for the operation, this method will be called
before '
'the left\n'
' operand’s non-reflected method. This
behavior allows '
'subclasses\n'
' to override their ancestors’
operations.\n'
'\n'
'object.__iadd__(self, other)\n'
'object.__isub__(self, other)\n'
'object.__imul__(self, other)\n'
'object.__imatmul__(self, other)\n'
'object.__itruediv__(self, other)\n'
'object.__ifloordiv__(self, other)\n'
'object.__imod__(self, other)\n'
'object.__ipow__(self, other[, modulo])\n'
'object.__ilshift__(self, other)\n'
'object.__irshift__(self, other)\n'
'object.__iand__(self, other)\n'
'object.__ixor__(self, other)\n'
'object.__ior__(self, other)\n'
'\n'
' These methods are called to implement the
augmented '
'arithmetic\n'
' assignments ("+=", "-=",
"*=", "@=", "/=", "//=",
"%=", '
'"**=",\n'
' "<<=", ">>=",
"&=", "^=", "|="). These methods should
'
'attempt to\n'
' do the operation in-place (modifying *self*) and
return '
'the result\n'
' (which could be, but does not have to be,
*self*). If a '
'specific\n'
' method is not defined, the augmented assignment
falls '
'back to the\n'
' normal methods. For instance, if *x* is an
instance of '
'a class\n'
' with an "__iadd__()" method, "x
+= y" is equivalent to '
'"x =\n'
' x.__iadd__(y)" . Otherwise,
"x.__add__(y)" and '
'"y.__radd__(x)" are\n'
' considered, as with the evaluation of "x +
y". In '
'certain\n'
' situations, augmented assignment can result in
'
'unexpected errors\n'
' (see Why does a_tuple[i] += [‘item’] raise
an exception '
'when the\n'
' addition works?), but this behavior is in fact
part of '
'the data\n'
' model.\n'
'\n'
'object.__neg__(self)\n'
'object.__pos__(self)\n'
'object.__abs__(self)\n'
'object.__invert__(self)\n'
'\n'
' Called to implement the unary arithmetic
operations '
'("-", "+",\n'
' "abs()" and "~").\n'
'\n'
'object.__complex__(self)\n'
'object.__int__(self)\n'
'object.__float__(self)\n'
'\n'
' Called to implement the built-in functions
"complex()", '
'"int()" and\n'
' "float()". Should return a value of
the appropriate '
'type.\n'
'\n'
'object.__index__(self)\n'
'\n'
' Called to implement
"operator.index()", and whenever '
'Python needs\n'
' to losslessly convert the numeric object to an
integer '
'object (such\n'
' as in slicing, or in the built-in
"bin()", "hex()" and '
'"oct()"\n'
' functions). Presence of this method indicates
that the '
'numeric\n'
' object is an integer type. Must return an
integer.\n'
'\n'
' Note: In order to have a coherent integer type
class, '
'when\n'
' "__index__()" is defined
"__int__()" should also be '
'defined, and\n'
' both should return the same value.\n'
'\n'
'object.__round__(self[, ndigits])\n'
'object.__trunc__(self)\n'
'object.__floor__(self)\n'
'object.__ceil__(self)\n'
'\n'
' Called to implement the built-in function
"round()" and '
'"math"\n'
' functions "trunc()",
"floor()" and "ceil()". Unless '
'*ndigits* is\n'
' passed to "__round__()" all these
methods should return '
'the value\n'
' of the object truncated to an
"Integral" (typically an '
'"int").\n'
'\n'
' If "__int__()" is not defined then the
built-in function '
'"int()"\n'
' falls back to "__trunc__()".\n',
'objects': 'Objects, values and types\n'
'*************************\n'
'\n'
'*Objects* are Python’s abstraction for data. All data
in a '
'Python\n'
'program is represented by objects or by relations between
'
'objects. (In\n'
'a sense, and in conformance to Von Neumann’s model of a
“stored\n'
'program computer,” code is also represented by
objects.)\n'
'\n'
'Every object has an identity, a type and a value. An
object’s\n'
'*identity* never changes once it has been created; you
may think '
'of it\n'
'as the object’s address in memory. The
‘"is"’ operator compares '
'the\n'
'identity of two objects; the "id()" function
returns an integer\n'
'representing its identity.\n'
'\n'
'**CPython implementation detail:** For CPython,
"id(x)" is the '
'memory\n'
'address where "x" is stored.\n'
'\n'
'An object’s type determines the operations that the
object '
'supports\n'
'(e.g., “does it have a length?”) and also defines the
possible '
'values\n'
'for objects of that type. The "type()"
function returns an '
'object’s\n'
'type (which is an object itself). Like its identity, an
'
'object’s\n'
'*type* is also unchangeable. [1]\n'
'\n'
'The *value* of some objects can change. Objects whose
value can\n'
'change are said to be *mutable*; objects whose value is
'
'unchangeable\n'
'once they are created are called *immutable*. (The value
of an\n'
'immutable container object that contains a reference to a
'
'mutable\n'
'object can change when the latter’s value is changed;
however '
'the\n'
'container is still considered immutable, because the
collection '
'of\n'
'objects it contains cannot be changed. So, immutability
is not\n'
'strictly the same as having an unchangeable value, it is
more '
'subtle.)\n'
'An object’s mutability is determined by its type; for
instance,\n'
'numbers, strings and tuples are immutable, while
dictionaries '
'and\n'
'lists are mutable.\n'
'\n'
'Objects are never explicitly destroyed; however, when
they '
'become\n'
'unreachable they may be garbage-collected. An
implementation is\n'
'allowed to postpone garbage collection or omit it
altogether — it '
'is a\n'
'matter of implementation quality how garbage collection
is\n'
'implemented, as long as no objects are collected that are
still\n'
'reachable.\n'
'\n'
'**CPython implementation detail:** CPython currently uses
a '
'reference-\n'
'counting scheme with (optional) delayed detection of
cyclically '
'linked\n'
'garbage, which collects most objects as soon as they
become\n'
'unreachable, but is not guaranteed to collect garbage
containing\n'
'circular references. See the documentation of the
"gc" module '
'for\n'
'information on controlling the collection of cyclic
garbage. '
'Other\n'
'implementations act differently and CPython may change.
Do not '
'depend\n'
'on immediate finalization of objects when they become
unreachable '
'(so\n'
'you should always close files explicitly).\n'
'\n'
'Note that the use of the implementation’s tracing or
debugging\n'
'facilities may keep objects alive that would normally be
'
'collectable.\n'
'Also note that catching an exception with a
‘"try"…"except"’ '
'statement\n'
'may keep objects alive.\n'
'\n'
'Some objects contain references to “external”
resources such as '
'open\n'
'files or windows. It is understood that these resources
are '
'freed\n'
'when the object is garbage-collected, but since garbage
'
'collection is\n'
'not guaranteed to happen, such objects also provide an
explicit '
'way to\n'
'release the external resource, usually a
"close()" method. '
'Programs\n'
'are strongly recommended to explicitly close such
objects. The\n'
'‘"try"…"finally"’ statement and
the ‘"with"’ statement provide\n'
'convenient ways to do this.\n'
'\n'
'Some objects contain references to other objects; these
are '
'called\n'
'*containers*. Examples of containers are tuples, lists
and\n'
'dictionaries. The references are part of a container’s
value. '
'In\n'
'most cases, when we talk about the value of a container,
we imply '
'the\n'
'values, not the identities of the contained objects;
however, '
'when we\n'
'talk about the mutability of a container, only the
identities of '
'the\n'
'immediately contained objects are implied. So, if an
immutable\n'
'container (like a tuple) contains a reference to a
mutable '
'object, its\n'
'value changes if that mutable object is changed.\n'
'\n'
'Types affect almost all aspects of object behavior. Even
the\n'
'importance of object identity is affected in some sense:
for '
'immutable\n'
'types, operations that compute new values may actually
return a\n'
'reference to any existing object with the same type and
value, '
'while\n'
'for mutable objects this is not allowed. E.g., after
"a = 1; b = '
'1",\n'
'"a" and "b" may or may not refer to
the same object with the '
'value\n'
'one, depending on the implementation, but after "c =
[]; d = []", '
'"c"\n'
'and "d" are guaranteed to refer to two
different, unique, newly\n'
'created empty lists. (Note that "c = d = []"
assigns the same '
'object\n'
'to both "c" and "d".)\n',
'operator-summary': 'Operator precedence\n'
'*******************\n'
'\n'
'The following table summarizes the operator
precedence '
'in Python, from\n'
'lowest precedence (least binding) to highest
precedence '
'(most\n'
'binding). Operators in the same box have the
same '
'precedence. Unless\n'
'the syntax is explicitly given, operators are
binary. '
'Operators in\n'
'the same box group left to right (except for
'
'exponentiation, which\n'
'groups from right to left).\n'
'\n'
'Note that comparisons, membership tests, and
identity '
'tests, all have\n'
'the same precedence and have a left-to-right
chaining '
'feature as\n'
'described in the Comparisons section.\n'
'\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| Operator
| '
'Description |\n'
'+=================================================+=======================================+\n'
'| "lambda"
| '
'Lambda expression |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "if" – "else"
| '
'Conditional expression |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "or"
| '
'Boolean OR |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "and"
| '
'Boolean AND |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "not" "x"
| '
'Boolean NOT |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "in", "not in",
"is", "is not", "<", "<=",
">", | '
'Comparisons, including membership |\n'
'| ">=", "!=",
"==" | '
'tests and identity tests |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "|"
| '
'Bitwise OR |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "^"
| '
'Bitwise XOR |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "&"
| '
'Bitwise AND |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "<<", ">>"
| '
'Shifts |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "+", "-"
| '
'Addition and subtraction |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "*", "@", "/",
"//", "%" | '
'Multiplication, matrix |\n'
'|
| '
'multiplication, division, floor |\n'
'|
| '
'division, remainder [5] |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "+x", "-x", "~x"
| '
'Positive, negative, bitwise NOT |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "**"
| '
'Exponentiation [6] |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "await" "x"
| '
'Await expression |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "x[index]",
"x[index:index]", | '
'Subscription, slicing, call, |\n'
'| "x(arguments...)",
"x.attribute" | '
'attribute reference |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'| "(expressions...)",
"[expressions...]", "{key: | '
'Binding or tuple display, list |\n'
'| value...}", "{expressions...}"
| '
'display, dictionary display, set |\n'
'|
| '
'display |\n'
'+-------------------------------------------------+---------------------------------------+\n'
'\n'
'-[ Footnotes ]-\n'
'\n'
'[1] While "abs(x%y) < abs(y)" is
true mathematically, '
'for floats\n'
' it may not be true numerically due to
roundoff. For '
'example, and\n'
' assuming a platform on which a Python float
is an '
'IEEE 754 double-\n'
' precision number, in order that
"-1e-100 % 1e100" '
'have the same\n'
' sign as "1e100", the computed
result is "-1e-100 + '
'1e100", which\n'
' is numerically exactly equal to
"1e100". The '
'function\n'
' "math.fmod()" returns a result
whose sign matches '
'the sign of the\n'
' first argument instead, and so returns
"-1e-100" in '
'this case.\n'
' Which approach is more appropriate depends
on the '
'application.\n'
'\n'
'[2] If x is very close to an exact integer
multiple of '
'y, it’s\n'
' possible for "x//y" to be one
larger than '
'"(x-x%y)//y" due to\n'
' rounding. In such cases, Python returns the
latter '
'result, in\n'
' order to preserve that "divmod(x,y)[0]
* y + x % y" '
'be very close\n'
' to "x".\n'
'\n'
'[3] The Unicode standard distinguishes between
*code '
'points* (e.g.\n'
' U+0041) and *abstract characters* (e.g.
“LATIN '
'CAPITAL LETTER A”).\n'
' While most abstract characters in Unicode
are only '
'represented\n'
' using one code point, there is a number of
abstract '
'characters\n'
' that can in addition be represented using a
sequence '
'of more than\n'
' one code point. For example, the abstract
character '
'“LATIN\n'
' CAPITAL LETTER C WITH CEDILLA” can be
represented as '
'a single\n'
' *precomposed character* at code position
U+00C7, or '
'as a sequence\n'
' of a *base character* at code position
U+0043 (LATIN '
'CAPITAL\n'
' LETTER C), followed by a *combining
character* at '
'code position\n'
' U+0327 (COMBINING CEDILLA).\n'
'\n'
' The comparison operators on strings compare
at the '
'level of\n'
' Unicode code points. This may be
counter-intuitive '
'to humans. For\n'
' example, ""\\u00C7" ==
"\\u0043\\u0327"" is "False", '
'even though both\n'
' strings represent the same abstract
character “LATIN '
'CAPITAL\n'
' LETTER C WITH CEDILLA”.\n'
'\n'
' To compare strings at the level of abstract
'
'characters (that is,\n'
' in a way intuitive to humans), use '
'"unicodedata.normalize()".\n'
'\n'
'[4] Due to automatic garbage-collection, free
lists, and '
'the\n'
' dynamic nature of descriptors, you may
notice '
'seemingly unusual\n'
' behaviour in certain uses of the
"is" operator, like '
'those\n'
' involving comparisons between instance
methods, or '
'constants.\n'
' Check their documentation for more
info.\n'
'\n'
'[5] The "%" operator is also used for
string formatting; '
'the same\n'
' precedence applies.\n'
'\n'
'[6] The power operator "**" binds less
tightly than an '
'arithmetic\n'
' or bitwise unary operator on its right, that
is, '
'"2**-1" is "0.5".\n',
'pass': 'The "pass" statement\n'
'********************\n'
'\n'
' pass_stmt ::= "pass"\n'
'\n'
'"pass" is a null operation — when it is
executed, nothing happens. '
'It\n'
'is useful as a placeholder when a statement is required
'
'syntactically,\n'
'but no code needs to be executed, for example:\n'
'\n'
' def f(arg): pass # a function that does nothing
(yet)\n'
'\n'
' class C: pass # a class with no methods
(yet)\n',
'power': 'The power operator\n'
'******************\n'
'\n'
'The power operator binds more tightly than unary operators
on its\n'
'left; it binds less tightly than unary operators on its
right. '
'The\n'
'syntax is:\n'
'\n'
' power ::= (await_expr | primary) ["**"
u_expr]\n'
'\n'
'Thus, in an unparenthesized sequence of power and unary
operators, '
'the\n'
'operators are evaluated from right to left (this does not
'
'constrain\n'
'the evaluation order for the operands): "-1**2"
results in "-1".\n'
'\n'
'The power operator has the same semantics as the built-in
"pow()"\n'
'function, when called with two arguments: it yields its
left '
'argument\n'
'raised to the power of its right argument. The numeric
arguments '
'are\n'
'first converted to a common type, and the result is of that
type.\n'
'\n'
'For int operands, the result has the same type as the
operands '
'unless\n'
'the second argument is negative; in that case, all
arguments are\n'
'converted to float and a float result is delivered. For
example,\n'
'"10**2" returns "100", but
"10**-2" returns "0.01".\n'
'\n'
'Raising "0.0" to a negative power results in a
'
'"ZeroDivisionError".\n'
'Raising a negative number to a fractional power results in
a '
'"complex"\n'
'number. (In earlier versions it raised a
"ValueError".)\n',
'raise': 'The "raise" statement\n'
'*********************\n'
'\n'
' raise_stmt ::= "raise" [expression
["from" expression]]\n'
'\n'
'If no expressions are present, "raise" re-raises
the last '
'exception\n'
'that was active in the current scope. If no exception is
active '
'in\n'
'the current scope, a "RuntimeError" exception is
raised indicating\n'
'that this is an error.\n'
'\n'
'Otherwise, "raise" evaluates the first expression
as the exception\n'
'object. It must be either a subclass or an instance
of\n'
'"BaseException". If it is a class, the exception
instance will be\n'
'obtained when needed by instantiating the class with no
arguments.\n'
'\n'
'The *type* of the exception is the exception instance’s
class, the\n'
'*value* is the instance itself.\n'
'\n'
'A traceback object is normally created automatically when
an '
'exception\n'
'is raised and attached to it as the
"__traceback__" attribute, '
'which\n'
'is writable. You can create an exception and set your own
traceback '
'in\n'
'one step using the "with_traceback()" exception
method (which '
'returns\n'
'the same exception instance, with its traceback set to its
'
'argument),\n'
'like so:\n'
'\n'
' raise Exception("foo
occurred").with_traceback(tracebackobj)\n'
'\n'
'The "from" clause is used for exception chaining:
if given, the '
'second\n'
'*expression* must be another exception class or instance,
which '
'will\n'
'then be attached to the raised exception as the
"__cause__" '
'attribute\n'
'(which is writable). If the raised exception is not
handled, both\n'
'exceptions will be printed:\n'
'\n'
' >>> try:\n'
' ... print(1 / 0)\n'
' ... except Exception as exc:\n'
' ... raise RuntimeError("Something bad
happened") from exc\n'
' ...\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 2, in
<module>\n'
' ZeroDivisionError: division by zero\n'
'\n'
' The above exception was the direct cause of the
following '
'exception:\n'
'\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 4, in
<module>\n'
' RuntimeError: Something bad happened\n'
'\n'
'A similar mechanism works implicitly if an exception is
raised '
'inside\n'
'an exception handler or a "finally" clause: the
previous exception '
'is\n'
'then attached as the new exception’s
"__context__" attribute:\n'
'\n'
' >>> try:\n'
' ... print(1 / 0)\n'
' ... except:\n'
' ... raise RuntimeError("Something bad
happened")\n'
' ...\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 2, in
<module>\n'
' ZeroDivisionError: division by zero\n'
'\n'
' During handling of the above exception, another
exception '
'occurred:\n'
'\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 4, in
<module>\n'
' RuntimeError: Something bad happened\n'
'\n'
'Exception chaining can be explicitly suppressed by
specifying '
'"None"\n'
'in the "from" clause:\n'
'\n'
' >>> try:\n'
' ... print(1 / 0)\n'
' ... except:\n'
' ... raise RuntimeError("Something bad
happened") from None\n'
' ...\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 4, in
<module>\n'
' RuntimeError: Something bad happened\n'
'\n'
'Additional information on exceptions can be found in
section\n'
'Exceptions, and information about handling exceptions is in
'
'section\n'
'The try statement.\n'
'\n'
'Changed in version 3.3: "None" is now permitted
as "Y" in "raise X\n'
'from Y".\n'
'\n'
'New in version 3.3: The "__suppress_context__"
attribute to '
'suppress\n'
'automatic display of the exception context.\n',
'return': 'The "return" statement\n'
'**********************\n'
'\n'
' return_stmt ::= "return"
[expression_list]\n'
'\n'
'"return" may only occur syntactically nested in
a function '
'definition,\n'
'not within a nested class definition.\n'
'\n'
'If an expression list is present, it is evaluated, else
"None" is\n'
'substituted.\n'
'\n'
'"return" leaves the current function call with
the expression list '
'(or\n'
'"None") as return value.\n'
'\n'
'When "return" passes control out of a
"try" statement with a '
'"finally"\n'
'clause, that "finally" clause is executed before
really leaving '
'the\n'
'function.\n'
'\n'
'In a generator function, the "return" statement
indicates that '
'the\n'
'generator is done and will cause "StopIteration"
to be raised. '
'The\n'
'returned value (if any) is used as an argument to
construct\n'
'"StopIteration" and becomes the
"StopIteration.value" attribute.\n'
'\n'
'In an asynchronous generator function, an empty
"return" '
'statement\n'
'indicates that the asynchronous generator is done and will
cause\n'
'"StopAsyncIteration" to be raised. A non-empty
"return" statement '
'is\n'
'a syntax error in an asynchronous generator
function.\n',
'sequence-types': 'Emulating container types\n'
'*************************\n'
'\n'
'The following methods can be defined to implement
'
'container objects.\n'
'Containers usually are sequences (such as lists or
tuples) '
'or mappings\n'
'(like dictionaries), but can represent other
containers as '
'well. The\n'
'first set of methods is used either to emulate a
sequence '
'or to\n'
'emulate a mapping; the difference is that for a
sequence, '
'the\n'
'allowable keys should be the integers *k* for
which "0 <= '
'k < N" where\n'
'*N* is the length of the sequence, or slice
objects, which '
'define a\n'
'range of items. It is also recommended that
mappings '
'provide the\n'
'methods "keys()", "values()",
"items()", "get()", '
'"clear()",\n'
'"setdefault()", "pop()",
"popitem()", "copy()", and '
'"update()"\n'
'behaving similar to those for Python’s standard
dictionary '
'objects.\n'
'The "collections" module provides a
"MutableMapping" '
'abstract base\n'
'class to help create those methods from a base set
of '
'"__getitem__()",\n'
'"__setitem__()",
"__delitem__()", and "keys()". Mutable '
'sequences\n'
'should provide methods "append()",
"count()", "index()", '
'"extend()",\n'
'"insert()", "pop()",
"remove()", "reverse()" and "sort()", '
'like Python\n'
'standard list objects. Finally, sequence types
should '
'implement\n'
'addition (meaning concatenation) and
multiplication '
'(meaning\n'
'repetition) by defining the methods
"__add__()", '
'"__radd__()",\n'
'"__iadd__()", "__mul__()",
"__rmul__()" and "__imul__()" '
'described\n'
'below; they should not define other numerical
operators. '
'It is\n'
'recommended that both mappings and sequences
implement '
'the\n'
'"__contains__()" method to allow
efficient use of the "in" '
'operator;\n'
'for mappings, "in" should search the
mapping’s keys; for '
'sequences, it\n'
'should search through the values. It is further
'
'recommended that both\n'
'mappings and sequences implement the
"__iter__()" method '
'to allow\n'
'efficient iteration through the container; for
mappings, '
'"__iter__()"\n'
'should be the same as "keys()"; for
sequences, it should '
'iterate\n'
'through the values.\n'
'\n'
'object.__len__(self)\n'
'\n'
' Called to implement the built-in function
"len()". '
'Should return\n'
' the length of the object, an integer
">=" 0. Also, an '
'object that\n'
' doesn’t define a "__bool__()"
method and whose '
'"__len__()" method\n'
' returns zero is considered to be false in a
Boolean '
'context.\n'
'\n'
' **CPython implementation detail:** In CPython,
the '
'length is\n'
' required to be at most "sys.maxsize".
If the length is '
'larger than\n'
' "sys.maxsize" some features (such as
"len()") may '
'raise\n'
' "OverflowError". To prevent raising
"OverflowError" by '
'truth value\n'
' testing, an object must define a
"__bool__()" method.\n'
'\n'
'object.__length_hint__(self)\n'
'\n'
' Called to implement
"operator.length_hint()". Should '
'return an\n'
' estimated length for the object (which may be
greater '
'or less than\n'
' the actual length). The length must be an
integer ">=" '
'0. This\n'
' method is purely an optimization and is never
required '
'for\n'
' correctness.\n'
'\n'
' New in version 3.4.\n'
'\n'
'Note: Slicing is done exclusively with the
following three '
'methods.\n'
' A call like\n'
'\n'
' a[1:2] = b\n'
'\n'
' is translated to\n'
'\n'
' a[slice(1, 2, None)] = b\n'
'\n'
' and so forth. Missing slice items are always
filled in '
'with "None".\n'
'\n'
'object.__getitem__(self, key)\n'
'\n'
' Called to implement evaluation of
"self[key]". For '
'sequence types,\n'
' the accepted keys should be integers and slice
'
'objects. Note that\n'
' the special interpretation of negative indexes
(if the '
'class wishes\n'
' to emulate a sequence type) is up to the '
'"__getitem__()" method. If\n'
' *key* is of an inappropriate type,
"TypeError" may be '
'raised; if of\n'
' a value outside the set of indexes for the
sequence '
'(after any\n'
' special interpretation of negative values),
'
'"IndexError" should be\n'
' raised. For mapping types, if *key* is missing
(not in '
'the\n'
' container), "KeyError" should be
raised.\n'
'\n'
' Note: "for" loops expect that an
"IndexError" will be '
'raised for\n'
' illegal indexes to allow proper detection of
the end '
'of the\n'
' sequence.\n'
'\n'
'object.__setitem__(self, key, value)\n'
'\n'
' Called to implement assignment to
"self[key]". Same '
'note as for\n'
' "__getitem__()". This should only be
implemented for '
'mappings if\n'
' the objects support changes to the values for
keys, or '
'if new keys\n'
' can be added, or for sequences if elements can
be '
'replaced. The\n'
' same exceptions should be raised for improper
*key* '
'values as for\n'
' the "__getitem__()" method.\n'
'\n'
'object.__delitem__(self, key)\n'
'\n'
' Called to implement deletion of
"self[key]". Same note '
'as for\n'
' "__getitem__()". This should only be
implemented for '
'mappings if\n'
' the objects support removal of keys, or for
sequences '
'if elements\n'
' can be removed from the sequence. The same
exceptions '
'should be\n'
' raised for improper *key* values as for the
'
'"__getitem__()" method.\n'
'\n'
'object.__missing__(self, key)\n'
'\n'
' Called by
"dict"."__getitem__()" to implement '
'"self[key]" for dict\n'
' subclasses when key is not in the
dictionary.\n'
'\n'
'object.__iter__(self)\n'
'\n'
' This method is called when an iterator is
required for '
'a container.\n'
' This method should return a new iterator object
that '
'can iterate\n'
' over all the objects in the container. For
mappings, '
'it should\n'
' iterate over the keys of the container.\n'
'\n'
' Iterator objects also need to implement this
method; '
'they are\n'
' required to return themselves. For more
information on '
'iterator\n'
' objects, see Iterator Types.\n'
'\n'
'object.__reversed__(self)\n'
'\n'
' Called (if present) by the
"reversed()" built-in to '
'implement\n'
' reverse iteration. It should return a new
iterator '
'object that\n'
' iterates over all the objects in the container
in '
'reverse order.\n'
'\n'
' If the "__reversed__()" method is not
provided, the '
'"reversed()"\n'
' built-in will fall back to using the sequence
protocol '
'("__len__()"\n'
' and "__getitem__()"). Objects that
support the '
'sequence protocol\n'
' should only provide "__reversed__()"
if they can '
'provide an\n'
' implementation that is more efficient than the
one '
'provided by\n'
' "reversed()".\n'
'\n'
'The membership test operators ("in" and
"not in") are '
'normally\n'
'implemented as an iteration through a sequence.
However, '
'container\n'
'objects can supply the following special method
with a '
'more efficient\n'
'implementation, which also does not require the
object be '
'a sequence.\n'
'\n'
'object.__contains__(self, item)\n'
'\n'
' Called to implement membership test operators.
Should '
'return true\n'
' if *item* is in *self*, false otherwise. For
mapping '
'objects, this\n'
' should consider the keys of the mapping rather
than the '
'values or\n'
' the key-item pairs.\n'
'\n'
' For objects that don’t define
"__contains__()", the '
'membership test\n'
' first tries iteration via
"__iter__()", then the old '
'sequence\n'
' iteration protocol via
"__getitem__()", see this '
'section in the\n'
' language reference.\n',
'shifting': 'Shifting operations\n'
'*******************\n'
'\n'
'The shifting operations have lower priority than the
arithmetic\n'
'operations:\n'
'\n'
' shift_expr ::= a_expr | shift_expr
("<<" | ">>") a_expr\n'
'\n'
'These operators accept integers as arguments. They
shift the '
'first\n'
'argument to the left or right by the number of bits
given by '
'the\n'
'second argument.\n'
'\n'
'A right shift by *n* bits is defined as floor division
by '
'"pow(2,n)".\n'
'A left shift by *n* bits is defined as multiplication
with '
'"pow(2,n)".\n'
'\n'
'Note: In the current implementation, the right-hand
operand is\n'
' required to be at most "sys.maxsize". If
the right-hand '
'operand is\n'
' larger than "sys.maxsize" an
"OverflowError" exception is '
'raised.\n',
'slicings': 'Slicings\n'
'********\n'
'\n'
'A slicing selects a range of items in a sequence object
(e.g., '
'a\n'
'string, tuple or list). Slicings may be used as
expressions or '
'as\n'
'targets in assignment or "del" statements.
The syntax for a '
'slicing:\n'
'\n'
' slicing ::= primary "[" slice_list
"]"\n'
' slice_list ::= slice_item (","
slice_item)* [","]\n'
' slice_item ::= expression | proper_slice\n'
' proper_slice ::= [lower_bound] ":"
[upper_bound] [ ":" '
'[stride] ]\n'
' lower_bound ::= expression\n'
' upper_bound ::= expression\n'
' stride ::= expression\n'
'\n'
'There is ambiguity in the formal syntax here: anything
that '
'looks like\n'
'an expression list also looks like a slice list, so any
'
'subscription\n'
'can be interpreted as a slicing. Rather than further
'
'complicating the\n'
'syntax, this is disambiguated by defining that in this
case the\n'
'interpretation as a subscription takes priority over
the\n'
'interpretation as a slicing (this is the case if the
slice list\n'
'contains no proper slice).\n'
'\n'
'The semantics for a slicing are as follows. The primary
is '
'indexed\n'
'(using the same "__getitem__()" method as
normal subscription) '
'with a\n'
'key that is constructed from the slice list, as follows.
If the '
'slice\n'
'list contains at least one comma, the key is a tuple
containing '
'the\n'
'conversion of the slice items; otherwise, the conversion
of the '
'lone\n'
'slice item is the key. The conversion of a slice item
that is '
'an\n'
'expression is that expression. The conversion of a
proper slice '
'is a\n'
'slice object (see section The standard type hierarchy)
whose '
'"start",\n'
'"stop" and "step" attributes are the
values of the expressions '
'given\n'
'as lower bound, upper bound and stride, respectively,
'
'substituting\n'
'"None" for missing expressions.\n',
'specialattrs': 'Special Attributes\n'
'******************\n'
'\n'
'The implementation adds a few special read-only
attributes '
'to several\n'
'object types, where they are relevant. Some of
these are '
'not reported\n'
'by the "dir()" built-in function.\n'
'\n'
'object.__dict__\n'
'\n'
' A dictionary or other mapping object used to
store an '
'object’s\n'
' (writable) attributes.\n'
'\n'
'instance.__class__\n'
'\n'
' The class to which a class instance
belongs.\n'
'\n'
'class.__bases__\n'
'\n'
' The tuple of base classes of a class
object.\n'
'\n'
'definition.__name__\n'
'\n'
' The name of the class, function, method,
descriptor, or '
'generator\n'
' instance.\n'
'\n'
'definition.__qualname__\n'
'\n'
' The *qualified name* of the class, function,
method, '
'descriptor, or\n'
' generator instance.\n'
'\n'
' New in version 3.3.\n'
'\n'
'class.__mro__\n'
'\n'
' This attribute is a tuple of classes that are
considered '
'when\n'
' looking for base classes during method
resolution.\n'
'\n'
'class.mro()\n'
'\n'
' This method can be overridden by a metaclass to
customize '
'the\n'
' method resolution order for its instances. It is
called '
'at class\n'
' instantiation, and its result is stored in
"__mro__".\n'
'\n'
'class.__subclasses__()\n'
'\n'
' Each class keeps a list of weak references to its
'
'immediate\n'
' subclasses. This method returns a list of all
those '
'references\n'
' still alive. Example:\n'
'\n'
' >>> int.__subclasses__()\n'
" [<class 'bool'>]\n"
'\n'
'-[ Footnotes ]-\n'
'\n'
'[1] Additional information on these special methods
may be '
'found\n'
' in the Python Reference Manual (Basic
customization).\n'
'\n'
'[2] As a consequence, the list "[1, 2]" is
considered equal '
'to\n'
' "[1.0, 2.0]", and similarly for
tuples.\n'
'\n'
'[3] They must have since the parser can’t tell the
type of '
'the\n'
' operands.\n'
'\n'
'[4] Cased characters are those with general category
'
'property\n'
' being one of “Lu” (Letter, uppercase),
“Ll” (Letter, '
'lowercase),\n'
' or “Lt” (Letter, titlecase).\n'
'\n'
'[5] To format only a tuple you should therefore
provide a\n'
' singleton tuple whose only element is the tuple
to be '
'formatted.\n',
'specialnames': 'Special method names\n'
'********************\n'
'\n'
'A class can implement certain operations that are
invoked by '
'special\n'
'syntax (such as arithmetic operations or
subscripting and '
'slicing) by\n'
'defining methods with special names. This is
Python’s '
'approach to\n'
'*operator overloading*, allowing classes to define
their own '
'behavior\n'
'with respect to language operators. For instance,
if a '
'class defines\n'
'a method named "__getitem__()", and
"x" is an instance of '
'this class,\n'
'then "x[i]" is roughly equivalent to
"type(x).__getitem__(x, '
'i)".\n'
'Except where mentioned, attempts to execute an
operation '
'raise an\n'
'exception when no appropriate method is defined
(typically\n'
'"AttributeError" or
"TypeError").\n'
'\n'
'Setting a special method to "None"
indicates that the '
'corresponding\n'
'operation is not available. For example, if a class
sets '
'"__iter__()"\n'
'to "None", the class is not iterable, so
calling "iter()" on '
'its\n'
'instances will raise a "TypeError"
(without falling back to\n'
'"__getitem__()"). [2]\n'
'\n'
'When implementing a class that emulates any built-in
type, '
'it is\n'
'important that the emulation only be implemented to
the '
'degree that it\n'
'makes sense for the object being modelled. For
example, '
'some\n'
'sequences may work well with retrieval of individual
'
'elements, but\n'
'extracting a slice may not make sense. (One example
of this '
'is the\n'
'"NodeList" interface in the W3C’s
Document Object Model.)\n'
'\n'
'\n'
'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'
'\n'
' If "__new__()" returns an instance of
*cls*, then the '
'new\n'
' instance’s "__init__()" method will
be invoked like\n'
' "__init__(self[, ...])", where *self*
is the new instance '
'and the\n'
' remaining arguments are the same as were passed
to '
'"__new__()".\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'
' called a finalizer or (improperly) a destructor.
If a '
'base class\n'
' has a "__del__()" method, the derived
class’s "__del__()" '
'method,\n'
' if any, must explicitly call it to ensure proper
deletion '
'of the\n'
' base class part of the instance.\n'
'\n'
' It is possible (though not recommended!) for the
'
'"__del__()" method\n'
' to postpone destruction of the instance by
creating a new '
'reference\n'
' to it. This is called object *resurrection*. It
is\n'
' implementation-dependent whether
"__del__()" is called a '
'second\n'
' time when a resurrected object is about to be
destroyed; '
'the\n'
' current *CPython* implementation only calls it
once.\n'
'\n'
' It is not guaranteed that "__del__()"
methods are called '
'for\n'
' objects that still exist when the interpreter
exits.\n'
'\n'
' Note: "del x" doesn’t directly call
"x.__del__()" — the '
'former\n'
' decrements the reference count for
"x" by one, and the '
'latter is\n'
' only called when "x"’s reference
count reaches zero.\n'
'\n'
' **CPython implementation detail:** It is possible
for a '
'reference\n'
' cycle to prevent the reference count of an object
from '
'going to\n'
' zero. In this case, the cycle will be later
detected and '
'deleted\n'
' by the *cyclic garbage collector*. A common
cause of '
'reference\n'
' cycles is when an exception has been caught in a
local '
'variable.\n'
' The frame’s locals then reference the
exception, which '
'references\n'
' its own traceback, which references the locals of
all '
'frames caught\n'
' in the traceback.\n'
'\n'
' See also: Documentation for the "gc"
module.\n'
'\n'
' Warning: Due to the precarious circumstances
under which\n'
' "__del__()" methods are invoked,
exceptions that occur '
'during\n'
' their execution are ignored, and a warning is
printed '
'to\n'
' "sys.stderr" instead. In
particular:\n'
'\n'
' * "__del__()" can be invoked when
arbitrary code is '
'being\n'
' executed, including from any arbitrary
thread. If '
'"__del__()"\n'
' needs to take a lock or invoke any other
blocking '
'resource, it\n'
' may deadlock as the resource may already be
taken by '
'the code\n'
' that gets interrupted to execute
"__del__()".\n'
'\n'
' * "__del__()" can be executed during
interpreter '
'shutdown. As\n'
' a consequence, the global variables it needs
to '
'access\n'
' (including other modules) may already have
been '
'deleted or set\n'
' to "None". Python guarantees that
globals whose name '
'begins\n'
' with a single underscore are deleted from
their '
'module before\n'
' other globals are deleted; if no other
references to '
'such\n'
' globals exist, this may help in assuring that
'
'imported modules\n'
' are still available at the time when the
"__del__()" '
'method is\n'
' called.\n'
'\n'
'object.__repr__(self)\n'
'\n'
' 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'
' object. The "format_spec" argument is a
string that '
'contains a\n'
' description of the formatting options desired.
The '
'interpretation\n'
' 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'
'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'
' By default, "__ne__()" delegates to
"__eq__()" and '
'inverts the\n'
' result unless it is "NotImplemented".
There are no other '
'implied\n'
' relationships among the comparison operators, for
'
'example, the\n'
' truth of "(x<y or x==y)" does not
imply "x<=y". To '
'automatically\n'
' generate 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'
'\n'
' Note: "hash()" truncates the value
returned from an '
'object’s\n'
' custom "__hash__()" method to the
size of a '
'"Py_ssize_t". This\n'
' is typically 8 bytes on 64-bit builds and 4
bytes on '
'32-bit\n'
' builds. If an object’s
"__hash__()" must interoperate '
'on builds\n'
' of different bit sizes, be sure to check the
width on '
'all\n'
' supported builds. An easy way to do this is
with '
'"python -c\n'
' "import sys;
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,
'
'collections.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.Hashable)" '
'call.\n'
'\n'
' Note: By default, the "__hash__()"
values of str, bytes '
'and\n'
' datetime objects are “salted” with an
unpredictable '
'random value.\n'
' Although they remain constant within an
individual '
'Python\n'
' process, they are not predictable between
repeated '
'invocations of\n'
' Python.This is intended to provide protection
against a '
'denial-\n'
' of-service caused by carefully-chosen inputs
that '
'exploit the\n'
' worst case performance of a dict insertion,
O(n^2) '
'complexity.\n'
' See
http://www.ocert.org/advisories/ocert-2011-003.html '
'for\n'
' details.Changing hash values affects the
iteration '
'order of\n'
' dicts, sets and other mappings. Python has
never made '
'guarantees\n'
' about this ordering (and it typically varies
between '
'32-bit and\n'
' 64-bit builds).See also
"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'
'\n'
'\n'
'Customizing attribute access\n'
'============================\n'
'\n'
'The following methods can be defined to customize
the '
'meaning of\n'
'attribute access (use of, assignment to, or deletion
of '
'"x.name") for\n'
'class instances.\n'
'\n'
'object.__getattr__(self, name)\n'
'\n'
' Called when the default attribute access fails
with an\n'
' "AttributeError" (either
"__getattribute__()" raises an\n'
' "AttributeError" because *name* is not
an instance '
'attribute or an\n'
' attribute in the class tree for "self";
or "__get__()" of '
'a *name*\n'
' property raises "AttributeError").
This method should '
'either\n'
' return the (computed) attribute value or raise an
'
'"AttributeError"\n'
' exception.\n'
'\n'
' Note that if the attribute is found through the
normal '
'mechanism,\n'
' "__getattr__()" is not called. (This
is an intentional '
'asymmetry\n'
' between "__getattr__()" and
"__setattr__()".) This is '
'done both for\n'
' efficiency reasons and because otherwise
"__getattr__()" '
'would have\n'
' no way to access other attributes of the
instance. Note '
'that at\n'
' least for instance variables, you can fake total
control '
'by not\n'
' inserting any values in the instance attribute
dictionary '
'(but\n'
' instead inserting them in another object). See
the\n'
' "__getattribute__()" method below for a
way to actually '
'get total\n'
' control over attribute access.\n'
'\n'
'object.__getattribute__(self, name)\n'
'\n'
' Called unconditionally to implement attribute
accesses '
'for\n'
' instances of the class. If the class also defines
'
'"__getattr__()",\n'
' the latter will not be called unless
"__getattribute__()" '
'either\n'
' calls it explicitly or raises an
"AttributeError". This '
'method\n'
' should return the (computed) attribute value or
raise an\n'
' "AttributeError" exception. In order to
avoid infinite '
'recursion in\n'
' this method, its implementation should always
call the '
'base class\n'
' method with the same name to access any
attributes it '
'needs, for\n'
' example, "object.__getattribute__(self,
name)".\n'
'\n'
' Note: This method may still be bypassed when
looking up '
'special\n'
' methods as the result of implicit invocation
via '
'language syntax\n'
' or built-in functions. See Special method
lookup.\n'
'\n'
'object.__setattr__(self, name, value)\n'
'\n'
' Called when an attribute assignment is attempted.
This '
'is called\n'
' instead of the normal mechanism (i.e. store the
value in '
'the\n'
' instance dictionary). *name* is the attribute
name, '
'*value* is the\n'
' value to be assigned to it.\n'
'\n'
' If "__setattr__()" wants to assign to
an instance '
'attribute, it\n'
' should call the base class method with the same
name, for '
'example,\n'
' "object.__setattr__(self, name,
value)".\n'
'\n'
'object.__delattr__(self, name)\n'
'\n'
' Like "__setattr__()" but for attribute
deletion instead '
'of\n'
' assignment. This should only be implemented if
"del '
'obj.name" is\n'
' meaningful for the object.\n'
'\n'
'object.__dir__(self)\n'
'\n'
' Called when "dir()" is called on the
object. A sequence '
'must be\n'
' returned. "dir()" converts the returned
sequence to a '
'list and\n'
' sorts it.\n'
'\n'
'\n'
'Customizing module attribute access\n'
'-----------------------------------\n'
'\n'
'For a more fine grained customization of the module
behavior '
'(setting\n'
'attributes, properties, etc.), one can set the
"__class__" '
'attribute\n'
'of a module object to a subclass of
"types.ModuleType". For '
'example:\n'
'\n'
' import sys\n'
' from types import ModuleType\n'
'\n'
' class VerboseModule(ModuleType):\n'
' def __repr__(self):\n'
" return f'Verbose
{self.__name__}'\n"
'\n'
' def __setattr__(self, attr, value):\n'
" print(f'Setting
{attr}...')\n"
' setattr(self, attr, value)\n'
'\n'
' sys.modules[__name__].__class__ =
VerboseModule\n'
'\n'
'Note: Setting module "__class__" only
affects lookups made '
'using the\n'
' attribute access syntax – directly accessing the
module '
'globals\n'
' (whether by code within the module, or via a
reference to '
'the\n'
' module’s globals dictionary) is
unaffected.\n'
'\n'
'Changed in version 3.5: "__class__" module
attribute is now '
'writable.\n'
'\n'
'\n'
'Implementing Descriptors\n'
'------------------------\n'
'\n'
'The following methods only apply when an instance of
the '
'class\n'
'containing the method (a so-called *descriptor*
class) '
'appears in an\n'
'*owner* class (the descriptor must be in either the
owner’s '
'class\n'
'dictionary or in the class dictionary for one of its
'
'parents). In the\n'
'examples below, “the attribute” refers to the
attribute '
'whose name is\n'
'the key of the property in the owner class’
"__dict__".\n'
'\n'
'object.__get__(self, instance, owner)\n'
'\n'
' Called to get the attribute of the owner class
(class '
'attribute\n'
' access) or of an instance of that class (instance
'
'attribute\n'
' access). *owner* is always the owner class, while
'
'*instance* is the\n'
' instance that the attribute was accessed through,
or '
'"None" when\n'
' the attribute is accessed through the *owner*.
This '
'method should\n'
' return the (computed) attribute value or raise an
'
'"AttributeError"\n'
' exception.\n'
'\n'
'object.__set__(self, instance, value)\n'
'\n'
' Called to set the attribute on an instance
*instance* of '
'the owner\n'
' class to a new value, *value*.\n'
'\n'
'object.__delete__(self, instance)\n'
'\n'
' Called to delete the attribute on an instance
*instance* '
'of the\n'
' owner class.\n'
'\n'
'object.__set_name__(self, owner, name)\n'
'\n'
' Called at the time the owning class *owner* is
created. '
'The\n'
' descriptor has been assigned to *name*.\n'
'\n'
' New in version 3.6.\n'
'\n'
'The attribute "__objclass__" is
interpreted by the "inspect" '
'module as\n'
'specifying the class where this object was defined
(setting '
'this\n'
'appropriately can assist in runtime introspection of
dynamic '
'class\n'
'attributes). For callables, it may indicate that an
instance '
'of the\n'
'given type (or a subclass) is expected or required
as the '
'first\n'
'positional argument (for example, CPython sets this
'
'attribute for\n'
'unbound methods that are implemented in C).\n'
'\n'
'\n'
'Invoking Descriptors\n'
'--------------------\n'
'\n'
'In general, a descriptor is an object attribute with
'
'“binding\n'
'behavior”, one whose attribute access has been
overridden by '
'methods\n'
'in the descriptor protocol: "__get__()",
"__set__()", and\n'
'"__delete__()". If any of those methods
are defined for an '
'object, it\n'
'is said to be a descriptor.\n'
'\n'
'The default behavior for attribute access is to get,
set, or '
'delete\n'
'the attribute from an object’s dictionary. For
instance, '
'"a.x" has a\n'
'lookup chain starting with
"a.__dict__[\'x\']", then\n'
'"type(a).__dict__[\'x\']", and
continuing through the base '
'classes of\n'
'"type(a)" excluding metaclasses.\n'
'\n'
'However, if the looked-up value is an object
defining one of '
'the\n'
'descriptor methods, then Python may override the
default '
'behavior and\n'
'invoke the descriptor method instead. Where this
occurs in '
'the\n'
'precedence chain depends on which descriptor methods
were '
'defined and\n'
'how they were called.\n'
'\n'
'The starting point for descriptor invocation is a
binding, '
'"a.x". How\n'
'the arguments are assembled depends on
"a":\n'
'\n'
'Direct Call\n'
' The simplest and least common call is when user
code '
'directly\n'
' invokes a descriptor method:
"x.__get__(a)".\n'
'\n'
'Instance Binding\n'
' If binding to an object instance, "a.x"
is transformed '
'into the\n'
' call:
"type(a).__dict__[\'x\'].__get__(a, type(a))".\n'
'\n'
'Class Binding\n'
' If binding to a class, "A.x" is
transformed into the '
'call:\n'
' "A.__dict__[\'x\'].__get__(None,
A)".\n'
'\n'
'Super Binding\n'
' If "a" is an instance of
"super", then the binding '
'"super(B,\n'
' obj).m()" searches
"obj.__class__.__mro__" for the base '
'class "A"\n'
' immediately preceding "B" and then
invokes the descriptor '
'with the\n'
' call:
"A.__dict__[\'m\'].__get__(obj,
obj.__class__)".\n'
'\n'
'For instance bindings, the precedence of descriptor
'
'invocation depends\n'
'on the which descriptor methods are defined. A
descriptor '
'can define\n'
'any combination of "__get__()",
"__set__()" and '
'"__delete__()". If it\n'
'does not define "__get__()", then
accessing the attribute '
'will return\n'
'the descriptor object itself unless there is a value
in the '
'object’s\n'
'instance dictionary. If the descriptor defines
"__set__()" '
'and/or\n'
'"__delete__()", it is a data descriptor;
if it defines '
'neither, it is\n'
'a non-data descriptor. Normally, data descriptors
define '
'both\n'
'"__get__()" and "__set__()",
while non-data descriptors have '
'just the\n'
'"__get__()" method. Data descriptors with
"__set__()" and '
'"__get__()"\n'
'defined always override a redefinition in an
instance '
'dictionary. In\n'
'contrast, non-data descriptors can be overridden by
'
'instances.\n'
'\n'
'Python methods (including "staticmethod()"
and '
'"classmethod()") are\n'
'implemented as non-data descriptors. Accordingly,
instances '
'can\n'
'redefine and override methods. This allows
individual '
'instances to\n'
'acquire behaviors that differ from other instances
of the '
'same class.\n'
'\n'
'The "property()" function is implemented
as a data '
'descriptor.\n'
'Accordingly, instances cannot override the behavior
of a '
'property.\n'
'\n'
'\n'
'__slots__\n'
'---------\n'
'\n'
'*__slots__* allow us to explicitly declare data
members '
'(like\n'
'properties) and deny the creation of *__dict__* and
'
'*__weakref__*\n'
'(unless explicitly declared in *__slots__* or
available in a '
'parent.)\n'
'\n'
'The space saved over using *__dict__* can be
significant.\n'
'\n'
'object.__slots__\n'
'\n'
' This class variable can be assigned a string,
iterable, '
'or sequence\n'
' of strings with variable names used by instances.
'
'*__slots__*\n'
' reserves space for the declared variables and
prevents '
'the\n'
' automatic creation of *__dict__* and
*__weakref__* for '
'each\n'
' instance.\n'
'\n'
'\n'
'Notes on using *__slots__*\n'
'~~~~~~~~~~~~~~~~~~~~~~~~~~\n'
'\n'
'* When inheriting from a class without *__slots__*,
the '
'*__dict__*\n'
' and *__weakref__* attribute of the instances will
always '
'be\n'
' accessible.\n'
'\n'
'* Without a *__dict__* variable, instances cannot be
'
'assigned new\n'
' variables not listed in the *__slots__*
definition. '
'Attempts to\n'
' assign to an unlisted variable name raises '
'"AttributeError". If\n'
' dynamic assignment of new variables is desired,
then add\n'
' "\'__dict__\'" to the sequence
of strings in the '
'*__slots__*\n'
' declaration.\n'
'\n'
'* Without a *__weakref__* variable for each
instance, '
'classes\n'
' defining *__slots__* do not support weak
references to '
'its\n'
' instances. If weak reference support is needed,
then add\n'
' "\'__weakref__\'" to the
sequence of strings in the '
'*__slots__*\n'
' declaration.\n'
'\n'
'* *__slots__* are implemented at the class level by
'
'creating\n'
' descriptors (Implementing Descriptors) for each
variable '
'name. As a\n'
' result, class attributes cannot be used to set
default '
'values for\n'
' instance variables defined by *__slots__*;
otherwise, the '
'class\n'
' attribute would overwrite the descriptor
assignment.\n'
'\n'
'* The action of a *__slots__* declaration is not
limited to '
'the\n'
' class where it is defined. *__slots__* declared
in '
'parents are\n'
' available in child classes. However, child
subclasses will '
'get a\n'
' *__dict__* and *__weakref__* unless they also
define '
'*__slots__*\n'
' (which should only contain names of any
*additional* '
'slots).\n'
'\n'
'* If a class defines a slot also defined in a base
class, '
'the\n'
' instance variable defined by the base class slot
is '
'inaccessible\n'
' (except by retrieving its descriptor directly from
the '
'base class).\n'
' This renders the meaning of the program undefined.
In the '
'future, a\n'
' check may be added to prevent this.\n'
'\n'
'* Nonempty *__slots__* does not work for classes
derived '
'from\n'
' “variable-length” built-in types such as
"int", "bytes" '
'and "tuple".\n'
'\n'
'* Any non-string iterable may be assigned to
*__slots__*. '
'Mappings\n'
' may also be used; however, in the future, special
meaning '
'may be\n'
' assigned to the values corresponding to each
key.\n'
'\n'
'* *__class__* assignment works only if both classes
have the '
'same\n'
' *__slots__*.\n'
'\n'
'* Multiple inheritance with multiple slotted parent
classes '
'can be\n'
' used, but only one parent is allowed to have
attributes '
'created by\n'
' slots (the other bases must have empty slot
layouts) - '
'violations\n'
' raise "TypeError".\n'
'\n'
'\n'
'Customizing class creation\n'
'==========================\n'
'\n'
'Whenever a class inherits from another class, '
'*__init_subclass__* is\n'
'called on that class. This way, it is possible to
write '
'classes which\n'
'change the behavior of subclasses. This is closely
related '
'to class\n'
'decorators, but where class decorators only affect
the '
'specific class\n'
'they’re applied to, "__init_subclass__"
solely applies to '
'future\n'
'subclasses of the class defining the method.\n'
'\n'
'classmethod object.__init_subclass__(cls)\n'
'\n'
' This method is called whenever the containing
class is '
'subclassed.\n'
' *cls* is then the new subclass. If defined as a
normal '
'instance\n'
' method, this method is implicitly converted to a
class '
'method.\n'
'\n'
' Keyword arguments which are given to a new class
are '
'passed to the\n'
' parent’s class "__init_subclass__".
For compatibility '
'with other\n'
' classes using "__init_subclass__", one
should take out '
'the needed\n'
' keyword arguments and pass the others over to the
base '
'class, as\n'
' in:\n'
'\n'
' class Philosopher:\n'
' def __init_subclass__(cls, default_name,
'
'**kwargs):\n'
'
super().__init_subclass__(**kwargs)\n'
' cls.default_name =
default_name\n'
'\n'
' class AustralianPhilosopher(Philosopher,
'
'default_name="Bruce"):\n'
' pass\n'
'\n'
' The default implementation
"object.__init_subclass__" '
'does nothing,\n'
' but raises an error if it is called with any
arguments.\n'
'\n'
' Note: The metaclass hint "metaclass" is
consumed by the '
'rest of\n'
' the type machinery, and is never passed to
'
'"__init_subclass__"\n'
' implementations. The actual metaclass (rather
than the '
'explicit\n'
' hint) can be accessed as
"type(cls)".\n'
'\n'
' New in version 3.6.\n'
'\n'
'\n'
'Metaclasses\n'
'-----------\n'
'\n'
'By default, classes are constructed using
"type()". The '
'class body is\n'
'executed in a new namespace and the class name is
bound '
'locally to the\n'
'result of "type(name, bases,
namespace)".\n'
'\n'
'The class creation process can be customized by
passing the\n'
'"metaclass" keyword argument in the class
definition line, '
'or by\n'
'inheriting from an existing class that included such
an '
'argument. In\n'
'the following example, both "MyClass" and
"MySubclass" are '
'instances\n'
'of "Meta":\n'
'\n'
' class Meta(type):\n'
' pass\n'
'\n'
' class MyClass(metaclass=Meta):\n'
' pass\n'
'\n'
' class MySubclass(MyClass):\n'
' pass\n'
'\n'
'Any other keyword arguments that are specified in
the class '
'definition\n'
'are passed through to all metaclass operations
described '
'below.\n'
'\n'
'When a class definition is executed, the following
steps '
'occur:\n'
'\n'
'* the appropriate metaclass is determined\n'
'\n'
'* the class namespace is prepared\n'
'\n'
'* the class body is executed\n'
'\n'
'* the class object is created\n'
'\n'
'\n'
'Determining the appropriate metaclass\n'
'-------------------------------------\n'
'\n'
'The appropriate metaclass for a class definition is
'
'determined as\n'
'follows:\n'
'\n'
'* if no bases and no explicit metaclass are given,
then '
'"type()" is\n'
' used\n'
'\n'
'* if an explicit metaclass is given and it is *not*
an '
'instance of\n'
' "type()", then it is used directly as
the metaclass\n'
'\n'
'* if an instance of "type()" is given as
the explicit '
'metaclass, or\n'
' bases are defined, then the most derived metaclass
is '
'used\n'
'\n'
'The most derived metaclass is selected from the
explicitly '
'specified\n'
'metaclass (if any) and the metaclasses (i.e.
"type(cls)") of '
'all\n'
'specified base classes. The most derived metaclass
is one '
'which is a\n'
'subtype of *all* of these candidate metaclasses. If
none of '
'the\n'
'candidate metaclasses meets that criterion, then the
class '
'definition\n'
'will fail with "TypeError".\n'
'\n'
'\n'
'Preparing the class namespace\n'
'-----------------------------\n'
'\n'
'Once the appropriate metaclass has been identified,
then the '
'class\n'
'namespace is prepared. If the metaclass has a
"__prepare__" '
'attribute,\n'
'it is called as "namespace =
metaclass.__prepare__(name, '
'bases,\n'
'**kwds)" (where the additional keyword
arguments, if any, '
'come from\n'
'the class definition).\n'
'\n'
'If the metaclass has no "__prepare__"
attribute, then the '
'class\n'
'namespace is initialised as an empty ordered
mapping.\n'
'\n'
'See also:\n'
'\n'
' **PEP 3115** - Metaclasses in Python 3000\n'
' Introduced the "__prepare__"
namespace hook\n'
'\n'
'\n'
'Executing the class body\n'
'------------------------\n'
'\n'
'The class body is executed (approximately) as
"exec(body, '
'globals(),\n'
'namespace)". The key difference from a normal
call to '
'"exec()" is that\n'
'lexical scoping allows the class body (including any
'
'methods) to\n'
'reference names from the current and outer scopes
when the '
'class\n'
'definition occurs inside a function.\n'
'\n'
'However, even when the class definition occurs
inside the '
'function,\n'
'methods defined inside the class still cannot see
names '
'defined at the\n'
'class scope. Class variables must be accessed
through the '
'first\n'
'parameter of instance or class methods, or through
the '
'implicit\n'
'lexically scoped "__class__" reference
described in the next '
'section.\n'
'\n'
'\n'
'Creating the class object\n'
'-------------------------\n'
'\n'
'Once the class namespace has been populated by
executing the '
'class\n'
'body, the class object is created by calling '
'"metaclass(name, bases,\n'
'namespace, **kwds)" (the additional keywords
passed here are '
'the same\n'
'as those passed to "__prepare__").\n'
'\n'
'This class object is the one that will be referenced
by the '
'zero-\n'
'argument form of "super()".
"__class__" is an implicit '
'closure\n'
'reference created by the compiler if any methods in
a class '
'body refer\n'
'to either "__class__" or
"super". This allows the zero '
'argument form\n'
'of "super()" to correctly identify the
class being defined '
'based on\n'
'lexical scoping, while the class or instance that
was used '
'to make the\n'
'current call is identified based on the first
argument '
'passed to the\n'
'method.\n'
'\n'
'**CPython implementation detail:** In CPython 3.6
and later, '
'the\n'
'"__class__" cell is passed to the
metaclass as a '
'"__classcell__" entry\n'
'in the class namespace. If present, this must be
propagated '
'up to the\n'
'"type.__new__" call in order for the class
to be '
'initialised\n'
'correctly. Failing to do so will result in a '
'"DeprecationWarning" in\n'
'Python 3.6, and a "RuntimeError" in Python
3.8.\n'
'\n'
'When using the default metaclass "type",
or any metaclass '
'that\n'
'ultimately calls "type.__new__", the
following additional\n'
'customisation steps are invoked after creating the
class '
'object:\n'
'\n'
'* first, "type.__new__" collects all of
the descriptors in '
'the class\n'
' namespace that define a "__set_name__()"
method;\n'
'\n'
'* second, all of these "__set_name__"
methods are called '
'with the\n'
' class being defined and the assigned name of that
'
'particular\n'
' descriptor; and\n'
'\n'
'* finally, the "__init_subclass__()" hook
is called on the '
'immediate\n'
' parent of the new class in its method resolution
order.\n'
'\n'
'After the class object is created, it is passed to
the '
'class\n'
'decorators included in the class definition (if any)
and the '
'resulting\n'
'object is bound in the local namespace as the
defined '
'class.\n'
'\n'
'When a new class is created by
"type.__new__", the object '
'provided as\n'
'the namespace parameter is copied to a new ordered
mapping '
'and the\n'
'original object is discarded. The new copy is
wrapped in a '
'read-only\n'
'proxy, which becomes the "__dict__"
attribute of the class '
'object.\n'
'\n'
'See also:\n'
'\n'
' **PEP 3135** - New super\n'
' Describes the implicit "__class__"
closure reference\n'
'\n'
'\n'
'Uses for metaclasses\n'
'--------------------\n'
'\n'
'The potential uses for metaclasses are boundless.
Some ideas '
'that have\n'
'been explored include enum, logging, interface
checking, '
'automatic\n'
'delegation, automatic property creation, proxies,
'
'frameworks, and\n'
'automatic resource locking/synchronization.\n'
'\n'
'\n'
'Customizing instance and subclass checks\n'
'========================================\n'
'\n'
'The following methods are used to override the
default '
'behavior of the\n'
'"isinstance()" and
"issubclass()" built-in functions.\n'
'\n'
'In particular, the metaclass "abc.ABCMeta"
implements these '
'methods in\n'
'order to allow the addition of Abstract Base Classes
(ABCs) '
'as\n'
'“virtual base classes” to any class or type
(including '
'built-in\n'
'types), including other ABCs.\n'
'\n'
'class.__instancecheck__(self, instance)\n'
'\n'
' Return true if *instance* should be considered a
(direct '
'or\n'
' indirect) instance of *class*. If defined, called
to '
'implement\n'
' "isinstance(instance, class)".\n'
'\n'
'class.__subclasscheck__(self, subclass)\n'
'\n'
' Return true if *subclass* should be considered a
(direct '
'or\n'
' indirect) subclass of *class*. If defined,
called to '
'implement\n'
' "issubclass(subclass, class)".\n'
'\n'
'Note that these methods are looked up on the type
'
'(metaclass) of a\n'
'class. They cannot be defined as class methods in
the '
'actual class.\n'
'This is consistent with the lookup of special
methods that '
'are called\n'
'on instances, only in this case the instance is
itself a '
'class.\n'
'\n'
'See also:\n'
'\n'
' **PEP 3119** - Introducing Abstract Base
Classes\n'
' Includes the specification for customizing
'
'"isinstance()" and\n'
' "issubclass()" behavior through
"__instancecheck__()" '
'and\n'
' "__subclasscheck__()", with
motivation for this '
'functionality in\n'
' the context of adding Abstract Base Classes
(see the '
'"abc"\n'
' module) to the language.\n'
'\n'
'\n'
'Emulating callable objects\n'
'==========================\n'
'\n'
'object.__call__(self[, args...])\n'
'\n'
' Called when the instance is “called” as a
function; if '
'this method\n'
' is defined, "x(arg1, arg2, ...)" is a
shorthand for\n'
' "x.__call__(arg1, arg2, ...)".\n'
'\n'
'\n'
'Emulating container types\n'
'=========================\n'
'\n'
'The following methods can be defined to implement
container '
'objects.\n'
'Containers usually are sequences (such as lists or
tuples) '
'or mappings\n'
'(like dictionaries), but can represent other
containers as '
'well. The\n'
'first set of methods is used either to emulate a
sequence or '
'to\n'
'emulate a mapping; the difference is that for a
sequence, '
'the\n'
'allowable keys should be the integers *k* for which
"0 <= k '
'< N" where\n'
'*N* is the length of the sequence, or slice objects,
which '
'define a\n'
'range of items. It is also recommended that
mappings '
'provide the\n'
'methods "keys()", "values()",
"items()", "get()", '
'"clear()",\n'
'"setdefault()", "pop()",
"popitem()", "copy()", and '
'"update()"\n'
'behaving similar to those for Python’s standard
dictionary '
'objects.\n'
'The "collections" module provides a
"MutableMapping" '
'abstract base\n'
'class to help create those methods from a base set
of '
'"__getitem__()",\n'
'"__setitem__()",
"__delitem__()", and "keys()". Mutable '
'sequences\n'
'should provide methods "append()",
"count()", "index()", '
'"extend()",\n'
'"insert()", "pop()",
"remove()", "reverse()" and "sort()", '
'like Python\n'
'standard list objects. Finally, sequence types
should '
'implement\n'
'addition (meaning concatenation) and multiplication
'
'(meaning\n'
'repetition) by defining the methods
"__add__()", '
'"__radd__()",\n'
'"__iadd__()", "__mul__()",
"__rmul__()" and "__imul__()" '
'described\n'
'below; they should not define other numerical
operators. It '
'is\n'
'recommended that both mappings and sequences
implement the\n'
'"__contains__()" method to allow efficient
use of the "in" '
'operator;\n'
'for mappings, "in" should search the
mapping’s keys; for '
'sequences, it\n'
'should search through the values. It is further
recommended '
'that both\n'
'mappings and sequences implement the
"__iter__()" method to '
'allow\n'
'efficient iteration through the container; for
mappings, '
'"__iter__()"\n'
'should be the same as "keys()"; for
sequences, it should '
'iterate\n'
'through the values.\n'
'\n'
'object.__len__(self)\n'
'\n'
' Called to implement the built-in function
"len()". '
'Should return\n'
' the length of the object, an integer
">=" 0. Also, an '
'object that\n'
' doesn’t define a "__bool__()" method
and whose '
'"__len__()" method\n'
' returns zero is considered to be false in a
Boolean '
'context.\n'
'\n'
' **CPython implementation detail:** In CPython,
the length '
'is\n'
' required to be at most "sys.maxsize".
If the length is '
'larger than\n'
' "sys.maxsize" some features (such as
"len()") may raise\n'
' "OverflowError". To prevent raising
"OverflowError" by '
'truth value\n'
' testing, an object must define a
"__bool__()" method.\n'
'\n'
'object.__length_hint__(self)\n'
'\n'
' Called to implement
"operator.length_hint()". Should '
'return an\n'
' estimated length for the object (which may be
greater or '
'less than\n'
' the actual length). The length must be an integer
">=" 0. '
'This\n'
' method is purely an optimization and is never
required '
'for\n'
' correctness.\n'
'\n'
' New in version 3.4.\n'
'\n'
'Note: Slicing is done exclusively with the following
three '
'methods.\n'
' A call like\n'
'\n'
' a[1:2] = b\n'
'\n'
' is translated to\n'
'\n'
' a[slice(1, 2, None)] = b\n'
'\n'
' and so forth. Missing slice items are always
filled in '
'with "None".\n'
'\n'
'object.__getitem__(self, key)\n'
'\n'
' Called to implement evaluation of
"self[key]". For '
'sequence types,\n'
' the accepted keys should be integers and slice
objects. '
'Note that\n'
' the special interpretation of negative indexes
(if the '
'class wishes\n'
' to emulate a sequence type) is up to the
"__getitem__()" '
'method. If\n'
' *key* is of an inappropriate type,
"TypeError" may be '
'raised; if of\n'
' a value outside the set of indexes for the
sequence '
'(after any\n'
' special interpretation of negative values),
"IndexError" '
'should be\n'
' raised. For mapping types, if *key* is missing
(not in '
'the\n'
' container), "KeyError" should be
raised.\n'
'\n'
' Note: "for" loops expect that an
"IndexError" will be '
'raised for\n'
' illegal indexes to allow proper detection of
the end of '
'the\n'
' sequence.\n'
'\n'
'object.__setitem__(self, key, value)\n'
'\n'
' Called to implement assignment to
"self[key]". Same note '
'as for\n'
' "__getitem__()". This should only be
implemented for '
'mappings if\n'
' the objects support changes to the values for
keys, or if '
'new keys\n'
' can be added, or for sequences if elements can be
'
'replaced. The\n'
' same exceptions should be raised for improper
*key* '
'values as for\n'
' the "__getitem__()" method.\n'
'\n'
'object.__delitem__(self, key)\n'
'\n'
' Called to implement deletion of
"self[key]". Same note '
'as for\n'
' "__getitem__()". This should only be
implemented for '
'mappings if\n'
' the objects support removal of keys, or for
sequences if '
'elements\n'
' can be removed from the sequence. The same
exceptions '
'should be\n'
' raised for improper *key* values as for the
'
'"__getitem__()" method.\n'
'\n'
'object.__missing__(self, key)\n'
'\n'
' Called by
"dict"."__getitem__()" to implement
"self[key]" '
'for dict\n'
' subclasses when key is not in the
dictionary.\n'
'\n'
'object.__iter__(self)\n'
'\n'
' This method is called when an iterator is
required for a '
'container.\n'
' This method should return a new iterator object
that can '
'iterate\n'
' over all the objects in the container. For
mappings, it '
'should\n'
' iterate over the keys of the container.\n'
'\n'
' Iterator objects also need to implement this
method; they '
'are\n'
' required to return themselves. For more
information on '
'iterator\n'
' objects, see Iterator Types.\n'
'\n'
'object.__reversed__(self)\n'
'\n'
' Called (if present) by the "reversed()"
built-in to '
'implement\n'
' reverse iteration. It should return a new
iterator '
'object that\n'
' iterates over all the objects in the container in
reverse '
'order.\n'
'\n'
' If the "__reversed__()" method is not
provided, the '
'"reversed()"\n'
' built-in will fall back to using the sequence
protocol '
'("__len__()"\n'
' and "__getitem__()"). Objects that
support the sequence '
'protocol\n'
' should only provide "__reversed__()" if
they can provide '
'an\n'
' implementation that is more efficient than the
one '
'provided by\n'
' "reversed()".\n'
'\n'
'The membership test operators ("in" and
"not in") are '
'normally\n'
'implemented as an iteration through a sequence.
However, '
'container\n'
'objects can supply the following special method with
a more '
'efficient\n'
'implementation, which also does not require the
object be a '
'sequence.\n'
'\n'
'object.__contains__(self, item)\n'
'\n'
' Called to implement membership test operators.
Should '
'return true\n'
' if *item* is in *self*, false otherwise. For
mapping '
'objects, this\n'
' should consider the keys of the mapping rather
than the '
'values or\n'
' the key-item pairs.\n'
'\n'
' For objects that don’t define
"__contains__()", the '
'membership test\n'
' first tries iteration via "__iter__()",
then the old '
'sequence\n'
' iteration protocol via "__getitem__()",
see this section '
'in the\n'
' language reference.\n'
'\n'
'\n'
'Emulating numeric types\n'
'=======================\n'
'\n'
'The following methods can be defined to emulate
numeric '
'objects.\n'
'Methods corresponding to operations that are not
supported '
'by the\n'
'particular kind of number implemented (e.g., bitwise
'
'operations for\n'
'non-integral numbers) should be left
undefined.\n'
'\n'
'object.__add__(self, other)\n'
'object.__sub__(self, other)\n'
'object.__mul__(self, other)\n'
'object.__matmul__(self, other)\n'
'object.__truediv__(self, other)\n'
'object.__floordiv__(self, other)\n'
'object.__mod__(self, other)\n'
'object.__divmod__(self, other)\n'
'object.__pow__(self, other[, modulo])\n'
'object.__lshift__(self, other)\n'
'object.__rshift__(self, other)\n'
'object.__and__(self, other)\n'
'object.__xor__(self, other)\n'
'object.__or__(self, other)\n'
'\n'
' These methods are called to implement the binary
'
'arithmetic\n'
' operations ("+", "-",
"*", "@", "/", "//", "%",
'
'"divmod()",\n'
' "pow()", "**",
"<<", ">>", "&",
"^", "|"). For instance, '
'to\n'
' evaluate the expression "x + y", where
*x* is an instance '
'of a\n'
' class that has an "__add__()" method,
"x.__add__(y)" is '
'called.\n'
' The "__divmod__()" method should be the
equivalent to '
'using\n'
' "__floordiv__()" and
"__mod__()"; it should not be '
'related to\n'
' "__truediv__()". Note that
"__pow__()" should be defined '
'to accept\n'
' an optional third argument if the ternary version
of the '
'built-in\n'
' "pow()" function is to be
supported.\n'
'\n'
' If one of those methods does not support the
operation '
'with the\n'
' supplied arguments, it should return
"NotImplemented".\n'
'\n'
'object.__radd__(self, other)\n'
'object.__rsub__(self, other)\n'
'object.__rmul__(self, other)\n'
'object.__rmatmul__(self, other)\n'
'object.__rtruediv__(self, other)\n'
'object.__rfloordiv__(self, other)\n'
'object.__rmod__(self, other)\n'
'object.__rdivmod__(self, other)\n'
'object.__rpow__(self, other)\n'
'object.__rlshift__(self, other)\n'
'object.__rrshift__(self, other)\n'
'object.__rand__(self, other)\n'
'object.__rxor__(self, other)\n'
'object.__ror__(self, other)\n'
'\n'
' These methods are called to implement the binary
'
'arithmetic\n'
' operations ("+", "-",
"*", "@", "/", "//", "%",
'
'"divmod()",\n'
' "pow()", "**",
"<<", ">>", "&",
"^", "|") with reflected '
'(swapped)\n'
' operands. These functions are only called if the
left '
'operand does\n'
' not support the corresponding operation [3] and
the '
'operands are of\n'
' different types. [4] For instance, to evaluate
the '
'expression "x -\n'
' y", where *y* is an instance of a class that
has an '
'"__rsub__()"\n'
' method, "y.__rsub__(x)" is called if
"x.__sub__(y)" '
'returns\n'
' *NotImplemented*.\n'
'\n'
' Note that ternary "pow()" will not try
calling '
'"__rpow__()" (the\n'
' coercion rules would become too
complicated).\n'
'\n'
' Note: If the right operand’s type is a subclass
of the '
'left\n'
' operand’s type and that subclass provides the
reflected '
'method\n'
' for the operation, this method will be called
before '
'the left\n'
' operand’s non-reflected method. This
behavior allows '
'subclasses\n'
' to override their ancestors’
operations.\n'
'\n'
'object.__iadd__(self, other)\n'
'object.__isub__(self, other)\n'
'object.__imul__(self, other)\n'
'object.__imatmul__(self, other)\n'
'object.__itruediv__(self, other)\n'
'object.__ifloordiv__(self, other)\n'
'object.__imod__(self, other)\n'
'object.__ipow__(self, other[, modulo])\n'
'object.__ilshift__(self, other)\n'
'object.__irshift__(self, other)\n'
'object.__iand__(self, other)\n'
'object.__ixor__(self, other)\n'
'object.__ior__(self, other)\n'
'\n'
' These methods are called to implement the
augmented '
'arithmetic\n'
' assignments ("+=", "-=",
"*=", "@=", "/=", "//=",
"%=", '
'"**=",\n'
' "<<=", ">>=",
"&=", "^=", "|="). These methods should
'
'attempt to\n'
' do the operation in-place (modifying *self*) and
return '
'the result\n'
' (which could be, but does not have to be,
*self*). If a '
'specific\n'
' method is not defined, the augmented assignment
falls '
'back to the\n'
' normal methods. For instance, if *x* is an
instance of a '
'class\n'
' with an "__iadd__()" method, "x +=
y" is equivalent to "x '
'=\n'
' x.__iadd__(y)" . Otherwise,
"x.__add__(y)" and '
'"y.__radd__(x)" are\n'
' considered, as with the evaluation of "x +
y". In '
'certain\n'
' situations, augmented assignment can result in
unexpected '
'errors\n'
' (see Why does a_tuple[i] += [‘item’] raise an
exception '
'when the\n'
' addition works?), but this behavior is in fact
part of '
'the data\n'
' model.\n'
'\n'
'object.__neg__(self)\n'
'object.__pos__(self)\n'
'object.__abs__(self)\n'
'object.__invert__(self)\n'
'\n'
' Called to implement the unary arithmetic
operations ("-", '
'"+",\n'
' "abs()" and "~").\n'
'\n'
'object.__complex__(self)\n'
'object.__int__(self)\n'
'object.__float__(self)\n'
'\n'
' Called to implement the built-in functions
"complex()", '
'"int()" and\n'
' "float()". Should return a value of
the appropriate '
'type.\n'
'\n'
'object.__index__(self)\n'
'\n'
' Called to implement "operator.index()",
and whenever '
'Python needs\n'
' to losslessly convert the numeric object to an
integer '
'object (such\n'
' as in slicing, or in the built-in
"bin()", "hex()" and '
'"oct()"\n'
' functions). Presence of this method indicates
that the '
'numeric\n'
' object is an integer type. Must return an
integer.\n'
'\n'
' Note: In order to have a coherent integer type
class, '
'when\n'
' "__index__()" is defined
"__int__()" should also be '
'defined, and\n'
' both should return the same value.\n'
'\n'
'object.__round__(self[, ndigits])\n'
'object.__trunc__(self)\n'
'object.__floor__(self)\n'
'object.__ceil__(self)\n'
'\n'
' Called to implement the built-in function
"round()" and '
'"math"\n'
' functions "trunc()",
"floor()" and "ceil()". Unless '
'*ndigits* is\n'
' passed to "__round__()" all these
methods should return '
'the value\n'
' of the object truncated to an
"Integral" (typically an '
'"int").\n'
'\n'
' If "__int__()" is not defined then the
built-in function '
'"int()"\n'
' falls back to "__trunc__()".\n'
'\n'
'\n'
'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'
'\n'
'\n'
'Special method lookup\n'
'=====================\n'
'\n'
'For custom classes, implicit invocations of special
methods '
'are only\n'
'guaranteed to work correctly if defined on an
object’s type, '
'not in\n'
'the object’s instance dictionary. That behaviour
is the '
'reason why\n'
'the following code raises an exception:\n'
'\n'
' >>> class C:\n'
' ... pass\n'
' ...\n'
' >>> c = C()\n'
' >>> c.__len__ = lambda: 5\n'
' >>> len(c)\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 1, in
<module>\n'
" TypeError: object of type 'C' has no
len()\n"
'\n'
'The rationale behind this behaviour lies with a
number of '
'special\n'
'methods such as "__hash__()" and
"__repr__()" that are '
'implemented by\n'
'all objects, including type objects. If the implicit
lookup '
'of these\n'
'methods used the conventional lookup process, they
would '
'fail when\n'
'invoked on the type object itself:\n'
'\n'
' >>> 1 .__hash__() == hash(1)\n'
' True\n'
' >>> int.__hash__() == hash(int)\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 1, in
<module>\n'
" TypeError: descriptor '__hash__' of
'int' object needs an "
'argument\n'
'\n'
'Incorrectly attempting to invoke an unbound method
of a '
'class in this\n'
'way is sometimes referred to as ‘metaclass
confusion’, and '
'is avoided\n'
'by bypassing the instance when looking up special
methods:\n'
'\n'
' >>> type(1).__hash__(1) ==
hash(1)\n'
' True\n'
' >>> type(int).__hash__(int) ==
hash(int)\n'
' True\n'
'\n'
'In addition to bypassing any instance attributes in
the '
'interest of\n'
'correctness, implicit special method lookup
generally also '
'bypasses\n'
'the "__getattribute__()" method even of
the object’s '
'metaclass:\n'
'\n'
' >>> class Meta(type):\n'
' ... def __getattribute__(*args):\n'
' ... print("Metaclass getattribute
invoked")\n'
' ... return
type.__getattribute__(*args)\n'
' ...\n'
' >>> class C(object,
metaclass=Meta):\n'
' ... def __len__(self):\n'
' ... return 10\n'
' ... def __getattribute__(*args):\n'
' ... print("Class getattribute
invoked")\n'
' ... return
object.__getattribute__(*args)\n'
' ...\n'
' >>> c = C()\n'
' >>> c.__len__() #
Explicit lookup via '
'instance\n'
' Class getattribute invoked\n'
' 10\n'
' >>> type(c).__len__(c) #
Explicit lookup via '
'type\n'
' Metaclass getattribute invoked\n'
' 10\n'
' >>> len(c) #
Implicit lookup\n'
' 10\n'
'\n'
'Bypassing the "__getattribute__()"
machinery in this fashion '
'provides\n'
'significant scope for speed optimisations within the
'
'interpreter, at\n'
'the cost of some flexibility in the handling of
special '
'methods (the\n'
'special method *must* be set on the class object
itself in '
'order to be\n'
'consistently invoked by the interpreter).\n',
'string-methods': 'String Methods\n'
'**************\n'
'\n'
'Strings implement all of the common sequence
operations, '
'along with\n'
'the additional methods described below.\n'
'\n'
'Strings also support two styles of string
formatting, one '
'providing a\n'
'large degree of flexibility and customization (see
'
'"str.format()",\n'
'Format String Syntax and Custom String Formatting)
and the '
'other based\n'
'on C "printf" style formatting that
handles a narrower '
'range of types\n'
'and is slightly harder to use correctly, but is
often '
'faster for the\n'
'cases it can handle (printf-style String
Formatting).\n'
'\n'
'The Text Processing Services section of the
standard '
'library covers a\n'
'number of other modules that provide various text
related '
'utilities\n'
'(including regular expression support in the
"re" '
'module).\n'
'\n'
'str.capitalize()\n'
'\n'
' Return a copy of the string with its first
character '
'capitalized\n'
' and the rest lowercased.\n'
'\n'
'str.casefold()\n'
'\n'
' Return a casefolded copy of the string.
Casefolded '
'strings may be\n'
' used for caseless matching.\n'
'\n'
' Casefolding is similar to lowercasing but more
'
'aggressive because\n'
' it is intended to remove all case distinctions
in a '
'string. For\n'
' example, the German lowercase letter
"\'ß\'" is '
'equivalent to ""ss"".\n'
' Since it is already lowercase,
"lower()" would do '
'nothing to "\'ß\'";\n'
' "casefold()" converts it to
""ss"".\n'
'\n'
' The casefolding algorithm is described in
section 3.13 '
'of the\n'
' Unicode Standard.\n'
'\n'
' New in version 3.3.\n'
'\n'
'str.center(width[, fillchar])\n'
'\n'
' Return centered in a string of length *width*.
Padding '
'is done\n'
' using the specified *fillchar* (default is an
ASCII '
'space). The\n'
' original string is returned if *width* is less
than or '
'equal to\n'
' "len(s)".\n'
'\n'
'str.count(sub[, start[, end]])\n'
'\n'
' Return the number of non-overlapping
occurrences of '
'substring *sub*\n'
' in the range [*start*, *end*]. Optional
arguments '
'*start* and\n'
' *end* are interpreted as in slice
notation.\n'
'\n'
'str.encode(encoding="utf-8",
errors="strict")\n'
'\n'
' Return an encoded version of the string as a
bytes '
'object. Default\n'
' encoding is "\'utf-8\'".
*errors* may be given to set a '
'different\n'
' error handling scheme. The default for *errors*
is '
'"\'strict\'",\n'
' meaning that encoding errors raise a
"UnicodeError". '
'Other possible\n'
' values are "\'ignore\'",
"\'replace\'", '
'"\'xmlcharrefreplace\'",\n'
' "\'backslashreplace\'" and
any other name registered '
'via\n'
' "codecs.register_error()", see
section Error Handlers. '
'For a list\n'
' of possible encodings, see section Standard
Encodings.\n'
'\n'
' Changed in version 3.1: Support for keyword
arguments '
'added.\n'
'\n'
'str.endswith(suffix[, start[, end]])\n'
'\n'
' Return "True" if the string ends with
the specified '
'*suffix*,\n'
' otherwise return "False". *suffix*
can also be a tuple '
'of suffixes\n'
' to look for. With optional *start*, test
beginning at '
'that\n'
' position. With optional *end*, stop comparing
at that '
'position.\n'
'\n'
'str.expandtabs(tabsize=8)\n'
'\n'
' Return a copy of the string where all tab
characters '
'are replaced\n'
' by one or more spaces, depending on the current
column '
'and the\n'
' given tab size. Tab positions occur every
*tabsize* '
'characters\n'
' (default is 8, giving tab positions at columns
0, 8, 16 '
'and so on).\n'
' To expand the string, the current column is set
to zero '
'and the\n'
' string is examined character by character. If
the '
'character is a\n'
' tab ("\\t"), one or more space
characters are inserted '
'in the result\n'
' until the current column is equal to the next
tab '
'position. (The\n'
' tab character itself is not copied.) If the
character '
'is a newline\n'
' ("\\n") or return ("\\r"),
it is copied and the current '
'column is\n'
' reset to zero. Any other character is copied
unchanged '
'and the\n'
' current column is incremented by one regardless
of how '
'the\n'
' character is represented when printed.\n'
'\n'
" >>>
'01\\t012\\t0123\\t01234'.expandtabs()\n"
" '01 012 0123
01234'\n"
" >>>
'01\\t012\\t0123\\t01234'.expandtabs(4)\n"
" '01 012 0123 01234'\n"
'\n'
'str.find(sub[, start[, end]])\n'
'\n'
' Return the lowest index in the string where
substring '
'*sub* is\n'
' found within the slice
"s[start:end]". Optional '
'arguments *start*\n'
' and *end* are interpreted as in slice notation.
Return '
'"-1" if\n'
' *sub* is not found.\n'
'\n'
' Note: The "find()" method should be
used only if you '
'need to know\n'
' the position of *sub*. To check if *sub* is
a '
'substring or not,\n'
' use the "in" operator:\n'
'\n'
" >>> 'Py' in
'Python'\n"
' True\n'
'\n'
'str.format(*args, **kwargs)\n'
'\n'
' Perform a string formatting operation. The
string on '
'which this\n'
' method is called can contain literal text or
'
'replacement fields\n'
' delimited by braces "{}". Each
replacement field '
'contains either\n'
' the numeric index of a positional argument, or
the name '
'of a\n'
' keyword argument. Returns a copy of the string
where '
'each\n'
' replacement field is replaced with the string
value of '
'the\n'
' corresponding argument.\n'
'\n'
' >>> "The sum of 1 + 2 is
{0}".format(1+2)\n'
" 'The sum of 1 + 2 is 3'\n"
'\n'
' See Format String Syntax for a description of
the '
'various\n'
' formatting options that can be specified in
format '
'strings.\n'
'\n'
' Note: When formatting a number
("int", "float", '
'"complex",\n'
' "decimal.Decimal" and subclasses)
with the "n" type '
'(ex:\n'
' "\'{:n}\'.format(1234)"),
the function temporarily '
'sets the\n'
' "LC_CTYPE" locale to the
"LC_NUMERIC" locale to '
'decode\n'
' "decimal_point" and
"thousands_sep" fields of '
'"localeconv()" if\n'
' they are non-ASCII or longer than 1 byte, and
the '
'"LC_NUMERIC"\n'
' locale is different than the
"LC_CTYPE" locale. This '
'temporary\n'
' change affects other threads.\n'
'\n'
' Changed in version 3.6.5: When formatting a
number with '
'the "n"\n'
' type, the function sets temporarily the
"LC_CTYPE" '
'locale to the\n'
' "LC_NUMERIC" locale in some
cases.\n'
'\n'
'str.format_map(mapping)\n'
'\n'
' Similar to "str.format(**mapping)",
except that '
'"mapping" is used\n'
' directly and not copied to a "dict".
This is useful if '
'for example\n'
' "mapping" is a dict subclass:\n'
'\n'
' >>> class Default(dict):\n'
' ... def __missing__(self, key):\n'
' ... return key\n'
' ...\n'
" >>> '{name} was born in "
"{country}'.format_map(Default(name='Guido'))\n"
" 'Guido was born in country'\n"
'\n'
' New in version 3.2.\n'
'\n'
'str.index(sub[, start[, end]])\n'
'\n'
' Like "find()", but raise
"ValueError" when the '
'substring is not\n'
' found.\n'
'\n'
'str.isalnum()\n'
'\n'
' Return true if all characters in the string are
'
'alphanumeric and\n'
' there is at least one character, false
otherwise. A '
'character "c"\n'
' is alphanumeric if one of the following returns
'
'"True":\n'
' "c.isalpha()",
"c.isdecimal()", "c.isdigit()", or '
'"c.isnumeric()".\n'
'\n'
'str.isalpha()\n'
'\n'
' Return true if all characters in the string are
'
'alphabetic and\n'
' there is at least one character, false
otherwise. '
'Alphabetic\n'
' characters are those characters defined in the
Unicode '
'character\n'
' database as “Letter”, i.e., those with
general category '
'property\n'
' being one of “Lm”, “Lt”, “Lu”,
“Ll”, or “Lo”. Note '
'that this is\n'
' different from the “Alphabetic” property
defined in the '
'Unicode\n'
' Standard.\n'
'\n'
'str.isdecimal()\n'
'\n'
' Return true if all characters in the string are
decimal '
'characters\n'
' and there is at least one character, false
otherwise. '
'Decimal\n'
' characters are those that can be used to form
numbers '
'in base 10,\n'
' e.g. U+0660, ARABIC-INDIC DIGIT ZERO. Formally
a '
'decimal character\n'
' is a character in the Unicode General Category
“Nd”.\n'
'\n'
'str.isdigit()\n'
'\n'
' Return true if all characters in the string are
digits '
'and there is\n'
' at least one character, false otherwise.
Digits '
'include decimal\n'
' characters and digits that need special
handling, such '
'as the\n'
' compatibility superscript digits. This covers
digits '
'which cannot\n'
' be used to form numbers in base 10, like the
Kharosthi '
'numbers.\n'
' Formally, a digit is a character that has the
property '
'value\n'
' Numeric_Type=Digit or
Numeric_Type=Decimal.\n'
'\n'
'str.isidentifier()\n'
'\n'
' Return true if the string is a valid identifier
'
'according to the\n'
' language definition, section Identifiers and
keywords.\n'
'\n'
' Use "keyword.iskeyword()" to test for
reserved '
'identifiers such as\n'
' "def" and "class".\n'
'\n'
'str.islower()\n'
'\n'
' Return true if all cased characters [4] in the
string '
'are lowercase\n'
' and there is at least one cased character,
false '
'otherwise.\n'
'\n'
'str.isnumeric()\n'
'\n'
' Return true if all characters in the string are
numeric '
'characters,\n'
' and there is at least one character, false
otherwise. '
'Numeric\n'
' characters include digit characters, and all
characters '
'that have\n'
' the Unicode numeric value property, e.g.
U+2155, VULGAR '
'FRACTION\n'
' ONE FIFTH. Formally, numeric characters are
those with '
'the\n'
' property value Numeric_Type=Digit,
Numeric_Type=Decimal '
'or\n'
' Numeric_Type=Numeric.\n'
'\n'
'str.isprintable()\n'
'\n'
' Return true if all characters in the string are
'
'printable or the\n'
' string is empty, false otherwise. Nonprintable
'
'characters are\n'
' those characters defined in the Unicode
character '
'database as\n'
' “Other” or “Separator”, excepting the
ASCII space '
'(0x20) which is\n'
' considered printable. (Note that printable
characters '
'in this\n'
' context are those which should not be escaped
when '
'"repr()" is\n'
' invoked on a string. It has no bearing on the
handling '
'of strings\n'
' written to "sys.stdout" or
"sys.stderr".)\n'
'\n'
'str.isspace()\n'
'\n'
' Return true if there are only whitespace
characters in '
'the string\n'
' and there is at least one character, false
otherwise. '
'Whitespace\n'
' characters are those characters defined in the
Unicode '
'character\n'
' database as “Other” or “Separator” and
those with '
'bidirectional\n'
' property being one of “WS”, “B”, or
“S”.\n'
'\n'
'str.istitle()\n'
'\n'
' Return true if the string is a titlecased
string and '
'there is at\n'
' least one character, for example uppercase
characters '
'may only\n'
' follow uncased characters and lowercase
characters only '
'cased ones.\n'
' Return false otherwise.\n'
'\n'
'str.isupper()\n'
'\n'
' Return true if all cased characters [4] in the
string '
'are uppercase\n'
' and there is at least one cased character,
false '
'otherwise.\n'
'\n'
'str.join(iterable)\n'
'\n'
' Return a string which is the concatenation of
the '
'strings in\n'
' *iterable*. A "TypeError" will be
raised if there are '
'any non-\n'
' string values in *iterable*, including
"bytes" '
'objects. The\n'
' separator between elements is the string
providing this '
'method.\n'
'\n'
'str.ljust(width[, fillchar])\n'
'\n'
' Return the string left justified in a string of
length '
'*width*.\n'
' Padding is done using the specified *fillchar*
(default '
'is an ASCII\n'
' space). The original string is returned if
*width* is '
'less than or\n'
' equal to "len(s)".\n'
'\n'
'str.lower()\n'
'\n'
' Return a copy of the string with all the cased
'
'characters [4]\n'
' converted to lowercase.\n'
'\n'
' The lowercasing algorithm used is described in
section '
'3.13 of the\n'
' Unicode Standard.\n'
'\n'
'str.lstrip([chars])\n'
'\n'
' Return a copy of the string with leading
characters '
'removed. The\n'
' *chars* argument is a string specifying the set
of '
'characters to be\n'
' removed. If omitted or "None", the
*chars* argument '
'defaults to\n'
' removing whitespace. The *chars* argument is
not a '
'prefix; rather,\n'
' all combinations of its values are
stripped:\n'
'\n'
" >>> ' spacious
'.lstrip()\n"
" 'spacious '\n"
" >>>
'www.example.com'.lstrip('cmowz.')\n"
" 'example.com'\n"
'\n'
'static str.maketrans(x[, y[, z]])\n'
'\n'
' This static method returns a translation table
usable '
'for\n'
' "str.translate()".\n'
'\n'
' If there is only one argument, it must be a
dictionary '
'mapping\n'
' Unicode ordinals (integers) or characters
(strings of '
'length 1) to\n'
' Unicode ordinals, strings (of arbitrary
lengths) or '
'"None".\n'
' Character keys will then be converted to
ordinals.\n'
'\n'
' If there are two arguments, they must be
strings of '
'equal length,\n'
' and in the resulting dictionary, each character
in x '
'will be mapped\n'
' to the character at the same position in y. If
there '
'is a third\n'
' argument, it must be a string, whose characters
will be '
'mapped to\n'
' "None" in the result.\n'
'\n'
'str.partition(sep)\n'
'\n'
' Split the string at the first occurrence of
*sep*, and '
'return a\n'
' 3-tuple containing the part before the
separator, the '
'separator\n'
' itself, and the part after the separator. If
the '
'separator is not\n'
' found, return a 3-tuple containing the string
itself, '
'followed by\n'
' two empty strings.\n'
'\n'
'str.replace(old, new[, count])\n'
'\n'
' Return a copy of the string with all
occurrences of '
'substring *old*\n'
' replaced by *new*. If the optional argument
*count* is '
'given, only\n'
' the first *count* occurrences are
replaced.\n'
'\n'
'str.rfind(sub[, start[, end]])\n'
'\n'
' Return the highest index in the string where
substring '
'*sub* is\n'
' found, such that *sub* is contained within
'
'"s[start:end]".\n'
' Optional arguments *start* and *end* are
interpreted as '
'in slice\n'
' notation. Return "-1" on
failure.\n'
'\n'
'str.rindex(sub[, start[, end]])\n'
'\n'
' Like "rfind()" but raises
"ValueError" when the '
'substring *sub* is\n'
' not found.\n'
'\n'
'str.rjust(width[, fillchar])\n'
'\n'
' Return the string right justified in a string
of length '
'*width*.\n'
' Padding is done using the specified *fillchar*
(default '
'is an ASCII\n'
' space). The original string is returned if
*width* is '
'less than or\n'
' equal to "len(s)".\n'
'\n'
'str.rpartition(sep)\n'
'\n'
' Split the string at the last occurrence of
*sep*, and '
'return a\n'
' 3-tuple containing the part before the
separator, the '
'separator\n'
' itself, and the part after the separator. If
the '
'separator is not\n'
' found, return a 3-tuple containing two empty
strings, '
'followed by\n'
' the string itself.\n'
'\n'
'str.rsplit(sep=None, maxsplit=-1)\n'
'\n'
' Return a list of the words in the string, using
*sep* '
'as the\n'
' delimiter string. If *maxsplit* is given, at
most '
'*maxsplit* splits\n'
' are done, the *rightmost* ones. If *sep* is
not '
'specified or\n'
' "None", any whitespace string is a
separator. Except '
'for splitting\n'
' from the right, "rsplit()" behaves
like "split()" which '
'is\n'
' described in detail below.\n'
'\n'
'str.rstrip([chars])\n'
'\n'
' Return a copy of the string with trailing
characters '
'removed. The\n'
' *chars* argument is a string specifying the set
of '
'characters to be\n'
' removed. If omitted or "None", the
*chars* argument '
'defaults to\n'
' removing whitespace. The *chars* argument is
not a '
'suffix; rather,\n'
' all combinations of its values are
stripped:\n'
'\n'
" >>> ' spacious
'.rstrip()\n"
" ' spacious'\n"
" >>>
'mississippi'.rstrip('ipz')\n"
" 'mississ'\n"
'\n'
'str.split(sep=None, maxsplit=-1)\n'
'\n'
' Return a list of the words in the string, using
*sep* '
'as the\n'
' delimiter string. If *maxsplit* is given, at
most '
'*maxsplit*\n'
' splits are done (thus, the list will have at
most '
'"maxsplit+1"\n'
' elements). If *maxsplit* is not specified or
"-1", '
'then there is\n'
' no limit on the number of splits (all possible
splits '
'are made).\n'
'\n'
' If *sep* is given, consecutive delimiters are
not '
'grouped together\n'
' and are deemed to delimit empty strings (for
example,\n'
'
"\'1,,2\'.split(\',\')" returns
"[\'1\', \'\', '
'\'2\']"). The *sep*
argument\n'
' may consist of multiple characters (for
example,\n'
'
"\'1<>2<>3\'.split(\'<>\')"
returns "[\'1\', \'2\', '
'\'3\']"). Splitting an\n'
' empty string with a specified separator returns
'
'"[\'\']".\n'
'\n'
' For example:\n'
'\n'
" >>>
'1,2,3'.split(',')\n"
" ['1', '2',
'3']\n"
" >>>
'1,2,3'.split(',', maxsplit=1)\n"
" ['1', '2,3']\n"
" >>>
'1,2,,3,'.split(',')\n"
" ['1', '2', '',
'3', '']\n"
'\n'
' If *sep* is not specified or is
"None", a different '
'splitting\n'
' algorithm is applied: runs of consecutive
whitespace '
'are regarded\n'
' as a single separator, and the result will
contain no '
'empty strings\n'
' at the start or end if the string has leading
or '
'trailing\n'
' whitespace. Consequently, splitting an empty
string or '
'a string\n'
' consisting of just whitespace with a
"None" separator '
'returns "[]".\n'
'\n'
' For example:\n'
'\n'
" >>> '1 2
3'.split()\n"
" ['1', '2',
'3']\n"
" >>> '1 2
3'.split(maxsplit=1)\n"
" ['1', '2 3']\n"
" >>> ' 1 2 3
'.split()\n"
" ['1', '2',
'3']\n"
'\n'
'str.splitlines([keepends])\n'
'\n'
' Return a list of the lines in the string,
breaking at '
'line\n'
' boundaries. Line breaks are not included in
the '
'resulting list\n'
' unless *keepends* is given and true.\n'
'\n'
' This method splits on the following line
boundaries. '
'In\n'
' particular, the boundaries are a superset of
*universal '
'newlines*.\n'
'\n'
' '
'+-------------------------+-------------------------------+\n'
' | Representation | '
'Description |\n'
' '
'+=========================+===============================+\n'
' | "\\n" | Line
'
'Feed |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\r" | Carriage
'
'Return |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\r\\n" |
Carriage Return + Line '
'Feed |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\v" or "\\x0b"
| Line '
'Tabulation |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\f" or "\\x0c"
| Form '
'Feed |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\x1c" | File
'
'Separator |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\x1d" | Group
'
'Separator |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\x1e" | Record
'
'Separator |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\x85" | Next
Line (C1 Control '
'Code) |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\u2028" | Line
'
'Separator |\n'
' '
'+-------------------------+-------------------------------+\n'
' | "\\u2029" |
Paragraph '
'Separator |\n'
' '
'+-------------------------+-------------------------------+\n'
'\n'
' Changed in version 3.2: "\\v" and
"\\f" added to list '
'of line\n'
' boundaries.\n'
'\n'
' For example:\n'
'\n'
" >>> 'ab c\\n\\nde
fg\\rkl\\r\\n'.splitlines()\n"
" ['ab c', '', 'de
fg', 'kl']\n"
" >>> 'ab c\\n\\nde "
"fg\\rkl\\r\\n'.splitlines(keepends=True)\n"
" ['ab c\\n', '\\n',
'de fg\\r', 'kl\\r\\n']\n"
'\n'
' Unlike "split()" when a delimiter
string *sep* is '
'given, this\n'
' method returns an empty list for the empty
string, and '
'a terminal\n'
' line break does not result in an extra
line:\n'
'\n'
' >>>
"".splitlines()\n'
' []\n'
' >>> "One
line\\n".splitlines()\n'
" ['One line']\n"
'\n'
' For comparison,
"split(\'\\n\')" gives:\n'
'\n'
" >>>
''.split('\\n')\n"
" ['']\n"
" >>> 'Two
lines\\n'.split('\\n')\n"
" ['Two lines',
'']\n"
'\n'
'str.startswith(prefix[, start[, end]])\n'
'\n'
' Return "True" if string starts with
the *prefix*, '
'otherwise return\n'
' "False". *prefix* can also be a tuple
of prefixes to '
'look for.\n'
' With optional *start*, test string beginning at
that '
'position.\n'
' With optional *end*, stop comparing string at
that '
'position.\n'
'\n'
'str.strip([chars])\n'
'\n'
' Return a copy of the string with the leading
and '
'trailing\n'
' characters removed. The *chars* argument is a
string '
'specifying the\n'
' set of characters to be removed. If omitted or
"None", '
'the *chars*\n'
' argument defaults to removing whitespace. The
*chars* '
'argument is\n'
' not a prefix or suffix; rather, all
combinations of its '
'values are\n'
' stripped:\n'
'\n'
" >>> ' spacious
'.strip()\n"
" 'spacious'\n"
" >>>
'www.example.com'.strip('cmowz.')\n"
" 'example'\n"
'\n'
' The outermost leading and trailing *chars*
argument '
'values are\n'
' stripped from the string. Characters are
removed from '
'the leading\n'
' end until reaching a string character that is
not '
'contained in the\n'
' set of characters in *chars*. A similar action
takes '
'place on the\n'
' trailing end. For example:\n'
'\n'
" >>> comment_string = '#.......
Section 3.2.1 Issue "
"#32 .......'\n"
" >>> comment_string.strip('.#!
')\n"
" 'Section 3.2.1 Issue #32'\n"
'\n'
'str.swapcase()\n'
'\n'
' Return a copy of the string with uppercase
characters '
'converted to\n'
' lowercase and vice versa. Note that it is not
'
'necessarily true that\n'
' "s.swapcase().swapcase() ==
s".\n'
'\n'
'str.title()\n'
'\n'
' Return a titlecased version of the string where
words '
'start with an\n'
' uppercase character and the remaining
characters are '
'lowercase.\n'
'\n'
' For example:\n'
'\n'
" >>> 'Hello
world'.title()\n"
" 'Hello World'\n"
'\n'
' The algorithm uses a simple
language-independent '
'definition of a\n'
' word as groups of consecutive letters. The
definition '
'works in\n'
' many contexts but it means that apostrophes in
'
'contractions and\n'
' possessives form word boundaries, which may not
be the '
'desired\n'
' result:\n'
'\n'
' >>> "they\'re
bill\'s friends from the UK".title()\n'
' "They\'Re Bill\'S Friends
From The Uk"\n'
'\n'
' A workaround for apostrophes can be constructed
using '
'regular\n'
' expressions:\n'
'\n'
' >>> import re\n'
' >>> def titlecase(s):\n'
' ... return
re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n'
' ... lambda mo: '
'mo.group(0)[0].upper() +\n'
' ... '
'mo.group(0)[1:].lower(),\n'
' ... s)\n'
' ...\n'
' >>> titlecase("they\'re
bill\'s friends.")\n'
' "They\'re Bill\'s
Friends."\n'
'\n'
'str.translate(table)\n'
'\n'
' Return a copy of the string in which each
character has '
'been mapped\n'
' through the given translation table. The table
must be '
'an object\n'
' that implements indexing via
"__getitem__()", typically '
'a *mapping*\n'
' or *sequence*. When indexed by a Unicode
ordinal (an '
'integer), the\n'
' table object can do any of the following:
return a '
'Unicode ordinal\n'
' or a string, to map the character to one or
more other '
'characters;\n'
' return "None", to delete the
character from the return '
'string; or\n'
' raise a "LookupError" exception, to
map the character '
'to itself.\n'
'\n'
' You can use "str.maketrans()" to
create a translation '
'map from\n'
' character-to-character mappings in different
formats.\n'
'\n'
' See also the "codecs" module for a
more flexible '
'approach to custom\n'
' character mappings.\n'
'\n'
'str.upper()\n'
'\n'
' Return a copy of the string with all the cased
'
'characters [4]\n'
' converted to uppercase. Note that '
'"s.upper().isupper()" might be\n'
' "False" if "s" contains
uncased characters or if the '
'Unicode\n'
' category of the resulting character(s) is not
“Lu” '
'(Letter,\n'
' uppercase), but e.g. “Lt” (Letter,
titlecase).\n'
'\n'
' The uppercasing algorithm used is described in
section '
'3.13 of the\n'
' Unicode Standard.\n'
'\n'
'str.zfill(width)\n'
'\n'
' Return a copy of the string left filled with
ASCII '
'"\'0\'" digits to\n'
' make a string of length *width*. A leading sign
prefix\n'
'
("\'+\'"/"\'-\'") is handled by
inserting the padding '
'*after* the sign\n'
' character rather than before. The original
string is '
'returned if\n'
' *width* is less than or equal to
"len(s)".\n'
'\n'
' For example:\n'
'\n'
' >>> "42".zfill(5)\n'
" '00042'\n"
' >>>
"-42".zfill(5)\n'
" '-0042'\n",
'strings': 'String and Bytes literals\n'
'*************************\n'
'\n'
'String literals are described by the following lexical
'
'definitions:\n'
'\n'
' stringliteral ::= [stringprefix](shortstring |
longstring)\n'
' stringprefix ::= "r" | "u" |
"R" | "U" | "f" | "F"\n'
' | "fr" | "Fr" |
"fR" | "FR" | "rf" | "rF" | '
'"Rf" | "RF"\n'
' shortstring ::= "\'"
shortstringitem* "\'" | \'"\' '
'shortstringitem* \'"\'\n'
' longstring ::= "\'\'\'"
longstringitem* "\'\'\'" | '
'\'"""\' longstringitem*
\'"""\'\n'
' shortstringitem ::= shortstringchar |
stringescapeseq\n'
' longstringitem ::= longstringchar |
stringescapeseq\n'
' shortstringchar ::= <any source character except
"\\" or '
'newline or the quote>\n'
' longstringchar ::= <any source character except
"\\">\n'
' stringescapeseq ::= "\\" <any source
character>\n'
'\n'
' bytesliteral ::= bytesprefix(shortbytes |
longbytes)\n'
' bytesprefix ::= "b" | "B" |
"br" | "Br" | "bR" | "BR" | '
'"rb" | "rB" | "Rb" |
"RB"\n'
' shortbytes ::= "\'" shortbytesitem*
"\'" | \'"\' '
'shortbytesitem* \'"\'\n'
' longbytes ::= "\'\'\'"
longbytesitem* "\'\'\'" |
\'"""\' '
'longbytesitem* \'"""\'\n'
' shortbytesitem ::= shortbyteschar |
bytesescapeseq\n'
' longbytesitem ::= longbyteschar |
bytesescapeseq\n'
' shortbyteschar ::= <any ASCII character except
"\\" or newline '
'or the quote>\n'
' longbyteschar ::= <any ASCII character except
"\\">\n'
' bytesescapeseq ::= "\\" <any ASCII
character>\n'
'\n'
'One syntactic restriction not indicated by these
productions is '
'that\n'
'whitespace is not allowed between the
"stringprefix" or '
'"bytesprefix"\n'
'and the rest of the literal. The source character set is
defined '
'by\n'
'the encoding declaration; it is UTF-8 if no encoding
declaration '
'is\n'
'given in the source file; see section Encoding
declarations.\n'
'\n'
'In plain English: Both types of literals can be enclosed
in '
'matching\n'
'single quotes ("\'") or double quotes
("""). They can also be '
'enclosed\n'
'in matching groups of three single or double quotes
(these are\n'
'generally referred to as *triple-quoted strings*). The
'
'backslash\n'
'("\\") character is used to escape characters
that otherwise have '
'a\n'
'special meaning, such as newline, backslash itself, or
the quote\n'
'character.\n'
'\n'
'Bytes literals are always prefixed with
"\'b\'" or "\'B\'"; they '
'produce\n'
'an instance of the "bytes" type instead of the
"str" type. They '
'may\n'
'only contain ASCII characters; bytes with a numeric value
of 128 '
'or\n'
'greater must be expressed with escapes.\n'
'\n'
'Both string and bytes literals may optionally be prefixed
with a\n'
'letter "\'r\'" or
"\'R\'"; such strings are called *raw strings* '
'and treat\n'
'backslashes as literal characters. As a result, in
string '
'literals,\n'
'"\'\\U\'" and
"\'\\u\'" escapes in raw strings are not treated '
'specially.\n'
'Given that Python 2.x’s raw unicode literals behave
differently '
'than\n'
'Python 3.x’s the "\'ur\'" syntax is
not supported.\n'
'\n'
'New in version 3.3: The "\'rb\'"
prefix of raw bytes literals has '
'been\n'
'added as a synonym of
"\'br\'".\n'
'\n'
'New in version 3.3: Support for the unicode legacy
literal\n'
'("u\'value\'") was reintroduced to
simplify the maintenance of '
'dual\n'
'Python 2.x and 3.x codebases. See **PEP 414** for more
'
'information.\n'
'\n'
'A string literal with "\'f\'" or
"\'F\'" in its prefix is a '
'*formatted\n'
'string literal*; see Formatted string literals. The
"\'f\'" may '
'be\n'
'combined with "\'r\'", but not with
"\'b\'" or "\'u\'", therefore
'
'raw\n'
'formatted strings are possible, but formatted bytes
literals are '
'not.\n'
'\n'
'In triple-quoted literals, unescaped newlines and quotes
are '
'allowed\n'
'(and are retained), except that three unescaped quotes in
a row\n'
'terminate the literal. (A “quote” is the character
used to open '
'the\n'
'literal, i.e. either "\'" or
""".)\n'
'\n'
'Unless an "\'r\'" or
"\'R\'" prefix is present, escape sequences '
'in string\n'
'and bytes literals are interpreted according to rules
similar to '
'those\n'
'used by Standard C. The recognized escape sequences
are:\n'
'\n'
'+-------------------+-----------------------------------+---------+\n'
'| Escape Sequence | Meaning |
Notes '
'|\n'
'+===================+===================================+=========+\n'
'| "\\newline" | Backslash and newline
ignored '
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\\\" | Backslash
("\\") '
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\\'" | Single quote
("\'") '
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\"" | Double quote
(""") '
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\a" | ASCII Bell (BEL)
'
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\b" | ASCII Backspace (BS)
'
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\f" | ASCII Formfeed (FF)
'
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\n" | ASCII Linefeed (LF)
'
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\r" | ASCII Carriage Return
(CR) '
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\t" | ASCII Horizontal Tab
(TAB) '
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\v" | ASCII Vertical Tab (VT)
'
'| |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\ooo" | Character with octal
value *ooo* | '
'(1,3) |\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\xhh" | Character with hex value
*hh* | '
'(2,3) |\n'
'+-------------------+-----------------------------------+---------+\n'
'\n'
'Escape sequences only recognized in string literals
are:\n'
'\n'
'+-------------------+-----------------------------------+---------+\n'
'| Escape Sequence | Meaning |
Notes '
'|\n'
'+===================+===================================+=========+\n'
'| "\\N{name}" | Character named *name*
in the | '
'(4) |\n'
'| | Unicode database |
'
'|\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\uxxxx" | Character with 16-bit
hex value | '
'(5) |\n'
'| | *xxxx* |
'
'|\n'
'+-------------------+-----------------------------------+---------+\n'
'| "\\Uxxxxxxxx" | Character with 32-bit
hex value | '
'(6) |\n'
'| | *xxxxxxxx* |
'
'|\n'
'+-------------------+-----------------------------------+---------+\n'
'\n'
'Notes:\n'
'\n'
'1. As in Standard C, up to three octal digits are
accepted.\n'
'\n'
'2. Unlike in Standard C, exactly two hex digits are
required.\n'
'\n'
'3. In a bytes literal, hexadecimal and octal escapes
denote the\n'
' byte with the given value. In a string literal, these
escapes\n'
' denote a Unicode character with the given
value.\n'
'\n'
'4. Changed in version 3.3: Support for name aliases [1]
has been\n'
' added.\n'
'\n'
'5. Exactly four hex digits are required.\n'
'\n'
'6. Any Unicode character can be encoded this way.
Exactly eight\n'
' hex digits are required.\n'
'\n'
'Unlike Standard C, all unrecognized escape sequences are
left in '
'the\n'
'string unchanged, i.e., *the backslash is left in the
result*. '
'(This\n'
'behavior is useful when debugging: if an escape sequence
is '
'mistyped,\n'
'the resulting output is more easily recognized as
broken.) It is '
'also\n'
'important to note that the escape sequences only
recognized in '
'string\n'
'literals fall into the category of unrecognized escapes
for '
'bytes\n'
'literals.\n'
'\n'
' Changed in version 3.6: Unrecognized escape sequences
produce '
'a\n'
' DeprecationWarning. In some future version of Python
they '
'will be\n'
' a SyntaxError.\n'
'\n'
'Even in a raw literal, quotes can be escaped with a
backslash, '
'but the\n'
'backslash remains in the result; for example,
"r"\\""" is a '
'valid\n'
'string literal consisting of two characters: a backslash
and a '
'double\n'
'quote; "r"\\"" is not a valid string
literal (even a raw string '
'cannot\n'
'end in an odd number of backslashes). Specifically, *a
raw '
'literal\n'
'cannot end in a single backslash* (since the backslash
would '
'escape\n'
'the following quote character). Note also that a single
'
'backslash\n'
'followed by a newline is interpreted as those two
characters as '
'part\n'
'of the literal, *not* as a line continuation.\n',
'subscriptions': 'Subscriptions\n'
'*************\n'
'\n'
'A subscription selects an item of a sequence
(string, tuple '
'or list)\n'
'or mapping (dictionary) object:\n'
'\n'
' subscription ::= primary "["
expression_list "]"\n'
'\n'
'The primary must evaluate to an object that
supports '
'subscription\n'
'(lists or dictionaries for example). User-defined
objects '
'can support\n'
'subscription by defining a
"__getitem__()" method.\n'
'\n'
'For built-in objects, there are two types of
objects that '
'support\n'
'subscription:\n'
'\n'
'If the primary is a mapping, the expression list
must '
'evaluate to an\n'
'object whose value is one of the keys of the
mapping, and '
'the\n'
'subscription selects the value in the mapping that
'
'corresponds to that\n'
'key. (The expression list is a tuple except if it
has '
'exactly one\n'
'item.)\n'
'\n'
'If the primary is a sequence, the expression list
must '
'evaluate to an\n'
'integer or a slice (as discussed in the following
'
'section).\n'
'\n'
'The formal syntax makes no special provision for
negative '
'indices in\n'
'sequences; however, built-in sequences all provide
a '
'"__getitem__()"\n'
'method that interprets negative indices by adding
the '
'length of the\n'
'sequence to the index (so that "x[-1]"
selects the last '
'item of "x").\n'
'The resulting value must be a nonnegative integer
less than '
'the number\n'
'of items in the sequence, and the subscription
selects the '
'item whose\n'
'index is that value (counting from zero). Since the
support '
'for\n'
'negative indices and slicing occurs in the
object’s '
'"__getitem__()"\n'
'method, subclasses overriding this method will need
to '
'explicitly add\n'
'that support.\n'
'\n'
'A string’s items are characters. A character is
not a '
'separate data\n'
'type but a string of exactly one
character.\n',
'truth': 'Truth Value Testing\n'
'*******************\n'
'\n'
'Any object can be tested for truth value, for use in an
"if" or\n'
'"while" condition or as operand of the Boolean
operations below.\n'
'\n'
'By default, an object is considered true unless its class
defines\n'
'either a "__bool__()" method that returns
"False" or a "__len__()"\n'
'method that returns zero, when called with the object. [1]
Here '
'are\n'
'most of the built-in objects considered false:\n'
'\n'
'* constants defined to be false: "None" and
"False".\n'
'\n'
'* zero of any numeric type: "0", "0.0",
"0j", "Decimal(0)",\n'
' "Fraction(0, 1)"\n'
'\n'
'* empty sequences and collections:
"\'\'", "()", "[]", "{}",
'
'"set()",\n'
' "range(0)"\n'
'\n'
'Operations and built-in functions that have a Boolean
result '
'always\n'
'return "0" or "False" for false and
"1" or "True" for true, unless\n'
'otherwise stated. (Important exception: the Boolean
operations '
'"or"\n'
'and "and" always return one of their
operands.)\n',
'try': 'The "try" statement\n'
'*******************\n'
'\n'
'The "try" statement specifies exception handlers
and/or cleanup code\n'
'for a group of statements:\n'
'\n'
' try_stmt ::= try1_stmt | try2_stmt\n'
' try1_stmt ::= "try" ":" suite\n'
' ("except" [expression
["as" identifier]] ":" '
'suite)+\n'
' ["else" ":"
suite]\n'
' ["finally" ":"
suite]\n'
' try2_stmt ::= "try" ":" suite\n'
' "finally" ":"
suite\n'
'\n'
'The "except" clause(s) specify one or more
exception handlers. When '
'no\n'
'exception occurs in the "try" clause, no exception
handler is\n'
'executed. When an exception occurs in the "try"
suite, a search for '
'an\n'
'exception handler is started. This search inspects the
except '
'clauses\n'
'in turn until one is found that matches the exception. An
'
'expression-\n'
'less except clause, if present, must be last; it matches
any\n'
'exception. For an except clause with an expression, that
expression\n'
'is evaluated, and the clause matches the exception if the
resulting\n'
'object is “compatible” with the exception. An object is
compatible\n'
'with an exception if it is the class or a base class of the
'
'exception\n'
'object or a tuple containing an item compatible with the
exception.\n'
'\n'
'If no except clause matches the exception, the search for an
'
'exception\n'
'handler continues in the surrounding code and on the
invocation '
'stack.\n'
'[1]\n'
'\n'
'If the evaluation of an expression in the header of an except
clause\n'
'raises an exception, the original search for a handler is
canceled '
'and\n'
'a search starts for the new exception in the surrounding code
and on\n'
'the call stack (it is treated as if the entire
"try" statement '
'raised\n'
'the exception).\n'
'\n'
'When a matching except clause is found, the exception is
assigned to\n'
'the target specified after the "as" keyword in that
except clause, '
'if\n'
'present, and the except clause’s suite is executed. All
except\n'
'clauses must have an executable block. When the end of this
block '
'is\n'
'reached, execution continues normally after the entire try
'
'statement.\n'
'(This means that if two nested handlers exist for the same
'
'exception,\n'
'and the exception occurs in the try clause of the inner
handler, the\n'
'outer handler will not handle the exception.)\n'
'\n'
'When an exception has been assigned using "as
target", it is cleared\n'
'at the end of the except clause. This is as if\n'
'\n'
' except E as N:\n'
' foo\n'
'\n'
'was translated to\n'
'\n'
' except E as N:\n'
' try:\n'
' foo\n'
' finally:\n'
' del N\n'
'\n'
'This means the exception must be assigned to a different name
to be\n'
'able to refer to it after the except clause. Exceptions are
cleared\n'
'because with the traceback attached to them, they form a
reference\n'
'cycle with the stack frame, keeping all locals in that frame
alive\n'
'until the next garbage collection occurs.\n'
'\n'
'Before an except clause’s suite is executed, details about
the\n'
'exception are stored in the "sys" module and can be
accessed via\n'
'"sys.exc_info()". "sys.exc_info()"
returns a 3-tuple consisting of '
'the\n'
'exception class, the exception instance and a traceback
object (see\n'
'section The standard type hierarchy) identifying the point in
the\n'
'program where the exception occurred.
"sys.exc_info()" values are\n'
'restored to their previous values (before the call) when
returning\n'
'from a function that handled an exception.\n'
'\n'
'The optional "else" clause is executed if the
control flow leaves '
'the\n'
'"try" suite, no exception was raised, and no
"return", "continue", '
'or\n'
'"break" statement was executed. Exceptions in the
"else" clause are\n'
'not handled by the preceding "except"
clauses.\n'
'\n'
'If "finally" is present, it specifies a
‘cleanup’ handler. The '
'"try"\n'
'clause is executed, including any "except" and
"else" clauses. If '
'an\n'
'exception occurs in any of the clauses and is not handled,
the\n'
'exception is temporarily saved. The "finally"
clause is executed. '
'If\n'
'there is a saved exception it is re-raised at the end of the
'
'"finally"\n'
'clause. If the "finally" clause raises another
exception, the saved\n'
'exception is set as the context of the new exception. If the
'
'"finally"\n'
'clause executes a "return" or "break"
statement, the saved exception\n'
'is discarded:\n'
'\n'
' >>> def f():\n'
' ... try:\n'
' ... 1/0\n'
' ... finally:\n'
' ... return 42\n'
' ...\n'
' >>> f()\n'
' 42\n'
'\n'
'The exception information is not available to the program
during\n'
'execution of the "finally" clause.\n'
'\n'
'When a "return", "break" or
"continue" statement is executed in the\n'
'"try" suite of a
"try"…"finally" statement, the "finally"
clause is\n'
'also executed ‘on the way out.’ A "continue"
statement is illegal in\n'
'the "finally" clause. (The reason is a problem with
the current\n'
'implementation — this restriction may be lifted in the
future).\n'
'\n'
'The return value of a function is determined by the last
"return"\n'
'statement executed. Since the "finally" clause
always executes, a\n'
'"return" statement executed in the
"finally" clause will always be '
'the\n'
'last one executed:\n'
'\n'
' >>> def foo():\n'
' ... try:\n'
" ... return 'try'\n"
' ... finally:\n'
" ... return 'finally'\n"
' ...\n'
' >>> foo()\n'
" 'finally'\n"
'\n'
'Additional information on exceptions can be found in
section\n'
'Exceptions, and information on using the "raise"
statement to '
'generate\n'
'exceptions may be found in section The raise
statement.\n',
'types': 'The standard type hierarchy\n'
'***************************\n'
'\n'
'Below is a list of the types that are built into Python.
'
'Extension\n'
'modules (written in C, Java, or other languages, depending
on the\n'
'implementation) can define additional types. Future
versions of\n'
'Python may add types to the type hierarchy (e.g., rational
'
'numbers,\n'
'efficiently stored arrays of integers, etc.), although such
'
'additions\n'
'will often be provided via the standard library
instead.\n'
'\n'
'Some of the type descriptions below contain a paragraph
listing\n'
'‘special attributes.’ These are attributes that
provide access to '
'the\n'
'implementation and are not intended for general use. Their
'
'definition\n'
'may change in the future.\n'
'\n'
'None\n'
' This type has a single value. There is a single object
with '
'this\n'
' value. This object is accessed through the built-in name
"None". '
'It\n'
' is used to signify the absence of a value in many
situations, '
'e.g.,\n'
' it is returned from functions that don’t explicitly
return\n'
' anything. Its truth value is false.\n'
'\n'
'NotImplemented\n'
' This type has a single value. There is a single object
with '
'this\n'
' value. This object is accessed through the built-in
name\n'
' "NotImplemented". Numeric methods and rich
comparison methods\n'
' should return this value if they do not implement the
operation '
'for\n'
' the operands provided. (The interpreter will then try
the\n'
' reflected operation, or some other fallback, depending
on the\n'
' operator.) Its truth value is true.\n'
'\n'
' See Implementing the arithmetic operations for more
details.\n'
'\n'
'Ellipsis\n'
' This type has a single value. There is a single object
with '
'this\n'
' value. This object is accessed through the literal
"..." or the\n'
' built-in name "Ellipsis". Its truth value is
true.\n'
'\n'
'"numbers.Number"\n'
' These are created by numeric literals and returned as
results '
'by\n'
' arithmetic operators and arithmetic built-in functions.
'
'Numeric\n'
' objects are immutable; once created their value never
changes.\n'
' Python numbers are of course strongly related to
mathematical\n'
' numbers, but subject to the limitations of numerical
'
'representation\n'
' in computers.\n'
'\n'
' Python distinguishes between integers, floating point
numbers, '
'and\n'
' complex numbers:\n'
'\n'
' "numbers.Integral"\n'
' These represent elements from the mathematical set of
'
'integers\n'
' (positive and negative).\n'
'\n'
' There are two types of integers:\n'
'\n'
' Integers ("int")\n'
'\n'
' These represent numbers in an unlimited range,
subject to\n'
' available (virtual) memory only. For the purpose
of '
'shift\n'
' and mask operations, a binary representation is
assumed, '
'and\n'
' negative numbers are represented in a variant of
2’s\n'
' complement which gives the illusion of an infinite
string '
'of\n'
' sign bits extending to the left.\n'
'\n'
' Booleans ("bool")\n'
' These represent the truth values False and True.
The two\n'
' objects representing the values "False"
and "True" are '
'the\n'
' only Boolean objects. The Boolean type is a
subtype of '
'the\n'
' integer type, and Boolean values behave like the
values 0 '
'and\n'
' 1, respectively, in almost all contexts, the
exception '
'being\n'
' that when converted to a string, the strings
""False"" or\n'
' ""True"" are returned,
respectively.\n'
'\n'
' The rules for integer representation are intended to
give '
'the\n'
' most meaningful interpretation of shift and mask
operations\n'
' involving negative integers.\n'
'\n'
' "numbers.Real" ("float")\n'
' These represent machine-level double precision
floating '
'point\n'
' numbers. You are at the mercy of the underlying
machine\n'
' architecture (and C or Java implementation) for the
accepted\n'
' range and handling of overflow. Python does not
support '
'single-\n'
' precision floating point numbers; the savings in
processor '
'and\n'
' memory usage that are usually the reason for using
these are\n'
' dwarfed by the overhead of using objects in Python,
so there '
'is\n'
' no reason to complicate the language with two kinds
of '
'floating\n'
' point numbers.\n'
'\n'
' "numbers.Complex"
("complex")\n'
' These represent complex numbers as a pair of
machine-level\n'
' double precision floating point numbers. The same
caveats '
'apply\n'
' as for floating point numbers. The real and imaginary
parts '
'of a\n'
' complex number "z" can be retrieved through
the read-only\n'
' attributes "z.real" and
"z.imag".\n'
'\n'
'Sequences\n'
' These represent finite ordered sets indexed by
non-negative\n'
' numbers. The built-in function "len()" returns
the number of '
'items\n'
' of a sequence. When the length of a sequence is *n*, the
index '
'set\n'
' contains the numbers 0, 1, …, *n*-1. Item *i* of
sequence *a* '
'is\n'
' selected by "a[i]".\n'
'\n'
' Sequences also support slicing: "a[i:j]"
selects all items with\n'
' index *k* such that *i* "<=" *k*
"<" *j*. When used as an\n'
' expression, a slice is a sequence of the same type.
This '
'implies\n'
' that the index set is renumbered so that it starts at
0.\n'
'\n'
' Some sequences also support “extended slicing” with
a third '
'“step”\n'
' parameter: "a[i:j:k]" selects all items of *a*
with index *x* '
'where\n'
' "x = i + n*k", *n* ">="
"0" and *i* "<=" *x* "<" *j*.\n'
'\n'
' Sequences are distinguished according to their
mutability:\n'
'\n'
' Immutable sequences\n'
' An object of an immutable sequence type cannot change
once it '
'is\n'
' created. (If the object contains references to other
'
'objects,\n'
' these other objects may be mutable and may be
changed; '
'however,\n'
' the collection of objects directly referenced by an
'
'immutable\n'
' object cannot change.)\n'
'\n'
' The following types are immutable sequences:\n'
'\n'
' Strings\n'
' A string is a sequence of values that represent
Unicode '
'code\n'
' points. All the code points in the range
"U+0000 - '
'U+10FFFF"\n'
' can be represented in a string. Python doesn’t
have a '
'"char"\n'
' type; instead, every code point in the string is
'
'represented\n'
' as a string object with length "1". The
built-in '
'function\n'
' "ord()" converts a code point from its
string form to an\n'
' integer in the range "0 - 10FFFF";
"chr()" converts an\n'
' integer in the range "0 - 10FFFF" to the
corresponding '
'length\n'
' "1" string object.
"str.encode()" can be used to convert '
'a\n'
' "str" to "bytes" using the
given text encoding, and\n'
' "bytes.decode()" can be used to achieve
the opposite.\n'
'\n'
' Tuples\n'
' The items of a tuple are arbitrary Python objects.
Tuples '
'of\n'
' two or more items are formed by comma-separated
lists of\n'
' expressions. A tuple of one item (a
‘singleton’) can be\n'
' formed by affixing a comma to an expression (an
expression '
'by\n'
' itself does not create a tuple, since parentheses
must be\n'
' usable for grouping of expressions). An empty
tuple can '
'be\n'
' formed by an empty pair of parentheses.\n'
'\n'
' Bytes\n'
' A bytes object is an immutable array. The items
are '
'8-bit\n'
' bytes, represented by integers in the range 0
<= x < 256.\n'
' Bytes literals (like
"b\'abc\'") and the built-in '
'"bytes()"\n'
' constructor can be used to create bytes objects.
Also, '
'bytes\n'
' objects can be decoded to strings via the
"decode()" '
'method.\n'
'\n'
' Mutable sequences\n'
' Mutable sequences can be changed after they are
created. '
'The\n'
' subscription and slicing notations can be used as the
target '
'of\n'
' assignment and "del" (delete)
statements.\n'
'\n'
' There are currently two intrinsic mutable sequence
types:\n'
'\n'
' Lists\n'
' The items of a list are arbitrary Python objects.
Lists '
'are\n'
' formed by placing a comma-separated list of
expressions '
'in\n'
' square brackets. (Note that there are no special
cases '
'needed\n'
' to form lists of length 0 or 1.)\n'
'\n'
' Byte Arrays\n'
' A bytearray object is a mutable array. They are
created '
'by\n'
' the built-in "bytearray()" constructor.
Aside from being\n'
' mutable (and hence unhashable), byte arrays
otherwise '
'provide\n'
' the same interface and functionality as immutable
"bytes"\n'
' objects.\n'
'\n'
' The extension module "array" provides an
additional example '
'of a\n'
' mutable sequence type, as does the
"collections" module.\n'
'\n'
'Set types\n'
' These represent unordered, finite sets of unique,
immutable\n'
' objects. As such, they cannot be indexed by any
subscript. '
'However,\n'
' they can be iterated over, and the built-in function
"len()"\n'
' returns the number of items in a set. Common uses for
sets are '
'fast\n'
' membership testing, removing duplicates from a sequence,
and\n'
' computing mathematical operations such as intersection,
union,\n'
' difference, and symmetric difference.\n'
'\n'
' For set elements, the same immutability rules apply as
for\n'
' dictionary keys. Note that numeric types obey the normal
rules '
'for\n'
' numeric comparison: if two numbers compare equal (e.g.,
"1" and\n'
' "1.0"), only one of them can be contained in a
set.\n'
'\n'
' There are currently two intrinsic set types:\n'
'\n'
' Sets\n'
' These represent a mutable set. They are created by
the '
'built-in\n'
' "set()" constructor and can be modified
afterwards by '
'several\n'
' methods, such as "add()".\n'
'\n'
' Frozen sets\n'
' These represent an immutable set. They are created
by the\n'
' built-in "frozenset()" constructor. As a
frozenset is '
'immutable\n'
' and *hashable*, it can be used again as an element of
'
'another\n'
' set, or as a dictionary key.\n'
'\n'
'Mappings\n'
' These represent finite sets of objects indexed by
arbitrary '
'index\n'
' sets. The subscript notation "a[k]" selects
the item indexed by '
'"k"\n'
' from the mapping "a"; this can be used in
expressions and as '
'the\n'
' target of assignments or "del" statements. The
built-in '
'function\n'
' "len()" returns the number of items in a
mapping.\n'
'\n'
' There is currently a single intrinsic mapping
type:\n'
'\n'
' Dictionaries\n'
' These represent finite sets of objects indexed by
nearly\n'
' arbitrary values. The only types of values not
acceptable '
'as\n'
' keys are values containing lists or dictionaries or
other\n'
' mutable types that are compared by value rather than
by '
'object\n'
' identity, the reason being that the efficient
implementation '
'of\n'
' dictionaries requires a key’s hash value to remain
constant.\n'
' Numeric types used for keys obey the normal rules for
'
'numeric\n'
' comparison: if two numbers compare equal (e.g.,
"1" and '
'"1.0")\n'
' then they can be used interchangeably to index the
same\n'
' dictionary entry.\n'
'\n'
' Dictionaries are mutable; they can be created by the
"{...}"\n'
' notation (see section Dictionary displays).\n'
'\n'
' The extension modules "dbm.ndbm" and
"dbm.gnu" provide\n'
' additional examples of mapping types, as does the
'
'"collections"\n'
' module.\n'
'\n'
'Callable types\n'
' These are the types to which the function call operation
(see\n'
' section Calls) can be applied:\n'
'\n'
' User-defined functions\n'
' A user-defined function object is created by a
function\n'
' definition (see section Function definitions). It
should be\n'
' called with an argument list containing the same
number of '
'items\n'
' as the function’s formal parameter list.\n'
'\n'
' Special attributes:\n'
'\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | Attribute | Meaning
'
'| |\n'
' '
'+===========================+=================================+=============+\n'
' | "__doc__" | The
function’s documentation '
'| Writable |\n'
' | | string, or
"None" if '
'| |\n'
' | | unavailable; not
inherited by '
'| |\n'
' | | subclasses
'
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__name__" | The
function’s name '
'| Writable |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__qualname__" | The
function’s *qualified name* '
'| Writable |\n'
' | | New in version 3.3.
'
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__module__" | The name of
the module the '
'| Writable |\n'
' | | function was defined
in, or '
'| |\n'
' | | "None" if
unavailable. '
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__defaults__" | A tuple
containing default '
'| Writable |\n'
' | | argument values for
those '
'| |\n'
' | | arguments that have
defaults, '
'| |\n'
' | | or "None" if
no arguments have '
'| |\n'
' | | a default value
'
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__code__" | The code
object representing '
'| Writable |\n'
' | | the compiled function
body. '
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__globals__" | A reference
to the dictionary '
'| Read-only |\n'
' | | that holds the
function’s '
'| |\n'
' | | global variables —
the global '
'| |\n'
' | | namespace of the module
in '
'| |\n'
' | | which the function was
defined. '
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__dict__" | The namespace
supporting '
'| Writable |\n'
' | | arbitrary function
attributes. '
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__closure__" |
"None" or a tuple of cells that '
'| Read-only |\n'
' | | contain bindings for
the '
'| |\n'
' | | function’s free
variables. '
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__annotations__" | A dict
containing annotations '
'| Writable |\n'
' | | of parameters. The
keys of the '
'| |\n'
' | | dict are the parameter
names, '
'| |\n'
' | | and
"\'return\'" for the '
'return | |\n'
' | | annotation, if
provided. '
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
' | "__kwdefaults__" | A dict
containing defaults for '
'| Writable |\n'
' | | keyword-only
parameters. '
'| |\n'
' '
'+---------------------------+---------------------------------+-------------+\n'
'\n'
' Most of the attributes labelled “Writable” check
the type of '
'the\n'
' assigned value.\n'
'\n'
' Function objects also support getting and setting
arbitrary\n'
' attributes, which can be used, for example, to attach
'
'metadata\n'
' to functions. Regular attribute dot-notation is used
to get '
'and\n'
' set such attributes. *Note that the current
implementation '
'only\n'
' supports function attributes on user-defined
functions. '
'Function\n'
' attributes on built-in functions may be supported in
the\n'
' future.*\n'
'\n'
' Additional information about a function’s
definition can be\n'
' retrieved from its code object; see the description
of '
'internal\n'
' types below.\n'
'\n'
' Instance methods\n'
' An instance method object combines a class, a class
instance '
'and\n'
' any callable object (normally a user-defined
function).\n'
'\n'
' Special read-only attributes: "__self__" is
the class '
'instance\n'
' object, "__func__" is the function object;
"__doc__" is the\n'
' method’s documentation (same as
"__func__.__doc__"); '
'"__name__"\n'
' is the method name (same as
"__func__.__name__"); '
'"__module__"\n'
' is the name of the module the method was defined in,
or '
'"None"\n'
' if unavailable.\n'
'\n'
' Methods also support accessing (but not setting) the
'
'arbitrary\n'
' function attributes on the underlying function
object.\n'
'\n'
' User-defined method objects may be created when
getting an\n'
' attribute of a class (perhaps via an instance of that
class), '
'if\n'
' that attribute is a user-defined function object or a
class\n'
' method object.\n'
'\n'
' When an instance method object is created by
retrieving a '
'user-\n'
' defined function object from a class via one of its
'
'instances,\n'
' its "__self__" attribute is the instance,
and the method '
'object\n'
' is said to be bound. The new method’s
"__func__" attribute '
'is\n'
' the original function object.\n'
'\n'
' When a user-defined method object is created by
retrieving\n'
' another method object from a class or instance, the
behaviour '
'is\n'
' the same as for a function object, except that the
'
'"__func__"\n'
' attribute of the new instance is not the original
method '
'object\n'
' but its "__func__" attribute.\n'
'\n'
' When an instance method object is created by
retrieving a '
'class\n'
' method object from a class or instance, its
"__self__" '
'attribute\n'
' is the class itself, and its "__func__"
attribute is the\n'
' function object underlying the class method.\n'
'\n'
' When an instance method object is called, the
underlying\n'
' function ("__func__") is called, inserting
the class '
'instance\n'
' ("__self__") in front of the argument list.
For instance, '
'when\n'
' "C" is a class which contains a definition
for a function '
'"f()",\n'
' and "x" is an instance of "C",
calling "x.f(1)" is equivalent '
'to\n'
' calling "C.f(x, 1)".\n'
'\n'
' When an instance method object is derived from a
class '
'method\n'
' object, the “class instance” stored in
"__self__" will '
'actually\n'
' be the class itself, so that calling either
"x.f(1)" or '
'"C.f(1)"\n'
' is equivalent to calling "f(C,1)" where
"f" is the '
'underlying\n'
' function.\n'
'\n'
' Note that the transformation from function object to
'
'instance\n'
' method object happens each time the attribute is
retrieved '
'from\n'
' the instance. In some cases, a fruitful optimization
is to\n'
' assign the attribute to a local variable and call
that local\n'
' variable. Also notice that this transformation only
happens '
'for\n'
' user-defined functions; other callable objects (and
all non-\n'
' callable objects) are retrieved without
transformation. It '
'is\n'
' also important to note that user-defined functions
which are\n'
' attributes of a class instance are not converted to
bound\n'
' methods; this *only* happens when the function is an
'
'attribute\n'
' of the class.\n'
'\n'
' Generator functions\n'
' A function or method which uses the "yield"
statement (see\n'
' section The yield statement) is called a *generator
'
'function*.\n'
' Such a function, when called, always returns an
iterator '
'object\n'
' which can be used to execute the body of the
function: '
'calling\n'
' the iterator’s "iterator.__next__()"
method will cause the\n'
' function to execute until it provides a value using
the '
'"yield"\n'
' statement. When the function executes a
"return" statement '
'or\n'
' falls off the end, a "StopIteration"
exception is raised and '
'the\n'
' iterator will have reached the end of the set of
values to '
'be\n'
' returned.\n'
'\n'
' Coroutine functions\n'
' A function or method which is defined using
"async def" is\n'
' called a *coroutine function*. Such a function, when
'
'called,\n'
' returns a *coroutine* object. It may contain
"await"\n'
' expressions, as well as "async with" and
"async for" '
'statements.\n'
' See also the Coroutine Objects section.\n'
'\n'
' Asynchronous generator functions\n'
' A function or method which is defined using
"async def" and\n'
' which uses the "yield" statement is called
a *asynchronous\n'
' generator function*. Such a function, when called,
returns '
'an\n'
' asynchronous iterator object which can be used in an
"async '
'for"\n'
' statement to execute the body of the
function.\n'
'\n'
' Calling the asynchronous iterator’s
"aiterator.__anext__()"\n'
' method will return an *awaitable* which when awaited
will\n'
' execute until it provides a value using the
"yield" '
'expression.\n'
' When the function executes an empty
"return" statement or '
'falls\n'
' off the end, a "StopAsyncIteration"
exception is raised and '
'the\n'
' asynchronous iterator will have reached the end of
the set '
'of\n'
' values to be yielded.\n'
'\n'
' Built-in functions\n'
' A built-in function object is a wrapper around a C
function.\n'
' Examples of built-in functions are "len()"
and "math.sin()"\n'
' ("math" is a standard built-in module). The
number and type '
'of\n'
' the arguments are determined by the C function.
Special '
'read-\n'
' only attributes: "__doc__" is the
function’s documentation\n'
' string, or "None" if unavailable;
"__name__" is the '
'function’s\n'
' name; "__self__" is set to "None"
(but see the next item);\n'
' "__module__" is the name of the module the
function was '
'defined\n'
' in or "None" if unavailable.\n'
'\n'
' Built-in methods\n'
' This is really a different disguise of a built-in
function, '
'this\n'
' time containing an object passed to the C function as
an\n'
' implicit extra argument. An example of a built-in
method is\n'
' "alist.append()", assuming *alist* is a
list object. In this\n'
' case, the special read-only attribute
"__self__" is set to '
'the\n'
' object denoted by *alist*.\n'
'\n'
' Classes\n'
' Classes are callable. These objects normally act as
'
'factories\n'
' for new instances of themselves, but variations are
possible '
'for\n'
' class types that override "__new__()". The
arguments of the\n'
' call are passed to "__new__()" and, in the
typical case, to\n'
' "__init__()" to initialize the new
instance.\n'
'\n'
' Class Instances\n'
' Instances of arbitrary classes can be made callable
by '
'defining\n'
' a "__call__()" method in their
class.\n'
'\n'
'Modules\n'
' Modules are a basic organizational unit of Python code,
and are\n'
' created by the import system as invoked either by the
"import"\n'
' statement (see "import"), or by calling
functions such as\n'
' "importlib.import_module()" and built-in
"__import__()". A '
'module\n'
' object has a namespace implemented by a dictionary
object (this '
'is\n'
' the dictionary referenced by the "__globals__"
attribute of\n'
' functions defined in the module). Attribute references
are\n'
' translated to lookups in this dictionary, e.g.,
"m.x" is '
'equivalent\n'
' to "m.__dict__["x"]". A module
object does not contain the code\n'
' object used to initialize the module (since it isn’t
needed '
'once\n'
' the initialization is done).\n'
'\n'
' Attribute assignment updates the module’s namespace
dictionary,\n'
' e.g., "m.x = 1" is equivalent to
"m.__dict__["x"] = 1".\n'
'\n'
' Predefined (writable) attributes: "__name__"
is the module’s '
'name;\n'
' "__doc__" is the module’s documentation
string, or "None" if\n'
' unavailable; "__annotations__" (optional) is a
dictionary\n'
' containing *variable annotations* collected during
module body\n'
' execution; "__file__" is the pathname of the
file from which '
'the\n'
' module was loaded, if it was loaded from a file. The
"__file__"\n'
' attribute may be missing for certain types of modules,
such as '
'C\n'
' modules that are statically linked into the interpreter;
for\n'
' extension modules loaded dynamically from a shared
library, it '
'is\n'
' the pathname of the shared library file.\n'
'\n'
' Special read-only attribute: "__dict__" is the
module’s '
'namespace\n'
' as a dictionary object.\n'
'\n'
' **CPython implementation detail:** Because of the way
CPython\n'
' clears module dictionaries, the module dictionary will
be '
'cleared\n'
' when the module falls out of scope even if the
dictionary still '
'has\n'
' live references. To avoid this, copy the dictionary or
keep '
'the\n'
' module around while using its dictionary
directly.\n'
'\n'
'Custom classes\n'
' Custom class types are typically created by class
definitions '
'(see\n'
' section Class definitions). A class has a namespace
implemented '
'by\n'
' a dictionary object. Class attribute references are
translated '
'to\n'
' lookups in this dictionary, e.g., "C.x" is
translated to\n'
' "C.__dict__["x"]" (although there
are a number of hooks which '
'allow\n'
' for other means of locating attributes). When the
attribute name '
'is\n'
' not found there, the attribute search continues in the
base\n'
' classes. This search of the base classes uses the C3
method\n'
' resolution order which behaves correctly even in the
presence '
'of\n'
' ‘diamond’ inheritance structures where there are
multiple\n'
' inheritance paths leading back to a common ancestor.
Additional\n'
' details on the C3 MRO used by Python can be found in
the\n'
' documentation accompanying the 2.3 release at\n'
'
https://www.python.org/download/releases/2.3/mro/.\n'
'\n'
' When a class attribute reference (for class
"C", say) would '
'yield a\n'
' class method object, it is transformed into an instance
method\n'
' object whose "__self__" attribute is
"C". When it would yield '
'a\n'
' static method object, it is transformed into the object
wrapped '
'by\n'
' the static method object. See section Implementing
Descriptors '
'for\n'
' another way in which attributes retrieved from a class
may '
'differ\n'
' from those actually contained in its
"__dict__".\n'
'\n'
' Class attribute assignments update the class’s
dictionary, '
'never\n'
' the dictionary of a base class.\n'
'\n'
' A class object can be called (see above) to yield a
class '
'instance\n'
' (see below).\n'
'\n'
' Special attributes: "__name__" is the class
name; "__module__" '
'is\n'
' the module name in which the class was defined;
"__dict__" is '
'the\n'
' dictionary containing the class’s namespace;
"__bases__" is a '
'tuple\n'
' containing the base classes, in the order of their
occurrence '
'in\n'
' the base class list; "__doc__" is the
class’s documentation '
'string,\n'
' or "None" if undefined;
"__annotations__" (optional) is a\n'
' dictionary containing *variable annotations* collected
during '
'class\n'
' body execution.\n'
'\n'
'Class instances\n'
' A class instance is created by calling a class object
(see '
'above).\n'
' A class instance has a namespace implemented as a
dictionary '
'which\n'
' is the first place in which attribute references are
searched.\n'
' When an attribute is not found there, and the
instance’s class '
'has\n'
' an attribute by that name, the search continues with the
class\n'
' attributes. If a class attribute is found that is a
'
'user-defined\n'
' function object, it is transformed into an instance
method '
'object\n'
' whose "__self__" attribute is the instance.
Static method and\n'
' class method objects are also transformed; see above
under\n'
' “Classes”. See section Implementing Descriptors for
another way '
'in\n'
' which attributes of a class retrieved via its instances
may '
'differ\n'
' from the objects actually stored in the class’s
"__dict__". If '
'no\n'
' class attribute is found, and the object’s class has
a\n'
' "__getattr__()" method, that is called to
satisfy the lookup.\n'
'\n'
' Attribute assignments and deletions update the
instance’s\n'
' dictionary, never a class’s dictionary. If the class
has a\n'
' "__setattr__()" or "__delattr__()"
method, this is called '
'instead\n'
' of updating the instance dictionary directly.\n'
'\n'
' Class instances can pretend to be numbers, sequences, or
'
'mappings\n'
' if they have methods with certain special names. See
section\n'
' Special method names.\n'
'\n'
' Special attributes: "__dict__" is the
attribute dictionary;\n'
' "__class__" is the instance’s class.\n'
'\n'
'I/O objects (also known as file objects)\n'
' A *file object* represents an open file. Various
shortcuts are\n'
' available to create file objects: the "open()"
built-in '
'function,\n'
' and also "os.popen()",
"os.fdopen()", and the "makefile()" '
'method\n'
' of socket objects (and perhaps by other functions or
methods\n'
' provided by extension modules).\n'
'\n'
' The objects "sys.stdin",
"sys.stdout" and "sys.stderr" are\n'
' initialized to file objects corresponding to the
interpreter’s\n'
' standard input, output and error streams; they are all
open in '
'text\n'
' mode and therefore follow the interface defined by
the\n'
' "io.TextIOBase" abstract class.\n'
'\n'
'Internal types\n'
' A few types used internally by the interpreter are
exposed to '
'the\n'
' user. Their definitions may change with future versions
of the\n'
' interpreter, but they are mentioned here for
completeness.\n'
'\n'
' Code objects\n'
' Code objects represent *byte-compiled* executable
Python '
'code,\n'
' or *bytecode*. The difference between a code object
and a\n'
' function object is that the function object contains
an '
'explicit\n'
' reference to the function’s globals (the module in
which it '
'was\n'
' defined), while a code object contains no context;
also the\n'
' default argument values are stored in the function
object, '
'not\n'
' in the code object (because they represent values
calculated '
'at\n'
' run-time). Unlike function objects, code objects are
'
'immutable\n'
' and contain no references (directly or indirectly) to
'
'mutable\n'
' objects.\n'
'\n'
' Special read-only attributes: "co_name"
gives the function '
'name;\n'
' "co_argcount" is the number of positional
arguments '
'(including\n'
' arguments with default values);
"co_nlocals" is the number '
'of\n'
' local variables used by the function (including
arguments);\n'
' "co_varnames" is a tuple containing the
names of the local\n'
' variables (starting with the argument names);
"co_cellvars" '
'is a\n'
' tuple containing the names of local variables that
are\n'
' referenced by nested functions;
"co_freevars" is a tuple\n'
' containing the names of free variables;
"co_code" is a '
'string\n'
' representing the sequence of bytecode instructions;
'
'"co_consts"\n'
' is a tuple containing the literals used by the
bytecode;\n'
' "co_names" is a tuple containing the names
used by the '
'bytecode;\n'
' "co_filename" is the filename from which
the code was '
'compiled;\n'
' "co_firstlineno" is the first line number
of the function;\n'
' "co_lnotab" is a string encoding the
mapping from bytecode\n'
' offsets to line numbers (for details see the source
code of '
'the\n'
' interpreter); "co_stacksize" is the
required stack size\n'
' (including local variables); "co_flags" is
an integer '
'encoding a\n'
' number of flags for the interpreter.\n'
'\n'
' The following flag bits are defined for
"co_flags": bit '
'"0x04"\n'
' is set if the function uses the
"*arguments" syntax to accept '
'an\n'
' arbitrary number of positional arguments; bit
"0x08" is set '
'if\n'
' the function uses the "**keywords" syntax
to accept '
'arbitrary\n'
' keyword arguments; bit "0x20" is set if the
function is a\n'
' generator.\n'
'\n'
' Future feature declarations ("from __future__
import '
'division")\n'
' also use bits in "co_flags" to indicate
whether a code '
'object\n'
' was compiled with a particular feature enabled: bit
"0x2000" '
'is\n'
' set if the function was compiled with future division
'
'enabled;\n'
' bits "0x10" and "0x1000" were
used in earlier versions of\n'
' Python.\n'
'\n'
' Other bits in "co_flags" are reserved for
internal use.\n'
'\n'
' If a code object represents a function, the first
item in\n'
' "co_consts" is the documentation string of
the function, or\n'
' "None" if undefined.\n'
'\n'
' Frame objects\n'
' Frame objects represent execution frames. They may
occur in\n'
' traceback objects (see below).\n'
'\n'
' Special read-only attributes: "f_back" is
to the previous '
'stack\n'
' frame (towards the caller), or "None" if
this is the bottom\n'
' stack frame; "f_code" is the code object
being executed in '
'this\n'
' frame; "f_locals" is the dictionary used to
look up local\n'
' variables; "f_globals" is used for global
variables;\n'
' "f_builtins" is used for built-in
(intrinsic) names; '
'"f_lasti"\n'
' gives the precise instruction (this is an index into
the\n'
' bytecode string of the code object).\n'
'\n'
' Special writable attributes: "f_trace", if
not "None", is a\n'
' function called at the start of each source code line
(this '
'is\n'
' used by the debugger); "f_lineno" is the
current line number '
'of\n'
' the frame — writing to this from within a trace
function '
'jumps\n'
' to the given line (only for the bottom-most frame).
A '
'debugger\n'
' can implement a Jump command (aka Set Next Statement)
by '
'writing\n'
' to f_lineno.\n'
'\n'
' Frame objects support one method:\n'
'\n'
' frame.clear()\n'
'\n'
' This method clears all references to local
variables held '
'by\n'
' the frame. Also, if the frame belonged to a
generator, '
'the\n'
' generator is finalized. This helps break
reference '
'cycles\n'
' involving frame objects (for example when catching
an\n'
' exception and storing its traceback for later
use).\n'
'\n'
' "RuntimeError" is raised if the frame is
currently '
'executing.\n'
'\n'
' New in version 3.4.\n'
'\n'
' Traceback objects\n'
' Traceback objects represent a stack trace of an
exception. '
'A\n'
' traceback object is created when an exception occurs.
When '
'the\n'
' search for an exception handler unwinds the execution
stack, '
'at\n'
' each unwound level a traceback object is inserted in
front '
'of\n'
' the current traceback. When an exception handler is
'
'entered,\n'
' the stack trace is made available to the program.
(See '
'section\n'
' The try statement.) It is accessible as the third
item of '
'the\n'
' tuple returned by "sys.exc_info()". When
the program contains '
'no\n'
' suitable handler, the stack trace is written (nicely
'
'formatted)\n'
' to the standard error stream; if the interpreter is
'
'interactive,\n'
' it is also made available to the user as '
'"sys.last_traceback".\n'
'\n'
' Special read-only attributes: "tb_next" is
the next level in '
'the\n'
' stack trace (towards the frame where the exception
occurred), '
'or\n'
' "None" if there is no next level;
"tb_frame" points to the\n'
' execution frame of the current level;
"tb_lineno" gives the '
'line\n'
' number where the exception occurred;
"tb_lasti" indicates '
'the\n'
' precise instruction. The line number and last
instruction '
'in\n'
' the traceback may differ from the line number of its
frame\n'
' object if the exception occurred in a "try"
statement with '
'no\n'
' matching except clause or with a finally
clause.\n'
'\n'
' Slice objects\n'
' Slice objects are used to represent slices for '
'"__getitem__()"\n'
' methods. They are also created by the built-in
"slice()"\n'
' function.\n'
'\n'
' Special read-only attributes: "start" is
the lower bound; '
'"stop"\n'
' is the upper bound; "step" is the step
value; each is "None" '
'if\n'
' omitted. These attributes can have any type.\n'
'\n'
' Slice objects support one method:\n'
'\n'
' slice.indices(self, length)\n'
'\n'
' This method takes a single integer argument
*length* and\n'
' computes information about the slice that the
slice '
'object\n'
' would describe if applied to a sequence of
*length* '
'items.\n'
' It returns a tuple of three integers; respectively
these '
'are\n'
' the *start* and *stop* indices and the *step* or
stride\n'
' length of the slice. Missing or out-of-bounds
indices are\n'
' handled in a manner consistent with regular
slices.\n'
'\n'
' Static method objects\n'
' Static method objects provide a way of defeating
the\n'
' transformation of function objects to method objects
'
'described\n'
' above. A static method object is a wrapper around any
other\n'
' object, usually a user-defined method object. When a
static\n'
' method object is retrieved from a class or a class
instance, '
'the\n'
' object actually returned is the wrapped object, which
is not\n'
' subject to any further transformation. Static method
objects '
'are\n'
' not themselves callable, although the objects they
wrap '
'usually\n'
' are. Static method objects are created by the
built-in\n'
' "staticmethod()" constructor.\n'
'\n'
' Class method objects\n'
' A class method object, like a static method object,
is a '
'wrapper\n'
' around another object that alters the way in which
that '
'object\n'
' is retrieved from classes and class instances. The
behaviour '
'of\n'
' class method objects upon such retrieval is described
above,\n'
' under “User-defined methods”. Class method
objects are '
'created\n'
' by the built-in "classmethod()"
constructor.\n',
'typesfunctions': 'Functions\n'
'*********\n'
'\n'
'Function objects are created by function
definitions. The '
'only\n'
'operation on a function object is to call it:
'
'"func(argument-list)".\n'
'\n'
'There are really two flavors of function objects:
built-in '
'functions\n'
'and user-defined functions. Both support the same
'
'operation (to call\n'
'the function), but the implementation is
different, hence '
'the\n'
'different object types.\n'
'\n'
'See Function definitions for more
information.\n',
'typesmapping': 'Mapping Types — "dict"\n'
'**********************\n'
'\n'
'A *mapping* object maps *hashable* values to
arbitrary '
'objects.\n'
'Mappings are mutable objects. There is currently
only one '
'standard\n'
'mapping type, the *dictionary*. (For other
containers see '
'the built-\n'
'in "list", "set", and
"tuple" classes, and the "collections" '
'module.)\n'
'\n'
'A dictionary’s keys are *almost* arbitrary values.
Values '
'that are\n'
'not *hashable*, that is, values containing lists,
'
'dictionaries or\n'
'other mutable types (that are compared by value
rather than '
'by object\n'
'identity) may not be used as keys. Numeric types
used for '
'keys obey\n'
'the normal rules for numeric comparison: if two
numbers '
'compare equal\n'
'(such as "1" and "1.0") then
they can be used '
'interchangeably to index\n'
'the same dictionary entry. (Note however, that
since '
'computers store\n'
'floating-point numbers as approximations it is
usually '
'unwise to use\n'
'them as dictionary keys.)\n'
'\n'
'Dictionaries can be created by placing a
comma-separated '
'list of "key:\n'
'value" pairs within braces, for example:
"{\'jack\': 4098, '
"'sjoerd':\n"
'4127}" or "{4098: \'jack\',
4127: \'sjoerd\'}", or by the '
'"dict"\n'
'constructor.\n'
'\n'
'class dict(**kwarg)\n'
'class dict(mapping, **kwarg)\n'
'class dict(iterable, **kwarg)\n'
'\n'
' Return a new dictionary initialized from an
optional '
'positional\n'
' argument and a possibly empty set of keyword
arguments.\n'
'\n'
' If no positional argument is given, an empty
dictionary '
'is created.\n'
' If a positional argument is given and it is a
mapping '
'object, a\n'
' dictionary is created with the same key-value
pairs as '
'the mapping\n'
' object. Otherwise, the positional argument must
be an '
'*iterable*\n'
' object. Each item in the iterable must itself be
an '
'iterable with\n'
' exactly two objects. The first object of each
item '
'becomes a key\n'
' in the new dictionary, and the second object the
'
'corresponding\n'
' value. If a key occurs more than once, the last
value '
'for that key\n'
' becomes the corresponding value in the new
dictionary.\n'
'\n'
' If keyword arguments are given, the keyword
arguments and '
'their\n'
' values are added to the dictionary created from
the '
'positional\n'
' argument. If a key being added is already
present, the '
'value from\n'
' the keyword argument replaces the value from the
'
'positional\n'
' argument.\n'
'\n'
' To illustrate, the following examples all return
a '
'dictionary equal\n'
' to "{"one": 1, "two": 2,
"three": 3}":\n'
'\n'
' >>> a = dict(one=1, two=2,
three=3)\n'
" >>> b = {'one': 1,
'two': 2, 'three': 3}\n"
" >>> c = dict(zip(['one',
'two', 'three'], [1, 2, 3]))\n"
" >>> d = dict([('two', 2),
('one', 1), ('three', 3)])\n"
" >>> e = dict({'three': 3,
'one': 1, 'two': 2})\n"
' >>> a == b == c == d == e\n'
' True\n'
'\n'
' Providing keyword arguments as in the first
example only '
'works for\n'
' keys that are valid Python identifiers.
Otherwise, any '
'valid keys\n'
' can be used.\n'
'\n'
' These are the operations that dictionaries
support (and '
'therefore,\n'
' custom mapping types should support too):\n'
'\n'
' len(d)\n'
'\n'
' Return the number of items in the dictionary
*d*.\n'
'\n'
' d[key]\n'
'\n'
' Return the item of *d* with key *key*. Raises
a '
'"KeyError" if\n'
' *key* is not in the map.\n'
'\n'
' If a subclass of dict defines a method
"__missing__()" '
'and *key*\n'
' is not present, the "d[key]"
operation calls that '
'method with\n'
' the key *key* as argument. The
"d[key]" operation '
'then returns\n'
' or raises whatever is returned or raised by
the\n'
' "__missing__(key)" call. No other
operations or '
'methods invoke\n'
' "__missing__()". If
"__missing__()" is not defined, '
'"KeyError"\n'
' is raised. "__missing__()" must be a
method; it cannot '
'be an\n'
' instance variable:\n'
'\n'
' >>> class Counter(dict):\n'
' ... def __missing__(self, key):\n'
' ... return 0\n'
' >>> c = Counter()\n'
" >>> c['red']\n"
' 0\n'
" >>> c['red'] +=
1\n"
" >>> c['red']\n"
' 1\n'
'\n'
' The example above shows part of the
implementation of\n'
' "collections.Counter". A different
"__missing__" '
'method is used\n'
' by
"collections.defaultdict".\n'
'\n'
' d[key] = value\n'
'\n'
' Set "d[key]" to *value*.\n'
'\n'
' del d[key]\n'
'\n'
' Remove "d[key]" from *d*. Raises a
"KeyError" if '
'*key* is not\n'
' in the map.\n'
'\n'
' key in d\n'
'\n'
' Return "True" if *d* has a key
*key*, else "False".\n'
'\n'
' key not in d\n'
'\n'
' Equivalent to "not key in
d".\n'
'\n'
' iter(d)\n'
'\n'
' Return an iterator over the keys of the
dictionary. '
'This is a\n'
' shortcut for
"iter(d.keys())".\n'
'\n'
' clear()\n'
'\n'
' Remove all items from the dictionary.\n'
'\n'
' copy()\n'
'\n'
' Return a shallow copy of the
dictionary.\n'
'\n'
' classmethod fromkeys(seq[, value])\n'
'\n'
' Create a new dictionary with keys from *seq*
and '
'values set to\n'
' *value*.\n'
'\n'
' "fromkeys()" is a class method that
returns a new '
'dictionary.\n'
' *value* defaults to "None".\n'
'\n'
' get(key[, default])\n'
'\n'
' Return the value for *key* if *key* is in the
'
'dictionary, else\n'
' *default*. If *default* is not given, it
defaults to '
'"None", so\n'
' that this method never raises a
"KeyError".\n'
'\n'
' items()\n'
'\n'
' Return a new view of the dictionary’s items
("(key, '
'value)"\n'
' pairs). See the documentation of view
objects.\n'
'\n'
' keys()\n'
'\n'
' Return a new view of the dictionary’s keys.
See the\n'
' documentation of view objects.\n'
'\n'
' pop(key[, default])\n'
'\n'
' If *key* is in the dictionary, remove it and
return '
'its value,\n'
' else return *default*. If *default* is not
given and '
'*key* is\n'
' not in the dictionary, a "KeyError"
is raised.\n'
'\n'
' popitem()\n'
'\n'
' Remove and return an arbitrary "(key,
value)" pair '
'from the\n'
' dictionary.\n'
'\n'
' "popitem()" is useful to
destructively iterate over a\n'
' dictionary, as often used in set algorithms.
If the '
'dictionary\n'
' is empty, calling "popitem()" raises
a "KeyError".\n'
'\n'
' setdefault(key[, default])\n'
'\n'
' If *key* is in the dictionary, return its
value. If '
'not, insert\n'
' *key* with a value of *default* and return
*default*. '
'*default*\n'
' defaults to "None".\n'
'\n'
' update([other])\n'
'\n'
' Update the dictionary with the key/value pairs
from '
'*other*,\n'
' overwriting existing keys. Return
"None".\n'
'\n'
' "update()" accepts either another
dictionary object or '
'an\n'
' iterable of key/value pairs (as tuples or
other '
'iterables of\n'
' length two). If keyword arguments are
specified, the '
'dictionary\n'
' is then updated with those key/value pairs:
'
'"d.update(red=1,\n'
' blue=2)".\n'
'\n'
' values()\n'
'\n'
' Return a new view of the dictionary’s
values. See '
'the\n'
' documentation of view objects.\n'
'\n'
' Dictionaries compare equal if and only if they
have the '
'same "(key,\n'
' value)" pairs. Order comparisons
(‘<’, ‘<=’, ‘>=’, ‘>’) '
'raise\n'
' "TypeError".\n'
'\n'
'See also: "types.MappingProxyType" can be
used to create a '
'read-only\n'
' view of a "dict".\n'
'\n'
'\n'
'Dictionary view objects\n'
'=======================\n'
'\n'
'The objects returned by "dict.keys()",
"dict.values()" and\n'
'"dict.items()" are *view objects*. They
provide a dynamic '
'view on the\n'
'dictionary’s entries, which means that when the
dictionary '
'changes,\n'
'the view reflects these changes.\n'
'\n'
'Dictionary views can be iterated over to yield their
'
'respective data,\n'
'and support membership tests:\n'
'\n'
'len(dictview)\n'
'\n'
' Return the number of entries in the
dictionary.\n'
'\n'
'iter(dictview)\n'
'\n'
' Return an iterator over the keys, values or items
'
'(represented as\n'
' tuples of "(key, value)") in the
dictionary.\n'
'\n'
' Keys and values are iterated over in an arbitrary
order '
'which is\n'
' non-random, varies across Python implementations,
and '
'depends on\n'
' the dictionary’s history of insertions and
deletions. If '
'keys,\n'
' values and items views are iterated over with no
'
'intervening\n'
' modifications to the dictionary, the order of
items will '
'directly\n'
' correspond. This allows the creation of
"(value, key)" '
'pairs using\n'
' "zip()": "pairs = zip(d.values(),
d.keys())". Another '
'way to\n'
' create the same list is "pairs = [(v, k) for
(k, v) in '
'd.items()]".\n'
'\n'
' Iterating views while adding or deleting entries
in the '
'dictionary\n'
' may raise a "RuntimeError" or fail to
iterate over all '
'entries.\n'
'\n'
'x in dictview\n'
'\n'
' Return "True" if *x* is in the
underlying dictionary’s '
'keys, values\n'
' or items (in the latter case, *x* should be a
"(key, '
'value)"\n'
' tuple).\n'
'\n'
'Keys views are set-like since their entries are
unique and '
'hashable.\n'
'If all values are hashable, so that "(key,
value)" pairs are '
'unique\n'
'and hashable, then the items view is also set-like.
(Values '
'views are\n'
'not treated as set-like since the entries are
generally not '
'unique.)\n'
'For set-like views, all of the operations defined
for the '
'abstract\n'
'base class "collections.abc.Set" are
available (for example, '
'"==",\n'
'"<", or "^").\n'
'\n'
'An example of dictionary view usage:\n'
'\n'
" >>> dishes = {'eggs': 2,
'sausage': 1, 'bacon': 1, "
"'spam': 500}\n"
' >>> keys = dishes.keys()\n'
' >>> values = dishes.values()\n'
'\n'
' >>> # iteration\n'
' >>> n = 0\n'
' >>> for val in values:\n'
' ... n += val\n'
' >>> print(n)\n'
' 504\n'
'\n'
' >>> # keys and values are iterated over
in the same '
'order\n'
' >>> list(keys)\n'
" ['eggs', 'bacon',
'sausage', 'spam']\n"
' >>> list(values)\n'
' [2, 1, 1, 500]\n'
'\n'
' >>> # view objects are dynamic and
reflect dict changes\n'
" >>> del dishes['eggs']\n"
" >>> del
dishes['sausage']\n"
' >>> list(keys)\n'
" ['spam', 'bacon']\n"
'\n'
' >>> # set operations\n'
" >>> keys & {'eggs',
'bacon', 'salad'}\n"
" {'bacon'}\n"
" >>> keys ^ {'sausage',
'juice'}\n"
" {'juice', 'sausage',
'bacon', 'spam'}\n",
'typesmethods': 'Methods\n'
'*******\n'
'\n'
'Methods are functions that are called using the
attribute '
'notation.\n'
'There are two flavors: built-in methods (such as
"append()" '
'on lists)\n'
'and class instance methods. Built-in methods are
described '
'with the\n'
'types that support them.\n'
'\n'
'If you access a method (a function defined in a
class '
'namespace)\n'
'through an instance, you get a special object: a
*bound '
'method* (also\n'
'called *instance method*) object. When called, it
will add '
'the "self"\n'
'argument to the argument list. Bound methods have
two '
'special read-\n'
'only attributes: "m.__self__" is the
object on which the '
'method\n'
'operates, and "m.__func__" is the function
implementing the '
'method.\n'
'Calling "m(arg-1, arg-2, ..., arg-n)" is
completely '
'equivalent to\n'
'calling "m.__func__(m.__self__, arg-1, arg-2,
..., arg-n)".\n'
'\n'
'Like function objects, bound method objects support
getting '
'arbitrary\n'
'attributes. However, since method attributes are
actually '
'stored on\n'
'the underlying function object
("meth.__func__"), setting '
'method\n'
'attributes on bound methods is disallowed.
Attempting to '
'set an\n'
'attribute on a method results in an
"AttributeError" being '
'raised. In\n'
'order to set a method attribute, you need to
explicitly set '
'it on the\n'
'underlying function object:\n'
'\n'
' >>> class C:\n'
' ... def method(self):\n'
' ... pass\n'
' ...\n'
' >>> c = C()\n'
" >>> c.method.whoami = 'my name is
method' # can't set on "
'the method\n'
' Traceback (most recent call last):\n'
' File "<stdin>", line 1, in
<module>\n'
" AttributeError: 'method' object has no
attribute "
"'whoami'\n"
" >>> c.method.__func__.whoami = 'my
name is method'\n"
' >>> c.method.whoami\n'
" 'my name is method'\n"
'\n'
'See The standard type hierarchy for more
information.\n',
'typesmodules': 'Modules\n'
'*******\n'
'\n'
'The only special operation on a module is attribute
access: '
'"m.name",\n'
'where *m* is a module and *name* accesses a name
defined in '
'*m*’s\n'
'symbol table. Module attributes can be assigned to.
(Note '
'that the\n'
'"import" statement is not, strictly
speaking, an operation '
'on a module\n'
'object; "import foo" does not require a
module object named '
'*foo* to\n'
'exist, rather it requires an (external) *definition*
for a '
'module\n'
'named *foo* somewhere.)\n'
'\n'
'A special attribute of every module is
"__dict__". This is '
'the\n'
'dictionary containing the module’s symbol table.
Modifying '
'this\n'
'dictionary will actually change the module’s
symbol table, '
'but direct\n'
'assignment to the "__dict__" attribute is
not possible (you '
'can write\n'
'"m.__dict__[\'a\'] = 1", which
defines "m.a" to be "1", but '
'you can’t\n'
'write "m.__dict__ = {}"). Modifying
"__dict__" directly is '
'not\n'
'recommended.\n'
'\n'
'Modules built into the interpreter are written like
this: '
'"<module\n'
'\'sys\' (built-in)>". If loaded
from a file, they are '
'written as\n'
'"<module \'os\' from '
'\'/usr/local/lib/pythonX.Y/os.pyc\'>".\n',
'typesseq': 'Sequence Types — "list",
"tuple", "range"\n'
'*****************************************\n'
'\n'
'There are three basic sequence types: lists, tuples, and
range\n'
'objects. Additional sequence types tailored for
processing of '
'binary\n'
'data and text strings are described in dedicated
sections.\n'
'\n'
'\n'
'Common Sequence Operations\n'
'==========================\n'
'\n'
'The operations in the following table are supported by
most '
'sequence\n'
'types, both mutable and immutable. The '
'"collections.abc.Sequence" ABC\n'
'is provided to make it easier to correctly implement
these '
'operations\n'
'on custom sequence types.\n'
'\n'
'This table lists the sequence operations sorted in
ascending '
'priority.\n'
'In the table, *s* and *t* are sequences of the same
type, *n*, '
'*i*,\n'
'*j* and *k* are integers and *x* is an arbitrary object
that '
'meets any\n'
'type and value restrictions imposed by *s*.\n'
'\n'
'The "in" and "not in" operations
have the same priorities as '
'the\n'
'comparison operations. The "+" (concatenation)
and "*" '
'(repetition)\n'
'operations have the same priority as the corresponding
numeric\n'
'operations. [3]\n'
'\n'
'+----------------------------+----------------------------------+------------+\n'
'| Operation | Result
'
'| Notes |\n'
'+============================+==================================+============+\n'
'| "x in s" |
"True" if an item of *s* is '
'| (1) |\n'
'| | equal to *x*, else
"False" '
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "x not in s" |
"False" if an item of *s* is '
'| (1) |\n'
'| | equal to *x*, else
"True" '
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "s + t" | the
concatenation of *s* and *t* '
'| (6)(7) |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "s * n" or "n * s" |
equivalent to adding *s* to '
'| (2)(7) |\n'
'| | itself *n* times
'
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "s[i]" | *i*th item of
*s*, origin 0 '
'| (3) |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "s[i:j]" | slice of *s*
from *i* to *j* '
'| (3)(4) |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "s[i:j:k]" | slice of *s*
from *i* to *j* '
'| (3)(5) |\n'
'| | with step *k*
'
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "len(s)" | length of *s*
'
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "min(s)" | smallest item
of *s* '
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "max(s)" | largest item of
*s* '
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "s.index(x[, i[, j]])" | index of the
first occurrence of '
'| (8) |\n'
'| | *x* in *s* (at or after
index '
'| |\n'
'| | *i* and before index *j*)
'
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'| "s.count(x)" | total number of
occurrences of '
'| |\n'
'| | *x* in *s*
'
'| |\n'
'+----------------------------+----------------------------------+------------+\n'
'\n'
'Sequences of the same type also support comparisons. In
'
'particular,\n'
'tuples and lists are compared lexicographically by
comparing\n'
'corresponding elements. This means that to compare
equal, every\n'
'element must compare equal and the two sequences must be
of the '
'same\n'
'type and have the same length. (For full details see
'
'Comparisons in\n'
'the language reference.)\n'
'\n'
'Notes:\n'
'\n'
'1. While the "in" and "not in"
operations are used only for '
'simple\n'
' containment testing in the general case, some
specialised '
'sequences\n'
' (such as "str", "bytes" and
"bytearray") also use them for\n'
' subsequence testing:\n'
'\n'
' >>> "gg" in
"eggs"\n'
' True\n'
'\n'
'2. Values of *n* less than "0" are treated as
"0" (which yields '
'an\n'
' empty sequence of the same type as *s*). Note that
items in '
'the\n'
' sequence *s* are not copied; they are referenced
multiple '
'times.\n'
' This often haunts new Python programmers;
consider:\n'
'\n'
' >>> lists = [[]] * 3\n'
' >>> lists\n'
' [[], [], []]\n'
' >>> lists[0].append(3)\n'
' >>> lists\n'
' [[3], [3], [3]]\n'
'\n'
' What has happened is that "[[]]" is a
one-element list '
'containing\n'
' an empty list, so all three elements of "[[]] *
3" are '
'references\n'
' to this single empty list. Modifying any of the
elements of\n'
' "lists" modifies this single list. You can
create a list of\n'
' different lists this way:\n'
'\n'
' >>> lists = [[] for i in
range(3)]\n'
' >>> lists[0].append(3)\n'
' >>> lists[1].append(5)\n'
' >>> lists[2].append(7)\n'
' >>> lists\n'
' [[3], [5], [7]]\n'
'\n'
' Further explanation is available in the FAQ entry How
do I '
'create a\n'
' multidimensional list?.\n'
'\n'
'3. If *i* or *j* is negative, the index is relative to
the end '
'of\n'
' sequence *s*: "len(s) + i" or "len(s)
+ j" is substituted. '
'But\n'
' note that "-0" is still
"0".\n'
'\n'
'4. The slice of *s* from *i* to *j* is defined as the
sequence '
'of\n'
' items with index *k* such that "i <= k <
j". If *i* or *j* '
'is\n'
' greater than "len(s)", use
"len(s)". If *i* is omitted or '
'"None",\n'
' use "0". If *j* is omitted or
"None", use "len(s)". If *i* '
'is\n'
' greater than or equal to *j*, the slice is
empty.\n'
'\n'
'5. The slice of *s* from *i* to *j* with step *k* is
defined as '
'the\n'
' sequence of items with index "x = i + n*k"
such that "0 <= n '
'<\n'
' (j-i)/k". In other words, the indices are
"i", "i+k", '
'"i+2*k",\n'
' "i+3*k" and so on, stopping when *j* is
reached (but never\n'
' including *j*). When *k* is positive, *i* and *j*
are '
'reduced to\n'
' "len(s)" if they are greater. When *k* is
negative, *i* and '
'*j* are\n'
' reduced to "len(s) - 1" if they are
greater. If *i* or *j* '
'are\n'
' omitted or "None", they become “end”
values (which end '
'depends on\n'
' the sign of *k*). Note, *k* cannot be zero. If *k*
is '
'"None", it\n'
' is treated like "1".\n'
'\n'
'6. Concatenating immutable sequences always results in a
new\n'
' object. This means that building up a sequence by
repeated\n'
' concatenation will have a quadratic runtime cost in
the '
'total\n'
' sequence length. To get a linear runtime cost, you
must '
'switch to\n'
' one of the alternatives below:\n'
'\n'
' * if concatenating "str" objects, you can
build a list and '
'use\n'
' "str.join()" at the end or else write to
an "io.StringIO"\n'
' instance and retrieve its value when
complete\n'
'\n'
' * if concatenating "bytes" objects, you can
similarly use\n'
' "bytes.join()" or "io.BytesIO",
or you can do in-place\n'
' concatenation with a "bytearray" object.
"bytearray" '
'objects are\n'
' mutable and have an efficient overallocation
mechanism\n'
'\n'
' * if concatenating "tuple" objects, extend
a "list" instead\n'
'\n'
' * for other types, investigate the relevant class
'
'documentation\n'
'\n'
'7. Some sequence types (such as "range") only
support item\n'
' sequences that follow specific patterns, and hence
don’t '
'support\n'
' sequence concatenation or repetition.\n'
'\n'
'8. "index" raises "ValueError" when
*x* is not found in *s*. '
'Not\n'
' all implementations support passing the additional
arguments '
'*i*\n'
' and *j*. These arguments allow efficient searching of
'
'subsections\n'
' of the sequence. Passing the extra arguments is
roughly '
'equivalent\n'
' to using "s[i:j].index(x)", only without
copying any data and '
'with\n'
' the returned index being relative to the start of the
'
'sequence\n'
' rather than the start of the slice.\n'
'\n'
'\n'
'Immutable Sequence Types\n'
'========================\n'
'\n'
'The only operation that immutable sequence types
generally '
'implement\n'
'that is not also implemented by mutable sequence types
is '
'support for\n'
'the "hash()" built-in.\n'
'\n'
'This support allows immutable sequences, such as
"tuple" '
'instances, to\n'
'be used as "dict" keys and stored in
"set" and "frozenset" '
'instances.\n'
'\n'
'Attempting to hash an immutable sequence that contains
'
'unhashable\n'
'values will result in "TypeError".\n'
'\n'
'\n'
'Mutable Sequence Types\n'
'======================\n'
'\n'
'The operations in the following table are defined on
mutable '
'sequence\n'
'types. The "collections.abc.MutableSequence"
ABC is provided to '
'make\n'
'it easier to correctly implement these operations on
custom '
'sequence\n'
'types.\n'
'\n'
'In the table *s* is an instance of a mutable sequence
type, *t* '
'is any\n'
'iterable object and *x* is an arbitrary object that
meets any '
'type and\n'
'value restrictions imposed by *s* (for example,
"bytearray" '
'only\n'
'accepts integers that meet the value restriction "0
<= x <= '
'255").\n'
'\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| Operation | '
'Result | Notes
|\n'
'+================================+==================================+=======================+\n'
'| "s[i] = x" | item *i* of
*s* is replaced '
'by | |\n'
'| | '
'*x* |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s[i:j] = t" | slice of
*s* from *i* to *j* '
'is | |\n'
'| | replaced by the
contents of '
'the | |\n'
'| | iterable '
'*t* |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "del s[i:j]" | same as
"s[i:j] = '
'[]" | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s[i:j:k] = t" | the
elements of "s[i:j:k]" '
'are | (1) |\n'
'| | replaced by those of
'
'*t* | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "del s[i:j:k]" | removes the
elements '
'of | |\n'
'| | "s[i:j:k]"
from the '
'list | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.append(x)" | appends *x*
to the end of '
'the | |\n'
'| | sequence (same '
'as | |\n'
'| |
"s[len(s):len(s)] = '
'[x]") | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.clear()" | removes all
items from *s* '
'(same | (5) |\n'
'| | as "del '
's[:]") |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.copy()" | creates a
shallow copy of '
'*s* | (5) |\n'
'| | (same as '
'"s[:]") |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.extend(t)" or "s += t" |
extends *s* with the contents '
'of | |\n'
'| | *t* (for the most
part the '
'same | |\n'
'| | as
"s[len(s):len(s)] = '
't") | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s *= n" | updates *s*
with its '
'contents | (6) |\n'
'| | repeated *n* '
'times | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.insert(i, x)" | inserts *x*
into *s* at '
'the | |\n'
'| | index given by *i*
(same '
'as | |\n'
'| | "s[i:i] = '
'[x]") |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.pop([i])" | retrieves
the item at *i* '
'and | (2) |\n'
'| | also removes it from
'
'*s* | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.remove(x)" | remove the
first item from '
'*s* | (3) |\n'
'| | where "s[i] ==
'
'x" | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.reverse()" | reverses
the items of *s* '
'in | (4) |\n'
'| | '
'place |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'\n'
'Notes:\n'
'\n'
'1. *t* must have the same length as the slice it is
replacing.\n'
'\n'
'2. The optional argument *i* defaults to "-1",
so that by '
'default\n'
' the last item is removed and returned.\n'
'\n'
'3. "remove" raises "ValueError" when
*x* is not found in *s*.\n'
'\n'
'4. The "reverse()" method modifies the
sequence in place for\n'
' economy of space when reversing a large sequence. To
remind '
'users\n'
' that it operates by side effect, it does not return
the '
'reversed\n'
' sequence.\n'
'\n'
'5. "clear()" and "copy()" are
included for consistency with the\n'
' interfaces of mutable containers that don’t support
slicing\n'
' operations (such as "dict" and
"set")\n'
'\n'
' New in version 3.3: "clear()" and
"copy()" methods.\n'
'\n'
'6. The value *n* is an integer, or an object
implementing\n'
' "__index__()". Zero and negative values of
*n* clear the '
'sequence.\n'
' Items in the sequence are not copied; they are
referenced '
'multiple\n'
' times, as explained for "s * n" under
Common Sequence '
'Operations.\n'
'\n'
'\n'
'Lists\n'
'=====\n'
'\n'
'Lists are mutable sequences, typically used to store
collections '
'of\n'
'homogeneous items (where the precise degree of
similarity will '
'vary by\n'
'application).\n'
'\n'
'class list([iterable])\n'
'\n'
' Lists may be constructed in several ways:\n'
'\n'
' * Using a pair of square brackets to denote the empty
list: '
'"[]"\n'
'\n'
' * Using square brackets, separating items with
commas: '
'"[a]",\n'
' "[a, b, c]"\n'
'\n'
' * Using a list comprehension: "[x for x in
iterable]"\n'
'\n'
' * Using the type constructor: "list()" or
"list(iterable)"\n'
'\n'
' The constructor builds a list whose items are the
same and in '
'the\n'
' same order as *iterable*’s items. *iterable* may
be either '
'a\n'
' sequence, a container that supports iteration, or an
'
'iterator\n'
' object. If *iterable* is already a list, a copy is
made and\n'
' returned, similar to "iterable[:]". For
example, '
'"list(\'abc\')"\n'
' returns "[\'a\', \'b\',
\'c\']" and "list( (1, 2, 3) )" '
'returns "[1, 2,\n'
' 3]". If no argument is given, the constructor
creates a new '
'empty\n'
' list, "[]".\n'
'\n'
' Many other operations also produce lists, including
the '
'"sorted()"\n'
' built-in.\n'
'\n'
' Lists implement all of the common and mutable
sequence '
'operations.\n'
' Lists also provide the following additional
method:\n'
'\n'
' sort(*, key=None, reverse=False)\n'
'\n'
' This method sorts the list in place, using only
"<" '
'comparisons\n'
' between items. Exceptions are not suppressed - if
any '
'comparison\n'
' operations fail, the entire sort operation will
fail (and '
'the\n'
' list will likely be left in a partially modified
state).\n'
'\n'
' "sort()" accepts two arguments that can
only be passed by\n'
' keyword (keyword-only arguments):\n'
'\n'
' *key* specifies a function of one argument that is
used '
'to\n'
' extract a comparison key from each list element
(for '
'example,\n'
' "key=str.lower"). The key corresponding
to each item in '
'the list\n'
' is calculated once and then used for the entire
sorting '
'process.\n'
' The default value of "None" means that
list items are '
'sorted\n'
' directly without calculating a separate key
value.\n'
'\n'
' The "functools.cmp_to_key()" utility is
available to '
'convert a\n'
' 2.x style *cmp* function to a *key*
function.\n'
'\n'
' *reverse* is a boolean value. If set to
"True", then the '
'list\n'
' elements are sorted as if each comparison were
reversed.\n'
'\n'
' This method modifies the sequence in place for
economy of '
'space\n'
' when sorting a large sequence. To remind users
that it '
'operates\n'
' by side effect, it does not return the sorted
sequence '
'(use\n'
' "sorted()" to explicitly request a new
sorted list '
'instance).\n'
'\n'
' The "sort()" method is guaranteed to be
stable. A sort '
'is\n'
' stable if it guarantees not to change the relative
order '
'of\n'
' elements that compare equal — this is helpful
for sorting '
'in\n'
' multiple passes (for example, sort by department,
then by '
'salary\n'
' grade).\n'
'\n'
' **CPython implementation detail:** While a list is
being '
'sorted,\n'
' the effect of attempting to mutate, or even
inspect, the '
'list is\n'
' undefined. The C implementation of Python makes
the list '
'appear\n'
' empty for the duration, and raises
"ValueError" if it can '
'detect\n'
' that the list has been mutated during a
sort.\n'
'\n'
'\n'
'Tuples\n'
'======\n'
'\n'
'Tuples are immutable sequences, typically used to store
'
'collections of\n'
'heterogeneous data (such as the 2-tuples produced by the
'
'"enumerate()"\n'
'built-in). Tuples are also used for cases where an
immutable '
'sequence\n'
'of homogeneous data is needed (such as allowing storage
in a '
'"set" or\n'
'"dict" instance).\n'
'\n'
'class tuple([iterable])\n'
'\n'
' Tuples may be constructed in a number of
ways:\n'
'\n'
' * Using a pair of parentheses to denote the empty
tuple: '
'"()"\n'
'\n'
' * Using a trailing comma for a singleton tuple:
"a," or '
'"(a,)"\n'
'\n'
' * Separating items with commas: "a, b, c"
or "(a, b, c)"\n'
'\n'
' * Using the "tuple()" built-in:
"tuple()" or '
'"tuple(iterable)"\n'
'\n'
' The constructor builds a tuple whose items are the
same and '
'in the\n'
' same order as *iterable*’s items. *iterable* may
be either '
'a\n'
' sequence, a container that supports iteration, or an
'
'iterator\n'
' object. If *iterable* is already a tuple, it is
returned\n'
' unchanged. For example,
"tuple(\'abc\')" returns "(\'a\', '
'\'b\', \'c\')"\n'
' and "tuple( [1, 2, 3] )" returns "(1,
2, 3)". If no argument '
'is\n'
' given, the constructor creates a new empty tuple,
"()".\n'
'\n'
' Note that it is actually the comma which makes a
tuple, not '
'the\n'
' parentheses. The parentheses are optional, except in
the '
'empty\n'
' tuple case, or when they are needed to avoid
syntactic '
'ambiguity.\n'
' For example, "f(a, b, c)" is a function
call with three '
'arguments,\n'
' while "f((a, b, c))" is a function call
with a 3-tuple as the '
'sole\n'
' argument.\n'
'\n'
' Tuples implement all of the common sequence
operations.\n'
'\n'
'For heterogeneous collections of data where access by
name is '
'clearer\n'
'than access by index,
"collections.namedtuple()" may be a more\n'
'appropriate choice than a simple tuple object.\n'
'\n'
'\n'
'Ranges\n'
'======\n'
'\n'
'The "range" type represents an immutable
sequence of numbers and '
'is\n'
'commonly used for looping a specific number of times in
"for" '
'loops.\n'
'\n'
'class range(stop)\n'
'class range(start, stop[, step])\n'
'\n'
' The arguments to the range constructor must be
integers '
'(either\n'
' built-in "int" or any object that
implements the "__index__"\n'
' special method). If the *step* argument is omitted,
it '
'defaults to\n'
' "1". If the *start* argument is omitted, it
defaults to "0". '
'If\n'
' *step* is zero, "ValueError" is
raised.\n'
'\n'
' For a positive *step*, the contents of a range
"r" are '
'determined\n'
' by the formula "r[i] = start + step*i"
where "i >= 0" and '
'"r[i] <\n'
' stop".\n'
'\n'
' For a negative *step*, the contents of the range are
still\n'
' determined by the formula "r[i] = start +
step*i", but the\n'
' constraints are "i >= 0" and "r[i]
> stop".\n'
'\n'
' A range object will be empty if "r[0]" does
not meet the '
'value\n'
' constraint. Ranges do support negative indices, but
these '
'are\n'
' interpreted as indexing from the end of the sequence
'
'determined by\n'
' the positive indices.\n'
'\n'
' Ranges containing absolute values larger than
"sys.maxsize" '
'are\n'
' permitted but some features (such as
"len()") may raise\n'
' "OverflowError".\n'
'\n'
' Range examples:\n'
'\n'
' >>> list(range(10))\n'
' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n'
' >>> list(range(1, 11))\n'
' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n'
' >>> list(range(0, 30, 5))\n'
' [0, 5, 10, 15, 20, 25]\n'
' >>> list(range(0, 10, 3))\n'
' [0, 3, 6, 9]\n'
' >>> list(range(0, -10, -1))\n'
' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n'
' >>> list(range(0))\n'
' []\n'
' >>> list(range(1, 0))\n'
' []\n'
'\n'
' Ranges implement all of the common sequence
operations '
'except\n'
' concatenation and repetition (due to the fact that
range '
'objects\n'
' can only represent sequences that follow a strict
pattern '
'and\n'
' repetition and concatenation will usually violate
that '
'pattern).\n'
'\n'
' start\n'
'\n'
' The value of the *start* parameter (or
"0" if the '
'parameter was\n'
' not supplied)\n'
'\n'
' stop\n'
'\n'
' The value of the *stop* parameter\n'
'\n'
' step\n'
'\n'
' The value of the *step* parameter (or
"1" if the parameter '
'was\n'
' not supplied)\n'
'\n'
'The advantage of the "range" type over a
regular "list" or '
'"tuple" is\n'
'that a "range" object will always take the
same (small) amount '
'of\n'
'memory, no matter the size of the range it represents
(as it '
'only\n'
'stores the "start", "stop" and
"step" values, calculating '
'individual\n'
'items and subranges as needed).\n'
'\n'
'Range objects implement the
"collections.abc.Sequence" ABC, and\n'
'provide features such as containment tests, element
index '
'lookup,\n'
'slicing and support for negative indices (see Sequence
Types — '
'list,\n'
'tuple, range):\n'
'\n'
'>>> r = range(0, 20, 2)\n'
'>>> r\n'
'range(0, 20, 2)\n'
'>>> 11 in r\n'
'False\n'
'>>> 10 in r\n'
'True\n'
'>>> r.index(10)\n'
'5\n'
'>>> r[5]\n'
'10\n'
'>>> r[:5]\n'
'range(0, 10, 2)\n'
'>>> r[-1]\n'
'18\n'
'\n'
'Testing range objects for equality with "=="
and "!=" compares '
'them as\n'
'sequences. That is, two range objects are considered
equal if '
'they\n'
'represent the same sequence of values. (Note that two
range '
'objects\n'
'that compare equal might have different
"start", "stop" and '
'"step"\n'
'attributes, for example "range(0) == range(2, 1,
3)" or '
'"range(0, 3,\n'
'2) == range(0, 4, 2)".)\n'
'\n'
'Changed in version 3.2: Implement the Sequence ABC.
Support '
'slicing\n'
'and negative indices. Test "int" objects for
membership in '
'constant\n'
'time instead of iterating through all items.\n'
'\n'
'Changed in version 3.3: Define ‘==’ and ‘!=’ to
compare range '
'objects\n'
'based on the sequence of values they define (instead of
'
'comparing\n'
'based on object identity).\n'
'\n'
'New in version 3.3: The "start",
"stop" and "step" attributes.\n'
'\n'
'See also:\n'
'\n'
' * The linspace recipe shows how to implement a lazy
version '
'of\n'
' range suitable for floating point
applications.\n',
'typesseq-mutable': 'Mutable Sequence Types\n'
'**********************\n'
'\n'
'The operations in the following table are
defined on '
'mutable sequence\n'
'types. The
"collections.abc.MutableSequence" ABC is '
'provided to make\n'
'it easier to correctly implement these
operations on '
'custom sequence\n'
'types.\n'
'\n'
'In the table *s* is an instance of a mutable
sequence '
'type, *t* is any\n'
'iterable object and *x* is an arbitrary object
that '
'meets any type and\n'
'value restrictions imposed by *s* (for example,
'
'"bytearray" only\n'
'accepts integers that meet the value restriction
"0 <= x '
'<= 255").\n'
'\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| Operation | '
'Result | Notes
'
'|\n'
'+================================+==================================+=======================+\n'
'| "s[i] = x" |
item *i* of *s* is '
'replaced by | |\n'
'| | '
'*x* |
'
'|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s[i:j] = t" |
slice of *s* from *i* '
'to *j* is | |\n'
'| | replaced by
the '
'contents of the |
|\n'
'| | iterable
'
'*t* |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "del s[i:j]" |
same as "s[i:j] = '
'[]" |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s[i:j:k] = t" | the
elements of '
'"s[i:j:k]" are | (1)
|\n'
'| | replaced by
those of '
'*t* | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "del s[i:j:k]" |
removes the elements '
'of | |\n'
'| |
"s[i:j:k]" from the '
'list | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.append(x)" |
appends *x* to the '
'end of the | |\n'
'| | sequence
(same '
'as |
|\n'
'| |
"s[len(s):len(s)] = '
'[x]") |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.clear()" |
removes all items '
'from *s* (same | (5) |\n'
'| | as "del
'
's[:]") |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.copy()" |
creates a shallow '
'copy of *s* | (5) |\n'
'| | (same as
'
'"s[:]") |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.extend(t)" or "s += t"
| extends *s* with the '
'contents of | |\n'
'| | *t* (for the
most '
'part the same | |\n'
'| | as
"s[len(s):len(s)] '
'= t") |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s *= n" |
updates *s* with its '
'contents | (6) |\n'
'| | repeated *n*
'
'times |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.insert(i, x)" |
inserts *x* into *s* '
'at the | |\n'
'| | index given
by *i* '
'(same as | |\n'
'| | "s[i:i]
= '
'[x]") |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.pop([i])" |
retrieves the item at '
'*i* and | (2) |\n'
'| | also removes
it from '
'*s* | |\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.remove(x)" |
remove the first item '
'from *s* | (3) |\n'
'| | where
"s[i] == '
'x" |
|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'| "s.reverse()" |
reverses the items of '
'*s* in | (4) |\n'
'| | '
'place |
'
'|\n'
'+--------------------------------+----------------------------------+-----------------------+\n'
'\n'
'Notes:\n'
'\n'
'1. *t* must have the same length as the slice it
is '
'replacing.\n'
'\n'
'2. The optional argument *i* defaults to
"-1", so that '
'by default\n'
' the last item is removed and
returned.\n'
'\n'
'3. "remove" raises
"ValueError" when *x* is not found in '
'*s*.\n'
'\n'
'4. The "reverse()" method modifies the
sequence in place '
'for\n'
' economy of space when reversing a large
sequence. To '
'remind users\n'
' that it operates by side effect, it does not
return '
'the reversed\n'
' sequence.\n'
'\n'
'5. "clear()" and "copy()"
are included for consistency '
'with the\n'
' interfaces of mutable containers that don’t
support '
'slicing\n'
' operations (such as "dict" and
"set")\n'
'\n'
' New in version 3.3: "clear()" and
"copy()" methods.\n'
'\n'
'6. The value *n* is an integer, or an object
'
'implementing\n'
' "__index__()". Zero and negative
values of *n* clear '
'the sequence.\n'
' Items in the sequence are not copied; they
are '
'referenced multiple\n'
' times, as explained for "s * n"
under Common Sequence '
'Operations.\n',
'unary': 'Unary arithmetic and bitwise operations\n'
'***************************************\n'
'\n'
'All unary arithmetic and bitwise operations have the same
'
'priority:\n'
'\n'
' u_expr ::= power | "-" u_expr | "+"
u_expr | "~" u_expr\n'
'\n'
'The unary "-" (minus) operator yields the
negation of its numeric\n'
'argument.\n'
'\n'
'The unary "+" (plus) operator yields its numeric
argument '
'unchanged.\n'
'\n'
'The unary "~" (invert) operator yields the
bitwise inversion of '
'its\n'
'integer argument. The bitwise inversion of "x"
is defined as\n'
'"-(x+1)". It only applies to integral
numbers.\n'
'\n'
'In all three cases, if the argument does not have the
proper type, '
'a\n'
'"TypeError" exception is raised.\n',
'while': 'The "while" statement\n'
'*********************\n'
'\n'
'The "while" statement is used for repeated
execution as long as an\n'
'expression is true:\n'
'\n'
' while_stmt ::= "while" expression
":" suite\n'
' ["else" ":"
suite]\n'
'\n'
'This repeatedly tests the expression and, if it is true,
executes '
'the\n'
'first suite; if the expression is false (which may be the
first '
'time\n'
'it is tested) the suite of the "else" clause, if
present, is '
'executed\n'
'and the loop 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
goes '
'back\n'
'to testing the expression.\n',
'with': 'The "with" statement\n'
'********************\n'
'\n'
'The "with" statement is used to wrap the execution
of a block with\n'
'methods defined by a context manager (see section With
Statement\n'
'Context Managers). This allows common
"try"…"except"…"finally" '
'usage\n'
'patterns to be encapsulated for convenient reuse.\n'
'\n'
' with_stmt ::= "with" with_item (","
with_item)* ":" suite\n'
' with_item ::= expression ["as" target]\n'
'\n'
'The execution of the "with" statement with one
“item” proceeds as\n'
'follows:\n'
'\n'
'1. The context expression (the expression given in the
"with_item")\n'
' is evaluated to obtain a context manager.\n'
'\n'
'2. The context manager’s "__exit__()" is loaded
for later use.\n'
'\n'
'3. The context manager’s "__enter__()" method is
invoked.\n'
'\n'
'4. If a target was included in the "with"
statement, the return\n'
' value from "__enter__()" is assigned to
it.\n'
'\n'
' Note: The "with" statement guarantees that if
the "__enter__()"\n'
' method returns without an error, then
"__exit__()" will always '
'be\n'
' called. Thus, if an error occurs during the assignment
to the\n'
' target list, it will be treated the same as an error
occurring\n'
' within the suite would be. See step 6 below.\n'
'\n'
'5. The suite is executed.\n'
'\n'
'6. The context manager’s "__exit__()" method is
invoked. If an\n'
' exception caused the suite to be exited, its type, value,
and\n'
' traceback are passed as arguments to
"__exit__()". Otherwise, '
'three\n'
' "None" arguments are supplied.\n'
'\n'
' If the suite was exited due to an exception, and the
return '
'value\n'
' from the "__exit__()" method was false, the
exception is '
'reraised.\n'
' If the return value was true, the exception is
suppressed, and\n'
' execution continues with the statement following the
"with"\n'
' statement.\n'
'\n'
' If the suite was exited for any reason other than an
exception, '
'the\n'
' return value from "__exit__()" is ignored, and
execution '
'proceeds\n'
' at the normal location for the kind of exit that was
taken.\n'
'\n'
'With more than one item, the context managers are processed
as if\n'
'multiple "with" statements were nested:\n'
'\n'
' with A() as a, B() as b:\n'
' suite\n'
'\n'
'is equivalent to\n'
'\n'
' with A() as a:\n'
' with B() as b:\n'
' suite\n'
'\n'
'Changed in version 3.1: Support for multiple context
expressions.\n'
'\n'
'See also:\n'
'\n'
' **PEP 343** - The “with” statement\n'
' The specification, background, and examples for the
Python '
'"with"\n'
' statement.\n',
'yield': 'The "yield" statement\n'
'*********************\n'
'\n'
' yield_stmt ::= yield_expression\n'
'\n'
'A "yield" statement is semantically equivalent to
a yield '
'expression.\n'
'The yield statement can be used to omit the parentheses
that would\n'
'otherwise be required in the equivalent yield expression
'
'statement.\n'
'For example, the yield statements\n'
'\n'
' yield <expr>\n'
' yield from <expr>\n'
'\n'
'are equivalent to the yield expression statements\n'
'\n'
' (yield <expr>)\n'
' (yield from <expr>)\n'
'\n'
'Yield expressions and statements are only used when
defining a\n'
'*generator* function, and are only used in the body of the
'
'generator\n'
'function. Using yield in a function definition is
sufficient to '
'cause\n'
'that definition to create a generator function instead of a
normal\n'
'function.\n'
'\n'
'For full details of "yield" semantics, refer to
the Yield '
'expressions\n'
'section.\n'}