-# Autogenerated by Sphinx on Tue Feb 11 19:16:18 2025
+# -*- coding: utf-8 -*-
+# Autogenerated by Sphinx on Fri Mar 14 15:39:06 2025
# as part of the release process.
-
-topics = {
- 'assert': r'''The "assert" statement
-**********************
-
-Assert statements are a convenient way to insert debugging assertions
-into a program:
-
- **assert_stmt**: "assert" "expression" ["," "expression"]
-
-The simple form, "assert expression", is equivalent to
-
- if __debug__:
- if not expression: raise AssertionError
-
-The extended form, "assert expression1, expression2", is equivalent to
-
- if __debug__:
- if not expression1: raise AssertionError(expression2)
-
-These equivalences assume that "__debug__" and "AssertionError" refer
-to the built-in variables with those names. In the current
-implementation, the built-in variable "__debug__" is "True" under
-normal circumstances, "False" when optimization is requested (command
-line option "-O"). The current code generator emits no code for an
-"assert" statement when optimization is requested at compile time.
-Note that it is unnecessary to include the source code for the
-expression that failed in the error message; it will be displayed as
-part of the stack trace.
-
-Assignments to "__debug__" are illegal. The value for the built-in
-variable is determined when the interpreter starts.
-''',
- 'assignment': r'''Assignment statements
-*********************
-
-Assignment statements are used to (re)bind names to values and to
-modify attributes or items of mutable objects:
-
- **assignment_stmt**: ("target_list" "=")+ ("starred_expression" | "yield_expression")
- **target_list**: "target" ("," "target")* [","]
- **target**: "identifier"
- | "(" ["target_list"] ")"
- | "[" ["target_list"] "]"
- | "attributeref"
- | "subscription"
- | "slicing"
- | "*" "target"
-
-(See section Primaries for the syntax definitions for *attributeref*,
-*subscription*, and *slicing*.)
-
-An assignment statement evaluates the expression list (remember that
-this can be a single expression or a comma-separated list, the latter
-yielding a tuple) and assigns the single resulting object to each of
-the target lists, from left to right.
-
-Assignment is defined recursively depending on the form of the target
-(list). When a target is part of a mutable object (an attribute
-reference, subscription or slicing), the mutable object must
-ultimately perform the assignment and decide about its validity, and
-may raise an exception if the assignment is unacceptable. The rules
-observed by various types and the exceptions raised are given with the
-definition of the object types (see section The standard type
-hierarchy).
-
-Assignment of an object to a target list, optionally enclosed in
-parentheses or square brackets, is recursively defined as follows.
-
-* If the target list is a single target with no trailing comma,
- optionally in parentheses, the object is assigned to that target.
-
-* Else:
-
- * If the target list contains one target prefixed with an asterisk,
- called a “starred” target: The object must be an iterable with at
- least as many items as there are targets in the target list, minus
- one. The first items of the iterable are assigned, from left to
- right, to the targets before the starred target. The final items
- of the iterable are assigned to the targets after the starred
- target. A list of the remaining items in the iterable is then
- assigned to the starred target (the list can be empty).
-
- * Else: The object must be an iterable with the same number of items
- as there are targets in the target list, and the items are
- assigned, from left to right, to the corresponding targets.
-
-Assignment of an object to a single target is recursively defined as
-follows.
-
-* If the target is an identifier (name):
-
- * If the name does not occur in a "global" or "nonlocal" statement
- in the current code block: the name is bound to the object in the
- current local namespace.
-
- * Otherwise: the name is bound to the object in the global namespace
- or the outer namespace determined by "nonlocal", respectively.
-
- The name is rebound if it was already bound. This may cause the
- reference count for the object previously bound to the name to reach
- zero, causing the object to be deallocated and its destructor (if it
- has one) to be called.
-
-* If the target is an attribute reference: The primary expression in
- the reference is evaluated. It should yield an object with
- assignable attributes; if this is not the case, "TypeError" is
- raised. That object is then asked to assign the assigned object to
- the given attribute; if it cannot perform the assignment, it raises
- an exception (usually but not necessarily "AttributeError").
-
- Note: If the object is a class instance and the attribute reference
- occurs on both sides of the assignment operator, the right-hand side
- expression, "a.x" can access either an instance attribute or (if no
- instance attribute exists) a class attribute. The left-hand side
- target "a.x" is always set as an instance attribute, creating it if
- necessary. Thus, the two occurrences of "a.x" do not necessarily
- refer to the same attribute: if the right-hand side expression
- refers to a class attribute, the left-hand side creates a new
- instance attribute as the target of the assignment:
-
- class Cls:
- x = 3 # class variable
- inst = Cls()
- inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x as 3
-
- This description does not necessarily apply to descriptor
- attributes, such as properties created with "property()".
-
-* If the target is a subscription: The primary expression in the
- reference is evaluated. It should yield either a mutable sequence
- object (such as a list) or a mapping object (such as a dictionary).
- Next, the subscript expression is evaluated.
-
- If the primary is a mutable sequence object (such as a list), the
- subscript must yield an integer. If it is negative, the sequence’s
- length is added to it. The resulting value must be a nonnegative
- integer less than the sequence’s length, and the sequence is asked
- to assign the assigned object to its item with that index. If the
- index is out of range, "IndexError" is raised (assignment to a
- subscripted sequence cannot add new items to a list).
-
- If the primary is a mapping object (such as a dictionary), the
- subscript must have a type compatible with the mapping’s key type,
- and the mapping is then asked to create a key/value pair which maps
- the subscript to the assigned object. This can either replace an
- existing key/value pair with the same key value, or insert a new
- key/value pair (if no key with the same value existed).
-
- For user-defined objects, the "__setitem__()" method is called with
- appropriate arguments.
-
-* If the target is a slicing: The primary expression in the reference
- is evaluated. It should yield a mutable sequence object (such as a
- list). The assigned object should be a sequence object of the same
- type. Next, the lower and upper bound expressions are evaluated,
- insofar they are present; defaults are zero and the sequence’s
- length. The bounds should evaluate to integers. If either bound is
- negative, the sequence’s length is added to it. The resulting
- bounds are clipped to lie between zero and the sequence’s length,
- inclusive. Finally, the sequence object is asked to replace the
- slice with the items of the assigned sequence. The length of the
- slice may be different from the length of the assigned sequence,
- thus changing the length of the target sequence, if the target
- sequence allows it.
-
-**CPython implementation detail:** In the current implementation, the
-syntax for targets is taken to be the same as for expressions, and
-invalid syntax is rejected during the code generation phase, causing
-less detailed error messages.
-
-Although the definition of assignment implies that overlaps between
-the left-hand side and the right-hand side are ‘simultaneous’ (for
-example "a, b = b, a" swaps two variables), overlaps *within* the
-collection of assigned-to variables occur left-to-right, sometimes
-resulting in confusion. For instance, the following program prints
-"[0, 2]":
-
- x = [0, 1]
- i = 0
- i, x[i] = 1, 2 # i is updated, then x[i] is updated
- print(x)
-
-See also:
-
- **PEP 3132** - Extended Iterable Unpacking
- The specification for the "*target" feature.
-
-
-Augmented assignment statements
-===============================
-
-Augmented assignment is the combination, in a single statement, of a
-binary operation and an assignment statement:
-
- **augmented_assignment_stmt**: "augtarget" "augop" ("expression_list" | "yield_expression")
- **augtarget**: "identifier" | "attributeref" | "subscription" | "slicing"
- **augop**: "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
- | ">>=" | "<<=" | "&=" | "^=" | "|="
-
-(See section Primaries for the syntax definitions of the last three
-symbols.)
-
-An augmented assignment evaluates the target (which, unlike normal
-assignment statements, cannot be an unpacking) and the expression
-list, performs the binary operation specific to the type of assignment
-on the two operands, and assigns the result to the original target.
-The target is only evaluated once.
-
-An augmented assignment statement like "x += 1" can be rewritten as "x
-= x + 1" to achieve a similar, but not exactly equal effect. In the
-augmented version, "x" is only evaluated once. Also, when possible,
-the actual operation is performed *in-place*, meaning that rather than
-creating a new object and assigning that to the target, the old object
-is modified instead.
-
-Unlike normal assignments, augmented assignments evaluate the left-
-hand side *before* evaluating the right-hand side. For example, "a[i]
-+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and performs
-the addition, and lastly, it writes the result back to "a[i]".
-
-With the exception of assigning to tuples and multiple targets in a
-single statement, the assignment done by augmented assignment
-statements is handled the same way as normal assignments. Similarly,
-with the exception of the possible *in-place* behavior, the binary
-operation performed by augmented assignment is the same as the normal
-binary operations.
-
-For targets which are attribute references, the same caveat about
-class and instance attributes applies as for regular assignments.
-
-
-Annotated assignment statements
-===============================
-
-*Annotation* assignment is the combination, in a single statement, of
-a variable or attribute annotation and an optional assignment
-statement:
-
- **annotated_assignment_stmt**: "augtarget" ":" "expression"
- ["=" ("starred_expression" | "yield_expression")]
-
-The difference from normal Assignment statements is that only a single
-target is allowed.
-
-The assignment target is considered “simple” if it consists of a
-single name that is not enclosed in parentheses. For simple assignment
-targets, if in class or module scope, the annotations are gathered in
-a lazily evaluated annotation scope. The annotations can be evaluated
-using the "__annotations__" attribute of a class or module, or using
-the facilities in the "annotationlib" module.
-
-If the assignment target is not simple (an attribute, subscript node,
-or parenthesized name), the annotation is never evaluated.
-
-If a name is annotated in a function scope, then this name is local
-for that scope. Annotations are never evaluated and stored in function
-scopes.
-
-If the right hand side is present, an annotated assignment performs
-the actual assignment as if there was no annotation present. If the
-right hand side is not present for an expression target, then the
-interpreter evaluates the target except for the last "__setitem__()"
-or "__setattr__()" call.
-
-See also:
-
- **PEP 526** - Syntax for Variable Annotations
- The proposal that added syntax for annotating the types of
- variables (including class variables and instance variables),
- instead of expressing them through comments.
-
- **PEP 484** - Type hints
- The proposal that added the "typing" module to provide a standard
- syntax for type annotations that can be used in static analysis
- tools and IDEs.
-
-Changed in version 3.8: Now annotated assignments allow the same
-expressions in the right hand side as regular assignments. Previously,
-some expressions (like un-parenthesized tuple expressions) caused a
-syntax error.
-
-Changed in version 3.14: Annotations are now lazily evaluated in a
-separate annotation scope. If the assignment target is not simple,
-annotations are never evaluated.
-''',
- 'assignment-expressions': r'''Assignment expressions
-**********************
-
- **assignment_expression**: ["identifier" ":="] "expression"
-
-An assignment expression (sometimes also called a “named expression”
-or “walrus”) assigns an "expression" to an "identifier", while also
-returning the value of the "expression".
-
-One common use case is when handling matched regular expressions:
-
- if matching := pattern.search(data):
- do_something(matching)
-
-Or, when processing a file stream in chunks:
-
- while chunk := file.read(9000):
- process(chunk)
-
-Assignment expressions must be surrounded by parentheses when used as
-expression statements and when used as sub-expressions in slicing,
-conditional, lambda, keyword-argument, and comprehension-if
-expressions and in "assert", "with", and "assignment" statements. In
-all other places where they can be used, parentheses are not required,
-including in "if" and "while" statements.
-
-Added in version 3.8: See **PEP 572** for more details about
-assignment expressions.
-''',
- 'async': r'''Coroutines
-**********
-
-Added in version 3.5.
-
-
-Coroutine function definition
-=============================
-
- **async_funcdef**: ["decorators"] "async" "def" "funcname" "(" ["parameter_list"] ")"
- ["->" "expression"] ":" "suite"
-
-Execution of Python coroutines can be suspended and resumed at many
-points (see *coroutine*). "await" expressions, "async for" and "async
-with" can only be used in the body of a coroutine function.
-
-Functions defined with "async def" syntax are always coroutine
-functions, even if they do not contain "await" or "async" keywords.
-
-It is a "SyntaxError" to use a "yield from" expression inside the body
-of a coroutine function.
-
-An example of a coroutine function:
-
- async def func(param1, param2):
- do_stuff()
- await some_coroutine()
-
-Changed in version 3.7: "await" and "async" are now keywords;
-previously they were only treated as such inside the body of a
-coroutine function.
-
-
-The "async for" statement
-=========================
-
- **async_for_stmt**: "async" "for_stmt"
-
-An *asynchronous iterable* provides an "__aiter__" method that
-directly returns an *asynchronous iterator*, which can call
-asynchronous code in its "__anext__" method.
-
-The "async for" statement allows convenient iteration over
-asynchronous iterables.
-
-The following code:
-
- async for TARGET in ITER:
- SUITE
- else:
- SUITE2
-
-Is semantically equivalent to:
-
- iter = (ITER)
- iter = type(iter).__aiter__(iter)
- running = True
-
- while running:
- try:
- TARGET = await type(iter).__anext__(iter)
- except StopAsyncIteration:
- running = False
- else:
- SUITE
- else:
- SUITE2
-
-See also "__aiter__()" and "__anext__()" for details.
-
-It is a "SyntaxError" to use an "async for" statement outside the body
-of a coroutine function.
-
-
-The "async with" statement
-==========================
-
- **async_with_stmt**: "async" "with_stmt"
-
-An *asynchronous context manager* is a *context manager* that is able
-to suspend execution in its *enter* and *exit* methods.
-
-The following code:
-
- async with EXPRESSION as TARGET:
- SUITE
-
-is semantically equivalent to:
-
- manager = (EXPRESSION)
- aenter = type(manager).__aenter__
- aexit = type(manager).__aexit__
- value = await aenter(manager)
- hit_except = False
-
- try:
- TARGET = value
- SUITE
- except:
- hit_except = True
- if not await aexit(manager, *sys.exc_info()):
- raise
- finally:
- if not hit_except:
- await aexit(manager, None, None, None)
-
-See also "__aenter__()" and "__aexit__()" for details.
-
-It is a "SyntaxError" to use an "async with" statement outside the
-body of a coroutine function.
-
-See also:
-
- **PEP 492** - Coroutines with async and await syntax
- The proposal that made coroutines a proper standalone concept in
- Python, and added supporting syntax.
-''',
- 'atom-identifiers': r'''Identifiers (Names)
-*******************
-
-An identifier occurring as an atom is a name. See section Identifiers
-and keywords for lexical definition and section Naming and binding for
-documentation of naming and binding.
-
-When the name is bound to an object, evaluation of the atom yields
-that object. When a name is not bound, an attempt to evaluate it
-raises a "NameError" exception.
-
-
-Private name mangling
-=====================
-
-When an identifier that textually occurs in a class definition begins
-with two or more underscore characters and does not end in two or more
-underscores, it is considered a *private name* of that class.
-
-See also: The class specifications.
-
-More precisely, private names are transformed to a longer form before
-code is generated for them. If the transformed name is longer than
-255 characters, implementation-defined truncation may happen.
-
-The transformation is independent of the syntactical context in which
-the identifier is used but only the following private identifiers are
-mangled:
-
-* Any name used as the name of a variable that is assigned or read or
- any name of an attribute being accessed.
-
- The "__name__" attribute of nested functions, classes, and type
- aliases is however not mangled.
-
-* The name of imported modules, e.g., "__spam" in "import __spam". If
- the module is part of a package (i.e., its name contains a dot), the
- name is *not* mangled, e.g., the "__foo" in "import __foo.bar" is
- not mangled.
-
-* The name of an imported member, e.g., "__f" in "from spam import
- __f".
-
-The transformation rule is defined as follows:
-
-* The class name, with leading underscores removed and a single
- leading underscore inserted, is inserted in front of the identifier,
- e.g., the identifier "__spam" occurring in a class named "Foo",
- "_Foo" or "__Foo" is transformed to "_Foo__spam".
-
-* If the class name consists only of underscores, the transformation
- is the identity, e.g., the identifier "__spam" occurring in a class
- named "_" or "__" is left as is.
-''',
- 'atom-literals': r'''Literals
-********
-
-Python supports string and bytes literals and various numeric
-literals:
-
- **literal**: "stringliteral" | "bytesliteral"
- | "integer" | "floatnumber" | "imagnumber"
-
-Evaluation of a literal yields an object of the given type (string,
-bytes, integer, floating-point number, complex number) with the given
-value. The value may be approximated in the case of floating-point
-and imaginary (complex) literals. See section Literals for details.
-
-All literals correspond to immutable data types, and hence the
-object’s identity is less important than its value. Multiple
-evaluations of literals with the same value (either the same
-occurrence in the program text or a different occurrence) may obtain
-the same object or a different object with the same value.
-''',
- 'attribute-access': r'''Customizing attribute access
-****************************
-
-The following methods can be defined to customize the meaning of
-attribute access (use of, assignment to, or deletion of "x.name") for
-class instances.
-
-object.__getattr__(self, name)
-
- Called when the default attribute access fails with an
- "AttributeError" (either "__getattribute__()" raises an
- "AttributeError" because *name* is not an instance attribute or an
- attribute in the class tree for "self"; or "__get__()" of a *name*
- property raises "AttributeError"). This method should either
- return the (computed) attribute value or raise an "AttributeError"
- exception. The "object" class itself does not provide this method.
-
- Note that if the attribute is found through the normal mechanism,
- "__getattr__()" is not called. (This is an intentional asymmetry
- between "__getattr__()" and "__setattr__()".) This is done both for
- efficiency reasons and because otherwise "__getattr__()" would have
- no way to access other attributes of the instance. Note that at
- least for instance variables, you can take total control by not
- inserting any values in the instance attribute dictionary (but
- instead inserting them in another object). See the
- "__getattribute__()" method below for a way to actually get total
- control over attribute access.
-
-object.__getattribute__(self, name)
-
- Called unconditionally to implement attribute accesses for
- instances of the class. If the class also defines "__getattr__()",
- the latter will not be called unless "__getattribute__()" either
- calls it explicitly or raises an "AttributeError". This method
- should return the (computed) attribute value or raise an
- "AttributeError" exception. In order to avoid infinite recursion in
- this method, its implementation should always call the base class
- method with the same name to access any attributes it needs, for
- example, "object.__getattribute__(self, name)".
-
- Note:
-
- This method may still be bypassed when looking up special methods
- as the result of implicit invocation via language syntax or
- built-in functions. See Special method lookup.
-
- For certain sensitive attribute accesses, raises an auditing event
- "object.__getattr__" with arguments "obj" and "name".
-
-object.__setattr__(self, name, value)
-
- Called when an attribute assignment is attempted. This is called
- instead of the normal mechanism (i.e. store the value in the
- instance dictionary). *name* is the attribute name, *value* is the
- value to be assigned to it.
-
- If "__setattr__()" wants to assign to an instance attribute, it
- should call the base class method with the same name, for example,
- "object.__setattr__(self, name, value)".
-
- For certain sensitive attribute assignments, raises an auditing
- event "object.__setattr__" with arguments "obj", "name", "value".
-
-object.__delattr__(self, name)
-
- Like "__setattr__()" but for attribute deletion instead of
- assignment. This should only be implemented if "del obj.name" is
- meaningful for the object.
-
- For certain sensitive attribute deletions, raises an auditing event
- "object.__delattr__" with arguments "obj" and "name".
-
-object.__dir__(self)
-
- Called when "dir()" is called on the object. An iterable must be
- returned. "dir()" converts the returned iterable to a list and
- sorts it.
-
-
-Customizing module attribute access
-===================================
-
-Special names "__getattr__" and "__dir__" can be also used to
-customize access to module attributes. The "__getattr__" function at
-the module level should accept one argument which is the name of an
-attribute and return the computed value or raise an "AttributeError".
-If an attribute is not found on a module object through the normal
-lookup, i.e. "object.__getattribute__()", then "__getattr__" is
-searched in the module "__dict__" before raising an "AttributeError".
-If found, it is called with the attribute name and the result is
-returned.
-
-The "__dir__" function should accept no arguments, and return an
-iterable of strings that represents the names accessible on module. If
-present, this function overrides the standard "dir()" search on a
-module.
-
-For a more fine grained customization of the module behavior (setting
-attributes, properties, etc.), one can set the "__class__" attribute
-of a module object to a subclass of "types.ModuleType". For example:
-
- import sys
- from types import ModuleType
-
- class VerboseModule(ModuleType):
- def __repr__(self):
- return f'Verbose {self.__name__}'
-
- def __setattr__(self, attr, value):
- print(f'Setting {attr}...')
- super().__setattr__(attr, value)
-
- sys.modules[__name__].__class__ = VerboseModule
-
-Note:
-
- Defining module "__getattr__" and setting module "__class__" only
- affect lookups made using the attribute access syntax – directly
- accessing the module globals (whether by code within the module, or
- via a reference to the module’s globals dictionary) is unaffected.
-
-Changed in version 3.5: "__class__" module attribute is now writable.
-
-Added in version 3.7: "__getattr__" and "__dir__" module attributes.
-
-See also:
-
- **PEP 562** - Module __getattr__ and __dir__
- Describes the "__getattr__" and "__dir__" functions on modules.
-
-
-Implementing Descriptors
-========================
-
-The following methods only apply when an instance of the class
-containing the method (a so-called *descriptor* class) appears in an
-*owner* class (the descriptor must be in either the owner’s class
-dictionary or in the class dictionary for one of its parents). In the
-examples below, “the attribute” refers to the attribute whose name is
-the key of the property in the owner class’ "__dict__". The "object"
-class itself does not implement any of these protocols.
-
-object.__get__(self, instance, owner=None)
-
- Called to get the attribute of the owner class (class attribute
- access) or of an instance of that class (instance attribute
- access). The optional *owner* argument is the owner class, while
- *instance* is the instance that the attribute was accessed through,
- or "None" when the attribute is accessed through the *owner*.
-
- This method should return the computed attribute value or raise an
- "AttributeError" exception.
-
- **PEP 252** specifies that "__get__()" is callable with one or two
- arguments. Python’s own built-in descriptors support this
- specification; however, it is likely that some third-party tools
- have descriptors that require both arguments. Python’s own
- "__getattribute__()" implementation always passes in both arguments
- whether they are required or not.
-
-object.__set__(self, instance, value)
-
- Called to set the attribute on an instance *instance* of the owner
- class to a new value, *value*.
-
- Note, adding "__set__()" or "__delete__()" changes the kind of
- descriptor to a “data descriptor”. See Invoking Descriptors for
- more details.
-
-object.__delete__(self, instance)
-
- Called to delete the attribute on an instance *instance* of the
- owner class.
-
-Instances of descriptors may also have the "__objclass__" attribute
-present:
-
-object.__objclass__
-
- The attribute "__objclass__" is interpreted by the "inspect" module
- as specifying the class where this object was defined (setting this
- appropriately can assist in runtime introspection of dynamic class
- attributes). For callables, it may indicate that an instance of the
- given type (or a subclass) is expected or required as the first
- positional argument (for example, CPython sets this attribute for
- unbound methods that are implemented in C).
-
-
-Invoking Descriptors
-====================
-
-In general, a descriptor is an object attribute with “binding
-behavior”, one whose attribute access has been overridden by methods
-in the descriptor protocol: "__get__()", "__set__()", and
-"__delete__()". If any of those methods are defined for an object, it
-is said to be a descriptor.
-
-The default behavior for attribute access is to get, set, or delete
-the attribute from an object’s dictionary. For instance, "a.x" has a
-lookup chain starting with "a.__dict__['x']", then
-"type(a).__dict__['x']", and continuing through the base classes of
-"type(a)" excluding metaclasses.
-
-However, if the looked-up value is an object defining one of the
-descriptor methods, then Python may override the default behavior and
-invoke the descriptor method instead. Where this occurs in the
-precedence chain depends on which descriptor methods were defined and
-how they were called.
-
-The starting point for descriptor invocation is a binding, "a.x". How
-the arguments are assembled depends on "a":
-
-Direct Call
- The simplest and least common call is when user code directly
- invokes a descriptor method: "x.__get__(a)".
-
-Instance Binding
- If binding to an object instance, "a.x" is transformed into the
- call: "type(a).__dict__['x'].__get__(a, type(a))".
-
-Class Binding
- If binding to a class, "A.x" is transformed into the call:
- "A.__dict__['x'].__get__(None, A)".
-
-Super Binding
- A dotted lookup such as "super(A, a).x" searches
- "a.__class__.__mro__" for a base class "B" following "A" and then
- returns "B.__dict__['x'].__get__(a, A)". If not a descriptor, "x"
- is returned unchanged.
-
-For instance bindings, the precedence of descriptor invocation depends
-on which descriptor methods are defined. A descriptor can define any
-combination of "__get__()", "__set__()" and "__delete__()". If it
-does not define "__get__()", then accessing the attribute will return
-the descriptor object itself unless there is a value in the object’s
-instance dictionary. If the descriptor defines "__set__()" and/or
-"__delete__()", it is a data descriptor; if it defines neither, it is
-a non-data descriptor. Normally, data descriptors define both
-"__get__()" and "__set__()", while non-data descriptors have just the
-"__get__()" method. Data descriptors with "__get__()" and "__set__()"
-(and/or "__delete__()") defined always override a redefinition in an
-instance dictionary. In contrast, non-data descriptors can be
-overridden by instances.
-
-Python methods (including those decorated with "@staticmethod" and
-"@classmethod") are implemented as non-data descriptors. Accordingly,
-instances can redefine and override methods. This allows individual
-instances to acquire behaviors that differ from other instances of the
-same class.
-
-The "property()" function is implemented as a data descriptor.
-Accordingly, instances cannot override the behavior of a property.
-
-
-__slots__
-=========
-
-*__slots__* allow us to explicitly declare data members (like
-properties) and deny the creation of "__dict__" and *__weakref__*
-(unless explicitly declared in *__slots__* or available in a parent.)
-
-The space saved over using "__dict__" can be significant. Attribute
-lookup speed can be significantly improved as well.
-
-object.__slots__
-
- This class variable can be assigned a string, iterable, or sequence
- of strings with variable names used by instances. *__slots__*
- reserves space for the declared variables and prevents the
- automatic creation of "__dict__" and *__weakref__* for each
- instance.
-
-Notes on using *__slots__*:
-
-* When inheriting from a class without *__slots__*, the "__dict__" and
- *__weakref__* attribute of the instances will always be accessible.
-
-* Without a "__dict__" variable, instances cannot be assigned new
- variables not listed in the *__slots__* definition. Attempts to
- assign to an unlisted variable name raises "AttributeError". If
- dynamic assignment of new variables is desired, then add
- "'__dict__'" to the sequence of strings in the *__slots__*
- declaration.
-
-* Without a *__weakref__* variable for each instance, classes defining
- *__slots__* do not support "weak references" to its instances. If
- weak reference support is needed, then add "'__weakref__'" to the
- sequence of strings in the *__slots__* declaration.
-
-* *__slots__* are implemented at the class level by creating
- descriptors for each variable name. As a result, class attributes
- cannot be used to set default values for instance variables defined
- by *__slots__*; otherwise, the class attribute would overwrite the
- descriptor assignment.
-
-* The action of a *__slots__* declaration is not limited to the class
- where it is defined. *__slots__* declared in parents are available
- in child classes. However, instances of a child subclass will get a
- "__dict__" and *__weakref__* unless the subclass also defines
- *__slots__* (which should only contain names of any *additional*
- slots).
-
-* If a class defines a slot also defined in a base class, the instance
- variable defined by the base class slot is inaccessible (except by
- retrieving its descriptor directly from the base class). This
- renders the meaning of the program undefined. In the future, a
- check may be added to prevent this.
-
-* "TypeError" will be raised if nonempty *__slots__* are defined for a
- class derived from a ""variable-length" built-in type" such as
- "int", "bytes", and "tuple".
-
-* Any non-string *iterable* may be assigned to *__slots__*.
-
-* If a "dictionary" is used to assign *__slots__*, the dictionary keys
- will be used as the slot names. The values of the dictionary can be
- used to provide per-attribute docstrings that will be recognised by
- "inspect.getdoc()" and displayed in the output of "help()".
-
-* "__class__" assignment works only if both classes have the same
- *__slots__*.
-
-* Multiple inheritance with multiple slotted parent classes can be
- used, but only one parent is allowed to have attributes created by
- slots (the other bases must have empty slot layouts) - violations
- raise "TypeError".
-
-* If an *iterator* is used for *__slots__* then a *descriptor* is
- created for each of the iterator’s values. However, the *__slots__*
- attribute will be an empty iterator.
-''',
- 'attribute-references': r'''Attribute references
-********************
-
-An attribute reference is a primary followed by a period and a name:
-
- **attributeref**: "primary" "." "identifier"
-
-The primary must evaluate to an object of a type that supports
-attribute references, which most objects do. This object is then
-asked to produce the attribute whose name is the identifier. The type
-and value produced is determined by the object. Multiple evaluations
-of the same attribute reference may yield different objects.
-
-This production can be customized by overriding the
-"__getattribute__()" method or the "__getattr__()" method. The
-"__getattribute__()" method is called first and either returns a value
-or raises "AttributeError" if the attribute is not available.
-
-If an "AttributeError" is raised and the object has a "__getattr__()"
-method, that method is called as a fallback.
-''',
- 'augassign': r'''Augmented assignment statements
-*******************************
-
-Augmented assignment is the combination, in a single statement, of a
-binary operation and an assignment statement:
-
- **augmented_assignment_stmt**: "augtarget" "augop" ("expression_list" | "yield_expression")
- **augtarget**: "identifier" | "attributeref" | "subscription" | "slicing"
- **augop**: "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
- | ">>=" | "<<=" | "&=" | "^=" | "|="
-
-(See section Primaries for the syntax definitions of the last three
-symbols.)
-
-An augmented assignment evaluates the target (which, unlike normal
-assignment statements, cannot be an unpacking) and the expression
-list, performs the binary operation specific to the type of assignment
-on the two operands, and assigns the result to the original target.
-The target is only evaluated once.
-
-An augmented assignment statement like "x += 1" can be rewritten as "x
-= x + 1" to achieve a similar, but not exactly equal effect. In the
-augmented version, "x" is only evaluated once. Also, when possible,
-the actual operation is performed *in-place*, meaning that rather than
-creating a new object and assigning that to the target, the old object
-is modified instead.
-
-Unlike normal assignments, augmented assignments evaluate the left-
-hand side *before* evaluating the right-hand side. For example, "a[i]
-+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and performs
-the addition, and lastly, it writes the result back to "a[i]".
-
-With the exception of assigning to tuples and multiple targets in a
-single statement, the assignment done by augmented assignment
-statements is handled the same way as normal assignments. Similarly,
-with the exception of the possible *in-place* behavior, the binary
-operation performed by augmented assignment is the same as the normal
-binary operations.
-
-For targets which are attribute references, the same caveat about
-class and instance attributes applies as for regular assignments.
-''',
- 'await': r'''Await expression
-****************
-
-Suspend the execution of *coroutine* on an *awaitable* object. Can
-only be used inside a *coroutine function*.
-
- **await_expr**: "await" "primary"
-
-Added in version 3.5.
-''',
- 'binary': r'''Binary arithmetic operations
-****************************
-
-The binary arithmetic operations have the conventional priority
-levels. Note that some of these operations also apply to certain non-
-numeric types. Apart from the power operator, there are only two
-levels, one for multiplicative operators and one for additive
-operators:
-
- **m_expr**: "u_expr" | "m_expr" "*" "u_expr" | "m_expr" "@" "m_expr" |
- "m_expr" "//" "u_expr" | "m_expr" "/" "u_expr" |
- "m_expr" "%" "u_expr"
- **a_expr**: "m_expr" | "a_expr" "+" "m_expr" | "a_expr" "-" "m_expr"
-
-The "*" (multiplication) operator yields the product of its arguments.
-The arguments must either both be numbers, or one argument must be an
-integer and the other must be a sequence. In the former case, the
-numbers are converted to a common real type and then multiplied
-together. In the latter case, sequence repetition is performed; a
-negative repetition factor yields an empty sequence.
-
-This operation can be customized using the special "__mul__()" and
-"__rmul__()" methods.
-
-Changed in version 3.14: If only one operand is a complex number, the
-other operand is converted to a floating-point number.
-
-The "@" (at) operator is intended to be used for matrix
-multiplication. No builtin Python types implement this operator.
-
-This operation can be customized using the special "__matmul__()" and
-"__rmatmul__()" methods.
-
-Added in version 3.5.
-
-The "/" (division) and "//" (floor division) operators yield the
-quotient of their arguments. The numeric arguments are first
-converted to a common type. Division of integers yields a float, while
-floor division of integers results in an integer; the result is that
-of mathematical division with the ‘floor’ function applied to the
-result. Division by zero raises the "ZeroDivisionError" exception.
-
-The division operation can be customized using the special
-"__truediv__()" and "__rtruediv__()" methods. The floor division
-operation can be customized using the special "__floordiv__()" and
-"__rfloordiv__()" methods.
-
-The "%" (modulo) operator yields the remainder from the division of
-the first argument by the second. The numeric arguments are first
-converted to a common type. A zero right argument raises the
-"ZeroDivisionError" exception. The arguments may be floating-point
-numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals "4*0.7 +
-0.34".) The modulo operator always yields a result with the same sign
-as its second operand (or zero); the absolute value of the result is
-strictly smaller than the absolute value of the second operand [1].
-
-The floor division and modulo operators are connected by the following
-identity: "x == (x//y)*y + (x%y)". Floor division and modulo are also
-connected with the built-in function "divmod()": "divmod(x, y) ==
-(x//y, x%y)". [2].
-
-In addition to performing the modulo operation on numbers, the "%"
-operator is also overloaded by string objects to perform old-style
-string formatting (also known as interpolation). The syntax for
-string formatting is described in the Python Library Reference,
-section printf-style String Formatting.
-
-The *modulo* operation can be customized using the special "__mod__()"
-and "__rmod__()" methods.
-
-The floor division operator, the modulo operator, and the "divmod()"
-function are not defined for complex numbers. Instead, convert to a
-floating-point number using the "abs()" function if appropriate.
-
-The "+" (addition) operator yields the sum of its arguments. The
-arguments must either both be numbers or both be sequences of the same
-type. In the former case, the numbers are converted to a common real
-type and then added together. In the latter case, the sequences are
-concatenated.
-
-This operation can be customized using the special "__add__()" and
-"__radd__()" methods.
-
-Changed in version 3.14: If only one operand is a complex number, the
-other operand is converted to a floating-point number.
-
-The "-" (subtraction) operator yields the difference of its arguments.
-The numeric arguments are first converted to a common real type.
-
-This operation can be customized using the special "__sub__()" and
-"__rsub__()" methods.
-
-Changed in version 3.14: If only one operand is a complex number, the
-other operand is converted to a floating-point number.
-''',
- 'bitwise': r'''Binary bitwise operations
-*************************
-
-Each of the three bitwise operations has a different priority level:
-
- **and_expr**: "shift_expr" | "and_expr" "&" "shift_expr"
- **xor_expr**: "and_expr" | "xor_expr" "^" "and_expr"
- **or_expr**: "xor_expr" | "or_expr" "|" "xor_expr"
-
-The "&" operator yields the bitwise AND of its arguments, which must
-be integers or one of them must be a custom object overriding
-"__and__()" or "__rand__()" special methods.
-
-The "^" operator yields the bitwise XOR (exclusive OR) of its
-arguments, which must be integers or one of them must be a custom
-object overriding "__xor__()" or "__rxor__()" special methods.
-
-The "|" operator yields the bitwise (inclusive) OR of its arguments,
-which must be integers or one of them must be a custom object
-overriding "__or__()" or "__ror__()" special methods.
-''',
- 'bltin-code-objects': r'''Code Objects
-************
-
-Code objects are used by the implementation to represent “pseudo-
-compiled” executable Python code such as a function body. They differ
-from function objects because they don’t contain a reference to their
-global execution environment. Code objects are returned by the built-
-in "compile()" function and can be extracted from function objects
-through their "__code__" attribute. See also the "code" module.
-
-Accessing "__code__" raises an auditing event "object.__getattr__"
-with arguments "obj" and ""__code__"".
-
-A code object can be executed or evaluated by passing it (instead of a
-source string) to the "exec()" or "eval()" built-in functions.
-
-See The standard type hierarchy for more information.
-''',
- 'bltin-ellipsis-object': r'''The Ellipsis Object
-*******************
-
-This object is commonly used by slicing (see Slicings). It supports
-no special operations. There is exactly one ellipsis object, named
-"Ellipsis" (a built-in name). "type(Ellipsis)()" produces the
-"Ellipsis" singleton.
-
-It is written as "Ellipsis" or "...".
-''',
- 'bltin-null-object': r'''The Null Object
-***************
-
-This object is returned by functions that don’t explicitly return a
-value. It supports no special operations. There is exactly one null
-object, named "None" (a built-in name). "type(None)()" produces the
-same singleton.
-
-It is written as "None".
-''',
- 'bltin-type-objects': r'''Type Objects
-************
-
-Type objects represent the various object types. An object’s type is
-accessed by the built-in function "type()". There are no special
-operations on types. The standard module "types" defines names for
-all standard built-in types.
-
-Types are written like this: "<class 'int'>".
-''',
- 'booleans': r'''Boolean operations
-******************
-
- **or_test**: "and_test" | "or_test" "or" "and_test"
- **and_test**: "not_test" | "and_test" "and" "not_test"
- **not_test**: "comparison" | "not" "not_test"
-
-In the context of Boolean operations, and also when expressions are
-used by control flow statements, the following values are interpreted
-as false: "False", "None", numeric zero of all types, and empty
-strings and containers (including strings, tuples, lists,
-dictionaries, sets and frozensets). All other values are interpreted
-as true. User-defined objects can customize their truth value by
-providing a "__bool__()" method.
-
-The operator "not" yields "True" if its argument is false, "False"
-otherwise.
-
-The expression "x and y" first evaluates *x*; if *x* is false, its
-value is returned; otherwise, *y* is evaluated and the resulting value
-is returned.
-
-The expression "x or y" first evaluates *x*; if *x* is true, its value
-is returned; otherwise, *y* is evaluated and the resulting value is
-returned.
-
-Note that neither "and" nor "or" restrict the value and type they
-return to "False" and "True", but rather return the last evaluated
-argument. This is sometimes useful, e.g., if "s" is a string that
-should be replaced by a default value if it is empty, the expression
-"s or 'foo'" yields the desired value. Because "not" has to create a
-new value, it returns a boolean value regardless of the type of its
-argument (for example, "not 'foo'" produces "False" rather than "''".)
-''',
- 'break': r'''The "break" statement
-*********************
-
- **break_stmt**: "break"
-
-"break" may only occur syntactically nested in a "for" or "while"
-loop, but not nested in a function or class definition within that
-loop.
-
-It terminates the nearest enclosing loop, skipping the optional "else"
-clause if the loop has one.
-
-If a "for" loop is terminated by "break", the loop control target
-keeps its current value.
-
-When "break" passes control out of a "try" statement with a "finally"
-clause, that "finally" clause is executed before really leaving the
-loop.
-''',
- 'callable-types': r'''Emulating callable objects
-**************************
-
-object.__call__(self[, args...])
-
- Called when the instance is “called” as a function; if this method
- is defined, "x(arg1, arg2, ...)" roughly translates to
- "type(x).__call__(x, arg1, ...)". The "object" class itself does
- not provide this method.
-''',
- 'calls': r'''Calls
-*****
-
-A call calls a callable object (e.g., a *function*) with a possibly
-empty series of *arguments*:
-
- **call**: "primary" "(" ["argument_list" [","] | "comprehension"] ")"
- **argument_list**: "positional_arguments" ["," "starred_and_keywords"]
- ["," "keywords_arguments"]
- | "starred_and_keywords" ["," "keywords_arguments"]
- | "keywords_arguments"
- **positional_arguments**: positional_item ("," positional_item)*
- **positional_item**: "assignment_expression" | "*" "expression"
- **starred_and_keywords**: ("*" "expression" | "keyword_item")
- ("," "*" "expression" | "," "keyword_item")*
- **keywords_arguments**: ("keyword_item" | "**" "expression")
- ("," "keyword_item" | "," "**" "expression")*
- **keyword_item**: "identifier" "=" "expression"
-
-An optional trailing comma may be present after the positional and
-keyword arguments but does not affect the semantics.
-
-The primary must evaluate to a callable object (user-defined
-functions, built-in functions, methods of built-in objects, class
-objects, methods of class instances, and all objects having a
-"__call__()" method are callable). All argument expressions are
-evaluated before the call is attempted. Please refer to section
-Function definitions for the syntax of formal *parameter* lists.
-
-If keyword arguments are present, they are first converted to
-positional arguments, as follows. First, a list of unfilled slots is
-created for the formal parameters. If there are N positional
-arguments, they are placed in the first N slots. Next, for each
-keyword argument, the identifier is used to determine the
-corresponding slot (if the identifier is the same as the first formal
-parameter name, the first slot is used, and so on). If the slot is
-already filled, a "TypeError" exception is raised. Otherwise, the
-argument is placed in the slot, filling it (even if the expression is
-"None", it fills the slot). When all arguments have been processed,
-the slots that are still unfilled are filled with the corresponding
-default value from the function definition. (Default values are
-calculated, once, when the function is defined; thus, a mutable object
-such as a list or dictionary used as default value will be shared by
-all calls that don’t specify an argument value for the corresponding
-slot; this should usually be avoided.) If there are any unfilled
-slots for which no default value is specified, a "TypeError" exception
-is raised. Otherwise, the list of filled slots is used as the
-argument list for the call.
-
-**CPython implementation detail:** An implementation may provide
-built-in functions whose positional parameters do not have names, even
-if they are ‘named’ for the purpose of documentation, and which
-therefore cannot be supplied by keyword. In CPython, this is the case
-for functions implemented in C that use "PyArg_ParseTuple()" to parse
-their arguments.
-
-If there are more positional arguments than there are formal parameter
-slots, a "TypeError" exception is raised, unless a formal parameter
-using the syntax "*identifier" is present; in this case, that formal
-parameter receives a tuple containing the excess positional arguments
-(or an empty tuple if there were no excess positional arguments).
-
-If any keyword argument does not correspond to a formal parameter
-name, a "TypeError" exception is raised, unless a formal parameter
-using the syntax "**identifier" is present; in this case, that formal
-parameter receives a dictionary containing the excess keyword
-arguments (using the keywords as keys and the argument values as
-corresponding values), or a (new) empty dictionary if there were no
-excess keyword arguments.
-
-If the syntax "*expression" appears in the function call, "expression"
-must evaluate to an *iterable*. Elements from these iterables are
-treated as if they were additional positional arguments. For the call
-"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, …, *yM*,
-this is equivalent to a call with M+4 positional arguments *x1*, *x2*,
-*y1*, …, *yM*, *x3*, *x4*.
-
-A consequence of this is that although the "*expression" syntax may
-appear *after* explicit keyword arguments, it is processed *before*
-the keyword arguments (and any "**expression" arguments – see below).
-So:
-
- >>> def f(a, b):
- ... print(a, b)
- ...
- >>> f(b=1, *(2,))
- 2 1
- >>> f(a=1, *(2,))
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- TypeError: f() got multiple values for keyword argument 'a'
- >>> f(1, *(2,))
- 1 2
-
-It is unusual for both keyword arguments and the "*expression" syntax
-to be used in the same call, so in practice this confusion does not
-often arise.
-
-If the syntax "**expression" appears in the function call,
-"expression" must evaluate to a *mapping*, the contents of which are
-treated as additional keyword arguments. If a parameter matching a key
-has already been given a value (by an explicit keyword argument, or
-from another unpacking), a "TypeError" exception is raised.
-
-When "**expression" is used, each key in this mapping must be a
-string. Each value from the mapping is assigned to the first formal
-parameter eligible for keyword assignment whose name is equal to the
-key. A key need not be a Python identifier (e.g. ""max-temp °F"" is
-acceptable, although it will not match any formal parameter that could
-be declared). If there is no match to a formal parameter the key-value
-pair is collected by the "**" parameter, if there is one, or if there
-is not, a "TypeError" exception is raised.
-
-Formal parameters using the syntax "*identifier" or "**identifier"
-cannot be used as positional argument slots or as keyword argument
-names.
-
-Changed in version 3.5: Function calls accept any number of "*" and
-"**" unpackings, positional arguments may follow iterable unpackings
-("*"), and keyword arguments may follow dictionary unpackings ("**").
-Originally proposed by **PEP 448**.
-
-A call always returns some value, possibly "None", unless it raises an
-exception. How this value is computed depends on the type of the
-callable object.
-
-If it is—
-
-a user-defined function:
- The code block for the function is executed, passing it the
- argument list. The first thing the code block will do is bind the
- formal parameters to the arguments; this is described in section
- Function definitions. When the code block executes a "return"
- statement, this specifies the return value of the function call.
- If execution reaches the end of the code block without executing a
- "return" statement, the return value is "None".
-
-a built-in function or method:
- The result is up to the interpreter; see Built-in Functions for the
- descriptions of built-in functions and methods.
-
-a class object:
- A new instance of that class is returned.
-
-a class instance method:
- The corresponding user-defined function is called, with an argument
- list that is one longer than the argument list of the call: the
- instance becomes the first argument.
-
-a class instance:
- The class must define a "__call__()" method; the effect is then the
- same as if that method was called.
-''',
- 'class': r'''Class definitions
-*****************
-
-A class definition defines a class object (see section The standard
-type hierarchy):
-
- **classdef**: ["decorators"] "class" "classname" ["type_params"] ["inheritance"] ":" "suite"
- **inheritance**: "(" ["argument_list"] ")"
- **classname**: "identifier"
-
-A class definition is an executable statement. The inheritance list
-usually gives a list of base classes (see Metaclasses for more
-advanced uses), so each item in the list should evaluate to a class
-object which allows subclassing. Classes without an inheritance list
-inherit, by default, from the base class "object"; hence,
-
- class Foo:
- pass
-
-is equivalent to
-
- class Foo(object):
- pass
-
-The class’s suite is then executed in a new execution frame (see
-Naming and binding), using a newly created local namespace and the
-original global namespace. (Usually, the suite contains mostly
-function definitions.) When the class’s suite finishes execution, its
-execution frame is discarded but its local namespace is saved. [5] A
-class object is then created using the inheritance list for the base
-classes and the saved local namespace for the attribute dictionary.
-The class name is bound to this class object in the original local
-namespace.
-
-The order in which attributes are defined in the class body is
-preserved in the new class’s "__dict__". Note that this is reliable
-only right after the class is created and only for classes that were
-defined using the definition syntax.
-
-Class creation can be customized heavily using metaclasses.
-
-Classes can also be decorated: just like when decorating functions,
-
- @f1(arg)
- @f2
- class Foo: pass
-
-is roughly equivalent to
-
- class Foo: pass
- Foo = f1(arg)(f2(Foo))
-
-The evaluation rules for the decorator expressions are the same as for
-function decorators. The result is then bound to the class name.
-
-Changed in version 3.9: Classes may be decorated with any valid
-"assignment_expression". Previously, the grammar was much more
-restrictive; see **PEP 614** for details.
-
-A list of type parameters may be given in square brackets immediately
-after the class’s name. This indicates to static type checkers that
-the class is generic. At runtime, the type parameters can be retrieved
-from the class’s "__type_params__" attribute. See Generic classes for
-more.
-
-Changed in version 3.12: Type parameter lists are new in Python 3.12.
-
-**Programmer’s note:** Variables defined in the class definition are
-class attributes; they are shared by instances. Instance attributes
-can be set in a method with "self.name = value". Both class and
-instance attributes are accessible through the notation “"self.name"”,
-and an instance attribute hides a class attribute with the same name
-when accessed in this way. Class attributes can be used as defaults
-for instance attributes, but using mutable values there can lead to
-unexpected results. Descriptors can be used to create instance
-variables with different implementation details.
-
-See also:
-
- **PEP 3115** - Metaclasses in Python 3000
- The proposal that changed the declaration of metaclasses to the
- current syntax, and the semantics for how classes with
- metaclasses are constructed.
-
- **PEP 3129** - Class Decorators
- The proposal that added class decorators. Function and method
- decorators were introduced in **PEP 318**.
-''',
- 'comparisons': r'''Comparisons
-***********
-
-Unlike C, all comparison operations in Python have the same priority,
-which is lower than that of any arithmetic, shifting or bitwise
-operation. Also unlike C, expressions like "a < b < c" have the
-interpretation that is conventional in mathematics:
-
- **comparison**: "or_expr" ("comp_operator" "or_expr")*
- **comp_operator**: "<" | ">" | "==" | ">=" | "<=" | "!="
- | "is" ["not"] | ["not"] "in"
-
-Comparisons yield boolean values: "True" or "False". Custom *rich
-comparison methods* may return non-boolean values. In this case Python
-will call "bool()" on such value in boolean contexts.
-
-Comparisons can be chained arbitrarily, e.g., "x < y <= z" is
-equivalent to "x < y and y <= z", except that "y" is evaluated only
-once (but in both cases "z" is not evaluated at all when "x < y" is
-found to be false).
-
-Formally, if *a*, *b*, *c*, …, *y*, *z* are expressions and *op1*,
-*op2*, …, *opN* are comparison operators, then "a op1 b op2 c ... y
-opN z" is equivalent to "a op1 b and b op2 c and ... y opN z", except
-that each expression is evaluated at most once.
-
-Note that "a op1 b op2 c" doesn’t imply any kind of comparison between
-*a* and *c*, so that, e.g., "x < y > z" is perfectly legal (though
-perhaps not pretty).
-
-
-Value comparisons
-=================
-
-The operators "<", ">", "==", ">=", "<=", and "!=" compare the values
-of two objects. The objects do not need to have the same type.
-
-Chapter Objects, values and types states that objects have a value (in
-addition to type and identity). The value of an object is a rather
-abstract notion in Python: For example, there is no canonical access
-method for an object’s value. Also, there is no requirement that the
-value of an object should be constructed in a particular way, e.g.
-comprised of all its data attributes. Comparison operators implement a
-particular notion of what the value of an object is. One can think of
-them as defining the value of an object indirectly, by means of their
-comparison implementation.
-
-Because all types are (direct or indirect) subtypes of "object", they
-inherit the default comparison behavior from "object". Types can
-customize their comparison behavior by implementing *rich comparison
-methods* like "__lt__()", described in Basic customization.
-
-The default behavior for equality comparison ("==" and "!=") is based
-on the identity of the objects. Hence, equality comparison of
-instances with the same identity results in equality, and equality
-comparison of instances with different identities results in
-inequality. A motivation for this default behavior is the desire that
-all objects should be reflexive (i.e. "x is y" implies "x == y").
-
-A default order comparison ("<", ">", "<=", and ">=") is not provided;
-an attempt raises "TypeError". A motivation for this default behavior
-is the lack of a similar invariant as for equality.
-
-The behavior of the default equality comparison, that instances with
-different identities are always unequal, may be in contrast to what
-types will need that have a sensible definition of object value and
-value-based equality. Such types will need to customize their
-comparison behavior, and in fact, a number of built-in types have done
-that.
-
-The following list describes the comparison behavior of the most
-important built-in types.
-
-* Numbers of built-in numeric types (Numeric Types — int, float,
- complex) and of the standard library types "fractions.Fraction" and
- "decimal.Decimal" can be compared within and across their types,
- with the restriction that complex numbers do not support order
- comparison. Within the limits of the types involved, they compare
- mathematically (algorithmically) correct without loss of precision.
-
- The not-a-number values "float('NaN')" and "decimal.Decimal('NaN')"
- are special. Any ordered comparison of a number to a not-a-number
- value is false. A counter-intuitive implication is that not-a-number
- values are not equal to themselves. For example, if "x =
- float('NaN')", "3 < x", "x < 3" and "x == x" are all false, while "x
- != x" is true. This behavior is compliant with IEEE 754.
-
-* "None" and "NotImplemented" are singletons. **PEP 8** advises that
- comparisons for singletons should always be done with "is" or "is
- not", never the equality operators.
-
-* Binary sequences (instances of "bytes" or "bytearray") can be
- compared within and across their types. They compare
- lexicographically using the numeric values of their elements.
-
-* Strings (instances of "str") compare lexicographically using the
- numerical Unicode code points (the result of the built-in function
- "ord()") of their characters. [3]
-
- Strings and binary sequences cannot be directly compared.
-
-* Sequences (instances of "tuple", "list", or "range") can be compared
- only within each of their types, with the restriction that ranges do
- not support order comparison. Equality comparison across these
- types results in inequality, and ordering comparison across these
- types raises "TypeError".
-
- Sequences compare lexicographically using comparison of
- corresponding elements. The built-in containers typically assume
- identical objects are equal to themselves. That lets them bypass
- equality tests for identical objects to improve performance and to
- maintain their internal invariants.
-
- Lexicographical comparison between built-in collections works as
- follows:
-
- * For two collections to compare equal, they must be of the same
- type, have the same length, and each pair of corresponding
- elements must compare equal (for example, "[1,2] == (1,2)" is
- false because the type is not the same).
-
- * Collections that support order comparison are ordered the same as
- their first unequal elements (for example, "[1,2,x] <= [1,2,y]"
- has the same value as "x <= y"). If a corresponding element does
- not exist, the shorter collection is ordered first (for example,
- "[1,2] < [1,2,3]" is true).
-
-* Mappings (instances of "dict") compare equal if and only if they
- have equal "(key, value)" pairs. Equality comparison of the keys and
- values enforces reflexivity.
-
- Order comparisons ("<", ">", "<=", and ">=") raise "TypeError".
-
-* Sets (instances of "set" or "frozenset") can be compared within and
- across their types.
-
- They define order comparison operators to mean subset and superset
- tests. Those relations do not define total orderings (for example,
- the two sets "{1,2}" and "{2,3}" are not equal, nor subsets of one
- another, nor supersets of one another). Accordingly, sets are not
- appropriate arguments for functions which depend on total ordering
- (for example, "min()", "max()", and "sorted()" produce undefined
- results given a list of sets as inputs).
-
- Comparison of sets enforces reflexivity of its elements.
-
-* Most other built-in types have no comparison methods implemented, so
- they inherit the default comparison behavior.
-
-User-defined classes that customize their comparison behavior should
-follow some consistency rules, if possible:
-
-* Equality comparison should be reflexive. In other words, identical
- objects should compare equal:
-
- "x is y" implies "x == y"
-
-* Comparison should be symmetric. In other words, the following
- expressions should have the same result:
-
- "x == y" and "y == x"
-
- "x != y" and "y != x"
-
- "x < y" and "y > x"
-
- "x <= y" and "y >= x"
-
-* Comparison should be transitive. The following (non-exhaustive)
- examples illustrate that:
-
- "x > y and y > z" implies "x > z"
-
- "x < y and y <= z" implies "x < z"
-
-* Inverse comparison should result in the boolean negation. In other
- words, the following expressions should have the same result:
-
- "x == y" and "not x != y"
-
- "x < y" and "not x >= y" (for total ordering)
-
- "x > y" and "not x <= y" (for total ordering)
-
- The last two expressions apply to totally ordered collections (e.g.
- to sequences, but not to sets or mappings). See also the
- "total_ordering()" decorator.
-
-* The "hash()" result should be consistent with equality. Objects that
- are equal should either have the same hash value, or be marked as
- unhashable.
-
-Python does not enforce these consistency rules. In fact, the
-not-a-number values are an example for not following these rules.
-
-
-Membership test operations
-==========================
-
-The operators "in" and "not in" test for membership. "x in s"
-evaluates to "True" if *x* is a member of *s*, and "False" otherwise.
-"x not in s" returns the negation of "x in s". All built-in sequences
-and set types support this as well as dictionary, for which "in" tests
-whether the dictionary has a given key. For container types such as
-list, tuple, set, frozenset, dict, or collections.deque, the
-expression "x in y" is equivalent to "any(x is e or x == e for e in
-y)".
-
-For the string and bytes types, "x in y" is "True" if and only if *x*
-is a substring of *y*. An equivalent test is "y.find(x) != -1".
-Empty strings are always considered to be a substring of any other
-string, so """ in "abc"" will return "True".
-
-For user-defined classes which define the "__contains__()" method, "x
-in y" returns "True" if "y.__contains__(x)" returns a true value, and
-"False" otherwise.
-
-For user-defined classes which do not define "__contains__()" but do
-define "__iter__()", "x in y" is "True" if some value "z", for which
-the expression "x is z or x == z" is true, is produced while iterating
-over "y". If an exception is raised during the iteration, it is as if
-"in" raised that exception.
-
-Lastly, the old-style iteration protocol is tried: if a class defines
-"__getitem__()", "x in y" is "True" if and only if there is a non-
-negative integer index *i* such that "x is y[i] or x == y[i]", and no
-lower integer index raises the "IndexError" exception. (If any other
-exception is raised, it is as if "in" raised that exception).
-
-The operator "not in" is defined to have the inverse truth value of
-"in".
-
-
-Identity comparisons
-====================
-
-The operators "is" and "is not" test for an object’s identity: "x is
-y" is true if and only if *x* and *y* are the same object. An
-Object’s identity is determined using the "id()" function. "x is not
-y" yields the inverse truth value. [4]
-''',
- 'compound': r'''Compound statements
-*******************
-
-Compound statements contain (groups of) other statements; they affect
-or control the execution of those other statements in some way. In
-general, compound statements span multiple lines, although in simple
-incarnations a whole compound statement may be contained in one line.
-
-The "if", "while" and "for" statements implement traditional control
-flow constructs. "try" specifies exception handlers and/or cleanup
-code for a group of statements, while the "with" statement allows the
-execution of initialization and finalization code around a block of
-code. Function and class definitions are also syntactically compound
-statements.
-
-A compound statement consists of one or more ‘clauses.’ A clause
-consists of a header and a ‘suite.’ The clause headers of a
-particular compound statement are all at the same indentation level.
-Each clause header begins with a uniquely identifying keyword and ends
-with a colon. A suite is a group of statements controlled by a
-clause. A suite can be one or more semicolon-separated simple
-statements on the same line as the header, following the header’s
-colon, or it can be one or more indented statements on subsequent
-lines. Only the latter form of a suite can contain nested compound
-statements; the following is illegal, mostly because it wouldn’t be
-clear to which "if" clause a following "else" clause would belong:
-
- if test1: if test2: print(x)
-
-Also note that the semicolon binds tighter than the colon in this
-context, so that in the following example, either all or none of the
-"print()" calls are executed:
-
- if x < y < z: print(x); print(y); print(z)
-
-Summarizing:
-
- **compound_stmt**: "if_stmt"
- | "while_stmt"
- | "for_stmt"
- | "try_stmt"
- | "with_stmt"
- | "match_stmt"
- | "funcdef"
- | "classdef"
- | "async_with_stmt"
- | "async_for_stmt"
- | "async_funcdef"
- **suite**: "stmt_list" NEWLINE | NEWLINE INDENT "statement"+ DEDENT
- **statement**: "stmt_list" NEWLINE | "compound_stmt"
- **stmt_list**: "simple_stmt" (";" "simple_stmt")* [";"]
-
-Note that statements always end in a "NEWLINE" possibly followed by a
-"DEDENT". Also note that optional continuation clauses always begin
-with a keyword that cannot start a statement, thus there are no
-ambiguities (the ‘dangling "else"’ problem is solved in Python by
-requiring nested "if" statements to be indented).
-
-The formatting of the grammar rules in the following sections places
-each clause on a separate line for clarity.
-
-
-The "if" statement
-==================
-
-The "if" statement is used for conditional execution:
-
- **if_stmt**: "if" "assignment_expression" ":" "suite"
- ("elif" "assignment_expression" ":" "suite")*
- ["else" ":" "suite"]
-
-It selects exactly one of the suites by evaluating the expressions one
-by one until one is found to be true (see section Boolean operations
-for the definition of true and false); then that suite is executed
-(and no other part of the "if" statement is executed or evaluated).
-If all expressions are false, the suite of the "else" clause, if
-present, is executed.
-
-
-The "while" statement
-=====================
-
-The "while" statement is used for repeated execution as long as an
-expression is true:
-
- **while_stmt**: "while" "assignment_expression" ":" "suite"
- ["else" ":" "suite"]
-
-This repeatedly tests the expression and, if it is true, executes the
-first suite; if the expression is false (which may be the first time
-it is tested) the suite of the "else" clause, if present, is executed
-and the loop terminates.
-
-A "break" statement executed in the first suite terminates the loop
-without executing the "else" clause’s suite. A "continue" statement
-executed in the first suite skips the rest of the suite and goes back
-to testing the expression.
-
-
-The "for" statement
-===================
-
-The "for" statement is used to iterate over the elements of a sequence
-(such as a string, tuple or list) or other iterable object:
-
- **for_stmt**: "for" "target_list" "in" "starred_list" ":" "suite"
- ["else" ":" "suite"]
-
-The "starred_list" expression is evaluated once; it should yield an
-*iterable* object. An *iterator* is created for that iterable. The
-first item provided by the iterator is then assigned to the target
-list using the standard rules for assignments (see Assignment
-statements), and the suite is executed. This repeats for each item
-provided by the iterator. When the iterator is exhausted, the suite
-in the "else" clause, if present, is executed, and the loop
-terminates.
-
-A "break" statement executed in the first suite terminates the loop
-without executing the "else" clause’s suite. A "continue" statement
-executed in the first suite skips the rest of the suite and continues
-with the next item, or with the "else" clause if there is no next
-item.
-
-The for-loop makes assignments to the variables in the target list.
-This overwrites all previous assignments to those variables including
-those made in the suite of the for-loop:
-
- for i in range(10):
- print(i)
- i = 5 # this will not affect the for-loop
- # because i will be overwritten with the next
- # index in the range
-
-Names in the target list are not deleted when the loop is finished,
-but if the sequence is empty, they will not have been assigned to at
-all by the loop. Hint: the built-in type "range()" represents
-immutable arithmetic sequences of integers. For instance, iterating
-"range(3)" successively yields 0, 1, and then 2.
-
-Changed in version 3.11: Starred elements are now allowed in the
-expression list.
-
-
-The "try" statement
-===================
-
-The "try" statement specifies exception handlers and/or cleanup code
-for a group of statements:
-
- **try_stmt**: "try1_stmt" | "try2_stmt" | "try3_stmt"
- **try1_stmt**: "try" ":" "suite"
- ("except" ["expression" ["as" "identifier"]] ":" "suite")+
- ["else" ":" "suite"]
- ["finally" ":" "suite"]
- **try2_stmt**: "try" ":" "suite"
- ("except" "*" "expression" ["as" "identifier"] ":" "suite")+
- ["else" ":" "suite"]
- ["finally" ":" "suite"]
- **try3_stmt**: "try" ":" "suite"
- "finally" ":" "suite"
-
-Additional information on exceptions can be found in section
-Exceptions, and information on using the "raise" statement to generate
-exceptions may be found in section The raise statement.
-
-
-"except" clause
----------------
-
-The "except" clause(s) specify one or more exception handlers. When no
-exception occurs in the "try" clause, no exception handler is
-executed. When an exception occurs in the "try" suite, a search for an
-exception handler is started. This search inspects the "except"
-clauses in turn until one is found that matches the exception. An
-expression-less "except" clause, if present, must be last; it matches
-any exception.
-
-For an "except" clause with an expression, the expression must
-evaluate to an exception type or a tuple of exception types. The
-raised exception matches an "except" clause whose expression evaluates
-to the class or a *non-virtual base class* of the exception object, or
-to a tuple that contains such a class.
-
-If no "except" clause matches the exception, the search for an
-exception handler continues in the surrounding code and on the
-invocation stack. [1]
-
-If the evaluation of an expression in the header of an "except" clause
-raises an exception, the original search for a handler is canceled and
-a search starts for the new exception in the surrounding code and on
-the call stack (it is treated as if the entire "try" statement raised
-the exception).
-
-When a matching "except" clause is found, the exception is assigned to
-the target specified after the "as" keyword in that "except" clause,
-if present, and the "except" clause’s suite is executed. All "except"
-clauses must have an executable block. When the end of this block is
-reached, execution continues normally after the entire "try"
-statement. (This means that if two nested handlers exist for the same
-exception, and the exception occurs in the "try" clause of the inner
-handler, the outer handler will not handle the exception.)
-
-When an exception has been assigned using "as target", it is cleared
-at the end of the "except" clause. This is as if
-
- except E as N:
- foo
-
-was translated to
-
- except E as N:
- try:
- foo
- finally:
- del N
-
-This means the exception must be assigned to a different name to be
-able to refer to it after the "except" clause. Exceptions are cleared
-because with the traceback attached to them, they form a reference
-cycle with the stack frame, keeping all locals in that frame alive
-until the next garbage collection occurs.
-
-Before an "except" clause’s suite is executed, the exception is stored
-in the "sys" module, where it can be accessed from within the body of
-the "except" clause by calling "sys.exception()". When leaving an
-exception handler, the exception stored in the "sys" module is reset
-to its previous value:
-
- >>> print(sys.exception())
- None
- >>> try:
- ... raise TypeError
- ... except:
- ... print(repr(sys.exception()))
- ... try:
- ... raise ValueError
- ... except:
- ... print(repr(sys.exception()))
- ... print(repr(sys.exception()))
- ...
- TypeError()
- ValueError()
- TypeError()
- >>> print(sys.exception())
- None
-
-
-"except*" clause
-----------------
-
-The "except*" clause(s) are used for handling "ExceptionGroup"s. The
-exception type for matching is interpreted as in the case of "except",
-but in the case of exception groups we can have partial matches when
-the type matches some of the exceptions in the group. This means that
-multiple "except*" clauses can execute, each handling part of the
-exception group. Each clause executes at most once and handles an
-exception group of all matching exceptions. Each exception in the
-group is handled by at most one "except*" clause, the first that
-matches it.
-
- >>> try:
- ... raise ExceptionGroup("eg",
- ... [ValueError(1), TypeError(2), OSError(3), OSError(4)])
- ... except* TypeError as e:
- ... print(f'caught {type(e)} with nested {e.exceptions}')
- ... except* OSError as e:
- ... print(f'caught {type(e)} with nested {e.exceptions}')
- ...
- caught <class 'ExceptionGroup'> with nested (TypeError(2),)
- caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))
- + Exception Group Traceback (most recent call last):
- | File "<stdin>", line 2, in <module>
- | ExceptionGroup: eg
- +-+---------------- 1 ----------------
- | ValueError: 1
- +------------------------------------
-
-Any remaining exceptions that were not handled by any "except*" clause
-are re-raised at the end, along with all exceptions that were raised
-from within the "except*" clauses. If this list contains more than one
-exception to reraise, they are combined into an exception group.
-
-If the raised exception is not an exception group and its type matches
-one of the "except*" clauses, it is caught and wrapped by an exception
-group with an empty message string.
-
- >>> try:
- ... raise BlockingIOError
- ... except* BlockingIOError as e:
- ... print(repr(e))
- ...
- ExceptionGroup('', (BlockingIOError()))
-
-An "except*" clause must have a matching expression; it cannot be
-"except*:". Furthermore, this expression cannot contain exception
-group types, because that would have ambiguous semantics.
-
-It is not possible to mix "except" and "except*" in the same "try".
-"break", "continue" and "return" cannot appear in an "except*" clause.
-
-
-"else" clause
--------------
-
-The optional "else" clause is executed if the control flow leaves the
-"try" suite, no exception was raised, and no "return", "continue", or
-"break" statement was executed. Exceptions in the "else" clause are
-not handled by the preceding "except" clauses.
-
-
-"finally" clause
-----------------
-
-If "finally" is present, it specifies a ‘cleanup’ handler. The "try"
-clause is executed, including any "except" and "else" clauses. If an
-exception occurs in any of the clauses and is not handled, the
-exception is temporarily saved. The "finally" clause is executed. If
-there is a saved exception it is re-raised at the end of the "finally"
-clause. If the "finally" clause raises another exception, the saved
-exception is set as the context of the new exception. If the "finally"
-clause executes a "return", "break" or "continue" statement, the saved
-exception is discarded:
-
- >>> def f():
- ... try:
- ... 1/0
- ... finally:
- ... return 42
- ...
- >>> f()
- 42
-
-The exception information is not available to the program during
-execution of the "finally" clause.
-
-When a "return", "break" or "continue" statement is executed in the
-"try" suite of a "try"…"finally" statement, the "finally" clause is
-also executed ‘on the way out.’
-
-The return value of a function is determined by the last "return"
-statement executed. Since the "finally" clause always executes, a
-"return" statement executed in the "finally" clause will always be the
-last one executed:
-
- >>> def foo():
- ... try:
- ... return 'try'
- ... finally:
- ... return 'finally'
- ...
- >>> foo()
- 'finally'
-
-Changed in version 3.8: Prior to Python 3.8, a "continue" statement
-was illegal in the "finally" clause due to a problem with the
-implementation.
-
-
-The "with" statement
-====================
-
-The "with" statement is used to wrap the execution of a block with
-methods defined by a context manager (see section With Statement
-Context Managers). This allows common "try"…"except"…"finally" usage
-patterns to be encapsulated for convenient reuse.
-
- **with_stmt**: "with" ( "(" "with_stmt_contents" ","? ")" | "with_stmt_contents" ) ":" "suite"
- **with_stmt_contents**: "with_item" ("," "with_item")*
- **with_item**: "expression" ["as" "target"]
-
-The execution of the "with" statement with one “item” proceeds as
-follows:
-
-1. The context expression (the expression given in the "with_item") is
- evaluated to obtain a context manager.
-
-2. The context manager’s "__enter__()" is loaded for later use.
-
-3. The context manager’s "__exit__()" is loaded for later use.
-
-4. The context manager’s "__enter__()" method is invoked.
-
-5. If a target was included in the "with" statement, the return value
- from "__enter__()" is assigned to it.
-
- Note:
-
- The "with" statement guarantees that if the "__enter__()" method
- returns without an error, then "__exit__()" will always be
- called. Thus, if an error occurs during the assignment to the
- target list, it will be treated the same as an error occurring
- within the suite would be. See step 7 below.
-
-6. The suite is executed.
-
-7. The context manager’s "__exit__()" method is invoked. If an
- exception caused the suite to be exited, its type, value, and
- traceback are passed as arguments to "__exit__()". Otherwise, three
- "None" arguments are supplied.
-
- If the suite was exited due to an exception, and the return value
- from the "__exit__()" method was false, the exception is reraised.
- If the return value was true, the exception is suppressed, and
- execution continues with the statement following the "with"
- statement.
-
- If the suite was exited for any reason other than an exception, the
- return value from "__exit__()" is ignored, and execution proceeds
- at the normal location for the kind of exit that was taken.
-
-The following code:
-
- with EXPRESSION as TARGET:
- SUITE
-
-is semantically equivalent to:
-
- manager = (EXPRESSION)
- enter = type(manager).__enter__
- exit = type(manager).__exit__
- value = enter(manager)
- hit_except = False
-
- try:
- TARGET = value
- SUITE
- except:
- hit_except = True
- if not exit(manager, *sys.exc_info()):
- raise
- finally:
- if not hit_except:
- exit(manager, None, None, None)
-
-With more than one item, the context managers are processed as if
-multiple "with" statements were nested:
-
- with A() as a, B() as b:
- SUITE
-
-is semantically equivalent to:
-
- with A() as a:
- with B() as b:
- SUITE
-
-You can also write multi-item context managers in multiple lines if
-the items are surrounded by parentheses. For example:
-
- with (
- A() as a,
- B() as b,
- ):
- SUITE
-
-Changed in version 3.1: Support for multiple context expressions.
-
-Changed in version 3.10: Support for using grouping parentheses to
-break the statement in multiple lines.
-
-See also:
-
- **PEP 343** - The “with” statement
- The specification, background, and examples for the Python "with"
- statement.
-
-
-The "match" statement
-=====================
-
-Added in version 3.10.
-
-The match statement is used for pattern matching. Syntax:
-
- **match_stmt**: 'match' "subject_expr" ":" NEWLINE INDENT "case_block"+ DEDENT
- **subject_expr**: "star_named_expression" "," "star_named_expressions"?
- | "named_expression"
- **case_block**: 'case' "patterns" ["guard"] ":" "block"
-
-Note:
-
- This section uses single quotes to denote soft keywords.
-
-Pattern matching takes a pattern as input (following "case") and a
-subject value (following "match"). The pattern (which may contain
-subpatterns) is matched against the subject value. The outcomes are:
-
-* A match success or failure (also termed a pattern success or
- failure).
-
-* Possible binding of matched values to a name. The prerequisites for
- this are further discussed below.
-
-The "match" and "case" keywords are soft keywords.
-
-See also:
-
- * **PEP 634** – Structural Pattern Matching: Specification
-
- * **PEP 636** – Structural Pattern Matching: Tutorial
-
-
-Overview
---------
-
-Here’s an overview of the logical flow of a match statement:
-
-1. The subject expression "subject_expr" is evaluated and a resulting
- subject value obtained. If the subject expression contains a comma,
- a tuple is constructed using the standard rules.
-
-2. Each pattern in a "case_block" is attempted to match with the
- subject value. The specific rules for success or failure are
- described below. The match attempt can also bind some or all of the
- standalone names within the pattern. The precise pattern binding
- rules vary per pattern type and are specified below. **Name
- bindings made during a successful pattern match outlive the
- executed block and can be used after the match statement**.
-
- Note:
-
- During failed pattern matches, some subpatterns may succeed. Do
- not rely on bindings being made for a failed match. Conversely,
- do not rely on variables remaining unchanged after a failed
- match. The exact behavior is dependent on implementation and may
- vary. This is an intentional decision made to allow different
- implementations to add optimizations.
-
-3. If the pattern succeeds, the corresponding guard (if present) is
- evaluated. In this case all name bindings are guaranteed to have
- happened.
-
- * If the guard evaluates as true or is missing, the "block" inside
- "case_block" is executed.
-
- * Otherwise, the next "case_block" is attempted as described above.
-
- * If there are no further case blocks, the match statement is
- completed.
-
-Note:
-
- Users should generally never rely on a pattern being evaluated.
- Depending on implementation, the interpreter may cache values or use
- other optimizations which skip repeated evaluations.
-
-A sample match statement:
-
- >>> flag = False
- >>> match (100, 200):
- ... case (100, 300): # Mismatch: 200 != 300
- ... print('Case 1')
- ... case (100, 200) if flag: # Successful match, but guard fails
- ... print('Case 2')
- ... case (100, y): # Matches and binds y to 200
- ... print(f'Case 3, y: {y}')
- ... case _: # Pattern not attempted
- ... print('Case 4, I match anything!')
- ...
- Case 3, y: 200
-
-In this case, "if flag" is a guard. Read more about that in the next
-section.
-
-
-Guards
-------
-
- **guard**: "if" "named_expression"
-
-A "guard" (which is part of the "case") must succeed for code inside
-the "case" block to execute. It takes the form: "if" followed by an
-expression.
-
-The logical flow of a "case" block with a "guard" follows:
-
-1. Check that the pattern in the "case" block succeeded. If the
- pattern failed, the "guard" is not evaluated and the next "case"
- block is checked.
-
-2. If the pattern succeeded, evaluate the "guard".
-
- * If the "guard" condition evaluates as true, the case block is
- selected.
-
- * If the "guard" condition evaluates as false, the case block is
- not selected.
-
- * If the "guard" raises an exception during evaluation, the
- exception bubbles up.
-
-Guards are allowed to have side effects as they are expressions.
-Guard evaluation must proceed from the first to the last case block,
-one at a time, skipping case blocks whose pattern(s) don’t all
-succeed. (I.e., guard evaluation must happen in order.) Guard
-evaluation must stop once a case block is selected.
-
-
-Irrefutable Case Blocks
------------------------
-
-An irrefutable case block is a match-all case block. A match
-statement may have at most one irrefutable case block, and it must be
-last.
-
-A case block is considered irrefutable if it has no guard and its
-pattern is irrefutable. A pattern is considered irrefutable if we can
-prove from its syntax alone that it will always succeed. Only the
-following patterns are irrefutable:
-
-* AS Patterns whose left-hand side is irrefutable
-
-* OR Patterns containing at least one irrefutable pattern
-
-* Capture Patterns
-
-* Wildcard Patterns
-
-* parenthesized irrefutable patterns
-
-
-Patterns
---------
-
-Note:
-
- This section uses grammar notations beyond standard EBNF:
-
- * the notation "SEP.RULE+" is shorthand for "RULE (SEP RULE)*"
-
- * the notation "!RULE" is shorthand for a negative lookahead
- assertion
-
-The top-level syntax for "patterns" is:
-
- **patterns**: "open_sequence_pattern" | "pattern"
- **pattern**: "as_pattern" | "or_pattern"
- **closed_pattern**: | "literal_pattern"
- | "capture_pattern"
- | "wildcard_pattern"
- | "value_pattern"
- | "group_pattern"
- | "sequence_pattern"
- | "mapping_pattern"
- | "class_pattern"
-
-The descriptions below will include a description “in simple terms” of
-what a pattern does for illustration purposes (credits to Raymond
-Hettinger for a document that inspired most of the descriptions). Note
-that these descriptions are purely for illustration purposes and **may
-not** reflect the underlying implementation. Furthermore, they do not
-cover all valid forms.
-
-
-OR Patterns
-~~~~~~~~~~~
-
-An OR pattern is two or more patterns separated by vertical bars "|".
-Syntax:
-
- **or_pattern**: "|"."closed_pattern"+
-
-Only the final subpattern may be irrefutable, and each subpattern must
-bind the same set of names to avoid ambiguity.
-
-An OR pattern matches each of its subpatterns in turn to the subject
-value, until one succeeds. The OR pattern is then considered
-successful. Otherwise, if none of the subpatterns succeed, the OR
-pattern fails.
-
-In simple terms, "P1 | P2 | ..." will try to match "P1", if it fails
-it will try to match "P2", succeeding immediately if any succeeds,
-failing otherwise.
-
-
-AS Patterns
-~~~~~~~~~~~
-
-An AS pattern matches an OR pattern on the left of the "as" keyword
-against a subject. Syntax:
-
- **as_pattern**: "or_pattern" "as" "capture_pattern"
-
-If the OR pattern fails, the AS pattern fails. Otherwise, the AS
-pattern binds the subject to the name on the right of the as keyword
-and succeeds. "capture_pattern" cannot be a "_".
-
-In simple terms "P as NAME" will match with "P", and on success it
-will set "NAME = <subject>".
-
-
-Literal Patterns
-~~~~~~~~~~~~~~~~
-
-A literal pattern corresponds to most literals in Python. Syntax:
-
- **literal_pattern**: "signed_number"
- | "signed_number" "+" NUMBER
- | "signed_number" "-" NUMBER
- | "strings"
- | "None"
- | "True"
- | "False"
- **signed_number**: ["-"] NUMBER
-
-The rule "strings" and the token "NUMBER" are defined in the standard
-Python grammar. Triple-quoted strings are supported. Raw strings and
-byte strings are supported. f-strings are not supported.
-
-The forms "signed_number '+' NUMBER" and "signed_number '-' NUMBER"
-are for expressing complex numbers; they require a real number on the
-left and an imaginary number on the right. E.g. "3 + 4j".
-
-In simple terms, "LITERAL" will succeed only if "<subject> ==
-LITERAL". For the singletons "None", "True" and "False", the "is"
-operator is used.
-
-
-Capture Patterns
-~~~~~~~~~~~~~~~~
-
-A capture pattern binds the subject value to a name. Syntax:
-
- **capture_pattern**: !'_' NAME
-
-A single underscore "_" is not a capture pattern (this is what "!'_'"
-expresses). It is instead treated as a "wildcard_pattern".
-
-In a given pattern, a given name can only be bound once. E.g. "case
-x, x: ..." is invalid while "case [x] | x: ..." is allowed.
-
-Capture patterns always succeed. The binding follows scoping rules
-established by the assignment expression operator in **PEP 572**; the
-name becomes a local variable in the closest containing function scope
-unless there’s an applicable "global" or "nonlocal" statement.
-
-In simple terms "NAME" will always succeed and it will set "NAME =
-<subject>".
-
-
-Wildcard Patterns
-~~~~~~~~~~~~~~~~~
-
-A wildcard pattern always succeeds (matches anything) and binds no
-name. Syntax:
-
- **wildcard_pattern**: '_'
-
-"_" is a soft keyword within any pattern, but only within patterns.
-It is an identifier, as usual, even within "match" subject
-expressions, "guard"s, and "case" blocks.
-
-In simple terms, "_" will always succeed.
-
-
-Value Patterns
-~~~~~~~~~~~~~~
-
-A value pattern represents a named value in Python. Syntax:
-
- **value_pattern**: "attr"
- **attr**: "name_or_attr" "." NAME
- **name_or_attr**: "attr" | NAME
-
-The dotted name in the pattern is looked up using standard Python name
-resolution rules. The pattern succeeds if the value found compares
-equal to the subject value (using the "==" equality operator).
-
-In simple terms "NAME1.NAME2" will succeed only if "<subject> ==
-NAME1.NAME2"
-
-Note:
-
- If the same value occurs multiple times in the same match statement,
- the interpreter may cache the first value found and reuse it rather
- than repeat the same lookup. This cache is strictly tied to a given
- execution of a given match statement.
-
-
-Group Patterns
-~~~~~~~~~~~~~~
-
-A group pattern allows users to add parentheses around patterns to
-emphasize the intended grouping. Otherwise, it has no additional
-syntax. Syntax:
-
- **group_pattern**: "(" "pattern" ")"
-
-In simple terms "(P)" has the same effect as "P".
-
-
-Sequence Patterns
-~~~~~~~~~~~~~~~~~
-
-A sequence pattern contains several subpatterns to be matched against
-sequence elements. The syntax is similar to the unpacking of a list or
-tuple.
-
- **sequence_pattern**: "[" ["maybe_sequence_pattern"] "]"
- | "(" ["open_sequence_pattern"] ")"
- **open_sequence_pattern**: "maybe_star_pattern" "," ["maybe_sequence_pattern"]
- **maybe_sequence_pattern**: ","."maybe_star_pattern"+ ","?
- **maybe_star_pattern**: "star_pattern" | "pattern"
- **star_pattern**: "*" ("capture_pattern" | "wildcard_pattern")
-
-There is no difference if parentheses or square brackets are used for
-sequence patterns (i.e. "(...)" vs "[...]" ).
-
-Note:
-
- A single pattern enclosed in parentheses without a trailing comma
- (e.g. "(3 | 4)") is a group pattern. While a single pattern enclosed
- in square brackets (e.g. "[3 | 4]") is still a sequence pattern.
-
-At most one star subpattern may be in a sequence pattern. The star
-subpattern may occur in any position. If no star subpattern is
-present, the sequence pattern is a fixed-length sequence pattern;
-otherwise it is a variable-length sequence pattern.
-
-The following is the logical flow for matching a sequence pattern
-against a subject value:
-
-1. If the subject value is not a sequence [2], the sequence pattern
- fails.
-
-2. If the subject value is an instance of "str", "bytes" or
- "bytearray" the sequence pattern fails.
-
-3. The subsequent steps depend on whether the sequence pattern is
- fixed or variable-length.
-
- If the sequence pattern is fixed-length:
-
- 1. If the length of the subject sequence is not equal to the number
- of subpatterns, the sequence pattern fails
-
- 2. Subpatterns in the sequence pattern are matched to their
- corresponding items in the subject sequence from left to right.
- Matching stops as soon as a subpattern fails. If all
- subpatterns succeed in matching their corresponding item, the
- sequence pattern succeeds.
-
- Otherwise, if the sequence pattern is variable-length:
-
- 1. If the length of the subject sequence is less than the number of
- non-star subpatterns, the sequence pattern fails.
-
- 2. The leading non-star subpatterns are matched to their
- corresponding items as for fixed-length sequences.
-
- 3. If the previous step succeeds, the star subpattern matches a
- list formed of the remaining subject items, excluding the
- remaining items corresponding to non-star subpatterns following
- the star subpattern.
-
- 4. Remaining non-star subpatterns are matched to their
- corresponding subject items, as for a fixed-length sequence.
-
- Note:
-
- The length of the subject sequence is obtained via "len()" (i.e.
- via the "__len__()" protocol). This length may be cached by the
- interpreter in a similar manner as value patterns.
-
-In simple terms "[P1, P2, P3," … ", P<N>]" matches only if all the
-following happens:
-
-* check "<subject>" is a sequence
-
-* "len(subject) == <N>"
-
-* "P1" matches "<subject>[0]" (note that this match can also bind
- names)
-
-* "P2" matches "<subject>[1]" (note that this match can also bind
- names)
-
-* … and so on for the corresponding pattern/element.
-
-
-Mapping Patterns
-~~~~~~~~~~~~~~~~
-
-A mapping pattern contains one or more key-value patterns. The syntax
-is similar to the construction of a dictionary. Syntax:
-
- **mapping_pattern**: "{" ["items_pattern"] "}"
- **items_pattern**: ","."key_value_pattern"+ ","?
- **key_value_pattern**: ("literal_pattern" | "value_pattern") ":" "pattern"
- | "double_star_pattern"
- **double_star_pattern**: "**" "capture_pattern"
-
-At most one double star pattern may be in a mapping pattern. The
-double star pattern must be the last subpattern in the mapping
-pattern.
-
-Duplicate keys in mapping patterns are disallowed. Duplicate literal
-keys will raise a "SyntaxError". Two keys that otherwise have the same
-value will raise a "ValueError" at runtime.
-
-The following is the logical flow for matching a mapping pattern
-against a subject value:
-
-1. If the subject value is not a mapping [3],the mapping pattern
- fails.
-
-2. If every key given in the mapping pattern is present in the subject
- mapping, and the pattern for each key matches the corresponding
- item of the subject mapping, the mapping pattern succeeds.
-
-3. If duplicate keys are detected in the mapping pattern, the pattern
- is considered invalid. A "SyntaxError" is raised for duplicate
- literal values; or a "ValueError" for named keys of the same value.
-
-Note:
-
- Key-value pairs are matched using the two-argument form of the
- mapping subject’s "get()" method. Matched key-value pairs must
- already be present in the mapping, and not created on-the-fly via
- "__missing__()" or "__getitem__()".
-
-In simple terms "{KEY1: P1, KEY2: P2, ... }" matches only if all the
-following happens:
-
-* check "<subject>" is a mapping
-
-* "KEY1 in <subject>"
-
-* "P1" matches "<subject>[KEY1]"
-
-* … and so on for the corresponding KEY/pattern pair.
-
-
-Class Patterns
-~~~~~~~~~~~~~~
-
-A class pattern represents a class and its positional and keyword
-arguments (if any). Syntax:
-
- **class_pattern**: "name_or_attr" "(" ["pattern_arguments" ","?] ")"
- **pattern_arguments**: "positional_patterns" ["," "keyword_patterns"]
- | "keyword_patterns"
- **positional_patterns**: ","."pattern"+
- **keyword_patterns**: ","."keyword_pattern"+
- **keyword_pattern**: NAME "=" "pattern"
-
-The same keyword should not be repeated in class patterns.
-
-The following is the logical flow for matching a class pattern against
-a subject value:
-
-1. If "name_or_attr" is not an instance of the builtin "type" , raise
- "TypeError".
-
-2. If the subject value is not an instance of "name_or_attr" (tested
- via "isinstance()"), the class pattern fails.
-
-3. If no pattern arguments are present, the pattern succeeds.
- Otherwise, the subsequent steps depend on whether keyword or
- positional argument patterns are present.
-
- For a number of built-in types (specified below), a single
- positional subpattern is accepted which will match the entire
- subject; for these types keyword patterns also work as for other
- types.
-
- If only keyword patterns are present, they are processed as
- follows, one by one:
-
- I. The keyword is looked up as an attribute on the subject.
-
- * If this raises an exception other than "AttributeError", the
- exception bubbles up.
-
- * If this raises "AttributeError", the class pattern has failed.
-
- * Else, the subpattern associated with the keyword pattern is
- matched against the subject’s attribute value. If this fails,
- the class pattern fails; if this succeeds, the match proceeds
- to the next keyword.
-
- II. If all keyword patterns succeed, the class pattern succeeds.
-
- If any positional patterns are present, they are converted to
- keyword patterns using the "__match_args__" attribute on the class
- "name_or_attr" before matching:
-
- I. The equivalent of "getattr(cls, "__match_args__", ())" is
- called.
-
- * If this raises an exception, the exception bubbles up.
-
- * If the returned value is not a tuple, the conversion fails and
- "TypeError" is raised.
-
- * If there are more positional patterns than
- "len(cls.__match_args__)", "TypeError" is raised.
-
- * Otherwise, positional pattern "i" is converted to a keyword
- pattern using "__match_args__[i]" as the keyword.
- "__match_args__[i]" must be a string; if not "TypeError" is
- raised.
-
- * If there are duplicate keywords, "TypeError" is raised.
-
- See also:
-
- Customizing positional arguments in class pattern matching
-
- II. Once all positional patterns have been converted to keyword
- patterns,
- the match proceeds as if there were only keyword patterns.
-
- For the following built-in types the handling of positional
- subpatterns is different:
-
- * "bool"
-
- * "bytearray"
-
- * "bytes"
-
- * "dict"
-
- * "float"
-
- * "frozenset"
-
- * "int"
-
- * "list"
-
- * "set"
-
- * "str"
-
- * "tuple"
-
- These classes accept a single positional argument, and the pattern
- there is matched against the whole object rather than an attribute.
- For example "int(0|1)" matches the value "0", but not the value
- "0.0".
-
-In simple terms "CLS(P1, attr=P2)" matches only if the following
-happens:
-
-* "isinstance(<subject>, CLS)"
-
-* convert "P1" to a keyword pattern using "CLS.__match_args__"
-
-* For each keyword argument "attr=P2":
-
- * "hasattr(<subject>, "attr")"
-
- * "P2" matches "<subject>.attr"
-
-* … and so on for the corresponding keyword argument/pattern pair.
-
-See also:
-
- * **PEP 634** – Structural Pattern Matching: Specification
-
- * **PEP 636** – Structural Pattern Matching: Tutorial
-
-
-Function definitions
-====================
-
-A function definition defines a user-defined function object (see
-section The standard type hierarchy):
-
- **funcdef**: ["decorators"] "def" "funcname" ["type_params"] "(" ["parameter_list"] ")"
- ["->" "expression"] ":" "suite"
- **decorators**: "decorator"+
- **decorator**: "@" "assignment_expression" NEWLINE
- **parameter_list**: "defparameter" ("," "defparameter")* "," "/" ["," ["parameter_list_no_posonly"]]
- | "parameter_list_no_posonly"
- **parameter_list_no_posonly**: "defparameter" ("," "defparameter")* ["," ["parameter_list_starargs"]]
- | "parameter_list_starargs"
- **parameter_list_starargs**: "*" ["star_parameter"] ("," "defparameter")* ["," ["parameter_star_kwargs"]]
- "*" ("," "defparameter")+ ["," ["parameter_star_kwargs"]]
- | "parameter_star_kwargs"
- **parameter_star_kwargs**: "**" "parameter" [","]
- **parameter**: "identifier" [":" "expression"]
- **star_parameter**: "identifier" [":" ["*"] "expression"]
- **defparameter**: "parameter" ["=" "expression"]
- **funcname**: "identifier"
-
-A function definition is an executable statement. Its execution binds
-the function name in the current local namespace to a function object
-(a wrapper around the executable code for the function). This
-function object contains a reference to the current global namespace
-as the global namespace to be used when the function is called.
-
-The function definition does not execute the function body; this gets
-executed only when the function is called. [4]
-
-A function definition may be wrapped by one or more *decorator*
-expressions. Decorator expressions are evaluated when the function is
-defined, in the scope that contains the function definition. The
-result must be a callable, which is invoked with the function object
-as the only argument. The returned value is bound to the function name
-instead of the function object. Multiple decorators are applied in
-nested fashion. For example, the following code
-
- @f1(arg)
- @f2
- def func(): pass
-
-is roughly equivalent to
-
- def func(): pass
- func = f1(arg)(f2(func))
-
-except that the original function is not temporarily bound to the name
-"func".
-
-Changed in version 3.9: Functions may be decorated with any valid
-"assignment_expression". Previously, the grammar was much more
-restrictive; see **PEP 614** for details.
-
-A list of type parameters may be given in square brackets between the
-function’s name and the opening parenthesis for its parameter list.
-This indicates to static type checkers that the function is generic.
-At runtime, the type parameters can be retrieved from the function’s
-"__type_params__" attribute. See Generic functions for more.
-
-Changed in version 3.12: Type parameter lists are new in Python 3.12.
-
-When one or more *parameters* have the form *parameter* "="
-*expression*, the function is said to have “default parameter values.”
-For a parameter with a default value, the corresponding *argument* may
-be omitted from a call, in which case the parameter’s default value is
-substituted. If a parameter has a default value, all following
-parameters up until the “"*"” must also have a default value — this is
-a syntactic restriction that is not expressed by the grammar.
-
-**Default parameter values are evaluated from left to right when the
-function definition is executed.** This means that the expression is
-evaluated once, when the function is defined, and that the same “pre-
-computed” value is used for each call. This is especially important
-to understand when a default parameter value is a mutable object, such
-as a list or a dictionary: if the function modifies the object (e.g.
-by appending an item to a list), the default parameter value is in
-effect modified. This is generally not what was intended. A way
-around this is to use "None" as the default, and explicitly test for
-it in the body of the function, e.g.:
-
- def whats_on_the_telly(penguin=None):
- if penguin is None:
- penguin = []
- penguin.append("property of the zoo")
- return penguin
-
-Function call semantics are described in more detail in section Calls.
-A function call always assigns values to all parameters mentioned in
-the parameter list, either from positional arguments, from keyword
-arguments, or from default values. If the form “"*identifier"” is
-present, it is initialized to a tuple receiving any excess positional
-parameters, defaulting to the empty tuple. If the form
-“"**identifier"” is present, it is initialized to a new ordered
-mapping receiving any excess keyword arguments, defaulting to a new
-empty mapping of the same type. Parameters after “"*"” or
-“"*identifier"” are keyword-only parameters and may only be passed by
-keyword arguments. Parameters before “"/"” are positional-only
-parameters and may only be passed by positional arguments.
-
-Changed in version 3.8: The "/" function parameter syntax may be used
-to indicate positional-only parameters. See **PEP 570** for details.
-
-Parameters may have an *annotation* of the form “": expression"”
-following the parameter name. Any parameter may have an annotation,
-even those of the form "*identifier" or "**identifier". (As a special
-case, parameters of the form "*identifier" may have an annotation “":
-*expression"”.) Functions may have “return” annotation of the form
-“"-> expression"” after the parameter list. These annotations can be
-any valid Python expression. The presence of annotations does not
-change the semantics of a function. See Annotations for more
-information on annotations.
-
-Changed in version 3.11: Parameters of the form “"*identifier"” may
-have an annotation “": *expression"”. See **PEP 646**.
-
-It is also possible to create anonymous functions (functions not bound
-to a name), for immediate use in expressions. This uses lambda
-expressions, described in section Lambdas. Note that the lambda
-expression is merely a shorthand for a simplified function definition;
-a function defined in a “"def"” statement can be passed around or
-assigned to another name just like a function defined by a lambda
-expression. The “"def"” form is actually more powerful since it
-allows the execution of multiple statements and annotations.
-
-**Programmer’s note:** Functions are first-class objects. A “"def"”
-statement executed inside a function definition defines a local
-function that can be returned or passed around. Free variables used
-in the nested function can access the local variables of the function
-containing the def. See section Naming and binding for details.
-
-See also:
-
- **PEP 3107** - Function Annotations
- The original specification for function annotations.
-
- **PEP 484** - Type Hints
- Definition of a standard meaning for annotations: type hints.
-
- **PEP 526** - Syntax for Variable Annotations
- Ability to type hint variable declarations, including class
- variables and instance variables.
-
- **PEP 563** - Postponed Evaluation of Annotations
- Support for forward references within annotations by preserving
- annotations in a string form at runtime instead of eager
- evaluation.
-
- **PEP 318** - Decorators for Functions and Methods
- Function and method decorators were introduced. Class decorators
- were introduced in **PEP 3129**.
-
-
-Class definitions
-=================
-
-A class definition defines a class object (see section The standard
-type hierarchy):
-
- **classdef**: ["decorators"] "class" "classname" ["type_params"] ["inheritance"] ":" "suite"
- **inheritance**: "(" ["argument_list"] ")"
- **classname**: "identifier"
-
-A class definition is an executable statement. The inheritance list
-usually gives a list of base classes (see Metaclasses for more
-advanced uses), so each item in the list should evaluate to a class
-object which allows subclassing. Classes without an inheritance list
-inherit, by default, from the base class "object"; hence,
-
- class Foo:
- pass
-
-is equivalent to
-
- class Foo(object):
- pass
-
-The class’s suite is then executed in a new execution frame (see
-Naming and binding), using a newly created local namespace and the
-original global namespace. (Usually, the suite contains mostly
-function definitions.) When the class’s suite finishes execution, its
-execution frame is discarded but its local namespace is saved. [5] A
-class object is then created using the inheritance list for the base
-classes and the saved local namespace for the attribute dictionary.
-The class name is bound to this class object in the original local
-namespace.
-
-The order in which attributes are defined in the class body is
-preserved in the new class’s "__dict__". Note that this is reliable
-only right after the class is created and only for classes that were
-defined using the definition syntax.
-
-Class creation can be customized heavily using metaclasses.
-
-Classes can also be decorated: just like when decorating functions,
-
- @f1(arg)
- @f2
- class Foo: pass
-
-is roughly equivalent to
-
- class Foo: pass
- Foo = f1(arg)(f2(Foo))
-
-The evaluation rules for the decorator expressions are the same as for
-function decorators. The result is then bound to the class name.
-
-Changed in version 3.9: Classes may be decorated with any valid
-"assignment_expression". Previously, the grammar was much more
-restrictive; see **PEP 614** for details.
-
-A list of type parameters may be given in square brackets immediately
-after the class’s name. This indicates to static type checkers that
-the class is generic. At runtime, the type parameters can be retrieved
-from the class’s "__type_params__" attribute. See Generic classes for
-more.
-
-Changed in version 3.12: Type parameter lists are new in Python 3.12.
-
-**Programmer’s note:** Variables defined in the class definition are
-class attributes; they are shared by instances. Instance attributes
-can be set in a method with "self.name = value". Both class and
-instance attributes are accessible through the notation “"self.name"”,
-and an instance attribute hides a class attribute with the same name
-when accessed in this way. Class attributes can be used as defaults
-for instance attributes, but using mutable values there can lead to
-unexpected results. Descriptors can be used to create instance
-variables with different implementation details.
-
-See also:
-
- **PEP 3115** - Metaclasses in Python 3000
- The proposal that changed the declaration of metaclasses to the
- current syntax, and the semantics for how classes with
- metaclasses are constructed.
-
- **PEP 3129** - Class Decorators
- The proposal that added class decorators. Function and method
- decorators were introduced in **PEP 318**.
-
-
-Coroutines
-==========
-
-Added in version 3.5.
-
-
-Coroutine function definition
------------------------------
-
- **async_funcdef**: ["decorators"] "async" "def" "funcname" "(" ["parameter_list"] ")"
- ["->" "expression"] ":" "suite"
-
-Execution of Python coroutines can be suspended and resumed at many
-points (see *coroutine*). "await" expressions, "async for" and "async
-with" can only be used in the body of a coroutine function.
-
-Functions defined with "async def" syntax are always coroutine
-functions, even if they do not contain "await" or "async" keywords.
-
-It is a "SyntaxError" to use a "yield from" expression inside the body
-of a coroutine function.
-
-An example of a coroutine function:
-
- async def func(param1, param2):
- do_stuff()
- await some_coroutine()
-
-Changed in version 3.7: "await" and "async" are now keywords;
-previously they were only treated as such inside the body of a
-coroutine function.
-
-
-The "async for" statement
--------------------------
-
- **async_for_stmt**: "async" "for_stmt"
-
-An *asynchronous iterable* provides an "__aiter__" method that
-directly returns an *asynchronous iterator*, which can call
-asynchronous code in its "__anext__" method.
-
-The "async for" statement allows convenient iteration over
-asynchronous iterables.
-
-The following code:
-
- async for TARGET in ITER:
- SUITE
- else:
- SUITE2
-
-Is semantically equivalent to:
-
- iter = (ITER)
- iter = type(iter).__aiter__(iter)
- running = True
-
- while running:
- try:
- TARGET = await type(iter).__anext__(iter)
- except StopAsyncIteration:
- running = False
- else:
- SUITE
- else:
- SUITE2
-
-See also "__aiter__()" and "__anext__()" for details.
-
-It is a "SyntaxError" to use an "async for" statement outside the body
-of a coroutine function.
-
-
-The "async with" statement
---------------------------
-
- **async_with_stmt**: "async" "with_stmt"
-
-An *asynchronous context manager* is a *context manager* that is able
-to suspend execution in its *enter* and *exit* methods.
-
-The following code:
-
- async with EXPRESSION as TARGET:
- SUITE
-
-is semantically equivalent to:
-
- manager = (EXPRESSION)
- aenter = type(manager).__aenter__
- aexit = type(manager).__aexit__
- value = await aenter(manager)
- hit_except = False
-
- try:
- TARGET = value
- SUITE
- except:
- hit_except = True
- if not await aexit(manager, *sys.exc_info()):
- raise
- finally:
- if not hit_except:
- await aexit(manager, None, None, None)
-
-See also "__aenter__()" and "__aexit__()" for details.
-
-It is a "SyntaxError" to use an "async with" statement outside the
-body of a coroutine function.
-
-See also:
-
- **PEP 492** - Coroutines with async and await syntax
- The proposal that made coroutines a proper standalone concept in
- Python, and added supporting syntax.
-
-
-Type parameter lists
-====================
-
-Added in version 3.12.
-
-Changed in version 3.13: Support for default values was added (see
-**PEP 696**).
-
- **type_params**: "[" "type_param" ("," "type_param")* "]"
- **type_param**: "typevar" | "typevartuple" | "paramspec"
- **typevar**: "identifier" (":" "expression")? ("=" "expression")?
- **typevartuple**: "*" "identifier" ("=" "expression")?
- **paramspec**: "**" "identifier" ("=" "expression")?
-
-Functions (including coroutines), classes and type aliases may contain
-a type parameter list:
-
- def max[T](args: list[T]) -> T:
- ...
-
- async def amax[T](args: list[T]) -> T:
- ...
-
- class Bag[T]:
- def __iter__(self) -> Iterator[T]:
- ...
-
- def add(self, arg: T) -> None:
- ...
-
- type ListOrSet[T] = list[T] | set[T]
-
-Semantically, this indicates that the function, class, or type alias
-is generic over a type variable. This information is primarily used by
-static type checkers, and at runtime, generic objects behave much like
-their non-generic counterparts.
-
-Type parameters are declared in square brackets ("[]") immediately
-after the name of the function, class, or type alias. The type
-parameters are accessible within the scope of the generic object, but
-not elsewhere. Thus, after a declaration "def func[T](): pass", the
-name "T" is not available in the module scope. Below, the semantics of
-generic objects are described with more precision. The scope of type
-parameters is modeled with a special function (technically, an
-annotation scope) that wraps the creation of the generic object.
-
-Generic functions, classes, and type aliases have a "__type_params__"
-attribute listing their type parameters.
-
-Type parameters come in three kinds:
-
-* "typing.TypeVar", introduced by a plain name (e.g., "T").
- Semantically, this represents a single type to a type checker.
-
-* "typing.TypeVarTuple", introduced by a name prefixed with a single
- asterisk (e.g., "*Ts"). Semantically, this stands for a tuple of any
- number of types.
-
-* "typing.ParamSpec", introduced by a name prefixed with two asterisks
- (e.g., "**P"). Semantically, this stands for the parameters of a
- callable.
-
-"typing.TypeVar" declarations can define *bounds* and *constraints*
-with a colon (":") followed by an expression. A single expression
-after the colon indicates a bound (e.g. "T: int"). Semantically, this
-means that the "typing.TypeVar" can only represent types that are a
-subtype of this bound. A parenthesized tuple of expressions after the
-colon indicates a set of constraints (e.g. "T: (str, bytes)"). Each
-member of the tuple should be a type (again, this is not enforced at
-runtime). Constrained type variables can only take on one of the types
-in the list of constraints.
-
-For "typing.TypeVar"s declared using the type parameter list syntax,
-the bound and constraints are not evaluated when the generic object is
-created, but only when the value is explicitly accessed through the
-attributes "__bound__" and "__constraints__". To accomplish this, the
-bounds or constraints are evaluated in a separate annotation scope.
-
-"typing.TypeVarTuple"s and "typing.ParamSpec"s cannot have bounds or
-constraints.
-
-All three flavors of type parameters can also have a *default value*,
-which is used when the type parameter is not explicitly provided. This
-is added by appending a single equals sign ("=") followed by an
-expression. Like the bounds and constraints of type variables, the
-default value is not evaluated when the object is created, but only
-when the type parameter’s "__default__" attribute is accessed. To this
-end, the default value is evaluated in a separate annotation scope. If
-no default value is specified for a type parameter, the "__default__"
-attribute is set to the special sentinel object "typing.NoDefault".
-
-The following example indicates the full set of allowed type parameter
-declarations:
-
- def overly_generic[
- SimpleTypeVar,
- TypeVarWithDefault = int,
- TypeVarWithBound: int,
- TypeVarWithConstraints: (str, bytes),
- *SimpleTypeVarTuple = (int, float),
- **SimpleParamSpec = (str, bytearray),
- ](
- a: SimpleTypeVar,
- b: TypeVarWithDefault,
- c: TypeVarWithBound,
- d: Callable[SimpleParamSpec, TypeVarWithConstraints],
- *e: SimpleTypeVarTuple,
- ): ...
-
-
-Generic functions
------------------
-
-Generic functions are declared as follows:
-
- def func[T](arg: T): ...
-
-This syntax is equivalent to:
-
- annotation-def TYPE_PARAMS_OF_func():
- T = typing.TypeVar("T")
- def func(arg: T): ...
- func.__type_params__ = (T,)
- return func
- func = TYPE_PARAMS_OF_func()
-
-Here "annotation-def" indicates an annotation scope, which is not
-actually bound to any name at runtime. (One other liberty is taken in
-the translation: the syntax does not go through attribute access on
-the "typing" module, but creates an instance of "typing.TypeVar"
-directly.)
-
-The annotations of generic functions are evaluated within the
-annotation scope used for declaring the type parameters, but the
-function’s defaults and decorators are not.
-
-The following example illustrates the scoping rules for these cases,
-as well as for additional flavors of type parameters:
-
- @decorator
- def func[T: int, *Ts, **P](*args: *Ts, arg: Callable[P, T] = some_default):
- ...
-
-Except for the lazy evaluation of the "TypeVar" bound, this is
-equivalent to:
-
- DEFAULT_OF_arg = some_default
-
- annotation-def TYPE_PARAMS_OF_func():
-
- annotation-def BOUND_OF_T():
- return int
- # In reality, BOUND_OF_T() is evaluated only on demand.
- T = typing.TypeVar("T", bound=BOUND_OF_T())
-
- Ts = typing.TypeVarTuple("Ts")
- P = typing.ParamSpec("P")
-
- def func(*args: *Ts, arg: Callable[P, T] = DEFAULT_OF_arg):
- ...
-
- func.__type_params__ = (T, Ts, P)
- return func
- func = decorator(TYPE_PARAMS_OF_func())
-
-The capitalized names like "DEFAULT_OF_arg" are not actually bound at
-runtime.
-
-
-Generic classes
----------------
-
-Generic classes are declared as follows:
-
- class Bag[T]: ...
-
-This syntax is equivalent to:
-
- annotation-def TYPE_PARAMS_OF_Bag():
- T = typing.TypeVar("T")
- class Bag(typing.Generic[T]):
- __type_params__ = (T,)
- ...
- return Bag
- Bag = TYPE_PARAMS_OF_Bag()
-
-Here again "annotation-def" (not a real keyword) indicates an
-annotation scope, and the name "TYPE_PARAMS_OF_Bag" is not actually
-bound at runtime.
-
-Generic classes implicitly inherit from "typing.Generic". The base
-classes and keyword arguments of generic classes are evaluated within
-the type scope for the type parameters, and decorators are evaluated
-outside that scope. This is illustrated by this example:
-
- @decorator
- class Bag(Base[T], arg=T): ...
-
-This is equivalent to:
-
- annotation-def TYPE_PARAMS_OF_Bag():
- T = typing.TypeVar("T")
- class Bag(Base[T], typing.Generic[T], arg=T):
- __type_params__ = (T,)
- ...
- return Bag
- Bag = decorator(TYPE_PARAMS_OF_Bag())
-
-
-Generic type aliases
---------------------
-
-The "type" statement can also be used to create a generic type alias:
-
- type ListOrSet[T] = list[T] | set[T]
-
-Except for the lazy evaluation of the value, this is equivalent to:
-
- annotation-def TYPE_PARAMS_OF_ListOrSet():
- T = typing.TypeVar("T")
-
- annotation-def VALUE_OF_ListOrSet():
- return list[T] | set[T]
- # In reality, the value is lazily evaluated
- return typing.TypeAliasType("ListOrSet", VALUE_OF_ListOrSet(), type_params=(T,))
- ListOrSet = TYPE_PARAMS_OF_ListOrSet()
-
-Here, "annotation-def" (not a real keyword) indicates an annotation
-scope. The capitalized names like "TYPE_PARAMS_OF_ListOrSet" are not
-actually bound at runtime.
-
-
-Annotations
-===========
-
-Changed in version 3.14: Annotations are now lazily evaluated by
-default.
-
-Variables and function parameters may carry *annotations*, created by
-adding a colon after the name, followed by an expression:
-
- x: annotation = 1
- def f(param: annotation): ...
-
-Functions may also carry a return annotation following an arrow:
-
- def f() -> annotation: ...
-
-Annotations are conventionally used for *type hints*, but this is not
-enforced by the language, and in general annotations may contain
-arbitrary expressions. The presence of annotations does not change the
-runtime semantics of the code, except if some mechanism is used that
-introspects and uses the annotations (such as "dataclasses" or
-"functools.singledispatch()").
-
-By default, annotations are lazily evaluated in a annotation scope.
-This means that they are not evaluated when the code containing the
-annotation is evaluated. Instead, the interpreter saves information
-that can be used to evaluate the annotation later if requested. The
-"annotationlib" module provides tools for evaluating annotations.
-
-If the future statement "from __future__ import annotations" is
-present, all annotations are instead stored as strings:
-
- >>> from __future__ import annotations
- >>> def f(param: annotation): ...
- >>> f.__annotations__
- {'param': 'annotation'}
-
--[ Footnotes ]-
-
-[1] The exception is propagated to the invocation stack unless there
- is a "finally" clause which happens to raise another exception.
- That new exception causes the old one to be lost.
-
-[2] In pattern matching, a sequence is defined as one of the
- following:
-
- * a class that inherits from "collections.abc.Sequence"
-
- * a Python class that has been registered as
- "collections.abc.Sequence"
-
- * a builtin class that has its (CPython) "Py_TPFLAGS_SEQUENCE" bit
- set
-
- * a class that inherits from any of the above
-
- The following standard library classes are sequences:
-
- * "array.array"
-
- * "collections.deque"
-
- * "list"
-
- * "memoryview"
-
- * "range"
-
- * "tuple"
-
- Note:
-
- Subject values of type "str", "bytes", and "bytearray" do not
- match sequence patterns.
-
-[3] In pattern matching, a mapping is defined as one of the following:
-
- * a class that inherits from "collections.abc.Mapping"
-
- * a Python class that has been registered as
- "collections.abc.Mapping"
-
- * a builtin class that has its (CPython) "Py_TPFLAGS_MAPPING" bit
- set
-
- * a class that inherits from any of the above
-
- The standard library classes "dict" and "types.MappingProxyType"
- are mappings.
-
-[4] A string literal appearing as the first statement in the function
- body is transformed into the function’s "__doc__" attribute and
- therefore the function’s *docstring*.
-
-[5] A string literal appearing as the first statement in the class
- body is transformed into the namespace’s "__doc__" item and
- therefore the class’s *docstring*.
-''',
- 'context-managers': r'''With Statement Context Managers
-*******************************
-
-A *context manager* is an object that defines the runtime context to
-be established when executing a "with" statement. The context manager
-handles the entry into, and the exit from, the desired runtime context
-for the execution of the block of code. Context managers are normally
-invoked using the "with" statement (described in section The with
-statement), but can also be used by directly invoking their methods.
-
-Typical uses of context managers include saving and restoring various
-kinds of global state, locking and unlocking resources, closing opened
-files, etc.
-
-For more information on context managers, see Context Manager Types.
-The "object" class itself does not provide the context manager
-methods.
-
-object.__enter__(self)
-
- Enter the runtime context related to this object. The "with"
- statement will bind this method’s return value to the target(s)
- specified in the "as" clause of the statement, if any.
-
-object.__exit__(self, exc_type, exc_value, traceback)
-
- Exit the runtime context related to this object. The parameters
- describe the exception that caused the context to be exited. If the
- context was exited without an exception, all three arguments will
- be "None".
-
- If an exception is supplied, and the method wishes to suppress the
- exception (i.e., prevent it from being propagated), it should
- return a true value. Otherwise, the exception will be processed
- normally upon exit from this method.
-
- Note that "__exit__()" methods should not reraise the passed-in
- exception; this is the caller’s responsibility.
-
-See also:
-
- **PEP 343** - The “with” statement
- The specification, background, and examples for the Python "with"
- statement.
-''',
- 'continue': r'''The "continue" statement
-************************
-
- **continue_stmt**: "continue"
-
-"continue" may only occur syntactically nested in a "for" or "while"
-loop, but not nested in a function or class definition within that
-loop. It continues with the next cycle of the nearest enclosing loop.
-
-When "continue" passes control out of a "try" statement with a
-"finally" clause, that "finally" clause is executed before really
-starting the next loop cycle.
-''',
- 'conversions': r'''Arithmetic conversions
-**********************
-
-When a description of an arithmetic operator below uses the phrase
-“the numeric arguments are converted to a common real type”, this
-means that the operator implementation for built-in types works as
-follows:
-
-* If both arguments are complex numbers, no conversion is performed;
-
-* if either argument is a complex or a floating-point number, the
- other is converted to a floating-point number;
-
-* otherwise, both must be integers and no conversion is necessary.
-
-Some additional rules apply for certain operators (e.g., a string as a
-left argument to the ‘%’ operator). Extensions must define their own
-conversion behavior.
-''',
- 'customization': r'''Basic customization
-*******************
-
-object.__new__(cls[, ...])
-
- Called to create a new instance of class *cls*. "__new__()" is a
- static method (special-cased so you need not declare it as such)
- that takes the class of which an instance was requested as its
- first argument. The remaining arguments are those passed to the
- object constructor expression (the call to the class). The return
- value of "__new__()" should be the new object instance (usually an
- instance of *cls*).
-
- Typical implementations create a new instance of the class by
- invoking the superclass’s "__new__()" method using
- "super().__new__(cls[, ...])" with appropriate arguments and then
- modifying the newly created instance as necessary before returning
- it.
-
- If "__new__()" is invoked during object construction and it returns
- an instance of *cls*, then the new instance’s "__init__()" method
- will be invoked like "__init__(self[, ...])", where *self* is the
- new instance and the remaining arguments are the same as were
- passed to the object constructor.
-
- If "__new__()" does not return an instance of *cls*, then the new
- instance’s "__init__()" method will not be invoked.
-
- "__new__()" is intended mainly to allow subclasses of immutable
- types (like int, str, or tuple) to customize instance creation. It
- is also commonly overridden in custom metaclasses in order to
- customize class creation.
-
-object.__init__(self[, ...])
-
- Called after the instance has been created (by "__new__()"), but
- before it is returned to the caller. The arguments are those
- passed to the class constructor expression. If a base class has an
- "__init__()" method, the derived class’s "__init__()" method, if
- any, must explicitly call it to ensure proper initialization of the
- base class part of the instance; for example:
- "super().__init__([args...])".
-
- Because "__new__()" and "__init__()" work together in constructing
- objects ("__new__()" to create it, and "__init__()" to customize
- it), no non-"None" value may be returned by "__init__()"; doing so
- will cause a "TypeError" to be raised at runtime.
-
-object.__del__(self)
-
- Called when the instance is about to be destroyed. This is also
- called a finalizer or (improperly) a destructor. If a base class
- has a "__del__()" method, the derived class’s "__del__()" method,
- if any, must explicitly call it to ensure proper deletion of the
- base class part of the instance.
-
- It is possible (though not recommended!) for the "__del__()" method
- to postpone destruction of the instance by creating a new reference
- to it. This is called object *resurrection*. It is
- implementation-dependent whether "__del__()" is called a second
- time when a resurrected object is about to be destroyed; the
- current *CPython* implementation only calls it once.
-
- It is not guaranteed that "__del__()" methods are called for
- objects that still exist when the interpreter exits.
- "weakref.finalize" provides a straightforward way to register a
- cleanup function to be called when an object is garbage collected.
-
- Note:
-
- "del x" doesn’t directly call "x.__del__()" — the former
- decrements the reference count for "x" by one, and the latter is
- only called when "x"’s reference count reaches zero.
-
- **CPython implementation detail:** It is possible for a reference
- cycle to prevent the reference count of an object from going to
- zero. In this case, the cycle will be later detected and deleted
- by the *cyclic garbage collector*. A common cause of reference
- cycles is when an exception has been caught in a local variable.
- The frame’s locals then reference the exception, which references
- its own traceback, which references the locals of all frames caught
- in the traceback.
-
- See also: Documentation for the "gc" module.
-
- Warning:
-
- Due to the precarious circumstances under which "__del__()"
- methods are invoked, exceptions that occur during their execution
- are ignored, and a warning is printed to "sys.stderr" instead.
- In particular:
-
- * "__del__()" can be invoked when arbitrary code is being
- executed, including from any arbitrary thread. If "__del__()"
- needs to take a lock or invoke any other blocking resource, it
- may deadlock as the resource may already be taken by the code
- that gets interrupted to execute "__del__()".
-
- * "__del__()" can be executed during interpreter shutdown. As a
- consequence, the global variables it needs to access (including
- other modules) may already have been deleted or set to "None".
- Python guarantees that globals whose name begins with a single
- underscore are deleted from their module before other globals
- are deleted; if no other references to such globals exist, this
- may help in assuring that imported modules are still available
- at the time when the "__del__()" method is called.
-
-object.__repr__(self)
-
- Called by the "repr()" built-in function to compute the “official”
- string representation of an object. If at all possible, this
- should look like a valid Python expression that could be used to
- recreate an object with the same value (given an appropriate
- environment). If this is not possible, a string of the form
- "<...some useful description...>" should be returned. The return
- value must be a string object. If a class defines "__repr__()" but
- not "__str__()", then "__repr__()" is also used when an “informal”
- string representation of instances of that class is required.
-
- This is typically used for debugging, so it is important that the
- representation is information-rich and unambiguous. A default
- implementation is provided by the "object" class itself.
-
-object.__str__(self)
-
- Called by "str(object)", the default "__format__()" implementation,
- and the built-in function "print()", to compute the “informal” or
- nicely printable string representation of an object. The return
- value must be a str object.
-
- This method differs from "object.__repr__()" in that there is no
- expectation that "__str__()" return a valid Python expression: a
- more convenient or concise representation can be used.
-
- The default implementation defined by the built-in type "object"
- calls "object.__repr__()".
-
-object.__bytes__(self)
-
- Called by bytes to compute a byte-string representation of an
- object. This should return a "bytes" object. The "object" class
- itself does not provide this method.
-
-object.__format__(self, format_spec)
-
- Called by the "format()" built-in function, and by extension,
- evaluation of formatted string literals and the "str.format()"
- method, to produce a “formatted” string representation of an
- object. The *format_spec* argument is a string that contains a
- description of the formatting options desired. The interpretation
- of the *format_spec* argument is up to the type implementing
- "__format__()", however most classes will either delegate
- formatting to one of the built-in types, or use a similar
- formatting option syntax.
-
- See Format Specification Mini-Language for a description of the
- standard formatting syntax.
-
- The return value must be a string object.
-
- The default implementation by the "object" class should be given an
- empty *format_spec* string. It delegates to "__str__()".
-
- Changed in version 3.4: The __format__ method of "object" itself
- raises a "TypeError" if passed any non-empty string.
-
- Changed in version 3.7: "object.__format__(x, '')" is now
- equivalent to "str(x)" rather than "format(str(x), '')".
-
-object.__lt__(self, other)
-object.__le__(self, other)
-object.__eq__(self, other)
-object.__ne__(self, other)
-object.__gt__(self, other)
-object.__ge__(self, other)
-
- These are the so-called “rich comparison” methods. The
- correspondence between operator symbols and method names is as
- follows: "x<y" calls "x.__lt__(y)", "x<=y" calls "x.__le__(y)",
- "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", "x>y" calls
- "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".
-
- A rich comparison method may return the singleton "NotImplemented"
- if it does not implement the operation for a given pair of
- arguments. By convention, "False" and "True" are returned for a
- successful comparison. However, these methods can return any value,
- so if the comparison operator is used in a Boolean context (e.g.,
- in the condition of an "if" statement), Python will call "bool()"
- on the value to determine if the result is true or false.
-
- By default, "object" implements "__eq__()" by using "is", returning
- "NotImplemented" in the case of a false comparison: "True if x is y
- else NotImplemented". For "__ne__()", by default it delegates to
- "__eq__()" and inverts the result unless it is "NotImplemented".
- There are no other implied relationships among the comparison
- operators or default implementations; for example, the truth of
- "(x<y or x==y)" does not imply "x<=y". To automatically generate
- ordering operations from a single root operation, see
- "functools.total_ordering()".
-
- By default, the "object" class provides implementations consistent
- with Value comparisons: equality compares according to object
- identity, and order comparisons raise "TypeError". Each default
- method may generate these results directly, but may also return
- "NotImplemented".
-
- See the paragraph on "__hash__()" for some important notes on
- creating *hashable* objects which support custom comparison
- operations and are usable as dictionary keys.
-
- There are no swapped-argument versions of these methods (to be used
- when the left argument does not support the operation but the right
- argument does); rather, "__lt__()" and "__gt__()" are each other’s
- reflection, "__le__()" and "__ge__()" are each other’s reflection,
- and "__eq__()" and "__ne__()" are their own reflection. If the
- operands are of different types, and the right operand’s type is a
- direct or indirect subclass of the left operand’s type, the
- reflected method of the right operand has priority, otherwise the
- left operand’s method has priority. Virtual subclassing is not
- considered.
-
- When no appropriate method returns any value other than
- "NotImplemented", the "==" and "!=" operators will fall back to
- "is" and "is not", respectively.
-
-object.__hash__(self)
-
- Called by built-in function "hash()" and for operations on members
- of hashed collections including "set", "frozenset", and "dict".
- The "__hash__()" method should return an integer. The only required
- property is that objects which compare equal have the same hash
- value; it is advised to mix together the hash values of the
- components of the object that also play a part in comparison of
- objects by packing them into a tuple and hashing the tuple.
- Example:
-
- def __hash__(self):
- return hash((self.name, self.nick, self.color))
-
- Note:
-
- "hash()" truncates the value returned from an object’s custom
- "__hash__()" method to the size of a "Py_ssize_t". This is
- typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds.
- If an object’s "__hash__()" must interoperate on builds of
- different bit sizes, be sure to check the width on all supported
- builds. An easy way to do this is with "python -c "import sys;
- print(sys.hash_info.width)"".
-
- If a class does not define an "__eq__()" method it should not
- define a "__hash__()" operation either; if it defines "__eq__()"
- but not "__hash__()", its instances will not be usable as items in
- hashable collections. If a class defines mutable objects and
- implements an "__eq__()" method, it should not implement
- "__hash__()", since the implementation of *hashable* collections
- requires that a key’s hash value is immutable (if the object’s hash
- value changes, it will be in the wrong hash bucket).
-
- User-defined classes have "__eq__()" and "__hash__()" methods by
- default (inherited from the "object" class); with them, all objects
- compare unequal (except with themselves) and "x.__hash__()" returns
- an appropriate value such that "x == y" implies both that "x is y"
- and "hash(x) == hash(y)".
-
- A class that overrides "__eq__()" and does not define "__hash__()"
- will have its "__hash__()" implicitly set to "None". When the
- "__hash__()" method of a class is "None", instances of the class
- will raise an appropriate "TypeError" when a program attempts to
- retrieve their hash value, and will also be correctly identified as
- unhashable when checking "isinstance(obj,
- collections.abc.Hashable)".
-
- If a class that overrides "__eq__()" needs to retain the
- implementation of "__hash__()" from a parent class, the interpreter
- must be told this explicitly by setting "__hash__ =
- <ParentClass>.__hash__".
-
- If a class that does not override "__eq__()" wishes to suppress
- hash support, it should include "__hash__ = None" in the class
- definition. A class which defines its own "__hash__()" that
- explicitly raises a "TypeError" would be incorrectly identified as
- hashable by an "isinstance(obj, collections.abc.Hashable)" call.
-
- Note:
-
- By default, the "__hash__()" values of str and bytes objects are
- “salted” with an unpredictable random value. Although they
- remain constant within an individual Python process, they are not
- predictable between repeated invocations of Python.This is
- intended to provide protection against a denial-of-service caused
- by carefully chosen inputs that exploit the worst case
- performance of a dict insertion, *O*(*n*^2) complexity. See
- http://ocert.org/advisories/ocert-2011-003.html for
- details.Changing hash values affects the iteration order of sets.
- Python has never made guarantees about this ordering (and it
- typically varies between 32-bit and 64-bit builds).See also
- "PYTHONHASHSEED".
-
- Changed in version 3.3: Hash randomization is enabled by default.
-
-object.__bool__(self)
-
- Called to implement truth value testing and the built-in operation
- "bool()"; should return "False" or "True". When this method is not
- defined, "__len__()" is called, if it is defined, and the object is
- considered true if its result is nonzero. If a class defines
- neither "__len__()" nor "__bool__()" (which is true of the "object"
- class itself), all its instances are considered true.
-''',
- 'debugger': r'''"pdb" — The Python Debugger
-***************************
-
-**Source code:** Lib/pdb.py
-
-======================================================================
-
-The module "pdb" defines an interactive source code debugger for
-Python programs. It supports setting (conditional) breakpoints and
-single stepping at the source line level, inspection of stack frames,
-source code listing, and evaluation of arbitrary Python code in the
-context of any stack frame. It also supports post-mortem debugging
-and can be called under program control.
-
-The debugger is extensible – it is actually defined as the class
-"Pdb". This is currently undocumented but easily understood by reading
-the source. The extension interface uses the modules "bdb" and "cmd".
-
-See also:
-
- Module "faulthandler"
- Used to dump Python tracebacks explicitly, on a fault, after a
- timeout, or on a user signal.
-
- Module "traceback"
- Standard interface to extract, format and print stack traces of
- Python programs.
-
-The typical usage to break into the debugger is to insert:
-
- import pdb; pdb.set_trace()
-
-Or:
-
- breakpoint()
-
-at the location you want to break into the debugger, and then run the
-program. You can then step through the code following this statement,
-and continue running without the debugger using the "continue"
-command.
-
-Changed in version 3.7: The built-in "breakpoint()", when called with
-defaults, can be used instead of "import pdb; pdb.set_trace()".
-
- def double(x):
- breakpoint()
- return x * 2
- val = 3
- print(f"{val} * 2 is {double(val)}")
-
-The debugger’s prompt is "(Pdb)", which is the indicator that you are
-in debug mode:
-
- > ...(2)double()
- -> breakpoint()
- (Pdb) p x
- 3
- (Pdb) continue
- 3 * 2 is 6
-
-Changed in version 3.3: Tab-completion via the "readline" module is
-available for commands and command arguments, e.g. the current global
-and local names are offered as arguments of the "p" command.
-
-You can also invoke "pdb" from the command line to debug other
-scripts. For example:
-
- python -m pdb myscript.py
-
-When invoked as a module, pdb will automatically enter post-mortem
-debugging if the program being debugged exits abnormally. After post-
-mortem debugging (or after normal exit of the program), pdb will
-restart the program. Automatic restarting preserves pdb’s state (such
-as breakpoints) and in most cases is more useful than quitting the
-debugger upon program’s exit.
-
-Changed in version 3.2: Added the "-c" option to execute commands as
-if given in a ".pdbrc" file; see Debugger Commands.
-
-Changed in version 3.7: Added the "-m" option to execute modules
-similar to the way "python -m" does. As with a script, the debugger
-will pause execution just before the first line of the module.
-
-Typical usage to execute a statement under control of the debugger is:
-
- >>> import pdb
- >>> def f(x):
- ... print(1 / x)
- >>> pdb.run("f(2)")
- > <string>(1)<module>()
- (Pdb) continue
- 0.5
- >>>
-
-The typical usage to inspect a crashed program is:
-
- >>> import pdb
- >>> def f(x):
- ... print(1 / x)
- ...
- >>> f(0)
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- File "<stdin>", line 2, in f
- ZeroDivisionError: division by zero
- >>> pdb.pm()
- > <stdin>(2)f()
- (Pdb) p x
- 0
- (Pdb)
-
-Changed in version 3.13: The implementation of **PEP 667** means that
-name assignments made via "pdb" will immediately affect the active
-scope, even when running inside an *optimized scope*.
-
-The module defines the following functions; each enters the debugger
-in a slightly different way:
-
-pdb.run(statement, globals=None, locals=None)
-
- Execute the *statement* (given as a string or a code object) under
- debugger control. The debugger prompt appears before any code is
- executed; you can set breakpoints and type "continue", or you can
- step through the statement using "step" or "next" (all these
- commands are explained below). The optional *globals* and *locals*
- arguments specify the environment in which the code is executed; by
- default the dictionary of the module "__main__" is used. (See the
- explanation of the built-in "exec()" or "eval()" functions.)
-
-pdb.runeval(expression, globals=None, locals=None)
-
- Evaluate the *expression* (given as a string or a code object)
- under debugger control. When "runeval()" returns, it returns the
- value of the *expression*. Otherwise this function is similar to
- "run()".
-
-pdb.runcall(function, *args, **kwds)
-
- Call the *function* (a function or method object, not a string)
- with the given arguments. When "runcall()" returns, it returns
- whatever the function call returned. The debugger prompt appears
- as soon as the function is entered.
-
-pdb.set_trace(*, header=None, commands=None)
-
- Enter the debugger at the calling stack frame. This is useful to
- hard-code a breakpoint at a given point in a program, even if the
- code is not otherwise being debugged (e.g. when an assertion
- fails). If given, *header* is printed to the console just before
- debugging begins. The *commands* argument, if given, is a list of
- commands to execute when the debugger starts.
-
- Changed in version 3.7: The keyword-only argument *header*.
-
- Changed in version 3.13: "set_trace()" will enter the debugger
- immediately, rather than on the next line of code to be executed.
-
- Added in version 3.14: The *commands* argument.
-
-pdb.post_mortem(t=None)
-
- Enter post-mortem debugging of the given exception or traceback
- object. If no value is given, it uses the exception that is
- currently being handled, or raises "ValueError" if there isn’t one.
-
- Changed in version 3.13: Support for exception objects was added.
-
-pdb.pm()
-
- Enter post-mortem debugging of the exception found in
- "sys.last_exc".
-
-The "run*" functions and "set_trace()" are aliases for instantiating
-the "Pdb" class and calling the method of the same name. If you want
-to access further features, you have to do this yourself:
-
-class pdb.Pdb(completekey='tab', stdin=None, stdout=None, skip=None, nosigint=False, readrc=True, mode=None)
-
- "Pdb" is the debugger class.
-
- The *completekey*, *stdin* and *stdout* arguments are passed to the
- underlying "cmd.Cmd" class; see the description there.
-
- The *skip* argument, if given, must be an iterable of glob-style
- module name patterns. The debugger will not step into frames that
- originate in a module that matches one of these patterns. [1]
-
- By default, Pdb sets a handler for the SIGINT signal (which is sent
- when the user presses "Ctrl-C" on the console) when you give a
- "continue" command. This allows you to break into the debugger
- again by pressing "Ctrl-C". If you want Pdb not to touch the
- SIGINT handler, set *nosigint* to true.
-
- The *readrc* argument defaults to true and controls whether Pdb
- will load .pdbrc files from the filesystem.
-
- The *mode* argument specifies how the debugger was invoked. It
- impacts the workings of some debugger commands. Valid values are
- "'inline'" (used by the breakpoint() builtin), "'cli'" (used by the
- command line invocation) or "None" (for backwards compatible
- behaviour, as before the *mode* argument was added).
-
- Example call to enable tracing with *skip*:
-
- import pdb; pdb.Pdb(skip=['django.*']).set_trace()
-
- Raises an auditing event "pdb.Pdb" with no arguments.
-
- Changed in version 3.1: Added the *skip* parameter.
-
- Changed in version 3.2: Added the *nosigint* parameter. Previously,
- a SIGINT handler was never set by Pdb.
-
- Changed in version 3.6: The *readrc* argument.
-
- Added in version 3.14: Added the *mode* argument.
-
- run(statement, globals=None, locals=None)
- runeval(expression, globals=None, locals=None)
- runcall(function, *args, **kwds)
- set_trace()
-
- See the documentation for the functions explained above.
-
-
-Debugger Commands
-=================
-
-The commands recognized by the debugger are listed below. Most
-commands can be abbreviated to one or two letters as indicated; e.g.
-"h(elp)" means that either "h" or "help" can be used to enter the help
-command (but not "he" or "hel", nor "H" or "Help" or "HELP").
-Arguments to commands must be separated by whitespace (spaces or
-tabs). Optional arguments are enclosed in square brackets ("[]") in
-the command syntax; the square brackets must not be typed.
-Alternatives in the command syntax are separated by a vertical bar
-("|").
-
-Entering a blank line repeats the last command entered. Exception: if
-the last command was a "list" command, the next 11 lines are listed.
-
-Commands that the debugger doesn’t recognize are assumed to be Python
-statements and are executed in the context of the program being
-debugged. Python statements can also be prefixed with an exclamation
-point ("!"). This is a powerful way to inspect the program being
-debugged; it is even possible to change a variable or call a function.
-When an exception occurs in such a statement, the exception name is
-printed but the debugger’s state is not changed.
-
-Changed in version 3.13: Expressions/Statements whose prefix is a pdb
-command are now correctly identified and executed.
-
-The debugger supports aliases. Aliases can have parameters which
-allows one a certain level of adaptability to the context under
-examination.
-
-Multiple commands may be entered on a single line, separated by ";;".
-(A single ";" is not used as it is the separator for multiple commands
-in a line that is passed to the Python parser.) No intelligence is
-applied to separating the commands; the input is split at the first
-";;" pair, even if it is in the middle of a quoted string. A
-workaround for strings with double semicolons is to use implicit
-string concatenation "';'';'" or "";"";"".
-
-To set a temporary global variable, use a *convenience variable*. A
-*convenience variable* is a variable whose name starts with "$". For
-example, "$foo = 1" sets a global variable "$foo" which you can use in
-the debugger session. The *convenience variables* are cleared when
-the program resumes execution so it’s less likely to interfere with
-your program compared to using normal variables like "foo = 1".
-
-There are three preset *convenience variables*:
-
-* "$_frame": the current frame you are debugging
-
-* "$_retval": the return value if the frame is returning
-
-* "$_exception": the exception if the frame is raising an exception
-
-Added in version 3.12: Added the *convenience variable* feature.
-
-If a file ".pdbrc" exists in the user’s home directory or in the
-current directory, it is read with "'utf-8'" encoding and executed as
-if it had been typed at the debugger prompt, with the exception that
-empty lines and lines starting with "#" are ignored. This is
-particularly useful for aliases. If both files exist, the one in the
-home directory is read first and aliases defined there can be
-overridden by the local file.
-
-Changed in version 3.2: ".pdbrc" can now contain commands that
-continue debugging, such as "continue" or "next". Previously, these
-commands had no effect.
-
-Changed in version 3.11: ".pdbrc" is now read with "'utf-8'" encoding.
-Previously, it was read with the system locale encoding.
-
-h(elp) [command]
-
- Without argument, print the list of available commands. With a
- *command* as argument, print help about that command. "help pdb"
- displays the full documentation (the docstring of the "pdb"
- module). Since the *command* argument must be an identifier, "help
- exec" must be entered to get help on the "!" command.
-
-w(here) [count]
-
- Print a stack trace, with the most recent frame at the bottom. if
- *count* is 0, print the current frame entry. If *count* is
- negative, print the least recent - *count* frames. If *count* is
- positive, print the most recent *count* frames. An arrow (">")
- indicates the current frame, which determines the context of most
- commands.
-
- Changed in version 3.14: *count* argument is added.
-
-d(own) [count]
-
- Move the current frame *count* (default one) levels down in the
- stack trace (to a newer frame).
-
-u(p) [count]
-
- Move the current frame *count* (default one) levels up in the stack
- trace (to an older frame).
-
-b(reak) [([filename:]lineno | function) [, condition]]
-
- With a *lineno* argument, set a break at line *lineno* in the
- current file. The line number may be prefixed with a *filename* and
- a colon, to specify a breakpoint in another file (possibly one that
- hasn’t been loaded yet). The file is searched on "sys.path".
- Acceptable forms of *filename* are "/abspath/to/file.py",
- "relpath/file.py", "module" and "package.module".
-
- With a *function* argument, set a break at the first executable
- statement within that function. *function* can be any expression
- that evaluates to a function in the current namespace.
-
- If a second argument is present, it is an expression which must
- evaluate to true before the breakpoint is honored.
-
- Without argument, list all breaks, including for each breakpoint,
- the number of times that breakpoint has been hit, the current
- ignore count, and the associated condition if any.
-
- Each breakpoint is assigned a number to which all the other
- breakpoint commands refer.
-
-tbreak [([filename:]lineno | function) [, condition]]
-
- Temporary breakpoint, which is removed automatically when it is
- first hit. The arguments are the same as for "break".
-
-cl(ear) [filename:lineno | bpnumber ...]
-
- With a *filename:lineno* argument, clear all the breakpoints at
- this line. With a space separated list of breakpoint numbers, clear
- those breakpoints. Without argument, clear all breaks (but first
- ask confirmation).
-
-disable bpnumber [bpnumber ...]
-
- Disable the breakpoints given as a space separated list of
- breakpoint numbers. Disabling a breakpoint means it cannot cause
- the program to stop execution, but unlike clearing a breakpoint, it
- remains in the list of breakpoints and can be (re-)enabled.
-
-enable bpnumber [bpnumber ...]
-
- Enable the breakpoints specified.
-
-ignore bpnumber [count]
-
- Set the ignore count for the given breakpoint number. If *count*
- is omitted, the ignore count is set to 0. A breakpoint becomes
- active when the ignore count is zero. When non-zero, the *count*
- is decremented each time the breakpoint is reached and the
- breakpoint is not disabled and any associated condition evaluates
- to true.
-
-condition bpnumber [condition]
-
- Set a new *condition* for the breakpoint, an expression which must
- evaluate to true before the breakpoint is honored. If *condition*
- is absent, any existing condition is removed; i.e., the breakpoint
- is made unconditional.
-
-commands [bpnumber]
-
- Specify a list of commands for breakpoint number *bpnumber*. The
- commands themselves appear on the following lines. Type a line
- containing just "end" to terminate the commands. An example:
-
- (Pdb) commands 1
- (com) p some_variable
- (com) end
- (Pdb)
-
- To remove all commands from a breakpoint, type "commands" and
- follow it immediately with "end"; that is, give no commands.
-
- With no *bpnumber* argument, "commands" refers to the last
- breakpoint set.
-
- You can use breakpoint commands to start your program up again.
- Simply use the "continue" command, or "step", or any other command
- that resumes execution.
-
- Specifying any command resuming execution (currently "continue",
- "step", "next", "return", "until", "jump", "quit" and their
- abbreviations) terminates the command list (as if that command was
- immediately followed by end). This is because any time you resume
- execution (even with a simple next or step), you may encounter
- another breakpoint—which could have its own command list, leading
- to ambiguities about which list to execute.
-
- If the list of commands contains the "silent" command, or a command
- that resumes execution, then the breakpoint message containing
- information about the frame is not displayed.
-
- Changed in version 3.14: Frame information will not be displayed if
- a command that resumes execution is present in the command list.
-
-s(tep)
-
- Execute the current line, stop at the first possible occasion
- (either in a function that is called or on the next line in the
- current function).
-
-n(ext)
-
- Continue execution until the next line in the current function is
- reached or it returns. (The difference between "next" and "step"
- is that "step" stops inside a called function, while "next"
- executes called functions at (nearly) full speed, only stopping at
- the next line in the current function.)
-
-unt(il) [lineno]
-
- Without argument, continue execution until the line with a number
- greater than the current one is reached.
-
- With *lineno*, continue execution until a line with a number
- greater or equal to *lineno* is reached. In both cases, also stop
- when the current frame returns.
-
- Changed in version 3.2: Allow giving an explicit line number.
-
-r(eturn)
-
- Continue execution until the current function returns.
-
-c(ont(inue))
-
- Continue execution, only stop when a breakpoint is encountered.
-
-j(ump) lineno
-
- Set the next line that will be executed. Only available in the
- bottom-most frame. This lets you jump back and execute code again,
- or jump forward to skip code that you don’t want to run.
-
- It should be noted that not all jumps are allowed – for instance it
- is not possible to jump into the middle of a "for" loop or out of a
- "finally" clause.
-
-l(ist) [first[, last]]
-
- List source code for the current file. Without arguments, list 11
- lines around the current line or continue the previous listing.
- With "." as argument, list 11 lines around the current line. With
- one argument, list 11 lines around at that line. With two
- arguments, list the given range; if the second argument is less
- than the first, it is interpreted as a count.
-
- The current line in the current frame is indicated by "->". If an
- exception is being debugged, the line where the exception was
- originally raised or propagated is indicated by ">>", if it differs
- from the current line.
-
- Changed in version 3.2: Added the ">>" marker.
-
-ll | longlist
-
- List all source code for the current function or frame.
- Interesting lines are marked as for "list".
-
- Added in version 3.2.
-
-a(rgs)
-
- Print the arguments of the current function and their current
- values.
-
-p expression
-
- Evaluate *expression* in the current context and print its value.
-
- Note:
-
- "print()" can also be used, but is not a debugger command — this
- executes the Python "print()" function.
-
-pp expression
-
- Like the "p" command, except the value of *expression* is pretty-
- printed using the "pprint" module.
-
-whatis expression
-
- Print the type of *expression*.
-
-source expression
-
- Try to get source code of *expression* and display it.
-
- Added in version 3.2.
-
-display [expression]
-
- Display the value of *expression* if it changed, each time
- execution stops in the current frame.
-
- Without *expression*, list all display expressions for the current
- frame.
-
- Note:
-
- Display evaluates *expression* and compares to the result of the
- previous evaluation of *expression*, so when the result is
- mutable, display may not be able to pick up the changes.
-
- Example:
-
- lst = []
- breakpoint()
- pass
- lst.append(1)
- print(lst)
-
- Display won’t realize "lst" has been changed because the result of
- evaluation is modified in place by "lst.append(1)" before being
- compared:
-
- > example.py(3)<module>()
- -> pass
- (Pdb) display lst
- display lst: []
- (Pdb) n
- > example.py(4)<module>()
- -> lst.append(1)
- (Pdb) n
- > example.py(5)<module>()
- -> print(lst)
- (Pdb)
-
- You can do some tricks with copy mechanism to make it work:
-
- > example.py(3)<module>()
- -> pass
- (Pdb) display lst[:]
- display lst[:]: []
- (Pdb) n
- > example.py(4)<module>()
- -> lst.append(1)
- (Pdb) n
- > example.py(5)<module>()
- -> print(lst)
- display lst[:]: [1] [old: []]
- (Pdb)
-
- Added in version 3.2.
-
-undisplay [expression]
-
- Do not display *expression* anymore in the current frame. Without
- *expression*, clear all display expressions for the current frame.
-
- Added in version 3.2.
-
-interact
-
- Start an interactive interpreter (using the "code" module) in a new
- global namespace initialised from the local and global namespaces
- for the current scope. Use "exit()" or "quit()" to exit the
- interpreter and return to the debugger.
-
- Note:
-
- As "interact" creates a new dedicated namespace for code
- execution, assignments to variables will not affect the original
- namespaces. However, modifications to any referenced mutable
- objects will be reflected in the original namespaces as usual.
-
- Added in version 3.2.
-
- Changed in version 3.13: "exit()" and "quit()" can be used to exit
- the "interact" command.
-
- Changed in version 3.13: "interact" directs its output to the
- debugger’s output channel rather than "sys.stderr".
-
-alias [name [command]]
-
- Create an alias called *name* that executes *command*. The
- *command* must *not* be enclosed in quotes. Replaceable parameters
- can be indicated by "%1", "%2", … and "%9", while "%*" is replaced
- by all the parameters. If *command* is omitted, the current alias
- for *name* is shown. If no arguments are given, all aliases are
- listed.
-
- Aliases may be nested and can contain anything that can be legally
- typed at the pdb prompt. Note that internal pdb commands *can* be
- overridden by aliases. Such a command is then hidden until the
- alias is removed. Aliasing is recursively applied to the first
- word of the command line; all other words in the line are left
- alone.
-
- As an example, here are two useful aliases (especially when placed
- in the ".pdbrc" file):
-
- # Print instance variables (usage "pi classInst")
- alias pi for k in %1.__dict__.keys(): print(f"%1.{k} = {%1.__dict__[k]}")
- # Print instance variables in self
- alias ps pi self
-
-unalias name
-
- Delete the specified alias *name*.
-
-! statement
-
- Execute the (one-line) *statement* in the context of the current
- stack frame. The exclamation point can be omitted unless the first
- word of the statement resembles a debugger command, e.g.:
-
- (Pdb) ! n=42
- (Pdb)
-
- To set a global variable, you can prefix the assignment command
- with a "global" statement on the same line, e.g.:
-
- (Pdb) global list_options; list_options = ['-l']
- (Pdb)
-
-run [args ...]
-restart [args ...]
-
- Restart the debugged Python program. If *args* is supplied, it is
- split with "shlex" and the result is used as the new "sys.argv".
- History, breakpoints, actions and debugger options are preserved.
- "restart" is an alias for "run".
-
- Changed in version 3.14: "run" and "restart" commands are disabled
- when the debugger is invoked in "'inline'" mode.
-
-q(uit)
-
- Quit from the debugger. The program being executed is aborted. An
- end-of-file input is equivalent to "quit".
-
- A confirmation prompt will be shown if the debugger is invoked in
- "'inline'" mode. Either "y", "Y", "<Enter>" or "EOF" will confirm
- the quit.
-
- Changed in version 3.14: A confirmation prompt will be shown if the
- debugger is invoked in "'inline'" mode. After the confirmation, the
- debugger will call "sys.exit()" immediately, instead of raising
- "bdb.BdbQuit" in the next trace event.
-
-debug code
-
- Enter a recursive debugger that steps through *code* (which is an
- arbitrary expression or statement to be executed in the current
- environment).
-
-retval
-
- Print the return value for the last return of the current function.
-
-exceptions [excnumber]
-
- List or jump between chained exceptions.
-
- When using "pdb.pm()" or "Pdb.post_mortem(...)" with a chained
- exception instead of a traceback, it allows the user to move
- between the chained exceptions using "exceptions" command to list
- exceptions, and "exception <number>" to switch to that exception.
-
- Example:
-
- def out():
- try:
- middle()
- except Exception as e:
- raise ValueError("reraise middle() error") from e
-
- def middle():
- try:
- return inner(0)
- except Exception as e:
- raise ValueError("Middle fail")
-
- def inner(x):
- 1 / x
-
- out()
-
- calling "pdb.pm()" will allow to move between exceptions:
-
- > example.py(5)out()
- -> raise ValueError("reraise middle() error") from e
-
- (Pdb) exceptions
- 0 ZeroDivisionError('division by zero')
- 1 ValueError('Middle fail')
- > 2 ValueError('reraise middle() error')
-
- (Pdb) exceptions 0
- > example.py(16)inner()
- -> 1 / x
-
- (Pdb) up
- > example.py(10)middle()
- -> return inner(0)
-
- Added in version 3.13.
-
--[ Footnotes ]-
-
-[1] Whether a frame is considered to originate in a certain module is
- determined by the "__name__" in the frame globals.
-''',
- 'del': r'''The "del" statement
-*******************
-
- **del_stmt**: "del" "target_list"
-
-Deletion is recursively defined very similar to the way assignment is
-defined. Rather than spelling it out in full details, here are some
-hints.
-
-Deletion of a target list recursively deletes each target, from left
-to right.
-
-Deletion of a name removes the binding of that name from the local or
-global namespace, depending on whether the name occurs in a "global"
-statement in the same code block. If the name is unbound, a
-"NameError" exception will be raised.
-
-Deletion of attribute references, subscriptions and slicings is passed
-to the primary object involved; deletion of a slicing is in general
-equivalent to assignment of an empty slice of the right type (but even
-this is determined by the sliced object).
-
-Changed in version 3.2: Previously it was illegal to delete a name
-from the local namespace if it occurs as a free variable in a nested
-block.
-''',
- 'dict': r'''Dictionary displays
-*******************
-
-A dictionary display is a possibly empty series of dict items
-(key/value pairs) enclosed in curly braces:
-
- **dict_display**: "{" ["dict_item_list" | "dict_comprehension"] "}"
- **dict_item_list**: "dict_item" ("," "dict_item")* [","]
- **dict_item**: "expression" ":" "expression" | "**" "or_expr"
- **dict_comprehension**: "expression" ":" "expression" "comp_for"
-
-A dictionary display yields a new dictionary object.
-
-If a comma-separated sequence of dict items is given, they are
-evaluated from left to right to define the entries of the dictionary:
-each key object is used as a key into the dictionary to store the
-corresponding value. This means that you can specify the same key
-multiple times in the dict item list, and the final dictionary’s value
-for that key will be the last one given.
-
-A double asterisk "**" denotes *dictionary unpacking*. Its operand
-must be a *mapping*. Each mapping item is added to the new
-dictionary. Later values replace values already set by earlier dict
-items and earlier dictionary unpackings.
-
-Added in version 3.5: Unpacking into dictionary displays, originally
-proposed by **PEP 448**.
-
-A dict comprehension, in contrast to list and set comprehensions,
-needs two expressions separated with a colon followed by the usual
-“for” and “if” clauses. When the comprehension is run, the resulting
-key and value elements are inserted in the new dictionary in the order
-they are produced.
-
-Restrictions on the types of the key values are listed earlier in
-section The standard type hierarchy. (To summarize, the key type
-should be *hashable*, which excludes all mutable objects.) Clashes
-between duplicate keys are not detected; the last value (textually
-rightmost in the display) stored for a given key value prevails.
-
-Changed in version 3.8: Prior to Python 3.8, in dict comprehensions,
-the evaluation order of key and value was not well-defined. In
-CPython, the value was evaluated before the key. Starting with 3.8,
-the key is evaluated before the value, as proposed by **PEP 572**.
-''',
- 'dynamic-features': r'''Interaction with dynamic features
-*********************************
-
-Name resolution of free variables occurs at runtime, not at compile
-time. This means that the following code will print 42:
-
- i = 10
- def f():
- print(i)
- i = 42
- f()
-
-The "eval()" and "exec()" functions do not have access to the full
-environment for resolving names. Names may be resolved in the local
-and global namespaces of the caller. Free variables are not resolved
-in the nearest enclosing namespace, but in the global namespace. [1]
-The "exec()" and "eval()" functions have optional arguments to
-override the global and local namespace. If only one namespace is
-specified, it is used for both.
-''',
- 'else': r'''The "if" statement
-******************
-
-The "if" statement is used for conditional execution:
-
- **if_stmt**: "if" "assignment_expression" ":" "suite"
- ("elif" "assignment_expression" ":" "suite")*
- ["else" ":" "suite"]
-
-It selects exactly one of the suites by evaluating the expressions one
-by one until one is found to be true (see section Boolean operations
-for the definition of true and false); then that suite is executed
-(and no other part of the "if" statement is executed or evaluated).
-If all expressions are false, the suite of the "else" clause, if
-present, is executed.
-''',
- 'exceptions': r'''Exceptions
-**********
-
-Exceptions are a means of breaking out of the normal flow of control
-of a code block in order to handle errors or other exceptional
-conditions. An exception is *raised* at the point where the error is
-detected; it may be *handled* by the surrounding code block or by any
-code block that directly or indirectly invoked the code block where
-the error occurred.
-
-The Python interpreter raises an exception when it detects a run-time
-error (such as division by zero). A Python program can also
-explicitly raise an exception with the "raise" statement. Exception
-handlers are specified with the "try" … "except" statement. The
-"finally" clause of such a statement can be used to specify cleanup
-code which does not handle the exception, but is executed whether an
-exception occurred or not in the preceding code.
-
-Python uses the “termination” model of error handling: an exception
-handler can find out what happened and continue execution at an outer
-level, but it cannot repair the cause of the error and retry the
-failing operation (except by re-entering the offending piece of code
-from the top).
-
-When an exception is not handled at all, the interpreter terminates
-execution of the program, or returns to its interactive main loop. In
-either case, it prints a stack traceback, except when the exception is
-"SystemExit".
-
-Exceptions are identified by class instances. The "except" clause is
-selected depending on the class of the instance: it must reference the
-class of the instance or a *non-virtual base class* thereof. The
-instance can be received by the handler and can carry additional
-information about the exceptional condition.
-
-Note:
-
- Exception messages are not part of the Python API. Their contents
- may change from one version of Python to the next without warning
- and should not be relied on by code which will run under multiple
- versions of the interpreter.
-
-See also the description of the "try" statement in section The try
-statement and "raise" statement in section The raise statement.
-
--[ Footnotes ]-
-
-[1] This limitation occurs because the code that is executed by these
- operations is not available at the time the module is compiled.
-''',
- 'execmodel': r'''Execution model
-***************
-
-
-Structure of a program
-======================
-
-A Python program is constructed from code blocks. A *block* is a piece
-of Python program text that is executed as a unit. The following are
-blocks: a module, a function body, and a class definition. Each
-command typed interactively is a block. A script file (a file given
-as standard input to the interpreter or specified as a command line
-argument to the interpreter) is a code block. A script command (a
-command specified on the interpreter command line with the "-c"
-option) is a code block. A module run as a top level script (as module
-"__main__") from the command line using a "-m" argument is also a code
-block. The string argument passed to the built-in functions "eval()"
-and "exec()" is a code block.
-
-A code block is executed in an *execution frame*. A frame contains
-some administrative information (used for debugging) and determines
-where and how execution continues after the code block’s execution has
-completed.
-
-
-Naming and binding
-==================
-
-
-Binding of names
-----------------
-
-*Names* refer to objects. Names are introduced by name binding
-operations.
-
-The following constructs bind names:
-
-* formal parameters to functions,
-
-* class definitions,
-
-* function definitions,
-
-* assignment expressions,
-
-* targets that are identifiers if occurring in an assignment:
-
- * "for" loop header,
-
- * after "as" in a "with" statement, "except" clause, "except*"
- clause, or in the as-pattern in structural pattern matching,
-
- * in a capture pattern in structural pattern matching
-
-* "import" statements.
-
-* "type" statements.
-
-* type parameter lists.
-
-The "import" statement of the form "from ... import *" binds all names
-defined in the imported module, except those beginning with an
-underscore. This form may only be used at the module level.
-
-A target occurring in a "del" statement is also considered bound for
-this purpose (though the actual semantics are to unbind the name).
-
-Each assignment or import statement occurs within a block defined by a
-class or function definition or at the module level (the top-level
-code block).
-
-If a name is bound in a block, it is a local variable of that block,
-unless declared as "nonlocal" or "global". If a name is bound at the
-module level, it is a global variable. (The variables of the module
-code block are local and global.) If a variable is used in a code
-block but not defined there, it is a *free variable*.
-
-Each occurrence of a name in the program text refers to the *binding*
-of that name established by the following name resolution rules.
-
-
-Resolution of names
--------------------
-
-A *scope* defines the visibility of a name within a block. If a local
-variable is defined in a block, its scope includes that block. If the
-definition occurs in a function block, the scope extends to any blocks
-contained within the defining one, unless a contained block introduces
-a different binding for the name.
-
-When a name is used in a code block, it is resolved using the nearest
-enclosing scope. The set of all such scopes visible to a code block
-is called the block’s *environment*.
-
-When a name is not found at all, a "NameError" exception is raised. If
-the current scope is a function scope, and the name refers to a local
-variable that has not yet been bound to a value at the point where the
-name is used, an "UnboundLocalError" exception is raised.
-"UnboundLocalError" is a subclass of "NameError".
-
-If a name binding operation occurs anywhere within a code block, all
-uses of the name within the block are treated as references to the
-current block. This can lead to errors when a name is used within a
-block before it is bound. This rule is subtle. Python lacks
-declarations and allows name binding operations to occur anywhere
-within a code block. The local variables of a code block can be
-determined by scanning the entire text of the block for name binding
-operations. See the FAQ entry on UnboundLocalError for examples.
-
-If the "global" statement occurs within a block, all uses of the names
-specified in the statement refer to the bindings of those names in the
-top-level namespace. Names are resolved in the top-level namespace by
-searching the global namespace, i.e. the namespace of the module
-containing the code block, and the builtins namespace, the namespace
-of the module "builtins". The global namespace is searched first. If
-the names are not found there, the builtins namespace is searched
-next. If the names are also not found in the builtins namespace, new
-variables are created in the global namespace. The global statement
-must precede all uses of the listed names.
-
-The "global" statement has the same scope as a name binding operation
-in the same block. If the nearest enclosing scope for a free variable
-contains a global statement, the free variable is treated as a global.
-
-The "nonlocal" statement causes corresponding names to refer to
-previously bound variables in the nearest enclosing function scope.
-"SyntaxError" is raised at compile time if the given name does not
-exist in any enclosing function scope. Type parameters cannot be
-rebound with the "nonlocal" statement.
-
-The namespace for a module is automatically created the first time a
-module is imported. The main module for a script is always called
-"__main__".
-
-Class definition blocks and arguments to "exec()" and "eval()" are
-special in the context of name resolution. A class definition is an
-executable statement that may use and define names. These references
-follow the normal rules for name resolution with an exception that
-unbound local variables are looked up in the global namespace. The
-namespace of the class definition becomes the attribute dictionary of
-the class. The scope of names defined in a class block is limited to
-the class block; it does not extend to the code blocks of methods.
-This includes comprehensions and generator expressions, but it does
-not include annotation scopes, which have access to their enclosing
-class scopes. This means that the following will fail:
-
- class A:
- a = 42
- b = list(a + i for i in range(10))
-
-However, the following will succeed:
-
- class A:
- type Alias = Nested
- class Nested: pass
-
- print(A.Alias.__value__) # <type 'A.Nested'>
-
-
-Annotation scopes
------------------
-
-*Annotations*, type parameter lists and "type" statements introduce
-*annotation scopes*, which behave mostly like function scopes, but
-with some exceptions discussed below.
-
-Annotation scopes are used in the following contexts:
-
-* *Function annotations*.
-
-* *Variable annotations*.
-
-* Type parameter lists for generic type aliases.
-
-* Type parameter lists for generic functions. A generic function’s
- annotations are executed within the annotation scope, but its
- defaults and decorators are not.
-
-* Type parameter lists for generic classes. A generic class’s base
- classes and keyword arguments are executed within the annotation
- scope, but its decorators are not.
-
-* The bounds, constraints, and default values for type parameters
- (lazily evaluated).
-
-* The value of type aliases (lazily evaluated).
-
-Annotation scopes differ from function scopes in the following ways:
-
-* Annotation scopes have access to their enclosing class namespace. If
- an annotation scope is immediately within a class scope, or within
- another annotation scope that is immediately within a class scope,
- the code in the annotation scope can use names defined in the class
- scope as if it were executed directly within the class body. This
- contrasts with regular functions defined within classes, which
- cannot access names defined in the class scope.
-
-* Expressions in annotation scopes cannot contain "yield", "yield
- from", "await", or ":=" expressions. (These expressions are allowed
- in other scopes contained within the annotation scope.)
-
-* Names defined in annotation scopes cannot be rebound with "nonlocal"
- statements in inner scopes. This includes only type parameters, as
- no other syntactic elements that can appear within annotation scopes
- can introduce new names.
-
-* While annotation scopes have an internal name, that name is not
- reflected in the *qualified name* of objects defined within the
- scope. Instead, the "__qualname__" of such objects is as if the
- object were defined in the enclosing scope.
-
-Added in version 3.12: Annotation scopes were introduced in Python
-3.12 as part of **PEP 695**.
-
-Changed in version 3.13: Annotation scopes are also used for type
-parameter defaults, as introduced by **PEP 696**.
-
-Changed in version 3.14: Annotation scopes are now also used for
-annotations, as specified in **PEP 649** and **PEP 749**.
-
-
-Lazy evaluation
----------------
-
-Most annotation scopes are *lazily evaluated*. This includes
-annotations, the values of type aliases created through the "type"
-statement, and the bounds, constraints, and default values of type
-variables created through the type parameter syntax. This means that
-they are not evaluated when the type alias or type variable is
-created, or when the object carrying annotations is created. Instead,
-they are only evaluated when necessary, for example when the
-"__value__" attribute on a type alias is accessed.
-
-Example:
-
- >>> type Alias = 1/0
- >>> Alias.__value__
- Traceback (most recent call last):
- ...
- ZeroDivisionError: division by zero
- >>> def func[T: 1/0](): pass
- >>> T = func.__type_params__[0]
- >>> T.__bound__
- Traceback (most recent call last):
- ...
- ZeroDivisionError: division by zero
-
-Here the exception is raised only when the "__value__" attribute of
-the type alias or the "__bound__" attribute of the type variable is
-accessed.
-
-This behavior is primarily useful for references to types that have
-not yet been defined when the type alias or type variable is created.
-For example, lazy evaluation enables creation of mutually recursive
-type aliases:
-
- from typing import Literal
-
- type SimpleExpr = int | Parenthesized
- type Parenthesized = tuple[Literal["("], Expr, Literal[")"]]
- type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], Expr]
-
-Lazily evaluated values are evaluated in annotation scope, which means
-that names that appear inside the lazily evaluated value are looked up
-as if they were used in the immediately enclosing scope.
-
-Added in version 3.12.
-
-
-Builtins and restricted execution
----------------------------------
-
-**CPython implementation detail:** Users should not touch
-"__builtins__"; it is strictly an implementation detail. Users
-wanting to override values in the builtins namespace should "import"
-the "builtins" module and modify its attributes appropriately.
-
-The builtins namespace associated with the execution of a code block
-is actually found by looking up the name "__builtins__" in its global
-namespace; this should be a dictionary or a module (in the latter case
-the module’s dictionary is used). By default, when in the "__main__"
-module, "__builtins__" is the built-in module "builtins"; when in any
-other module, "__builtins__" is an alias for the dictionary of the
-"builtins" module itself.
-
-
-Interaction with dynamic features
----------------------------------
-
-Name resolution of free variables occurs at runtime, not at compile
-time. This means that the following code will print 42:
-
- i = 10
- def f():
- print(i)
- i = 42
- f()
-
-The "eval()" and "exec()" functions do not have access to the full
-environment for resolving names. Names may be resolved in the local
-and global namespaces of the caller. Free variables are not resolved
-in the nearest enclosing namespace, but in the global namespace. [1]
-The "exec()" and "eval()" functions have optional arguments to
-override the global and local namespace. If only one namespace is
-specified, it is used for both.
-
-
-Exceptions
-==========
-
-Exceptions are a means of breaking out of the normal flow of control
-of a code block in order to handle errors or other exceptional
-conditions. An exception is *raised* at the point where the error is
-detected; it may be *handled* by the surrounding code block or by any
-code block that directly or indirectly invoked the code block where
-the error occurred.
-
-The Python interpreter raises an exception when it detects a run-time
-error (such as division by zero). A Python program can also
-explicitly raise an exception with the "raise" statement. Exception
-handlers are specified with the "try" … "except" statement. The
-"finally" clause of such a statement can be used to specify cleanup
-code which does not handle the exception, but is executed whether an
-exception occurred or not in the preceding code.
-
-Python uses the “termination” model of error handling: an exception
-handler can find out what happened and continue execution at an outer
-level, but it cannot repair the cause of the error and retry the
-failing operation (except by re-entering the offending piece of code
-from the top).
-
-When an exception is not handled at all, the interpreter terminates
-execution of the program, or returns to its interactive main loop. In
-either case, it prints a stack traceback, except when the exception is
-"SystemExit".
-
-Exceptions are identified by class instances. The "except" clause is
-selected depending on the class of the instance: it must reference the
-class of the instance or a *non-virtual base class* thereof. The
-instance can be received by the handler and can carry additional
-information about the exceptional condition.
-
-Note:
-
- Exception messages are not part of the Python API. Their contents
- may change from one version of Python to the next without warning
- and should not be relied on by code which will run under multiple
- versions of the interpreter.
-
-See also the description of the "try" statement in section The try
-statement and "raise" statement in section The raise statement.
-
--[ Footnotes ]-
-
-[1] This limitation occurs because the code that is executed by these
- operations is not available at the time the module is compiled.
-''',
- 'exprlists': r'''Expression lists
-****************
-
- **starred_expression**: ["*"] "or_expr"
- **flexible_expression**: "assignment_expression" | "starred_expression"
- **flexible_expression_list**: "flexible_expression" ("," "flexible_expression")* [","]
- **starred_expression_list**: "starred_expression" ("," "starred_expression")* [","]
- **expression_list**: "expression" ("," "expression")* [","]
- **yield_list**: "expression_list" | "starred_expression" "," ["starred_expression_list"]
-
-Except when part of a list or set display, an expression list
-containing at least one comma yields a tuple. The length of the tuple
-is the number of expressions in the list. The expressions are
-evaluated from left to right.
-
-An asterisk "*" denotes *iterable unpacking*. Its operand must be an
-*iterable*. The iterable is expanded into a sequence of items, which
-are included in the new tuple, list, or set, at the site of the
-unpacking.
-
-Added in version 3.5: Iterable unpacking in expression lists,
-originally proposed by **PEP 448**.
-
-Added in version 3.11: Any item in an expression list may be starred.
-See **PEP 646**.
-
-A trailing comma is required only to create a one-item tuple, such as
-"1,"; it is optional in all other cases. A single expression without a
-trailing comma doesn’t create a tuple, but rather yields the value of
-that expression. (To create an empty tuple, use an empty pair of
-parentheses: "()".)
-''',
- 'floating': r'''Floating-point literals
-***********************
-
-Floating-point literals are described by the following lexical
-definitions:
-
- **floatnumber**: "pointfloat" | "exponentfloat"
- **pointfloat**: ["digitpart"] "fraction" | "digitpart" "."
- **exponentfloat**: ("digitpart" | "pointfloat") "exponent"
- **digitpart**: "digit" (["_"] "digit")*
- **fraction**: "." "digitpart"
- **exponent**: ("e" | "E") ["+" | "-"] "digitpart"
-
-Note that the integer and exponent parts are always interpreted using
-radix 10. For example, "077e010" is legal, and denotes the same number
-as "77e10". The allowed range of floating-point literals is
-implementation-dependent. As in integer literals, underscores are
-supported for digit grouping.
-
-Some examples of floating-point literals:
-
- 3.14 10. .001 1e100 3.14e-10 0e0 3.14_15_93
-
-Changed in version 3.6: Underscores are now allowed for grouping
-purposes in literals.
-''',
- 'for': r'''The "for" statement
-*******************
-
-The "for" statement is used to iterate over the elements of a sequence
-(such as a string, tuple or list) or other iterable object:
-
- **for_stmt**: "for" "target_list" "in" "starred_list" ":" "suite"
- ["else" ":" "suite"]
-
-The "starred_list" expression is evaluated once; it should yield an
-*iterable* object. An *iterator* is created for that iterable. The
-first item provided by the iterator is then assigned to the target
-list using the standard rules for assignments (see Assignment
-statements), and the suite is executed. This repeats for each item
-provided by the iterator. When the iterator is exhausted, the suite
-in the "else" clause, if present, is executed, and the loop
-terminates.
-
-A "break" statement executed in the first suite terminates the loop
-without executing the "else" clause’s suite. A "continue" statement
-executed in the first suite skips the rest of the suite and continues
-with the next item, or with the "else" clause if there is no next
-item.
-
-The for-loop makes assignments to the variables in the target list.
-This overwrites all previous assignments to those variables including
-those made in the suite of the for-loop:
-
- for i in range(10):
- print(i)
- i = 5 # this will not affect the for-loop
- # because i will be overwritten with the next
- # index in the range
-
-Names in the target list are not deleted when the loop is finished,
-but if the sequence is empty, they will not have been assigned to at
-all by the loop. Hint: the built-in type "range()" represents
-immutable arithmetic sequences of integers. For instance, iterating
-"range(3)" successively yields 0, 1, and then 2.
-
-Changed in version 3.11: Starred elements are now allowed in the
-expression list.
-''',
- 'formatstrings': r'''Format String Syntax
-********************
-
-The "str.format()" method and the "Formatter" class share the same
-syntax for format strings (although in the case of "Formatter",
-subclasses can define their own format string syntax). The syntax is
-related to that of formatted string literals, but it is less
-sophisticated and, in particular, does not support arbitrary
-expressions.
-
-Format strings contain “replacement fields” surrounded by curly braces
-"{}". Anything that is not contained in braces is considered literal
-text, which is copied unchanged to the output. If you need to include
-a brace character in the literal text, it can be escaped by doubling:
-"{{" and "}}".
-
-The grammar for a replacement field is as follows:
-
- **replacement_field**: "{" ["field_name"] ["!" "conversion"] [":" "format_spec"] "}"
- **field_name**: "arg_name" ("." "attribute_name" | "[" "element_index" "]")*
- **arg_name**: ["identifier" | "digit"+]
- **attribute_name**: "identifier"
- **element_index**: "digit"+ | "index_string"
- **index_string**: <any source character except "]"> +
- **conversion**: "r" | "s" | "a"
- **format_spec**: "format-spec:format_spec"
-
-In less formal terms, the replacement field can start with a
-*field_name* that specifies the object whose value is to be formatted
-and inserted into the output instead of the replacement field. The
-*field_name* is optionally followed by a *conversion* field, which is
-preceded by an exclamation point "'!'", and a *format_spec*, which is
-preceded by a colon "':'". These specify a non-default format for the
-replacement value.
-
-See also the Format Specification Mini-Language section.
-
-The *field_name* itself begins with an *arg_name* that is either a
-number or a keyword. If it’s a number, it refers to a positional
-argument, and if it’s a keyword, it refers to a named keyword
-argument. An *arg_name* is treated as a number if a call to
-"str.isdecimal()" on the string would return true. If the numerical
-arg_names in a format string are 0, 1, 2, … in sequence, they can all
-be omitted (not just some) and the numbers 0, 1, 2, … will be
-automatically inserted in that order. Because *arg_name* is not quote-
-delimited, it is not possible to specify arbitrary dictionary keys
-(e.g., the strings "'10'" or "':-]'") within a format string. The
-*arg_name* can be followed by any number of index or attribute
-expressions. An expression of the form "'.name'" selects the named
-attribute using "getattr()", while an expression of the form
-"'[index]'" does an index lookup using "__getitem__()".
-
-Changed in version 3.1: The positional argument specifiers can be
-omitted for "str.format()", so "'{} {}'.format(a, b)" is equivalent to
-"'{0} {1}'.format(a, b)".
-
-Changed in version 3.4: The positional argument specifiers can be
-omitted for "Formatter".
-
-Some simple format string examples:
-
- "First, thou shalt count to {0}" # References first positional argument
- "Bring me a {}" # Implicitly references the first positional argument
- "From {} to {}" # Same as "From {0} to {1}"
- "My quest is {name}" # References keyword argument 'name'
- "Weight in tons {0.weight}" # 'weight' attribute of first positional arg
- "Units destroyed: {players[0]}" # First element of keyword argument 'players'.
-
-The *conversion* field causes a type coercion before formatting.
-Normally, the job of formatting a value is done by the "__format__()"
-method of the value itself. However, in some cases it is desirable to
-force a type to be formatted as a string, overriding its own
-definition of formatting. By converting the value to a string before
-calling "__format__()", the normal formatting logic is bypassed.
-
-Three conversion flags are currently supported: "'!s'" which calls
-"str()" on the value, "'!r'" which calls "repr()" and "'!a'" which
-calls "ascii()".
-
-Some examples:
-
- "Harold's a clever {0!s}" # Calls str() on the argument first
- "Bring out the holy {name!r}" # Calls repr() on the argument first
- "More {!a}" # Calls ascii() on the argument first
-
-The *format_spec* field contains a specification of how the value
-should be presented, including such details as field width, alignment,
-padding, decimal precision and so on. Each value type can define its
-own “formatting mini-language” or interpretation of the *format_spec*.
-
-Most built-in types support a common formatting mini-language, which
-is described in the next section.
-
-A *format_spec* field can also include nested replacement fields
-within it. These nested replacement fields may contain a field name,
-conversion flag and format specification, but deeper nesting is not
-allowed. The replacement fields within the format_spec are
-substituted before the *format_spec* string is interpreted. This
-allows the formatting of a value to be dynamically specified.
-
-See the Format examples section for some examples.
-
-
-Format Specification Mini-Language
-==================================
-
-“Format specifications” are used within replacement fields contained
-within a format string to define how individual values are presented
-(see Format String Syntax and f-strings). They can also be passed
-directly to the built-in "format()" function. Each formattable type
-may define how the format specification is to be interpreted.
-
-Most built-in types implement the following options for format
-specifications, although some of the formatting options are only
-supported by the numeric types.
-
-A general convention is that an empty format specification produces
-the same result as if you had called "str()" on the value. A non-empty
-format specification typically modifies the result.
-
-The general form of a *standard format specifier* is:
-
- **format_spec**: [["fill"]"align"]["sign"]["z"]["#"]["0"]["width"]["grouping_option"]["." "precision"]["type"]
- **fill**: <any character>
- **align**: "<" | ">" | "=" | "^"
- **sign**: "+" | "-" | " "
- **width**: "digit"+
- **grouping_option**: "_" | ","
- **precision**: "digit"+
- **type**: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"
-
-If a valid *align* value is specified, it can be preceded by a *fill*
-character that can be any character and defaults to a space if
-omitted. It is not possible to use a literal curly brace (”"{"” or
-“"}"”) as the *fill* character in a formatted string literal or when
-using the "str.format()" method. However, it is possible to insert a
-curly brace with a nested replacement field. This limitation doesn’t
-affect the "format()" function.
-
-The meaning of the various alignment options is as follows:
-
-+-----------+------------------------------------------------------------+
-| Option | Meaning |
-|===========|============================================================|
-| "'<'" | Forces the field to be left-aligned within the available |
-| | space (this is the default for most objects). |
-+-----------+------------------------------------------------------------+
-| "'>'" | Forces the field to be right-aligned within the available |
-| | space (this is the default for numbers). |
-+-----------+------------------------------------------------------------+
-| "'='" | Forces the padding to be placed after the sign (if any) |
-| | but before the digits. This is used for printing fields |
-| | in the form ‘+000000120’. This alignment option is only |
-| | valid for numeric types, excluding "complex". It becomes |
-| | the default for numbers when ‘0’ immediately precedes the |
-| | field width. |
-+-----------+------------------------------------------------------------+
-| "'^'" | Forces the field to be centered within the available |
-| | space. |
-+-----------+------------------------------------------------------------+
-
-Note that unless a minimum field width is defined, the field width
-will always be the same size as the data to fill it, so that the
-alignment option has no meaning in this case.
-
-The *sign* option is only valid for number types, and can be one of
-the following:
-
-+-----------+------------------------------------------------------------+
-| Option | Meaning |
-|===========|============================================================|
-| "'+'" | indicates that a sign should be used for both positive as |
-| | well as negative numbers. |
-+-----------+------------------------------------------------------------+
-| "'-'" | indicates that a sign should be used only for negative |
-| | numbers (this is the default behavior). |
-+-----------+------------------------------------------------------------+
-| space | indicates that a leading space should be used on positive |
-| | numbers, and a minus sign on negative numbers. |
-+-----------+------------------------------------------------------------+
-
-The "'z'" option coerces negative zero floating-point values to
-positive zero after rounding to the format precision. This option is
-only valid for floating-point presentation types.
-
-Changed in version 3.11: Added the "'z'" option (see also **PEP
-682**).
-
-The "'#'" option causes the “alternate form” to be used for the
-conversion. The alternate form is defined differently for different
-types. This option is only valid for integer, float and complex
-types. For integers, when binary, octal, or hexadecimal output is
-used, this option adds the respective prefix "'0b'", "'0o'", "'0x'",
-or "'0X'" to the output value. For float and complex the alternate
-form causes the result of the conversion to always contain a decimal-
-point character, even if no digits follow it. Normally, a decimal-
-point character appears in the result of these conversions only if a
-digit follows it. In addition, for "'g'" and "'G'" conversions,
-trailing zeros are not removed from the result.
-
-The "','" option signals the use of a comma for a thousands separator
-for floating-point presentation types and for integer presentation
-type "'d'". For other presentation types, this option is an error. For
-a locale aware separator, use the "'n'" integer presentation type
-instead.
-
-Changed in version 3.1: Added the "','" option (see also **PEP 378**).
-
-The "'_'" option signals the use of an underscore for a thousands
-separator for floating-point presentation types and for integer
-presentation type "'d'". For integer presentation types "'b'", "'o'",
-"'x'", and "'X'", underscores will be inserted every 4 digits. For
-other presentation types, specifying this option is an error.
-
-Changed in version 3.6: Added the "'_'" option (see also **PEP 515**).
-
-*width* is a decimal integer defining the minimum total field width,
-including any prefixes, separators, and other formatting characters.
-If not specified, then the field width will be determined by the
-content.
-
-When no explicit alignment is given, preceding the *width* field by a
-zero ("'0'") character enables sign-aware zero-padding for numeric
-types, excluding "complex". This is equivalent to a *fill* character
-of "'0'" with an *alignment* type of "'='".
-
-Changed in version 3.10: Preceding the *width* field by "'0'" no
-longer affects the default alignment for strings.
-
-The *precision* is a decimal integer indicating how many digits should
-be displayed after the decimal point for presentation types "'f'" and
-"'F'", or before and after the decimal point for presentation types
-"'g'" or "'G'". For string presentation types the field indicates the
-maximum field size - in other words, how many characters will be used
-from the field content. The *precision* is not allowed for integer
-presentation types.
-
-Finally, the *type* determines how the data should be presented.
-
-The available string presentation types are:
-
- +-----------+------------------------------------------------------------+
- | Type | Meaning |
- |===========|============================================================|
- | "'s'" | String format. This is the default type for strings and |
- | | may be omitted. |
- +-----------+------------------------------------------------------------+
- | None | The same as "'s'". |
- +-----------+------------------------------------------------------------+
-
-The available integer presentation types are:
-
- +-----------+------------------------------------------------------------+
- | Type | Meaning |
- |===========|============================================================|
- | "'b'" | Binary format. Outputs the number in base 2. |
- +-----------+------------------------------------------------------------+
- | "'c'" | Character. Converts the integer to the corresponding |
- | | unicode character before printing. |
- +-----------+------------------------------------------------------------+
- | "'d'" | Decimal Integer. Outputs the number in base 10. |
- +-----------+------------------------------------------------------------+
- | "'o'" | Octal format. Outputs the number in base 8. |
- +-----------+------------------------------------------------------------+
- | "'x'" | Hex format. Outputs the number in base 16, using lower- |
- | | case letters for the digits above 9. |
- +-----------+------------------------------------------------------------+
- | "'X'" | Hex format. Outputs the number in base 16, using upper- |
- | | case letters for the digits above 9. In case "'#'" is |
- | | specified, the prefix "'0x'" will be upper-cased to "'0X'" |
- | | as well. |
- +-----------+------------------------------------------------------------+
- | "'n'" | Number. This is the same as "'d'", except that it uses the |
- | | current locale setting to insert the appropriate number |
- | | separator characters. |
- +-----------+------------------------------------------------------------+
- | None | The same as "'d'". |
- +-----------+------------------------------------------------------------+
-
-In addition to the above presentation types, integers can be formatted
-with the floating-point presentation types listed below (except "'n'"
-and "None"). When doing so, "float()" is used to convert the integer
-to a floating-point number before formatting.
-
-The available presentation types for "float" and "Decimal" values are:
-
- +-----------+------------------------------------------------------------+
- | Type | Meaning |
- |===========|============================================================|
- | "'e'" | Scientific notation. For a given precision "p", formats |
- | | the number in scientific notation with the letter ‘e’ |
- | | separating the coefficient from the exponent. The |
- | | coefficient has one digit before and "p" digits after the |
- | | decimal point, for a total of "p + 1" significant digits. |
- | | With no precision given, uses a precision of "6" digits |
- | | after the decimal point for "float", and shows all |
- | | coefficient digits for "Decimal". If "p=0", the decimal |
- | | point is omitted unless the "#" option is used. |
- +-----------+------------------------------------------------------------+
- | "'E'" | Scientific notation. Same as "'e'" except it uses an upper |
- | | case ‘E’ as the separator character. |
- +-----------+------------------------------------------------------------+
- | "'f'" | Fixed-point notation. For a given precision "p", formats |
- | | the number as a decimal number with exactly "p" digits |
- | | following the decimal point. With no precision given, uses |
- | | a precision of "6" digits after the decimal point for |
- | | "float", and uses a precision large enough to show all |
- | | coefficient digits for "Decimal". If "p=0", the decimal |
- | | point is omitted unless the "#" option is used. |
- +-----------+------------------------------------------------------------+
- | "'F'" | Fixed-point notation. Same as "'f'", but converts "nan" to |
- | | "NAN" and "inf" to "INF". |
- +-----------+------------------------------------------------------------+
- | "'g'" | General format. For a given precision "p >= 1", this |
- | | rounds the number to "p" significant digits and then |
- | | formats the result in either fixed-point format or in |
- | | scientific notation, depending on its magnitude. A |
- | | precision of "0" is treated as equivalent to a precision |
- | | of "1". The precise rules are as follows: suppose that |
- | | the result formatted with presentation type "'e'" and |
- | | precision "p-1" would have exponent "exp". Then, if "m <= |
- | | exp < p", where "m" is -4 for floats and -6 for |
- | | "Decimals", the number is formatted with presentation type |
- | | "'f'" and precision "p-1-exp". Otherwise, the number is |
- | | formatted with presentation type "'e'" and precision |
- | | "p-1". In both cases insignificant trailing zeros are |
- | | removed from the significand, and the decimal point is |
- | | also removed if there are no remaining digits following |
- | | it, unless the "'#'" option is used. With no precision |
- | | given, uses a precision of "6" significant digits for |
- | | "float". For "Decimal", the coefficient of the result is |
- | | formed from the coefficient digits of the value; |
- | | scientific notation is used for values smaller than "1e-6" |
- | | in absolute value and values where the place value of the |
- | | least significant digit is larger than 1, and fixed-point |
- | | notation is used otherwise. Positive and negative |
- | | infinity, positive and negative zero, and nans, are |
- | | formatted as "inf", "-inf", "0", "-0" and "nan" |
- | | respectively, regardless of the precision. |
- +-----------+------------------------------------------------------------+
- | "'G'" | General format. Same as "'g'" except switches to "'E'" if |
- | | the number gets too large. The representations of infinity |
- | | and NaN are uppercased, too. |
- +-----------+------------------------------------------------------------+
- | "'n'" | Number. This is the same as "'g'", except that it uses the |
- | | current locale setting to insert the appropriate number |
- | | separator characters. |
- +-----------+------------------------------------------------------------+
- | "'%'" | Percentage. Multiplies the number by 100 and displays in |
- | | fixed ("'f'") format, followed by a percent sign. |
- +-----------+------------------------------------------------------------+
- | None | For "float" this is like the "'g'" type, except that when |
- | | fixed- point notation is used to format the result, it |
- | | always includes at least one digit past the decimal point, |
- | | and switches to the scientific notation when "exp >= p - |
- | | 1". When the precision is not specified, the latter will |
- | | be as large as needed to represent the given value |
- | | faithfully. For "Decimal", this is the same as either |
- | | "'g'" or "'G'" depending on the value of |
- | | "context.capitals" for the current decimal context. The |
- | | overall effect is to match the output of "str()" as |
- | | altered by the other format modifiers. |
- +-----------+------------------------------------------------------------+
-
-The result should be correctly rounded to a given precision "p" of
-digits after the decimal point. The rounding mode for "float" matches
-that of the "round()" builtin. For "Decimal", the rounding mode of
-the current context will be used.
-
-The available presentation types for "complex" are the same as those
-for "float" ("'%'" is not allowed). Both the real and imaginary
-components of a complex number are formatted as floating-point
-numbers, according to the specified presentation type. They are
-separated by the mandatory sign of the imaginary part, the latter
-being terminated by a "j" suffix. If the presentation type is
-missing, the result will match the output of "str()" (complex numbers
-with a non-zero real part are also surrounded by parentheses),
-possibly altered by other format modifiers.
-
-
-Format examples
-===============
-
-This section contains examples of the "str.format()" syntax and
-comparison with the old "%"-formatting.
-
-In most of the cases the syntax is similar to the old "%"-formatting,
-with the addition of the "{}" and with ":" used instead of "%". For
-example, "'%03.2f'" can be translated to "'{:03.2f}'".
-
-The new format syntax also supports new and different options, shown
-in the following examples.
-
-Accessing arguments by position:
-
- >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
- 'a, b, c'
- >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only
- 'a, b, c'
- >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
- 'c, b, a'
- >>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence
- 'c, b, a'
- >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' indices can be repeated
- 'abracadabra'
-
-Accessing arguments by name:
-
- >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
- 'Coordinates: 37.24N, -115.81W'
- >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
- >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
- 'Coordinates: 37.24N, -115.81W'
-
-Accessing arguments’ attributes:
-
- >>> c = 3-5j
- >>> ('The complex number {0} is formed from the real part {0.real} '
- ... 'and the imaginary part {0.imag}.').format(c)
- 'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
- >>> class Point:
- ... def __init__(self, x, y):
- ... self.x, self.y = x, y
- ... def __str__(self):
- ... return 'Point({self.x}, {self.y})'.format(self=self)
- ...
- >>> str(Point(4, 2))
- 'Point(4, 2)'
-
-Accessing arguments’ items:
-
- >>> coord = (3, 5)
- >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
- 'X: 3; Y: 5'
-
-Replacing "%s" and "%r":
-
- >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
- "repr() shows quotes: 'test1'; str() doesn't: test2"
-
-Aligning the text and specifying a width:
-
- >>> '{:<30}'.format('left aligned')
- 'left aligned '
- >>> '{:>30}'.format('right aligned')
- ' right aligned'
- >>> '{:^30}'.format('centered')
- ' centered '
- >>> '{:*^30}'.format('centered') # use '*' as a fill char
- '***********centered***********'
-
-Replacing "%+f", "%-f", and "% f" and specifying a sign:
-
- >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always
- '+3.140000; -3.140000'
- >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers
- ' 3.140000; -3.140000'
- >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}'
- '3.140000; -3.140000'
-
-Replacing "%x" and "%o" and converting the value to different bases:
-
- >>> # format also supports binary numbers
- >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42)
- 'int: 42; hex: 2a; oct: 52; bin: 101010'
- >>> # with 0x, 0o, or 0b as prefix:
- >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42)
- 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'
-
-Using the comma as a thousands separator:
-
- >>> '{:,}'.format(1234567890)
- '1,234,567,890'
-
-Expressing a percentage:
-
- >>> points = 19
- >>> total = 22
- >>> 'Correct answers: {:.2%}'.format(points/total)
- 'Correct answers: 86.36%'
-
-Using type-specific formatting:
-
- >>> import datetime
- >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
- >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
- '2010-07-04 12:15:58'
-
-Nesting arguments and more complex examples:
-
- >>> for align, text in zip('<^>', ['left', 'center', 'right']):
- ... '{0:{fill}{align}16}'.format(text, fill=align, align=align)
- ...
- 'left<<<<<<<<<<<<'
- '^^^^^center^^^^^'
- '>>>>>>>>>>>right'
- >>>
- >>> octets = [192, 168, 0, 1]
- >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
- 'C0A80001'
- >>> int(_, 16)
- 3232235521
- >>>
- >>> width = 5
- >>> for num in range(5,12):
- ... for base in 'dXob':
- ... print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
- ... print()
- ...
- 5 5 5 101
- 6 6 6 110
- 7 7 7 111
- 8 8 10 1000
- 9 9 11 1001
- 10 A 12 1010
- 11 B 13 1011
-''',
- 'function': r'''Function definitions
-********************
-
-A function definition defines a user-defined function object (see
-section The standard type hierarchy):
-
- **funcdef**: ["decorators"] "def" "funcname" ["type_params"] "(" ["parameter_list"] ")"
- ["->" "expression"] ":" "suite"
- **decorators**: "decorator"+
- **decorator**: "@" "assignment_expression" NEWLINE
- **parameter_list**: "defparameter" ("," "defparameter")* "," "/" ["," ["parameter_list_no_posonly"]]
- | "parameter_list_no_posonly"
- **parameter_list_no_posonly**: "defparameter" ("," "defparameter")* ["," ["parameter_list_starargs"]]
- | "parameter_list_starargs"
- **parameter_list_starargs**: "*" ["star_parameter"] ("," "defparameter")* ["," ["parameter_star_kwargs"]]
- "*" ("," "defparameter")+ ["," ["parameter_star_kwargs"]]
- | "parameter_star_kwargs"
- **parameter_star_kwargs**: "**" "parameter" [","]
- **parameter**: "identifier" [":" "expression"]
- **star_parameter**: "identifier" [":" ["*"] "expression"]
- **defparameter**: "parameter" ["=" "expression"]
- **funcname**: "identifier"
-
-A function definition is an executable statement. Its execution binds
-the function name in the current local namespace to a function object
-(a wrapper around the executable code for the function). This
-function object contains a reference to the current global namespace
-as the global namespace to be used when the function is called.
-
-The function definition does not execute the function body; this gets
-executed only when the function is called. [4]
-
-A function definition may be wrapped by one or more *decorator*
-expressions. Decorator expressions are evaluated when the function is
-defined, in the scope that contains the function definition. The
-result must be a callable, which is invoked with the function object
-as the only argument. The returned value is bound to the function name
-instead of the function object. Multiple decorators are applied in
-nested fashion. For example, the following code
-
- @f1(arg)
- @f2
- def func(): pass
-
-is roughly equivalent to
-
- def func(): pass
- func = f1(arg)(f2(func))
-
-except that the original function is not temporarily bound to the name
-"func".
-
-Changed in version 3.9: Functions may be decorated with any valid
-"assignment_expression". Previously, the grammar was much more
-restrictive; see **PEP 614** for details.
-
-A list of type parameters may be given in square brackets between the
-function’s name and the opening parenthesis for its parameter list.
-This indicates to static type checkers that the function is generic.
-At runtime, the type parameters can be retrieved from the function’s
-"__type_params__" attribute. See Generic functions for more.
-
-Changed in version 3.12: Type parameter lists are new in Python 3.12.
-
-When one or more *parameters* have the form *parameter* "="
-*expression*, the function is said to have “default parameter values.”
-For a parameter with a default value, the corresponding *argument* may
-be omitted from a call, in which case the parameter’s default value is
-substituted. If a parameter has a default value, all following
-parameters up until the “"*"” must also have a default value — this is
-a syntactic restriction that is not expressed by the grammar.
-
-**Default parameter values are evaluated from left to right when the
-function definition is executed.** This means that the expression is
-evaluated once, when the function is defined, and that the same “pre-
-computed” value is used for each call. This is especially important
-to understand when a default parameter value is a mutable object, such
-as a list or a dictionary: if the function modifies the object (e.g.
-by appending an item to a list), the default parameter value is in
-effect modified. This is generally not what was intended. A way
-around this is to use "None" as the default, and explicitly test for
-it in the body of the function, e.g.:
-
- def whats_on_the_telly(penguin=None):
- if penguin is None:
- penguin = []
- penguin.append("property of the zoo")
- return penguin
-
-Function call semantics are described in more detail in section Calls.
-A function call always assigns values to all parameters mentioned in
-the parameter list, either from positional arguments, from keyword
-arguments, or from default values. If the form “"*identifier"” is
-present, it is initialized to a tuple receiving any excess positional
-parameters, defaulting to the empty tuple. If the form
-“"**identifier"” is present, it is initialized to a new ordered
-mapping receiving any excess keyword arguments, defaulting to a new
-empty mapping of the same type. Parameters after “"*"” or
-“"*identifier"” are keyword-only parameters and may only be passed by
-keyword arguments. Parameters before “"/"” are positional-only
-parameters and may only be passed by positional arguments.
-
-Changed in version 3.8: The "/" function parameter syntax may be used
-to indicate positional-only parameters. See **PEP 570** for details.
-
-Parameters may have an *annotation* of the form “": expression"”
-following the parameter name. Any parameter may have an annotation,
-even those of the form "*identifier" or "**identifier". (As a special
-case, parameters of the form "*identifier" may have an annotation “":
-*expression"”.) Functions may have “return” annotation of the form
-“"-> expression"” after the parameter list. These annotations can be
-any valid Python expression. The presence of annotations does not
-change the semantics of a function. See Annotations for more
-information on annotations.
-
-Changed in version 3.11: Parameters of the form “"*identifier"” may
-have an annotation “": *expression"”. See **PEP 646**.
-
-It is also possible to create anonymous functions (functions not bound
-to a name), for immediate use in expressions. This uses lambda
-expressions, described in section Lambdas. Note that the lambda
-expression is merely a shorthand for a simplified function definition;
-a function defined in a “"def"” statement can be passed around or
-assigned to another name just like a function defined by a lambda
-expression. The “"def"” form is actually more powerful since it
-allows the execution of multiple statements and annotations.
-
-**Programmer’s note:** Functions are first-class objects. A “"def"”
-statement executed inside a function definition defines a local
-function that can be returned or passed around. Free variables used
-in the nested function can access the local variables of the function
-containing the def. See section Naming and binding for details.
-
-See also:
-
- **PEP 3107** - Function Annotations
- The original specification for function annotations.
-
- **PEP 484** - Type Hints
- Definition of a standard meaning for annotations: type hints.
-
- **PEP 526** - Syntax for Variable Annotations
- Ability to type hint variable declarations, including class
- variables and instance variables.
-
- **PEP 563** - Postponed Evaluation of Annotations
- Support for forward references within annotations by preserving
- annotations in a string form at runtime instead of eager
- evaluation.
-
- **PEP 318** - Decorators for Functions and Methods
- Function and method decorators were introduced. Class decorators
- were introduced in **PEP 3129**.
-''',
- 'global': r'''The "global" statement
-**********************
-
- **global_stmt**: "global" "identifier" ("," "identifier")*
-
-The "global" statement causes the listed identifiers to be interpreted
-as globals. It would be impossible to assign to a global variable
-without "global", although free variables may refer to globals without
-being declared global.
-
-The "global" statement applies to the entire scope of a function or
-class body. A "SyntaxError" is raised if a variable is used or
-assigned to prior to its global declaration in the scope.
-
-**Programmer’s note:** "global" is a directive to the parser. It
-applies only to code parsed at the same time as the "global"
-statement. In particular, a "global" statement contained in a string
-or code object supplied to the built-in "exec()" function does not
-affect the code block *containing* the function call, and code
-contained in such a string is unaffected by "global" statements in the
-code containing the function call. The same applies to the "eval()"
-and "compile()" functions.
-''',
- 'id-classes': r'''Reserved classes of identifiers
-*******************************
-
-Certain classes of identifiers (besides keywords) have special
-meanings. These classes are identified by the patterns of leading and
-trailing underscore characters:
-
-"_*"
- Not imported by "from module import *".
-
-"_"
- In a "case" pattern within a "match" statement, "_" is a soft
- keyword that denotes a wildcard.
-
- Separately, the interactive interpreter makes the result of the
- last evaluation available in the variable "_". (It is stored in the
- "builtins" module, alongside built-in functions like "print".)
-
- Elsewhere, "_" is a regular identifier. It is often used to name
- “special” items, but it is not special to Python itself.
-
- Note:
-
- The name "_" is often used in conjunction with
- internationalization; refer to the documentation for the
- "gettext" module for more information on this convention.It is
- also commonly used for unused variables.
-
-"__*__"
- System-defined names, informally known as “dunder” names. These
- names are defined by the interpreter and its implementation
- (including the standard library). Current system names are
- discussed in the Special method names section and elsewhere. More
- will likely be defined in future versions of Python. *Any* use of
- "__*__" names, in any context, that does not follow explicitly
- documented use, is subject to breakage without warning.
-
-"__*"
- Class-private names. Names in this category, when used within the
- context of a class definition, are re-written to use a mangled form
- to help avoid name clashes between “private” attributes of base and
- derived classes. See section Identifiers (Names).
-''',
- 'identifiers': r'''Identifiers and keywords
-************************
-
-Identifiers (also referred to as *names*) are described by the
-following lexical definitions.
-
-The syntax of identifiers in Python is based on the Unicode standard
-annex UAX-31, with elaboration and changes as defined below; see also
-**PEP 3131** for further details.
-
-Within the ASCII range (U+0001..U+007F), the valid characters for
-identifiers include the uppercase and lowercase letters "A" through
-"Z", the underscore "_" and, except for the first character, the
-digits "0" through "9". Python 3.0 introduced additional characters
-from outside the ASCII range (see **PEP 3131**). For these
-characters, the classification uses the version of the Unicode
-Character Database as included in the "unicodedata" module.
-
-Identifiers are unlimited in length. Case is significant.
-
- **identifier**: "xid_start" "xid_continue"*
- **id_start**: <all characters in general categories Lu, Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the Other_ID_Start property>
- **id_continue**: <all characters in "id_start", plus characters in the categories Mn, Mc, Nd, Pc and others with the Other_ID_Continue property>
- **xid_start**: <all characters in "id_start" whose NFKC normalization is in "id_start xid_continue*">
- **xid_continue**: <all characters in "id_continue" whose NFKC normalization is in "id_continue*">
-
-The Unicode category codes mentioned above stand for:
-
-* *Lu* - uppercase letters
-
-* *Ll* - lowercase letters
-
-* *Lt* - titlecase letters
-
-* *Lm* - modifier letters
-
-* *Lo* - other letters
-
-* *Nl* - letter numbers
-
-* *Mn* - nonspacing marks
-
-* *Mc* - spacing combining marks
-
-* *Nd* - decimal numbers
-
-* *Pc* - connector punctuations
-
-* *Other_ID_Start* - explicit list of characters in PropList.txt to
- support backwards compatibility
-
-* *Other_ID_Continue* - likewise
-
-All identifiers are converted into the normal form NFKC while parsing;
-comparison of identifiers is based on NFKC.
-
-A non-normative HTML file listing all valid identifier characters for
-Unicode 16.0.0 can be found at
-https://www.unicode.org/Public/16.0.0/ucd/DerivedCoreProperties.txt
-
-
-Keywords
-========
-
-The following identifiers are used as reserved words, or *keywords* of
-the language, and cannot be used as ordinary identifiers. They must
-be spelled exactly as written here:
-
- False await else import pass
- None break except in raise
- True class finally is return
- and continue for lambda try
- as def from nonlocal while
- assert del global not with
- async elif if or yield
-
-
-Soft Keywords
-=============
-
-Added in version 3.10.
-
-Some identifiers are only reserved under specific contexts. These are
-known as *soft keywords*. The identifiers "match", "case", "type" and
-"_" can syntactically act as keywords in certain contexts, but this
-distinction is done at the parser level, not when tokenizing.
-
-As soft keywords, their use in the grammar is possible while still
-preserving compatibility with existing code that uses these names as
-identifier names.
-
-"match", "case", and "_" are used in the "match" statement. "type" is
-used in the "type" statement.
-
-Changed in version 3.12: "type" is now a soft keyword.
-
-
-Reserved classes of identifiers
-===============================
-
-Certain classes of identifiers (besides keywords) have special
-meanings. These classes are identified by the patterns of leading and
-trailing underscore characters:
-
-"_*"
- Not imported by "from module import *".
-
-"_"
- In a "case" pattern within a "match" statement, "_" is a soft
- keyword that denotes a wildcard.
-
- Separately, the interactive interpreter makes the result of the
- last evaluation available in the variable "_". (It is stored in the
- "builtins" module, alongside built-in functions like "print".)
-
- Elsewhere, "_" is a regular identifier. It is often used to name
- “special” items, but it is not special to Python itself.
-
- Note:
-
- The name "_" is often used in conjunction with
- internationalization; refer to the documentation for the
- "gettext" module for more information on this convention.It is
- also commonly used for unused variables.
-
-"__*__"
- System-defined names, informally known as “dunder” names. These
- names are defined by the interpreter and its implementation
- (including the standard library). Current system names are
- discussed in the Special method names section and elsewhere. More
- will likely be defined in future versions of Python. *Any* use of
- "__*__" names, in any context, that does not follow explicitly
- documented use, is subject to breakage without warning.
-
-"__*"
- Class-private names. Names in this category, when used within the
- context of a class definition, are re-written to use a mangled form
- to help avoid name clashes between “private” attributes of base and
- derived classes. See section Identifiers (Names).
-''',
- 'if': r'''The "if" statement
-******************
-
-The "if" statement is used for conditional execution:
-
- **if_stmt**: "if" "assignment_expression" ":" "suite"
- ("elif" "assignment_expression" ":" "suite")*
- ["else" ":" "suite"]
-
-It selects exactly one of the suites by evaluating the expressions one
-by one until one is found to be true (see section Boolean operations
-for the definition of true and false); then that suite is executed
-(and no other part of the "if" statement is executed or evaluated).
-If all expressions are false, the suite of the "else" clause, if
-present, is executed.
-''',
- 'imaginary': r'''Imaginary literals
-******************
-
-Imaginary literals are described by the following lexical definitions:
-
- **imagnumber**: ("floatnumber" | "digitpart") ("j" | "J")
-
-An imaginary literal yields a complex number with a real part of 0.0.
-Complex numbers are represented as a pair of floating-point numbers
-and have the same restrictions on their range. To create a complex
-number with a nonzero real part, add a floating-point number to it,
-e.g., "(3+4j)". Some examples of imaginary literals:
-
- 3.14j 10.j 10j .001j 1e100j 3.14e-10j 3.14_15_93j
-''',
- 'import': r'''The "import" statement
-**********************
-
- **import_stmt**: "import" "module" ["as" "identifier"] ("," "module" ["as" "identifier"])*
- | "from" "relative_module" "import" "identifier" ["as" "identifier"]
- ("," "identifier" ["as" "identifier"])*
- | "from" "relative_module" "import" "(" "identifier" ["as" "identifier"]
- ("," "identifier" ["as" "identifier"])* [","] ")"
- | "from" "relative_module" "import" "*"
- **module**: ("identifier" ".")* "identifier"
- **relative_module**: "."* "module" | "."+
-
-The basic import statement (no "from" clause) is executed in two
-steps:
-
-1. find a module, loading and initializing it if necessary
-
-2. define a name or names in the local namespace for the scope where
- the "import" statement occurs.
-
-When the statement contains multiple clauses (separated by commas) the
-two steps are carried out separately for each clause, just as though
-the clauses had been separated out into individual import statements.
-
-The details of the first step, finding and loading modules, are
-described in greater detail in the section on the import system, which
-also describes the various types of packages and modules that can be
-imported, as well as all the hooks that can be used to customize the
-import system. Note that failures in this step may indicate either
-that the module could not be located, *or* that an error occurred
-while initializing the module, which includes execution of the
-module’s code.
-
-If the requested module is retrieved successfully, it will be made
-available in the local namespace in one of three ways:
-
-* If the module name is followed by "as", then the name following "as"
- is bound directly to the imported module.
-
-* If no other name is specified, and the module being imported is a
- top level module, the module’s name is bound in the local namespace
- as a reference to the imported module
-
-* If the module being imported is *not* a top level module, then the
- name of the top level package that contains the module is bound in
- the local namespace as a reference to the top level package. The
- imported module must be accessed using its full qualified name
- rather than directly
-
-The "from" form uses a slightly more complex process:
-
-1. find the module specified in the "from" clause, loading and
- initializing it if necessary;
-
-2. for each of the identifiers specified in the "import" clauses:
-
- 1. check if the imported module has an attribute by that name
-
- 2. if not, attempt to import a submodule with that name and then
- check the imported module again for that attribute
-
- 3. if the attribute is not found, "ImportError" is raised.
-
- 4. otherwise, a reference to that value is stored in the local
- namespace, using the name in the "as" clause if it is present,
- otherwise using the attribute name
-
-Examples:
-
- import foo # foo imported and bound locally
- import foo.bar.baz # foo, foo.bar, and foo.bar.baz imported, foo bound locally
- import foo.bar.baz as fbb # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as fbb
- from foo.bar import baz # foo, foo.bar, and foo.bar.baz imported, foo.bar.baz bound as baz
- from foo import attr # foo imported and foo.attr bound as attr
-
-If the list of identifiers is replaced by a star ("'*'"), all public
-names defined in the module are bound in the local namespace for the
-scope where the "import" statement occurs.
-
-The *public names* defined by a module are determined by checking the
-module’s namespace for a variable named "__all__"; if defined, it must
-be a sequence of strings which are names defined or imported by that
-module. The names given in "__all__" are all considered public and
-are required to exist. If "__all__" is not defined, the set of public
-names includes all names found in the module’s namespace which do not
-begin with an underscore character ("'_'"). "__all__" should contain
-the entire public API. It is intended to avoid accidentally exporting
-items that are not part of the API (such as library modules which were
-imported and used within the module).
-
-The wild card form of import — "from module import *" — is only
-allowed at the module level. Attempting to use it in class or
-function definitions will raise a "SyntaxError".
-
-When specifying what module to import you do not have to specify the
-absolute name of the module. When a module or package is contained
-within another package it is possible to make a relative import within
-the same top package without having to mention the package name. By
-using leading dots in the specified module or package after "from" you
-can specify how high to traverse up the current package hierarchy
-without specifying exact names. One leading dot means the current
-package where the module making the import exists. Two dots means up
-one package level. Three dots is up two levels, etc. So if you execute
-"from . import mod" from a module in the "pkg" package then you will
-end up importing "pkg.mod". If you execute "from ..subpkg2 import mod"
-from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The
-specification for relative imports is contained in the Package
-Relative Imports section.
-
-"importlib.import_module()" is provided to support applications that
-determine dynamically the modules to be loaded.
-
-Raises an auditing event "import" with arguments "module", "filename",
-"sys.path", "sys.meta_path", "sys.path_hooks".
-
-
-Future statements
-=================
-
-A *future statement* is a directive to the compiler that a particular
-module should be compiled using syntax or semantics that will be
-available in a specified future release of Python where the feature
-becomes standard.
-
-The future statement is intended to ease migration to future versions
-of Python that introduce incompatible changes to the language. It
-allows use of the new features on a per-module basis before the
-release in which the feature becomes standard.
-
- **future_stmt**: "from" "__future__" "import" "feature" ["as" "identifier"]
- ("," "feature" ["as" "identifier"])*
- | "from" "__future__" "import" "(" "feature" ["as" "identifier"]
- ("," "feature" ["as" "identifier"])* [","] ")"
- **feature**: "identifier"
-
-A future statement must appear near the top of the module. The only
-lines that can appear before a future statement are:
-
-* the module docstring (if any),
-
-* comments,
-
-* blank lines, and
-
-* other future statements.
-
-The only feature that requires using the future statement is
-"annotations" (see **PEP 563**).
-
-All historical features enabled by the future statement are still
-recognized by Python 3. The list includes "absolute_import",
-"division", "generators", "generator_stop", "unicode_literals",
-"print_function", "nested_scopes" and "with_statement". They are all
-redundant because they are always enabled, and only kept for backwards
-compatibility.
-
-A future statement is recognized and treated specially at compile
-time: Changes to the semantics of core constructs are often
-implemented by generating different code. It may even be the case
-that a new feature introduces new incompatible syntax (such as a new
-reserved word), in which case the compiler may need to parse the
-module differently. Such decisions cannot be pushed off until
-runtime.
-
-For any given release, the compiler knows which feature names have
-been defined, and raises a compile-time error if a future statement
-contains a feature not known to it.
-
-The direct runtime semantics are the same as for any import statement:
-there is a standard module "__future__", described later, and it will
-be imported in the usual way at the time the future statement is
-executed.
-
-The interesting runtime semantics depend on the specific feature
-enabled by the future statement.
-
-Note that there is nothing special about the statement:
-
- import __future__ [as name]
-
-That is not a future statement; it’s an ordinary import statement with
-no special semantics or syntax restrictions.
-
-Code compiled by calls to the built-in functions "exec()" and
-"compile()" that occur in a module "M" containing a future statement
-will, by default, use the new syntax or semantics associated with the
-future statement. This can be controlled by optional arguments to
-"compile()" — see the documentation of that function for details.
-
-A future statement typed at an interactive interpreter prompt will
-take effect for the rest of the interpreter session. If an
-interpreter is started with the "-i" option, is passed a script name
-to execute, and the script includes a future statement, it will be in
-effect in the interactive session started after the script is
-executed.
-
-See also:
-
- **PEP 236** - Back to the __future__
- The original proposal for the __future__ mechanism.
-''',
- 'in': r'''Membership test operations
-**************************
-
-The operators "in" and "not in" test for membership. "x in s"
-evaluates to "True" if *x* is a member of *s*, and "False" otherwise.
-"x not in s" returns the negation of "x in s". All built-in sequences
-and set types support this as well as dictionary, for which "in" tests
-whether the dictionary has a given key. For container types such as
-list, tuple, set, frozenset, dict, or collections.deque, the
-expression "x in y" is equivalent to "any(x is e or x == e for e in
-y)".
-
-For the string and bytes types, "x in y" is "True" if and only if *x*
-is a substring of *y*. An equivalent test is "y.find(x) != -1".
-Empty strings are always considered to be a substring of any other
-string, so """ in "abc"" will return "True".
-
-For user-defined classes which define the "__contains__()" method, "x
-in y" returns "True" if "y.__contains__(x)" returns a true value, and
-"False" otherwise.
-
-For user-defined classes which do not define "__contains__()" but do
-define "__iter__()", "x in y" is "True" if some value "z", for which
-the expression "x is z or x == z" is true, is produced while iterating
-over "y". If an exception is raised during the iteration, it is as if
-"in" raised that exception.
-
-Lastly, the old-style iteration protocol is tried: if a class defines
-"__getitem__()", "x in y" is "True" if and only if there is a non-
-negative integer index *i* such that "x is y[i] or x == y[i]", and no
-lower integer index raises the "IndexError" exception. (If any other
-exception is raised, it is as if "in" raised that exception).
-
-The operator "not in" is defined to have the inverse truth value of
-"in".
-''',
- 'integers': r'''Integer literals
-****************
-
-Integer literals are described by the following lexical definitions:
-
- **integer**: "decinteger" | "bininteger" | "octinteger" | "hexinteger"
- **decinteger**: "nonzerodigit" (["_"] "digit")* | "0"+ (["_"] "0")*
- **bininteger**: "0" ("b" | "B") (["_"] "bindigit")+
- **octinteger**: "0" ("o" | "O") (["_"] "octdigit")+
- **hexinteger**: "0" ("x" | "X") (["_"] "hexdigit")+
- **nonzerodigit**: "1"..."9"
- **digit**: "0"..."9"
- **bindigit**: "0" | "1"
- **octdigit**: "0"..."7"
- **hexdigit**: "digit" | "a"..."f" | "A"..."F"
-
-There is no limit for the length of integer literals apart from what
-can be stored in available memory.
-
-Underscores are ignored for determining the numeric value of the
-literal. They can be used to group digits for enhanced readability.
-One underscore can occur between digits, and after base specifiers
-like "0x".
-
-Note that leading zeros in a non-zero decimal number are not allowed.
-This is for disambiguation with C-style octal literals, which Python
-used before version 3.0.
-
-Some examples of integer literals:
-
- 7 2147483647 0o177 0b100110111
- 3 79228162514264337593543950336 0o377 0xdeadbeef
- 100_000_000_000 0b_1110_0101
-
-Changed in version 3.6: Underscores are now allowed for grouping
-purposes in literals.
-''',
- 'lambda': r'''Lambdas
-*******
-
- **lambda_expr**: "lambda" ["parameter_list"] ":" "expression"
-
-Lambda expressions (sometimes called lambda forms) are used to create
-anonymous functions. The expression "lambda parameters: expression"
-yields a function object. The unnamed object behaves like a function
-object defined with:
-
- def <lambda>(parameters):
- return expression
-
-See section Function definitions for the syntax of parameter lists.
-Note that functions created with lambda expressions cannot contain
-statements or annotations.
-''',
- 'lists': r'''List displays
-*************
-
-A list display is a possibly empty series of expressions enclosed in
-square brackets:
-
- **list_display**: "[" ["flexible_expression_list" | "comprehension"] "]"
-
-A list display yields a new list object, the contents being specified
-by either a list of expressions or a comprehension. When a comma-
-separated list of expressions is supplied, its elements are evaluated
-from left to right and placed into the list object in that order.
-When a comprehension is supplied, the list is constructed from the
-elements resulting from the comprehension.
-''',
- 'naming': r'''Naming and binding
-******************
-
-
-Binding of names
-================
-
-*Names* refer to objects. Names are introduced by name binding
-operations.
-
-The following constructs bind names:
-
-* formal parameters to functions,
-
-* class definitions,
-
-* function definitions,
-
-* assignment expressions,
-
-* targets that are identifiers if occurring in an assignment:
-
- * "for" loop header,
-
- * after "as" in a "with" statement, "except" clause, "except*"
- clause, or in the as-pattern in structural pattern matching,
-
- * in a capture pattern in structural pattern matching
-
-* "import" statements.
-
-* "type" statements.
-
-* type parameter lists.
-
-The "import" statement of the form "from ... import *" binds all names
-defined in the imported module, except those beginning with an
-underscore. This form may only be used at the module level.
-
-A target occurring in a "del" statement is also considered bound for
-this purpose (though the actual semantics are to unbind the name).
-
-Each assignment or import statement occurs within a block defined by a
-class or function definition or at the module level (the top-level
-code block).
-
-If a name is bound in a block, it is a local variable of that block,
-unless declared as "nonlocal" or "global". If a name is bound at the
-module level, it is a global variable. (The variables of the module
-code block are local and global.) If a variable is used in a code
-block but not defined there, it is a *free variable*.
-
-Each occurrence of a name in the program text refers to the *binding*
-of that name established by the following name resolution rules.
-
-
-Resolution of names
-===================
-
-A *scope* defines the visibility of a name within a block. If a local
-variable is defined in a block, its scope includes that block. If the
-definition occurs in a function block, the scope extends to any blocks
-contained within the defining one, unless a contained block introduces
-a different binding for the name.
-
-When a name is used in a code block, it is resolved using the nearest
-enclosing scope. The set of all such scopes visible to a code block
-is called the block’s *environment*.
-
-When a name is not found at all, a "NameError" exception is raised. If
-the current scope is a function scope, and the name refers to a local
-variable that has not yet been bound to a value at the point where the
-name is used, an "UnboundLocalError" exception is raised.
-"UnboundLocalError" is a subclass of "NameError".
-
-If a name binding operation occurs anywhere within a code block, all
-uses of the name within the block are treated as references to the
-current block. This can lead to errors when a name is used within a
-block before it is bound. This rule is subtle. Python lacks
-declarations and allows name binding operations to occur anywhere
-within a code block. The local variables of a code block can be
-determined by scanning the entire text of the block for name binding
-operations. See the FAQ entry on UnboundLocalError for examples.
-
-If the "global" statement occurs within a block, all uses of the names
-specified in the statement refer to the bindings of those names in the
-top-level namespace. Names are resolved in the top-level namespace by
-searching the global namespace, i.e. the namespace of the module
-containing the code block, and the builtins namespace, the namespace
-of the module "builtins". The global namespace is searched first. If
-the names are not found there, the builtins namespace is searched
-next. If the names are also not found in the builtins namespace, new
-variables are created in the global namespace. The global statement
-must precede all uses of the listed names.
-
-The "global" statement has the same scope as a name binding operation
-in the same block. If the nearest enclosing scope for a free variable
-contains a global statement, the free variable is treated as a global.
-
-The "nonlocal" statement causes corresponding names to refer to
-previously bound variables in the nearest enclosing function scope.
-"SyntaxError" is raised at compile time if the given name does not
-exist in any enclosing function scope. Type parameters cannot be
-rebound with the "nonlocal" statement.
-
-The namespace for a module is automatically created the first time a
-module is imported. The main module for a script is always called
-"__main__".
-
-Class definition blocks and arguments to "exec()" and "eval()" are
-special in the context of name resolution. A class definition is an
-executable statement that may use and define names. These references
-follow the normal rules for name resolution with an exception that
-unbound local variables are looked up in the global namespace. The
-namespace of the class definition becomes the attribute dictionary of
-the class. The scope of names defined in a class block is limited to
-the class block; it does not extend to the code blocks of methods.
-This includes comprehensions and generator expressions, but it does
-not include annotation scopes, which have access to their enclosing
-class scopes. This means that the following will fail:
-
- class A:
- a = 42
- b = list(a + i for i in range(10))
-
-However, the following will succeed:
-
- class A:
- type Alias = Nested
- class Nested: pass
-
- print(A.Alias.__value__) # <type 'A.Nested'>
-
-
-Annotation scopes
-=================
-
-*Annotations*, type parameter lists and "type" statements introduce
-*annotation scopes*, which behave mostly like function scopes, but
-with some exceptions discussed below.
-
-Annotation scopes are used in the following contexts:
-
-* *Function annotations*.
-
-* *Variable annotations*.
-
-* Type parameter lists for generic type aliases.
-
-* Type parameter lists for generic functions. A generic function’s
- annotations are executed within the annotation scope, but its
- defaults and decorators are not.
-
-* Type parameter lists for generic classes. A generic class’s base
- classes and keyword arguments are executed within the annotation
- scope, but its decorators are not.
-
-* The bounds, constraints, and default values for type parameters
- (lazily evaluated).
-
-* The value of type aliases (lazily evaluated).
-
-Annotation scopes differ from function scopes in the following ways:
-
-* Annotation scopes have access to their enclosing class namespace. If
- an annotation scope is immediately within a class scope, or within
- another annotation scope that is immediately within a class scope,
- the code in the annotation scope can use names defined in the class
- scope as if it were executed directly within the class body. This
- contrasts with regular functions defined within classes, which
- cannot access names defined in the class scope.
-
-* Expressions in annotation scopes cannot contain "yield", "yield
- from", "await", or ":=" expressions. (These expressions are allowed
- in other scopes contained within the annotation scope.)
-
-* Names defined in annotation scopes cannot be rebound with "nonlocal"
- statements in inner scopes. This includes only type parameters, as
- no other syntactic elements that can appear within annotation scopes
- can introduce new names.
-
-* While annotation scopes have an internal name, that name is not
- reflected in the *qualified name* of objects defined within the
- scope. Instead, the "__qualname__" of such objects is as if the
- object were defined in the enclosing scope.
-
-Added in version 3.12: Annotation scopes were introduced in Python
-3.12 as part of **PEP 695**.
-
-Changed in version 3.13: Annotation scopes are also used for type
-parameter defaults, as introduced by **PEP 696**.
-
-Changed in version 3.14: Annotation scopes are now also used for
-annotations, as specified in **PEP 649** and **PEP 749**.
-
-
-Lazy evaluation
-===============
-
-Most annotation scopes are *lazily evaluated*. This includes
-annotations, the values of type aliases created through the "type"
-statement, and the bounds, constraints, and default values of type
-variables created through the type parameter syntax. This means that
-they are not evaluated when the type alias or type variable is
-created, or when the object carrying annotations is created. Instead,
-they are only evaluated when necessary, for example when the
-"__value__" attribute on a type alias is accessed.
-
-Example:
-
- >>> type Alias = 1/0
- >>> Alias.__value__
- Traceback (most recent call last):
- ...
- ZeroDivisionError: division by zero
- >>> def func[T: 1/0](): pass
- >>> T = func.__type_params__[0]
- >>> T.__bound__
- Traceback (most recent call last):
- ...
- ZeroDivisionError: division by zero
-
-Here the exception is raised only when the "__value__" attribute of
-the type alias or the "__bound__" attribute of the type variable is
-accessed.
-
-This behavior is primarily useful for references to types that have
-not yet been defined when the type alias or type variable is created.
-For example, lazy evaluation enables creation of mutually recursive
-type aliases:
-
- from typing import Literal
-
- type SimpleExpr = int | Parenthesized
- type Parenthesized = tuple[Literal["("], Expr, Literal[")"]]
- type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], Expr]
-
-Lazily evaluated values are evaluated in annotation scope, which means
-that names that appear inside the lazily evaluated value are looked up
-as if they were used in the immediately enclosing scope.
-
-Added in version 3.12.
-
-
-Builtins and restricted execution
-=================================
-
-**CPython implementation detail:** Users should not touch
-"__builtins__"; it is strictly an implementation detail. Users
-wanting to override values in the builtins namespace should "import"
-the "builtins" module and modify its attributes appropriately.
-
-The builtins namespace associated with the execution of a code block
-is actually found by looking up the name "__builtins__" in its global
-namespace; this should be a dictionary or a module (in the latter case
-the module’s dictionary is used). By default, when in the "__main__"
-module, "__builtins__" is the built-in module "builtins"; when in any
-other module, "__builtins__" is an alias for the dictionary of the
-"builtins" module itself.
-
-
-Interaction with dynamic features
-=================================
-
-Name resolution of free variables occurs at runtime, not at compile
-time. This means that the following code will print 42:
-
- i = 10
- def f():
- print(i)
- i = 42
- f()
-
-The "eval()" and "exec()" functions do not have access to the full
-environment for resolving names. Names may be resolved in the local
-and global namespaces of the caller. Free variables are not resolved
-in the nearest enclosing namespace, but in the global namespace. [1]
-The "exec()" and "eval()" functions have optional arguments to
-override the global and local namespace. If only one namespace is
-specified, it is used for both.
-''',
- 'nonlocal': r'''The "nonlocal" statement
-************************
-
- **nonlocal_stmt**: "nonlocal" "identifier" ("," "identifier")*
-
-When the definition of a function or class is nested (enclosed) within
-the definitions of other functions, its nonlocal scopes are the local
-scopes of the enclosing functions. The "nonlocal" statement causes the
-listed identifiers to refer to names previously bound in nonlocal
-scopes. It allows encapsulated code to rebind such nonlocal
-identifiers. If a name is bound in more than one nonlocal scope, the
-nearest binding is used. If a name is not bound in any nonlocal scope,
-or if there is no nonlocal scope, a "SyntaxError" is raised.
-
-The "nonlocal" statement applies to the entire scope of a function or
-class body. A "SyntaxError" is raised if a variable is used or
-assigned to prior to its nonlocal declaration in the scope.
-
-See also:
-
- **PEP 3104** - Access to Names in Outer Scopes
- The specification for the "nonlocal" statement.
-
-**Programmer’s note:** "nonlocal" is a directive to the parser and
-applies only to code parsed along with it. See the note for the
-"global" statement.
-''',
- 'numbers': r'''Numeric literals
-****************
-
-There are three types of numeric literals: integers, floating-point
-numbers, and imaginary numbers. There are no complex literals
-(complex numbers can be formed by adding a real number and an
-imaginary number).
-
-Note that numeric literals do not include a sign; a phrase like "-1"
-is actually an expression composed of the unary operator ‘"-"’ and the
-literal "1".
-''',
- 'numeric-types': r'''Emulating numeric types
-***********************
-
-The following methods can be defined to emulate numeric objects.
-Methods corresponding to operations that are not supported by the
-particular kind of number implemented (e.g., bitwise operations for
-non-integral numbers) should be left undefined.
-
-object.__add__(self, other)
-object.__sub__(self, other)
-object.__mul__(self, other)
-object.__matmul__(self, other)
-object.__truediv__(self, other)
-object.__floordiv__(self, other)
-object.__mod__(self, other)
-object.__divmod__(self, other)
-object.__pow__(self, other[, modulo])
-object.__lshift__(self, other)
-object.__rshift__(self, other)
-object.__and__(self, other)
-object.__xor__(self, other)
-object.__or__(self, other)
-
- These methods are called to implement the binary arithmetic
- operations ("+", "-", "*", "@", "/", "//", "%", "divmod()",
- "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, to
- evaluate the expression "x + y", where *x* is an instance of a
- class that has an "__add__()" method, "type(x).__add__(x, y)" is
- called. The "__divmod__()" method should be the equivalent to
- using "__floordiv__()" and "__mod__()"; it should not be related to
- "__truediv__()". Note that "__pow__()" should be defined to accept
- an optional third argument if the ternary version of the built-in
- "pow()" function is to be supported.
-
- If one of those methods does not support the operation with the
- supplied arguments, it should return "NotImplemented".
-
-object.__radd__(self, other)
-object.__rsub__(self, other)
-object.__rmul__(self, other)
-object.__rmatmul__(self, other)
-object.__rtruediv__(self, other)
-object.__rfloordiv__(self, other)
-object.__rmod__(self, other)
-object.__rdivmod__(self, other)
-object.__rpow__(self, other[, modulo])
-object.__rlshift__(self, other)
-object.__rrshift__(self, other)
-object.__rand__(self, other)
-object.__rxor__(self, other)
-object.__ror__(self, other)
-
- These methods are called to implement the binary arithmetic
- operations ("+", "-", "*", "@", "/", "//", "%", "divmod()",
- "pow()", "**", "<<", ">>", "&", "^", "|") with reflected (swapped)
- operands. These functions are only called if the operands are of
- different types, when the left operand does not support the
- corresponding operation [3], or the right operand’s class is
- derived from the left operand’s class. [4] For instance, to
- evaluate the expression "x - y", where *y* is an instance of a
- class that has an "__rsub__()" method, "type(y).__rsub__(y, x)" is
- called if "type(x).__sub__(x, y)" returns "NotImplemented" or
- "type(y)" is a subclass of "type(x)". [5]
-
- Note that ternary "pow()" will not try calling "__rpow__()" (the
- coercion rules would become too complicated).
-
- Note:
-
- If the right operand’s type is a subclass of the left operand’s
- type and that subclass provides a different implementation of the
- reflected method for the operation, this method will be called
- before the left operand’s non-reflected method. This behavior
- allows subclasses to override their ancestors’ operations.
-
-object.__iadd__(self, other)
-object.__isub__(self, other)
-object.__imul__(self, other)
-object.__imatmul__(self, other)
-object.__itruediv__(self, other)
-object.__ifloordiv__(self, other)
-object.__imod__(self, other)
-object.__ipow__(self, other[, modulo])
-object.__ilshift__(self, other)
-object.__irshift__(self, other)
-object.__iand__(self, other)
-object.__ixor__(self, other)
-object.__ior__(self, other)
-
- These methods are called to implement the augmented arithmetic
- assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", "**=",
- "<<=", ">>=", "&=", "^=", "|="). These methods should attempt to
- do the operation in-place (modifying *self*) and return the result
- (which could be, but does not have to be, *self*). If a specific
- method is not defined, or if that method returns "NotImplemented",
- the augmented assignment falls back to the normal methods. For
- instance, if *x* is an instance of a class with an "__iadd__()"
- method, "x += y" is equivalent to "x = x.__iadd__(y)" . If
- "__iadd__()" does not exist, or if "x.__iadd__(y)" returns
- "NotImplemented", "x.__add__(y)" and "y.__radd__(x)" are
- considered, as with the evaluation of "x + y". In certain
- situations, augmented assignment can result in unexpected errors
- (see Why does a_tuple[i] += [‘item’] raise an exception when the
- addition works?), but this behavior is in fact part of the data
- model.
-
-object.__neg__(self)
-object.__pos__(self)
-object.__abs__(self)
-object.__invert__(self)
-
- Called to implement the unary arithmetic operations ("-", "+",
- "abs()" and "~").
-
-object.__complex__(self)
-object.__int__(self)
-object.__float__(self)
-
- Called to implement the built-in functions "complex()", "int()" and
- "float()". Should return a value of the appropriate type.
-
-object.__index__(self)
-
- Called to implement "operator.index()", and whenever Python needs
- to losslessly convert the numeric object to an integer object (such
- as in slicing, or in the built-in "bin()", "hex()" and "oct()"
- functions). Presence of this method indicates that the numeric
- object is an integer type. Must return an integer.
-
- If "__int__()", "__float__()" and "__complex__()" are not defined
- then corresponding built-in functions "int()", "float()" and
- "complex()" fall back to "__index__()".
-
-object.__round__(self[, ndigits])
-object.__trunc__(self)
-object.__floor__(self)
-object.__ceil__(self)
-
- Called to implement the built-in function "round()" and "math"
- functions "trunc()", "floor()" and "ceil()". Unless *ndigits* is
- passed to "__round__()" all these methods should return the value
- of the object truncated to an "Integral" (typically an "int").
-
- Changed in version 3.14: "int()" no longer delegates to the
- "__trunc__()" method.
-''',
- 'objects': r'''Objects, values and types
-*************************
-
-*Objects* are Python’s abstraction for data. All data in a Python
-program is represented by objects or by relations between objects. (In
-a sense, and in conformance to Von Neumann’s model of a “stored
-program computer”, code is also represented by objects.)
-
-Every object has an identity, a type and a value. An object’s
-*identity* never changes once it has been created; you may think of it
-as the object’s address in memory. The "is" operator compares the
-identity of two objects; the "id()" function returns an integer
-representing its identity.
-
-**CPython implementation detail:** For CPython, "id(x)" is the memory
-address where "x" is stored.
-
-An object’s type determines the operations that the object supports
-(e.g., “does it have a length?”) and also defines the possible values
-for objects of that type. The "type()" function returns an object’s
-type (which is an object itself). Like its identity, an object’s
-*type* is also unchangeable. [1]
-
-The *value* of some objects can change. Objects whose value can
-change are said to be *mutable*; objects whose value is unchangeable
-once they are created are called *immutable*. (The value of an
-immutable container object that contains a reference to a mutable
-object can change when the latter’s value is changed; however the
-container is still considered immutable, because the collection of
-objects it contains cannot be changed. So, immutability is not
-strictly the same as having an unchangeable value, it is more subtle.)
-An object’s mutability is determined by its type; for instance,
-numbers, strings and tuples are immutable, while dictionaries and
-lists are mutable.
-
-Objects are never explicitly destroyed; however, when they become
-unreachable they may be garbage-collected. An implementation is
-allowed to postpone garbage collection or omit it altogether — it is a
-matter of implementation quality how garbage collection is
-implemented, as long as no objects are collected that are still
-reachable.
-
-**CPython implementation detail:** CPython currently uses a reference-
-counting scheme with (optional) delayed detection of cyclically linked
-garbage, which collects most objects as soon as they become
-unreachable, but is not guaranteed to collect garbage containing
-circular references. See the documentation of the "gc" module for
-information on controlling the collection of cyclic garbage. Other
-implementations act differently and CPython may change. Do not depend
-on immediate finalization of objects when they become unreachable (so
-you should always close files explicitly).
-
-Note that the use of the implementation’s tracing or debugging
-facilities may keep objects alive that would normally be collectable.
-Also note that catching an exception with a "try"…"except" statement
-may keep objects alive.
-
-Some objects contain references to “external” resources such as open
-files or windows. It is understood that these resources are freed
-when the object is garbage-collected, but since garbage collection is
-not guaranteed to happen, such objects also provide an explicit way to
-release the external resource, usually a "close()" method. Programs
-are strongly recommended to explicitly close such objects. The
-"try"…"finally" statement and the "with" statement provide convenient
-ways to do this.
-
-Some objects contain references to other objects; these are called
-*containers*. Examples of containers are tuples, lists and
-dictionaries. The references are part of a container’s value. In
-most cases, when we talk about the value of a container, we imply the
-values, not the identities of the contained objects; however, when we
-talk about the mutability of a container, only the identities of the
-immediately contained objects are implied. So, if an immutable
-container (like a tuple) contains a reference to a mutable object, its
-value changes if that mutable object is changed.
-
-Types affect almost all aspects of object behavior. Even the
-importance of object identity is affected in some sense: for immutable
-types, operations that compute new values may actually return a
-reference to any existing object with the same type and value, while
-for mutable objects this is not allowed. For example, after "a = 1; b
-= 1", *a* and *b* may or may not refer to the same object with the
-value one, depending on the implementation. This is because "int" is
-an immutable type, so the reference to "1" can be reused. This
-behaviour depends on the implementation used, so should not be relied
-upon, but is something to be aware of when making use of object
-identity tests. However, after "c = []; d = []", *c* and *d* are
-guaranteed to refer to two different, unique, newly created empty
-lists. (Note that "e = f = []" assigns the *same* object to both *e*
-and *f*.)
-''',
- 'operator-summary': r'''Operator precedence
-*******************
-
-The following table summarizes the operator precedence in Python, from
-highest precedence (most binding) to lowest precedence (least
-binding). Operators in the same box have the same precedence. Unless
-the syntax is explicitly given, operators are binary. Operators in
-the same box group left to right (except for exponentiation and
-conditional expressions, which group from right to left).
-
-Note that comparisons, membership tests, and identity tests, all have
-the same precedence and have a left-to-right chaining feature as
-described in the Comparisons section.
-
-+-------------------------------------------------+---------------------------------------+
-| Operator | Description |
-|=================================================|=======================================|
-| "(expressions...)", "[expressions...]", "{key: | Binding or parenthesized expression, |
-| value...}", "{expressions...}" | list display, dictionary display, set |
-| | display |
-+-------------------------------------------------+---------------------------------------+
-| "x[index]", "x[index:index]", | Subscription, slicing, call, |
-| "x(arguments...)", "x.attribute" | attribute reference |
-+-------------------------------------------------+---------------------------------------+
-| "await x" | Await expression |
-+-------------------------------------------------+---------------------------------------+
-| "**" | Exponentiation [5] |
-+-------------------------------------------------+---------------------------------------+
-| "+x", "-x", "~x" | Positive, negative, bitwise NOT |
-+-------------------------------------------------+---------------------------------------+
-| "*", "@", "/", "//", "%" | Multiplication, matrix |
-| | multiplication, division, floor |
-| | division, remainder [6] |
-+-------------------------------------------------+---------------------------------------+
-| "+", "-" | Addition and subtraction |
-+-------------------------------------------------+---------------------------------------+
-| "<<", ">>" | Shifts |
-+-------------------------------------------------+---------------------------------------+
-| "&" | Bitwise AND |
-+-------------------------------------------------+---------------------------------------+
-| "^" | Bitwise XOR |
-+-------------------------------------------------+---------------------------------------+
-| "|" | Bitwise OR |
-+-------------------------------------------------+---------------------------------------+
-| "in", "not in", "is", "is not", "<", "<=", ">", | Comparisons, including membership |
-| ">=", "!=", "==" | tests and identity tests |
-+-------------------------------------------------+---------------------------------------+
-| "not x" | Boolean NOT |
-+-------------------------------------------------+---------------------------------------+
-| "and" | Boolean AND |
-+-------------------------------------------------+---------------------------------------+
-| "or" | Boolean OR |
-+-------------------------------------------------+---------------------------------------+
-| "if" – "else" | Conditional expression |
-+-------------------------------------------------+---------------------------------------+
-| "lambda" | Lambda expression |
-+-------------------------------------------------+---------------------------------------+
-| ":=" | Assignment expression |
-+-------------------------------------------------+---------------------------------------+
-
--[ Footnotes ]-
-
-[1] While "abs(x%y) < abs(y)" is true mathematically, for floats it
- may not be true numerically due to roundoff. For example, and
- assuming a platform on which a Python float is an IEEE 754 double-
- precision number, in order that "-1e-100 % 1e100" have the same
- sign as "1e100", the computed result is "-1e-100 + 1e100", which
- is numerically exactly equal to "1e100". The function
- "math.fmod()" returns a result whose sign matches the sign of the
- first argument instead, and so returns "-1e-100" in this case.
- Which approach is more appropriate depends on the application.
-
-[2] If x is very close to an exact integer multiple of y, it’s
- possible for "x//y" to be one larger than "(x-x%y)//y" due to
- rounding. In such cases, Python returns the latter result, in
- order to preserve that "divmod(x,y)[0] * y + x % y" be very close
- to "x".
-
-[3] The Unicode standard distinguishes between *code points* (e.g.
- U+0041) and *abstract characters* (e.g. “LATIN CAPITAL LETTER A”).
- While most abstract characters in Unicode are only represented
- using one code point, there is a number of abstract characters
- that can in addition be represented using a sequence of more than
- one code point. For example, the abstract character “LATIN
- CAPITAL LETTER C WITH CEDILLA” can be represented as a single
- *precomposed character* at code position U+00C7, or as a sequence
- of a *base character* at code position U+0043 (LATIN CAPITAL
- LETTER C), followed by a *combining character* at code position
- U+0327 (COMBINING CEDILLA).
-
- The comparison operators on strings compare at the level of
- Unicode code points. This may be counter-intuitive to humans. For
- example, ""\u00C7" == "\u0043\u0327"" is "False", even though both
- strings represent the same abstract character “LATIN CAPITAL
- LETTER C WITH CEDILLA”.
-
- To compare strings at the level of abstract characters (that is,
- in a way intuitive to humans), use "unicodedata.normalize()".
-
-[4] Due to automatic garbage-collection, free lists, and the dynamic
- nature of descriptors, you may notice seemingly unusual behaviour
- in certain uses of the "is" operator, like those involving
- comparisons between instance methods, or constants. Check their
- documentation for more info.
-
-[5] The power operator "**" binds less tightly than an arithmetic or
- bitwise unary operator on its right, that is, "2**-1" is "0.5".
-
-[6] The "%" operator is also used for string formatting; the same
- precedence applies.
-''',
- 'pass': r'''The "pass" statement
-********************
-
- **pass_stmt**: "pass"
-
-"pass" is a null operation — when it is executed, nothing happens. It
-is useful as a placeholder when a statement is required syntactically,
-but no code needs to be executed, for example:
-
- def f(arg): pass # a function that does nothing (yet)
-
- class C: pass # a class with no methods (yet)
-''',
- 'power': r'''The power operator
-******************
-
-The power operator binds more tightly than unary operators on its
-left; it binds less tightly than unary operators on its right. The
-syntax is:
-
- **power**: ("await_expr" | "primary") ["**" "u_expr"]
-
-Thus, in an unparenthesized sequence of power and unary operators, the
-operators are evaluated from right to left (this does not constrain
-the evaluation order for the operands): "-1**2" results in "-1".
-
-The power operator has the same semantics as the built-in "pow()"
-function, when called with two arguments: it yields its left argument
-raised to the power of its right argument. The numeric arguments are
-first converted to a common type, and the result is of that type.
-
-For int operands, the result has the same type as the operands unless
-the second argument is negative; in that case, all arguments are
-converted to float and a float result is delivered. For example,
-"10**2" returns "100", but "10**-2" returns "0.01".
-
-Raising "0.0" to a negative power results in a "ZeroDivisionError".
-Raising a negative number to a fractional power results in a "complex"
-number. (In earlier versions it raised a "ValueError".)
-
-This operation can be customized using the special "__pow__()" and
-"__rpow__()" methods.
-''',
- 'raise': r'''The "raise" statement
-*********************
-
- **raise_stmt**: "raise" ["expression" ["from" "expression"]]
-
-If no expressions are present, "raise" re-raises the exception that is
-currently being handled, which is also known as the *active
-exception*. If there isn’t currently an active exception, a
-"RuntimeError" exception is raised indicating that this is an error.
-
-Otherwise, "raise" evaluates the first expression as the exception
-object. It must be either a subclass or an instance of
-"BaseException". If it is a class, the exception instance will be
-obtained when needed by instantiating the class with no arguments.
-
-The *type* of the exception is the exception instance’s class, the
-*value* is the instance itself.
-
-A traceback object is normally created automatically when an exception
-is raised and attached to it as the "__traceback__" attribute. You can
-create an exception and set your own traceback in one step using the
-"with_traceback()" exception method (which returns the same exception
-instance, with its traceback set to its argument), like so:
-
- raise Exception("foo occurred").with_traceback(tracebackobj)
-
-The "from" clause is used for exception chaining: if given, the second
-*expression* must be another exception class or instance. If the
-second expression is an exception instance, it will be attached to the
-raised exception as the "__cause__" attribute (which is writable). If
-the expression is an exception class, the class will be instantiated
-and the resulting exception instance will be attached to the raised
-exception as the "__cause__" attribute. If the raised exception is not
-handled, both exceptions will be printed:
-
- >>> try:
- ... print(1 / 0)
- ... except Exception as exc:
- ... raise RuntimeError("Something bad happened") from exc
- ...
- Traceback (most recent call last):
- File "<stdin>", line 2, in <module>
- print(1 / 0)
- ~~^~~
- ZeroDivisionError: division by zero
-
- The above exception was the direct cause of the following exception:
-
- Traceback (most recent call last):
- File "<stdin>", line 4, in <module>
- raise RuntimeError("Something bad happened") from exc
- RuntimeError: Something bad happened
-
-A similar mechanism works implicitly if a new exception is raised when
-an exception is already being handled. An exception may be handled
-when an "except" or "finally" clause, or a "with" statement, is used.
-The previous exception is then attached as the new exception’s
-"__context__" attribute:
-
- >>> try:
- ... print(1 / 0)
- ... except:
- ... raise RuntimeError("Something bad happened")
- ...
- Traceback (most recent call last):
- File "<stdin>", line 2, in <module>
- print(1 / 0)
- ~~^~~
- ZeroDivisionError: division by zero
-
- During handling of the above exception, another exception occurred:
-
- Traceback (most recent call last):
- File "<stdin>", line 4, in <module>
- raise RuntimeError("Something bad happened")
- RuntimeError: Something bad happened
-
-Exception chaining can be explicitly suppressed by specifying "None"
-in the "from" clause:
-
- >>> try:
- ... print(1 / 0)
- ... except:
- ... raise RuntimeError("Something bad happened") from None
- ...
- Traceback (most recent call last):
- File "<stdin>", line 4, in <module>
- RuntimeError: Something bad happened
-
-Additional information on exceptions can be found in section
-Exceptions, and information about handling exceptions is in section
-The try statement.
-
-Changed in version 3.3: "None" is now permitted as "Y" in "raise X
-from Y".Added the "__suppress_context__" attribute to suppress
-automatic display of the exception context.
-
-Changed in version 3.11: If the traceback of the active exception is
-modified in an "except" clause, a subsequent "raise" statement re-
-raises the exception with the modified traceback. Previously, the
-exception was re-raised with the traceback it had when it was caught.
-''',
- 'return': r'''The "return" statement
-**********************
-
- **return_stmt**: "return" ["expression_list"]
-
-"return" may only occur syntactically nested in a function definition,
-not within a nested class definition.
-
-If an expression list is present, it is evaluated, else "None" is
-substituted.
-
-"return" leaves the current function call with the expression list (or
-"None") as return value.
-
-When "return" passes control out of a "try" statement with a "finally"
-clause, that "finally" clause is executed before really leaving the
-function.
-
-In a generator function, the "return" statement indicates that the
-generator is done and will cause "StopIteration" to be raised. The
-returned value (if any) is used as an argument to construct
-"StopIteration" and becomes the "StopIteration.value" attribute.
-
-In an asynchronous generator function, an empty "return" statement
-indicates that the asynchronous generator is done and will cause
-"StopAsyncIteration" to be raised. A non-empty "return" statement is
-a syntax error in an asynchronous generator function.
-''',
- 'sequence-types': r'''Emulating container types
-*************************
-
-The following methods can be defined to implement container objects.
-None of them are provided by the "object" class itself. Containers
-usually are *sequences* (such as "lists" or "tuples") or *mappings*
-(like *dictionaries*), but can represent other containers as well.
-The first set of methods is used either to emulate a sequence or to
-emulate a mapping; the difference is that for a sequence, the
-allowable keys should be the integers *k* for which "0 <= k < N" where
-*N* is the length of the sequence, or "slice" objects, which define a
-range of items. It is also recommended that mappings provide the
-methods "keys()", "values()", "items()", "get()", "clear()",
-"setdefault()", "pop()", "popitem()", "copy()", and "update()"
-behaving similar to those for Python’s standard "dictionary" objects.
-The "collections.abc" module provides a "MutableMapping" *abstract
-base class* to help create those methods from a base set of
-"__getitem__()", "__setitem__()", "__delitem__()", and "keys()".
-Mutable sequences should provide methods "append()", "count()",
-"index()", "extend()", "insert()", "pop()", "remove()", "reverse()"
-and "sort()", like Python standard "list" objects. Finally, sequence
-types should implement addition (meaning concatenation) and
-multiplication (meaning repetition) by defining the methods
-"__add__()", "__radd__()", "__iadd__()", "__mul__()", "__rmul__()" and
-"__imul__()" described below; they should not define other numerical
-operators. It is recommended that both mappings and sequences
-implement the "__contains__()" method to allow efficient use of the
-"in" operator; for mappings, "in" should search the mapping’s keys;
-for sequences, it should search through the values. It is further
-recommended that both mappings and sequences implement the
-"__iter__()" method to allow efficient iteration through the
-container; for mappings, "__iter__()" should iterate through the
-object’s keys; for sequences, it should iterate through the values.
-
-object.__len__(self)
-
- Called to implement the built-in function "len()". Should return
- the length of the object, an integer ">=" 0. Also, an object that
- doesn’t define a "__bool__()" method and whose "__len__()" method
- returns zero is considered to be false in a Boolean context.
-
- **CPython implementation detail:** In CPython, the length is
- required to be at most "sys.maxsize". If the length is larger than
- "sys.maxsize" some features (such as "len()") may raise
- "OverflowError". To prevent raising "OverflowError" by truth value
- testing, an object must define a "__bool__()" method.
-
-object.__length_hint__(self)
-
- Called to implement "operator.length_hint()". Should return an
- estimated length for the object (which may be greater or less than
- the actual length). The length must be an integer ">=" 0. The
- return value may also be "NotImplemented", which is treated the
- same as if the "__length_hint__" method didn’t exist at all. This
- method is purely an optimization and is never required for
- correctness.
-
- Added in version 3.4.
-
-Note:
-
- Slicing is done exclusively with the following three methods. A
- call like
-
- a[1:2] = b
-
- is translated to
-
- a[slice(1, 2, None)] = b
-
- and so forth. Missing slice items are always filled in with "None".
-
-object.__getitem__(self, key)
-
- Called to implement evaluation of "self[key]". For *sequence*
- types, the accepted keys should be integers. Optionally, they may
- support "slice" objects as well. Negative index support is also
- optional. If *key* is of an inappropriate type, "TypeError" may be
- raised; if *key* is a value outside the set of indexes for the
- sequence (after any special interpretation of negative values),
- "IndexError" should be raised. For *mapping* types, if *key* is
- missing (not in the container), "KeyError" should be raised.
-
- Note:
-
- "for" loops expect that an "IndexError" will be raised for
- illegal indexes to allow proper detection of the end of the
- sequence.
-
- Note:
-
- When subscripting a *class*, the special class method
- "__class_getitem__()" may be called instead of "__getitem__()".
- See __class_getitem__ versus __getitem__ for more details.
-
-object.__setitem__(self, key, value)
-
- Called to implement assignment to "self[key]". Same note as for
- "__getitem__()". This should only be implemented for mappings if
- the objects support changes to the values for keys, or if new keys
- can be added, or for sequences if elements can be replaced. The
- same exceptions should be raised for improper *key* values as for
- the "__getitem__()" method.
-
-object.__delitem__(self, key)
-
- Called to implement deletion of "self[key]". Same note as for
- "__getitem__()". This should only be implemented for mappings if
- the objects support removal of keys, or for sequences if elements
- can be removed from the sequence. The same exceptions should be
- raised for improper *key* values as for the "__getitem__()" method.
-
-object.__missing__(self, key)
-
- Called by "dict"."__getitem__()" to implement "self[key]" for dict
- subclasses when key is not in the dictionary.
-
-object.__iter__(self)
-
- This method is called when an *iterator* is required for a
- container. This method should return a new iterator object that can
- iterate over all the objects in the container. For mappings, it
- should iterate over the keys of the container.
-
-object.__reversed__(self)
-
- Called (if present) by the "reversed()" built-in to implement
- reverse iteration. It should return a new iterator object that
- iterates over all the objects in the container in reverse order.
-
- If the "__reversed__()" method is not provided, the "reversed()"
- built-in will fall back to using the sequence protocol ("__len__()"
- and "__getitem__()"). Objects that support the sequence protocol
- should only provide "__reversed__()" if they can provide an
- implementation that is more efficient than the one provided by
- "reversed()".
-
-The membership test operators ("in" and "not in") are normally
-implemented as an iteration through a container. However, container
-objects can supply the following special method with a more efficient
-implementation, which also does not require the object be iterable.
-
-object.__contains__(self, item)
-
- Called to implement membership test operators. Should return true
- if *item* is in *self*, false otherwise. For mapping objects, this
- should consider the keys of the mapping rather than the values or
- the key-item pairs.
-
- For objects that don’t define "__contains__()", the membership test
- first tries iteration via "__iter__()", then the old sequence
- iteration protocol via "__getitem__()", see this section in the
- language reference.
-''',
- 'shifting': r'''Shifting operations
-*******************
-
-The shifting operations have lower priority than the arithmetic
-operations:
-
- **shift_expr**: "a_expr" | "shift_expr" ("<<" | ">>") "a_expr"
-
-These operators accept integers as arguments. They shift the first
-argument to the left or right by the number of bits given by the
-second argument.
-
-The left shift operation can be customized using the special
-"__lshift__()" and "__rlshift__()" methods. The right shift operation
-can be customized using the special "__rshift__()" and "__rrshift__()"
-methods.
-
-A right shift by *n* bits is defined as floor division by "pow(2,n)".
-A left shift by *n* bits is defined as multiplication with "pow(2,n)".
-''',
- 'slicings': r'''Slicings
-********
-
-A slicing selects a range of items in a sequence object (e.g., a
-string, tuple or list). Slicings may be used as expressions or as
-targets in assignment or "del" statements. The syntax for a slicing:
-
- **slicing**: "primary" "[" "slice_list" "]"
- **slice_list**: "slice_item" ("," "slice_item")* [","]
- **slice_item**: "expression" | "proper_slice"
- **proper_slice**: ["lower_bound"] ":" ["upper_bound"] [ ":" ["stride"] ]
- **lower_bound**: "expression"
- **upper_bound**: "expression"
- **stride**: "expression"
-
-There is ambiguity in the formal syntax here: anything that looks like
-an expression list also looks like a slice list, so any subscription
-can be interpreted as a slicing. Rather than further complicating the
-syntax, this is disambiguated by defining that in this case the
-interpretation as a subscription takes priority over the
-interpretation as a slicing (this is the case if the slice list
-contains no proper slice).
-
-The semantics for a slicing are as follows. The primary is indexed
-(using the same "__getitem__()" method as normal subscription) with a
-key that is constructed from the slice list, as follows. If the slice
-list contains at least one comma, the key is a tuple containing the
-conversion of the slice items; otherwise, the conversion of the lone
-slice item is the key. The conversion of a slice item that is an
-expression is that expression. The conversion of a proper slice is a
-slice object (see section The standard type hierarchy) whose "start",
-"stop" and "step" attributes are the values of the expressions given
-as lower bound, upper bound and stride, respectively, substituting
-"None" for missing expressions.
-''',
- 'specialattrs': r'''Special Attributes
-******************
-
-The implementation adds a few special read-only attributes to several
-object types, where they are relevant. Some of these are not reported
-by the "dir()" built-in function.
-
-definition.__name__
-
- The name of the class, function, method, descriptor, or generator
- instance.
-
-definition.__qualname__
-
- The *qualified name* of the class, function, method, descriptor, or
- generator instance.
-
- Added in version 3.3.
-
-definition.__module__
-
- The name of the module in which a class or function was defined.
-
-definition.__doc__
-
- The documentation string of a class or function, or "None" if
- undefined.
-
-definition.__type_params__
-
- The type parameters of generic classes, functions, and type
- aliases. For classes and functions that are not generic, this will
- be an empty tuple.
-
- Added in version 3.12.
-''',
- 'specialnames': r'''Special method names
-********************
-
-A class can implement certain operations that are invoked by special
-syntax (such as arithmetic operations or subscripting and slicing) by
-defining methods with special names. This is Python’s approach to
-*operator overloading*, allowing classes to define their own behavior
-with respect to language operators. For instance, if a class defines
-a method named "__getitem__()", and "x" is an instance of this class,
-then "x[i]" is roughly equivalent to "type(x).__getitem__(x, i)".
-Except where mentioned, attempts to execute an operation raise an
-exception when no appropriate method is defined (typically
-"AttributeError" or "TypeError").
-
-Setting a special method to "None" indicates that the corresponding
-operation is not available. For example, if a class sets "__iter__()"
-to "None", the class is not iterable, so calling "iter()" on its
-instances will raise a "TypeError" (without falling back to
-"__getitem__()"). [2]
-
-When implementing a class that emulates any built-in type, it is
-important that the emulation only be implemented to the degree that it
-makes sense for the object being modelled. For example, some
-sequences may work well with retrieval of individual elements, but
-extracting a slice may not make sense. (One example of this is the
-"NodeList" interface in the W3C’s Document Object Model.)
-
-
-Basic customization
-===================
-
-object.__new__(cls[, ...])
-
- Called to create a new instance of class *cls*. "__new__()" is a
- static method (special-cased so you need not declare it as such)
- that takes the class of which an instance was requested as its
- first argument. The remaining arguments are those passed to the
- object constructor expression (the call to the class). The return
- value of "__new__()" should be the new object instance (usually an
- instance of *cls*).
-
- Typical implementations create a new instance of the class by
- invoking the superclass’s "__new__()" method using
- "super().__new__(cls[, ...])" with appropriate arguments and then
- modifying the newly created instance as necessary before returning
- it.
-
- If "__new__()" is invoked during object construction and it returns
- an instance of *cls*, then the new instance’s "__init__()" method
- will be invoked like "__init__(self[, ...])", where *self* is the
- new instance and the remaining arguments are the same as were
- passed to the object constructor.
-
- If "__new__()" does not return an instance of *cls*, then the new
- instance’s "__init__()" method will not be invoked.
-
- "__new__()" is intended mainly to allow subclasses of immutable
- types (like int, str, or tuple) to customize instance creation. It
- is also commonly overridden in custom metaclasses in order to
- customize class creation.
-
-object.__init__(self[, ...])
-
- Called after the instance has been created (by "__new__()"), but
- before it is returned to the caller. The arguments are those
- passed to the class constructor expression. If a base class has an
- "__init__()" method, the derived class’s "__init__()" method, if
- any, must explicitly call it to ensure proper initialization of the
- base class part of the instance; for example:
- "super().__init__([args...])".
-
- Because "__new__()" and "__init__()" work together in constructing
- objects ("__new__()" to create it, and "__init__()" to customize
- it), no non-"None" value may be returned by "__init__()"; doing so
- will cause a "TypeError" to be raised at runtime.
-
-object.__del__(self)
-
- Called when the instance is about to be destroyed. This is also
- called a finalizer or (improperly) a destructor. If a base class
- has a "__del__()" method, the derived class’s "__del__()" method,
- if any, must explicitly call it to ensure proper deletion of the
- base class part of the instance.
-
- It is possible (though not recommended!) for the "__del__()" method
- to postpone destruction of the instance by creating a new reference
- to it. This is called object *resurrection*. It is
- implementation-dependent whether "__del__()" is called a second
- time when a resurrected object is about to be destroyed; the
- current *CPython* implementation only calls it once.
-
- It is not guaranteed that "__del__()" methods are called for
- objects that still exist when the interpreter exits.
- "weakref.finalize" provides a straightforward way to register a
- cleanup function to be called when an object is garbage collected.
-
- Note:
-
- "del x" doesn’t directly call "x.__del__()" — the former
- decrements the reference count for "x" by one, and the latter is
- only called when "x"’s reference count reaches zero.
-
- **CPython implementation detail:** It is possible for a reference
- cycle to prevent the reference count of an object from going to
- zero. In this case, the cycle will be later detected and deleted
- by the *cyclic garbage collector*. A common cause of reference
- cycles is when an exception has been caught in a local variable.
- The frame’s locals then reference the exception, which references
- its own traceback, which references the locals of all frames caught
- in the traceback.
-
- See also: Documentation for the "gc" module.
-
- Warning:
-
- Due to the precarious circumstances under which "__del__()"
- methods are invoked, exceptions that occur during their execution
- are ignored, and a warning is printed to "sys.stderr" instead.
- In particular:
-
- * "__del__()" can be invoked when arbitrary code is being
- executed, including from any arbitrary thread. If "__del__()"
- needs to take a lock or invoke any other blocking resource, it
- may deadlock as the resource may already be taken by the code
- that gets interrupted to execute "__del__()".
-
- * "__del__()" can be executed during interpreter shutdown. As a
- consequence, the global variables it needs to access (including
- other modules) may already have been deleted or set to "None".
- Python guarantees that globals whose name begins with a single
- underscore are deleted from their module before other globals
- are deleted; if no other references to such globals exist, this
- may help in assuring that imported modules are still available
- at the time when the "__del__()" method is called.
-
-object.__repr__(self)
-
- Called by the "repr()" built-in function to compute the “official”
- string representation of an object. If at all possible, this
- should look like a valid Python expression that could be used to
- recreate an object with the same value (given an appropriate
- environment). If this is not possible, a string of the form
- "<...some useful description...>" should be returned. The return
- value must be a string object. If a class defines "__repr__()" but
- not "__str__()", then "__repr__()" is also used when an “informal”
- string representation of instances of that class is required.
-
- This is typically used for debugging, so it is important that the
- representation is information-rich and unambiguous. A default
- implementation is provided by the "object" class itself.
-
-object.__str__(self)
-
- Called by "str(object)", the default "__format__()" implementation,
- and the built-in function "print()", to compute the “informal” or
- nicely printable string representation of an object. The return
- value must be a str object.
-
- This method differs from "object.__repr__()" in that there is no
- expectation that "__str__()" return a valid Python expression: a
- more convenient or concise representation can be used.
-
- The default implementation defined by the built-in type "object"
- calls "object.__repr__()".
-
-object.__bytes__(self)
-
- Called by bytes to compute a byte-string representation of an
- object. This should return a "bytes" object. The "object" class
- itself does not provide this method.
-
-object.__format__(self, format_spec)
-
- Called by the "format()" built-in function, and by extension,
- evaluation of formatted string literals and the "str.format()"
- method, to produce a “formatted” string representation of an
- object. The *format_spec* argument is a string that contains a
- description of the formatting options desired. The interpretation
- of the *format_spec* argument is up to the type implementing
- "__format__()", however most classes will either delegate
- formatting to one of the built-in types, or use a similar
- formatting option syntax.
-
- See Format Specification Mini-Language for a description of the
- standard formatting syntax.
-
- The return value must be a string object.
-
- The default implementation by the "object" class should be given an
- empty *format_spec* string. It delegates to "__str__()".
-
- Changed in version 3.4: The __format__ method of "object" itself
- raises a "TypeError" if passed any non-empty string.
-
- Changed in version 3.7: "object.__format__(x, '')" is now
- equivalent to "str(x)" rather than "format(str(x), '')".
-
-object.__lt__(self, other)
-object.__le__(self, other)
-object.__eq__(self, other)
-object.__ne__(self, other)
-object.__gt__(self, other)
-object.__ge__(self, other)
-
- These are the so-called “rich comparison” methods. The
- correspondence between operator symbols and method names is as
- follows: "x<y" calls "x.__lt__(y)", "x<=y" calls "x.__le__(y)",
- "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", "x>y" calls
- "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".
-
- A rich comparison method may return the singleton "NotImplemented"
- if it does not implement the operation for a given pair of
- arguments. By convention, "False" and "True" are returned for a
- successful comparison. However, these methods can return any value,
- so if the comparison operator is used in a Boolean context (e.g.,
- in the condition of an "if" statement), Python will call "bool()"
- on the value to determine if the result is true or false.
-
- By default, "object" implements "__eq__()" by using "is", returning
- "NotImplemented" in the case of a false comparison: "True if x is y
- else NotImplemented". For "__ne__()", by default it delegates to
- "__eq__()" and inverts the result unless it is "NotImplemented".
- There are no other implied relationships among the comparison
- operators or default implementations; for example, the truth of
- "(x<y or x==y)" does not imply "x<=y". To automatically generate
- ordering operations from a single root operation, see
- "functools.total_ordering()".
-
- By default, the "object" class provides implementations consistent
- with Value comparisons: equality compares according to object
- identity, and order comparisons raise "TypeError". Each default
- method may generate these results directly, but may also return
- "NotImplemented".
-
- See the paragraph on "__hash__()" for some important notes on
- creating *hashable* objects which support custom comparison
- operations and are usable as dictionary keys.
-
- There are no swapped-argument versions of these methods (to be used
- when the left argument does not support the operation but the right
- argument does); rather, "__lt__()" and "__gt__()" are each other’s
- reflection, "__le__()" and "__ge__()" are each other’s reflection,
- and "__eq__()" and "__ne__()" are their own reflection. If the
- operands are of different types, and the right operand’s type is a
- direct or indirect subclass of the left operand’s type, the
- reflected method of the right operand has priority, otherwise the
- left operand’s method has priority. Virtual subclassing is not
- considered.
-
- When no appropriate method returns any value other than
- "NotImplemented", the "==" and "!=" operators will fall back to
- "is" and "is not", respectively.
-
-object.__hash__(self)
-
- Called by built-in function "hash()" and for operations on members
- of hashed collections including "set", "frozenset", and "dict".
- The "__hash__()" method should return an integer. The only required
- property is that objects which compare equal have the same hash
- value; it is advised to mix together the hash values of the
- components of the object that also play a part in comparison of
- objects by packing them into a tuple and hashing the tuple.
- Example:
-
- def __hash__(self):
- return hash((self.name, self.nick, self.color))
-
- Note:
-
- "hash()" truncates the value returned from an object’s custom
- "__hash__()" method to the size of a "Py_ssize_t". This is
- typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds.
- If an object’s "__hash__()" must interoperate on builds of
- different bit sizes, be sure to check the width on all supported
- builds. An easy way to do this is with "python -c "import sys;
- print(sys.hash_info.width)"".
-
- If a class does not define an "__eq__()" method it should not
- define a "__hash__()" operation either; if it defines "__eq__()"
- but not "__hash__()", its instances will not be usable as items in
- hashable collections. If a class defines mutable objects and
- implements an "__eq__()" method, it should not implement
- "__hash__()", since the implementation of *hashable* collections
- requires that a key’s hash value is immutable (if the object’s hash
- value changes, it will be in the wrong hash bucket).
-
- User-defined classes have "__eq__()" and "__hash__()" methods by
- default (inherited from the "object" class); with them, all objects
- compare unequal (except with themselves) and "x.__hash__()" returns
- an appropriate value such that "x == y" implies both that "x is y"
- and "hash(x) == hash(y)".
-
- A class that overrides "__eq__()" and does not define "__hash__()"
- will have its "__hash__()" implicitly set to "None". When the
- "__hash__()" method of a class is "None", instances of the class
- will raise an appropriate "TypeError" when a program attempts to
- retrieve their hash value, and will also be correctly identified as
- unhashable when checking "isinstance(obj,
- collections.abc.Hashable)".
-
- If a class that overrides "__eq__()" needs to retain the
- implementation of "__hash__()" from a parent class, the interpreter
- must be told this explicitly by setting "__hash__ =
- <ParentClass>.__hash__".
-
- If a class that does not override "__eq__()" wishes to suppress
- hash support, it should include "__hash__ = None" in the class
- definition. A class which defines its own "__hash__()" that
- explicitly raises a "TypeError" would be incorrectly identified as
- hashable by an "isinstance(obj, collections.abc.Hashable)" call.
-
- Note:
-
- By default, the "__hash__()" values of str and bytes objects are
- “salted” with an unpredictable random value. Although they
- remain constant within an individual Python process, they are not
- predictable between repeated invocations of Python.This is
- intended to provide protection against a denial-of-service caused
- by carefully chosen inputs that exploit the worst case
- performance of a dict insertion, *O*(*n*^2) complexity. See
- http://ocert.org/advisories/ocert-2011-003.html for
- details.Changing hash values affects the iteration order of sets.
- Python has never made guarantees about this ordering (and it
- typically varies between 32-bit and 64-bit builds).See also
- "PYTHONHASHSEED".
-
- Changed in version 3.3: Hash randomization is enabled by default.
-
-object.__bool__(self)
-
- Called to implement truth value testing and the built-in operation
- "bool()"; should return "False" or "True". When this method is not
- defined, "__len__()" is called, if it is defined, and the object is
- considered true if its result is nonzero. If a class defines
- neither "__len__()" nor "__bool__()" (which is true of the "object"
- class itself), all its instances are considered true.
-
-
-Customizing attribute access
-============================
-
-The following methods can be defined to customize the meaning of
-attribute access (use of, assignment to, or deletion of "x.name") for
-class instances.
-
-object.__getattr__(self, name)
-
- Called when the default attribute access fails with an
- "AttributeError" (either "__getattribute__()" raises an
- "AttributeError" because *name* is not an instance attribute or an
- attribute in the class tree for "self"; or "__get__()" of a *name*
- property raises "AttributeError"). This method should either
- return the (computed) attribute value or raise an "AttributeError"
- exception. The "object" class itself does not provide this method.
-
- Note that if the attribute is found through the normal mechanism,
- "__getattr__()" is not called. (This is an intentional asymmetry
- between "__getattr__()" and "__setattr__()".) This is done both for
- efficiency reasons and because otherwise "__getattr__()" would have
- no way to access other attributes of the instance. Note that at
- least for instance variables, you can take total control by not
- inserting any values in the instance attribute dictionary (but
- instead inserting them in another object). See the
- "__getattribute__()" method below for a way to actually get total
- control over attribute access.
-
-object.__getattribute__(self, name)
-
- Called unconditionally to implement attribute accesses for
- instances of the class. If the class also defines "__getattr__()",
- the latter will not be called unless "__getattribute__()" either
- calls it explicitly or raises an "AttributeError". This method
- should return the (computed) attribute value or raise an
- "AttributeError" exception. In order to avoid infinite recursion in
- this method, its implementation should always call the base class
- method with the same name to access any attributes it needs, for
- example, "object.__getattribute__(self, name)".
-
- Note:
-
- This method may still be bypassed when looking up special methods
- as the result of implicit invocation via language syntax or
- built-in functions. See Special method lookup.
-
- For certain sensitive attribute accesses, raises an auditing event
- "object.__getattr__" with arguments "obj" and "name".
-
-object.__setattr__(self, name, value)
-
- Called when an attribute assignment is attempted. This is called
- instead of the normal mechanism (i.e. store the value in the
- instance dictionary). *name* is the attribute name, *value* is the
- value to be assigned to it.
-
- If "__setattr__()" wants to assign to an instance attribute, it
- should call the base class method with the same name, for example,
- "object.__setattr__(self, name, value)".
-
- For certain sensitive attribute assignments, raises an auditing
- event "object.__setattr__" with arguments "obj", "name", "value".
-
-object.__delattr__(self, name)
-
- Like "__setattr__()" but for attribute deletion instead of
- assignment. This should only be implemented if "del obj.name" is
- meaningful for the object.
-
- For certain sensitive attribute deletions, raises an auditing event
- "object.__delattr__" with arguments "obj" and "name".
-
-object.__dir__(self)
-
- Called when "dir()" is called on the object. An iterable must be
- returned. "dir()" converts the returned iterable to a list and
- sorts it.
-
-
-Customizing module attribute access
------------------------------------
-
-Special names "__getattr__" and "__dir__" can be also used to
-customize access to module attributes. The "__getattr__" function at
-the module level should accept one argument which is the name of an
-attribute and return the computed value or raise an "AttributeError".
-If an attribute is not found on a module object through the normal
-lookup, i.e. "object.__getattribute__()", then "__getattr__" is
-searched in the module "__dict__" before raising an "AttributeError".
-If found, it is called with the attribute name and the result is
-returned.
-
-The "__dir__" function should accept no arguments, and return an
-iterable of strings that represents the names accessible on module. If
-present, this function overrides the standard "dir()" search on a
-module.
-
-For a more fine grained customization of the module behavior (setting
-attributes, properties, etc.), one can set the "__class__" attribute
-of a module object to a subclass of "types.ModuleType". For example:
-
- import sys
- from types import ModuleType
-
- class VerboseModule(ModuleType):
- def __repr__(self):
- return f'Verbose {self.__name__}'
-
- def __setattr__(self, attr, value):
- print(f'Setting {attr}...')
- super().__setattr__(attr, value)
-
- sys.modules[__name__].__class__ = VerboseModule
-
-Note:
-
- Defining module "__getattr__" and setting module "__class__" only
- affect lookups made using the attribute access syntax – directly
- accessing the module globals (whether by code within the module, or
- via a reference to the module’s globals dictionary) is unaffected.
-
-Changed in version 3.5: "__class__" module attribute is now writable.
-
-Added in version 3.7: "__getattr__" and "__dir__" module attributes.
-
-See also:
-
- **PEP 562** - Module __getattr__ and __dir__
- Describes the "__getattr__" and "__dir__" functions on modules.
-
-
-Implementing Descriptors
-------------------------
-
-The following methods only apply when an instance of the class
-containing the method (a so-called *descriptor* class) appears in an
-*owner* class (the descriptor must be in either the owner’s class
-dictionary or in the class dictionary for one of its parents). In the
-examples below, “the attribute” refers to the attribute whose name is
-the key of the property in the owner class’ "__dict__". The "object"
-class itself does not implement any of these protocols.
-
-object.__get__(self, instance, owner=None)
-
- Called to get the attribute of the owner class (class attribute
- access) or of an instance of that class (instance attribute
- access). The optional *owner* argument is the owner class, while
- *instance* is the instance that the attribute was accessed through,
- or "None" when the attribute is accessed through the *owner*.
-
- This method should return the computed attribute value or raise an
- "AttributeError" exception.
-
- **PEP 252** specifies that "__get__()" is callable with one or two
- arguments. Python’s own built-in descriptors support this
- specification; however, it is likely that some third-party tools
- have descriptors that require both arguments. Python’s own
- "__getattribute__()" implementation always passes in both arguments
- whether they are required or not.
-
-object.__set__(self, instance, value)
-
- Called to set the attribute on an instance *instance* of the owner
- class to a new value, *value*.
-
- Note, adding "__set__()" or "__delete__()" changes the kind of
- descriptor to a “data descriptor”. See Invoking Descriptors for
- more details.
-
-object.__delete__(self, instance)
-
- Called to delete the attribute on an instance *instance* of the
- owner class.
-
-Instances of descriptors may also have the "__objclass__" attribute
-present:
-
-object.__objclass__
-
- The attribute "__objclass__" is interpreted by the "inspect" module
- as specifying the class where this object was defined (setting this
- appropriately can assist in runtime introspection of dynamic class
- attributes). For callables, it may indicate that an instance of the
- given type (or a subclass) is expected or required as the first
- positional argument (for example, CPython sets this attribute for
- unbound methods that are implemented in C).
-
-
-Invoking Descriptors
---------------------
-
-In general, a descriptor is an object attribute with “binding
-behavior”, one whose attribute access has been overridden by methods
-in the descriptor protocol: "__get__()", "__set__()", and
-"__delete__()". If any of those methods are defined for an object, it
-is said to be a descriptor.
-
-The default behavior for attribute access is to get, set, or delete
-the attribute from an object’s dictionary. For instance, "a.x" has a
-lookup chain starting with "a.__dict__['x']", then
-"type(a).__dict__['x']", and continuing through the base classes of
-"type(a)" excluding metaclasses.
-
-However, if the looked-up value is an object defining one of the
-descriptor methods, then Python may override the default behavior and
-invoke the descriptor method instead. Where this occurs in the
-precedence chain depends on which descriptor methods were defined and
-how they were called.
-
-The starting point for descriptor invocation is a binding, "a.x". How
-the arguments are assembled depends on "a":
-
-Direct Call
- The simplest and least common call is when user code directly
- invokes a descriptor method: "x.__get__(a)".
-
-Instance Binding
- If binding to an object instance, "a.x" is transformed into the
- call: "type(a).__dict__['x'].__get__(a, type(a))".
-
-Class Binding
- If binding to a class, "A.x" is transformed into the call:
- "A.__dict__['x'].__get__(None, A)".
-
-Super Binding
- A dotted lookup such as "super(A, a).x" searches
- "a.__class__.__mro__" for a base class "B" following "A" and then
- returns "B.__dict__['x'].__get__(a, A)". If not a descriptor, "x"
- is returned unchanged.
-
-For instance bindings, the precedence of descriptor invocation depends
-on which descriptor methods are defined. A descriptor can define any
-combination of "__get__()", "__set__()" and "__delete__()". If it
-does not define "__get__()", then accessing the attribute will return
-the descriptor object itself unless there is a value in the object’s
-instance dictionary. If the descriptor defines "__set__()" and/or
-"__delete__()", it is a data descriptor; if it defines neither, it is
-a non-data descriptor. Normally, data descriptors define both
-"__get__()" and "__set__()", while non-data descriptors have just the
-"__get__()" method. Data descriptors with "__get__()" and "__set__()"
-(and/or "__delete__()") defined always override a redefinition in an
-instance dictionary. In contrast, non-data descriptors can be
-overridden by instances.
-
-Python methods (including those decorated with "@staticmethod" and
-"@classmethod") are implemented as non-data descriptors. Accordingly,
-instances can redefine and override methods. This allows individual
-instances to acquire behaviors that differ from other instances of the
-same class.
-
-The "property()" function is implemented as a data descriptor.
-Accordingly, instances cannot override the behavior of a property.
-
-
-__slots__
----------
-
-*__slots__* allow us to explicitly declare data members (like
-properties) and deny the creation of "__dict__" and *__weakref__*
-(unless explicitly declared in *__slots__* or available in a parent.)
-
-The space saved over using "__dict__" can be significant. Attribute
-lookup speed can be significantly improved as well.
-
-object.__slots__
-
- This class variable can be assigned a string, iterable, or sequence
- of strings with variable names used by instances. *__slots__*
- reserves space for the declared variables and prevents the
- automatic creation of "__dict__" and *__weakref__* for each
- instance.
-
-Notes on using *__slots__*:
-
-* When inheriting from a class without *__slots__*, the "__dict__" and
- *__weakref__* attribute of the instances will always be accessible.
-
-* Without a "__dict__" variable, instances cannot be assigned new
- variables not listed in the *__slots__* definition. Attempts to
- assign to an unlisted variable name raises "AttributeError". If
- dynamic assignment of new variables is desired, then add
- "'__dict__'" to the sequence of strings in the *__slots__*
- declaration.
-
-* Without a *__weakref__* variable for each instance, classes defining
- *__slots__* do not support "weak references" to its instances. If
- weak reference support is needed, then add "'__weakref__'" to the
- sequence of strings in the *__slots__* declaration.
-
-* *__slots__* are implemented at the class level by creating
- descriptors for each variable name. As a result, class attributes
- cannot be used to set default values for instance variables defined
- by *__slots__*; otherwise, the class attribute would overwrite the
- descriptor assignment.
-
-* The action of a *__slots__* declaration is not limited to the class
- where it is defined. *__slots__* declared in parents are available
- in child classes. However, instances of a child subclass will get a
- "__dict__" and *__weakref__* unless the subclass also defines
- *__slots__* (which should only contain names of any *additional*
- slots).
-
-* If a class defines a slot also defined in a base class, the instance
- variable defined by the base class slot is inaccessible (except by
- retrieving its descriptor directly from the base class). This
- renders the meaning of the program undefined. In the future, a
- check may be added to prevent this.
-
-* "TypeError" will be raised if nonempty *__slots__* are defined for a
- class derived from a ""variable-length" built-in type" such as
- "int", "bytes", and "tuple".
-
-* Any non-string *iterable* may be assigned to *__slots__*.
-
-* If a "dictionary" is used to assign *__slots__*, the dictionary keys
- will be used as the slot names. The values of the dictionary can be
- used to provide per-attribute docstrings that will be recognised by
- "inspect.getdoc()" and displayed in the output of "help()".
-
-* "__class__" assignment works only if both classes have the same
- *__slots__*.
-
-* Multiple inheritance with multiple slotted parent classes can be
- used, but only one parent is allowed to have attributes created by
- slots (the other bases must have empty slot layouts) - violations
- raise "TypeError".
-
-* If an *iterator* is used for *__slots__* then a *descriptor* is
- created for each of the iterator’s values. However, the *__slots__*
- attribute will be an empty iterator.
-
-
-Customizing class creation
-==========================
-
-Whenever a class inherits from another class, "__init_subclass__()" is
-called on the parent class. This way, it is possible to write classes
-which change the behavior of subclasses. This is closely related to
-class decorators, but where class decorators only affect the specific
-class they’re applied to, "__init_subclass__" solely applies to future
-subclasses of the class defining the method.
-
-classmethod object.__init_subclass__(cls)
-
- This method is called whenever the containing class is subclassed.
- *cls* is then the new subclass. If defined as a normal instance
- method, this method is implicitly converted to a class method.
-
- Keyword arguments which are given to a new class are passed to the
- parent class’s "__init_subclass__". For compatibility with other
- classes using "__init_subclass__", one should take out the needed
- keyword arguments and pass the others over to the base class, as
- in:
-
- class Philosopher:
- def __init_subclass__(cls, /, default_name, **kwargs):
- super().__init_subclass__(**kwargs)
- cls.default_name = default_name
-
- class AustralianPhilosopher(Philosopher, default_name="Bruce"):
- pass
-
- The default implementation "object.__init_subclass__" does nothing,
- but raises an error if it is called with any arguments.
-
- Note:
-
- The metaclass hint "metaclass" is consumed by the rest of the
- type machinery, and is never passed to "__init_subclass__"
- implementations. The actual metaclass (rather than the explicit
- hint) can be accessed as "type(cls)".
-
- Added in version 3.6.
-
-When a class is created, "type.__new__()" scans the class variables
-and makes callbacks to those with a "__set_name__()" hook.
-
-object.__set_name__(self, owner, name)
-
- Automatically called at the time the owning class *owner* is
- created. The object has been assigned to *name* in that class:
-
- class A:
- x = C() # Automatically calls: x.__set_name__(A, 'x')
-
- If the class variable is assigned after the class is created,
- "__set_name__()" will not be called automatically. If needed,
- "__set_name__()" can be called directly:
-
- class A:
- pass
-
- c = C()
- A.x = c # The hook is not called
- c.__set_name__(A, 'x') # Manually invoke the hook
-
- See Creating the class object for more details.
-
- Added in version 3.6.
-
-
-Metaclasses
------------
-
-By default, classes are constructed using "type()". The class body is
-executed in a new namespace and the class name is bound locally to the
-result of "type(name, bases, namespace)".
-
-The class creation process can be customized by passing the
-"metaclass" keyword argument in the class definition line, or by
-inheriting from an existing class that included such an argument. In
-the following example, both "MyClass" and "MySubclass" are instances
-of "Meta":
-
- class Meta(type):
- pass
-
- class MyClass(metaclass=Meta):
- pass
-
- class MySubclass(MyClass):
- pass
-
-Any other keyword arguments that are specified in the class definition
-are passed through to all metaclass operations described below.
-
-When a class definition is executed, the following steps occur:
-
-* MRO entries are resolved;
-
-* the appropriate metaclass is determined;
-
-* the class namespace is prepared;
-
-* the class body is executed;
-
-* the class object is created.
-
-
-Resolving MRO entries
----------------------
-
-object.__mro_entries__(self, bases)
-
- If a base that appears in a class definition is not an instance of
- "type", then an "__mro_entries__()" method is searched on the base.
- If an "__mro_entries__()" method is found, the base is substituted
- with the result of a call to "__mro_entries__()" when creating the
- class. The method is called with the original bases tuple passed to
- the *bases* parameter, and must return a tuple of classes that will
- be used instead of the base. The returned tuple may be empty: in
- these cases, the original base is ignored.
-
-See also:
-
- "types.resolve_bases()"
- Dynamically resolve bases that are not instances of "type".
-
- "types.get_original_bases()"
- Retrieve a class’s “original bases” prior to modifications by
- "__mro_entries__()".
-
- **PEP 560**
- Core support for typing module and generic types.
-
-
-Determining the appropriate metaclass
--------------------------------------
-
-The appropriate metaclass for a class definition is determined as
-follows:
-
-* if no bases and no explicit metaclass are given, then "type()" is
- used;
-
-* if an explicit metaclass is given and it is *not* an instance of
- "type()", then it is used directly as the metaclass;
-
-* if an instance of "type()" is given as the explicit metaclass, or
- bases are defined, then the most derived metaclass is used.
-
-The most derived metaclass is selected from the explicitly specified
-metaclass (if any) and the metaclasses (i.e. "type(cls)") of all
-specified base classes. The most derived metaclass is one which is a
-subtype of *all* of these candidate metaclasses. If none of the
-candidate metaclasses meets that criterion, then the class definition
-will fail with "TypeError".
-
-
-Preparing the class namespace
------------------------------
-
-Once the appropriate metaclass has been identified, then the class
-namespace is prepared. If the metaclass has a "__prepare__" attribute,
-it is called as "namespace = metaclass.__prepare__(name, bases,
-**kwds)" (where the additional keyword arguments, if any, come from
-the class definition). The "__prepare__" method should be implemented
-as a "classmethod". The namespace returned by "__prepare__" is passed
-in to "__new__", but when the final class object is created the
-namespace is copied into a new "dict".
-
-If the metaclass has no "__prepare__" attribute, then the class
-namespace is initialised as an empty ordered mapping.
-
-See also:
-
- **PEP 3115** - Metaclasses in Python 3000
- Introduced the "__prepare__" namespace hook
-
-
-Executing the class body
-------------------------
-
-The class body is executed (approximately) as "exec(body, globals(),
-namespace)". The key difference from a normal call to "exec()" is that
-lexical scoping allows the class body (including any methods) to
-reference names from the current and outer scopes when the class
-definition occurs inside a function.
-
-However, even when the class definition occurs inside the function,
-methods defined inside the class still cannot see names defined at the
-class scope. Class variables must be accessed through the first
-parameter of instance or class methods, or through the implicit
-lexically scoped "__class__" reference described in the next section.
-
-
-Creating the class object
--------------------------
-
-Once the class namespace has been populated by executing the class
-body, the class object is created by calling "metaclass(name, bases,
-namespace, **kwds)" (the additional keywords passed here are the same
-as those passed to "__prepare__").
-
-This class object is the one that will be referenced by the zero-
-argument form of "super()". "__class__" is an implicit closure
-reference created by the compiler if any methods in a class body refer
-to either "__class__" or "super". This allows the zero argument form
-of "super()" to correctly identify the class being defined based on
-lexical scoping, while the class or instance that was used to make the
-current call is identified based on the first argument passed to the
-method.
-
-**CPython implementation detail:** In CPython 3.6 and later, the
-"__class__" cell is passed to the metaclass as a "__classcell__" entry
-in the class namespace. If present, this must be propagated up to the
-"type.__new__" call in order for the class to be initialised
-correctly. Failing to do so will result in a "RuntimeError" in Python
-3.8.
-
-When using the default metaclass "type", or any metaclass that
-ultimately calls "type.__new__", the following additional
-customization steps are invoked after creating the class object:
-
-1. The "type.__new__" method collects all of the attributes in the
- class namespace that define a "__set_name__()" method;
-
-2. Those "__set_name__" methods are called with the class being
- defined and the assigned name of that particular attribute;
-
-3. The "__init_subclass__()" hook is called on the immediate parent of
- the new class in its method resolution order.
-
-After the class object is created, it is passed to the class
-decorators included in the class definition (if any) and the resulting
-object is bound in the local namespace as the defined class.
-
-When a new class is created by "type.__new__", the object provided as
-the namespace parameter is copied to a new ordered mapping and the
-original object is discarded. The new copy is wrapped in a read-only
-proxy, which becomes the "__dict__" attribute of the class object.
-
-See also:
-
- **PEP 3135** - New super
- Describes the implicit "__class__" closure reference
-
-
-Uses for metaclasses
---------------------
-
-The potential uses for metaclasses are boundless. Some ideas that have
-been explored include enum, logging, interface checking, automatic
-delegation, automatic property creation, proxies, frameworks, and
-automatic resource locking/synchronization.
-
-
-Customizing instance and subclass checks
-========================================
-
-The following methods are used to override the default behavior of the
-"isinstance()" and "issubclass()" built-in functions.
-
-In particular, the metaclass "abc.ABCMeta" implements these methods in
-order to allow the addition of Abstract Base Classes (ABCs) as
-“virtual base classes” to any class or type (including built-in
-types), including other ABCs.
-
-type.__instancecheck__(self, instance)
-
- Return true if *instance* should be considered a (direct or
- indirect) instance of *class*. If defined, called to implement
- "isinstance(instance, class)".
-
-type.__subclasscheck__(self, subclass)
-
- Return true if *subclass* should be considered a (direct or
- indirect) subclass of *class*. If defined, called to implement
- "issubclass(subclass, class)".
-
-Note that these methods are looked up on the type (metaclass) of a
-class. They cannot be defined as class methods in the actual class.
-This is consistent with the lookup of special methods that are called
-on instances, only in this case the instance is itself a class.
-
-See also:
-
- **PEP 3119** - Introducing Abstract Base Classes
- Includes the specification for customizing "isinstance()" and
- "issubclass()" behavior through "__instancecheck__()" and
- "__subclasscheck__()", with motivation for this functionality in
- the context of adding Abstract Base Classes (see the "abc"
- module) to the language.
-
-
-Emulating generic types
-=======================
-
-When using *type annotations*, it is often useful to *parameterize* a
-*generic type* using Python’s square-brackets notation. For example,
-the annotation "list[int]" might be used to signify a "list" in which
-all the elements are of type "int".
-
-See also:
-
- **PEP 484** - Type Hints
- Introducing Python’s framework for type annotations
-
- Generic Alias Types
- Documentation for objects representing parameterized generic
- classes
-
- Generics, user-defined generics and "typing.Generic"
- Documentation on how to implement generic classes that can be
- parameterized at runtime and understood by static type-checkers.
-
-A class can *generally* only be parameterized if it defines the
-special class method "__class_getitem__()".
-
-classmethod object.__class_getitem__(cls, key)
-
- Return an object representing the specialization of a generic class
- by type arguments found in *key*.
-
- When defined on a class, "__class_getitem__()" is automatically a
- class method. As such, there is no need for it to be decorated with
- "@classmethod" when it is defined.
-
-
-The purpose of *__class_getitem__*
-----------------------------------
-
-The purpose of "__class_getitem__()" is to allow runtime
-parameterization of standard-library generic classes in order to more
-easily apply *type hints* to these classes.
-
-To implement custom generic classes that can be parameterized at
-runtime and understood by static type-checkers, users should either
-inherit from a standard library class that already implements
-"__class_getitem__()", or inherit from "typing.Generic", which has its
-own implementation of "__class_getitem__()".
-
-Custom implementations of "__class_getitem__()" on classes defined
-outside of the standard library may not be understood by third-party
-type-checkers such as mypy. Using "__class_getitem__()" on any class
-for purposes other than type hinting is discouraged.
-
-
-*__class_getitem__* versus *__getitem__*
-----------------------------------------
-
-Usually, the subscription of an object using square brackets will call
-the "__getitem__()" instance method defined on the object’s class.
-However, if the object being subscribed is itself a class, the class
-method "__class_getitem__()" may be called instead.
-"__class_getitem__()" should return a GenericAlias object if it is
-properly defined.
-
-Presented with the *expression* "obj[x]", the Python interpreter
-follows something like the following process to decide whether
-"__getitem__()" or "__class_getitem__()" should be called:
-
- from inspect import isclass
-
- def subscribe(obj, x):
- """Return the result of the expression 'obj[x]'"""
-
- class_of_obj = type(obj)
-
- # If the class of obj defines __getitem__,
- # call class_of_obj.__getitem__(obj, x)
- if hasattr(class_of_obj, '__getitem__'):
- return class_of_obj.__getitem__(obj, x)
-
- # Else, if obj is a class and defines __class_getitem__,
- # call obj.__class_getitem__(x)
- elif isclass(obj) and hasattr(obj, '__class_getitem__'):
- return obj.__class_getitem__(x)
-
- # Else, raise an exception
- else:
- raise TypeError(
- f"'{class_of_obj.__name__}' object is not subscriptable"
- )
-
-In Python, all classes are themselves instances of other classes. The
-class of a class is known as that class’s *metaclass*, and most
-classes have the "type" class as their metaclass. "type" does not
-define "__getitem__()", meaning that expressions such as "list[int]",
-"dict[str, float]" and "tuple[str, bytes]" all result in
-"__class_getitem__()" being called:
-
- >>> # list has class "type" as its metaclass, like most classes:
- >>> type(list)
- <class 'type'>
- >>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
- True
- >>> # "list[int]" calls "list.__class_getitem__(int)"
- >>> list[int]
- list[int]
- >>> # list.__class_getitem__ returns a GenericAlias object:
- >>> type(list[int])
- <class 'types.GenericAlias'>
-
-However, if a class has a custom metaclass that defines
-"__getitem__()", subscribing the class may result in different
-behaviour. An example of this can be found in the "enum" module:
-
- >>> from enum import Enum
- >>> class Menu(Enum):
- ... """A breakfast menu"""
- ... SPAM = 'spam'
- ... BACON = 'bacon'
- ...
- >>> # Enum classes have a custom metaclass:
- >>> type(Menu)
- <class 'enum.EnumMeta'>
- >>> # EnumMeta defines __getitem__,
- >>> # so __class_getitem__ is not called,
- >>> # and the result is not a GenericAlias object:
- >>> Menu['SPAM']
- <Menu.SPAM: 'spam'>
- >>> type(Menu['SPAM'])
- <enum 'Menu'>
-
-See also:
-
- **PEP 560** - Core Support for typing module and generic types
- Introducing "__class_getitem__()", and outlining when a
- subscription results in "__class_getitem__()" being called
- instead of "__getitem__()"
-
-
-Emulating callable objects
-==========================
-
-object.__call__(self[, args...])
-
- Called when the instance is “called” as a function; if this method
- is defined, "x(arg1, arg2, ...)" roughly translates to
- "type(x).__call__(x, arg1, ...)". The "object" class itself does
- not provide this method.
-
-
-Emulating container types
-=========================
-
-The following methods can be defined to implement container objects.
-None of them are provided by the "object" class itself. Containers
-usually are *sequences* (such as "lists" or "tuples") or *mappings*
-(like *dictionaries*), but can represent other containers as well.
-The first set of methods is used either to emulate a sequence or to
-emulate a mapping; the difference is that for a sequence, the
-allowable keys should be the integers *k* for which "0 <= k < N" where
-*N* is the length of the sequence, or "slice" objects, which define a
-range of items. It is also recommended that mappings provide the
-methods "keys()", "values()", "items()", "get()", "clear()",
-"setdefault()", "pop()", "popitem()", "copy()", and "update()"
-behaving similar to those for Python’s standard "dictionary" objects.
-The "collections.abc" module provides a "MutableMapping" *abstract
-base class* to help create those methods from a base set of
-"__getitem__()", "__setitem__()", "__delitem__()", and "keys()".
-Mutable sequences should provide methods "append()", "count()",
-"index()", "extend()", "insert()", "pop()", "remove()", "reverse()"
-and "sort()", like Python standard "list" objects. Finally, sequence
-types should implement addition (meaning concatenation) and
-multiplication (meaning repetition) by defining the methods
-"__add__()", "__radd__()", "__iadd__()", "__mul__()", "__rmul__()" and
-"__imul__()" described below; they should not define other numerical
-operators. It is recommended that both mappings and sequences
-implement the "__contains__()" method to allow efficient use of the
-"in" operator; for mappings, "in" should search the mapping’s keys;
-for sequences, it should search through the values. It is further
-recommended that both mappings and sequences implement the
-"__iter__()" method to allow efficient iteration through the
-container; for mappings, "__iter__()" should iterate through the
-object’s keys; for sequences, it should iterate through the values.
-
-object.__len__(self)
-
- Called to implement the built-in function "len()". Should return
- the length of the object, an integer ">=" 0. Also, an object that
- doesn’t define a "__bool__()" method and whose "__len__()" method
- returns zero is considered to be false in a Boolean context.
-
- **CPython implementation detail:** In CPython, the length is
- required to be at most "sys.maxsize". If the length is larger than
- "sys.maxsize" some features (such as "len()") may raise
- "OverflowError". To prevent raising "OverflowError" by truth value
- testing, an object must define a "__bool__()" method.
-
-object.__length_hint__(self)
-
- Called to implement "operator.length_hint()". Should return an
- estimated length for the object (which may be greater or less than
- the actual length). The length must be an integer ">=" 0. The
- return value may also be "NotImplemented", which is treated the
- same as if the "__length_hint__" method didn’t exist at all. This
- method is purely an optimization and is never required for
- correctness.
-
- Added in version 3.4.
-
-Note:
-
- Slicing is done exclusively with the following three methods. A
- call like
-
- a[1:2] = b
-
- is translated to
-
- a[slice(1, 2, None)] = b
-
- and so forth. Missing slice items are always filled in with "None".
-
-object.__getitem__(self, key)
-
- Called to implement evaluation of "self[key]". For *sequence*
- types, the accepted keys should be integers. Optionally, they may
- support "slice" objects as well. Negative index support is also
- optional. If *key* is of an inappropriate type, "TypeError" may be
- raised; if *key* is a value outside the set of indexes for the
- sequence (after any special interpretation of negative values),
- "IndexError" should be raised. For *mapping* types, if *key* is
- missing (not in the container), "KeyError" should be raised.
-
- Note:
-
- "for" loops expect that an "IndexError" will be raised for
- illegal indexes to allow proper detection of the end of the
- sequence.
-
- Note:
-
- When subscripting a *class*, the special class method
- "__class_getitem__()" may be called instead of "__getitem__()".
- See __class_getitem__ versus __getitem__ for more details.
-
-object.__setitem__(self, key, value)
-
- Called to implement assignment to "self[key]". Same note as for
- "__getitem__()". This should only be implemented for mappings if
- the objects support changes to the values for keys, or if new keys
- can be added, or for sequences if elements can be replaced. The
- same exceptions should be raised for improper *key* values as for
- the "__getitem__()" method.
-
-object.__delitem__(self, key)
-
- Called to implement deletion of "self[key]". Same note as for
- "__getitem__()". This should only be implemented for mappings if
- the objects support removal of keys, or for sequences if elements
- can be removed from the sequence. The same exceptions should be
- raised for improper *key* values as for the "__getitem__()" method.
-
-object.__missing__(self, key)
-
- Called by "dict"."__getitem__()" to implement "self[key]" for dict
- subclasses when key is not in the dictionary.
-
-object.__iter__(self)
-
- This method is called when an *iterator* is required for a
- container. This method should return a new iterator object that can
- iterate over all the objects in the container. For mappings, it
- should iterate over the keys of the container.
-
-object.__reversed__(self)
-
- Called (if present) by the "reversed()" built-in to implement
- reverse iteration. It should return a new iterator object that
- iterates over all the objects in the container in reverse order.
-
- If the "__reversed__()" method is not provided, the "reversed()"
- built-in will fall back to using the sequence protocol ("__len__()"
- and "__getitem__()"). Objects that support the sequence protocol
- should only provide "__reversed__()" if they can provide an
- implementation that is more efficient than the one provided by
- "reversed()".
-
-The membership test operators ("in" and "not in") are normally
-implemented as an iteration through a container. However, container
-objects can supply the following special method with a more efficient
-implementation, which also does not require the object be iterable.
-
-object.__contains__(self, item)
-
- Called to implement membership test operators. Should return true
- if *item* is in *self*, false otherwise. For mapping objects, this
- should consider the keys of the mapping rather than the values or
- the key-item pairs.
-
- For objects that don’t define "__contains__()", the membership test
- first tries iteration via "__iter__()", then the old sequence
- iteration protocol via "__getitem__()", see this section in the
- language reference.
-
-
-Emulating numeric types
-=======================
-
-The following methods can be defined to emulate numeric objects.
-Methods corresponding to operations that are not supported by the
-particular kind of number implemented (e.g., bitwise operations for
-non-integral numbers) should be left undefined.
-
-object.__add__(self, other)
-object.__sub__(self, other)
-object.__mul__(self, other)
-object.__matmul__(self, other)
-object.__truediv__(self, other)
-object.__floordiv__(self, other)
-object.__mod__(self, other)
-object.__divmod__(self, other)
-object.__pow__(self, other[, modulo])
-object.__lshift__(self, other)
-object.__rshift__(self, other)
-object.__and__(self, other)
-object.__xor__(self, other)
-object.__or__(self, other)
-
- These methods are called to implement the binary arithmetic
- operations ("+", "-", "*", "@", "/", "//", "%", "divmod()",
- "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, to
- evaluate the expression "x + y", where *x* is an instance of a
- class that has an "__add__()" method, "type(x).__add__(x, y)" is
- called. The "__divmod__()" method should be the equivalent to
- using "__floordiv__()" and "__mod__()"; it should not be related to
- "__truediv__()". Note that "__pow__()" should be defined to accept
- an optional third argument if the ternary version of the built-in
- "pow()" function is to be supported.
-
- If one of those methods does not support the operation with the
- supplied arguments, it should return "NotImplemented".
-
-object.__radd__(self, other)
-object.__rsub__(self, other)
-object.__rmul__(self, other)
-object.__rmatmul__(self, other)
-object.__rtruediv__(self, other)
-object.__rfloordiv__(self, other)
-object.__rmod__(self, other)
-object.__rdivmod__(self, other)
-object.__rpow__(self, other[, modulo])
-object.__rlshift__(self, other)
-object.__rrshift__(self, other)
-object.__rand__(self, other)
-object.__rxor__(self, other)
-object.__ror__(self, other)
-
- These methods are called to implement the binary arithmetic
- operations ("+", "-", "*", "@", "/", "//", "%", "divmod()",
- "pow()", "**", "<<", ">>", "&", "^", "|") with reflected (swapped)
- operands. These functions are only called if the operands are of
- different types, when the left operand does not support the
- corresponding operation [3], or the right operand’s class is
- derived from the left operand’s class. [4] For instance, to
- evaluate the expression "x - y", where *y* is an instance of a
- class that has an "__rsub__()" method, "type(y).__rsub__(y, x)" is
- called if "type(x).__sub__(x, y)" returns "NotImplemented" or
- "type(y)" is a subclass of "type(x)". [5]
-
- Note that ternary "pow()" will not try calling "__rpow__()" (the
- coercion rules would become too complicated).
-
- Note:
-
- If the right operand’s type is a subclass of the left operand’s
- type and that subclass provides a different implementation of the
- reflected method for the operation, this method will be called
- before the left operand’s non-reflected method. This behavior
- allows subclasses to override their ancestors’ operations.
-
-object.__iadd__(self, other)
-object.__isub__(self, other)
-object.__imul__(self, other)
-object.__imatmul__(self, other)
-object.__itruediv__(self, other)
-object.__ifloordiv__(self, other)
-object.__imod__(self, other)
-object.__ipow__(self, other[, modulo])
-object.__ilshift__(self, other)
-object.__irshift__(self, other)
-object.__iand__(self, other)
-object.__ixor__(self, other)
-object.__ior__(self, other)
-
- These methods are called to implement the augmented arithmetic
- assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", "**=",
- "<<=", ">>=", "&=", "^=", "|="). These methods should attempt to
- do the operation in-place (modifying *self*) and return the result
- (which could be, but does not have to be, *self*). If a specific
- method is not defined, or if that method returns "NotImplemented",
- the augmented assignment falls back to the normal methods. For
- instance, if *x* is an instance of a class with an "__iadd__()"
- method, "x += y" is equivalent to "x = x.__iadd__(y)" . If
- "__iadd__()" does not exist, or if "x.__iadd__(y)" returns
- "NotImplemented", "x.__add__(y)" and "y.__radd__(x)" are
- considered, as with the evaluation of "x + y". In certain
- situations, augmented assignment can result in unexpected errors
- (see Why does a_tuple[i] += [‘item’] raise an exception when the
- addition works?), but this behavior is in fact part of the data
- model.
-
-object.__neg__(self)
-object.__pos__(self)
-object.__abs__(self)
-object.__invert__(self)
-
- Called to implement the unary arithmetic operations ("-", "+",
- "abs()" and "~").
-
-object.__complex__(self)
-object.__int__(self)
-object.__float__(self)
-
- Called to implement the built-in functions "complex()", "int()" and
- "float()". Should return a value of the appropriate type.
-
-object.__index__(self)
-
- Called to implement "operator.index()", and whenever Python needs
- to losslessly convert the numeric object to an integer object (such
- as in slicing, or in the built-in "bin()", "hex()" and "oct()"
- functions). Presence of this method indicates that the numeric
- object is an integer type. Must return an integer.
-
- If "__int__()", "__float__()" and "__complex__()" are not defined
- then corresponding built-in functions "int()", "float()" and
- "complex()" fall back to "__index__()".
-
-object.__round__(self[, ndigits])
-object.__trunc__(self)
-object.__floor__(self)
-object.__ceil__(self)
-
- Called to implement the built-in function "round()" and "math"
- functions "trunc()", "floor()" and "ceil()". Unless *ndigits* is
- passed to "__round__()" all these methods should return the value
- of the object truncated to an "Integral" (typically an "int").
-
- Changed in version 3.14: "int()" no longer delegates to the
- "__trunc__()" method.
-
-
-With Statement Context Managers
-===============================
-
-A *context manager* is an object that defines the runtime context to
-be established when executing a "with" statement. The context manager
-handles the entry into, and the exit from, the desired runtime context
-for the execution of the block of code. Context managers are normally
-invoked using the "with" statement (described in section The with
-statement), but can also be used by directly invoking their methods.
-
-Typical uses of context managers include saving and restoring various
-kinds of global state, locking and unlocking resources, closing opened
-files, etc.
-
-For more information on context managers, see Context Manager Types.
-The "object" class itself does not provide the context manager
-methods.
-
-object.__enter__(self)
-
- Enter the runtime context related to this object. The "with"
- statement will bind this method’s return value to the target(s)
- specified in the "as" clause of the statement, if any.
-
-object.__exit__(self, exc_type, exc_value, traceback)
-
- Exit the runtime context related to this object. The parameters
- describe the exception that caused the context to be exited. If the
- context was exited without an exception, all three arguments will
- be "None".
-
- If an exception is supplied, and the method wishes to suppress the
- exception (i.e., prevent it from being propagated), it should
- return a true value. Otherwise, the exception will be processed
- normally upon exit from this method.
-
- Note that "__exit__()" methods should not reraise the passed-in
- exception; this is the caller’s responsibility.
-
-See also:
-
- **PEP 343** - The “with” statement
- The specification, background, and examples for the Python "with"
- statement.
-
-
-Customizing positional arguments in class pattern matching
-==========================================================
-
-When using a class name in a pattern, positional arguments in the
-pattern are not allowed by default, i.e. "case MyClass(x, y)" is
-typically invalid without special support in "MyClass". To be able to
-use that kind of pattern, the class needs to define a *__match_args__*
-attribute.
-
-object.__match_args__
-
- This class variable can be assigned a tuple of strings. When this
- class is used in a class pattern with positional arguments, each
- positional argument will be converted into a keyword argument,
- using the corresponding value in *__match_args__* as the keyword.
- The absence of this attribute is equivalent to setting it to "()".
-
-For example, if "MyClass.__match_args__" is "("left", "center",
-"right")" that means that "case MyClass(x, y)" is equivalent to "case
-MyClass(left=x, center=y)". Note that the number of arguments in the
-pattern must be smaller than or equal to the number of elements in
-*__match_args__*; if it is larger, the pattern match attempt will
-raise a "TypeError".
-
-Added in version 3.10.
-
-See also:
-
- **PEP 634** - Structural Pattern Matching
- The specification for the Python "match" statement.
-
-
-Emulating buffer types
-======================
-
-The buffer protocol provides a way for Python objects to expose
-efficient access to a low-level memory array. This protocol is
-implemented by builtin types such as "bytes" and "memoryview", and
-third-party libraries may define additional buffer types.
-
-While buffer types are usually implemented in C, it is also possible
-to implement the protocol in Python.
-
-object.__buffer__(self, flags)
-
- Called when a buffer is requested from *self* (for example, by the
- "memoryview" constructor). The *flags* argument is an integer
- representing the kind of buffer requested, affecting for example
- whether the returned buffer is read-only or writable.
- "inspect.BufferFlags" provides a convenient way to interpret the
- flags. The method must return a "memoryview" object.
-
-object.__release_buffer__(self, buffer)
-
- Called when a buffer is no longer needed. The *buffer* argument is
- a "memoryview" object that was previously returned by
- "__buffer__()". The method must release any resources associated
- with the buffer. This method should return "None". Buffer objects
- that do not need to perform any cleanup are not required to
- implement this method.
-
-Added in version 3.12.
-
-See also:
-
- **PEP 688** - Making the buffer protocol accessible in Python
- Introduces the Python "__buffer__" and "__release_buffer__"
- methods.
-
- "collections.abc.Buffer"
- ABC for buffer types.
-
-
-Annotations
-===========
-
-Functions, classes, and modules may contain *annotations*, which are a
-way to associate information (usually *type hints*) with a symbol.
-
-object.__annotations__
-
- This attribute contains the annotations for an object. It is lazily
- evaluated, so accessing the attribute may execute arbitrary code
- and raise exceptions. If evaluation is successful, the attribute is
- set to a dictionary mapping from variable names to annotations.
-
- Changed in version 3.14: Annotations are now lazily evaluated.
-
-object.__annotate__(format)
-
- An *annotate function*. Returns a new dictionary object mapping
- attribute/parameter names to their annotation values.
-
- Takes a format parameter specifying the format in which annotations
- values should be provided. It must be a member of the
- "annotationlib.Format" enum, or an integer with a value
- corresponding to a member of the enum.
-
- If an annotate function doesn’t support the requested format, it
- must raise "NotImplementedError". Annotate functions must always
- support "VALUE" format; they must not raise "NotImplementedError()"
- when called with this format.
-
- When called with "VALUE" format, an annotate function may raise
- "NameError"; it must not raise "NameError" when called requesting
- any other format.
-
- If an object does not have any annotations, "__annotate__" should
- preferably be set to "None" (it can’t be deleted), rather than set
- to a function that returns an empty dict.
-
- Added in version 3.14.
-
-See also:
-
- **PEP 649** — Deferred evaluation of annotation using descriptors
- Introduces lazy evaluation of annotations and the "__annotate__"
- function.
-
-
-Special method lookup
-=====================
-
-For custom classes, implicit invocations of special methods are only
-guaranteed to work correctly if defined on an object’s type, not in
-the object’s instance dictionary. That behaviour is the reason why
-the following code raises an exception:
-
- >>> class C:
- ... pass
- ...
- >>> c = C()
- >>> c.__len__ = lambda: 5
- >>> len(c)
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- TypeError: object of type 'C' has no len()
-
-The rationale behind this behaviour lies with a number of special
-methods such as "__hash__()" and "__repr__()" that are implemented by
-all objects, including type objects. If the implicit lookup of these
-methods used the conventional lookup process, they would fail when
-invoked on the type object itself:
-
- >>> 1 .__hash__() == hash(1)
- True
- >>> int.__hash__() == hash(int)
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- TypeError: descriptor '__hash__' of 'int' object needs an argument
-
-Incorrectly attempting to invoke an unbound method of a class in this
-way is sometimes referred to as ‘metaclass confusion’, and is avoided
-by bypassing the instance when looking up special methods:
-
- >>> type(1).__hash__(1) == hash(1)
- True
- >>> type(int).__hash__(int) == hash(int)
- True
-
-In addition to bypassing any instance attributes in the interest of
-correctness, implicit special method lookup generally also bypasses
-the "__getattribute__()" method even of the object’s metaclass:
-
- >>> class Meta(type):
- ... def __getattribute__(*args):
- ... print("Metaclass getattribute invoked")
- ... return type.__getattribute__(*args)
- ...
- >>> class C(object, metaclass=Meta):
- ... def __len__(self):
- ... return 10
- ... def __getattribute__(*args):
- ... print("Class getattribute invoked")
- ... return object.__getattribute__(*args)
- ...
- >>> c = C()
- >>> c.__len__() # Explicit lookup via instance
- Class getattribute invoked
- 10
- >>> type(c).__len__(c) # Explicit lookup via type
- Metaclass getattribute invoked
- 10
- >>> len(c) # Implicit lookup
- 10
-
-Bypassing the "__getattribute__()" machinery in this fashion provides
-significant scope for speed optimisations within the interpreter, at
-the cost of some flexibility in the handling of special methods (the
-special method *must* be set on the class object itself in order to be
-consistently invoked by the interpreter).
-''',
- 'string-methods': r'''String Methods
-**************
-
-Strings implement all of the common sequence operations, along with
-the additional methods described below.
-
-Strings also support two styles of string formatting, one providing a
-large degree of flexibility and customization (see "str.format()",
-Format String Syntax and Custom String Formatting) and the other based
-on C "printf" style formatting that handles a narrower range of types
-and is slightly harder to use correctly, but is often faster for the
-cases it can handle (printf-style String Formatting).
-
-The Text Processing Services section of the standard library covers a
-number of other modules that provide various text related utilities
-(including regular expression support in the "re" module).
-
-str.capitalize()
-
- Return a copy of the string with its first character capitalized
- and the rest lowercased.
-
- Changed in version 3.8: The first character is now put into
- titlecase rather than uppercase. This means that characters like
- digraphs will only have their first letter capitalized, instead of
- the full character.
-
-str.casefold()
-
- Return a casefolded copy of the string. Casefolded strings may be
- used for caseless matching.
-
- Casefolding is similar to lowercasing but more aggressive because
- it is intended to remove all case distinctions in a string. For
- example, the German lowercase letter "'ß'" is equivalent to ""ss"".
- Since it is already lowercase, "lower()" would do nothing to "'ß'";
- "casefold()" converts it to ""ss"".
-
- The casefolding algorithm is described in section 3.13 ‘Default
- Case Folding’ of the Unicode Standard.
-
- Added in version 3.3.
-
-str.center(width[, fillchar])
-
- Return centered in a string of length *width*. Padding is done
- using the specified *fillchar* (default is an ASCII space). The
- original string is returned if *width* is less than or equal to
- "len(s)".
-
-str.count(sub[, start[, end]])
-
- Return the number of non-overlapping occurrences of substring *sub*
- in the range [*start*, *end*]. Optional arguments *start* and
- *end* are interpreted as in slice notation.
-
- If *sub* is empty, returns the number of empty strings between
- characters which is the length of the string plus one.
-
-str.encode(encoding='utf-8', errors='strict')
-
- Return the string encoded to "bytes".
-
- *encoding* defaults to "'utf-8'"; see Standard Encodings for
- possible values.
-
- *errors* controls how encoding errors are handled. If "'strict'"
- (the default), a "UnicodeError" exception is raised. Other possible
- values are "'ignore'", "'replace'", "'xmlcharrefreplace'",
- "'backslashreplace'" and any other name registered via
- "codecs.register_error()". See Error Handlers for details.
-
- For performance reasons, the value of *errors* is not checked for
- validity unless an encoding error actually occurs, Python
- Development Mode is enabled or a debug build is used.
-
- Changed in version 3.1: Added support for keyword arguments.
-
- Changed in version 3.9: The value of the *errors* argument is now
- checked in Python Development Mode and in debug mode.
-
-str.endswith(suffix[, start[, end]])
-
- Return "True" if the string ends with the specified *suffix*,
- otherwise return "False". *suffix* can also be a tuple of suffixes
- to look for. With optional *start*, test beginning at that
- position. With optional *end*, stop comparing at that position.
-
-str.expandtabs(tabsize=8)
-
- Return a copy of the string where all tab characters are replaced
- by one or more spaces, depending on the current column and the
- given tab size. Tab positions occur every *tabsize* characters
- (default is 8, giving tab positions at columns 0, 8, 16 and so on).
- To expand the string, the current column is set to zero and the
- string is examined character by character. If the character is a
- tab ("\t"), one or more space characters are inserted in the result
- until the current column is equal to the next tab position. (The
- tab character itself is not copied.) If the character is a newline
- ("\n") or return ("\r"), it is copied and the current column is
- reset to zero. Any other character is copied unchanged and the
- current column is incremented by one regardless of how the
- character is represented when printed.
-
- >>> '01\t012\t0123\t01234'.expandtabs()
- '01 012 0123 01234'
- >>> '01\t012\t0123\t01234'.expandtabs(4)
- '01 012 0123 01234'
-
-str.find(sub[, start[, end]])
-
- Return the lowest index in the string where substring *sub* is
- found within the slice "s[start:end]". Optional arguments *start*
- and *end* are interpreted as in slice notation. Return "-1" if
- *sub* is not found.
-
- Note:
-
- The "find()" method should be used only if you need to know the
- position of *sub*. To check if *sub* is a substring or not, use
- the "in" operator:
-
- >>> 'Py' in 'Python'
- True
-
-str.format(*args, **kwargs)
-
- Perform a string formatting operation. The string on which this
- method is called can contain literal text or replacement fields
- delimited by braces "{}". Each replacement field contains either
- the numeric index of a positional argument, or the name of a
- keyword argument. Returns a copy of the string where each
- replacement field is replaced with the string value of the
- corresponding argument.
-
- >>> "The sum of 1 + 2 is {0}".format(1+2)
- 'The sum of 1 + 2 is 3'
-
- See Format String Syntax for a description of the various
- formatting options that can be specified in format strings.
-
- Note:
-
- When formatting a number ("int", "float", "complex",
- "decimal.Decimal" and subclasses) with the "n" type (ex:
- "'{:n}'.format(1234)"), the function temporarily sets the
- "LC_CTYPE" locale to the "LC_NUMERIC" locale to decode
- "decimal_point" and "thousands_sep" fields of "localeconv()" if
- they are non-ASCII or longer than 1 byte, and the "LC_NUMERIC"
- locale is different than the "LC_CTYPE" locale. This temporary
- change affects other threads.
-
- Changed in version 3.7: When formatting a number with the "n" type,
- the function sets temporarily the "LC_CTYPE" locale to the
- "LC_NUMERIC" locale in some cases.
-
-str.format_map(mapping, /)
-
- Similar to "str.format(**mapping)", except that "mapping" is used
- directly and not copied to a "dict". This is useful if for example
- "mapping" is a dict subclass:
-
- >>> class Default(dict):
- ... def __missing__(self, key):
- ... return key
- ...
- >>> '{name} was born in {country}'.format_map(Default(name='Guido'))
- 'Guido was born in country'
-
- Added in version 3.2.
-
-str.index(sub[, start[, end]])
-
- Like "find()", but raise "ValueError" when the substring is not
- found.
-
-str.isalnum()
-
- Return "True" if all characters in the string are alphanumeric and
- there is at least one character, "False" otherwise. A character
- "c" is alphanumeric if one of the following returns "True":
- "c.isalpha()", "c.isdecimal()", "c.isdigit()", or "c.isnumeric()".
-
-str.isalpha()
-
- Return "True" if all characters in the string are alphabetic and
- there is at least one character, "False" otherwise. Alphabetic
- characters are those characters defined in the Unicode character
- database as “Letter”, i.e., those with general category property
- being one of “Lm”, “Lt”, “Lu”, “Ll”, or “Lo”. Note that this is
- different from the Alphabetic property defined in the section 4.10
- ‘Letters, Alphabetic, and Ideographic’ of the Unicode Standard.
-
-str.isascii()
-
- Return "True" if the string is empty or all characters in the
- string are ASCII, "False" otherwise. ASCII characters have code
- points in the range U+0000-U+007F.
-
- Added in version 3.7.
-
-str.isdecimal()
-
- Return "True" if all characters in the string are decimal
- characters and there is at least one character, "False" otherwise.
- Decimal characters are those that can be used to form numbers in
- base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. Formally a decimal
- character is a character in the Unicode General Category “Nd”.
-
-str.isdigit()
-
- Return "True" if all characters in the string are digits and there
- is at least one character, "False" otherwise. Digits include
- decimal characters and digits that need special handling, such as
- the compatibility superscript digits. This covers digits which
- cannot be used to form numbers in base 10, like the Kharosthi
- numbers. Formally, a digit is a character that has the property
- value Numeric_Type=Digit or Numeric_Type=Decimal.
-
-str.isidentifier()
-
- Return "True" if the string is a valid identifier according to the
- language definition, section Identifiers and keywords.
-
- "keyword.iskeyword()" can be used to test whether string "s" is a
- reserved identifier, such as "def" and "class".
-
- Example:
-
- >>> from keyword import iskeyword
-
- >>> 'hello'.isidentifier(), iskeyword('hello')
- (True, False)
- >>> 'def'.isidentifier(), iskeyword('def')
- (True, True)
-
-str.islower()
-
- Return "True" if all cased characters [4] in the string are
- lowercase and there is at least one cased character, "False"
- otherwise.
-
-str.isnumeric()
-
- Return "True" if all characters in the string are numeric
- characters, and there is at least one character, "False" otherwise.
- Numeric characters include digit characters, and all characters
- that have the Unicode numeric value property, e.g. U+2155, VULGAR
- FRACTION ONE FIFTH. Formally, numeric characters are those with
- the property value Numeric_Type=Digit, Numeric_Type=Decimal or
- Numeric_Type=Numeric.
-
-str.isprintable()
-
- Return "True" if all characters in the string are printable or the
- string is empty, "False" otherwise. Nonprintable characters are
- those characters defined in the Unicode character database as
- “Other” or “Separator”, excepting the ASCII space (0x20) which is
- considered printable. (Note that printable characters in this
- context are those which should not be escaped when "repr()" is
- invoked on a string. It has no bearing on the handling of strings
- written to "sys.stdout" or "sys.stderr".)
-
-str.isspace()
-
- Return "True" if there are only whitespace characters in the string
- and there is at least one character, "False" otherwise.
-
- A character is *whitespace* if in the Unicode character database
- (see "unicodedata"), either its general category is "Zs"
- (“Separator, space”), or its bidirectional class is one of "WS",
- "B", or "S".
-
-str.istitle()
-
- Return "True" if the string is a titlecased string and there is at
- least one character, for example uppercase characters may only
- follow uncased characters and lowercase characters only cased ones.
- Return "False" otherwise.
-
-str.isupper()
-
- Return "True" if all cased characters [4] in the string are
- uppercase and there is at least one cased character, "False"
- otherwise.
-
- >>> 'BANANA'.isupper()
- True
- >>> 'banana'.isupper()
- False
- >>> 'baNana'.isupper()
- False
- >>> ' '.isupper()
- False
-
-str.join(iterable)
-
- Return a string which is the concatenation of the strings in
- *iterable*. A "TypeError" will be raised if there are any non-
- string values in *iterable*, including "bytes" objects. The
- separator between elements is the string providing this method.
-
-str.ljust(width[, fillchar])
-
- Return the string left justified in a string of length *width*.
- Padding is done using the specified *fillchar* (default is an ASCII
- space). The original string is returned if *width* is less than or
- equal to "len(s)".
-
-str.lower()
-
- Return a copy of the string with all the cased characters [4]
- converted to lowercase.
-
- The lowercasing algorithm used is described in section 3.13
- ‘Default Case Folding’ of the Unicode Standard.
-
-str.lstrip([chars])
-
- Return a copy of the string with leading characters removed. The
- *chars* argument is a string specifying the set of characters to be
- removed. If omitted or "None", the *chars* argument defaults to
- removing whitespace. The *chars* argument is not a prefix; rather,
- all combinations of its values are stripped:
-
- >>> ' spacious '.lstrip()
- 'spacious '
- >>> 'www.example.com'.lstrip('cmowz.')
- 'example.com'
-
- See "str.removeprefix()" for a method that will remove a single
- prefix string rather than all of a set of characters. For example:
-
- >>> 'Arthur: three!'.lstrip('Arthur: ')
- 'ee!'
- >>> 'Arthur: three!'.removeprefix('Arthur: ')
- 'three!'
-
-static str.maketrans(x[, y[, z]])
-
- This static method returns a translation table usable for
- "str.translate()".
-
- If there is only one argument, it must be a dictionary mapping
- Unicode ordinals (integers) or characters (strings of length 1) to
- Unicode ordinals, strings (of arbitrary lengths) or "None".
- Character keys will then be converted to ordinals.
-
- If there are two arguments, they must be strings of equal length,
- and in the resulting dictionary, each character in x will be mapped
- to the character at the same position in y. If there is a third
- argument, it must be a string, whose characters will be mapped to
- "None" in the result.
-
-str.partition(sep)
-
- Split the string at the first occurrence of *sep*, and return a
- 3-tuple containing the part before the separator, the separator
- itself, and the part after the separator. If the separator is not
- found, return a 3-tuple containing the string itself, followed by
- two empty strings.
-
-str.removeprefix(prefix, /)
-
- If the string starts with the *prefix* string, return
- "string[len(prefix):]". Otherwise, return a copy of the original
- string:
-
- >>> 'TestHook'.removeprefix('Test')
- 'Hook'
- >>> 'BaseTestCase'.removeprefix('Test')
- 'BaseTestCase'
-
- Added in version 3.9.
-
-str.removesuffix(suffix, /)
-
- If the string ends with the *suffix* string and that *suffix* is
- not empty, return "string[:-len(suffix)]". Otherwise, return a copy
- of the original string:
-
- >>> 'MiscTests'.removesuffix('Tests')
- 'Misc'
- >>> 'TmpDirMixin'.removesuffix('Tests')
- 'TmpDirMixin'
-
- Added in version 3.9.
-
-str.replace(old, new, count=-1)
-
- Return a copy of the string with all occurrences of substring *old*
- replaced by *new*. If *count* is given, only the first *count*
- occurrences are replaced. If *count* is not specified or "-1", then
- all occurrences are replaced.
-
- Changed in version 3.13: *count* is now supported as a keyword
- argument.
-
-str.rfind(sub[, start[, end]])
-
- Return the highest index in the string where substring *sub* is
- found, such that *sub* is contained within "s[start:end]".
- Optional arguments *start* and *end* are interpreted as in slice
- notation. Return "-1" on failure.
-
-str.rindex(sub[, start[, end]])
-
- Like "rfind()" but raises "ValueError" when the substring *sub* is
- not found.
-
-str.rjust(width[, fillchar])
-
- Return the string right justified in a string of length *width*.
- Padding is done using the specified *fillchar* (default is an ASCII
- space). The original string is returned if *width* is less than or
- equal to "len(s)".
-
-str.rpartition(sep)
-
- Split the string at the last occurrence of *sep*, and return a
- 3-tuple containing the part before the separator, the separator
- itself, and the part after the separator. If the separator is not
- found, return a 3-tuple containing two empty strings, followed by
- the string itself.
-
-str.rsplit(sep=None, maxsplit=-1)
-
- Return a list of the words in the string, using *sep* as the
- delimiter string. If *maxsplit* is given, at most *maxsplit* splits
- are done, the *rightmost* ones. If *sep* is not specified or
- "None", any whitespace string is a separator. Except for splitting
- from the right, "rsplit()" behaves like "split()" which is
- described in detail below.
-
-str.rstrip([chars])
-
- Return a copy of the string with trailing characters removed. The
- *chars* argument is a string specifying the set of characters to be
- removed. If omitted or "None", the *chars* argument defaults to
- removing whitespace. The *chars* argument is not a suffix; rather,
- all combinations of its values are stripped:
-
- >>> ' spacious '.rstrip()
- ' spacious'
- >>> 'mississippi'.rstrip('ipz')
- 'mississ'
-
- See "str.removesuffix()" for a method that will remove a single
- suffix string rather than all of a set of characters. For example:
-
- >>> 'Monty Python'.rstrip(' Python')
- 'M'
- >>> 'Monty Python'.removesuffix(' Python')
- 'Monty'
-
-str.split(sep=None, maxsplit=-1)
-
- Return a list of the words in the string, using *sep* as the
- delimiter string. If *maxsplit* is given, at most *maxsplit*
- splits are done (thus, the list will have at most "maxsplit+1"
- elements). If *maxsplit* is not specified or "-1", then there is
- no limit on the number of splits (all possible splits are made).
-
- If *sep* is given, consecutive delimiters are not grouped together
- and are deemed to delimit empty strings (for example,
- "'1,,2'.split(',')" returns "['1', '', '2']"). The *sep* argument
- may consist of multiple characters as a single delimiter (to split
- with multiple delimiters, use "re.split()"). Splitting an empty
- string with a specified separator returns "['']".
-
- For example:
-
- >>> '1,2,3'.split(',')
- ['1', '2', '3']
- >>> '1,2,3'.split(',', maxsplit=1)
- ['1', '2,3']
- >>> '1,2,,3,'.split(',')
- ['1', '2', '', '3', '']
- >>> '1<>2<>3<4'.split('<>')
- ['1', '2', '3<4']
-
- If *sep* is not specified or is "None", a different splitting
- algorithm is applied: runs of consecutive whitespace are regarded
- as a single separator, and the result will contain no empty strings
- at the start or end if the string has leading or trailing
- whitespace. Consequently, splitting an empty string or a string
- consisting of just whitespace with a "None" separator returns "[]".
-
- For example:
-
- >>> '1 2 3'.split()
- ['1', '2', '3']
- >>> '1 2 3'.split(maxsplit=1)
- ['1', '2 3']
- >>> ' 1 2 3 '.split()
- ['1', '2', '3']
-
-str.splitlines(keepends=False)
-
- Return a list of the lines in the string, breaking at line
- boundaries. Line breaks are not included in the resulting list
- unless *keepends* is given and true.
-
- This method splits on the following line boundaries. In
- particular, the boundaries are a superset of *universal newlines*.
-
- +-------------------------+-------------------------------+
- | Representation | Description |
- |=========================|===============================|
- | "\n" | Line Feed |
- +-------------------------+-------------------------------+
- | "\r" | Carriage Return |
- +-------------------------+-------------------------------+
- | "\r\n" | Carriage Return + Line Feed |
- +-------------------------+-------------------------------+
- | "\v" or "\x0b" | Line Tabulation |
- +-------------------------+-------------------------------+
- | "\f" or "\x0c" | Form Feed |
- +-------------------------+-------------------------------+
- | "\x1c" | File Separator |
- +-------------------------+-------------------------------+
- | "\x1d" | Group Separator |
- +-------------------------+-------------------------------+
- | "\x1e" | Record Separator |
- +-------------------------+-------------------------------+
- | "\x85" | Next Line (C1 Control Code) |
- +-------------------------+-------------------------------+
- | "\u2028" | Line Separator |
- +-------------------------+-------------------------------+
- | "\u2029" | Paragraph Separator |
- +-------------------------+-------------------------------+
-
- Changed in version 3.2: "\v" and "\f" added to list of line
- boundaries.
-
- For example:
-
- >>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
- ['ab c', '', 'de fg', 'kl']
- >>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True)
- ['ab c\n', '\n', 'de fg\r', 'kl\r\n']
-
- Unlike "split()" when a delimiter string *sep* is given, this
- method returns an empty list for the empty string, and a terminal
- line break does not result in an extra line:
-
- >>> "".splitlines()
- []
- >>> "One line\n".splitlines()
- ['One line']
-
- For comparison, "split('\n')" gives:
-
- >>> ''.split('\n')
- ['']
- >>> 'Two lines\n'.split('\n')
- ['Two lines', '']
-
-str.startswith(prefix[, start[, end]])
-
- Return "True" if string starts with the *prefix*, otherwise return
- "False". *prefix* can also be a tuple of prefixes to look for.
- With optional *start*, test string beginning at that position.
- With optional *end*, stop comparing string at that position.
-
-str.strip([chars])
-
- Return a copy of the string with the leading and trailing
- characters removed. The *chars* argument is a string specifying the
- set of characters to be removed. If omitted or "None", the *chars*
- argument defaults to removing whitespace. The *chars* argument is
- not a prefix or suffix; rather, all combinations of its values are
- stripped:
-
- >>> ' spacious '.strip()
- 'spacious'
- >>> 'www.example.com'.strip('cmowz.')
- 'example'
-
- The outermost leading and trailing *chars* argument values are
- stripped from the string. Characters are removed from the leading
- end until reaching a string character that is not contained in the
- set of characters in *chars*. A similar action takes place on the
- trailing end. For example:
-
- >>> comment_string = '#....... Section 3.2.1 Issue #32 .......'
- >>> comment_string.strip('.#! ')
- 'Section 3.2.1 Issue #32'
-
-str.swapcase()
-
- Return a copy of the string with uppercase characters converted to
- lowercase and vice versa. Note that it is not necessarily true that
- "s.swapcase().swapcase() == s".
-
-str.title()
-
- Return a titlecased version of the string where words start with an
- uppercase character and the remaining characters are lowercase.
-
- For example:
-
- >>> 'Hello world'.title()
- 'Hello World'
-
- The algorithm uses a simple language-independent definition of a
- word as groups of consecutive letters. The definition works in
- many contexts but it means that apostrophes in contractions and
- possessives form word boundaries, which may not be the desired
- result:
-
- >>> "they're bill's friends from the UK".title()
- "They'Re Bill'S Friends From The Uk"
-
- The "string.capwords()" function does not have this problem, as it
- splits words on spaces only.
-
- Alternatively, a workaround for apostrophes can be constructed
- using regular expressions:
-
- >>> import re
- >>> def titlecase(s):
- ... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
- ... lambda mo: mo.group(0).capitalize(),
- ... s)
- ...
- >>> titlecase("they're bill's friends.")
- "They're Bill's Friends."
-
-str.translate(table)
-
- Return a copy of the string in which each character has been mapped
- through the given translation table. The table must be an object
- that implements indexing via "__getitem__()", typically a *mapping*
- or *sequence*. When indexed by a Unicode ordinal (an integer), the
- table object can do any of the following: return a Unicode ordinal
- or a string, to map the character to one or more other characters;
- return "None", to delete the character from the return string; or
- raise a "LookupError" exception, to map the character to itself.
-
- You can use "str.maketrans()" to create a translation map from
- character-to-character mappings in different formats.
-
- See also the "codecs" module for a more flexible approach to custom
- character mappings.
-
-str.upper()
-
- Return a copy of the string with all the cased characters [4]
- converted to uppercase. Note that "s.upper().isupper()" might be
- "False" if "s" contains uncased characters or if the Unicode
- category of the resulting character(s) is not “Lu” (Letter,
- uppercase), but e.g. “Lt” (Letter, titlecase).
-
- The uppercasing algorithm used is described in section 3.13
- ‘Default Case Folding’ of the Unicode Standard.
-
-str.zfill(width)
-
- Return a copy of the string left filled with ASCII "'0'" digits to
- make a string of length *width*. A leading sign prefix
- ("'+'"/"'-'") is handled by inserting the padding *after* the sign
- character rather than before. The original string is returned if
- *width* is less than or equal to "len(s)".
-
- For example:
-
- >>> "42".zfill(5)
- '00042'
- >>> "-42".zfill(5)
- '-0042'
-''',
- 'strings': '''String and Bytes literals
-*************************
-
-String literals are described by the following lexical definitions:
-
- **stringliteral**: ["stringprefix"]("shortstring" | "longstring")
- **stringprefix**: "r" | "u" | "R" | "U" | "f" | "F"
- | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | "Rf" | "RF"
- **shortstring**: "'" "shortstringitem"* "'" | '"' "shortstringitem"* '"'
- **longstring**: "\'\'\'" "longstringitem"* "\'\'\'" | '"""' "longstringitem"* '"""'
- **shortstringitem**: "shortstringchar" | "stringescapeseq"
- **longstringitem**: "longstringchar" | "stringescapeseq"
- **shortstringchar**: <any source character except "\\" or newline or the quote>
- **longstringchar**: <any source character except "\\">
- **stringescapeseq**: "\\" <any source character>
-
- **bytesliteral**: "bytesprefix"("shortbytes" | "longbytes")
- **bytesprefix**: "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"
- **shortbytes**: "'" "shortbytesitem"* "'" | '"' "shortbytesitem"* '"'
- **longbytes**: "\'\'\'" "longbytesitem"* "\'\'\'" | '"""' "longbytesitem"* '"""'
- **shortbytesitem**: "shortbyteschar" | "bytesescapeseq"
- **longbytesitem**: "longbyteschar" | "bytesescapeseq"
- **shortbyteschar**: <any ASCII character except "\\" or newline or the quote>
- **longbyteschar**: <any ASCII character except "\\">
- **bytesescapeseq**: "\\" <any ASCII character>
-
-One syntactic restriction not indicated by these productions is that
-whitespace is not allowed between the "stringprefix" or "bytesprefix"
-and the rest of the literal. The source character set is defined by
-the encoding declaration; it is UTF-8 if no encoding declaration is
-given in the source file; see section Encoding declarations.
-
-In plain English: Both types of literals can be enclosed in matching
-single quotes ("'") or double quotes ("""). They can also be enclosed
-in matching groups of three single or double quotes (these are
-generally referred to as *triple-quoted strings*). The backslash ("\\")
-character is used to give special meaning to otherwise ordinary
-characters like "n", which means ‘newline’ when escaped ("\\n"). It can
-also be used to escape characters that otherwise have a special
-meaning, such as newline, backslash itself, or the quote character.
-See escape sequences below for examples.
-
-Bytes literals are always prefixed with "'b'" or "'B'"; they produce
-an instance of the "bytes" type instead of the "str" type. They may
-only contain ASCII characters; bytes with a numeric value of 128 or
-greater must be expressed with escapes.
-
-Both string and bytes literals may optionally be prefixed with a
-letter "'r'" or "'R'"; such constructs are called *raw string
-literals* and *raw bytes literals* respectively and treat backslashes
-as literal characters. As a result, in raw string literals, "'\\U'"
-and "'\\u'" escapes are not treated specially.
-
-Added in version 3.3: The "'rb'" prefix of raw bytes literals has been
-added as a synonym of "'br'".Support for the unicode legacy literal
-("u'value'") was reintroduced to simplify the maintenance of dual
-Python 2.x and 3.x codebases. See **PEP 414** for more information.
-
-A string literal with "'f'" or "'F'" in its prefix is a *formatted
-string literal*; see f-strings. The "'f'" may be combined with "'r'",
-but not with "'b'" or "'u'", therefore raw formatted strings are
-possible, but formatted bytes literals are not.
-
-In triple-quoted literals, unescaped newlines and quotes are allowed
-(and are retained), except that three unescaped quotes in a row
-terminate the literal. (A “quote” is the character used to open the
-literal, i.e. either "'" or """.)
-
-
-Escape sequences
-================
-
-Unless an "'r'" or "'R'" prefix is present, escape sequences in string
-and bytes literals are interpreted according to rules similar to those
-used by Standard C. The recognized escape sequences are:
-
-+---------------------------+-----------------------------------+---------+
-| Escape Sequence | Meaning | Notes |
-|===========================|===================================|=========|
-| "\\"<newline> | Backslash and newline ignored | (1) |
-+---------------------------+-----------------------------------+---------+
-| "\\\\" | Backslash ("\\") | |
-+---------------------------+-----------------------------------+---------+
-| "\\'" | Single quote ("'") | |
-+---------------------------+-----------------------------------+---------+
-| "\\"" | Double quote (""") | |
-+---------------------------+-----------------------------------+---------+
-| "\\a" | ASCII Bell (BEL) | |
-+---------------------------+-----------------------------------+---------+
-| "\\b" | ASCII Backspace (BS) | |
-+---------------------------+-----------------------------------+---------+
-| "\\f" | ASCII Formfeed (FF) | |
-+---------------------------+-----------------------------------+---------+
-| "\\n" | ASCII Linefeed (LF) | |
-+---------------------------+-----------------------------------+---------+
-| "\\r" | ASCII Carriage Return (CR) | |
-+---------------------------+-----------------------------------+---------+
-| "\\t" | ASCII Horizontal Tab (TAB) | |
-+---------------------------+-----------------------------------+---------+
-| "\\v" | ASCII Vertical Tab (VT) | |
-+---------------------------+-----------------------------------+---------+
-| "\\*ooo*" | Character with octal value *ooo* | (2,4) |
-+---------------------------+-----------------------------------+---------+
-| "\\x*hh*" | Character with hex value *hh* | (3,4) |
-+---------------------------+-----------------------------------+---------+
-
-Escape sequences only recognized in string literals are:
-
-+---------------------------+-----------------------------------+---------+
-| Escape Sequence | Meaning | Notes |
-|===========================|===================================|=========|
-| "\\N{*name*}" | Character named *name* in the | (5) |
-| | Unicode database | |
-+---------------------------+-----------------------------------+---------+
-| "\\u*xxxx*" | Character with 16-bit hex value | (6) |
-| | *xxxx* | |
-+---------------------------+-----------------------------------+---------+
-| "\\U*xxxxxxxx*" | Character with 32-bit hex value | (7) |
-| | *xxxxxxxx* | |
-+---------------------------+-----------------------------------+---------+
-
-Notes:
-
-1. A backslash can be added at the end of a line to ignore the
- newline:
-
- >>> 'This string will not include \\
- ... backslashes or newline characters.'
- 'This string will not include backslashes or newline characters.'
-
- The same result can be achieved using triple-quoted strings, or
- parentheses and string literal concatenation.
-
-2. As in Standard C, up to three octal digits are accepted.
-
- Changed in version 3.11: Octal escapes with value larger than
- "0o377" produce a "DeprecationWarning".
-
- Changed in version 3.12: Octal escapes with value larger than
- "0o377" produce a "SyntaxWarning". In a future Python version they
- will be eventually a "SyntaxError".
-
-3. Unlike in Standard C, exactly two hex digits are required.
-
-4. In a bytes literal, hexadecimal and octal escapes denote the byte
- with the given value. In a string literal, these escapes denote a
- Unicode character with the given value.
-
-5. Changed in version 3.3: Support for name aliases [1] has been
- added.
-
-6. Exactly four hex digits are required.
-
-7. Any Unicode character can be encoded this way. Exactly eight hex
- digits are required.
-
-Unlike Standard C, all unrecognized escape sequences are left in the
-string unchanged, i.e., *the backslash is left in the result*. (This
-behavior is useful when debugging: if an escape sequence is mistyped,
-the resulting output is more easily recognized as broken.) It is also
-important to note that the escape sequences only recognized in string
-literals fall into the category of unrecognized escapes for bytes
-literals.
-
-Changed in version 3.6: Unrecognized escape sequences produce a
-"DeprecationWarning".
-
-Changed in version 3.12: Unrecognized escape sequences produce a
-"SyntaxWarning". In a future Python version they will be eventually a
-"SyntaxError".
-
-Even in a raw literal, quotes can be escaped with a backslash, but the
-backslash remains in the result; for example, "r"\\""" is a valid
-string literal consisting of two characters: a backslash and a double
-quote; "r"\\"" is not a valid string literal (even a raw string cannot
-end in an odd number of backslashes). Specifically, *a raw literal
-cannot end in a single backslash* (since the backslash would escape
-the following quote character). Note also that a single backslash
-followed by a newline is interpreted as those two characters as part
-of the literal, *not* as a line continuation.
-''',
- 'subscriptions': r'''Subscriptions
-*************
-
-The subscription of an instance of a container class will generally
-select an element from the container. The subscription of a *generic
-class* will generally return a GenericAlias object.
-
- **subscription**: "primary" "[" "flexible_expression_list" "]"
-
-When an object is subscripted, the interpreter will evaluate the
-primary and the expression list.
-
-The primary must evaluate to an object that supports subscription. An
-object may support subscription through defining one or both of
-"__getitem__()" and "__class_getitem__()". When the primary is
-subscripted, the evaluated result of the expression list will be
-passed to one of these methods. For more details on when
-"__class_getitem__" is called instead of "__getitem__", see
-__class_getitem__ versus __getitem__.
-
-If the expression list contains at least one comma, or if any of the
-expressions are starred, the expression list will evaluate to a
-"tuple" containing the items of the expression list. Otherwise, the
-expression list will evaluate to the value of the list’s sole member.
-
-Changed in version 3.11: Expressions in an expression list may be
-starred. See **PEP 646**.
-
-For built-in objects, there are two types of objects that support
-subscription via "__getitem__()":
-
-1. Mappings. If the primary is a *mapping*, the expression list must
- evaluate to an object whose value is one of the keys of the
- mapping, and the subscription selects the value in the mapping that
- corresponds to that key. An example of a builtin mapping class is
- the "dict" class.
-
-2. Sequences. If the primary is a *sequence*, the expression list must
- evaluate to an "int" or a "slice" (as discussed in the following
- section). Examples of builtin sequence classes include the "str",
- "list" and "tuple" classes.
-
-The formal syntax makes no special provision for negative indices in
-*sequences*. However, built-in sequences all provide a "__getitem__()"
-method that interprets negative indices by adding the length of the
-sequence to the index so that, for example, "x[-1]" selects the last
-item of "x". The resulting value must be a nonnegative integer less
-than the number of items in the sequence, and the subscription selects
-the item whose index is that value (counting from zero). Since the
-support for negative indices and slicing occurs in the object’s
-"__getitem__()" method, subclasses overriding this method will need to
-explicitly add that support.
-
-A "string" is a special kind of sequence whose items are *characters*.
-A character is not a separate data type but a string of exactly one
-character.
-''',
- 'truth': r'''Truth Value Testing
-*******************
-
-Any object can be tested for truth value, for use in an "if" or
-"while" condition or as operand of the Boolean operations below.
-
-By default, an object is considered true unless its class defines
-either a "__bool__()" method that returns "False" or a "__len__()"
-method that returns zero, when called with the object. [1] Here are
-most of the built-in objects considered false:
-
-* constants defined to be false: "None" and "False"
-
-* zero of any numeric type: "0", "0.0", "0j", "Decimal(0)",
- "Fraction(0, 1)"
-
-* empty sequences and collections: "''", "()", "[]", "{}", "set()",
- "range(0)"
-
-Operations and built-in functions that have a Boolean result always
-return "0" or "False" for false and "1" or "True" for true, unless
-otherwise stated. (Important exception: the Boolean operations "or"
-and "and" always return one of their operands.)
-''',
- 'try': r'''The "try" statement
-*******************
-
-The "try" statement specifies exception handlers and/or cleanup code
-for a group of statements:
-
- **try_stmt**: "try1_stmt" | "try2_stmt" | "try3_stmt"
- **try1_stmt**: "try" ":" "suite"
- ("except" ["expression" ["as" "identifier"]] ":" "suite")+
- ["else" ":" "suite"]
- ["finally" ":" "suite"]
- **try2_stmt**: "try" ":" "suite"
- ("except" "*" "expression" ["as" "identifier"] ":" "suite")+
- ["else" ":" "suite"]
- ["finally" ":" "suite"]
- **try3_stmt**: "try" ":" "suite"
- "finally" ":" "suite"
-
-Additional information on exceptions can be found in section
-Exceptions, and information on using the "raise" statement to generate
-exceptions may be found in section The raise statement.
-
-
-"except" clause
-===============
-
-The "except" clause(s) specify one or more exception handlers. When no
-exception occurs in the "try" clause, no exception handler is
-executed. When an exception occurs in the "try" suite, a search for an
-exception handler is started. This search inspects the "except"
-clauses in turn until one is found that matches the exception. An
-expression-less "except" clause, if present, must be last; it matches
-any exception.
-
-For an "except" clause with an expression, the expression must
-evaluate to an exception type or a tuple of exception types. The
-raised exception matches an "except" clause whose expression evaluates
-to the class or a *non-virtual base class* of the exception object, or
-to a tuple that contains such a class.
-
-If no "except" clause matches the exception, the search for an
-exception handler continues in the surrounding code and on the
-invocation stack. [1]
-
-If the evaluation of an expression in the header of an "except" clause
-raises an exception, the original search for a handler is canceled and
-a search starts for the new exception in the surrounding code and on
-the call stack (it is treated as if the entire "try" statement raised
-the exception).
-
-When a matching "except" clause is found, the exception is assigned to
-the target specified after the "as" keyword in that "except" clause,
-if present, and the "except" clause’s suite is executed. All "except"
-clauses must have an executable block. When the end of this block is
-reached, execution continues normally after the entire "try"
-statement. (This means that if two nested handlers exist for the same
-exception, and the exception occurs in the "try" clause of the inner
-handler, the outer handler will not handle the exception.)
-
-When an exception has been assigned using "as target", it is cleared
-at the end of the "except" clause. This is as if
-
- except E as N:
- foo
-
-was translated to
-
- except E as N:
- try:
- foo
- finally:
- del N
-
-This means the exception must be assigned to a different name to be
-able to refer to it after the "except" clause. Exceptions are cleared
-because with the traceback attached to them, they form a reference
-cycle with the stack frame, keeping all locals in that frame alive
-until the next garbage collection occurs.
-
-Before an "except" clause’s suite is executed, the exception is stored
-in the "sys" module, where it can be accessed from within the body of
-the "except" clause by calling "sys.exception()". When leaving an
-exception handler, the exception stored in the "sys" module is reset
-to its previous value:
-
- >>> print(sys.exception())
- None
- >>> try:
- ... raise TypeError
- ... except:
- ... print(repr(sys.exception()))
- ... try:
- ... raise ValueError
- ... except:
- ... print(repr(sys.exception()))
- ... print(repr(sys.exception()))
- ...
- TypeError()
- ValueError()
- TypeError()
- >>> print(sys.exception())
- None
-
-
-"except*" clause
-================
-
-The "except*" clause(s) are used for handling "ExceptionGroup"s. The
-exception type for matching is interpreted as in the case of "except",
-but in the case of exception groups we can have partial matches when
-the type matches some of the exceptions in the group. This means that
-multiple "except*" clauses can execute, each handling part of the
-exception group. Each clause executes at most once and handles an
-exception group of all matching exceptions. Each exception in the
-group is handled by at most one "except*" clause, the first that
-matches it.
-
- >>> try:
- ... raise ExceptionGroup("eg",
- ... [ValueError(1), TypeError(2), OSError(3), OSError(4)])
- ... except* TypeError as e:
- ... print(f'caught {type(e)} with nested {e.exceptions}')
- ... except* OSError as e:
- ... print(f'caught {type(e)} with nested {e.exceptions}')
- ...
- caught <class 'ExceptionGroup'> with nested (TypeError(2),)
- caught <class 'ExceptionGroup'> with nested (OSError(3), OSError(4))
- + Exception Group Traceback (most recent call last):
- | File "<stdin>", line 2, in <module>
- | ExceptionGroup: eg
- +-+---------------- 1 ----------------
- | ValueError: 1
- +------------------------------------
-
-Any remaining exceptions that were not handled by any "except*" clause
-are re-raised at the end, along with all exceptions that were raised
-from within the "except*" clauses. If this list contains more than one
-exception to reraise, they are combined into an exception group.
-
-If the raised exception is not an exception group and its type matches
-one of the "except*" clauses, it is caught and wrapped by an exception
-group with an empty message string.
-
- >>> try:
- ... raise BlockingIOError
- ... except* BlockingIOError as e:
- ... print(repr(e))
- ...
- ExceptionGroup('', (BlockingIOError()))
-
-An "except*" clause must have a matching expression; it cannot be
-"except*:". Furthermore, this expression cannot contain exception
-group types, because that would have ambiguous semantics.
-
-It is not possible to mix "except" and "except*" in the same "try".
-"break", "continue" and "return" cannot appear in an "except*" clause.
-
-
-"else" clause
-=============
-
-The optional "else" clause is executed if the control flow leaves the
-"try" suite, no exception was raised, and no "return", "continue", or
-"break" statement was executed. Exceptions in the "else" clause are
-not handled by the preceding "except" clauses.
-
-
-"finally" clause
-================
-
-If "finally" is present, it specifies a ‘cleanup’ handler. The "try"
-clause is executed, including any "except" and "else" clauses. If an
-exception occurs in any of the clauses and is not handled, the
-exception is temporarily saved. The "finally" clause is executed. If
-there is a saved exception it is re-raised at the end of the "finally"
-clause. If the "finally" clause raises another exception, the saved
-exception is set as the context of the new exception. If the "finally"
-clause executes a "return", "break" or "continue" statement, the saved
-exception is discarded:
-
- >>> def f():
- ... try:
- ... 1/0
- ... finally:
- ... return 42
- ...
- >>> f()
- 42
-
-The exception information is not available to the program during
-execution of the "finally" clause.
-
-When a "return", "break" or "continue" statement is executed in the
-"try" suite of a "try"…"finally" statement, the "finally" clause is
-also executed ‘on the way out.’
-
-The return value of a function is determined by the last "return"
-statement executed. Since the "finally" clause always executes, a
-"return" statement executed in the "finally" clause will always be the
-last one executed:
-
- >>> def foo():
- ... try:
- ... return 'try'
- ... finally:
- ... return 'finally'
- ...
- >>> foo()
- 'finally'
-
-Changed in version 3.8: Prior to Python 3.8, a "continue" statement
-was illegal in the "finally" clause due to a problem with the
-implementation.
-''',
- 'types': r'''The standard type hierarchy
-***************************
-
-Below is a list of the types that are built into Python. Extension
-modules (written in C, Java, or other languages, depending on the
-implementation) can define additional types. Future versions of
-Python may add types to the type hierarchy (e.g., rational numbers,
-efficiently stored arrays of integers, etc.), although such additions
-will often be provided via the standard library instead.
-
-Some of the type descriptions below contain a paragraph listing
-‘special attributes.’ These are attributes that provide access to the
-implementation and are not intended for general use. Their definition
-may change in the future.
-
-
-None
-====
-
-This type has a single value. There is a single object with this
-value. This object is accessed through the built-in name "None". It is
-used to signify the absence of a value in many situations, e.g., it is
-returned from functions that don’t explicitly return anything. Its
-truth value is false.
-
-
-NotImplemented
-==============
-
-This type has a single value. There is a single object with this
-value. This object is accessed through the built-in name
-"NotImplemented". Numeric methods and rich comparison methods should
-return this value if they do not implement the operation for the
-operands provided. (The interpreter will then try the reflected
-operation, or some other fallback, depending on the operator.) It
-should not be evaluated in a boolean context.
-
-See Implementing the arithmetic operations for more details.
-
-Changed in version 3.9: Evaluating "NotImplemented" in a boolean
-context was deprecated.
-
-Changed in version 3.14: Evaluating "NotImplemented" in a boolean
-context now raises a "TypeError". It previously evaluated to "True"
-and emitted a "DeprecationWarning" since Python 3.9.
-
-
-Ellipsis
-========
-
-This type has a single value. There is a single object with this
-value. This object is accessed through the literal "..." or the built-
-in name "Ellipsis". Its truth value is true.
-
-
-"numbers.Number"
-================
-
-These are created by numeric literals and returned as results by
-arithmetic operators and arithmetic built-in functions. Numeric
-objects are immutable; once created their value never changes. Python
-numbers are of course strongly related to mathematical numbers, but
-subject to the limitations of numerical representation in computers.
-
-The string representations of the numeric classes, computed by
-"__repr__()" and "__str__()", have the following properties:
-
-* They are valid numeric literals which, when passed to their class
- constructor, produce an object having the value of the original
- numeric.
-
-* The representation is in base 10, when possible.
-
-* Leading zeros, possibly excepting a single zero before a decimal
- point, are not shown.
-
-* Trailing zeros, possibly excepting a single zero after a decimal
- point, are not shown.
-
-* A sign is shown only when the number is negative.
-
-Python distinguishes between integers, floating-point numbers, and
-complex numbers:
-
-
-"numbers.Integral"
-------------------
-
-These represent elements from the mathematical set of integers
-(positive and negative).
-
-Note:
-
- The rules for integer representation are intended to give the most
- meaningful interpretation of shift and mask operations involving
- negative integers.
-
-There are two types of integers:
-
-Integers ("int")
- These represent numbers in an unlimited range, subject to available
- (virtual) memory only. For the purpose of shift and mask
- operations, a binary representation is assumed, and negative
- numbers are represented in a variant of 2’s complement which gives
- the illusion of an infinite string of sign bits extending to the
- left.
-
-Booleans ("bool")
- These represent the truth values False and True. The two objects
- representing the values "False" and "True" are the only Boolean
- objects. The Boolean type is a subtype of the integer type, and
- Boolean values behave like the values 0 and 1, respectively, in
- almost all contexts, the exception being that when converted to a
- string, the strings ""False"" or ""True"" are returned,
- respectively.
-
-
-"numbers.Real" ("float")
-------------------------
-
-These represent machine-level double precision floating-point numbers.
-You are at the mercy of the underlying machine architecture (and C or
-Java implementation) for the accepted range and handling of overflow.
-Python does not support single-precision floating-point numbers; the
-savings in processor and memory usage that are usually the reason for
-using these are dwarfed by the overhead of using objects in Python, so
-there is no reason to complicate the language with two kinds of
-floating-point numbers.
-
-
-"numbers.Complex" ("complex")
------------------------------
-
-These represent complex numbers as a pair of machine-level double
-precision floating-point numbers. The same caveats apply as for
-floating-point numbers. The real and imaginary parts of a complex
-number "z" can be retrieved through the read-only attributes "z.real"
-and "z.imag".
-
-
-Sequences
-=========
-
-These represent finite ordered sets indexed by non-negative numbers.
-The built-in function "len()" returns the number of items of a
-sequence. When the length of a sequence is *n*, the index set contains
-the numbers 0, 1, …, *n*-1. Item *i* of sequence *a* is selected by
-"a[i]". Some sequences, including built-in sequences, interpret
-negative subscripts by adding the sequence length. For example,
-"a[-2]" equals "a[n-2]", the second to last item of sequence a with
-length "n".
-
-Sequences also support slicing: "a[i:j]" selects all items with index
-*k* such that *i* "<=" *k* "<" *j*. When used as an expression, a
-slice is a sequence of the same type. The comment above about negative
-indexes also applies to negative slice positions.
-
-Some sequences also support “extended slicing” with a third “step”
-parameter: "a[i:j:k]" selects all items of *a* with index *x* where "x
-= i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.
-
-Sequences are distinguished according to their mutability:
-
-
-Immutable sequences
--------------------
-
-An object of an immutable sequence type cannot change once it is
-created. (If the object contains references to other objects, these
-other objects may be mutable and may be changed; however, the
-collection of objects directly referenced by an immutable object
-cannot change.)
-
-The following types are immutable sequences:
-
-Strings
- A string is a sequence of values that represent Unicode code
- points. All the code points in the range "U+0000 - U+10FFFF" can be
- represented in a string. Python doesn’t have a char type; instead,
- every code point in the string is represented as a string object
- with length "1". The built-in function "ord()" converts a code
- point from its string form to an integer in the range "0 - 10FFFF";
- "chr()" converts an integer in the range "0 - 10FFFF" to the
- corresponding length "1" string object. "str.encode()" can be used
- to convert a "str" to "bytes" using the given text encoding, and
- "bytes.decode()" can be used to achieve the opposite.
-
-Tuples
- The items of a tuple are arbitrary Python objects. Tuples of two or
- more items are formed by comma-separated lists of expressions. A
- tuple of one item (a ‘singleton’) can be formed by affixing a comma
- to an expression (an expression by itself does not create a tuple,
- since parentheses must be usable for grouping of expressions). An
- empty tuple can be formed by an empty pair of parentheses.
-
-Bytes
- A bytes object is an immutable array. The items are 8-bit bytes,
- represented by integers in the range 0 <= x < 256. Bytes literals
- (like "b'abc'") and the built-in "bytes()" constructor can be used
- to create bytes objects. Also, bytes objects can be decoded to
- strings via the "decode()" method.
-
-
-Mutable sequences
------------------
-
-Mutable sequences can be changed after they are created. The
-subscription and slicing notations can be used as the target of
-assignment and "del" (delete) statements.
-
-Note:
-
- The "collections" and "array" module provide additional examples of
- mutable sequence types.
-
-There are currently two intrinsic mutable sequence types:
-
-Lists
- The items of a list are arbitrary Python objects. Lists are formed
- by placing a comma-separated list of expressions in square
- brackets. (Note that there are no special cases needed to form
- lists of length 0 or 1.)
-
-Byte Arrays
- A bytearray object is a mutable array. They are created by the
- built-in "bytearray()" constructor. Aside from being mutable (and
- hence unhashable), byte arrays otherwise provide the same interface
- and functionality as immutable "bytes" objects.
-
-
-Set types
-=========
-
-These represent unordered, finite sets of unique, immutable objects.
-As such, they cannot be indexed by any subscript. However, they can be
-iterated over, and the built-in function "len()" returns the number of
-items in a set. Common uses for sets are fast membership testing,
-removing duplicates from a sequence, and computing mathematical
-operations such as intersection, union, difference, and symmetric
-difference.
-
-For set elements, the same immutability rules apply as for dictionary
-keys. Note that numeric types obey the normal rules for numeric
-comparison: if two numbers compare equal (e.g., "1" and "1.0"), only
-one of them can be contained in a set.
-
-There are currently two intrinsic set types:
-
-Sets
- These represent a mutable set. They are created by the built-in
- "set()" constructor and can be modified afterwards by several
- methods, such as "add()".
-
-Frozen sets
- These represent an immutable set. They are created by the built-in
- "frozenset()" constructor. As a frozenset is immutable and
- *hashable*, it can be used again as an element of another set, or
- as a dictionary key.
-
-
-Mappings
-========
-
-These represent finite sets of objects indexed by arbitrary index
-sets. The subscript notation "a[k]" selects the item indexed by "k"
-from the mapping "a"; this can be used in expressions and as the
-target of assignments or "del" statements. The built-in function
-"len()" returns the number of items in a mapping.
-
-There is currently a single intrinsic mapping type:
-
-
-Dictionaries
-------------
-
-These represent finite sets of objects indexed by nearly arbitrary
-values. The only types of values not acceptable as keys are values
-containing lists or dictionaries or other mutable types that are
-compared by value rather than by object identity, the reason being
-that the efficient implementation of dictionaries requires a key’s
-hash value to remain constant. Numeric types used for keys obey the
-normal rules for numeric comparison: if two numbers compare equal
-(e.g., "1" and "1.0") then they can be used interchangeably to index
-the same dictionary entry.
-
-Dictionaries preserve insertion order, meaning that keys will be
-produced in the same order they were added sequentially over the
-dictionary. Replacing an existing key does not change the order,
-however removing a key and re-inserting it will add it to the end
-instead of keeping its old place.
-
-Dictionaries are mutable; they can be created by the "{}" notation
-(see section Dictionary displays).
-
-The extension modules "dbm.ndbm" and "dbm.gnu" provide additional
-examples of mapping types, as does the "collections" module.
-
-Changed in version 3.7: Dictionaries did not preserve insertion order
-in versions of Python before 3.6. In CPython 3.6, insertion order was
-preserved, but it was considered an implementation detail at that time
-rather than a language guarantee.
-
-
-Callable types
-==============
-
-These are the types to which the function call operation (see section
-Calls) can be applied:
-
-
-User-defined functions
-----------------------
-
-A user-defined function object is created by a function definition
-(see section Function definitions). It should be called with an
-argument list containing the same number of items as the function’s
-formal parameter list.
-
-
-Special read-only attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-+----------------------------------------------------+----------------------------------------------------+
-| Attribute | Meaning |
-|====================================================|====================================================|
-| function.__globals__ | A reference to the "dictionary" that holds the |
-| | function’s global variables – the global namespace |
-| | of the module in which the function was defined. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__closure__ | "None" or a "tuple" of cells that contain bindings |
-| | for the names specified in the "co_freevars" |
-| | attribute of the function’s "code object". A cell |
-| | object has the attribute "cell_contents". This can |
-| | be used to get the value of the cell, as well as |
-| | set the value. |
-+----------------------------------------------------+----------------------------------------------------+
-
-
-Special writable attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Most of these attributes check the type of the assigned value:
-
-+----------------------------------------------------+----------------------------------------------------+
-| Attribute | Meaning |
-|====================================================|====================================================|
-| function.__doc__ | The function’s documentation string, or "None" if |
-| | unavailable. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__name__ | The function’s name. See also: "__name__ |
-| | attributes". |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__qualname__ | The function’s *qualified name*. See also: |
-| | "__qualname__ attributes". Added in version 3.3. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__module__ | The name of the module the function was defined |
-| | in, or "None" if unavailable. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__defaults__ | A "tuple" containing default *parameter* values |
-| | for those parameters that have defaults, or "None" |
-| | if no parameters have a default value. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__code__ | The code object representing the compiled function |
-| | body. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__dict__ | The namespace supporting arbitrary function |
-| | attributes. See also: "__dict__ attributes". |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__annotations__ | A "dictionary" containing annotations of |
-| | *parameters*. The keys of the dictionary are the |
-| | parameter names, and "'return'" for the return |
-| | annotation, if provided. See also: |
-| | "object.__annotations__". Changed in version |
-| | 3.14: Annotations are now lazily evaluated. See |
-| | **PEP 649**. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__annotate__ | The *annotate function* for this function, or |
-| | "None" if the function has no annotations. See |
-| | "object.__annotate__". Added in version 3.14. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__kwdefaults__ | A "dictionary" containing defaults for keyword- |
-| | only *parameters*. |
-+----------------------------------------------------+----------------------------------------------------+
-| function.__type_params__ | A "tuple" containing the type parameters of a |
-| | generic function. Added in version 3.12. |
-+----------------------------------------------------+----------------------------------------------------+
-
-Function objects also support getting and setting arbitrary
-attributes, which can be used, for example, to attach metadata to
-functions. Regular attribute dot-notation is used to get and set such
-attributes.
-
-**CPython implementation detail:** CPython’s current implementation
-only supports function attributes on user-defined functions. Function
-attributes on built-in functions may be supported in the future.
-
-Additional information about a function’s definition can be retrieved
-from its code object (accessible via the "__code__" attribute).
-
-
-Instance methods
-----------------
-
-An instance method object combines a class, a class instance and any
-callable object (normally a user-defined function).
-
-Special read-only attributes:
-
-+----------------------------------------------------+----------------------------------------------------+
-| method.__self__ | Refers to the class instance object to which the |
-| | method is bound |
-+----------------------------------------------------+----------------------------------------------------+
-| method.__func__ | Refers to the original function object |
-+----------------------------------------------------+----------------------------------------------------+
-| method.__doc__ | The method’s documentation (same as |
-| | "method.__func__.__doc__"). A "string" if the |
-| | original function had a docstring, else "None". |
-+----------------------------------------------------+----------------------------------------------------+
-| method.__name__ | The name of the method (same as |
-| | "method.__func__.__name__") |
-+----------------------------------------------------+----------------------------------------------------+
-| method.__module__ | The name of the module the method was defined in, |
-| | or "None" if unavailable. |
-+----------------------------------------------------+----------------------------------------------------+
-
-Methods also support accessing (but not setting) the arbitrary
-function attributes on the underlying function object.
-
-User-defined method objects may be created when getting an attribute
-of a class (perhaps via an instance of that class), if that attribute
-is a user-defined function object or a "classmethod" object.
-
-When an instance method object is created by retrieving a user-defined
-function object from a class via one of its instances, its "__self__"
-attribute is the instance, and the method object is said to be
-*bound*. The new method’s "__func__" attribute is the original
-function object.
-
-When an instance method object is created by retrieving a
-"classmethod" object from a class or instance, its "__self__"
-attribute is the class itself, and its "__func__" attribute is the
-function object underlying the class method.
-
-When an instance method object is called, the underlying function
-("__func__") is called, inserting the class instance ("__self__") in
-front of the argument list. For instance, when "C" is a class which
-contains a definition for a function "f()", and "x" is an instance of
-"C", calling "x.f(1)" is equivalent to calling "C.f(x, 1)".
-
-When an instance method object is derived from a "classmethod" object,
-the “class instance” stored in "__self__" will actually be the class
-itself, so that calling either "x.f(1)" or "C.f(1)" is equivalent to
-calling "f(C,1)" where "f" is the underlying function.
-
-It is important to note that user-defined functions which are
-attributes of a class instance are not converted to bound methods;
-this *only* happens when the function is an attribute of the class.
-
-
-Generator functions
--------------------
-
-A function or method which uses the "yield" statement (see section The
-yield statement) is called a *generator function*. Such a function,
-when called, always returns an *iterator* object which can be used to
-execute the body of the function: calling the iterator’s
-"iterator.__next__()" method will cause the function to execute until
-it provides a value using the "yield" statement. When the function
-executes a "return" statement or falls off the end, a "StopIteration"
-exception is raised and the iterator will have reached the end of the
-set of values to be returned.
-
-
-Coroutine functions
--------------------
-
-A function or method which is defined using "async def" is called a
-*coroutine function*. Such a function, when called, returns a
-*coroutine* object. It may contain "await" expressions, as well as
-"async with" and "async for" statements. See also the Coroutine
-Objects section.
-
-
-Asynchronous generator functions
---------------------------------
-
-A function or method which is defined using "async def" and which uses
-the "yield" statement is called a *asynchronous generator function*.
-Such a function, when called, returns an *asynchronous iterator*
-object which can be used in an "async for" statement to execute the
-body of the function.
-
-Calling the asynchronous iterator’s "aiterator.__anext__" method will
-return an *awaitable* which when awaited will execute until it
-provides a value using the "yield" expression. When the function
-executes an empty "return" statement or falls off the end, a
-"StopAsyncIteration" exception is raised and the asynchronous iterator
-will have reached the end of the set of values to be yielded.
-
-
-Built-in functions
-------------------
-
-A built-in function object is a wrapper around a C function. Examples
-of built-in functions are "len()" and "math.sin()" ("math" is a
-standard built-in module). The number and type of the arguments are
-determined by the C function. Special read-only attributes:
-
-* "__doc__" is the function’s documentation string, or "None" if
- unavailable. See "function.__doc__".
-
-* "__name__" is the function’s name. See "function.__name__".
-
-* "__self__" is set to "None" (but see the next item).
-
-* "__module__" is the name of the module the function was defined in
- or "None" if unavailable. See "function.__module__".
-
-
-Built-in methods
-----------------
-
-This is really a different disguise of a built-in function, this time
-containing an object passed to the C function as an implicit extra
-argument. An example of a built-in method is "alist.append()",
-assuming *alist* is a list object. In this case, the special read-only
-attribute "__self__" is set to the object denoted by *alist*. (The
-attribute has the same semantics as it does with "other instance
-methods".)
-
-
-Classes
--------
-
-Classes are callable. These objects normally act as factories for new
-instances of themselves, but variations are possible for class types
-that override "__new__()". The arguments of the call are passed to
-"__new__()" and, in the typical case, to "__init__()" to initialize
-the new instance.
-
-
-Class Instances
----------------
-
-Instances of arbitrary classes can be made callable by defining a
-"__call__()" method in their class.
-
-
-Modules
-=======
-
-Modules are a basic organizational unit of Python code, and are
-created by the import system as invoked either by the "import"
-statement, or by calling functions such as "importlib.import_module()"
-and built-in "__import__()". A module object has a namespace
-implemented by a "dictionary" object (this is the dictionary
-referenced by the "__globals__" attribute of functions defined in the
-module). Attribute references are translated to lookups in this
-dictionary, e.g., "m.x" is equivalent to "m.__dict__["x"]". A module
-object does not contain the code object used to initialize the module
-(since it isn’t needed once the initialization is done).
-
-Attribute assignment updates the module’s namespace dictionary, e.g.,
-"m.x = 1" is equivalent to "m.__dict__["x"] = 1".
-
-
-Import-related attributes on module objects
--------------------------------------------
-
-Module objects have the following attributes that relate to the import
-system. When a module is created using the machinery associated with
-the import system, these attributes are filled in based on the
-module’s *spec*, before the *loader* executes and loads the module.
-
-To create a module dynamically rather than using the import system,
-it’s recommended to use "importlib.util.module_from_spec()", which
-will set the various import-controlled attributes to appropriate
-values. It’s also possible to use the "types.ModuleType" constructor
-to create modules directly, but this technique is more error-prone, as
-most attributes must be manually set on the module object after it has
-been created when using this approach.
-
-Caution:
-
- With the exception of "__name__", it is **strongly** recommended
- that you rely on "__spec__" and its attributes instead of any of the
- other individual attributes listed in this subsection. Note that
- updating an attribute on "__spec__" will not update the
- corresponding attribute on the module itself:
-
- >>> import typing
- >>> typing.__name__, typing.__spec__.name
- ('typing', 'typing')
- >>> typing.__spec__.name = 'spelling'
- >>> typing.__name__, typing.__spec__.name
- ('typing', 'spelling')
- >>> typing.__name__ = 'keyboard_smashing'
- >>> typing.__name__, typing.__spec__.name
- ('keyboard_smashing', 'spelling')
-
-module.__name__
-
- The name used to uniquely identify the module in the import system.
- For a directly executed module, this will be set to ""__main__"".
-
- This attribute must be set to the fully qualified name of the
- module. It is expected to match the value of
- "module.__spec__.name".
-
-module.__spec__
-
- A record of the module’s import-system-related state.
-
- Set to the "module spec" that was used when importing the module.
- See Module specs for more details.
-
- Added in version 3.4.
-
-module.__package__
-
- The *package* a module belongs to.
-
- If the module is top-level (that is, not a part of any specific
- package) then the attribute should be set to "''" (the empty
- string). Otherwise, it should be set to the name of the module’s
- package (which can be equal to "module.__name__" if the module
- itself is a package). See **PEP 366** for further details.
-
- This attribute is used instead of "__name__" to calculate explicit
- relative imports for main modules. It defaults to "None" for
- modules created dynamically using the "types.ModuleType"
- constructor; use "importlib.util.module_from_spec()" instead to
- ensure the attribute is set to a "str".
-
- It is **strongly** recommended that you use
- "module.__spec__.parent" instead of "module.__package__".
- "__package__" is now only used as a fallback if "__spec__.parent"
- is not set, and this fallback path is deprecated.
-
- Changed in version 3.4: This attribute now defaults to "None" for
- modules created dynamically using the "types.ModuleType"
- constructor. Previously the attribute was optional.
-
- Changed in version 3.6: The value of "__package__" is expected to
- be the same as "__spec__.parent". "__package__" is now only used as
- a fallback during import resolution if "__spec__.parent" is not
- defined.
-
- Changed in version 3.10: "ImportWarning" is raised if an import
- resolution falls back to "__package__" instead of
- "__spec__.parent".
-
- Changed in version 3.12: Raise "DeprecationWarning" instead of
- "ImportWarning" when falling back to "__package__" during import
- resolution.
-
- Deprecated since version 3.13, will be removed in version 3.15:
- "__package__" will cease to be set or taken into consideration by
- the import system or standard library.
-
-module.__loader__
-
- The *loader* object that the import machinery used to load the
- module.
-
- This attribute is mostly useful for introspection, but can be used
- for additional loader-specific functionality, for example getting
- data associated with a loader.
-
- "__loader__" defaults to "None" for modules created dynamically
- using the "types.ModuleType" constructor; use
- "importlib.util.module_from_spec()" instead to ensure the attribute
- is set to a *loader* object.
-
- It is **strongly** recommended that you use
- "module.__spec__.loader" instead of "module.__loader__".
-
- Changed in version 3.4: This attribute now defaults to "None" for
- modules created dynamically using the "types.ModuleType"
- constructor. Previously the attribute was optional.
-
- Deprecated since version 3.12, will be removed in version 3.16:
- Setting "__loader__" on a module while failing to set
- "__spec__.loader" is deprecated. In Python 3.16, "__loader__" will
- cease to be set or taken into consideration by the import system or
- the standard library.
-
-module.__path__
-
- A (possibly empty) *sequence* of strings enumerating the locations
- where the package’s submodules will be found. Non-package modules
- should not have a "__path__" attribute. See __path__ attributes on
- modules for more details.
-
- It is **strongly** recommended that you use
- "module.__spec__.submodule_search_locations" instead of
- "module.__path__".
-
-module.__file__
-
-module.__cached__
-
- "__file__" and "__cached__" are both optional attributes that may
- or may not be set. Both attributes should be a "str" when they are
- available.
-
- "__file__" indicates the pathname of the file from which the module
- was loaded (if loaded from a file), or the pathname of the shared
- library file for extension modules loaded dynamically from a shared
- library. It might be missing for certain types of modules, such as
- C modules that are statically linked into the interpreter, and the
- import system may opt to leave it unset if it has no semantic
- meaning (for example, a module loaded from a database).
-
- If "__file__" is set then the "__cached__" attribute might also be
- set, which is the path to any compiled version of the code (for
- example, a byte-compiled file). The file does not need to exist to
- set this attribute; the path can simply point to where the compiled
- file *would* exist (see **PEP 3147**).
-
- Note that "__cached__" may be set even if "__file__" is not set.
- However, that scenario is quite atypical. Ultimately, the *loader*
- is what makes use of the module spec provided by the *finder* (from
- which "__file__" and "__cached__" are derived). So if a loader can
- load from a cached module but otherwise does not load from a file,
- that atypical scenario may be appropriate.
-
- It is **strongly** recommended that you use
- "module.__spec__.cached" instead of "module.__cached__".
-
- Deprecated since version 3.13, will be removed in version 3.15:
- Setting "__cached__" on a module while failing to set
- "__spec__.cached" is deprecated. In Python 3.15, "__cached__" will
- cease to be set or taken into consideration by the import system or
- standard library.
-
-
-Other writable attributes on module objects
--------------------------------------------
-
-As well as the import-related attributes listed above, module objects
-also have the following writable attributes:
-
-module.__doc__
-
- The module’s documentation string, or "None" if unavailable. See
- also: "__doc__ attributes".
-
-module.__annotations__
-
- A dictionary containing *variable annotations* collected during
- module body execution. For best practices on working with
- "__annotations__", see "annotationlib".
-
- Changed in version 3.14: Annotations are now lazily evaluated. See
- **PEP 649**.
-
-module.__annotate__
-
- The *annotate function* for this module, or "None" if the module
- has no annotations. See also: "__annotate__" attributes.
-
- Added in version 3.14.
-
-
-Module dictionaries
--------------------
-
-Module objects also have the following special read-only attribute:
-
-module.__dict__
-
- The module’s namespace as a dictionary object. Uniquely among the
- attributes listed here, "__dict__" cannot be accessed as a global
- variable from within a module; it can only be accessed as an
- attribute on module objects.
-
- **CPython implementation detail:** Because of the way CPython
- clears module dictionaries, the module dictionary will be cleared
- when the module falls out of scope even if the dictionary still has
- live references. To avoid this, copy the dictionary or keep the
- module around while using its dictionary directly.
-
-
-Custom classes
-==============
-
-Custom class types are typically created by class definitions (see
-section Class definitions). A class has a namespace implemented by a
-dictionary object. Class attribute references are translated to
-lookups in this dictionary, e.g., "C.x" is translated to
-"C.__dict__["x"]" (although there are a number of hooks which allow
-for other means of locating attributes). When the attribute name is
-not found there, the attribute search continues in the base classes.
-This search of the base classes uses the C3 method resolution order
-which behaves correctly even in the presence of ‘diamond’ inheritance
-structures where there are multiple inheritance paths leading back to
-a common ancestor. Additional details on the C3 MRO used by Python can
-be found at The Python 2.3 Method Resolution Order.
-
-When a class attribute reference (for class "C", say) would yield a
-class method object, it is transformed into an instance method object
-whose "__self__" attribute is "C". When it would yield a
-"staticmethod" object, it is transformed into the object wrapped by
-the static method object. See section Implementing Descriptors for
-another way in which attributes retrieved from a class may differ from
-those actually contained in its "__dict__".
-
-Class attribute assignments update the class’s dictionary, never the
-dictionary of a base class.
-
-A class object can be called (see above) to yield a class instance
-(see below).
-
-
-Special attributes
-------------------
-
-+----------------------------------------------------+----------------------------------------------------+
-| Attribute | Meaning |
-|====================================================|====================================================|
-| type.__name__ | The class’s name. See also: "__name__ attributes". |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__qualname__ | The class’s *qualified name*. See also: |
-| | "__qualname__ attributes". |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__module__ | The name of the module in which the class was |
-| | defined. |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__dict__ | A "mapping proxy" providing a read-only view of |
-| | the class’s namespace. See also: "__dict__ |
-| | attributes". |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__bases__ | A "tuple" containing the class’s bases. In most |
-| | cases, for a class defined as "class X(A, B, C)", |
-| | "X.__bases__" will be exactly equal to "(A, B, |
-| | C)". |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__doc__ | The class’s documentation string, or "None" if |
-| | undefined. Not inherited by subclasses. |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__annotations__ | A dictionary containing *variable annotations* |
-| | collected during class body execution. See also: |
-| | "__annotations__ attributes". For best practices |
-| | on working with "__annotations__", please see |
-| | "annotationlib". Caution: Accessing the |
-| | "__annotations__" attribute of a class object |
-| | directly may yield incorrect results in the |
-| | presence of metaclasses. In addition, the |
-| | attribute may not exist for some classes. Use |
-| | "annotationlib.get_annotations()" to retrieve |
-| | class annotations safely. Changed in version |
-| | 3.14: Annotations are now lazily evaluated. See |
-| | **PEP 649**. |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__annotate__() | The *annotate function* for this class, or "None" |
-| | if the class has no annotations. See also: |
-| | "__annotate__ attributes". Caution: Accessing |
-| | the "__annotate__" attribute of a class object |
-| | directly may yield incorrect results in the |
-| | presence of metaclasses. Use |
-| | "annotationlib.get_annotate_function()" to |
-| | retrieve the annotate function safely. Added in |
-| | version 3.14. |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__type_params__ | A "tuple" containing the type parameters of a |
-| | generic class. Added in version 3.12. |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__static_attributes__ | A "tuple" containing names of attributes of this |
-| | class which are assigned through "self.X" from any |
-| | function in its body. Added in version 3.13. |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__firstlineno__ | The line number of the first line of the class |
-| | definition, including decorators. Setting the |
-| | "__module__" attribute removes the |
-| | "__firstlineno__" item from the type’s dictionary. |
-| | Added in version 3.13. |
-+----------------------------------------------------+----------------------------------------------------+
-| type.__mro__ | The "tuple" of classes that are considered when |
-| | looking for base classes during method resolution. |
-+----------------------------------------------------+----------------------------------------------------+
-
-
-Special methods
----------------
-
-In addition to the special attributes described above, all Python
-classes also have the following two methods available:
-
-type.mro()
-
- This method can be overridden by a metaclass to customize the
- method resolution order for its instances. It is called at class
- instantiation, and its result is stored in "__mro__".
-
-type.__subclasses__()
-
- Each class keeps a list of weak references to its immediate
- subclasses. This method returns a list of all those references
- still alive. The list is in definition order. Example:
-
- >>> class A: pass
- >>> class B(A): pass
- >>> A.__subclasses__()
- [<class 'B'>]
-
-
-Class instances
-===============
-
-A class instance is created by calling a class object (see above). A
-class instance has a namespace implemented as a dictionary which is
-the first place in which attribute references are searched. When an
-attribute is not found there, and the instance’s class has an
-attribute by that name, the search continues with the class
-attributes. If a class attribute is found that is a user-defined
-function object, it is transformed into an instance method object
-whose "__self__" attribute is the instance. Static method and class
-method objects are also transformed; see above under “Classes”. See
-section Implementing Descriptors for another way in which attributes
-of a class retrieved via its instances may differ from the objects
-actually stored in the class’s "__dict__". If no class attribute is
-found, and the object’s class has a "__getattr__()" method, that is
-called to satisfy the lookup.
-
-Attribute assignments and deletions update the instance’s dictionary,
-never a class’s dictionary. If the class has a "__setattr__()" or
-"__delattr__()" method, this is called instead of updating the
-instance dictionary directly.
-
-Class instances can pretend to be numbers, sequences, or mappings if
-they have methods with certain special names. See section Special
-method names.
-
-
-Special attributes
-------------------
-
-object.__class__
-
- The class to which a class instance belongs.
-
-object.__dict__
-
- A dictionary or other mapping object used to store an object’s
- (writable) attributes. Not all instances have a "__dict__"
- attribute; see the section on __slots__ for more details.
-
-
-I/O objects (also known as file objects)
-========================================
-
-A *file object* represents an open file. Various shortcuts are
-available to create file objects: the "open()" built-in function, and
-also "os.popen()", "os.fdopen()", and the "makefile()" method of
-socket objects (and perhaps by other functions or methods provided by
-extension modules).
-
-The objects "sys.stdin", "sys.stdout" and "sys.stderr" are initialized
-to file objects corresponding to the interpreter’s standard input,
-output and error streams; they are all open in text mode and therefore
-follow the interface defined by the "io.TextIOBase" abstract class.
-
-
-Internal types
-==============
-
-A few types used internally by the interpreter are exposed to the
-user. Their definitions may change with future versions of the
-interpreter, but they are mentioned here for completeness.
-
-
-Code objects
-------------
-
-Code objects represent *byte-compiled* executable Python code, or
-*bytecode*. The difference between a code object and a function object
-is that the function object contains an explicit reference to the
-function’s globals (the module in which it was defined), while a code
-object contains no context; also the default argument values are
-stored in the function object, not in the code object (because they
-represent values calculated at run-time). Unlike function objects,
-code objects are immutable and contain no references (directly or
-indirectly) to mutable objects.
-
-
-Special read-only attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_name | The function name |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_qualname | The fully qualified function name Added in |
-| | version 3.11. |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_argcount | The total number of positional *parameters* |
-| | (including positional-only parameters and |
-| | parameters with default values) that the function |
-| | has |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_posonlyargcount | The number of positional-only *parameters* |
-| | (including arguments with default values) that the |
-| | function has |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_kwonlyargcount | The number of keyword-only *parameters* (including |
-| | arguments with default values) that the function |
-| | has |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_nlocals | The number of local variables used by the function |
-| | (including parameters) |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_varnames | A "tuple" containing the names of the local |
-| | variables in the function (starting with the |
-| | parameter names) |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_cellvars | A "tuple" containing the names of local variables |
-| | that are referenced from at least one *nested |
-| | scope* inside the function |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_freevars | A "tuple" containing the names of *free (closure) |
-| | variables* that a *nested scope* references in an |
-| | outer scope. See also "function.__closure__". |
-| | Note: references to global and builtin names are |
-| | *not* included. |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_code | A string representing the sequence of *bytecode* |
-| | instructions in the function |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_consts | A "tuple" containing the literals used by the |
-| | *bytecode* in the function |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_names | A "tuple" containing the names used by the |
-| | *bytecode* in the function |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_filename | The name of the file from which the code was |
-| | compiled |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_firstlineno | The line number of the first line of the function |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_lnotab | A string encoding the mapping from *bytecode* |
-| | offsets to line numbers. For details, see the |
-| | source code of the interpreter. Deprecated since |
-| | version 3.12: This attribute of code objects is |
-| | deprecated, and may be removed in Python 3.15. |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_stacksize | The required stack size of the code object |
-+----------------------------------------------------+----------------------------------------------------+
-| codeobject.co_flags | An "integer" encoding a number of flags for the |
-| | interpreter. |
-+----------------------------------------------------+----------------------------------------------------+
-
-The following flag bits are defined for "co_flags": bit "0x04" is set
-if the function uses the "*arguments" syntax to accept an arbitrary
-number of positional arguments; bit "0x08" is set if the function uses
-the "**keywords" syntax to accept arbitrary keyword arguments; bit
-"0x20" is set if the function is a generator. See Code Objects Bit
-Flags for details on the semantics of each flags that might be
-present.
-
-Future feature declarations ("from __future__ import division") also
-use bits in "co_flags" to indicate whether a code object was compiled
-with a particular feature enabled: bit "0x2000" is set if the function
-was compiled with future division enabled; bits "0x10" and "0x1000"
-were used in earlier versions of Python.
-
-Other bits in "co_flags" are reserved for internal use.
-
-If a code object represents a function and has a docstring, the first
-item in "co_consts" is the docstring of the function.
-
-
-Methods on code objects
-~~~~~~~~~~~~~~~~~~~~~~~
-
-codeobject.co_positions()
-
- Returns an iterable over the source code positions of each
- *bytecode* instruction in the code object.
-
- The iterator returns "tuple"s containing the "(start_line,
- end_line, start_column, end_column)". The *i-th* tuple corresponds
- to the position of the source code that compiled to the *i-th* code
- unit. Column information is 0-indexed utf-8 byte offsets on the
- given source line.
-
- This positional information can be missing. A non-exhaustive lists
- of cases where this may happen:
-
- * Running the interpreter with "-X" "no_debug_ranges".
-
- * Loading a pyc file compiled while using "-X" "no_debug_ranges".
-
- * Position tuples corresponding to artificial instructions.
-
- * Line and column numbers that can’t be represented due to
- implementation specific limitations.
-
- When this occurs, some or all of the tuple elements can be "None".
-
- Added in version 3.11.
-
- Note:
-
- This feature requires storing column positions in code objects
- which may result in a small increase of disk usage of compiled
- Python files or interpreter memory usage. To avoid storing the
- extra information and/or deactivate printing the extra traceback
- information, the "-X" "no_debug_ranges" command line flag or the
- "PYTHONNODEBUGRANGES" environment variable can be used.
-
-codeobject.co_lines()
-
- Returns an iterator that yields information about successive ranges
- of *bytecode*s. Each item yielded is a "(start, end, lineno)"
- "tuple":
-
- * "start" (an "int") represents the offset (inclusive) of the start
- of the *bytecode* range
-
- * "end" (an "int") represents the offset (exclusive) of the end of
- the *bytecode* range
-
- * "lineno" is an "int" representing the line number of the
- *bytecode* range, or "None" if the bytecodes in the given range
- have no line number
-
- The items yielded will have the following properties:
-
- * The first range yielded will have a "start" of 0.
-
- * The "(start, end)" ranges will be non-decreasing and consecutive.
- That is, for any pair of "tuple"s, the "start" of the second will
- be equal to the "end" of the first.
-
- * No range will be backwards: "end >= start" for all triples.
-
- * The last "tuple" yielded will have "end" equal to the size of the
- *bytecode*.
-
- Zero-width ranges, where "start == end", are allowed. Zero-width
- ranges are used for lines that are present in the source code, but
- have been eliminated by the *bytecode* compiler.
-
- Added in version 3.10.
-
- See also:
-
- **PEP 626** - Precise line numbers for debugging and other tools.
- The PEP that introduced the "co_lines()" method.
-
-codeobject.replace(**kwargs)
-
- Return a copy of the code object with new values for the specified
- fields.
-
- Code objects are also supported by the generic function
- "copy.replace()".
-
- Added in version 3.8.
-
-
-Frame objects
--------------
-
-Frame objects represent execution frames. They may occur in traceback
-objects, and are also passed to registered trace functions.
-
-
-Special read-only attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_back | Points to the previous stack frame (towards the |
-| | caller), or "None" if this is the bottom stack |
-| | frame |
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_code | The code object being executed in this frame. |
-| | Accessing this attribute raises an auditing event |
-| | "object.__getattr__" with arguments "obj" and |
-| | ""f_code"". |
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_locals | The mapping used by the frame to look up local |
-| | variables. If the frame refers to an *optimized |
-| | scope*, this may return a write-through proxy |
-| | object. Changed in version 3.13: Return a proxy |
-| | for optimized scopes. |
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_globals | The dictionary used by the frame to look up global |
-| | variables |
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_builtins | The dictionary used by the frame to look up built- |
-| | in (intrinsic) names |
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_lasti | The “precise instruction” of the frame object |
-| | (this is an index into the *bytecode* string of |
-| | the code object) |
-+----------------------------------------------------+----------------------------------------------------+
-
-
-Special writable attributes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_trace | If not "None", this is a function called for |
-| | various events during code execution (this is used |
-| | by debuggers). Normally an event is triggered for |
-| | each new source line (see "f_trace_lines"). |
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_trace_lines | Set this attribute to "False" to disable |
-| | triggering a tracing event for each source line. |
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_trace_opcodes | Set this attribute to "True" to allow per-opcode |
-| | events to be requested. Note that this may lead to |
-| | undefined interpreter behaviour if exceptions |
-| | raised by the trace function escape to the |
-| | function being traced. |
-+----------------------------------------------------+----------------------------------------------------+
-| frame.f_lineno | The current line number of the frame – writing to |
-| | this from within a trace function jumps to the |
-| | given line (only for the bottom-most frame). A |
-| | debugger can implement a Jump command (aka Set |
-| | Next Statement) by writing to this attribute. |
-+----------------------------------------------------+----------------------------------------------------+
-
-
-Frame object methods
-~~~~~~~~~~~~~~~~~~~~
-
-Frame objects support one method:
-
-frame.clear()
-
- This method clears all references to local variables held by the
- frame. Also, if the frame belonged to a *generator*, the generator
- is finalized. This helps break reference cycles involving frame
- objects (for example when catching an exception and storing its
- traceback for later use).
-
- "RuntimeError" is raised if the frame is currently executing or
- suspended.
-
- Added in version 3.4.
-
- Changed in version 3.13: Attempting to clear a suspended frame
- raises "RuntimeError" (as has always been the case for executing
- frames).
-
-
-Traceback objects
------------------
-
-Traceback objects represent the stack trace of an exception. A
-traceback object is implicitly created when an exception occurs, and
-may also be explicitly created by calling "types.TracebackType".
-
-Changed in version 3.7: Traceback objects can now be explicitly
-instantiated from Python code.
-
-For implicitly created tracebacks, when the search for an exception
-handler unwinds the execution stack, at each unwound level a traceback
-object is inserted in front of the current traceback. When an
-exception handler is entered, the stack trace is made available to the
-program. (See section The try statement.) It is accessible as the
-third item of the tuple returned by "sys.exc_info()", and as the
-"__traceback__" attribute of the caught exception.
-
-When the program contains no suitable handler, the stack trace is
-written (nicely formatted) to the standard error stream; if the
-interpreter is interactive, it is also made available to the user as
-"sys.last_traceback".
-
-For explicitly created tracebacks, it is up to the creator of the
-traceback to determine how the "tb_next" attributes should be linked
-to form a full stack trace.
-
-Special read-only attributes:
-
-+----------------------------------------------------+----------------------------------------------------+
-| traceback.tb_frame | Points to the execution frame of the current |
-| | level. Accessing this attribute raises an |
-| | auditing event "object.__getattr__" with arguments |
-| | "obj" and ""tb_frame"". |
-+----------------------------------------------------+----------------------------------------------------+
-| traceback.tb_lineno | Gives the line number where the exception occurred |
-+----------------------------------------------------+----------------------------------------------------+
-| traceback.tb_lasti | Indicates the “precise instruction”. |
-+----------------------------------------------------+----------------------------------------------------+
-
-The line number and last instruction in the traceback may differ from
-the line number of its frame object if the exception occurred in a
-"try" statement with no matching except clause or with a "finally"
-clause.
-
-traceback.tb_next
-
- The special writable attribute "tb_next" is the next level in the
- stack trace (towards the frame where the exception occurred), or
- "None" if there is no next level.
-
- Changed in version 3.7: This attribute is now writable
-
-
-Slice objects
--------------
-
-Slice objects are used to represent slices for "__getitem__()"
-methods. They are also created by the built-in "slice()" function.
-
-Special read-only attributes: "start" is the lower bound; "stop" is
-the upper bound; "step" is the step value; each is "None" if omitted.
-These attributes can have any type.
-
-Slice objects support one method:
-
-slice.indices(self, length)
-
- This method takes a single integer argument *length* and computes
- information about the slice that the slice object would describe if
- applied to a sequence of *length* items. It returns a tuple of
- three integers; respectively these are the *start* and *stop*
- indices and the *step* or stride length of the slice. Missing or
- out-of-bounds indices are handled in a manner consistent with
- regular slices.
-
-
-Static method objects
----------------------
-
-Static method objects provide a way of defeating the transformation of
-function objects to method objects described above. A static method
-object is a wrapper around any other object, usually a user-defined
-method object. When a static method object is retrieved from a class
-or a class instance, the object actually returned is the wrapped
-object, which is not subject to any further transformation. Static
-method objects are also callable. Static method objects are created by
-the built-in "staticmethod()" constructor.
-
-
-Class method objects
---------------------
-
-A class method object, like a static method object, is a wrapper
-around another object that alters the way in which that object is
-retrieved from classes and class instances. The behaviour of class
-method objects upon such retrieval is described above, under “instance
-methods”. Class method objects are created by the built-in
-"classmethod()" constructor.
-''',
- 'typesfunctions': r'''Functions
-*********
-
-Function objects are created by function definitions. The only
-operation on a function object is to call it: "func(argument-list)".
-
-There are really two flavors of function objects: built-in functions
-and user-defined functions. Both support the same operation (to call
-the function), but the implementation is different, hence the
-different object types.
-
-See Function definitions for more information.
-''',
- 'typesmapping': r'''Mapping Types — "dict"
-**********************
-
-A *mapping* object maps *hashable* values to arbitrary objects.
-Mappings are mutable objects. There is currently only one standard
-mapping type, the *dictionary*. (For other containers see the built-
-in "list", "set", and "tuple" classes, and the "collections" module.)
-
-A dictionary’s keys are *almost* arbitrary values. Values that are
-not *hashable*, that is, values containing lists, dictionaries or
-other mutable types (that are compared by value rather than by object
-identity) may not be used as keys. Values that compare equal (such as
-"1", "1.0", and "True") can be used interchangeably to index the same
-dictionary entry.
-
-class dict(**kwargs)
-class dict(mapping, **kwargs)
-class dict(iterable, **kwargs)
-
- Return a new dictionary initialized from an optional positional
- argument and a possibly empty set of keyword arguments.
-
- Dictionaries can be created by several means:
-
- * Use a comma-separated list of "key: value" pairs within braces:
- "{'jack': 4098, 'sjoerd': 4127}" or "{4098: 'jack', 4127:
- 'sjoerd'}"
-
- * Use a dict comprehension: "{}", "{x: x ** 2 for x in range(10)}"
-
- * Use the type constructor: "dict()", "dict([('foo', 100), ('bar',
- 200)])", "dict(foo=100, bar=200)"
-
- If no positional argument is given, an empty dictionary is created.
- If a positional argument is given and it defines a "keys()" method,
- a dictionary is created by calling "__getitem__()" on the argument
- with each returned key from the method. Otherwise, the positional
- argument must be an *iterable* object. Each item in the iterable
- must itself be an iterable with exactly two elements. The first
- element of each item becomes a key in the new dictionary, and the
- second element the corresponding value. If a key occurs more than
- once, the last value for that key becomes the corresponding value
- in the new dictionary.
-
- If keyword arguments are given, the keyword arguments and their
- values are added to the dictionary created from the positional
- argument. If a key being added is already present, the value from
- the keyword argument replaces the value from the positional
- argument.
-
- To illustrate, the following examples all return a dictionary equal
- to "{"one": 1, "two": 2, "three": 3}":
-
- >>> a = dict(one=1, two=2, three=3)
- >>> b = {'one': 1, 'two': 2, 'three': 3}
- >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
- >>> d = dict([('two', 2), ('one', 1), ('three', 3)])
- >>> e = dict({'three': 3, 'one': 1, 'two': 2})
- >>> f = dict({'one': 1, 'three': 3}, two=2)
- >>> a == b == c == d == e == f
- True
-
- Providing keyword arguments as in the first example only works for
- keys that are valid Python identifiers. Otherwise, any valid keys
- can be used.
-
- These are the operations that dictionaries support (and therefore,
- custom mapping types should support too):
-
- list(d)
-
- Return a list of all the keys used in the dictionary *d*.
-
- len(d)
-
- Return the number of items in the dictionary *d*.
-
- d[key]
-
- Return the item of *d* with key *key*. Raises a "KeyError" if
- *key* is not in the map.
-
- If a subclass of dict defines a method "__missing__()" and *key*
- is not present, the "d[key]" operation calls that method with
- the key *key* as argument. The "d[key]" operation then returns
- or raises whatever is returned or raised by the
- "__missing__(key)" call. No other operations or methods invoke
- "__missing__()". If "__missing__()" is not defined, "KeyError"
- is raised. "__missing__()" must be a method; it cannot be an
- instance variable:
-
- >>> class Counter(dict):
- ... def __missing__(self, key):
- ... return 0
- ...
- >>> c = Counter()
- >>> c['red']
- 0
- >>> c['red'] += 1
- >>> c['red']
- 1
-
- The example above shows part of the implementation of
- "collections.Counter". A different "__missing__" method is used
- by "collections.defaultdict".
-
- d[key] = value
-
- Set "d[key]" to *value*.
-
- del d[key]
-
- Remove "d[key]" from *d*. Raises a "KeyError" if *key* is not
- in the map.
-
- key in d
-
- Return "True" if *d* has a key *key*, else "False".
-
- key not in d
-
- Equivalent to "not key in d".
-
- iter(d)
-
- Return an iterator over the keys of the dictionary. This is a
- shortcut for "iter(d.keys())".
-
- clear()
-
- Remove all items from the dictionary.
-
- copy()
-
- Return a shallow copy of the dictionary.
-
- classmethod fromkeys(iterable, value=None, /)
-
- Create a new dictionary with keys from *iterable* and values set
- to *value*.
-
- "fromkeys()" is a class method that returns a new dictionary.
- *value* defaults to "None". All of the values refer to just a
- single instance, so it generally doesn’t make sense for *value*
- to be a mutable object such as an empty list. To get distinct
- values, use a dict comprehension instead.
-
- get(key, default=None)
-
- Return the value for *key* if *key* is in the dictionary, else
- *default*. If *default* is not given, it defaults to "None", so
- that this method never raises a "KeyError".
-
- items()
-
- Return a new view of the dictionary’s items ("(key, value)"
- pairs). See the documentation of view objects.
-
- keys()
-
- Return a new view of the dictionary’s keys. See the
- documentation of view objects.
-
- pop(key[, default])
-
- If *key* is in the dictionary, remove it and return its value,
- else return *default*. If *default* is not given and *key* is
- not in the dictionary, a "KeyError" is raised.
-
- popitem()
-
- Remove and return a "(key, value)" pair from the dictionary.
- Pairs are returned in LIFO (last-in, first-out) order.
-
- "popitem()" is useful to destructively iterate over a
- dictionary, as often used in set algorithms. If the dictionary
- is empty, calling "popitem()" raises a "KeyError".
-
- Changed in version 3.7: LIFO order is now guaranteed. In prior
- versions, "popitem()" would return an arbitrary key/value pair.
-
- reversed(d)
-
- Return a reverse iterator over the keys of the dictionary. This
- is a shortcut for "reversed(d.keys())".
-
- Added in version 3.8.
-
- setdefault(key, default=None)
-
- If *key* is in the dictionary, return its value. If not, insert
- *key* with a value of *default* and return *default*. *default*
- defaults to "None".
-
- update([other])
-
- Update the dictionary with the key/value pairs from *other*,
- overwriting existing keys. Return "None".
-
- "update()" accepts either another object with a "keys()" method
- (in which case "__getitem__()" is called with every key returned
- from the method) or an iterable of key/value pairs (as tuples or
- other iterables of length two). If keyword arguments are
- specified, the dictionary is then updated with those key/value
- pairs: "d.update(red=1, blue=2)".
-
- values()
-
- Return a new view of the dictionary’s values. See the
- documentation of view objects.
-
- An equality comparison between one "dict.values()" view and
- another will always return "False". This also applies when
- comparing "dict.values()" to itself:
-
- >>> d = {'a': 1}
- >>> d.values() == d.values()
- False
-
- d | other
-
- Create a new dictionary with the merged keys and values of *d*
- and *other*, which must both be dictionaries. The values of
- *other* take priority when *d* and *other* share keys.
-
- Added in version 3.9.
-
- d |= other
-
- Update the dictionary *d* with keys and values from *other*,
- which may be either a *mapping* or an *iterable* of key/value
- pairs. The values of *other* take priority when *d* and *other*
- share keys.
-
- Added in version 3.9.
-
- Dictionaries compare equal if and only if they have the same "(key,
- value)" pairs (regardless of ordering). Order comparisons (‘<’,
- ‘<=’, ‘>=’, ‘>’) raise "TypeError".
-
- Dictionaries preserve insertion order. Note that updating a key
- does not affect the order. Keys added after deletion are inserted
- at the end.
-
- >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
- >>> d
- {'one': 1, 'two': 2, 'three': 3, 'four': 4}
- >>> list(d)
- ['one', 'two', 'three', 'four']
- >>> list(d.values())
- [1, 2, 3, 4]
- >>> d["one"] = 42
- >>> d
- {'one': 42, 'two': 2, 'three': 3, 'four': 4}
- >>> del d["two"]
- >>> d["two"] = None
- >>> d
- {'one': 42, 'three': 3, 'four': 4, 'two': None}
-
- Changed in version 3.7: Dictionary order is guaranteed to be
- insertion order. This behavior was an implementation detail of
- CPython from 3.6.
-
- Dictionaries and dictionary views are reversible.
-
- >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}
- >>> d
- {'one': 1, 'two': 2, 'three': 3, 'four': 4}
- >>> list(reversed(d))
- ['four', 'three', 'two', 'one']
- >>> list(reversed(d.values()))
- [4, 3, 2, 1]
- >>> list(reversed(d.items()))
- [('four', 4), ('three', 3), ('two', 2), ('one', 1)]
-
- Changed in version 3.8: Dictionaries are now reversible.
-
-See also:
-
- "types.MappingProxyType" can be used to create a read-only view of a
- "dict".
-
-
-Dictionary view objects
-=======================
-
-The objects returned by "dict.keys()", "dict.values()" and
-"dict.items()" are *view objects*. They provide a dynamic view on the
-dictionary’s entries, which means that when the dictionary changes,
-the view reflects these changes.
-
-Dictionary views can be iterated over to yield their respective data,
-and support membership tests:
-
-len(dictview)
-
- Return the number of entries in the dictionary.
-
-iter(dictview)
-
- Return an iterator over the keys, values or items (represented as
- tuples of "(key, value)") in the dictionary.
-
- Keys and values are iterated over in insertion order. This allows
- the creation of "(value, key)" pairs using "zip()": "pairs =
- zip(d.values(), d.keys())". Another way to create the same list is
- "pairs = [(v, k) for (k, v) in d.items()]".
-
- Iterating views while adding or deleting entries in the dictionary
- may raise a "RuntimeError" or fail to iterate over all entries.
-
- Changed in version 3.7: Dictionary order is guaranteed to be
- insertion order.
-
-x in dictview
-
- Return "True" if *x* is in the underlying dictionary’s keys, values
- or items (in the latter case, *x* should be a "(key, value)"
- tuple).
-
-reversed(dictview)
-
- Return a reverse iterator over the keys, values or items of the
- dictionary. The view will be iterated in reverse order of the
- insertion.
-
- Changed in version 3.8: Dictionary views are now reversible.
-
-dictview.mapping
-
- Return a "types.MappingProxyType" that wraps the original
- dictionary to which the view refers.
-
- Added in version 3.10.
-
-Keys views are set-like since their entries are unique and *hashable*.
-Items views also have set-like operations since the (key, value) pairs
-are unique and the keys are hashable. If all values in an items view
-are hashable as well, then the items view can interoperate with other
-sets. (Values views are not treated as set-like since the entries are
-generally not unique.) For set-like views, all of the operations
-defined for the abstract base class "collections.abc.Set" are
-available (for example, "==", "<", or "^"). While using set
-operators, set-like views accept any iterable as the other operand,
-unlike sets which only accept sets as the input.
-
-An example of dictionary view usage:
-
- >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
- >>> keys = dishes.keys()
- >>> values = dishes.values()
-
- >>> # iteration
- >>> n = 0
- >>> for val in values:
- ... n += val
- ...
- >>> print(n)
- 504
-
- >>> # keys and values are iterated over in the same order (insertion order)
- >>> list(keys)
- ['eggs', 'sausage', 'bacon', 'spam']
- >>> list(values)
- [2, 1, 1, 500]
-
- >>> # view objects are dynamic and reflect dict changes
- >>> del dishes['eggs']
- >>> del dishes['sausage']
- >>> list(keys)
- ['bacon', 'spam']
-
- >>> # set operations
- >>> keys & {'eggs', 'bacon', 'salad'}
- {'bacon'}
- >>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', 'bacon', 'spam'}
- True
- >>> keys | ['juice', 'juice', 'juice'] == {'bacon', 'spam', 'juice'}
- True
-
- >>> # get back a read-only proxy for the original dictionary
- >>> values.mapping
- mappingproxy({'bacon': 1, 'spam': 500})
- >>> values.mapping['spam']
- 500
-''',
- 'typesmethods': r'''Methods
-*******
-
-Methods are functions that are called using the attribute notation.
-There are two flavors: built-in methods (such as "append()" on lists)
-and class instance method. Built-in methods are described with the
-types that support them.
-
-If you access a method (a function defined in a class namespace)
-through an instance, you get a special object: a *bound method* (also
-called instance method) object. When called, it will add the "self"
-argument to the argument list. Bound methods have two special read-
-only attributes: "m.__self__" is the object on which the method
-operates, and "m.__func__" is the function implementing the method.
-Calling "m(arg-1, arg-2, ..., arg-n)" is completely equivalent to
-calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".
-
-Like function objects, bound method objects support getting arbitrary
-attributes. However, since method attributes are actually stored on
-the underlying function object ("method.__func__"), setting method
-attributes on bound methods is disallowed. Attempting to set an
-attribute on a method results in an "AttributeError" being raised. In
-order to set a method attribute, you need to explicitly set it on the
-underlying function object:
-
- >>> class C:
- ... def method(self):
- ... pass
- ...
- >>> c = C()
- >>> c.method.whoami = 'my name is method' # can't set on the method
- Traceback (most recent call last):
- File "<stdin>", line 1, in <module>
- AttributeError: 'method' object has no attribute 'whoami'
- >>> c.method.__func__.whoami = 'my name is method'
- >>> c.method.whoami
- 'my name is method'
-
-See Instance methods for more information.
-''',
- 'typesmodules': r'''Modules
-*******
-
-The only special operation on a module is attribute access: "m.name",
-where *m* is a module and *name* accesses a name defined in *m*’s
-symbol table. Module attributes can be assigned to. (Note that the
-"import" statement is not, strictly speaking, an operation on a module
-object; "import foo" does not require a module object named *foo* to
-exist, rather it requires an (external) *definition* for a module
-named *foo* somewhere.)
-
-A special attribute of every module is "__dict__". This is the
-dictionary containing the module’s symbol table. Modifying this
-dictionary will actually change the module’s symbol table, but direct
-assignment to the "__dict__" attribute is not possible (you can write
-"m.__dict__['a'] = 1", which defines "m.a" to be "1", but you can’t
-write "m.__dict__ = {}"). Modifying "__dict__" directly is not
-recommended.
-
-Modules built into the interpreter are written like this: "<module
-'sys' (built-in)>". If loaded from a file, they are written as
-"<module 'os' from '/usr/local/lib/pythonX.Y/os.pyc'>".
-''',
- 'typesseq': r'''Sequence Types — "list", "tuple", "range"
-*****************************************
-
-There are three basic sequence types: lists, tuples, and range
-objects. Additional sequence types tailored for processing of binary
-data and text strings are described in dedicated sections.
-
-
-Common Sequence Operations
-==========================
-
-The operations in the following table are supported by most sequence
-types, both mutable and immutable. The "collections.abc.Sequence" ABC
-is provided to make it easier to correctly implement these operations
-on custom sequence types.
-
-This table lists the sequence operations sorted in ascending priority.
-In the table, *s* and *t* are sequences of the same type, *n*, *i*,
-*j* and *k* are integers and *x* is an arbitrary object that meets any
-type and value restrictions imposed by *s*.
-
-The "in" and "not in" operations have the same priorities as the
-comparison operations. The "+" (concatenation) and "*" (repetition)
-operations have the same priority as the corresponding numeric
-operations. [3]
-
-+----------------------------+----------------------------------+------------+
-| Operation | Result | Notes |
-|============================|==================================|============|
-| "x in s" | "True" if an item of *s* is | (1) |
-| | equal to *x*, else "False" | |
-+----------------------------+----------------------------------+------------+
-| "x not in s" | "False" if an item of *s* is | (1) |
-| | equal to *x*, else "True" | |
-+----------------------------+----------------------------------+------------+
-| "s + t" | the concatenation of *s* and *t* | (6)(7) |
-+----------------------------+----------------------------------+------------+
-| "s * n" or "n * s" | equivalent to adding *s* to | (2)(7) |
-| | itself *n* times | |
-+----------------------------+----------------------------------+------------+
-| "s[i]" | *i*th item of *s*, origin 0 | (3) |
-+----------------------------+----------------------------------+------------+
-| "s[i:j]" | slice of *s* from *i* to *j* | (3)(4) |
-+----------------------------+----------------------------------+------------+
-| "s[i:j:k]" | slice of *s* from *i* to *j* | (3)(5) |
-| | with step *k* | |
-+----------------------------+----------------------------------+------------+
-| "len(s)" | length of *s* | |
-+----------------------------+----------------------------------+------------+
-| "min(s)" | smallest item of *s* | |
-+----------------------------+----------------------------------+------------+
-| "max(s)" | largest item of *s* | |
-+----------------------------+----------------------------------+------------+
-| "s.index(x[, i[, j]])" | index of the first occurrence of | (8) |
-| | *x* in *s* (at or after index | |
-| | *i* and before index *j*) | |
-+----------------------------+----------------------------------+------------+
-| "s.count(x)" | total number of occurrences of | |
-| | *x* in *s* | |
-+----------------------------+----------------------------------+------------+
-
-Sequences of the same type also support comparisons. In particular,
-tuples and lists are compared lexicographically by comparing
-corresponding elements. This means that to compare equal, every
-element must compare equal and the two sequences must be of the same
-type and have the same length. (For full details see Comparisons in
-the language reference.)
-
-Forward and reversed iterators over mutable sequences access values
-using an index. That index will continue to march forward (or
-backward) even if the underlying sequence is mutated. The iterator
-terminates only when an "IndexError" or a "StopIteration" is
-encountered (or when the index drops below zero).
-
-Notes:
-
-1. While the "in" and "not in" operations are used only for simple
- containment testing in the general case, some specialised sequences
- (such as "str", "bytes" and "bytearray") also use them for
- subsequence testing:
-
- >>> "gg" in "eggs"
- True
-
-2. Values of *n* less than "0" are treated as "0" (which yields an
- empty sequence of the same type as *s*). Note that items in the
- sequence *s* are not copied; they are referenced multiple times.
- This often haunts new Python programmers; consider:
-
- >>> lists = [[]] * 3
- >>> lists
- [[], [], []]
- >>> lists[0].append(3)
- >>> lists
- [[3], [3], [3]]
-
- What has happened is that "[[]]" is a one-element list containing
- an empty list, so all three elements of "[[]] * 3" are references
- to this single empty list. Modifying any of the elements of
- "lists" modifies this single list. You can create a list of
- different lists this way:
-
- >>> lists = [[] for i in range(3)]
- >>> lists[0].append(3)
- >>> lists[1].append(5)
- >>> lists[2].append(7)
- >>> lists
- [[3], [5], [7]]
-
- Further explanation is available in the FAQ entry How do I create a
- multidimensional list?.
-
-3. If *i* or *j* is negative, the index is relative to the end of
- sequence *s*: "len(s) + i" or "len(s) + j" is substituted. But
- note that "-0" is still "0".
-
-4. The slice of *s* from *i* to *j* is defined as the sequence of
- items with index *k* such that "i <= k < j". If *i* or *j* is
- greater than "len(s)", use "len(s)". If *i* is omitted or "None",
- use "0". If *j* is omitted or "None", use "len(s)". If *i* is
- greater than or equal to *j*, the slice is empty.
-
-5. The slice of *s* from *i* to *j* with step *k* is defined as the
- sequence of items with index "x = i + n*k" such that "0 <= n <
- (j-i)/k". In other words, the indices are "i", "i+k", "i+2*k",
- "i+3*k" and so on, stopping when *j* is reached (but never
- including *j*). When *k* is positive, *i* and *j* are reduced to
- "len(s)" if they are greater. When *k* is negative, *i* and *j* are
- reduced to "len(s) - 1" if they are greater. If *i* or *j* are
- omitted or "None", they become “end” values (which end depends on
- the sign of *k*). Note, *k* cannot be zero. If *k* is "None", it
- is treated like "1".
-
-6. Concatenating immutable sequences always results in a new object.
- This means that building up a sequence by repeated concatenation
- will have a quadratic runtime cost in the total sequence length.
- To get a linear runtime cost, you must switch to one of the
- alternatives below:
-
- * if concatenating "str" objects, you can build a list and use
- "str.join()" at the end or else write to an "io.StringIO"
- instance and retrieve its value when complete
-
- * if concatenating "bytes" objects, you can similarly use
- "bytes.join()" or "io.BytesIO", or you can do in-place
- concatenation with a "bytearray" object. "bytearray" objects are
- mutable and have an efficient overallocation mechanism
-
- * if concatenating "tuple" objects, extend a "list" instead
-
- * for other types, investigate the relevant class documentation
-
-7. Some sequence types (such as "range") only support item sequences
- that follow specific patterns, and hence don’t support sequence
- concatenation or repetition.
-
-8. "index" raises "ValueError" when *x* is not found in *s*. Not all
- implementations support passing the additional arguments *i* and
- *j*. These arguments allow efficient searching of subsections of
- the sequence. Passing the extra arguments is roughly equivalent to
- using "s[i:j].index(x)", only without copying any data and with the
- returned index being relative to the start of the sequence rather
- than the start of the slice.
-
-
-Immutable Sequence Types
-========================
-
-The only operation that immutable sequence types generally implement
-that is not also implemented by mutable sequence types is support for
-the "hash()" built-in.
-
-This support allows immutable sequences, such as "tuple" instances, to
-be used as "dict" keys and stored in "set" and "frozenset" instances.
-
-Attempting to hash an immutable sequence that contains unhashable
-values will result in "TypeError".
-
-
-Mutable Sequence Types
-======================
-
-The operations in the following table are defined on mutable sequence
-types. The "collections.abc.MutableSequence" ABC is provided to make
-it easier to correctly implement these operations on custom sequence
-types.
-
-In the table *s* is an instance of a mutable sequence type, *t* is any
-iterable object and *x* is an arbitrary object that meets any type and
-value restrictions imposed by *s* (for example, "bytearray" only
-accepts integers that meet the value restriction "0 <= x <= 255").
-
-+--------------------------------+----------------------------------+-----------------------+
-| Operation | Result | Notes |
-|================================|==================================|=======================|
-| "s[i] = x" | item *i* of *s* is replaced by | |
-| | *x* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s[i:j] = t" | slice of *s* from *i* to *j* is | |
-| | replaced by the contents of the | |
-| | iterable *t* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "del s[i:j]" | same as "s[i:j] = []" | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s[i:j:k] = t" | the elements of "s[i:j:k]" are | (1) |
-| | replaced by those of *t* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "del s[i:j:k]" | removes the elements of | |
-| | "s[i:j:k]" from the list | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.append(x)" | appends *x* to the end of the | |
-| | sequence (same as | |
-| | "s[len(s):len(s)] = [x]") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.clear()" | removes all items from *s* (same | (5) |
-| | as "del s[:]") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.copy()" | creates a shallow copy of *s* | (5) |
-| | (same as "s[:]") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.extend(t)" or "s += t" | extends *s* with the contents of | |
-| | *t* (for the most part the same | |
-| | as "s[len(s):len(s)] = t") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s *= n" | updates *s* with its contents | (6) |
-| | repeated *n* times | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.insert(i, x)" | inserts *x* into *s* at the | |
-| | index given by *i* (same as | |
-| | "s[i:i] = [x]") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.pop()" or "s.pop(i)" | retrieves the item at *i* and | (2) |
-| | also removes it from *s* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.remove(x)" | removes the first item from *s* | (3) |
-| | where "s[i]" is equal to *x* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.reverse()" | reverses the items of *s* in | (4) |
-| | place | |
-+--------------------------------+----------------------------------+-----------------------+
-
-Notes:
-
-1. If *k* is not equal to "1", *t* must have the same length as the
- slice it is replacing.
-
-2. The optional argument *i* defaults to "-1", so that by default the
- last item is removed and returned.
-
-3. "remove()" raises "ValueError" when *x* is not found in *s*.
-
-4. The "reverse()" method modifies the sequence in place for economy
- of space when reversing a large sequence. To remind users that it
- operates by side effect, it does not return the reversed sequence.
-
-5. "clear()" and "copy()" are included for consistency with the
- interfaces of mutable containers that don’t support slicing
- operations (such as "dict" and "set"). "copy()" is not part of the
- "collections.abc.MutableSequence" ABC, but most concrete mutable
- sequence classes provide it.
-
- Added in version 3.3: "clear()" and "copy()" methods.
-
-6. The value *n* is an integer, or an object implementing
- "__index__()". Zero and negative values of *n* clear the sequence.
- Items in the sequence are not copied; they are referenced multiple
- times, as explained for "s * n" under Common Sequence Operations.
-
-
-Lists
-=====
-
-Lists are mutable sequences, typically used to store collections of
-homogeneous items (where the precise degree of similarity will vary by
-application).
-
-class list([iterable])
-
- Lists may be constructed in several ways:
-
- * Using a pair of square brackets to denote the empty list: "[]"
-
- * Using square brackets, separating items with commas: "[a]", "[a,
- b, c]"
-
- * Using a list comprehension: "[x for x in iterable]"
-
- * Using the type constructor: "list()" or "list(iterable)"
-
- The constructor builds a list whose items are the same and in the
- same order as *iterable*’s items. *iterable* may be either a
- sequence, a container that supports iteration, or an iterator
- object. If *iterable* is already a list, a copy is made and
- returned, similar to "iterable[:]". For example, "list('abc')"
- returns "['a', 'b', 'c']" and "list( (1, 2, 3) )" returns "[1, 2,
- 3]". If no argument is given, the constructor creates a new empty
- list, "[]".
-
- Many other operations also produce lists, including the "sorted()"
- built-in.
-
- Lists implement all of the common and mutable sequence operations.
- Lists also provide the following additional method:
-
- sort(*, key=None, reverse=False)
-
- This method sorts the list in place, using only "<" comparisons
- between items. Exceptions are not suppressed - if any comparison
- operations fail, the entire sort operation will fail (and the
- list will likely be left in a partially modified state).
-
- "sort()" accepts two arguments that can only be passed by
- keyword (keyword-only arguments):
-
- *key* specifies a function of one argument that is used to
- extract a comparison key from each list element (for example,
- "key=str.lower"). The key corresponding to each item in the list
- is calculated once and then used for the entire sorting process.
- The default value of "None" means that list items are sorted
- directly without calculating a separate key value.
-
- The "functools.cmp_to_key()" utility is available to convert a
- 2.x style *cmp* function to a *key* function.
-
- *reverse* is a boolean value. If set to "True", then the list
- elements are sorted as if each comparison were reversed.
-
- This method modifies the sequence in place for economy of space
- when sorting a large sequence. To remind users that it operates
- by side effect, it does not return the sorted sequence (use
- "sorted()" to explicitly request a new sorted list instance).
-
- The "sort()" method is guaranteed to be stable. A sort is
- stable if it guarantees not to change the relative order of
- elements that compare equal — this is helpful for sorting in
- multiple passes (for example, sort by department, then by salary
- grade).
-
- For sorting examples and a brief sorting tutorial, see Sorting
- Techniques.
-
- **CPython implementation detail:** While a list is being sorted,
- the effect of attempting to mutate, or even inspect, the list is
- undefined. The C implementation of Python makes the list appear
- empty for the duration, and raises "ValueError" if it can detect
- that the list has been mutated during a sort.
-
-
-Tuples
-======
-
-Tuples are immutable sequences, typically used to store collections of
-heterogeneous data (such as the 2-tuples produced by the "enumerate()"
-built-in). Tuples are also used for cases where an immutable sequence
-of homogeneous data is needed (such as allowing storage in a "set" or
-"dict" instance).
-
-class tuple([iterable])
-
- Tuples may be constructed in a number of ways:
-
- * Using a pair of parentheses to denote the empty tuple: "()"
-
- * Using a trailing comma for a singleton tuple: "a," or "(a,)"
-
- * Separating items with commas: "a, b, c" or "(a, b, c)"
-
- * Using the "tuple()" built-in: "tuple()" or "tuple(iterable)"
-
- The constructor builds a tuple whose items are the same and in the
- same order as *iterable*’s items. *iterable* may be either a
- sequence, a container that supports iteration, or an iterator
- object. If *iterable* is already a tuple, it is returned
- unchanged. For example, "tuple('abc')" returns "('a', 'b', 'c')"
- and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument is
- given, the constructor creates a new empty tuple, "()".
-
- Note that it is actually the comma which makes a tuple, not the
- parentheses. The parentheses are optional, except in the empty
- tuple case, or when they are needed to avoid syntactic ambiguity.
- For example, "f(a, b, c)" is a function call with three arguments,
- while "f((a, b, c))" is a function call with a 3-tuple as the sole
- argument.
-
- Tuples implement all of the common sequence operations.
-
-For heterogeneous collections of data where access by name is clearer
-than access by index, "collections.namedtuple()" may be a more
-appropriate choice than a simple tuple object.
-
-
-Ranges
-======
-
-The "range" type represents an immutable sequence of numbers and is
-commonly used for looping a specific number of times in "for" loops.
-
-class range(stop)
-class range(start, stop[, step])
-
- The arguments to the range constructor must be integers (either
- built-in "int" or any object that implements the "__index__()"
- special method). If the *step* argument is omitted, it defaults to
- "1". If the *start* argument is omitted, it defaults to "0". If
- *step* is zero, "ValueError" is raised.
-
- For a positive *step*, the contents of a range "r" are determined
- by the formula "r[i] = start + step*i" where "i >= 0" and "r[i] <
- stop".
-
- For a negative *step*, the contents of the range are still
- determined by the formula "r[i] = start + step*i", but the
- constraints are "i >= 0" and "r[i] > stop".
-
- A range object will be empty if "r[0]" does not meet the value
- constraint. Ranges do support negative indices, but these are
- interpreted as indexing from the end of the sequence determined by
- the positive indices.
-
- Ranges containing absolute values larger than "sys.maxsize" are
- permitted but some features (such as "len()") may raise
- "OverflowError".
-
- Range examples:
-
- >>> list(range(10))
- [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
- >>> list(range(1, 11))
- [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
- >>> list(range(0, 30, 5))
- [0, 5, 10, 15, 20, 25]
- >>> list(range(0, 10, 3))
- [0, 3, 6, 9]
- >>> list(range(0, -10, -1))
- [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
- >>> list(range(0))
- []
- >>> list(range(1, 0))
- []
-
- Ranges implement all of the common sequence operations except
- concatenation and repetition (due to the fact that range objects
- can only represent sequences that follow a strict pattern and
- repetition and concatenation will usually violate that pattern).
-
- start
-
- The value of the *start* parameter (or "0" if the parameter was
- not supplied)
-
- stop
-
- The value of the *stop* parameter
-
- step
-
- The value of the *step* parameter (or "1" if the parameter was
- not supplied)
-
-The advantage of the "range" type over a regular "list" or "tuple" is
-that a "range" object will always take the same (small) amount of
-memory, no matter the size of the range it represents (as it only
-stores the "start", "stop" and "step" values, calculating individual
-items and subranges as needed).
-
-Range objects implement the "collections.abc.Sequence" ABC, and
-provide features such as containment tests, element index lookup,
-slicing and support for negative indices (see Sequence Types — list,
-tuple, range):
-
->>> r = range(0, 20, 2)
->>> r
-range(0, 20, 2)
->>> 11 in r
-False
->>> 10 in r
-True
->>> r.index(10)
-5
->>> r[5]
-10
->>> r[:5]
-range(0, 10, 2)
->>> r[-1]
-18
-
-Testing range objects for equality with "==" and "!=" compares them as
-sequences. That is, two range objects are considered equal if they
-represent the same sequence of values. (Note that two range objects
-that compare equal might have different "start", "stop" and "step"
-attributes, for example "range(0) == range(2, 1, 3)" or "range(0, 3,
-2) == range(0, 4, 2)".)
-
-Changed in version 3.2: Implement the Sequence ABC. Support slicing
-and negative indices. Test "int" objects for membership in constant
-time instead of iterating through all items.
-
-Changed in version 3.3: Define ‘==’ and ‘!=’ to compare range objects
-based on the sequence of values they define (instead of comparing
-based on object identity).Added the "start", "stop" and "step"
-attributes.
-
-See also:
-
- * The linspace recipe shows how to implement a lazy version of range
- suitable for floating-point applications.
-''',
- 'typesseq-mutable': r'''Mutable Sequence Types
-**********************
-
-The operations in the following table are defined on mutable sequence
-types. The "collections.abc.MutableSequence" ABC is provided to make
-it easier to correctly implement these operations on custom sequence
-types.
-
-In the table *s* is an instance of a mutable sequence type, *t* is any
-iterable object and *x* is an arbitrary object that meets any type and
-value restrictions imposed by *s* (for example, "bytearray" only
-accepts integers that meet the value restriction "0 <= x <= 255").
-
-+--------------------------------+----------------------------------+-----------------------+
-| Operation | Result | Notes |
-|================================|==================================|=======================|
-| "s[i] = x" | item *i* of *s* is replaced by | |
-| | *x* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s[i:j] = t" | slice of *s* from *i* to *j* is | |
-| | replaced by the contents of the | |
-| | iterable *t* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "del s[i:j]" | same as "s[i:j] = []" | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s[i:j:k] = t" | the elements of "s[i:j:k]" are | (1) |
-| | replaced by those of *t* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "del s[i:j:k]" | removes the elements of | |
-| | "s[i:j:k]" from the list | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.append(x)" | appends *x* to the end of the | |
-| | sequence (same as | |
-| | "s[len(s):len(s)] = [x]") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.clear()" | removes all items from *s* (same | (5) |
-| | as "del s[:]") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.copy()" | creates a shallow copy of *s* | (5) |
-| | (same as "s[:]") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.extend(t)" or "s += t" | extends *s* with the contents of | |
-| | *t* (for the most part the same | |
-| | as "s[len(s):len(s)] = t") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s *= n" | updates *s* with its contents | (6) |
-| | repeated *n* times | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.insert(i, x)" | inserts *x* into *s* at the | |
-| | index given by *i* (same as | |
-| | "s[i:i] = [x]") | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.pop()" or "s.pop(i)" | retrieves the item at *i* and | (2) |
-| | also removes it from *s* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.remove(x)" | removes the first item from *s* | (3) |
-| | where "s[i]" is equal to *x* | |
-+--------------------------------+----------------------------------+-----------------------+
-| "s.reverse()" | reverses the items of *s* in | (4) |
-| | place | |
-+--------------------------------+----------------------------------+-----------------------+
-
-Notes:
-
-1. If *k* is not equal to "1", *t* must have the same length as the
- slice it is replacing.
-
-2. The optional argument *i* defaults to "-1", so that by default the
- last item is removed and returned.
-
-3. "remove()" raises "ValueError" when *x* is not found in *s*.
-
-4. The "reverse()" method modifies the sequence in place for economy
- of space when reversing a large sequence. To remind users that it
- operates by side effect, it does not return the reversed sequence.
-
-5. "clear()" and "copy()" are included for consistency with the
- interfaces of mutable containers that don’t support slicing
- operations (such as "dict" and "set"). "copy()" is not part of the
- "collections.abc.MutableSequence" ABC, but most concrete mutable
- sequence classes provide it.
-
- Added in version 3.3: "clear()" and "copy()" methods.
-
-6. The value *n* is an integer, or an object implementing
- "__index__()". Zero and negative values of *n* clear the sequence.
- Items in the sequence are not copied; they are referenced multiple
- times, as explained for "s * n" under Common Sequence Operations.
-''',
- 'unary': r'''Unary arithmetic and bitwise operations
-***************************************
-
-All unary arithmetic and bitwise operations have the same priority:
-
- **u_expr**: "power" | "-" "u_expr" | "+" "u_expr" | "~" "u_expr"
-
-The unary "-" (minus) operator yields the negation of its numeric
-argument; the operation can be overridden with the "__neg__()" special
-method.
-
-The unary "+" (plus) operator yields its numeric argument unchanged;
-the operation can be overridden with the "__pos__()" special method.
-
-The unary "~" (invert) operator yields the bitwise inversion of its
-integer argument. The bitwise inversion of "x" is defined as
-"-(x+1)". It only applies to integral numbers or to custom objects
-that override the "__invert__()" special method.
-
-In all three cases, if the argument does not have the proper type, a
-"TypeError" exception is raised.
-''',
- 'while': r'''The "while" statement
-*********************
-
-The "while" statement is used for repeated execution as long as an
-expression is true:
-
- **while_stmt**: "while" "assignment_expression" ":" "suite"
- ["else" ":" "suite"]
-
-This repeatedly tests the expression and, if it is true, executes the
-first suite; if the expression is false (which may be the first time
-it is tested) the suite of the "else" clause, if present, is executed
-and the loop terminates.
-
-A "break" statement executed in the first suite terminates the loop
-without executing the "else" clause’s suite. A "continue" statement
-executed in the first suite skips the rest of the suite and goes back
-to testing the expression.
-''',
- 'with': r'''The "with" statement
-********************
-
-The "with" statement is used to wrap the execution of a block with
-methods defined by a context manager (see section With Statement
-Context Managers). This allows common "try"…"except"…"finally" usage
-patterns to be encapsulated for convenient reuse.
-
- **with_stmt**: "with" ( "(" "with_stmt_contents" ","? ")" | "with_stmt_contents" ) ":" "suite"
- **with_stmt_contents**: "with_item" ("," "with_item")*
- **with_item**: "expression" ["as" "target"]
-
-The execution of the "with" statement with one “item” proceeds as
-follows:
-
-1. The context expression (the expression given in the "with_item") is
- evaluated to obtain a context manager.
-
-2. The context manager’s "__enter__()" is loaded for later use.
-
-3. The context manager’s "__exit__()" is loaded for later use.
-
-4. The context manager’s "__enter__()" method is invoked.
-
-5. If a target was included in the "with" statement, the return value
- from "__enter__()" is assigned to it.
-
- Note:
-
- The "with" statement guarantees that if the "__enter__()" method
- returns without an error, then "__exit__()" will always be
- called. Thus, if an error occurs during the assignment to the
- target list, it will be treated the same as an error occurring
- within the suite would be. See step 7 below.
-
-6. The suite is executed.
-
-7. The context manager’s "__exit__()" method is invoked. If an
- exception caused the suite to be exited, its type, value, and
- traceback are passed as arguments to "__exit__()". Otherwise, three
- "None" arguments are supplied.
-
- If the suite was exited due to an exception, and the return value
- from the "__exit__()" method was false, the exception is reraised.
- If the return value was true, the exception is suppressed, and
- execution continues with the statement following the "with"
- statement.
-
- If the suite was exited for any reason other than an exception, the
- return value from "__exit__()" is ignored, and execution proceeds
- at the normal location for the kind of exit that was taken.
-
-The following code:
-
- with EXPRESSION as TARGET:
- SUITE
-
-is semantically equivalent to:
-
- manager = (EXPRESSION)
- enter = type(manager).__enter__
- exit = type(manager).__exit__
- value = enter(manager)
- hit_except = False
-
- try:
- TARGET = value
- SUITE
- except:
- hit_except = True
- if not exit(manager, *sys.exc_info()):
- raise
- finally:
- if not hit_except:
- exit(manager, None, None, None)
-
-With more than one item, the context managers are processed as if
-multiple "with" statements were nested:
-
- with A() as a, B() as b:
- SUITE
-
-is semantically equivalent to:
-
- with A() as a:
- with B() as b:
- SUITE
-
-You can also write multi-item context managers in multiple lines if
-the items are surrounded by parentheses. For example:
-
- with (
- A() as a,
- B() as b,
- ):
- SUITE
-
-Changed in version 3.1: Support for multiple context expressions.
-
-Changed in version 3.10: Support for using grouping parentheses to
-break the statement in multiple lines.
-
-See also:
-
- **PEP 343** - The “with” statement
- The specification, background, and examples for the Python "with"
- statement.
-''',
- 'yield': r'''The "yield" statement
-*********************
-
- **yield_stmt**: "yield_expression"
-
-A "yield" statement is semantically equivalent to a yield expression.
-The "yield" statement can be used to omit the parentheses that would
-otherwise be required in the equivalent yield expression statement.
-For example, the yield statements
-
- yield <expr>
- yield from <expr>
-
-are equivalent to the yield expression statements
-
- (yield <expr>)
- (yield from <expr>)
-
-Yield expressions and statements are only used when defining a
-*generator* function, and are only used in the body of the generator
-function. Using "yield" in a function definition is sufficient to
-cause that definition to create a generator function instead of a
-normal function.
-
-For full details of "yield" semantics, refer to the Yield expressions
-section.
-''',
-}
+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.\n'
+ 'Note that it is unnecessary to include the source code for the\n'
+ 'expression that failed in the error message; it will be displayed '
+ 'as\n'
+ 'part of the 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:\n'
+ '\n'
+ ' * If the target list contains one target prefixed with an '
+ 'asterisk,\n'
+ ' called a “starred” target: The object must be an iterable '
+ 'with at\n'
+ ' least as many items as there are targets in the target '
+ 'list, minus\n'
+ ' one. The first items of the iterable are assigned, from '
+ 'left to\n'
+ ' right, to the targets before the starred target. The '
+ 'final items\n'
+ ' of the iterable are assigned to the targets after the '
+ 'starred\n'
+ ' target. A list of the remaining items in the iterable is '
+ 'then\n'
+ ' assigned to the starred target (the list can be empty).\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\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 '
+ 'namespace\n'
+ ' or the outer namespace determined by "nonlocal", '
+ '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 '
+ 'right-hand side\n'
+ ' expression, "a.x" can access either an instance attribute or '
+ '(if no\n'
+ ' instance attribute exists) a class attribute. The left-hand '
+ 'side\n'
+ ' target "a.x" is always set as an instance attribute, '
+ 'creating it if\n'
+ ' necessary. Thus, the two occurrences of "a.x" do not '
+ 'necessarily\n'
+ ' refer to the same attribute: if the right-hand side '
+ 'expression\n'
+ ' refers to a class attribute, the left-hand side creates a '
+ 'new\n'
+ ' instance attribute as the target of the 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/value 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 '
+ 'reference\n'
+ ' is evaluated. It should yield a mutable sequence object '
+ '(such as a\n'
+ ' list). The assigned object should be a sequence object of '
+ 'the same\n'
+ ' type. Next, the lower and upper bound expressions are '
+ 'evaluated,\n'
+ ' insofar they are present; defaults are zero and the '
+ 'sequence’s\n'
+ ' length. The bounds should evaluate to integers. If either '
+ 'bound is\n'
+ ' negative, the sequence’s length is added to it. The '
+ 'resulting\n'
+ ' bounds are clipped to lie between zero and the sequence’s '
+ 'length,\n'
+ ' inclusive. Finally, the sequence object is asked to replace '
+ 'the\n'
+ ' slice with the items of the assigned sequence. The length '
+ 'of the\n'
+ ' 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 statement like "x += 1" can be '
+ 'rewritten as "x\n'
+ '= 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\n'
+ 'a variable or attribute annotation and an optional assignment\n'
+ 'statement:\n'
+ '\n'
+ ' **annotated_assignment_stmt**: "augtarget" ":" '
+ '"expression"\n'
+ ' ["=" ("starred_expression" | '
+ '"yield_expression")]\n'
+ '\n'
+ 'The difference from normal Assignment statements is that only '
+ 'a single\n'
+ 'target is allowed.\n'
+ '\n'
+ 'The assignment target is considered “simple” if it consists of '
+ 'a\n'
+ 'single name that is not enclosed in parentheses. For simple '
+ 'assignment\n'
+ 'targets, if in class or module scope, the annotations are '
+ 'gathered in\n'
+ 'a lazily evaluated annotation scope. The annotations can be '
+ 'evaluated\n'
+ 'using the "__annotations__" attribute of a class or module, or '
+ 'using\n'
+ 'the facilities in the "annotationlib" module.\n'
+ '\n'
+ 'If the assignment target is not simple (an attribute, '
+ 'subscript node,\n'
+ 'or parenthesized name), the annotation is never evaluated.\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 as if there was no annotation present. '
+ 'If the\n'
+ 'right hand side is not present for an expression target, then '
+ 'the\n'
+ 'interpreter evaluates the target except for the last '
+ '"__setitem__()"\n'
+ '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'
+ '\n'
+ 'Changed in version 3.8: Now annotated assignments allow the '
+ 'same\n'
+ 'expressions in the right hand side as regular assignments. '
+ 'Previously,\n'
+ 'some expressions (like un-parenthesized tuple expressions) '
+ 'caused a\n'
+ 'syntax error.\n'
+ '\n'
+ 'Changed in version 3.14: Annotations are now lazily evaluated '
+ 'in a\n'
+ 'separate annotation scope. If the assignment target is not '
+ 'simple,\n'
+ 'annotations are never evaluated.\n',
+ 'assignment-expressions': 'Assignment expressions\n'
+ '**********************\n'
+ '\n'
+ ' **assignment_expression**: ["identifier" ":="] '
+ '"expression"\n'
+ '\n'
+ 'An assignment expression (sometimes also called a '
+ '“named expression”\n'
+ 'or “walrus”) assigns an "expression" to an '
+ '"identifier", while also\n'
+ 'returning the value of the "expression".\n'
+ '\n'
+ 'One common use case is when handling matched '
+ 'regular expressions:\n'
+ '\n'
+ ' if matching := pattern.search(data):\n'
+ ' do_something(matching)\n'
+ '\n'
+ 'Or, when processing a file stream in chunks:\n'
+ '\n'
+ ' while chunk := file.read(9000):\n'
+ ' process(chunk)\n'
+ '\n'
+ 'Assignment expressions must be surrounded by '
+ 'parentheses when used as\n'
+ 'expression statements and when used as '
+ 'sub-expressions in slicing,\n'
+ 'conditional, lambda, keyword-argument, and '
+ 'comprehension-if\n'
+ 'expressions and in "assert", "with", and '
+ '"assignment" statements. In\n'
+ 'all other places where they can be used, '
+ 'parentheses are not required,\n'
+ 'including in "if" and "while" statements.\n'
+ '\n'
+ 'Added in version 3.8: See **PEP 572** for more '
+ 'details about\n'
+ 'assignment expressions.\n',
+ 'async': 'Coroutines\n'
+ '**********\n'
+ '\n'
+ 'Added 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*). "await" expressions, "async for" and '
+ '"async\n'
+ 'with" can only be used in the body of a coroutine function.\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 a "yield from" expression inside the '
+ 'body\n'
+ 'of a coroutine function.\n'
+ '\n'
+ 'An example of a coroutine function:\n'
+ '\n'
+ ' async def func(param1, param2):\n'
+ ' do_stuff()\n'
+ ' await some_coroutine()\n'
+ '\n'
+ 'Changed in version 3.7: "await" and "async" are now keywords;\n'
+ 'previously they were only treated as such inside the body of a\n'
+ 'coroutine function.\n'
+ '\n'
+ '\n'
+ 'The "async for" statement\n'
+ '=========================\n'
+ '\n'
+ ' **async_for_stmt**: "async" "for_stmt"\n'
+ '\n'
+ 'An *asynchronous iterable* provides an "__aiter__" method that\n'
+ 'directly returns an *asynchronous iterator*, which can call\n'
+ 'asynchronous code in its "__anext__" method.\n'
+ '\n'
+ 'The "async for" statement allows convenient iteration over\n'
+ 'asynchronous iterables.\n'
+ '\n'
+ 'The following code:\n'
+ '\n'
+ ' async for TARGET in ITER:\n'
+ ' SUITE\n'
+ ' else:\n'
+ ' SUITE2\n'
+ '\n'
+ 'Is semantically equivalent to:\n'
+ '\n'
+ ' iter = (ITER)\n'
+ ' iter = type(iter).__aiter__(iter)\n'
+ ' running = True\n'
+ '\n'
+ ' while running:\n'
+ ' try:\n'
+ ' TARGET = await type(iter).__anext__(iter)\n'
+ ' except StopAsyncIteration:\n'
+ ' running = False\n'
+ ' else:\n'
+ ' SUITE\n'
+ ' else:\n'
+ ' SUITE2\n'
+ '\n'
+ 'See also "__aiter__()" and "__anext__()" for details.\n'
+ '\n'
+ 'It is a "SyntaxError" to use an "async for" statement outside the '
+ 'body\n'
+ 'of a coroutine function.\n'
+ '\n'
+ '\n'
+ 'The "async with" statement\n'
+ '==========================\n'
+ '\n'
+ ' **async_with_stmt**: "async" "with_stmt"\n'
+ '\n'
+ 'An *asynchronous context manager* is a *context manager* that is '
+ 'able\n'
+ 'to suspend execution in its *enter* and *exit* methods.\n'
+ '\n'
+ 'The following code:\n'
+ '\n'
+ ' async with EXPRESSION as TARGET:\n'
+ ' SUITE\n'
+ '\n'
+ 'is semantically equivalent to:\n'
+ '\n'
+ ' manager = (EXPRESSION)\n'
+ ' aenter = type(manager).__aenter__\n'
+ ' aexit = type(manager).__aexit__\n'
+ ' value = await aenter(manager)\n'
+ ' hit_except = False\n'
+ '\n'
+ ' try:\n'
+ ' TARGET = value\n'
+ ' SUITE\n'
+ ' except:\n'
+ ' hit_except = True\n'
+ ' if not await aexit(manager, *sys.exc_info()):\n'
+ ' raise\n'
+ ' finally:\n'
+ ' if not hit_except:\n'
+ ' await aexit(manager, None, None, None)\n'
+ '\n'
+ 'See also "__aenter__()" and "__aexit__()" for details.\n'
+ '\n'
+ 'It is a "SyntaxError" to use an "async with" statement outside the\n'
+ 'body of a coroutine function.\n'
+ '\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',
+ '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'
+ '\n'
+ 'Private name mangling\n'
+ '=====================\n'
+ '\n'
+ 'When an identifier that textually occurs in a class '
+ 'definition begins\n'
+ 'with two or more underscore characters and does not end '
+ 'in two or more\n'
+ 'underscores, it is considered a *private name* of that '
+ 'class.\n'
+ '\n'
+ 'See also: The class specifications.\n'
+ '\n'
+ 'More precisely, private names are transformed to a '
+ 'longer form before\n'
+ 'code is generated for them. If the transformed name is '
+ 'longer than\n'
+ '255 characters, implementation-defined truncation may '
+ 'happen.\n'
+ '\n'
+ 'The transformation is independent of the syntactical '
+ 'context in which\n'
+ 'the identifier is used but only the following private '
+ 'identifiers are\n'
+ 'mangled:\n'
+ '\n'
+ '* Any name used as the name of a variable that is '
+ 'assigned or read or\n'
+ ' any name of an attribute being accessed.\n'
+ '\n'
+ ' The "__name__" attribute of nested functions, classes, '
+ 'and type\n'
+ ' aliases is however not mangled.\n'
+ '\n'
+ '* The name of imported modules, e.g., "__spam" in '
+ '"import __spam". If\n'
+ ' the module is part of a package (i.e., its name '
+ 'contains a dot), the\n'
+ ' name is *not* mangled, e.g., the "__foo" in "import '
+ '__foo.bar" is\n'
+ ' not mangled.\n'
+ '\n'
+ '* The name of an imported member, e.g., "__f" in "from '
+ 'spam import\n'
+ ' __f".\n'
+ '\n'
+ 'The transformation rule is defined as follows:\n'
+ '\n'
+ '* The class name, with leading underscores removed and a '
+ 'single\n'
+ ' leading underscore inserted, is inserted in front of '
+ 'the identifier,\n'
+ ' e.g., the identifier "__spam" occurring in a class '
+ 'named "Foo",\n'
+ ' "_Foo" or "__Foo" is transformed to "_Foo__spam".\n'
+ '\n'
+ '* If the class name consists only of underscores, the '
+ 'transformation\n'
+ ' is the identity, e.g., the identifier "__spam" '
+ 'occurring in a class\n'
+ ' named "_" or "__" is left as is.\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. The "object" class itself does not provide '
+ 'this method.\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 take 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:\n'
+ '\n'
+ ' This method may still be bypassed when looking up '
+ 'special methods\n'
+ ' as the result of implicit invocation via language '
+ 'syntax or\n'
+ ' built-in functions. See Special method lookup.\n'
+ '\n'
+ ' For certain sensitive attribute accesses, raises an '
+ 'auditing event\n'
+ ' "object.__getattr__" with arguments "obj" and '
+ '"name".\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'
+ ' For certain sensitive attribute assignments, raises '
+ 'an auditing\n'
+ ' event "object.__setattr__" with arguments "obj", '
+ '"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'
+ ' For certain sensitive attribute deletions, raises an '
+ 'auditing event\n'
+ ' "object.__delattr__" with arguments "obj" and '
+ '"name".\n'
+ '\n'
+ 'object.__dir__(self)\n'
+ '\n'
+ ' Called when "dir()" is called on the object. An '
+ 'iterable must be\n'
+ ' returned. "dir()" converts the returned iterable to a '
+ 'list and\n'
+ ' sorts it.\n'
+ '\n'
+ '\n'
+ 'Customizing module attribute access\n'
+ '===================================\n'
+ '\n'
+ 'Special names "__getattr__" and "__dir__" can be also '
+ 'used to\n'
+ 'customize access to module attributes. The "__getattr__" '
+ 'function at\n'
+ 'the module level should accept one argument which is the '
+ 'name of an\n'
+ 'attribute and return the computed value or raise an '
+ '"AttributeError".\n'
+ 'If an attribute is not found on a module object through '
+ 'the normal\n'
+ 'lookup, i.e. "object.__getattribute__()", then '
+ '"__getattr__" is\n'
+ 'searched in the module "__dict__" before raising an '
+ '"AttributeError".\n'
+ 'If found, it is called with the attribute name and the '
+ 'result is\n'
+ 'returned.\n'
+ '\n'
+ 'The "__dir__" function should accept no arguments, and '
+ 'return an\n'
+ 'iterable of strings that represents the names accessible '
+ 'on module. If\n'
+ 'present, this function overrides the standard "dir()" '
+ 'search on a\n'
+ 'module.\n'
+ '\n'
+ 'For a more fine grained customization of the module '
+ 'behavior (setting\n'
+ 'attributes, properties, etc.), one can set the '
+ '"__class__" attribute\n'
+ 'of a module object to a subclass of "types.ModuleType". '
+ 'For example:\n'
+ '\n'
+ ' import sys\n'
+ ' from types import ModuleType\n'
+ '\n'
+ ' class VerboseModule(ModuleType):\n'
+ ' def __repr__(self):\n'
+ " return f'Verbose {self.__name__}'\n"
+ '\n'
+ ' def __setattr__(self, attr, value):\n'
+ " print(f'Setting {attr}...')\n"
+ ' super().__setattr__(attr, value)\n'
+ '\n'
+ ' sys.modules[__name__].__class__ = VerboseModule\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Defining module "__getattr__" and setting module '
+ '"__class__" only\n'
+ ' affect lookups made using the attribute access syntax '
+ '– directly\n'
+ ' accessing the module globals (whether by code within '
+ 'the module, or\n'
+ ' via a reference to the module’s globals dictionary) is '
+ 'unaffected.\n'
+ '\n'
+ 'Changed in version 3.5: "__class__" module attribute is '
+ 'now writable.\n'
+ '\n'
+ 'Added in version 3.7: "__getattr__" and "__dir__" module '
+ 'attributes.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 562** - Module __getattr__ and __dir__\n'
+ ' Describes the "__getattr__" and "__dir__" functions '
+ 'on modules.\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__". '
+ 'The "object"\n'
+ 'class itself does not implement any of these protocols.\n'
+ '\n'
+ 'object.__get__(self, instance, owner=None)\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). The optional *owner* argument is the owner '
+ 'class, while\n'
+ ' *instance* is the instance that the attribute was '
+ 'accessed through,\n'
+ ' or "None" when the attribute is accessed through the '
+ '*owner*.\n'
+ '\n'
+ ' This method should return the computed attribute '
+ 'value or raise an\n'
+ ' "AttributeError" exception.\n'
+ '\n'
+ ' **PEP 252** specifies that "__get__()" is callable '
+ 'with one or two\n'
+ ' arguments. Python’s own built-in descriptors support '
+ 'this\n'
+ ' specification; however, it is likely that some '
+ 'third-party tools\n'
+ ' have descriptors that require both arguments. '
+ 'Python’s own\n'
+ ' "__getattribute__()" implementation always passes in '
+ 'both arguments\n'
+ ' whether they are required or not.\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'
+ ' Note, adding "__set__()" or "__delete__()" changes '
+ 'the kind of\n'
+ ' descriptor to a “data descriptor”. See Invoking '
+ 'Descriptors for\n'
+ ' more details.\n'
+ '\n'
+ 'object.__delete__(self, instance)\n'
+ '\n'
+ ' Called to delete the attribute on an instance '
+ '*instance* of the\n'
+ ' owner class.\n'
+ '\n'
+ 'Instances of descriptors may also have the '
+ '"__objclass__" attribute\n'
+ 'present:\n'
+ '\n'
+ 'object.__objclass__\n'
+ '\n'
+ ' The attribute "__objclass__" is interpreted by the '
+ '"inspect" module\n'
+ ' as 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'
+ ' A dotted lookup such as "super(A, a).x" searches\n'
+ ' "a.__class__.__mro__" for a base class "B" following '
+ '"A" and then\n'
+ ' returns "B.__dict__[\'x\'].__get__(a, A)". If not a '
+ 'descriptor, "x"\n'
+ ' is returned unchanged.\n'
+ '\n'
+ 'For instance bindings, the precedence of descriptor '
+ 'invocation depends\n'
+ 'on which descriptor methods are defined. A descriptor '
+ 'can define any\n'
+ '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 "__get__()" '
+ 'and "__set__()"\n'
+ '(and/or "__delete__()") defined always override a '
+ 'redefinition in an\n'
+ 'instance dictionary. In contrast, non-data descriptors '
+ 'can be\n'
+ 'overridden by instances.\n'
+ '\n'
+ 'Python methods (including those decorated with '
+ '"@staticmethod" and\n'
+ '"@classmethod") are implemented as non-data '
+ 'descriptors. Accordingly,\n'
+ 'instances can redefine and override methods. This '
+ 'allows individual\n'
+ 'instances to acquire behaviors that differ from other '
+ 'instances of the\n'
+ '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. Attribute\n'
+ 'lookup speed can be significantly improved as well.\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'
+ 'Notes on using *__slots__*:\n'
+ '\n'
+ '* When inheriting from a class without *__slots__*, the '
+ '"__dict__" and\n'
+ ' *__weakref__* attribute of the instances will always '
+ 'be 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 defining\n'
+ ' *__slots__* do not support "weak references" to its '
+ 'instances. If\n'
+ ' weak reference support is needed, then add '
+ '"\'__weakref__\'" to the\n'
+ ' sequence of strings in the *__slots__* declaration.\n'
+ '\n'
+ '* *__slots__* are implemented at the class level by '
+ 'creating\n'
+ ' descriptors for each variable name. As a result, '
+ 'class attributes\n'
+ ' cannot be used to set default values for instance '
+ 'variables defined\n'
+ ' by *__slots__*; otherwise, the class attribute would '
+ 'overwrite the\n'
+ ' descriptor assignment.\n'
+ '\n'
+ '* The action of a *__slots__* declaration is not limited '
+ 'to the class\n'
+ ' where it is defined. *__slots__* declared in parents '
+ 'are available\n'
+ ' in child classes. However, instances of a child '
+ 'subclass will get a\n'
+ ' "__dict__" and *__weakref__* unless the subclass also '
+ 'defines\n'
+ ' *__slots__* (which should only contain names of any '
+ '*additional*\n'
+ ' slots).\n'
+ '\n'
+ '* If a class defines a slot also defined in a base '
+ 'class, the instance\n'
+ ' variable defined by the base class slot is '
+ 'inaccessible (except by\n'
+ ' retrieving its descriptor directly from the base '
+ 'class). This\n'
+ ' renders the meaning of the program undefined. In the '
+ 'future, a\n'
+ ' check may be added to prevent this.\n'
+ '\n'
+ '* "TypeError" will be raised if nonempty *__slots__* are '
+ 'defined for a\n'
+ ' class derived from a ""variable-length" built-in type" '
+ 'such as\n'
+ ' "int", "bytes", and "tuple".\n'
+ '\n'
+ '* Any non-string *iterable* may be assigned to '
+ '*__slots__*.\n'
+ '\n'
+ '* If a "dictionary" is used to assign *__slots__*, the '
+ 'dictionary keys\n'
+ ' will be used as the slot names. The values of the '
+ 'dictionary can be\n'
+ ' used to provide per-attribute docstrings that will be '
+ 'recognised by\n'
+ ' "inspect.getdoc()" and displayed in the output of '
+ '"help()".\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'
+ '* If an *iterator* is used for *__slots__* then a '
+ '*descriptor* is\n'
+ ' created for each of the iterator’s values. However, '
+ 'the *__slots__*\n'
+ ' attribute will be an empty iterator.\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. The type\n'
+ 'and value produced is determined by the object. '
+ 'Multiple evaluations\n'
+ 'of the same attribute reference may yield different '
+ 'objects.\n'
+ '\n'
+ 'This production can be customized by overriding the\n'
+ '"__getattribute__()" method or the "__getattr__()" '
+ 'method. The\n'
+ '"__getattribute__()" method is called first and '
+ 'either returns a value\n'
+ 'or raises "AttributeError" if the attribute is not '
+ 'available.\n'
+ '\n'
+ 'If an "AttributeError" is raised and the object has '
+ 'a "__getattr__()"\n'
+ 'method, that method is called as a fallback.\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 statement like "x += 1" can be '
+ 'rewritten as "x\n'
+ '= 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',
+ 'await': 'Await expression\n'
+ '****************\n'
+ '\n'
+ 'Suspend the execution of *coroutine* on an *awaitable* object. Can\n'
+ 'only be used inside a *coroutine function*.\n'
+ '\n'
+ ' **await_expr**: "await" "primary"\n'
+ '\n'
+ 'Added in version 3.5.\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 real type and then multiplied\n'
+ 'together. In the latter case, sequence repetition is performed; '
+ 'a\n'
+ 'negative repetition factor yields an empty sequence.\n'
+ '\n'
+ 'This operation can be customized using the special "__mul__()" '
+ 'and\n'
+ '"__rmul__()" methods.\n'
+ '\n'
+ 'Changed in version 3.14: If only one operand is a complex number, '
+ 'the\n'
+ 'other operand is converted to a floating-point number.\n'
+ '\n'
+ 'The "@" (at) operator is intended to be used for matrix\n'
+ 'multiplication. No builtin Python types implement this operator.\n'
+ '\n'
+ 'This operation can be customized using the special "__matmul__()" '
+ 'and\n'
+ '"__rmatmul__()" methods.\n'
+ '\n'
+ 'Added 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 division operation can be customized using the special\n'
+ '"__truediv__()" and "__rtruediv__()" methods. The floor division\n'
+ 'operation can be customized using the special "__floordiv__()" '
+ 'and\n'
+ '"__rfloordiv__()" methods.\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 *modulo* operation can be customized using the special '
+ '"__mod__()"\n'
+ 'and "__rmod__()" methods.\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 '
+ 'real\n'
+ 'type and then added together. In the latter case, the sequences '
+ 'are\n'
+ 'concatenated.\n'
+ '\n'
+ 'This operation can be customized using the special "__add__()" '
+ 'and\n'
+ '"__radd__()" methods.\n'
+ '\n'
+ 'Changed in version 3.14: If only one operand is a complex number, '
+ 'the\n'
+ 'other operand is converted to a floating-point number.\n'
+ '\n'
+ 'The "-" (subtraction) operator yields the difference of its '
+ 'arguments.\n'
+ 'The numeric arguments are first converted to a common real type.\n'
+ '\n'
+ 'This operation can be customized using the special "__sub__()" '
+ 'and\n'
+ '"__rsub__()" methods.\n'
+ '\n'
+ 'Changed in version 3.14: If only one operand is a complex number, '
+ 'the\n'
+ 'other operand is converted to a floating-point number.\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 or one of them must be a custom object overriding\n'
+ '"__and__()" or "__rand__()" special methods.\n'
+ '\n'
+ 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n'
+ 'arguments, which must be integers or one of them must be a '
+ 'custom\n'
+ 'object overriding "__xor__()" or "__rxor__()" special methods.\n'
+ '\n'
+ 'The "|" operator yields the bitwise (inclusive) OR of its '
+ 'arguments,\n'
+ 'which must be integers or one of them must be a custom object\n'
+ 'overriding "__or__()" or "__ror__()" special methods.\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'
+ 'Accessing "__code__" raises an auditing event '
+ '"object.__getattr__"\n'
+ 'with arguments "obj" and ""__code__"".\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, ...)" roughly translates to\n'
+ ' "type(x).__call__(x, arg1, ...)". The "object" class '
+ 'itself does\n'
+ ' not provide this method.\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**: positional_item ("," '
+ 'positional_item)*\n'
+ ' **positional_item**: "assignment_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'
+ 'argument is placed in the slot, filling it (even if the expression '
+ 'is\n'
+ '"None", it fills the slot). When all arguments have been '
+ 'processed,\n'
+ 'the slots that are still unfilled are filled with the '
+ 'corresponding\n'
+ 'default value from the function definition. (Default values are\n'
+ 'calculated, once, when the function is defined; thus, a mutable '
+ 'object\n'
+ 'such as a list or dictionary used as default value will be shared '
+ 'by\n'
+ 'all calls that don’t specify an argument value for the '
+ 'corresponding\n'
+ 'slot; this should usually be avoided.) If there are any unfilled\n'
+ 'slots for which no default value is specified, a "TypeError" '
+ 'exception\n'
+ 'is raised. Otherwise, the list of filled slots is used as the\n'
+ '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'
+ 'often 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 parameter matching a '
+ 'key\n'
+ 'has already been given a value (by an explicit keyword argument, '
+ 'or\n'
+ 'from another unpacking), a "TypeError" exception is raised.\n'
+ '\n'
+ 'When "**expression" is used, each key in this mapping must be a\n'
+ 'string. Each value from the mapping is assigned to the first '
+ 'formal\n'
+ 'parameter eligible for keyword assignment whose name is equal to '
+ 'the\n'
+ 'key. A key need not be a Python identifier (e.g. ""max-temp °F"" '
+ 'is\n'
+ 'acceptable, although it will not match any formal parameter that '
+ 'could\n'
+ 'be declared). If there is no match to a formal parameter the '
+ 'key-value\n'
+ 'pair is collected by the "**" parameter, if there is one, or if '
+ 'there\n'
+ 'is not, 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'
+ ' If execution reaches the end of the code block without executing '
+ 'a\n'
+ ' "return" statement, the return value is "None".\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" '
+ '["type_params"] ["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. [5] '
+ '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'
+ 'Changed in version 3.9: Classes may be decorated with any valid\n'
+ '"assignment_expression". Previously, the grammar was much more\n'
+ 'restrictive; see **PEP 614** for details.\n'
+ '\n'
+ 'A list of type parameters may be given in square brackets '
+ 'immediately\n'
+ 'after the class’s name. This indicates to static type checkers '
+ 'that\n'
+ 'the class is generic. At runtime, the type parameters can be '
+ 'retrieved\n'
+ 'from the class’s "__type_params__" attribute. See Generic classes '
+ 'for\n'
+ 'more.\n'
+ '\n'
+ 'Changed in version 3.12: Type parameter lists are new in Python '
+ '3.12.\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". Custom '
+ '*rich\n'
+ 'comparison methods* may return non-boolean values. In this '
+ 'case Python\n'
+ 'will call "bool()" on such value in boolean contexts.\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.Decimal(\'NaN\')"\n'
+ ' are special. Any ordered comparison of a number to a '
+ 'not-a-number\n'
+ ' value is false. A counter-intuitive implication is that '
+ 'not-a-number\n'
+ ' values are not equal to themselves. For example, if "x =\n'
+ ' float(\'NaN\')", "3 < x", "x < 3" and "x == x" are all '
+ 'false, while "x\n'
+ ' != x" is true. This behavior is compliant with IEEE 754.\n'
+ '\n'
+ '* "None" and "NotImplemented" are singletons. **PEP 8** '
+ 'advises that\n'
+ ' comparisons for singletons should always be done with "is" '
+ 'or "is\n'
+ ' not", never the equality operators.\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 '
+ 'compared\n'
+ ' only within each of their types, with the restriction that '
+ 'ranges do\n'
+ ' not support order comparison. Equality comparison across '
+ 'these\n'
+ ' types results in inequality, and ordering comparison across '
+ 'these\n'
+ ' types raises "TypeError".\n'
+ '\n'
+ ' Sequences compare lexicographically using comparison of\n'
+ ' corresponding elements. The built-in containers typically '
+ 'assume\n'
+ ' identical objects are equal to themselves. That lets them '
+ 'bypass\n'
+ ' equality tests for identical objects to improve performance '
+ 'and to\n'
+ ' maintain their internal invariants.\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 as\n'
+ ' 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 and\n'
+ ' 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, so\n'
+ ' 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 that\n'
+ ' are equal should either have the same hash value, or be '
+ 'marked as\n'
+ ' 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", '
+ 'for which\n'
+ 'the expression "x is z or x == z" is true, is produced while '
+ 'iterating\n'
+ 'over "y". If an exception is raised during the iteration, it '
+ 'is as if\n'
+ '"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 is y[i] or x == '
+ 'y[i]", and no\n'
+ 'lower integer index raises the "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 truth '
+ 'value of\n'
+ '"in".\n'
+ '\n'
+ '\n'
+ 'Identity comparisons\n'
+ '====================\n'
+ '\n'
+ 'The operators "is" and "is not" test for an object’s '
+ 'identity: "x is\n'
+ 'y" is true if and only if *x* and *y* are the same object. '
+ 'An\n'
+ 'Object’s identity is determined using the "id()" function. '
+ '"x is not\n'
+ 'y" yields the 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'
+ ' | "match_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" "assignment_expression" ":" "suite"\n'
+ ' ("elif" "assignment_expression" ":" "suite")*\n'
+ ' ["else" ":" "suite"]\n'
+ '\n'
+ 'It selects exactly one of the suites by evaluating the '
+ 'expressions one\n'
+ 'by one until one is found to be true (see section Boolean '
+ 'operations\n'
+ 'for the definition of true and false); then that suite is '
+ 'executed\n'
+ '(and no other part of the "if" statement is executed or '
+ 'evaluated).\n'
+ 'If all expressions are false, the suite of the "else" clause, '
+ 'if\n'
+ 'present, is executed.\n'
+ '\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" "assignment_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" "starred_list" ":" '
+ '"suite"\n'
+ ' ["else" ":" "suite"]\n'
+ '\n'
+ 'The "starred_list" expression is evaluated once; it should yield '
+ 'an\n'
+ '*iterable* object. An *iterator* is created for that iterable. '
+ 'The\n'
+ 'first item provided by the iterator is then assigned to the '
+ 'target\n'
+ 'list using the standard rules for assignments (see Assignment\n'
+ 'statements), and the suite is executed. This repeats for each '
+ 'item\n'
+ 'provided by the iterator. When the iterator is exhausted, the '
+ 'suite\n'
+ 'in the "else" clause, if present, is executed, and the loop\n'
+ 'terminates.\n'
+ '\n'
+ 'A "break" statement executed in the first suite terminates the '
+ 'loop\n'
+ 'without executing the "else" clause’s suite. A "continue" '
+ 'statement\n'
+ 'executed in the first suite skips the rest of the suite and '
+ 'continues\n'
+ 'with the next item, or with the "else" clause if there is no '
+ 'next\n'
+ 'item.\n'
+ '\n'
+ 'The for-loop makes assignments to the variables in the target '
+ 'list.\n'
+ 'This overwrites all previous assignments to those variables '
+ 'including\n'
+ 'those made in the suite of the for-loop:\n'
+ '\n'
+ ' for i in range(10):\n'
+ ' print(i)\n'
+ ' i = 5 # this will not affect the for-loop\n'
+ ' # because i will be overwritten with '
+ 'the next\n'
+ ' # index in the range\n'
+ '\n'
+ 'Names in the target list are not deleted when the loop is '
+ 'finished,\n'
+ 'but if the sequence is empty, they will not have been assigned '
+ 'to at\n'
+ 'all by the loop. Hint: the built-in type "range()" represents\n'
+ 'immutable arithmetic sequences of integers. For instance, '
+ 'iterating\n'
+ '"range(3)" successively yields 0, 1, and then 2.\n'
+ '\n'
+ 'Changed in version 3.11: Starred elements are now allowed in '
+ 'the\n'
+ 'expression list.\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" | "try3_stmt"\n'
+ ' **try1_stmt**: "try" ":" "suite"\n'
+ ' ("except" ["expression" ["as" "identifier"]] ":" '
+ '"suite")+\n'
+ ' ["else" ":" "suite"]\n'
+ ' ["finally" ":" "suite"]\n'
+ ' **try2_stmt**: "try" ":" "suite"\n'
+ ' ("except" "*" "expression" ["as" "identifier"] ":" '
+ '"suite")+\n'
+ ' ["else" ":" "suite"]\n'
+ ' ["finally" ":" "suite"]\n'
+ ' **try3_stmt**: "try" ":" "suite"\n'
+ ' "finally" ":" "suite"\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'
+ '"except" clause\n'
+ '---------------\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"\n'
+ 'clauses in turn until one is found that matches the exception. '
+ 'An\n'
+ 'expression-less "except" clause, if present, must be last; it '
+ 'matches\n'
+ 'any exception.\n'
+ '\n'
+ 'For an "except" clause with an expression, the expression must\n'
+ 'evaluate to an exception type or a tuple of exception types. '
+ 'The\n'
+ 'raised exception matches an "except" clause whose expression '
+ 'evaluates\n'
+ 'to the class or a *non-virtual base class* of the exception '
+ 'object, or\n'
+ 'to a tuple that contains such a class.\n'
+ '\n'
+ 'If no "except" clause matches the exception, the search for an\n'
+ 'exception handler continues in the surrounding code and on the\n'
+ 'invocation stack. [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,\n'
+ 'if 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"\n'
+ 'statement. (This means that if two nested handlers exist for the '
+ 'same\n'
+ 'exception, and the exception occurs in the "try" clause of the '
+ 'inner\n'
+ 'handler, the 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, the exception is '
+ 'stored\n'
+ 'in the "sys" module, where it can be accessed from within the '
+ 'body of\n'
+ 'the "except" clause by calling "sys.exception()". When leaving '
+ 'an\n'
+ 'exception handler, the exception stored in the "sys" module is '
+ 'reset\n'
+ 'to its previous value:\n'
+ '\n'
+ ' >>> print(sys.exception())\n'
+ ' None\n'
+ ' >>> try:\n'
+ ' ... raise TypeError\n'
+ ' ... except:\n'
+ ' ... print(repr(sys.exception()))\n'
+ ' ... try:\n'
+ ' ... raise ValueError\n'
+ ' ... except:\n'
+ ' ... print(repr(sys.exception()))\n'
+ ' ... print(repr(sys.exception()))\n'
+ ' ...\n'
+ ' TypeError()\n'
+ ' ValueError()\n'
+ ' TypeError()\n'
+ ' >>> print(sys.exception())\n'
+ ' None\n'
+ '\n'
+ '\n'
+ '"except*" clause\n'
+ '----------------\n'
+ '\n'
+ 'The "except*" clause(s) are used for handling "ExceptionGroup"s. '
+ 'The\n'
+ 'exception type for matching is interpreted as in the case of '
+ '"except",\n'
+ 'but in the case of exception groups we can have partial matches '
+ 'when\n'
+ 'the type matches some of the exceptions in the group. This means '
+ 'that\n'
+ 'multiple "except*" clauses can execute, each handling part of '
+ 'the\n'
+ 'exception group. Each clause executes at most once and handles '
+ 'an\n'
+ 'exception group of all matching exceptions. Each exception in '
+ 'the\n'
+ 'group is handled by at most one "except*" clause, the first '
+ 'that\n'
+ 'matches it.\n'
+ '\n'
+ ' >>> try:\n'
+ ' ... raise ExceptionGroup("eg",\n'
+ ' ... [ValueError(1), TypeError(2), OSError(3), '
+ 'OSError(4)])\n'
+ ' ... except* TypeError as e:\n'
+ " ... print(f'caught {type(e)} with nested "
+ "{e.exceptions}')\n"
+ ' ... except* OSError as e:\n'
+ " ... print(f'caught {type(e)} with nested "
+ "{e.exceptions}')\n"
+ ' ...\n'
+ " caught <class 'ExceptionGroup'> with nested (TypeError(2),)\n"
+ " caught <class 'ExceptionGroup'> with nested (OSError(3), "
+ 'OSError(4))\n'
+ ' + Exception Group Traceback (most recent call last):\n'
+ ' | File "<stdin>", line 2, in <module>\n'
+ ' | ExceptionGroup: eg\n'
+ ' +-+---------------- 1 ----------------\n'
+ ' | ValueError: 1\n'
+ ' +------------------------------------\n'
+ '\n'
+ 'Any remaining exceptions that were not handled by any "except*" '
+ 'clause\n'
+ 'are re-raised at the end, along with all exceptions that were '
+ 'raised\n'
+ 'from within the "except*" clauses. If this list contains more '
+ 'than one\n'
+ 'exception to reraise, they are combined into an exception '
+ 'group.\n'
+ '\n'
+ 'If the raised exception is not an exception group and its type '
+ 'matches\n'
+ 'one of the "except*" clauses, it is caught and wrapped by an '
+ 'exception\n'
+ 'group with an empty message string.\n'
+ '\n'
+ ' >>> try:\n'
+ ' ... raise BlockingIOError\n'
+ ' ... except* BlockingIOError as e:\n'
+ ' ... print(repr(e))\n'
+ ' ...\n'
+ " ExceptionGroup('', (BlockingIOError()))\n"
+ '\n'
+ 'An "except*" clause must have a matching expression; it cannot '
+ 'be\n'
+ '"except*:". Furthermore, this expression cannot contain '
+ 'exception\n'
+ 'group types, because that would have ambiguous semantics.\n'
+ '\n'
+ 'It is not possible to mix "except" and "except*" in the same '
+ '"try".\n'
+ '"break", "continue" and "return" cannot appear in an "except*" '
+ 'clause.\n'
+ '\n'
+ '\n'
+ '"else" clause\n'
+ '-------------\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'
+ '\n'
+ '"finally" clause\n'
+ '----------------\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", "break" or "continue" statement, the '
+ 'saved\n'
+ 'exception 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.’\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'
+ 'Changed in version 3.8: Prior to Python 3.8, a "continue" '
+ 'statement\n'
+ 'was illegal in the "finally" clause due to a problem with the\n'
+ 'implementation.\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_stmt_contents" '
+ '","? ")" | "with_stmt_contents" ) ":" "suite"\n'
+ ' **with_stmt_contents**: "with_item" ("," "with_item")*\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") is\n'
+ ' evaluated to obtain a context manager.\n'
+ '\n'
+ '2. The context manager’s "__enter__()" is loaded for later use.\n'
+ '\n'
+ '3. The context manager’s "__exit__()" is loaded for later use.\n'
+ '\n'
+ '4. The context manager’s "__enter__()" method is invoked.\n'
+ '\n'
+ '5. If a target was included in the "with" statement, the return '
+ 'value\n'
+ ' from "__enter__()" is assigned to it.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' The "with" statement guarantees that if the "__enter__()" '
+ 'method\n'
+ ' 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 7 below.\n'
+ '\n'
+ '6. The suite is executed.\n'
+ '\n'
+ '7. 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'
+ 'The following code:\n'
+ '\n'
+ ' with EXPRESSION as TARGET:\n'
+ ' SUITE\n'
+ '\n'
+ 'is semantically equivalent to:\n'
+ '\n'
+ ' manager = (EXPRESSION)\n'
+ ' enter = type(manager).__enter__\n'
+ ' exit = type(manager).__exit__\n'
+ ' value = enter(manager)\n'
+ ' hit_except = False\n'
+ '\n'
+ ' try:\n'
+ ' TARGET = value\n'
+ ' SUITE\n'
+ ' except:\n'
+ ' hit_except = True\n'
+ ' if not exit(manager, *sys.exc_info()):\n'
+ ' raise\n'
+ ' finally:\n'
+ ' if not hit_except:\n'
+ ' exit(manager, None, None, None)\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 semantically equivalent to:\n'
+ '\n'
+ ' with A() as a:\n'
+ ' with B() as b:\n'
+ ' SUITE\n'
+ '\n'
+ 'You can also write multi-item context managers in multiple lines '
+ 'if\n'
+ 'the items are surrounded by parentheses. For example:\n'
+ '\n'
+ ' with (\n'
+ ' A() as a,\n'
+ ' B() as b,\n'
+ ' ):\n'
+ ' SUITE\n'
+ '\n'
+ 'Changed in version 3.1: Support for multiple context '
+ 'expressions.\n'
+ '\n'
+ 'Changed in version 3.10: Support for using grouping parentheses '
+ 'to\n'
+ 'break the statement in multiple lines.\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'
+ 'The "match" statement\n'
+ '=====================\n'
+ '\n'
+ 'Added in version 3.10.\n'
+ '\n'
+ 'The match statement is used for pattern matching. Syntax:\n'
+ '\n'
+ ' **match_stmt**: \'match\' "subject_expr" ":" NEWLINE INDENT '
+ '"case_block"+ DEDENT\n'
+ ' **subject_expr**: "star_named_expression" "," '
+ '"star_named_expressions"?\n'
+ ' | "named_expression"\n'
+ ' **case_block**: \'case\' "patterns" ["guard"] ":" "block"\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' This section uses single quotes to denote soft keywords.\n'
+ '\n'
+ 'Pattern matching takes a pattern as input (following "case") and '
+ 'a\n'
+ 'subject value (following "match"). The pattern (which may '
+ 'contain\n'
+ 'subpatterns) is matched against the subject value. The outcomes '
+ 'are:\n'
+ '\n'
+ '* A match success or failure (also termed a pattern success or\n'
+ ' failure).\n'
+ '\n'
+ '* Possible binding of matched values to a name. The '
+ 'prerequisites for\n'
+ ' this are further discussed below.\n'
+ '\n'
+ 'The "match" and "case" keywords are soft keywords.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' * **PEP 634** – Structural Pattern Matching: Specification\n'
+ '\n'
+ ' * **PEP 636** – Structural Pattern Matching: Tutorial\n'
+ '\n'
+ '\n'
+ 'Overview\n'
+ '--------\n'
+ '\n'
+ 'Here’s an overview of the logical flow of a match statement:\n'
+ '\n'
+ '1. The subject expression "subject_expr" is evaluated and a '
+ 'resulting\n'
+ ' subject value obtained. If the subject expression contains a '
+ 'comma,\n'
+ ' a tuple is constructed using the standard rules.\n'
+ '\n'
+ '2. Each pattern in a "case_block" is attempted to match with '
+ 'the\n'
+ ' subject value. The specific rules for success or failure are\n'
+ ' described below. The match attempt can also bind some or all '
+ 'of the\n'
+ ' standalone names within the pattern. The precise pattern '
+ 'binding\n'
+ ' rules vary per pattern type and are specified below. **Name\n'
+ ' bindings made during a successful pattern match outlive the\n'
+ ' executed block and can be used after the match statement**.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' During failed pattern matches, some subpatterns may '
+ 'succeed. Do\n'
+ ' not rely on bindings being made for a failed match. '
+ 'Conversely,\n'
+ ' do not rely on variables remaining unchanged after a '
+ 'failed\n'
+ ' match. The exact behavior is dependent on implementation '
+ 'and may\n'
+ ' vary. This is an intentional decision made to allow '
+ 'different\n'
+ ' implementations to add optimizations.\n'
+ '\n'
+ '3. If the pattern succeeds, the corresponding guard (if present) '
+ 'is\n'
+ ' evaluated. In this case all name bindings are guaranteed to '
+ 'have\n'
+ ' happened.\n'
+ '\n'
+ ' * If the guard evaluates as true or is missing, the "block" '
+ 'inside\n'
+ ' "case_block" is executed.\n'
+ '\n'
+ ' * Otherwise, the next "case_block" is attempted as described '
+ 'above.\n'
+ '\n'
+ ' * If there are no further case blocks, the match statement '
+ 'is\n'
+ ' completed.\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Users should generally never rely on a pattern being '
+ 'evaluated.\n'
+ ' Depending on implementation, the interpreter may cache values '
+ 'or use\n'
+ ' other optimizations which skip repeated evaluations.\n'
+ '\n'
+ 'A sample match statement:\n'
+ '\n'
+ ' >>> flag = False\n'
+ ' >>> match (100, 200):\n'
+ ' ... case (100, 300): # Mismatch: 200 != 300\n'
+ " ... print('Case 1')\n"
+ ' ... case (100, 200) if flag: # Successful match, but '
+ 'guard fails\n'
+ " ... print('Case 2')\n"
+ ' ... case (100, y): # Matches and binds y to 200\n'
+ " ... print(f'Case 3, y: {y}')\n"
+ ' ... case _: # Pattern not attempted\n'
+ " ... print('Case 4, I match anything!')\n"
+ ' ...\n'
+ ' Case 3, y: 200\n'
+ '\n'
+ 'In this case, "if flag" is a guard. Read more about that in the '
+ 'next\n'
+ 'section.\n'
+ '\n'
+ '\n'
+ 'Guards\n'
+ '------\n'
+ '\n'
+ ' **guard**: "if" "named_expression"\n'
+ '\n'
+ 'A "guard" (which is part of the "case") must succeed for code '
+ 'inside\n'
+ 'the "case" block to execute. It takes the form: "if" followed '
+ 'by an\n'
+ 'expression.\n'
+ '\n'
+ 'The logical flow of a "case" block with a "guard" follows:\n'
+ '\n'
+ '1. Check that the pattern in the "case" block succeeded. If '
+ 'the\n'
+ ' pattern failed, the "guard" is not evaluated and the next '
+ '"case"\n'
+ ' block is checked.\n'
+ '\n'
+ '2. If the pattern succeeded, evaluate the "guard".\n'
+ '\n'
+ ' * If the "guard" condition evaluates as true, the case block '
+ 'is\n'
+ ' selected.\n'
+ '\n'
+ ' * If the "guard" condition evaluates as false, the case block '
+ 'is\n'
+ ' not selected.\n'
+ '\n'
+ ' * If the "guard" raises an exception during evaluation, the\n'
+ ' exception bubbles up.\n'
+ '\n'
+ 'Guards are allowed to have side effects as they are '
+ 'expressions.\n'
+ 'Guard evaluation must proceed from the first to the last case '
+ 'block,\n'
+ 'one at a time, skipping case blocks whose pattern(s) don’t all\n'
+ 'succeed. (I.e., guard evaluation must happen in order.) Guard\n'
+ 'evaluation must stop once a case block is selected.\n'
+ '\n'
+ '\n'
+ 'Irrefutable Case Blocks\n'
+ '-----------------------\n'
+ '\n'
+ 'An irrefutable case block is a match-all case block. A match\n'
+ 'statement may have at most one irrefutable case block, and it '
+ 'must be\n'
+ 'last.\n'
+ '\n'
+ 'A case block is considered irrefutable if it has no guard and '
+ 'its\n'
+ 'pattern is irrefutable. A pattern is considered irrefutable if '
+ 'we can\n'
+ 'prove from its syntax alone that it will always succeed. Only '
+ 'the\n'
+ 'following patterns are irrefutable:\n'
+ '\n'
+ '* AS Patterns whose left-hand side is irrefutable\n'
+ '\n'
+ '* OR Patterns containing at least one irrefutable pattern\n'
+ '\n'
+ '* Capture Patterns\n'
+ '\n'
+ '* Wildcard Patterns\n'
+ '\n'
+ '* parenthesized irrefutable patterns\n'
+ '\n'
+ '\n'
+ 'Patterns\n'
+ '--------\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' This section uses grammar notations beyond standard EBNF:\n'
+ '\n'
+ ' * the notation "SEP.RULE+" is shorthand for "RULE (SEP '
+ 'RULE)*"\n'
+ '\n'
+ ' * the notation "!RULE" is shorthand for a negative lookahead\n'
+ ' assertion\n'
+ '\n'
+ 'The top-level syntax for "patterns" is:\n'
+ '\n'
+ ' **patterns**: "open_sequence_pattern" | "pattern"\n'
+ ' **pattern**: "as_pattern" | "or_pattern"\n'
+ ' **closed_pattern**: | "literal_pattern"\n'
+ ' | "capture_pattern"\n'
+ ' | "wildcard_pattern"\n'
+ ' | "value_pattern"\n'
+ ' | "group_pattern"\n'
+ ' | "sequence_pattern"\n'
+ ' | "mapping_pattern"\n'
+ ' | "class_pattern"\n'
+ '\n'
+ 'The descriptions below will include a description “in simple '
+ 'terms” of\n'
+ 'what a pattern does for illustration purposes (credits to '
+ 'Raymond\n'
+ 'Hettinger for a document that inspired most of the '
+ 'descriptions). Note\n'
+ 'that these descriptions are purely for illustration purposes and '
+ '**may\n'
+ 'not** reflect the underlying implementation. Furthermore, they '
+ 'do not\n'
+ 'cover all valid forms.\n'
+ '\n'
+ '\n'
+ 'OR Patterns\n'
+ '~~~~~~~~~~~\n'
+ '\n'
+ 'An OR pattern is two or more patterns separated by vertical bars '
+ '"|".\n'
+ 'Syntax:\n'
+ '\n'
+ ' **or_pattern**: "|"."closed_pattern"+\n'
+ '\n'
+ 'Only the final subpattern may be irrefutable, and each '
+ 'subpattern must\n'
+ 'bind the same set of names to avoid ambiguity.\n'
+ '\n'
+ 'An OR pattern matches each of its subpatterns in turn to the '
+ 'subject\n'
+ 'value, until one succeeds. The OR pattern is then considered\n'
+ 'successful. Otherwise, if none of the subpatterns succeed, the '
+ 'OR\n'
+ 'pattern fails.\n'
+ '\n'
+ 'In simple terms, "P1 | P2 | ..." will try to match "P1", if it '
+ 'fails\n'
+ 'it will try to match "P2", succeeding immediately if any '
+ 'succeeds,\n'
+ 'failing otherwise.\n'
+ '\n'
+ '\n'
+ 'AS Patterns\n'
+ '~~~~~~~~~~~\n'
+ '\n'
+ 'An AS pattern matches an OR pattern on the left of the "as" '
+ 'keyword\n'
+ 'against a subject. Syntax:\n'
+ '\n'
+ ' **as_pattern**: "or_pattern" "as" "capture_pattern"\n'
+ '\n'
+ 'If the OR pattern fails, the AS pattern fails. Otherwise, the '
+ 'AS\n'
+ 'pattern binds the subject to the name on the right of the as '
+ 'keyword\n'
+ 'and succeeds. "capture_pattern" cannot be a "_".\n'
+ '\n'
+ 'In simple terms "P as NAME" will match with "P", and on success '
+ 'it\n'
+ 'will set "NAME = <subject>".\n'
+ '\n'
+ '\n'
+ 'Literal Patterns\n'
+ '~~~~~~~~~~~~~~~~\n'
+ '\n'
+ 'A literal pattern corresponds to most literals in Python. '
+ 'Syntax:\n'
+ '\n'
+ ' **literal_pattern**: "signed_number"\n'
+ ' | "signed_number" "+" NUMBER\n'
+ ' | "signed_number" "-" NUMBER\n'
+ ' | "strings"\n'
+ ' | "None"\n'
+ ' | "True"\n'
+ ' | "False"\n'
+ ' **signed_number**: ["-"] NUMBER\n'
+ '\n'
+ 'The rule "strings" and the token "NUMBER" are defined in the '
+ 'standard\n'
+ 'Python grammar. Triple-quoted strings are supported. Raw '
+ 'strings and\n'
+ 'byte strings are supported. f-strings are not supported.\n'
+ '\n'
+ 'The forms "signed_number \'+\' NUMBER" and "signed_number \'-\' '
+ 'NUMBER"\n'
+ 'are for expressing complex numbers; they require a real number '
+ 'on the\n'
+ 'left and an imaginary number on the right. E.g. "3 + 4j".\n'
+ '\n'
+ 'In simple terms, "LITERAL" will succeed only if "<subject> ==\n'
+ 'LITERAL". For the singletons "None", "True" and "False", the '
+ '"is"\n'
+ 'operator is used.\n'
+ '\n'
+ '\n'
+ 'Capture Patterns\n'
+ '~~~~~~~~~~~~~~~~\n'
+ '\n'
+ 'A capture pattern binds the subject value to a name. Syntax:\n'
+ '\n'
+ " **capture_pattern**: !'_' NAME\n"
+ '\n'
+ 'A single underscore "_" is not a capture pattern (this is what '
+ '"!\'_\'"\n'
+ 'expresses). It is instead treated as a "wildcard_pattern".\n'
+ '\n'
+ 'In a given pattern, a given name can only be bound once. E.g. '
+ '"case\n'
+ 'x, x: ..." is invalid while "case [x] | x: ..." is allowed.\n'
+ '\n'
+ 'Capture patterns always succeed. The binding follows scoping '
+ 'rules\n'
+ 'established by the assignment expression operator in **PEP '
+ '572**; the\n'
+ 'name becomes a local variable in the closest containing function '
+ 'scope\n'
+ 'unless there’s an applicable "global" or "nonlocal" statement.\n'
+ '\n'
+ 'In simple terms "NAME" will always succeed and it will set "NAME '
+ '=\n'
+ '<subject>".\n'
+ '\n'
+ '\n'
+ 'Wildcard Patterns\n'
+ '~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ 'A wildcard pattern always succeeds (matches anything) and binds '
+ 'no\n'
+ 'name. Syntax:\n'
+ '\n'
+ " **wildcard_pattern**: '_'\n"
+ '\n'
+ '"_" is a soft keyword within any pattern, but only within '
+ 'patterns.\n'
+ 'It is an identifier, as usual, even within "match" subject\n'
+ 'expressions, "guard"s, and "case" blocks.\n'
+ '\n'
+ 'In simple terms, "_" will always succeed.\n'
+ '\n'
+ '\n'
+ 'Value Patterns\n'
+ '~~~~~~~~~~~~~~\n'
+ '\n'
+ 'A value pattern represents a named value in Python. Syntax:\n'
+ '\n'
+ ' **value_pattern**: "attr"\n'
+ ' **attr**: "name_or_attr" "." NAME\n'
+ ' **name_or_attr**: "attr" | NAME\n'
+ '\n'
+ 'The dotted name in the pattern is looked up using standard '
+ 'Python name\n'
+ 'resolution rules. The pattern succeeds if the value found '
+ 'compares\n'
+ 'equal to the subject value (using the "==" equality operator).\n'
+ '\n'
+ 'In simple terms "NAME1.NAME2" will succeed only if "<subject> '
+ '==\n'
+ 'NAME1.NAME2"\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' If the same value occurs multiple times in the same match '
+ 'statement,\n'
+ ' the interpreter may cache the first value found and reuse it '
+ 'rather\n'
+ ' than repeat the same lookup. This cache is strictly tied to a '
+ 'given\n'
+ ' execution of a given match statement.\n'
+ '\n'
+ '\n'
+ 'Group Patterns\n'
+ '~~~~~~~~~~~~~~\n'
+ '\n'
+ 'A group pattern allows users to add parentheses around patterns '
+ 'to\n'
+ 'emphasize the intended grouping. Otherwise, it has no '
+ 'additional\n'
+ 'syntax. Syntax:\n'
+ '\n'
+ ' **group_pattern**: "(" "pattern" ")"\n'
+ '\n'
+ 'In simple terms "(P)" has the same effect as "P".\n'
+ '\n'
+ '\n'
+ 'Sequence Patterns\n'
+ '~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ 'A sequence pattern contains several subpatterns to be matched '
+ 'against\n'
+ 'sequence elements. The syntax is similar to the unpacking of a '
+ 'list or\n'
+ 'tuple.\n'
+ '\n'
+ ' **sequence_pattern**: "[" ["maybe_sequence_pattern"] '
+ '"]"\n'
+ ' | "(" ["open_sequence_pattern"] ")"\n'
+ ' **open_sequence_pattern**: "maybe_star_pattern" "," '
+ '["maybe_sequence_pattern"]\n'
+ ' **maybe_sequence_pattern**: ","."maybe_star_pattern"+ ","?\n'
+ ' **maybe_star_pattern**: "star_pattern" | "pattern"\n'
+ ' **star_pattern**: "*" ("capture_pattern" | '
+ '"wildcard_pattern")\n'
+ '\n'
+ 'There is no difference if parentheses or square brackets are '
+ 'used for\n'
+ 'sequence patterns (i.e. "(...)" vs "[...]" ).\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' A single pattern enclosed in parentheses without a trailing '
+ 'comma\n'
+ ' (e.g. "(3 | 4)") is a group pattern. While a single pattern '
+ 'enclosed\n'
+ ' in square brackets (e.g. "[3 | 4]") is still a sequence '
+ 'pattern.\n'
+ '\n'
+ 'At most one star subpattern may be in a sequence pattern. The '
+ 'star\n'
+ 'subpattern may occur in any position. If no star subpattern is\n'
+ 'present, the sequence pattern is a fixed-length sequence '
+ 'pattern;\n'
+ 'otherwise it is a variable-length sequence pattern.\n'
+ '\n'
+ 'The following is the logical flow for matching a sequence '
+ 'pattern\n'
+ 'against a subject value:\n'
+ '\n'
+ '1. If the subject value is not a sequence [2], the sequence '
+ 'pattern\n'
+ ' fails.\n'
+ '\n'
+ '2. If the subject value is an instance of "str", "bytes" or\n'
+ ' "bytearray" the sequence pattern fails.\n'
+ '\n'
+ '3. The subsequent steps depend on whether the sequence pattern '
+ 'is\n'
+ ' fixed or variable-length.\n'
+ '\n'
+ ' If the sequence pattern is fixed-length:\n'
+ '\n'
+ ' 1. If the length of the subject sequence is not equal to the '
+ 'number\n'
+ ' of subpatterns, the sequence pattern fails\n'
+ '\n'
+ ' 2. Subpatterns in the sequence pattern are matched to their\n'
+ ' corresponding items in the subject sequence from left to '
+ 'right.\n'
+ ' Matching stops as soon as a subpattern fails. If all\n'
+ ' subpatterns succeed in matching their corresponding item, '
+ 'the\n'
+ ' sequence pattern succeeds.\n'
+ '\n'
+ ' Otherwise, if the sequence pattern is variable-length:\n'
+ '\n'
+ ' 1. If the length of the subject sequence is less than the '
+ 'number of\n'
+ ' non-star subpatterns, the sequence pattern fails.\n'
+ '\n'
+ ' 2. The leading non-star subpatterns are matched to their\n'
+ ' corresponding items as for fixed-length sequences.\n'
+ '\n'
+ ' 3. If the previous step succeeds, the star subpattern matches '
+ 'a\n'
+ ' list formed of the remaining subject items, excluding the\n'
+ ' remaining items corresponding to non-star subpatterns '
+ 'following\n'
+ ' the star subpattern.\n'
+ '\n'
+ ' 4. Remaining non-star subpatterns are matched to their\n'
+ ' corresponding subject items, as for a fixed-length '
+ 'sequence.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' The length of the subject sequence is obtained via "len()" '
+ '(i.e.\n'
+ ' via the "__len__()" protocol). This length may be cached '
+ 'by the\n'
+ ' interpreter in a similar manner as value patterns.\n'
+ '\n'
+ 'In simple terms "[P1, P2, P3," … ", P<N>]" matches only if all '
+ 'the\n'
+ 'following happens:\n'
+ '\n'
+ '* check "<subject>" is a sequence\n'
+ '\n'
+ '* "len(subject) == <N>"\n'
+ '\n'
+ '* "P1" matches "<subject>[0]" (note that this match can also '
+ 'bind\n'
+ ' names)\n'
+ '\n'
+ '* "P2" matches "<subject>[1]" (note that this match can also '
+ 'bind\n'
+ ' names)\n'
+ '\n'
+ '* … and so on for the corresponding pattern/element.\n'
+ '\n'
+ '\n'
+ 'Mapping Patterns\n'
+ '~~~~~~~~~~~~~~~~\n'
+ '\n'
+ 'A mapping pattern contains one or more key-value patterns. The '
+ 'syntax\n'
+ 'is similar to the construction of a dictionary. Syntax:\n'
+ '\n'
+ ' **mapping_pattern**: "{" ["items_pattern"] "}"\n'
+ ' **items_pattern**: ","."key_value_pattern"+ ","?\n'
+ ' **key_value_pattern**: ("literal_pattern" | '
+ '"value_pattern") ":" "pattern"\n'
+ ' | "double_star_pattern"\n'
+ ' **double_star_pattern**: "**" "capture_pattern"\n'
+ '\n'
+ 'At most one double star pattern may be in a mapping pattern. '
+ 'The\n'
+ 'double star pattern must be the last subpattern in the mapping\n'
+ 'pattern.\n'
+ '\n'
+ 'Duplicate keys in mapping patterns are disallowed. Duplicate '
+ 'literal\n'
+ 'keys will raise a "SyntaxError". Two keys that otherwise have '
+ 'the same\n'
+ 'value will raise a "ValueError" at runtime.\n'
+ '\n'
+ 'The following is the logical flow for matching a mapping '
+ 'pattern\n'
+ 'against a subject value:\n'
+ '\n'
+ '1. If the subject value is not a mapping [3],the mapping '
+ 'pattern\n'
+ ' fails.\n'
+ '\n'
+ '2. If every key given in the mapping pattern is present in the '
+ 'subject\n'
+ ' mapping, and the pattern for each key matches the '
+ 'corresponding\n'
+ ' item of the subject mapping, the mapping pattern succeeds.\n'
+ '\n'
+ '3. If duplicate keys are detected in the mapping pattern, the '
+ 'pattern\n'
+ ' is considered invalid. A "SyntaxError" is raised for '
+ 'duplicate\n'
+ ' literal values; or a "ValueError" for named keys of the same '
+ 'value.\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Key-value pairs are matched using the two-argument form of '
+ 'the\n'
+ ' mapping subject’s "get()" method. Matched key-value pairs '
+ 'must\n'
+ ' already be present in the mapping, and not created on-the-fly '
+ 'via\n'
+ ' "__missing__()" or "__getitem__()".\n'
+ '\n'
+ 'In simple terms "{KEY1: P1, KEY2: P2, ... }" matches only if all '
+ 'the\n'
+ 'following happens:\n'
+ '\n'
+ '* check "<subject>" is a mapping\n'
+ '\n'
+ '* "KEY1 in <subject>"\n'
+ '\n'
+ '* "P1" matches "<subject>[KEY1]"\n'
+ '\n'
+ '* … and so on for the corresponding KEY/pattern pair.\n'
+ '\n'
+ '\n'
+ 'Class Patterns\n'
+ '~~~~~~~~~~~~~~\n'
+ '\n'
+ 'A class pattern represents a class and its positional and '
+ 'keyword\n'
+ 'arguments (if any). Syntax:\n'
+ '\n'
+ ' **class_pattern**: "name_or_attr" "(" '
+ '["pattern_arguments" ","?] ")"\n'
+ ' **pattern_arguments**: "positional_patterns" ["," '
+ '"keyword_patterns"]\n'
+ ' | "keyword_patterns"\n'
+ ' **positional_patterns**: ","."pattern"+\n'
+ ' **keyword_patterns**: ","."keyword_pattern"+\n'
+ ' **keyword_pattern**: NAME "=" "pattern"\n'
+ '\n'
+ 'The same keyword should not be repeated in class patterns.\n'
+ '\n'
+ 'The following is the logical flow for matching a class pattern '
+ 'against\n'
+ 'a subject value:\n'
+ '\n'
+ '1. If "name_or_attr" is not an instance of the builtin "type" , '
+ 'raise\n'
+ ' "TypeError".\n'
+ '\n'
+ '2. If the subject value is not an instance of "name_or_attr" '
+ '(tested\n'
+ ' via "isinstance()"), the class pattern fails.\n'
+ '\n'
+ '3. If no pattern arguments are present, the pattern succeeds.\n'
+ ' Otherwise, the subsequent steps depend on whether keyword or\n'
+ ' positional argument patterns are present.\n'
+ '\n'
+ ' For a number of built-in types (specified below), a single\n'
+ ' positional subpattern is accepted which will match the '
+ 'entire\n'
+ ' subject; for these types keyword patterns also work as for '
+ 'other\n'
+ ' types.\n'
+ '\n'
+ ' If only keyword patterns are present, they are processed as\n'
+ ' follows, one by one:\n'
+ '\n'
+ ' I. The keyword is looked up as an attribute on the subject.\n'
+ '\n'
+ ' * If this raises an exception other than "AttributeError", '
+ 'the\n'
+ ' exception bubbles up.\n'
+ '\n'
+ ' * If this raises "AttributeError", the class pattern has '
+ 'failed.\n'
+ '\n'
+ ' * Else, the subpattern associated with the keyword pattern '
+ 'is\n'
+ ' matched against the subject’s attribute value. If this '
+ 'fails,\n'
+ ' the class pattern fails; if this succeeds, the match '
+ 'proceeds\n'
+ ' to the next keyword.\n'
+ '\n'
+ ' II. If all keyword patterns succeed, the class pattern '
+ 'succeeds.\n'
+ '\n'
+ ' If any positional patterns are present, they are converted '
+ 'to\n'
+ ' keyword patterns using the "__match_args__" attribute on the '
+ 'class\n'
+ ' "name_or_attr" before matching:\n'
+ '\n'
+ ' I. The equivalent of "getattr(cls, "__match_args__", ())" is\n'
+ ' called.\n'
+ '\n'
+ ' * If this raises an exception, the exception bubbles up.\n'
+ '\n'
+ ' * If the returned value is not a tuple, the conversion '
+ 'fails and\n'
+ ' "TypeError" is raised.\n'
+ '\n'
+ ' * If there are more positional patterns than\n'
+ ' "len(cls.__match_args__)", "TypeError" is raised.\n'
+ '\n'
+ ' * Otherwise, positional pattern "i" is converted to a '
+ 'keyword\n'
+ ' pattern using "__match_args__[i]" as the keyword.\n'
+ ' "__match_args__[i]" must be a string; if not "TypeError" '
+ 'is\n'
+ ' raised.\n'
+ '\n'
+ ' * If there are duplicate keywords, "TypeError" is raised.\n'
+ '\n'
+ ' See also:\n'
+ '\n'
+ ' Customizing positional arguments in class pattern '
+ 'matching\n'
+ '\n'
+ ' II. Once all positional patterns have been converted to '
+ 'keyword\n'
+ ' patterns,\n'
+ ' the match proceeds as if there were only keyword '
+ 'patterns.\n'
+ '\n'
+ ' For the following built-in types the handling of positional\n'
+ ' subpatterns is different:\n'
+ '\n'
+ ' * "bool"\n'
+ '\n'
+ ' * "bytearray"\n'
+ '\n'
+ ' * "bytes"\n'
+ '\n'
+ ' * "dict"\n'
+ '\n'
+ ' * "float"\n'
+ '\n'
+ ' * "frozenset"\n'
+ '\n'
+ ' * "int"\n'
+ '\n'
+ ' * "list"\n'
+ '\n'
+ ' * "set"\n'
+ '\n'
+ ' * "str"\n'
+ '\n'
+ ' * "tuple"\n'
+ '\n'
+ ' These classes accept a single positional argument, and the '
+ 'pattern\n'
+ ' there is matched against the whole object rather than an '
+ 'attribute.\n'
+ ' For example "int(0|1)" matches the value "0", but not the '
+ 'value\n'
+ ' "0.0".\n'
+ '\n'
+ 'In simple terms "CLS(P1, attr=P2)" matches only if the '
+ 'following\n'
+ 'happens:\n'
+ '\n'
+ '* "isinstance(<subject>, CLS)"\n'
+ '\n'
+ '* convert "P1" to a keyword pattern using "CLS.__match_args__"\n'
+ '\n'
+ '* For each keyword argument "attr=P2":\n'
+ '\n'
+ ' * "hasattr(<subject>, "attr")"\n'
+ '\n'
+ ' * "P2" matches "<subject>.attr"\n'
+ '\n'
+ '* … and so on for the corresponding keyword argument/pattern '
+ 'pair.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' * **PEP 634** – Structural Pattern Matching: Specification\n'
+ '\n'
+ ' * **PEP 636** – Structural Pattern Matching: Tutorial\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" ["type_params"] "(" ["parameter_list"] ")"\n'
+ ' ["->" "expression"] ":" "suite"\n'
+ ' **decorators**: "decorator"+\n'
+ ' **decorator**: "@" "assignment_expression" '
+ 'NEWLINE\n'
+ ' **parameter_list**: "defparameter" ("," '
+ '"defparameter")* "," "/" ["," ["parameter_list_no_posonly"]]\n'
+ ' | "parameter_list_no_posonly"\n'
+ ' **parameter_list_no_posonly**: "defparameter" ("," '
+ '"defparameter")* ["," ["parameter_list_starargs"]]\n'
+ ' | "parameter_list_starargs"\n'
+ ' **parameter_list_starargs**: "*" ["star_parameter"] ("," '
+ '"defparameter")* ["," ["parameter_star_kwargs"]]\n'
+ ' "*" ("," "defparameter")+ ["," '
+ '["parameter_star_kwargs"]]\n'
+ ' | "parameter_star_kwargs"\n'
+ ' **parameter_star_kwargs**: "**" "parameter" [","]\n'
+ ' **parameter**: "identifier" [":" '
+ '"expression"]\n'
+ ' **star_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. [4]\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'
+ 'Changed in version 3.9: Functions may be decorated with any '
+ 'valid\n'
+ '"assignment_expression". Previously, the grammar was much more\n'
+ 'restrictive; see **PEP 614** for details.\n'
+ '\n'
+ 'A list of type parameters may be given in square brackets '
+ 'between the\n'
+ 'function’s name and the opening parenthesis for its parameter '
+ 'list.\n'
+ 'This indicates to static type checkers that the function is '
+ 'generic.\n'
+ 'At runtime, the type parameters can be retrieved from the '
+ 'function’s\n'
+ '"__type_params__" attribute. See Generic functions for more.\n'
+ '\n'
+ 'Changed in version 3.12: Type parameter lists are new in Python '
+ '3.12.\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 value is a mutable '
+ 'object, such\n'
+ 'as a list or a dictionary: if the function modifies the object '
+ '(e.g.\n'
+ 'by appending an item to a list), the default parameter value is '
+ 'in\n'
+ 'effect modified. This is generally not what was intended. A '
+ 'way\n'
+ 'around this is to use "None" as the default, and explicitly test '
+ 'for\n'
+ 'it in the body of the 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 positional 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 by\n'
+ 'keyword arguments. Parameters before “"/"” are positional-only\n'
+ 'parameters and may only be passed by positional arguments.\n'
+ '\n'
+ 'Changed in version 3.8: The "/" function parameter syntax may be '
+ 'used\n'
+ 'to indicate positional-only parameters. See **PEP 570** for '
+ 'details.\n'
+ '\n'
+ 'Parameters may have an *annotation* of the form “": '
+ 'expression"”\n'
+ 'following the parameter name. Any parameter may have an '
+ 'annotation,\n'
+ 'even those of the form "*identifier" or "**identifier". (As a '
+ 'special\n'
+ 'case, parameters of the form "*identifier" may have an '
+ 'annotation “":\n'
+ '*expression"”.) Functions may have “return” annotation of the '
+ 'form\n'
+ '“"-> expression"” after the parameter list. These annotations '
+ 'can be\n'
+ 'any valid Python expression. The presence of annotations does '
+ 'not\n'
+ 'change the semantics of a function. See Annotations for more\n'
+ 'information on annotations.\n'
+ '\n'
+ 'Changed in version 3.11: Parameters of the form “"*identifier"” '
+ 'may\n'
+ 'have an annotation “": *expression"”. See **PEP 646**.\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'
+ ' **PEP 484** - Type Hints\n'
+ ' Definition of a standard meaning for annotations: type '
+ 'hints.\n'
+ '\n'
+ ' **PEP 526** - Syntax for Variable Annotations\n'
+ ' Ability to type hint variable declarations, including '
+ 'class\n'
+ ' variables and instance variables.\n'
+ '\n'
+ ' **PEP 563** - Postponed Evaluation of Annotations\n'
+ ' Support for forward references within annotations by '
+ 'preserving\n'
+ ' annotations in a string form at runtime instead of eager\n'
+ ' evaluation.\n'
+ '\n'
+ ' **PEP 318** - Decorators for Functions and Methods\n'
+ ' Function and method decorators were introduced. Class '
+ 'decorators\n'
+ ' were introduced in **PEP 3129**.\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" '
+ '["type_params"] ["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. '
+ '[5] 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'
+ 'Changed in version 3.9: Classes may be decorated with any valid\n'
+ '"assignment_expression". Previously, the grammar was much more\n'
+ 'restrictive; see **PEP 614** for details.\n'
+ '\n'
+ 'A list of type parameters may be given in square brackets '
+ 'immediately\n'
+ 'after the class’s name. This indicates to static type checkers '
+ 'that\n'
+ 'the class is generic. At runtime, the type parameters can be '
+ 'retrieved\n'
+ 'from the class’s "__type_params__" attribute. See Generic '
+ 'classes for\n'
+ 'more.\n'
+ '\n'
+ 'Changed in version 3.12: Type parameter lists are new in Python '
+ '3.12.\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'
+ 'Added 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*). "await" expressions, "async for" and '
+ '"async\n'
+ 'with" can only be used in the body of a coroutine function.\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 a "yield from" expression inside '
+ 'the body\n'
+ 'of a coroutine function.\n'
+ '\n'
+ 'An example of a coroutine function:\n'
+ '\n'
+ ' async def func(param1, param2):\n'
+ ' do_stuff()\n'
+ ' await some_coroutine()\n'
+ '\n'
+ 'Changed in version 3.7: "await" and "async" are now keywords;\n'
+ 'previously they were only treated as such inside the body of a\n'
+ 'coroutine function.\n'
+ '\n'
+ '\n'
+ 'The "async for" statement\n'
+ '-------------------------\n'
+ '\n'
+ ' **async_for_stmt**: "async" "for_stmt"\n'
+ '\n'
+ 'An *asynchronous iterable* provides an "__aiter__" method that\n'
+ 'directly returns an *asynchronous iterator*, which can call\n'
+ 'asynchronous code in its "__anext__" method.\n'
+ '\n'
+ 'The "async for" statement allows convenient iteration over\n'
+ 'asynchronous iterables.\n'
+ '\n'
+ 'The following code:\n'
+ '\n'
+ ' async for TARGET in ITER:\n'
+ ' SUITE\n'
+ ' else:\n'
+ ' SUITE2\n'
+ '\n'
+ 'Is semantically equivalent to:\n'
+ '\n'
+ ' iter = (ITER)\n'
+ ' iter = type(iter).__aiter__(iter)\n'
+ ' running = True\n'
+ '\n'
+ ' while running:\n'
+ ' try:\n'
+ ' TARGET = await type(iter).__anext__(iter)\n'
+ ' except StopAsyncIteration:\n'
+ ' running = False\n'
+ ' else:\n'
+ ' SUITE\n'
+ ' else:\n'
+ ' SUITE2\n'
+ '\n'
+ 'See also "__aiter__()" and "__anext__()" for details.\n'
+ '\n'
+ 'It is a "SyntaxError" to use an "async for" statement outside '
+ 'the body\n'
+ 'of a coroutine function.\n'
+ '\n'
+ '\n'
+ 'The "async with" statement\n'
+ '--------------------------\n'
+ '\n'
+ ' **async_with_stmt**: "async" "with_stmt"\n'
+ '\n'
+ 'An *asynchronous context manager* is a *context manager* that is '
+ 'able\n'
+ 'to suspend execution in its *enter* and *exit* methods.\n'
+ '\n'
+ 'The following code:\n'
+ '\n'
+ ' async with EXPRESSION as TARGET:\n'
+ ' SUITE\n'
+ '\n'
+ 'is semantically equivalent to:\n'
+ '\n'
+ ' manager = (EXPRESSION)\n'
+ ' aenter = type(manager).__aenter__\n'
+ ' aexit = type(manager).__aexit__\n'
+ ' value = await aenter(manager)\n'
+ ' hit_except = False\n'
+ '\n'
+ ' try:\n'
+ ' TARGET = value\n'
+ ' SUITE\n'
+ ' except:\n'
+ ' hit_except = True\n'
+ ' if not await aexit(manager, *sys.exc_info()):\n'
+ ' raise\n'
+ ' finally:\n'
+ ' if not hit_except:\n'
+ ' await aexit(manager, None, None, None)\n'
+ '\n'
+ 'See also "__aenter__()" and "__aexit__()" for details.\n'
+ '\n'
+ 'It is a "SyntaxError" to use an "async with" statement outside '
+ 'the\n'
+ 'body of a coroutine function.\n'
+ '\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'
+ '\n'
+ 'Type parameter lists\n'
+ '====================\n'
+ '\n'
+ 'Added in version 3.12.\n'
+ '\n'
+ 'Changed in version 3.13: Support for default values was added '
+ '(see\n'
+ '**PEP 696**).\n'
+ '\n'
+ ' **type_params**: "[" "type_param" ("," "type_param")* "]"\n'
+ ' **type_param**: "typevar" | "typevartuple" | "paramspec"\n'
+ ' **typevar**: "identifier" (":" "expression")? ("=" '
+ '"expression")?\n'
+ ' **typevartuple**: "*" "identifier" ("=" "expression")?\n'
+ ' **paramspec**: "**" "identifier" ("=" "expression")?\n'
+ '\n'
+ 'Functions (including coroutines), classes and type aliases may '
+ 'contain\n'
+ 'a type parameter list:\n'
+ '\n'
+ ' def max[T](args: list[T]) -> T:\n'
+ ' ...\n'
+ '\n'
+ ' async def amax[T](args: list[T]) -> T:\n'
+ ' ...\n'
+ '\n'
+ ' class Bag[T]:\n'
+ ' def __iter__(self) -> Iterator[T]:\n'
+ ' ...\n'
+ '\n'
+ ' def add(self, arg: T) -> None:\n'
+ ' ...\n'
+ '\n'
+ ' type ListOrSet[T] = list[T] | set[T]\n'
+ '\n'
+ 'Semantically, this indicates that the function, class, or type '
+ 'alias\n'
+ 'is generic over a type variable. This information is primarily '
+ 'used by\n'
+ 'static type checkers, and at runtime, generic objects behave '
+ 'much like\n'
+ 'their non-generic counterparts.\n'
+ '\n'
+ 'Type parameters are declared in square brackets ("[]") '
+ 'immediately\n'
+ 'after the name of the function, class, or type alias. The type\n'
+ 'parameters are accessible within the scope of the generic '
+ 'object, but\n'
+ 'not elsewhere. Thus, after a declaration "def func[T](): pass", '
+ 'the\n'
+ 'name "T" is not available in the module scope. Below, the '
+ 'semantics of\n'
+ 'generic objects are described with more precision. The scope of '
+ 'type\n'
+ 'parameters is modeled with a special function (technically, an\n'
+ 'annotation scope) that wraps the creation of the generic '
+ 'object.\n'
+ '\n'
+ 'Generic functions, classes, and type aliases have a '
+ '"__type_params__"\n'
+ 'attribute listing their type parameters.\n'
+ '\n'
+ 'Type parameters come in three kinds:\n'
+ '\n'
+ '* "typing.TypeVar", introduced by a plain name (e.g., "T").\n'
+ ' Semantically, this represents a single type to a type '
+ 'checker.\n'
+ '\n'
+ '* "typing.TypeVarTuple", introduced by a name prefixed with a '
+ 'single\n'
+ ' asterisk (e.g., "*Ts"). Semantically, this stands for a tuple '
+ 'of any\n'
+ ' number of types.\n'
+ '\n'
+ '* "typing.ParamSpec", introduced by a name prefixed with two '
+ 'asterisks\n'
+ ' (e.g., "**P"). Semantically, this stands for the parameters of '
+ 'a\n'
+ ' callable.\n'
+ '\n'
+ '"typing.TypeVar" declarations can define *bounds* and '
+ '*constraints*\n'
+ 'with a colon (":") followed by an expression. A single '
+ 'expression\n'
+ 'after the colon indicates a bound (e.g. "T: int"). Semantically, '
+ 'this\n'
+ 'means that the "typing.TypeVar" can only represent types that '
+ 'are a\n'
+ 'subtype of this bound. A parenthesized tuple of expressions '
+ 'after the\n'
+ 'colon indicates a set of constraints (e.g. "T: (str, bytes)"). '
+ 'Each\n'
+ 'member of the tuple should be a type (again, this is not '
+ 'enforced at\n'
+ 'runtime). Constrained type variables can only take on one of the '
+ 'types\n'
+ 'in the list of constraints.\n'
+ '\n'
+ 'For "typing.TypeVar"s declared using the type parameter list '
+ 'syntax,\n'
+ 'the bound and constraints are not evaluated when the generic '
+ 'object is\n'
+ 'created, but only when the value is explicitly accessed through '
+ 'the\n'
+ 'attributes "__bound__" and "__constraints__". To accomplish '
+ 'this, the\n'
+ 'bounds or constraints are evaluated in a separate annotation '
+ 'scope.\n'
+ '\n'
+ '"typing.TypeVarTuple"s and "typing.ParamSpec"s cannot have '
+ 'bounds or\n'
+ 'constraints.\n'
+ '\n'
+ 'All three flavors of type parameters can also have a *default '
+ 'value*,\n'
+ 'which is used when the type parameter is not explicitly '
+ 'provided. This\n'
+ 'is added by appending a single equals sign ("=") followed by an\n'
+ 'expression. Like the bounds and constraints of type variables, '
+ 'the\n'
+ 'default value is not evaluated when the object is created, but '
+ 'only\n'
+ 'when the type parameter’s "__default__" attribute is accessed. '
+ 'To this\n'
+ 'end, the default value is evaluated in a separate annotation '
+ 'scope. If\n'
+ 'no default value is specified for a type parameter, the '
+ '"__default__"\n'
+ 'attribute is set to the special sentinel object '
+ '"typing.NoDefault".\n'
+ '\n'
+ 'The following example indicates the full set of allowed type '
+ 'parameter\n'
+ 'declarations:\n'
+ '\n'
+ ' def overly_generic[\n'
+ ' SimpleTypeVar,\n'
+ ' TypeVarWithDefault = int,\n'
+ ' TypeVarWithBound: int,\n'
+ ' TypeVarWithConstraints: (str, bytes),\n'
+ ' *SimpleTypeVarTuple = (int, float),\n'
+ ' **SimpleParamSpec = (str, bytearray),\n'
+ ' ](\n'
+ ' a: SimpleTypeVar,\n'
+ ' b: TypeVarWithDefault,\n'
+ ' c: TypeVarWithBound,\n'
+ ' d: Callable[SimpleParamSpec, TypeVarWithConstraints],\n'
+ ' *e: SimpleTypeVarTuple,\n'
+ ' ): ...\n'
+ '\n'
+ '\n'
+ 'Generic functions\n'
+ '-----------------\n'
+ '\n'
+ 'Generic functions are declared as follows:\n'
+ '\n'
+ ' def func[T](arg: T): ...\n'
+ '\n'
+ 'This syntax is equivalent to:\n'
+ '\n'
+ ' annotation-def TYPE_PARAMS_OF_func():\n'
+ ' T = typing.TypeVar("T")\n'
+ ' def func(arg: T): ...\n'
+ ' func.__type_params__ = (T,)\n'
+ ' return func\n'
+ ' func = TYPE_PARAMS_OF_func()\n'
+ '\n'
+ 'Here "annotation-def" indicates an annotation scope, which is '
+ 'not\n'
+ 'actually bound to any name at runtime. (One other liberty is '
+ 'taken in\n'
+ 'the translation: the syntax does not go through attribute access '
+ 'on\n'
+ 'the "typing" module, but creates an instance of '
+ '"typing.TypeVar"\n'
+ 'directly.)\n'
+ '\n'
+ 'The annotations of generic functions are evaluated within the\n'
+ 'annotation scope used for declaring the type parameters, but '
+ 'the\n'
+ 'function’s defaults and decorators are not.\n'
+ '\n'
+ 'The following example illustrates the scoping rules for these '
+ 'cases,\n'
+ 'as well as for additional flavors of type parameters:\n'
+ '\n'
+ ' @decorator\n'
+ ' def func[T: int, *Ts, **P](*args: *Ts, arg: Callable[P, T] = '
+ 'some_default):\n'
+ ' ...\n'
+ '\n'
+ 'Except for the lazy evaluation of the "TypeVar" bound, this is\n'
+ 'equivalent to:\n'
+ '\n'
+ ' DEFAULT_OF_arg = some_default\n'
+ '\n'
+ ' annotation-def TYPE_PARAMS_OF_func():\n'
+ '\n'
+ ' annotation-def BOUND_OF_T():\n'
+ ' return int\n'
+ ' # In reality, BOUND_OF_T() is evaluated only on demand.\n'
+ ' T = typing.TypeVar("T", bound=BOUND_OF_T())\n'
+ '\n'
+ ' Ts = typing.TypeVarTuple("Ts")\n'
+ ' P = typing.ParamSpec("P")\n'
+ '\n'
+ ' def func(*args: *Ts, arg: Callable[P, T] = '
+ 'DEFAULT_OF_arg):\n'
+ ' ...\n'
+ '\n'
+ ' func.__type_params__ = (T, Ts, P)\n'
+ ' return func\n'
+ ' func = decorator(TYPE_PARAMS_OF_func())\n'
+ '\n'
+ 'The capitalized names like "DEFAULT_OF_arg" are not actually '
+ 'bound at\n'
+ 'runtime.\n'
+ '\n'
+ '\n'
+ 'Generic classes\n'
+ '---------------\n'
+ '\n'
+ 'Generic classes are declared as follows:\n'
+ '\n'
+ ' class Bag[T]: ...\n'
+ '\n'
+ 'This syntax is equivalent to:\n'
+ '\n'
+ ' annotation-def TYPE_PARAMS_OF_Bag():\n'
+ ' T = typing.TypeVar("T")\n'
+ ' class Bag(typing.Generic[T]):\n'
+ ' __type_params__ = (T,)\n'
+ ' ...\n'
+ ' return Bag\n'
+ ' Bag = TYPE_PARAMS_OF_Bag()\n'
+ '\n'
+ 'Here again "annotation-def" (not a real keyword) indicates an\n'
+ 'annotation scope, and the name "TYPE_PARAMS_OF_Bag" is not '
+ 'actually\n'
+ 'bound at runtime.\n'
+ '\n'
+ 'Generic classes implicitly inherit from "typing.Generic". The '
+ 'base\n'
+ 'classes and keyword arguments of generic classes are evaluated '
+ 'within\n'
+ 'the type scope for the type parameters, and decorators are '
+ 'evaluated\n'
+ 'outside that scope. This is illustrated by this example:\n'
+ '\n'
+ ' @decorator\n'
+ ' class Bag(Base[T], arg=T): ...\n'
+ '\n'
+ 'This is equivalent to:\n'
+ '\n'
+ ' annotation-def TYPE_PARAMS_OF_Bag():\n'
+ ' T = typing.TypeVar("T")\n'
+ ' class Bag(Base[T], typing.Generic[T], arg=T):\n'
+ ' __type_params__ = (T,)\n'
+ ' ...\n'
+ ' return Bag\n'
+ ' Bag = decorator(TYPE_PARAMS_OF_Bag())\n'
+ '\n'
+ '\n'
+ 'Generic type aliases\n'
+ '--------------------\n'
+ '\n'
+ 'The "type" statement can also be used to create a generic type '
+ 'alias:\n'
+ '\n'
+ ' type ListOrSet[T] = list[T] | set[T]\n'
+ '\n'
+ 'Except for the lazy evaluation of the value, this is equivalent '
+ 'to:\n'
+ '\n'
+ ' annotation-def TYPE_PARAMS_OF_ListOrSet():\n'
+ ' T = typing.TypeVar("T")\n'
+ '\n'
+ ' annotation-def VALUE_OF_ListOrSet():\n'
+ ' return list[T] | set[T]\n'
+ ' # In reality, the value is lazily evaluated\n'
+ ' return typing.TypeAliasType("ListOrSet", '
+ 'VALUE_OF_ListOrSet(), type_params=(T,))\n'
+ ' ListOrSet = TYPE_PARAMS_OF_ListOrSet()\n'
+ '\n'
+ 'Here, "annotation-def" (not a real keyword) indicates an '
+ 'annotation\n'
+ 'scope. The capitalized names like "TYPE_PARAMS_OF_ListOrSet" are '
+ 'not\n'
+ 'actually bound at runtime.\n'
+ '\n'
+ '\n'
+ 'Annotations\n'
+ '===========\n'
+ '\n'
+ 'Changed in version 3.14: Annotations are now lazily evaluated '
+ 'by\n'
+ 'default.\n'
+ '\n'
+ 'Variables and function parameters may carry *annotations*, '
+ 'created by\n'
+ 'adding a colon after the name, followed by an expression:\n'
+ '\n'
+ ' x: annotation = 1\n'
+ ' def f(param: annotation): ...\n'
+ '\n'
+ 'Functions may also carry a return annotation following an '
+ 'arrow:\n'
+ '\n'
+ ' def f() -> annotation: ...\n'
+ '\n'
+ 'Annotations are conventionally used for *type hints*, but this '
+ 'is not\n'
+ 'enforced by the language, and in general annotations may '
+ 'contain\n'
+ 'arbitrary expressions. The presence of annotations does not '
+ 'change the\n'
+ 'runtime semantics of the code, except if some mechanism is used '
+ 'that\n'
+ 'introspects and uses the annotations (such as "dataclasses" or\n'
+ '"functools.singledispatch()").\n'
+ '\n'
+ 'By default, annotations are lazily evaluated in a annotation '
+ 'scope.\n'
+ 'This means that they are not evaluated when the code containing '
+ 'the\n'
+ 'annotation is evaluated. Instead, the interpreter saves '
+ 'information\n'
+ 'that can be used to evaluate the annotation later if requested. '
+ 'The\n'
+ '"annotationlib" module provides tools for evaluating '
+ 'annotations.\n'
+ '\n'
+ 'If the future statement "from __future__ import annotations" is\n'
+ 'present, all annotations are instead stored as strings:\n'
+ '\n'
+ ' >>> from __future__ import annotations\n'
+ ' >>> def f(param: annotation): ...\n'
+ ' >>> f.__annotations__\n'
+ " {'param': 'annotation'}\n"
+ '\n'
+ '-[ Footnotes ]-\n'
+ '\n'
+ '[1] The exception is propagated to the invocation stack unless '
+ 'there\n'
+ ' is a "finally" clause which happens to raise another '
+ 'exception.\n'
+ ' That new exception causes the old one to be lost.\n'
+ '\n'
+ '[2] In pattern matching, a sequence is defined as one of the\n'
+ ' following:\n'
+ '\n'
+ ' * a class that inherits from "collections.abc.Sequence"\n'
+ '\n'
+ ' * a Python class that has been registered as\n'
+ ' "collections.abc.Sequence"\n'
+ '\n'
+ ' * a builtin class that has its (CPython) '
+ '"Py_TPFLAGS_SEQUENCE" bit\n'
+ ' set\n'
+ '\n'
+ ' * a class that inherits from any of the above\n'
+ '\n'
+ ' The following standard library classes are sequences:\n'
+ '\n'
+ ' * "array.array"\n'
+ '\n'
+ ' * "collections.deque"\n'
+ '\n'
+ ' * "list"\n'
+ '\n'
+ ' * "memoryview"\n'
+ '\n'
+ ' * "range"\n'
+ '\n'
+ ' * "tuple"\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' Subject values of type "str", "bytes", and "bytearray" do '
+ 'not\n'
+ ' match sequence patterns.\n'
+ '\n'
+ '[3] In pattern matching, a mapping is defined as one of the '
+ 'following:\n'
+ '\n'
+ ' * a class that inherits from "collections.abc.Mapping"\n'
+ '\n'
+ ' * a Python class that has been registered as\n'
+ ' "collections.abc.Mapping"\n'
+ '\n'
+ ' * a builtin class that has its (CPython) '
+ '"Py_TPFLAGS_MAPPING" bit\n'
+ ' set\n'
+ '\n'
+ ' * a class that inherits from any of the above\n'
+ '\n'
+ ' The standard library classes "dict" and '
+ '"types.MappingProxyType"\n'
+ ' are mappings.\n'
+ '\n'
+ '[4] A string literal appearing as the first statement in the '
+ 'function\n'
+ ' body is transformed into the function’s "__doc__" attribute '
+ 'and\n'
+ ' therefore the function’s *docstring*.\n'
+ '\n'
+ '[5] 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'
+ 'The "object" class itself does not provide the context '
+ 'manager\n'
+ 'methods.\n'
+ '\n'
+ 'object.__enter__(self)\n'
+ '\n'
+ ' Enter the runtime context related to this object. The '
+ '"with"\n'
+ ' statement will bind this method’s return value to the '
+ 'target(s)\n'
+ ' specified in the "as" clause of the statement, if '
+ 'any.\n'
+ '\n'
+ 'object.__exit__(self, exc_type, exc_value, traceback)\n'
+ '\n'
+ ' Exit the runtime context related to this object. The '
+ 'parameters\n'
+ ' describe the exception that caused the context to be '
+ 'exited. If the\n'
+ ' context was exited without an exception, all three '
+ 'arguments will\n'
+ ' be "None".\n'
+ '\n'
+ ' If an exception is supplied, and the method wishes to '
+ 'suppress the\n'
+ ' exception (i.e., prevent it from being propagated), '
+ 'it should\n'
+ ' return a true value. Otherwise, the exception will be '
+ 'processed\n'
+ ' normally upon exit from this method.\n'
+ '\n'
+ ' Note that "__exit__()" methods should not reraise the '
+ 'passed-in\n'
+ ' exception; this is the caller’s responsibility.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 343** - The “with” statement\n'
+ ' The specification, background, and examples for the '
+ 'Python "with"\n'
+ ' statement.\n',
+ 'continue': 'The "continue" statement\n'
+ '************************\n'
+ '\n'
+ ' **continue_stmt**: "continue"\n'
+ '\n'
+ '"continue" may only occur syntactically nested in a "for" or '
+ '"while"\n'
+ 'loop, but not nested in a function or class definition within '
+ 'that\n'
+ 'loop. It continues with the next cycle of the nearest enclosing '
+ 'loop.\n'
+ '\n'
+ 'When "continue" passes control out of a "try" statement with a\n'
+ '"finally" clause, that "finally" clause is executed before '
+ 'really\n'
+ 'starting the next loop cycle.\n',
+ 'conversions': 'Arithmetic conversions\n'
+ '**********************\n'
+ '\n'
+ 'When a description of an arithmetic operator below uses the '
+ 'phrase\n'
+ '“the numeric arguments are converted to a common real type”, '
+ 'this\n'
+ 'means that the operator implementation for built-in types '
+ 'works as\n'
+ 'follows:\n'
+ '\n'
+ '* If both arguments are complex numbers, no conversion is '
+ 'performed;\n'
+ '\n'
+ '* if either argument is a complex or a floating-point number, '
+ 'the\n'
+ ' other is converted to a floating-point number;\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__()" is invoked during object construction and '
+ 'it returns\n'
+ ' an instance of *cls*, then the new instance’s '
+ '"__init__()" method\n'
+ ' will be invoked like "__init__(self[, ...])", where '
+ '*self* is the\n'
+ ' new instance and the remaining arguments are the same as '
+ 'were\n'
+ ' passed to the object constructor.\n'
+ '\n'
+ ' If "__new__()" does not return an instance of *cls*, '
+ 'then the new\n'
+ ' instance’s "__init__()" method will not be invoked.\n'
+ '\n'
+ ' "__new__()" is intended mainly to allow subclasses of '
+ 'immutable\n'
+ ' types (like int, str, or tuple) to customize instance '
+ 'creation. It\n'
+ ' is also commonly overridden in custom metaclasses in '
+ 'order to\n'
+ ' customize class creation.\n'
+ '\n'
+ 'object.__init__(self[, ...])\n'
+ '\n'
+ ' Called after the instance has been created (by '
+ '"__new__()"), but\n'
+ ' before it is returned to the caller. The arguments are '
+ 'those\n'
+ ' passed to the class constructor expression. If a base '
+ 'class has an\n'
+ ' "__init__()" method, the derived class’s "__init__()" '
+ 'method, if\n'
+ ' any, must explicitly call it to ensure proper '
+ 'initialization of the\n'
+ ' base class part of the instance; for example:\n'
+ ' "super().__init__([args...])".\n'
+ '\n'
+ ' Because "__new__()" and "__init__()" work together in '
+ 'constructing\n'
+ ' objects ("__new__()" to create it, and "__init__()" to '
+ 'customize\n'
+ ' it), no non-"None" value may be returned by '
+ '"__init__()"; doing so\n'
+ ' will cause a "TypeError" to be raised at runtime.\n'
+ '\n'
+ 'object.__del__(self)\n'
+ '\n'
+ ' Called when the instance is about to be destroyed. This '
+ 'is also\n'
+ ' 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'
+ ' "weakref.finalize" provides a straightforward way to '
+ 'register a\n'
+ ' cleanup function to be called when an object is garbage '
+ 'collected.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' "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:\n'
+ '\n'
+ ' Due to the precarious circumstances under which '
+ '"__del__()"\n'
+ ' methods are invoked, exceptions that occur during '
+ 'their execution\n'
+ ' are ignored, and a warning is printed to "sys.stderr" '
+ 'instead.\n'
+ ' In particular:\n'
+ '\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 a\n'
+ ' consequence, the global variables it needs to access '
+ '(including\n'
+ ' other modules) may already have been deleted or set '
+ 'to "None".\n'
+ ' Python guarantees that globals whose name begins '
+ 'with a single\n'
+ ' underscore are deleted from their module before '
+ 'other globals\n'
+ ' are deleted; if no other references to such globals '
+ 'exist, this\n'
+ ' may help in assuring that imported modules are still '
+ 'available\n'
+ ' at the time when the "__del__()" method is called.\n'
+ '\n'
+ 'object.__repr__(self)\n'
+ '\n'
+ ' Called by the "repr()" built-in function to compute the '
+ '“official”\n'
+ ' string representation of an object. If at all possible, '
+ 'this\n'
+ ' should look like a valid Python expression that could be '
+ 'used to\n'
+ ' recreate an object with the same value (given an '
+ 'appropriate\n'
+ ' environment). If this is not possible, a string of the '
+ 'form\n'
+ ' "<...some useful description...>" should be returned. '
+ 'The return\n'
+ ' value must be a string object. If a class defines '
+ '"__repr__()" but\n'
+ ' not "__str__()", then "__repr__()" is also used when an '
+ '“informal”\n'
+ ' string representation of instances of that class is '
+ 'required.\n'
+ '\n'
+ ' This is typically used for debugging, so it is important '
+ 'that the\n'
+ ' representation is information-rich and unambiguous. A '
+ 'default\n'
+ ' implementation is provided by the "object" class '
+ 'itself.\n'
+ '\n'
+ 'object.__str__(self)\n'
+ '\n'
+ ' Called by "str(object)", the default "__format__()" '
+ 'implementation,\n'
+ ' and the built-in function "print()", to compute the '
+ '“informal” or\n'
+ ' nicely printable string representation of an object. '
+ 'The return\n'
+ ' value must be a str 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. The '
+ '"object" class\n'
+ ' itself does not provide this method.\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'
+ ' The default implementation by the "object" class should '
+ 'be given an\n'
+ ' empty *format_spec* string. It delegates to '
+ '"__str__()".\n'
+ '\n'
+ ' Changed in version 3.4: The __format__ method of '
+ '"object" itself\n'
+ ' raises a "TypeError" if passed any non-empty string.\n'
+ '\n'
+ ' Changed in version 3.7: "object.__format__(x, \'\')" is '
+ 'now\n'
+ ' equivalent to "str(x)" rather than "format(str(x), '
+ '\'\')".\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, "object" implements "__eq__()" by using '
+ '"is", returning\n'
+ ' "NotImplemented" in the case of a false comparison: '
+ '"True if x is y\n'
+ ' else NotImplemented". For "__ne__()", by default it '
+ 'delegates to\n'
+ ' "__eq__()" and inverts the result unless it is '
+ '"NotImplemented".\n'
+ ' There are no other implied relationships among the '
+ 'comparison\n'
+ ' operators or default implementations; for example, the '
+ 'truth of\n'
+ ' "(x<y or x==y)" does not imply "x<=y". To automatically '
+ 'generate\n'
+ ' ordering operations from a single root operation, see\n'
+ ' "functools.total_ordering()".\n'
+ '\n'
+ ' By default, the "object" class provides implementations '
+ 'consistent\n'
+ ' with Value comparisons: equality compares according to '
+ 'object\n'
+ ' identity, and order comparisons raise "TypeError". Each '
+ 'default\n'
+ ' method may generate these results directly, but may also '
+ 'return\n'
+ ' "NotImplemented".\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 the 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'
+ ' When no appropriate method returns any value other than\n'
+ ' "NotImplemented", the "==" and "!=" operators will fall '
+ 'back to\n'
+ ' "is" and "is not", respectively.\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'
+ ' The "__hash__()" method should return an integer. The '
+ 'only required\n'
+ ' property is that objects which compare equal have the '
+ 'same hash\n'
+ ' value; it is advised to mix together the hash values of '
+ 'the\n'
+ ' components of the object that also play a part in '
+ 'comparison of\n'
+ ' objects by packing them into a tuple and hashing the '
+ 'tuple.\n'
+ ' Example:\n'
+ '\n'
+ ' def __hash__(self):\n'
+ ' return hash((self.name, self.nick, self.color))\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' "hash()" truncates the value returned from an object’s '
+ 'custom\n'
+ ' "__hash__()" method to the size of a "Py_ssize_t". '
+ 'This is\n'
+ ' typically 8 bytes on 64-bit builds and 4 bytes on '
+ '32-bit builds.\n'
+ ' If an object’s "__hash__()" must interoperate on '
+ 'builds of\n'
+ ' different bit sizes, be sure to check the width on all '
+ 'supported\n'
+ ' builds. An easy way to do this is with "python -c '
+ '"import sys;\n'
+ ' print(sys.hash_info.width)"".\n'
+ '\n'
+ ' If a class does not define an "__eq__()" method it '
+ 'should not\n'
+ ' define a "__hash__()" operation either; if it defines '
+ '"__eq__()"\n'
+ ' but not "__hash__()", its instances will not be usable '
+ 'as items in\n'
+ ' hashable collections. If a class defines mutable '
+ 'objects and\n'
+ ' implements an "__eq__()" method, it should not '
+ 'implement\n'
+ ' "__hash__()", since the implementation of *hashable* '
+ 'collections\n'
+ ' requires that a key’s hash value is immutable (if the '
+ 'object’s hash\n'
+ ' value changes, it will be in the wrong hash bucket).\n'
+ '\n'
+ ' User-defined classes have "__eq__()" and "__hash__()" '
+ 'methods by\n'
+ ' default (inherited from the "object" class); with them, '
+ 'all objects\n'
+ ' compare unequal (except with themselves) and '
+ '"x.__hash__()" returns\n'
+ ' an appropriate value such that "x == y" implies both '
+ 'that "x is y"\n'
+ ' and "hash(x) == hash(y)".\n'
+ '\n'
+ ' A class that overrides "__eq__()" and does not define '
+ '"__hash__()"\n'
+ ' will have its "__hash__()" implicitly set to "None". '
+ 'When the\n'
+ ' "__hash__()" method of a class is "None", instances of '
+ 'the class\n'
+ ' will raise an appropriate "TypeError" when a program '
+ 'attempts to\n'
+ ' retrieve their hash value, and will also be correctly '
+ 'identified as\n'
+ ' unhashable when checking "isinstance(obj,\n'
+ ' collections.abc.Hashable)".\n'
+ '\n'
+ ' If a class that overrides "__eq__()" needs to retain '
+ 'the\n'
+ ' implementation of "__hash__()" from a parent class, the '
+ 'interpreter\n'
+ ' must be told this explicitly by setting "__hash__ =\n'
+ ' <ParentClass>.__hash__".\n'
+ '\n'
+ ' If a class that does not override "__eq__()" wishes to '
+ 'suppress\n'
+ ' hash support, it should include "__hash__ = None" in the '
+ 'class\n'
+ ' definition. A class which defines its own "__hash__()" '
+ 'that\n'
+ ' explicitly raises a "TypeError" would be incorrectly '
+ 'identified as\n'
+ ' hashable by an "isinstance(obj, '
+ 'collections.abc.Hashable)" call.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' By default, the "__hash__()" values of str and bytes '
+ 'objects are\n'
+ ' “salted” with an unpredictable random value. Although '
+ 'they\n'
+ ' remain constant within an individual Python process, '
+ 'they are not\n'
+ ' predictable between repeated invocations of '
+ 'Python.This is\n'
+ ' intended to provide protection against a '
+ 'denial-of-service caused\n'
+ ' by carefully chosen inputs that exploit the worst '
+ 'case\n'
+ ' performance of a dict insertion, *O*(*n*^2) '
+ 'complexity. See\n'
+ ' http://ocert.org/advisories/ocert-2011-003.html for\n'
+ ' details.Changing hash values affects the iteration '
+ 'order of sets.\n'
+ ' Python has never made guarantees about this ordering '
+ '(and it\n'
+ ' typically varies between 32-bit and 64-bit builds).See '
+ 'also\n'
+ ' "PYTHONHASHSEED".\n'
+ '\n'
+ ' Changed in version 3.3: Hash randomization is enabled by '
+ 'default.\n'
+ '\n'
+ 'object.__bool__(self)\n'
+ '\n'
+ ' Called to implement truth value testing and the built-in '
+ 'operation\n'
+ ' "bool()"; should return "False" or "True". When this '
+ 'method is not\n'
+ ' defined, "__len__()" is called, if it is defined, and '
+ 'the object is\n'
+ ' considered true if its result is nonzero. If a class '
+ 'defines\n'
+ ' neither "__len__()" nor "__bool__()" (which is true of '
+ 'the "object"\n'
+ ' class itself), all its instances are 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'
+ 'See also:\n'
+ '\n'
+ ' Module "faulthandler"\n'
+ ' Used to dump Python tracebacks explicitly, on a fault, '
+ 'after a\n'
+ ' timeout, or on a user signal.\n'
+ '\n'
+ ' Module "traceback"\n'
+ ' Standard interface to extract, format and print stack '
+ 'traces of\n'
+ ' Python programs.\n'
+ '\n'
+ 'The typical usage to break into the debugger is to insert:\n'
+ '\n'
+ ' import pdb; pdb.set_trace()\n'
+ '\n'
+ 'Or:\n'
+ '\n'
+ ' breakpoint()\n'
+ '\n'
+ 'at the location you want to break into the debugger, and then '
+ 'run the\n'
+ 'program. You can then step through the code following this '
+ 'statement,\n'
+ 'and continue running without the debugger using the "continue"\n'
+ 'command.\n'
+ '\n'
+ 'Changed in version 3.7: The built-in "breakpoint()", when called '
+ 'with\n'
+ 'defaults, can be used instead of "import pdb; pdb.set_trace()".\n'
+ '\n'
+ ' def double(x):\n'
+ ' breakpoint()\n'
+ ' return x * 2\n'
+ ' val = 3\n'
+ ' print(f"{val} * 2 is {double(val)}")\n'
+ '\n'
+ 'The debugger’s prompt is "(Pdb)", which is the indicator that '
+ 'you are\n'
+ 'in debug mode:\n'
+ '\n'
+ ' > ...(2)double()\n'
+ ' -> breakpoint()\n'
+ ' (Pdb) p x\n'
+ ' 3\n'
+ ' (Pdb) continue\n'
+ ' 3 * 2 is 6\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'
+ 'You can also invoke "pdb" from the command line to debug other\n'
+ 'scripts. For example:\n'
+ '\n'
+ ' python -m pdb [-c command] (-m module | pyfile) [args ...]\n'
+ '\n'
+ 'When invoked as a module, 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'
+ '-c, --command <command>\n'
+ '\n'
+ ' To execute commands as if given in a ".pdbrc" file; see '
+ 'Debugger\n'
+ ' Commands.\n'
+ '\n'
+ ' Changed in version 3.2: Added the "-c" option.\n'
+ '\n'
+ '-m <module>\n'
+ '\n'
+ ' To execute modules similar to the way "python -m" does. As '
+ 'with a\n'
+ ' script, the debugger will pause execution just before the '
+ 'first\n'
+ ' line of the module.\n'
+ '\n'
+ ' Changed in version 3.7: Added the "-m" option.\n'
+ '\n'
+ 'Typical usage to execute a statement under control of the '
+ 'debugger is:\n'
+ '\n'
+ ' >>> import pdb\n'
+ ' >>> def f(x):\n'
+ ' ... print(1 / x)\n'
+ ' >>> pdb.run("f(2)")\n'
+ ' > <string>(1)<module>()\n'
+ ' (Pdb) continue\n'
+ ' 0.5\n'
+ ' >>>\n'
+ '\n'
+ 'The typical usage to inspect a crashed program is:\n'
+ '\n'
+ ' >>> import pdb\n'
+ ' >>> def f(x):\n'
+ ' ... print(1 / x)\n'
+ ' ...\n'
+ ' >>> f(0)\n'
+ ' Traceback (most recent call last):\n'
+ ' File "<stdin>", line 1, in <module>\n'
+ ' File "<stdin>", line 2, in f\n'
+ ' ZeroDivisionError: division by zero\n'
+ ' >>> pdb.pm()\n'
+ ' > <stdin>(2)f()\n'
+ ' (Pdb) p x\n'
+ ' 0\n'
+ ' (Pdb)\n'
+ '\n'
+ 'Changed in version 3.13: The implementation of **PEP 667** means '
+ 'that\n'
+ 'name assignments made via "pdb" will immediately affect the '
+ 'active\n'
+ 'scope, even when running inside an *optimized scope*.\n'
+ '\n'
+ 'The module defines the following functions; each enters the '
+ 'debugger\n'
+ 'in a slightly different way:\n'
+ '\n'
+ 'pdb.run(statement, globals=None, locals=None)\n'
+ '\n'
+ ' Execute the *statement* (given as a string or a code object) '
+ 'under\n'
+ ' debugger control. The debugger prompt appears before any '
+ 'code is\n'
+ ' executed; you can set breakpoints and type "continue", or you '
+ 'can\n'
+ ' step through the statement using "step" or "next" (all these\n'
+ ' commands are explained below). The optional *globals* and '
+ '*locals*\n'
+ ' arguments specify the environment in which the code is '
+ 'executed; by\n'
+ ' default the dictionary of the module "__main__" is used. '
+ '(See the\n'
+ ' explanation of the built-in "exec()" or "eval()" functions.)\n'
+ '\n'
+ 'pdb.runeval(expression, globals=None, locals=None)\n'
+ '\n'
+ ' Evaluate the *expression* (given as a string or a code '
+ 'object)\n'
+ ' under debugger control. When "runeval()" returns, it returns '
+ 'the\n'
+ ' value of the *expression*. Otherwise this function is '
+ 'similar to\n'
+ ' "run()".\n'
+ '\n'
+ 'pdb.runcall(function, *args, **kwds)\n'
+ '\n'
+ ' Call the *function* (a function or method object, not a '
+ 'string)\n'
+ ' with the given arguments. When "runcall()" returns, it '
+ 'returns\n'
+ ' whatever the function call returned. The debugger prompt '
+ 'appears\n'
+ ' as soon as the function is entered.\n'
+ '\n'
+ 'pdb.set_trace(*, header=None, commands=None)\n'
+ '\n'
+ ' Enter the debugger at the calling stack frame. This is '
+ 'useful to\n'
+ ' hard-code a breakpoint at a given point in a program, even if '
+ 'the\n'
+ ' code is not otherwise being debugged (e.g. when an assertion\n'
+ ' fails). If given, *header* is printed to the console just '
+ 'before\n'
+ ' debugging begins. The *commands* argument, if given, is a '
+ 'list of\n'
+ ' commands to execute when the debugger starts.\n'
+ '\n'
+ ' Changed in version 3.7: The keyword-only argument *header*.\n'
+ '\n'
+ ' Changed in version 3.13: "set_trace()" will enter the '
+ 'debugger\n'
+ ' immediately, rather than on the next line of code to be '
+ 'executed.\n'
+ '\n'
+ ' Added in version 3.14: The *commands* argument.\n'
+ '\n'
+ 'pdb.post_mortem(t=None)\n'
+ '\n'
+ ' Enter post-mortem debugging of the given exception or '
+ 'traceback\n'
+ ' object. If no value is given, it uses the exception that is\n'
+ ' currently being handled, or raises "ValueError" if there '
+ 'isn’t one.\n'
+ '\n'
+ ' Changed in version 3.13: Support for exception objects was '
+ 'added.\n'
+ '\n'
+ 'pdb.pm()\n'
+ '\n'
+ ' Enter post-mortem debugging of the exception found in\n'
+ ' "sys.last_exc".\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, mode=None)\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'
+ ' The *mode* argument specifies how the debugger was invoked. '
+ 'It\n'
+ ' impacts the workings of some debugger commands. Valid values '
+ 'are\n'
+ ' "\'inline\'" (used by the breakpoint() builtin), "\'cli\'" '
+ '(used by the\n'
+ ' command line invocation) or "None" (for backwards compatible\n'
+ ' behaviour, as before the *mode* argument was added).\n'
+ '\n'
+ ' Example call to enable tracing with *skip*:\n'
+ '\n'
+ " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n"
+ '\n'
+ ' Raises an auditing event "pdb.Pdb" with no arguments.\n'
+ '\n'
+ ' Changed in version 3.1: Added the *skip* parameter.\n'
+ '\n'
+ ' Changed in version 3.2: Added the *nosigint* parameter. '
+ 'Previously,\n'
+ ' a SIGINT handler was never set by Pdb.\n'
+ '\n'
+ ' Changed in version 3.6: The *readrc* argument.\n'
+ '\n'
+ ' Added in version 3.14: Added the *mode* argument.\n'
+ '\n'
+ ' Changed in version 3.14: Inline breakpoints like '
+ '"breakpoint()" or\n'
+ ' "pdb.set_trace()" will always stop the program at calling '
+ 'frame,\n'
+ ' ignoring the *skip* pattern (if any).\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'
+ 'Changed in version 3.13: Expressions/Statements whose prefix is '
+ 'a pdb\n'
+ 'command are now correctly identified and executed.\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. A\n'
+ 'workaround for strings with double semicolons is to use '
+ 'implicit\n'
+ 'string concatenation "\';\'\';\'" or "";"";"".\n'
+ '\n'
+ 'To set a temporary global variable, use a *convenience '
+ 'variable*. A\n'
+ '*convenience variable* is a variable whose name starts with '
+ '"$". For\n'
+ 'example, "$foo = 1" sets a global variable "$foo" which you can '
+ 'use in\n'
+ 'the debugger session. The *convenience variables* are cleared '
+ 'when\n'
+ 'the program resumes execution so it’s less likely to interfere '
+ 'with\n'
+ 'your program compared to using normal variables like "foo = 1".\n'
+ '\n'
+ 'There are three preset *convenience variables*:\n'
+ '\n'
+ '* "$_frame": the current frame you are debugging\n'
+ '\n'
+ '* "$_retval": the return value if the frame is returning\n'
+ '\n'
+ '* "$_exception": the exception if the frame is raising an '
+ 'exception\n'
+ '\n'
+ 'Added in version 3.12: Added the *convenience variable* '
+ 'feature.\n'
+ '\n'
+ 'If a file ".pdbrc" exists in the user’s home directory or in '
+ 'the\n'
+ 'current directory, it is read with "\'utf-8\'" encoding and '
+ 'executed as\n'
+ 'if it had been typed at the debugger prompt, with the exception '
+ 'that\n'
+ 'empty lines and lines starting with "#" are ignored. This is\n'
+ 'particularly useful for aliases. If both files exist, the one '
+ 'in the\n'
+ 'home directory is read first and aliases defined there can be\n'
+ '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'
+ 'Changed in version 3.11: ".pdbrc" is now read with "\'utf-8\'" '
+ 'encoding.\n'
+ 'Previously, it was read with the system locale encoding.\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) [count]\n'
+ '\n'
+ ' Print a stack trace, with the most recent frame at the '
+ 'bottom. if\n'
+ ' *count* is 0, print the current frame entry. If *count* is\n'
+ ' negative, print the least recent - *count* frames. If *count* '
+ 'is\n'
+ ' positive, print the most recent *count* frames. An arrow '
+ '(">")\n'
+ ' indicates the current frame, which determines the context of '
+ 'most\n'
+ ' commands.\n'
+ '\n'
+ ' Changed in version 3.14: *count* argument is added.\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 at line *lineno* in '
+ 'the\n'
+ ' current file. The line number may be prefixed with a '
+ '*filename* and\n'
+ ' a colon, to specify a breakpoint in another file (possibly '
+ 'one that\n'
+ ' hasn’t been loaded yet). The file is searched on '
+ '"sys.path".\n'
+ ' Acceptable forms of *filename* are "/abspath/to/file.py",\n'
+ ' "relpath/file.py", "module" and "package.module".\n'
+ '\n'
+ ' With a *function* argument, set a break at the first '
+ 'executable\n'
+ ' statement within that function. *function* can be any '
+ 'expression\n'
+ ' that evaluates to a function in the current namespace.\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'
+ ' Each breakpoint is assigned a number to which all the other\n'
+ ' breakpoint commands refer.\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 ...]\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*\n'
+ ' is omitted, the ignore count is set to 0. A breakpoint '
+ 'becomes\n'
+ ' active when the ignore count is zero. When non-zero, the '
+ '*count*\n'
+ ' is decremented each time the breakpoint is reached and the\n'
+ ' breakpoint is not disabled and any associated condition '
+ 'evaluates\n'
+ ' to true.\n'
+ '\n'
+ 'condition bpnumber [condition]\n'
+ '\n'
+ ' Set a new *condition* for the breakpoint, an expression which '
+ 'must\n'
+ ' evaluate to true before the breakpoint is honored. If '
+ '*condition*\n'
+ ' is absent, any existing condition is removed; i.e., the '
+ 'breakpoint\n'
+ ' is made unconditional.\n'
+ '\n'
+ 'commands [bpnumber]\n'
+ '\n'
+ ' Specify a list of commands for breakpoint number *bpnumber*. '
+ 'The\n'
+ ' commands themselves appear on the following lines. Type a '
+ 'line\n'
+ ' containing just "end" to terminate the commands. An example:\n'
+ '\n'
+ ' (Pdb) commands 1\n'
+ ' (com) p some_variable\n'
+ ' (com) end\n'
+ ' (Pdb)\n'
+ '\n'
+ ' To remove all commands from a breakpoint, type "commands" '
+ 'and\n'
+ ' follow it immediately with "end"; that is, give no commands.\n'
+ '\n'
+ ' With no *bpnumber* argument, "commands" refers to the last\n'
+ ' breakpoint set.\n'
+ '\n'
+ ' You can use breakpoint commands to start your program up '
+ 'again.\n'
+ ' Simply use the "continue" command, or "step", or any other '
+ 'command\n'
+ ' that resumes execution.\n'
+ '\n'
+ ' Specifying any command resuming execution (currently '
+ '"continue",\n'
+ ' "step", "next", "return", "until", "jump", "quit" and their\n'
+ ' abbreviations) terminates the command list (as if that '
+ 'command was\n'
+ ' immediately followed by end). This is because any time you '
+ 'resume\n'
+ ' execution (even with a simple next or step), you may '
+ 'encounter\n'
+ ' another breakpoint—which could have its own command list, '
+ 'leading\n'
+ ' to ambiguities about which list to execute.\n'
+ '\n'
+ ' If the list of commands contains the "silent" command, or a '
+ 'command\n'
+ ' that resumes execution, then the breakpoint message '
+ 'containing\n'
+ ' information about the frame is not displayed.\n'
+ '\n'
+ ' Changed in version 3.14: Frame information will not be '
+ 'displayed if\n'
+ ' a command that resumes execution is present in the command '
+ 'list.\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 *lineno*, continue execution until a line with a number\n'
+ ' greater or equal to *lineno* is reached. In both cases, also '
+ 'stop\n'
+ ' when 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'
+ ' Changed in version 3.2: Added 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'
+ ' Added in version 3.2.\n'
+ '\n'
+ 'a(rgs)\n'
+ '\n'
+ ' Print the arguments of the current function and their '
+ 'current\n'
+ ' values.\n'
+ '\n'
+ 'p expression\n'
+ '\n'
+ ' Evaluate *expression* in the current context and print its '
+ 'value.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' "print()" can also be used, but is not a debugger command — '
+ 'this\n'
+ ' executes the Python "print()" function.\n'
+ '\n'
+ 'pp expression\n'
+ '\n'
+ ' Like the "p" command, except the value of *expression* is '
+ 'pretty-\n'
+ ' printed using the "pprint" module.\n'
+ '\n'
+ 'whatis expression\n'
+ '\n'
+ ' Print the type of *expression*.\n'
+ '\n'
+ 'source expression\n'
+ '\n'
+ ' Try to get source code of *expression* and display it.\n'
+ '\n'
+ ' Added in version 3.2.\n'
+ '\n'
+ 'display [expression]\n'
+ '\n'
+ ' Display the value of *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'
+ ' Note:\n'
+ '\n'
+ ' Display evaluates *expression* and compares to the result '
+ 'of the\n'
+ ' previous evaluation of *expression*, so when the result is\n'
+ ' mutable, display may not be able to pick up the changes.\n'
+ '\n'
+ ' Example:\n'
+ '\n'
+ ' lst = []\n'
+ ' breakpoint()\n'
+ ' pass\n'
+ ' lst.append(1)\n'
+ ' print(lst)\n'
+ '\n'
+ ' Display won’t realize "lst" has been changed because the '
+ 'result of\n'
+ ' evaluation is modified in place by "lst.append(1)" before '
+ 'being\n'
+ ' compared:\n'
+ '\n'
+ ' > example.py(3)<module>()\n'
+ ' -> pass\n'
+ ' (Pdb) display lst\n'
+ ' display lst: []\n'
+ ' (Pdb) n\n'
+ ' > example.py(4)<module>()\n'
+ ' -> lst.append(1)\n'
+ ' (Pdb) n\n'
+ ' > example.py(5)<module>()\n'
+ ' -> print(lst)\n'
+ ' (Pdb)\n'
+ '\n'
+ ' You can do some tricks with copy mechanism to make it work:\n'
+ '\n'
+ ' > example.py(3)<module>()\n'
+ ' -> pass\n'
+ ' (Pdb) display lst[:]\n'
+ ' display lst[:]: []\n'
+ ' (Pdb) n\n'
+ ' > example.py(4)<module>()\n'
+ ' -> lst.append(1)\n'
+ ' (Pdb) n\n'
+ ' > example.py(5)<module>()\n'
+ ' -> print(lst)\n'
+ ' display lst[:]: [1] [old: []]\n'
+ ' (Pdb)\n'
+ '\n'
+ ' Added in version 3.2.\n'
+ '\n'
+ 'undisplay [expression]\n'
+ '\n'
+ ' Do not display *expression* anymore in the current frame. '
+ 'Without\n'
+ ' *expression*, clear all display expressions for the current '
+ 'frame.\n'
+ '\n'
+ ' Added in version 3.2.\n'
+ '\n'
+ 'interact\n'
+ '\n'
+ ' Start an interactive interpreter (using the "code" module) in '
+ 'a new\n'
+ ' global namespace initialised from the local and global '
+ 'namespaces\n'
+ ' for the current scope. Use "exit()" or "quit()" to exit the\n'
+ ' interpreter and return to the debugger.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' As "interact" creates a new dedicated namespace for code\n'
+ ' execution, assignments to variables will not affect the '
+ 'original\n'
+ ' namespaces. However, modifications to any referenced '
+ 'mutable\n'
+ ' objects will be reflected in the original namespaces as '
+ 'usual.\n'
+ '\n'
+ ' Added in version 3.2.\n'
+ '\n'
+ ' Changed in version 3.13: "exit()" and "quit()" can be used to '
+ 'exit\n'
+ ' the "interact" command.\n'
+ '\n'
+ ' Changed in version 3.13: "interact" directs its output to '
+ 'the\n'
+ ' debugger’s output channel rather than "sys.stderr".\n'
+ '\n'
+ 'alias [name [command]]\n'
+ '\n'
+ ' Create an alias called *name* that executes *command*. The\n'
+ ' *command* must *not* be enclosed in quotes. Replaceable '
+ 'parameters\n'
+ ' can be indicated by "%1", "%2", … and "%9", while "%*" is '
+ 'replaced\n'
+ ' by all the parameters. If *command* is omitted, the current '
+ 'alias\n'
+ ' for *name* is shown. If no arguments are given, all aliases '
+ 'are\n'
+ ' 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(f"%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 *name*.\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, e.g.:\n'
+ '\n'
+ ' (Pdb) ! n=42\n'
+ ' (Pdb)\n'
+ '\n'
+ ' To set a global variable, you can prefix the assignment '
+ 'command\n'
+ ' with a "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 *args* is supplied, '
+ 'it is\n'
+ ' split with "shlex" and the result is used as the new '
+ '"sys.argv".\n'
+ ' History, breakpoints, actions and debugger options are '
+ 'preserved.\n'
+ ' "restart" is an alias for "run".\n'
+ '\n'
+ ' Changed in version 3.14: "run" and "restart" commands are '
+ 'disabled\n'
+ ' when the debugger is invoked in "\'inline\'" mode.\n'
+ '\n'
+ 'q(uit)\n'
+ '\n'
+ ' Quit from the debugger. The program being executed is '
+ 'aborted. An\n'
+ ' end-of-file input is equivalent to "quit".\n'
+ '\n'
+ ' A confirmation prompt will be shown if the debugger is '
+ 'invoked in\n'
+ ' "\'inline\'" mode. Either "y", "Y", "<Enter>" or "EOF" will '
+ 'confirm\n'
+ ' the quit.\n'
+ '\n'
+ ' Changed in version 3.14: A confirmation prompt will be shown '
+ 'if the\n'
+ ' debugger is invoked in "\'inline\'" mode. After the '
+ 'confirmation, the\n'
+ ' debugger will call "sys.exit()" immediately, instead of '
+ 'raising\n'
+ ' "bdb.BdbQuit" in the next trace event.\n'
+ '\n'
+ 'debug code\n'
+ '\n'
+ ' Enter a recursive debugger that steps through *code* (which '
+ 'is an\n'
+ ' arbitrary expression or statement to be executed in the '
+ 'current\n'
+ ' environment).\n'
+ '\n'
+ 'retval\n'
+ '\n'
+ ' Print the return value for the last return of the current '
+ 'function.\n'
+ '\n'
+ 'exceptions [excnumber]\n'
+ '\n'
+ ' List or jump between chained exceptions.\n'
+ '\n'
+ ' When using "pdb.pm()" or "Pdb.post_mortem(...)" with a '
+ 'chained\n'
+ ' exception instead of a traceback, it allows the user to move\n'
+ ' between the chained exceptions using "exceptions" command to '
+ 'list\n'
+ ' exceptions, and "exception <number>" to switch to that '
+ 'exception.\n'
+ '\n'
+ ' Example:\n'
+ '\n'
+ ' def out():\n'
+ ' try:\n'
+ ' middle()\n'
+ ' except Exception as e:\n'
+ ' raise ValueError("reraise middle() error") from e\n'
+ '\n'
+ ' def middle():\n'
+ ' try:\n'
+ ' return inner(0)\n'
+ ' except Exception as e:\n'
+ ' raise ValueError("Middle fail")\n'
+ '\n'
+ ' def inner(x):\n'
+ ' 1 / x\n'
+ '\n'
+ ' out()\n'
+ '\n'
+ ' calling "pdb.pm()" will allow to move between exceptions:\n'
+ '\n'
+ ' > example.py(5)out()\n'
+ ' -> raise ValueError("reraise middle() error") from e\n'
+ '\n'
+ ' (Pdb) exceptions\n'
+ " 0 ZeroDivisionError('division by zero')\n"
+ " 1 ValueError('Middle fail')\n"
+ " > 2 ValueError('reraise middle() error')\n"
+ '\n'
+ ' (Pdb) exceptions 0\n'
+ ' > example.py(16)inner()\n'
+ ' -> 1 / x\n'
+ '\n'
+ ' (Pdb) up\n'
+ ' > example.py(10)middle()\n'
+ ' -> return inner(0)\n'
+ '\n'
+ ' Added in version 3.13.\n'
+ '\n'
+ '-[ Footnotes ]-\n'
+ '\n'
+ '[1] Whether a frame is considered to originate in a certain '
+ 'module is\n'
+ ' determined by the "__name__" in the frame globals.\n',
+ 'del': 'The "del" statement\n'
+ '*******************\n'
+ '\n'
+ ' **del_stmt**: "del" "target_list"\n'
+ '\n'
+ 'Deletion is recursively defined very similar to the way assignment '
+ 'is\n'
+ 'defined. Rather than spelling it out in full details, here are some\n'
+ 'hints.\n'
+ '\n'
+ 'Deletion of a target list recursively deletes each target, from left\n'
+ 'to right.\n'
+ '\n'
+ 'Deletion of a name removes the binding of that name from the local '
+ 'or\n'
+ 'global namespace, depending on whether the name occurs in a "global"\n'
+ 'statement in the same code block. If the name is unbound, a\n'
+ '"NameError" exception will be raised.\n'
+ '\n'
+ 'Deletion of attribute references, subscriptions and slicings is '
+ 'passed\n'
+ 'to the primary object involved; deletion of a slicing is in general\n'
+ 'equivalent to assignment of an empty slice of the right type (but '
+ 'even\n'
+ 'this is determined by the sliced object).\n'
+ '\n'
+ 'Changed in version 3.2: Previously it was illegal to delete a name\n'
+ 'from the local namespace if it occurs as a free variable in a nested\n'
+ 'block.\n',
+ 'dict': 'Dictionary displays\n'
+ '*******************\n'
+ '\n'
+ 'A dictionary display is a possibly empty series of dict items\n'
+ '(key/value pairs) enclosed in curly braces:\n'
+ '\n'
+ ' **dict_display**: "{" ["dict_item_list" | '
+ '"dict_comprehension"] "}"\n'
+ ' **dict_item_list**: "dict_item" ("," "dict_item")* [","]\n'
+ ' **dict_item**: "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 dict items 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 value. This means that you can specify the same key\n'
+ 'multiple times in the dict item 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 '
+ 'dict\n'
+ 'items and earlier dictionary unpackings.\n'
+ '\n'
+ 'Added 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 value (textually\n'
+ 'rightmost in the display) stored for a given key value prevails.\n'
+ '\n'
+ 'Changed in version 3.8: Prior to Python 3.8, in dict '
+ 'comprehensions,\n'
+ 'the evaluation order of key and value was not well-defined. In\n'
+ 'CPython, the value was evaluated before the key. Starting with '
+ '3.8,\n'
+ 'the key is evaluated before the value, as proposed by **PEP 572**.\n',
+ 'dynamic-features': 'Interaction with dynamic features\n'
+ '*********************************\n'
+ '\n'
+ 'Name resolution of free variables occurs at runtime, not '
+ 'at compile\n'
+ 'time. This means that the following code will print 42:\n'
+ '\n'
+ ' i = 10\n'
+ ' def f():\n'
+ ' print(i)\n'
+ ' i = 42\n'
+ ' f()\n'
+ '\n'
+ 'The "eval()" and "exec()" functions do not have access '
+ 'to the full\n'
+ 'environment for resolving names. Names may be resolved '
+ 'in the local\n'
+ 'and global namespaces of the caller. Free variables are '
+ 'not resolved\n'
+ 'in the nearest enclosing namespace, but in the global '
+ 'namespace. [1]\n'
+ 'The "exec()" and "eval()" functions have optional '
+ 'arguments to\n'
+ 'override the global and local namespace. If only one '
+ 'namespace is\n'
+ 'specified, it is used for both.\n',
+ 'else': 'The "if" statement\n'
+ '******************\n'
+ '\n'
+ 'The "if" statement is used for conditional execution:\n'
+ '\n'
+ ' **if_stmt**: "if" "assignment_expression" ":" "suite"\n'
+ ' ("elif" "assignment_expression" ":" "suite")*\n'
+ ' ["else" ":" "suite"]\n'
+ '\n'
+ 'It selects exactly one of the suites by evaluating the expressions '
+ 'one\n'
+ 'by one until one is found to be true (see section Boolean '
+ 'operations\n'
+ 'for the definition of true and false); then that suite is executed\n'
+ '(and no other part of the "if" statement is executed or evaluated).\n'
+ 'If all expressions are false, the suite of the "else" clause, if\n'
+ 'present, is executed.\n',
+ 'exceptions': 'Exceptions\n'
+ '**********\n'
+ '\n'
+ 'Exceptions are a means of breaking out of the normal flow of '
+ 'control\n'
+ 'of a code block in order to handle errors or other '
+ 'exceptional\n'
+ 'conditions. An exception is *raised* at the point where the '
+ 'error is\n'
+ 'detected; it may be *handled* by the surrounding code block or '
+ 'by any\n'
+ 'code block that directly or indirectly invoked the code block '
+ 'where\n'
+ 'the error occurred.\n'
+ '\n'
+ 'The Python interpreter raises an exception when it detects a '
+ 'run-time\n'
+ 'error (such as division by zero). A Python program can also\n'
+ 'explicitly raise an exception with the "raise" statement. '
+ 'Exception\n'
+ 'handlers are specified with the "try" … "except" statement. '
+ 'The\n'
+ '"finally" clause of such a statement can be used to specify '
+ 'cleanup\n'
+ 'code which does not handle the exception, but is executed '
+ 'whether an\n'
+ 'exception occurred or not in the preceding code.\n'
+ '\n'
+ 'Python uses the “termination” model of error handling: an '
+ 'exception\n'
+ 'handler can find out what happened and continue execution at '
+ 'an outer\n'
+ 'level, but it cannot repair the cause of the error and retry '
+ 'the\n'
+ 'failing operation (except by re-entering the offending piece '
+ 'of code\n'
+ 'from the top).\n'
+ '\n'
+ 'When an exception is not handled at all, the interpreter '
+ 'terminates\n'
+ 'execution of the program, or returns to its interactive main '
+ 'loop. In\n'
+ 'either case, it prints a stack traceback, except when the '
+ 'exception is\n'
+ '"SystemExit".\n'
+ '\n'
+ 'Exceptions are identified by class instances. The "except" '
+ 'clause is\n'
+ 'selected depending on the class of the instance: it must '
+ 'reference the\n'
+ 'class of the instance or a *non-virtual base class* thereof. '
+ 'The\n'
+ 'instance can be received by the handler and can carry '
+ 'additional\n'
+ 'information about the exceptional condition.\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Exception messages are not part of the Python API. Their '
+ 'contents\n'
+ ' may change from one version of Python to the next without '
+ 'warning\n'
+ ' and should not be relied on by code which will run under '
+ 'multiple\n'
+ ' versions of the interpreter.\n'
+ '\n'
+ 'See also the description of the "try" statement in section The '
+ 'try\n'
+ 'statement and "raise" statement in section The raise '
+ 'statement.\n'
+ '\n'
+ '-[ Footnotes ]-\n'
+ '\n'
+ '[1] This limitation occurs because the code that is executed '
+ 'by these\n'
+ ' operations is not available at the time the module is '
+ 'compiled.\n',
+ 'execmodel': 'Execution model\n'
+ '***************\n'
+ '\n'
+ '\n'
+ 'Structure of a program\n'
+ '======================\n'
+ '\n'
+ 'A Python program is constructed from code blocks. A *block* is '
+ 'a piece\n'
+ 'of Python program text that is executed as a unit. The '
+ 'following are\n'
+ 'blocks: a module, a function body, and a class definition. '
+ 'Each\n'
+ 'command typed interactively is a block. A script file (a file '
+ 'given\n'
+ 'as standard input to the interpreter or specified as a command '
+ 'line\n'
+ 'argument to the interpreter) is a code block. A script command '
+ '(a\n'
+ 'command specified on the interpreter command line with the '
+ '"-c"\n'
+ 'option) is a code block. A module run as a top level script (as '
+ 'module\n'
+ '"__main__") from the command line using a "-m" argument is also '
+ 'a code\n'
+ 'block. The string argument passed to the built-in functions '
+ '"eval()"\n'
+ '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:\n'
+ '\n'
+ '* formal parameters to functions,\n'
+ '\n'
+ '* class definitions,\n'
+ '\n'
+ '* function definitions,\n'
+ '\n'
+ '* assignment expressions,\n'
+ '\n'
+ '* targets that are identifiers if occurring in an assignment:\n'
+ '\n'
+ ' * "for" loop header,\n'
+ '\n'
+ ' * after "as" in a "with" statement, "except" clause, '
+ '"except*"\n'
+ ' clause, or in the as-pattern in structural pattern '
+ 'matching,\n'
+ '\n'
+ ' * in a capture pattern in structural pattern matching\n'
+ '\n'
+ '* "import" statements.\n'
+ '\n'
+ '* "type" statements.\n'
+ '\n'
+ '* type parameter lists.\n'
+ '\n'
+ 'The "import" statement of the form "from ... import *" binds '
+ 'all names\n'
+ 'defined in the imported module, except those beginning with an\n'
+ 'underscore. This form 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. See the FAQ entry on UnboundLocalError for '
+ 'examples.\n'
+ '\n'
+ 'If the "global" statement occurs within a block, all uses of '
+ 'the names\n'
+ 'specified in the statement refer to the bindings of those names '
+ '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 names are not found there, the builtins namespace is '
+ 'searched\n'
+ 'next. If the names are also not found in the builtins '
+ 'namespace, new\n'
+ 'variables are created in the global namespace. The global '
+ 'statement\n'
+ 'must precede all uses of the listed names.\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. Type parameters cannot '
+ 'be\n'
+ 'rebound with the "nonlocal" statement.\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, but it '
+ 'does\n'
+ 'not include annotation scopes, which have access to their '
+ 'enclosing\n'
+ 'class scopes. This means that the following will fail:\n'
+ '\n'
+ ' class A:\n'
+ ' a = 42\n'
+ ' b = list(a + i for i in range(10))\n'
+ '\n'
+ 'However, the following will succeed:\n'
+ '\n'
+ ' class A:\n'
+ ' type Alias = Nested\n'
+ ' class Nested: pass\n'
+ '\n'
+ " print(A.Alias.__value__) # <type 'A.Nested'>\n"
+ '\n'
+ '\n'
+ 'Annotation scopes\n'
+ '-----------------\n'
+ '\n'
+ '*Annotations*, type parameter lists and "type" statements '
+ 'introduce\n'
+ '*annotation scopes*, which behave mostly like function scopes, '
+ 'but\n'
+ 'with some exceptions discussed below.\n'
+ '\n'
+ 'Annotation scopes are used in the following contexts:\n'
+ '\n'
+ '* *Function annotations*.\n'
+ '\n'
+ '* *Variable annotations*.\n'
+ '\n'
+ '* Type parameter lists for generic type aliases.\n'
+ '\n'
+ '* Type parameter lists for generic functions. A generic '
+ 'function’s\n'
+ ' annotations are executed within the annotation scope, but '
+ 'its\n'
+ ' defaults and decorators are not.\n'
+ '\n'
+ '* Type parameter lists for generic classes. A generic class’s '
+ 'base\n'
+ ' classes and keyword arguments are executed within the '
+ 'annotation\n'
+ ' scope, but its decorators are not.\n'
+ '\n'
+ '* The bounds, constraints, and default values for type '
+ 'parameters\n'
+ ' (lazily evaluated).\n'
+ '\n'
+ '* The value of type aliases (lazily evaluated).\n'
+ '\n'
+ 'Annotation scopes differ from function scopes in the following '
+ 'ways:\n'
+ '\n'
+ '* Annotation scopes have access to their enclosing class '
+ 'namespace. If\n'
+ ' an annotation scope is immediately within a class scope, or '
+ 'within\n'
+ ' another annotation scope that is immediately within a class '
+ 'scope,\n'
+ ' the code in the annotation scope can use names defined in the '
+ 'class\n'
+ ' scope as if it were executed directly within the class body. '
+ 'This\n'
+ ' contrasts with regular functions defined within classes, '
+ 'which\n'
+ ' cannot access names defined in the class scope.\n'
+ '\n'
+ '* Expressions in annotation scopes cannot contain "yield", '
+ '"yield\n'
+ ' from", "await", or ":=" expressions. (These expressions are '
+ 'allowed\n'
+ ' in other scopes contained within the annotation scope.)\n'
+ '\n'
+ '* Names defined in annotation scopes cannot be rebound with '
+ '"nonlocal"\n'
+ ' statements in inner scopes. This includes only type '
+ 'parameters, as\n'
+ ' no other syntactic elements that can appear within annotation '
+ 'scopes\n'
+ ' can introduce new names.\n'
+ '\n'
+ '* While annotation scopes have an internal name, that name is '
+ 'not\n'
+ ' reflected in the *qualified name* of objects defined within '
+ 'the\n'
+ ' scope. Instead, the "__qualname__" of such objects is as if '
+ 'the\n'
+ ' object were defined in the enclosing scope.\n'
+ '\n'
+ 'Added in version 3.12: Annotation scopes were introduced in '
+ 'Python\n'
+ '3.12 as part of **PEP 695**.\n'
+ '\n'
+ 'Changed in version 3.13: Annotation scopes are also used for '
+ 'type\n'
+ 'parameter defaults, as introduced by **PEP 696**.\n'
+ '\n'
+ 'Changed in version 3.14: Annotation scopes are now also used '
+ 'for\n'
+ 'annotations, as specified in **PEP 649** and **PEP 749**.\n'
+ '\n'
+ '\n'
+ 'Lazy evaluation\n'
+ '---------------\n'
+ '\n'
+ 'Most annotation scopes are *lazily evaluated*. This includes\n'
+ 'annotations, the values of type aliases created through the '
+ '"type"\n'
+ 'statement, and the bounds, constraints, and default values of '
+ 'type\n'
+ 'variables created through the type parameter syntax. This means '
+ 'that\n'
+ 'they are not evaluated when the type alias or type variable is\n'
+ 'created, or when the object carrying annotations is created. '
+ 'Instead,\n'
+ 'they are only evaluated when necessary, for example when the\n'
+ '"__value__" attribute on a type alias is accessed.\n'
+ '\n'
+ 'Example:\n'
+ '\n'
+ ' >>> type Alias = 1/0\n'
+ ' >>> Alias.__value__\n'
+ ' Traceback (most recent call last):\n'
+ ' ...\n'
+ ' ZeroDivisionError: division by zero\n'
+ ' >>> def func[T: 1/0](): pass\n'
+ ' >>> T = func.__type_params__[0]\n'
+ ' >>> T.__bound__\n'
+ ' Traceback (most recent call last):\n'
+ ' ...\n'
+ ' ZeroDivisionError: division by zero\n'
+ '\n'
+ 'Here the exception is raised only when the "__value__" '
+ 'attribute of\n'
+ 'the type alias or the "__bound__" attribute of the type '
+ 'variable is\n'
+ 'accessed.\n'
+ '\n'
+ 'This behavior is primarily useful for references to types that '
+ 'have\n'
+ 'not yet been defined when the type alias or type variable is '
+ 'created.\n'
+ 'For example, lazy evaluation enables creation of mutually '
+ 'recursive\n'
+ 'type aliases:\n'
+ '\n'
+ ' from typing import Literal\n'
+ '\n'
+ ' type SimpleExpr = int | Parenthesized\n'
+ ' type Parenthesized = tuple[Literal["("], Expr, '
+ 'Literal[")"]]\n'
+ ' type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", '
+ '"-"], Expr]\n'
+ '\n'
+ 'Lazily evaluated values are evaluated in annotation scope, '
+ 'which means\n'
+ 'that names that appear inside the lazily evaluated value are '
+ 'looked up\n'
+ 'as if they were used in the immediately enclosing scope.\n'
+ '\n'
+ 'Added in version 3.12.\n'
+ '\n'
+ '\n'
+ 'Builtins and restricted execution\n'
+ '---------------------------------\n'
+ '\n'
+ '**CPython implementation detail:** Users should not touch\n'
+ '"__builtins__"; it is strictly an implementation detail. '
+ 'Users\n'
+ 'wanting to override values in the builtins namespace should '
+ '"import"\n'
+ 'the "builtins" module and modify its attributes appropriately.\n'
+ '\n'
+ 'The builtins namespace associated with the execution of a code '
+ 'block\n'
+ 'is actually found by looking up the name "__builtins__" in its '
+ 'global\n'
+ 'namespace; this should be a dictionary or a module (in the '
+ 'latter case\n'
+ 'the module’s dictionary is used). By default, when in the '
+ '"__main__"\n'
+ 'module, "__builtins__" is the built-in module "builtins"; when '
+ 'in any\n'
+ 'other module, "__builtins__" is an alias for the dictionary of '
+ 'the\n'
+ '"builtins" module itself.\n'
+ '\n'
+ '\n'
+ 'Interaction with dynamic features\n'
+ '---------------------------------\n'
+ '\n'
+ 'Name resolution of free variables occurs at runtime, not at '
+ 'compile\n'
+ 'time. This means that the following code will print 42:\n'
+ '\n'
+ ' i = 10\n'
+ ' def f():\n'
+ ' print(i)\n'
+ ' i = 42\n'
+ ' f()\n'
+ '\n'
+ 'The "eval()" and "exec()" functions do not have access to the '
+ 'full\n'
+ 'environment for resolving names. Names may be resolved in the '
+ 'local\n'
+ 'and global namespaces of the caller. Free variables are not '
+ 'resolved\n'
+ 'in the nearest enclosing namespace, but in the global '
+ 'namespace. [1]\n'
+ 'The "exec()" and "eval()" functions have optional arguments to\n'
+ 'override the global and local namespace. If only one namespace '
+ 'is\n'
+ 'specified, it is used for both.\n'
+ '\n'
+ '\n'
+ 'Exceptions\n'
+ '==========\n'
+ '\n'
+ 'Exceptions are a means of breaking out of the normal flow of '
+ 'control\n'
+ 'of a code block in order to handle errors or other exceptional\n'
+ 'conditions. An exception is *raised* at the point where the '
+ 'error is\n'
+ 'detected; it may be *handled* by the surrounding code block or '
+ 'by any\n'
+ 'code block that directly or indirectly invoked the code block '
+ 'where\n'
+ 'the error occurred.\n'
+ '\n'
+ 'The Python interpreter raises an exception when it detects a '
+ 'run-time\n'
+ 'error (such as division by zero). A Python program can also\n'
+ 'explicitly raise an exception with the "raise" statement. '
+ 'Exception\n'
+ 'handlers are specified with the "try" … "except" statement. '
+ 'The\n'
+ '"finally" clause of such a statement can be used to specify '
+ 'cleanup\n'
+ 'code which does not handle the exception, but is executed '
+ 'whether an\n'
+ 'exception occurred or not in the preceding code.\n'
+ '\n'
+ 'Python uses the “termination” model of error handling: an '
+ 'exception\n'
+ 'handler can find out what happened and continue execution at an '
+ 'outer\n'
+ 'level, but it cannot repair the cause of the error and retry '
+ 'the\n'
+ 'failing operation (except by re-entering the offending piece of '
+ 'code\n'
+ 'from the top).\n'
+ '\n'
+ 'When an exception is not handled at all, the interpreter '
+ 'terminates\n'
+ 'execution of the program, or returns to its interactive main '
+ 'loop. In\n'
+ 'either case, it prints a stack traceback, except when the '
+ 'exception is\n'
+ '"SystemExit".\n'
+ '\n'
+ 'Exceptions are identified by class instances. The "except" '
+ 'clause is\n'
+ 'selected depending on the class of the instance: it must '
+ 'reference the\n'
+ 'class of the instance or a *non-virtual base class* thereof. '
+ 'The\n'
+ 'instance can be received by the handler and can carry '
+ 'additional\n'
+ 'information about the exceptional condition.\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Exception messages are not part of the Python API. Their '
+ 'contents\n'
+ ' may change from one version of Python to the next without '
+ 'warning\n'
+ ' and should not be relied on by code which will run under '
+ 'multiple\n'
+ ' versions of the interpreter.\n'
+ '\n'
+ 'See also the description of the "try" statement in section The '
+ 'try\n'
+ 'statement and "raise" statement in section The raise '
+ 'statement.\n'
+ '\n'
+ '-[ Footnotes ]-\n'
+ '\n'
+ '[1] This limitation occurs because the code that is executed by '
+ 'these\n'
+ ' operations is not available at the time the module is '
+ 'compiled.\n',
+ 'exprlists': 'Expression lists\n'
+ '****************\n'
+ '\n'
+ ' **starred_expression**: ["*"] "or_expr"\n'
+ ' **flexible_expression**: "assignment_expression" | '
+ '"starred_expression"\n'
+ ' **flexible_expression_list**: "flexible_expression" ("," '
+ '"flexible_expression")* [","]\n'
+ ' **starred_expression_list**: "starred_expression" ("," '
+ '"starred_expression")* [","]\n'
+ ' **expression_list**: "expression" ("," '
+ '"expression")* [","]\n'
+ ' **yield_list**: "expression_list" | '
+ '"starred_expression" "," ["starred_expression_list"]\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'
+ 'Added in version 3.5: Iterable unpacking in expression lists,\n'
+ 'originally proposed by **PEP 448**.\n'
+ '\n'
+ 'Added in version 3.11: Any item in an expression list may be '
+ 'starred.\n'
+ 'See **PEP 646**.\n'
+ '\n'
+ 'A trailing comma is required only to create a one-item tuple, '
+ 'such as\n'
+ '"1,"; it is optional in all other cases. A single expression '
+ 'without a\n'
+ 'trailing comma doesn’t create a tuple, but rather yields the '
+ 'value of\n'
+ 'that expression. (To create an empty tuple, use an empty pair '
+ 'of\n'
+ '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" "starred_list" ":" "suite"\n'
+ ' ["else" ":" "suite"]\n'
+ '\n'
+ 'The "starred_list" expression is evaluated once; it should yield an\n'
+ '*iterable* object. An *iterator* is created for that iterable. The\n'
+ 'first item provided by the iterator is then assigned to the target\n'
+ 'list using the standard rules for assignments (see Assignment\n'
+ 'statements), and the suite is executed. This repeats for each item\n'
+ 'provided by the iterator. When the iterator is exhausted, the suite\n'
+ 'in the "else" clause, if present, is executed, and the loop\n'
+ 'terminates.\n'
+ '\n'
+ 'A "break" statement executed in the first suite terminates the loop\n'
+ 'without executing the "else" clause’s suite. A "continue" statement\n'
+ 'executed in the first suite skips the rest of the suite and '
+ 'continues\n'
+ 'with the next item, or with the "else" clause if there is no next\n'
+ 'item.\n'
+ '\n'
+ 'The for-loop makes assignments to the variables in the target list.\n'
+ 'This overwrites all previous assignments to those variables '
+ 'including\n'
+ 'those made in the suite of the for-loop:\n'
+ '\n'
+ ' for i in range(10):\n'
+ ' print(i)\n'
+ ' i = 5 # this will not affect the for-loop\n'
+ ' # because i will be overwritten with the '
+ 'next\n'
+ ' # index in the range\n'
+ '\n'
+ 'Names in the target list are not deleted when the loop is finished,\n'
+ 'but if the sequence is empty, they will not have been assigned to at\n'
+ 'all by the loop. Hint: the built-in type "range()" represents\n'
+ 'immutable arithmetic sequences of integers. For instance, iterating\n'
+ '"range(3)" successively yields 0, 1, and then 2.\n'
+ '\n'
+ 'Changed in version 3.11: Starred elements are now allowed in the\n'
+ 'expression list.\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 it is '
+ 'less\n'
+ 'sophisticated and, in particular, does not support '
+ 'arbitrary\n'
+ 'expressions.\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**: "format-spec:format_spec"\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. An *arg_name* is treated as a number if a call '
+ 'to\n'
+ '"str.isdecimal()" on the string would return true. If the '
+ 'numerical\n'
+ 'arg_names in a format string are 0, 1, 2, … in sequence, '
+ 'they can all\n'
+ 'be omitted (not just some) and the numbers 0, 1, 2, … will '
+ 'be\n'
+ 'automatically inserted in that order. Because *arg_name* is '
+ 'not quote-\n'
+ 'delimited, it is not possible to specify arbitrary '
+ 'dictionary keys\n'
+ '(e.g., the strings "\'10\'" or "\':-]\'") within a format '
+ 'string. The\n'
+ '*arg_name* can be followed by any number of index or '
+ 'attribute\n'
+ 'expressions. An expression of the form "\'.name\'" selects '
+ 'the named\n'
+ '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 f-strings). They can also be '
+ 'passed\n'
+ 'directly to the built-in "format()" function. Each '
+ 'formattable type\n'
+ 'may define how the format specification is to be '
+ '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 specification '
+ 'produces\n'
+ 'the same result as if you had called "str()" on the value. '
+ 'A non-empty\n'
+ 'format specification typically modifies the result.\n'
+ '\n'
+ 'The general form of a *standard format specifier* is:\n'
+ '\n'
+ ' **format_spec**: '
+ '["options"]["width_and_precision"]["type"]\n'
+ ' **options**: '
+ '[["fill"]"align"]["sign"]["z"]["#"]["0"]\n'
+ ' **fill**: <any character>\n'
+ ' **align**: "<" | ">" | "=" | "^"\n'
+ ' **sign**: "+" | "-" | " "\n'
+ ' **width_and_precision**: '
+ '["width_with_grouping"]["precision_with_grouping"]\n'
+ ' **width_with_grouping**: '
+ '["width"]["grouping_option"]\n'
+ ' **precision_with_grouping**: "." '
+ '["precision"]"grouping_option"\n'
+ ' **width**: "digit"+\n'
+ ' **grouping_option**: "_" | ","\n'
+ ' **precision**: "digit"+\n'
+ ' **type**: "b" | "c" | "d" | "e" | "E" '
+ '| "f" | "F" | "g"\n'
+ ' | "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, excluding "complex". '
+ 'It becomes |\n'
+ '| | the default for numbers when ‘0’ immediately '
+ 'precedes the |\n'
+ '| | 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 "\'z\'" option coerces negative zero floating-point '
+ 'values to\n'
+ 'positive zero after rounding to the format precision. This '
+ 'option is\n'
+ 'only valid for floating-point presentation types.\n'
+ '\n'
+ 'Changed in version 3.11: Added the "\'z\'" option (see also '
+ '**PEP\n'
+ '682**).\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 and '
+ 'complex\n'
+ 'types. For integers, when binary, octal, or hexadecimal '
+ 'output is\n'
+ 'used, this option adds the respective prefix "\'0b\'", '
+ '"\'0o\'", "\'0x\'",\n'
+ 'or "\'0X\'" to the output value. For float and complex the '
+ 'alternate\n'
+ 'form causes the result of the conversion to always contain '
+ 'a decimal-\n'
+ 'point character, even if no digits follow it. Normally, a '
+ 'decimal-\n'
+ 'point character appears in the result of these conversions '
+ 'only if a\n'
+ 'digit follows it. In addition, for "\'g\'" and "\'G\'" '
+ 'conversions,\n'
+ 'trailing zeros are not removed from the result.\n'
+ '\n'
+ 'The "\',\'" option signals the use of a comma for a '
+ 'thousands separator\n'
+ 'for floating-point presentation types and for integer '
+ 'presentation\n'
+ 'type "\'d\'". For other presentation types, this option is '
+ 'an error. For\n'
+ '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 total '
+ 'field width,\n'
+ 'including any prefixes, separators, and other formatting '
+ 'characters.\n'
+ 'If not specified, then the field width will be determined '
+ 'by the\n'
+ '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, excluding "complex". This is equivalent to a *fill* '
+ 'character\n'
+ 'of "\'0\'" with an *alignment* type of "\'=\'".\n'
+ '\n'
+ 'Changed in version 3.10: Preceding the *width* field by '
+ '"\'0\'" no\n'
+ 'longer affects the default alignment for strings.\n'
+ '\n'
+ 'The *precision* is a decimal integer indicating how many '
+ 'digits should\n'
+ 'be displayed after the decimal point for presentation types '
+ '"\'f\'" and\n'
+ '"\'F\'", or before and after the decimal point for '
+ 'presentation types\n'
+ '"\'g\'" or "\'G\'". For string presentation types the '
+ 'field indicates the\n'
+ 'maximum field size - in other words, how many characters '
+ 'will be used\n'
+ 'from the field content. The *precision* is not allowed for '
+ 'integer\n'
+ 'presentation types.\n'
+ '\n'
+ 'The "\'_\'" or "\',\'" option after *precision* means the '
+ 'use of an\n'
+ 'underscore or a comma for a thousands separator of the '
+ 'fractional part\n'
+ 'for floating-point presentation types.\n'
+ '\n'
+ 'Changed in version 3.14: Support thousands separators for '
+ 'the\n'
+ 'fractional part.\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. In '
+ 'case "\'#\'" is |\n'
+ ' | | specified, the prefix "\'0x\'" will be '
+ 'upper-cased to "\'0X\'" |\n'
+ ' | | as '
+ 'well. |\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 "float" and "Decimal" '
+ 'values are:\n'
+ '\n'
+ ' '
+ '+-----------+------------------------------------------------------------+\n'
+ ' | Type | '
+ 'Meaning '
+ '|\n'
+ ' '
+ '|===========|============================================================|\n'
+ ' | "\'e\'" | Scientific notation. For a given '
+ 'precision "p", formats |\n'
+ ' | | the number in scientific notation with the '
+ 'letter ‘e’ |\n'
+ ' | | separating the coefficient from the '
+ 'exponent. The |\n'
+ ' | | coefficient has one digit before and "p" '
+ 'digits after the |\n'
+ ' | | decimal point, for a total of "p + 1" '
+ 'significant digits. |\n'
+ ' | | With no precision given, uses a precision '
+ 'of "6" digits |\n'
+ ' | | after the decimal point for "float", and '
+ 'shows all |\n'
+ ' | | coefficient digits for "Decimal". If '
+ '"p=0", the decimal |\n'
+ ' | | point is omitted unless the "#" option is '
+ 'used. |\n'
+ ' '
+ '+-----------+------------------------------------------------------------+\n'
+ ' | "\'E\'" | Scientific notation. Same as "\'e\'" '
+ 'except it uses an upper |\n'
+ ' | | case ‘E’ as the separator '
+ 'character. |\n'
+ ' '
+ '+-----------+------------------------------------------------------------+\n'
+ ' | "\'f\'" | Fixed-point notation. For a given '
+ 'precision "p", formats |\n'
+ ' | | the number as a decimal number with '
+ 'exactly "p" digits |\n'
+ ' | | following the decimal point. With no '
+ 'precision given, uses |\n'
+ ' | | a precision of "6" digits after the '
+ 'decimal point for |\n'
+ ' | | "float", and uses a precision large enough '
+ 'to show all |\n'
+ ' | | coefficient digits for "Decimal". If '
+ '"p=0", the decimal |\n'
+ ' | | point is omitted unless the "#" option is '
+ 'used. |\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. A |\n'
+ ' | | precision of "0" is treated as equivalent '
+ 'to a precision |\n'
+ ' | | of "1". The precise rules are as follows: '
+ 'suppose that |\n'
+ ' | | the result formatted with presentation '
+ 'type "\'e\'" and |\n'
+ ' | | precision "p-1" would have exponent '
+ '"exp". Then, if "m <= |\n'
+ ' | | exp < p", where "m" is -4 for floats and '
+ '-6 for |\n'
+ ' | | "Decimals", the number is formatted with '
+ 'presentation type |\n'
+ ' | | "\'f\'" and precision "p-1-exp". '
+ 'Otherwise, the number is |\n'
+ ' | | formatted with presentation type "\'e\'" '
+ 'and precision |\n'
+ ' | | "p-1". In both cases insignificant '
+ 'trailing zeros are |\n'
+ ' | | removed from the significand, and the '
+ 'decimal point is |\n'
+ ' | | also removed if there are no remaining '
+ 'digits following |\n'
+ ' | | it, unless the "\'#\'" option is used. '
+ 'With no precision |\n'
+ ' | | given, uses a precision of "6" significant '
+ 'digits for |\n'
+ ' | | "float". For "Decimal", the coefficient of '
+ 'the result is |\n'
+ ' | | formed from the coefficient digits of the '
+ 'value; |\n'
+ ' | | scientific notation is used for values '
+ 'smaller than "1e-6" |\n'
+ ' | | in absolute value and values where the '
+ 'place value of the |\n'
+ ' | | least significant digit is larger than 1, '
+ 'and fixed-point |\n'
+ ' | | notation is used otherwise. Positive and '
+ 'negative |\n'
+ ' | | infinity, positive and negative zero, and '
+ 'nans, are |\n'
+ ' | | formatted as "inf", "-inf", "0", "-0" and '
+ '"nan" |\n'
+ ' | | respectively, regardless of the '
+ 'precision. |\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 | For "float" this is like the "\'g\'" type, '
+ 'except that when |\n'
+ ' | | fixed- point notation is used to format '
+ 'the result, it |\n'
+ ' | | always includes at least one digit past '
+ 'the decimal point, |\n'
+ ' | | and switches to the scientific notation '
+ 'when "exp >= p - |\n'
+ ' | | 1". When the precision is not specified, '
+ 'the latter will |\n'
+ ' | | be as large as needed to represent the '
+ 'given value |\n'
+ ' | | faithfully. For "Decimal", this is the '
+ 'same as either |\n'
+ ' | | "\'g\'" or "\'G\'" depending on the value '
+ 'of |\n'
+ ' | | "context.capitals" for the current decimal '
+ 'context. The |\n'
+ ' | | overall effect is to match the output of '
+ '"str()" as |\n'
+ ' | | altered by the other format '
+ 'modifiers. |\n'
+ ' '
+ '+-----------+------------------------------------------------------------+\n'
+ '\n'
+ 'The result should be correctly rounded to a given precision '
+ '"p" of\n'
+ 'digits after the decimal point. The rounding mode for '
+ '"float" matches\n'
+ 'that of the "round()" builtin. For "Decimal", the rounding '
+ 'mode of\n'
+ 'the current context will be used.\n'
+ '\n'
+ 'The available presentation types for "complex" are the same '
+ 'as those\n'
+ 'for "float" ("\'%\'" is not allowed). Both the real and '
+ 'imaginary\n'
+ 'components of a complex number are formatted as '
+ 'floating-point\n'
+ 'numbers, according to the specified presentation type. '
+ 'They are\n'
+ 'separated by the mandatory sign of the imaginary part, the '
+ 'latter\n'
+ 'being terminated by a "j" suffix. If the presentation type '
+ 'is\n'
+ 'missing, the result will match the output of "str()" '
+ '(complex numbers\n'
+ 'with a non-zero real part are also surrounded by '
+ 'parentheses),\n'
+ 'possibly altered by other format modifiers.\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 or the underscore as a thousands '
+ 'separator:\n'
+ '\n'
+ " >>> '{:,}'.format(1234567890)\n"
+ " '1,234,567,890'\n"
+ " >>> '{:_}'.format(1234567890)\n"
+ " '1_234_567_890'\n"
+ " >>> '{:_}'.format(123456789.123456789)\n"
+ " '123_456_789.12345679'\n"
+ " >>> '{:._}'.format(123456789.123456789)\n"
+ " '123456789.123_456_79'\n"
+ " >>> '{:_._}'.format(123456789.123456789)\n"
+ " '123_456_789.123_456_79'\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" ["type_params"] "(" ["parameter_list"] ")"\n'
+ ' ["->" "expression"] ":" "suite"\n'
+ ' **decorators**: "decorator"+\n'
+ ' **decorator**: "@" "assignment_expression" '
+ 'NEWLINE\n'
+ ' **parameter_list**: "defparameter" ("," '
+ '"defparameter")* "," "/" ["," ["parameter_list_no_posonly"]]\n'
+ ' | "parameter_list_no_posonly"\n'
+ ' **parameter_list_no_posonly**: "defparameter" ("," '
+ '"defparameter")* ["," ["parameter_list_starargs"]]\n'
+ ' | "parameter_list_starargs"\n'
+ ' **parameter_list_starargs**: "*" ["star_parameter"] ("," '
+ '"defparameter")* ["," ["parameter_star_kwargs"]]\n'
+ ' "*" ("," "defparameter")+ ["," '
+ '["parameter_star_kwargs"]]\n'
+ ' | "parameter_star_kwargs"\n'
+ ' **parameter_star_kwargs**: "**" "parameter" [","]\n'
+ ' **parameter**: "identifier" [":" '
+ '"expression"]\n'
+ ' **star_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. [4]\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'
+ 'Changed in version 3.9: Functions may be decorated with any '
+ 'valid\n'
+ '"assignment_expression". Previously, the grammar was much more\n'
+ 'restrictive; see **PEP 614** for details.\n'
+ '\n'
+ 'A list of type parameters may be given in square brackets '
+ 'between the\n'
+ 'function’s name and the opening parenthesis for its parameter '
+ 'list.\n'
+ 'This indicates to static type checkers that the function is '
+ 'generic.\n'
+ 'At runtime, the type parameters can be retrieved from the '
+ 'function’s\n'
+ '"__type_params__" attribute. See Generic functions for more.\n'
+ '\n'
+ 'Changed in version 3.12: Type parameter lists are new in Python '
+ '3.12.\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 value is a mutable '
+ 'object, such\n'
+ 'as a list or a dictionary: if the function modifies the object '
+ '(e.g.\n'
+ 'by appending an item to a list), the default parameter value is '
+ 'in\n'
+ 'effect modified. This is generally not what was intended. A '
+ 'way\n'
+ 'around this is to use "None" as the default, and explicitly test '
+ 'for\n'
+ 'it in the body of the 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 positional 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 by\n'
+ 'keyword arguments. Parameters before “"/"” are positional-only\n'
+ 'parameters and may only be passed by positional arguments.\n'
+ '\n'
+ 'Changed in version 3.8: The "/" function parameter syntax may be '
+ 'used\n'
+ 'to indicate positional-only parameters. See **PEP 570** for '
+ 'details.\n'
+ '\n'
+ 'Parameters may have an *annotation* of the form “": '
+ 'expression"”\n'
+ 'following the parameter name. Any parameter may have an '
+ 'annotation,\n'
+ 'even those of the form "*identifier" or "**identifier". (As a '
+ 'special\n'
+ 'case, parameters of the form "*identifier" may have an '
+ 'annotation “":\n'
+ '*expression"”.) Functions may have “return” annotation of the '
+ 'form\n'
+ '“"-> expression"” after the parameter list. These annotations '
+ 'can be\n'
+ 'any valid Python expression. The presence of annotations does '
+ 'not\n'
+ 'change the semantics of a function. See Annotations for more\n'
+ 'information on annotations.\n'
+ '\n'
+ 'Changed in version 3.11: Parameters of the form “"*identifier"” '
+ 'may\n'
+ 'have an annotation “": *expression"”. See **PEP 646**.\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'
+ ' **PEP 484** - Type Hints\n'
+ ' Definition of a standard meaning for annotations: type '
+ 'hints.\n'
+ '\n'
+ ' **PEP 526** - Syntax for Variable Annotations\n'
+ ' Ability to type hint variable declarations, including '
+ 'class\n'
+ ' variables and instance variables.\n'
+ '\n'
+ ' **PEP 563** - Postponed Evaluation of Annotations\n'
+ ' Support for forward references within annotations by '
+ 'preserving\n'
+ ' annotations in a string form at runtime instead of eager\n'
+ ' evaluation.\n'
+ '\n'
+ ' **PEP 318** - Decorators for Functions and Methods\n'
+ ' Function and method decorators were introduced. Class '
+ 'decorators\n'
+ ' were introduced in **PEP 3129**.\n',
+ 'global': 'The "global" statement\n'
+ '**********************\n'
+ '\n'
+ ' **global_stmt**: "global" "identifier" ("," "identifier")*\n'
+ '\n'
+ 'The "global" statement causes the listed identifiers to be '
+ 'interpreted\n'
+ 'as globals. It would be impossible to assign to a global variable\n'
+ 'without "global", although free variables may refer to globals '
+ 'without\n'
+ 'being declared global.\n'
+ '\n'
+ 'The "global" statement applies to the entire scope of a function '
+ 'or\n'
+ 'class body. A "SyntaxError" is raised if a variable is used or\n'
+ 'assigned to prior to its global declaration in the scope.\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 *".\n'
+ '\n'
+ '"_"\n'
+ ' In a "case" pattern within a "match" statement, "_" is a '
+ 'soft\n'
+ ' keyword that denotes a wildcard.\n'
+ '\n'
+ ' Separately, the interactive interpreter makes the result of '
+ 'the\n'
+ ' last evaluation available in the variable "_". (It is '
+ 'stored in the\n'
+ ' "builtins" module, alongside built-in functions like '
+ '"print".)\n'
+ '\n'
+ ' Elsewhere, "_" is a regular identifier. It is often used to '
+ 'name\n'
+ ' “special” items, but it is not special to Python itself.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' 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.It is\n'
+ ' also commonly used for unused variables.\n'
+ '\n'
+ '"__*__"\n'
+ ' System-defined names, informally known as “dunder” names. '
+ 'These\n'
+ ' names are defined by the interpreter and its '
+ 'implementation\n'
+ ' (including the standard library). Current system names are\n'
+ ' discussed in the Special method names section and '
+ 'elsewhere. More\n'
+ ' will likely be defined in future versions of Python. *Any* '
+ 'use of\n'
+ ' "__*__" names, in any context, that does not follow '
+ 'explicitly\n'
+ ' documented use, is subject to breakage without 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 include the uppercase and lowercase letters "A" '
+ 'through\n'
+ '"Z", the underscore "_" and, except for the first character, '
+ 'the\n'
+ 'digits "0" through "9". Python 3.0 introduced additional '
+ 'characters\n'
+ 'from outside the ASCII range (see **PEP 3131**). For these\n'
+ 'characters, the classification uses the version of the '
+ 'Unicode\n'
+ 'Character Database as included in the "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 16.0.0 can be found at\n'
+ 'https://www.unicode.org/Public/16.0.0/ucd/DerivedCoreProperties.txt\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 await else import pass\n'
+ ' None break except in raise\n'
+ ' True class finally is return\n'
+ ' and continue for lambda try\n'
+ ' as def from nonlocal while\n'
+ ' assert del global not with\n'
+ ' async elif if or yield\n'
+ '\n'
+ '\n'
+ 'Soft Keywords\n'
+ '=============\n'
+ '\n'
+ 'Added in version 3.10.\n'
+ '\n'
+ 'Some identifiers are only reserved under specific contexts. '
+ 'These are\n'
+ 'known as *soft keywords*. The identifiers "match", "case", '
+ '"type" and\n'
+ '"_" can syntactically act as keywords in certain contexts, '
+ 'but this\n'
+ 'distinction is done at the parser level, not when '
+ 'tokenizing.\n'
+ '\n'
+ 'As soft keywords, their use in the grammar is possible while '
+ 'still\n'
+ 'preserving compatibility with existing code that uses these '
+ 'names as\n'
+ 'identifier names.\n'
+ '\n'
+ '"match", "case", and "_" are used in the "match" statement. '
+ '"type" is\n'
+ 'used in the "type" statement.\n'
+ '\n'
+ 'Changed in version 3.12: "type" is now a soft keyword.\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 *".\n'
+ '\n'
+ '"_"\n'
+ ' In a "case" pattern within a "match" statement, "_" is a '
+ 'soft\n'
+ ' keyword that denotes a wildcard.\n'
+ '\n'
+ ' Separately, the interactive interpreter makes the result '
+ 'of the\n'
+ ' last evaluation available in the variable "_". (It is '
+ 'stored in the\n'
+ ' "builtins" module, alongside built-in functions like '
+ '"print".)\n'
+ '\n'
+ ' Elsewhere, "_" is a regular identifier. It is often used '
+ 'to name\n'
+ ' “special” items, but it is not special to Python itself.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' 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.It is\n'
+ ' also commonly used for unused variables.\n'
+ '\n'
+ '"__*__"\n'
+ ' System-defined names, informally known as “dunder” names. '
+ 'These\n'
+ ' names are defined by the interpreter and its '
+ 'implementation\n'
+ ' (including the standard library). Current system names '
+ 'are\n'
+ ' discussed in the Special method names section and '
+ 'elsewhere. More\n'
+ ' will likely be defined in future versions of Python. '
+ '*Any* use of\n'
+ ' "__*__" names, in any context, that does not follow '
+ 'explicitly\n'
+ ' documented use, is subject to breakage without 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" "assignment_expression" ":" "suite"\n'
+ ' ("elif" "assignment_expression" ":" "suite")*\n'
+ ' ["else" ":" "suite"]\n'
+ '\n'
+ 'It selects exactly one of the suites by evaluating the expressions '
+ 'one\n'
+ 'by one until one is found to be true (see section Boolean operations\n'
+ 'for the definition of true and false); then that suite is executed\n'
+ '(and no other part of the "if" statement is executed or evaluated).\n'
+ 'If all expressions are false, the suite of the "else" clause, if\n'
+ 'present, is executed.\n',
+ '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" "relative_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 '
+ 'where\n'
+ ' 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 '
+ '"as"\n'
+ ' 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, foo.bar, and foo.bar.baz '
+ 'imported, foo bound locally\n'
+ ' import foo.bar.baz as fbb # foo, foo.bar, and foo.bar.baz '
+ 'imported, foo.bar.baz bound as fbb\n'
+ ' from foo.bar import baz # foo, foo.bar, and foo.bar.baz '
+ 'imported, foo.bar.baz 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 in the Package\n'
+ 'Relative Imports section.\n'
+ '\n'
+ '"importlib.import_module()" is provided to support applications '
+ 'that\n'
+ 'determine dynamically the modules to be loaded.\n'
+ '\n'
+ 'Raises an auditing event "import" with arguments "module", '
+ '"filename",\n'
+ '"sys.path", "sys.meta_path", "sys.path_hooks".\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 only feature that requires using the future statement is\n'
+ '"annotations" (see **PEP 563**).\n'
+ '\n'
+ 'All historical features enabled by the future statement are still\n'
+ 'recognized by Python 3. The list includes "absolute_import",\n'
+ '"division", "generators", "generator_stop", "unicode_literals",\n'
+ '"print_function", "nested_scopes" and "with_statement". They are '
+ 'all\n'
+ 'redundant because they are always enabled, and only kept for '
+ 'backwards\n'
+ '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", for which\n'
+ 'the expression "x is z or x == z" is true, is produced while '
+ 'iterating\n'
+ 'over "y". If an exception is raised during the iteration, it is as if\n'
+ '"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 is y[i] or x == y[i]", and no\n'
+ 'lower integer index raises the "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 truth 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'
+ '\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**: "[" ["flexible_expression_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:\n'
+ '\n'
+ '* formal parameters to functions,\n'
+ '\n'
+ '* class definitions,\n'
+ '\n'
+ '* function definitions,\n'
+ '\n'
+ '* assignment expressions,\n'
+ '\n'
+ '* targets that are identifiers if occurring in an assignment:\n'
+ '\n'
+ ' * "for" loop header,\n'
+ '\n'
+ ' * after "as" in a "with" statement, "except" clause, "except*"\n'
+ ' clause, or in the as-pattern in structural pattern matching,\n'
+ '\n'
+ ' * in a capture pattern in structural pattern matching\n'
+ '\n'
+ '* "import" statements.\n'
+ '\n'
+ '* "type" statements.\n'
+ '\n'
+ '* type parameter lists.\n'
+ '\n'
+ 'The "import" statement of the form "from ... import *" binds all '
+ 'names\n'
+ 'defined in the imported module, except those beginning with an\n'
+ 'underscore. This form 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. See the FAQ entry on UnboundLocalError for examples.\n'
+ '\n'
+ 'If the "global" statement occurs within a block, all uses of the '
+ 'names\n'
+ 'specified in the statement refer to the bindings of those names 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 names are not found there, the builtins namespace is searched\n'
+ 'next. If the names are also not found in the builtins namespace, '
+ 'new\n'
+ 'variables are created in the global namespace. The global '
+ 'statement\n'
+ 'must precede all uses of the listed names.\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. Type parameters cannot be\n'
+ 'rebound with the "nonlocal" statement.\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, but it '
+ 'does\n'
+ 'not include annotation scopes, which have access to their '
+ 'enclosing\n'
+ 'class scopes. This means that the following will fail:\n'
+ '\n'
+ ' class A:\n'
+ ' a = 42\n'
+ ' b = list(a + i for i in range(10))\n'
+ '\n'
+ 'However, the following will succeed:\n'
+ '\n'
+ ' class A:\n'
+ ' type Alias = Nested\n'
+ ' class Nested: pass\n'
+ '\n'
+ " print(A.Alias.__value__) # <type 'A.Nested'>\n"
+ '\n'
+ '\n'
+ 'Annotation scopes\n'
+ '=================\n'
+ '\n'
+ '*Annotations*, type parameter lists and "type" statements '
+ 'introduce\n'
+ '*annotation scopes*, which behave mostly like function scopes, '
+ 'but\n'
+ 'with some exceptions discussed below.\n'
+ '\n'
+ 'Annotation scopes are used in the following contexts:\n'
+ '\n'
+ '* *Function annotations*.\n'
+ '\n'
+ '* *Variable annotations*.\n'
+ '\n'
+ '* Type parameter lists for generic type aliases.\n'
+ '\n'
+ '* Type parameter lists for generic functions. A generic '
+ 'function’s\n'
+ ' annotations are executed within the annotation scope, but its\n'
+ ' defaults and decorators are not.\n'
+ '\n'
+ '* Type parameter lists for generic classes. A generic class’s '
+ 'base\n'
+ ' classes and keyword arguments are executed within the '
+ 'annotation\n'
+ ' scope, but its decorators are not.\n'
+ '\n'
+ '* The bounds, constraints, and default values for type parameters\n'
+ ' (lazily evaluated).\n'
+ '\n'
+ '* The value of type aliases (lazily evaluated).\n'
+ '\n'
+ 'Annotation scopes differ from function scopes in the following '
+ 'ways:\n'
+ '\n'
+ '* Annotation scopes have access to their enclosing class '
+ 'namespace. If\n'
+ ' an annotation scope is immediately within a class scope, or '
+ 'within\n'
+ ' another annotation scope that is immediately within a class '
+ 'scope,\n'
+ ' the code in the annotation scope can use names defined in the '
+ 'class\n'
+ ' scope as if it were executed directly within the class body. '
+ 'This\n'
+ ' contrasts with regular functions defined within classes, which\n'
+ ' cannot access names defined in the class scope.\n'
+ '\n'
+ '* Expressions in annotation scopes cannot contain "yield", "yield\n'
+ ' from", "await", or ":=" expressions. (These expressions are '
+ 'allowed\n'
+ ' in other scopes contained within the annotation scope.)\n'
+ '\n'
+ '* Names defined in annotation scopes cannot be rebound with '
+ '"nonlocal"\n'
+ ' statements in inner scopes. This includes only type parameters, '
+ 'as\n'
+ ' no other syntactic elements that can appear within annotation '
+ 'scopes\n'
+ ' can introduce new names.\n'
+ '\n'
+ '* While annotation scopes have an internal name, that name is not\n'
+ ' reflected in the *qualified name* of objects defined within the\n'
+ ' scope. Instead, the "__qualname__" of such objects is as if the\n'
+ ' object were defined in the enclosing scope.\n'
+ '\n'
+ 'Added in version 3.12: Annotation scopes were introduced in '
+ 'Python\n'
+ '3.12 as part of **PEP 695**.\n'
+ '\n'
+ 'Changed in version 3.13: Annotation scopes are also used for type\n'
+ 'parameter defaults, as introduced by **PEP 696**.\n'
+ '\n'
+ 'Changed in version 3.14: Annotation scopes are now also used for\n'
+ 'annotations, as specified in **PEP 649** and **PEP 749**.\n'
+ '\n'
+ '\n'
+ 'Lazy evaluation\n'
+ '===============\n'
+ '\n'
+ 'Most annotation scopes are *lazily evaluated*. This includes\n'
+ 'annotations, the values of type aliases created through the '
+ '"type"\n'
+ 'statement, and the bounds, constraints, and default values of '
+ 'type\n'
+ 'variables created through the type parameter syntax. This means '
+ 'that\n'
+ 'they are not evaluated when the type alias or type variable is\n'
+ 'created, or when the object carrying annotations is created. '
+ 'Instead,\n'
+ 'they are only evaluated when necessary, for example when the\n'
+ '"__value__" attribute on a type alias is accessed.\n'
+ '\n'
+ 'Example:\n'
+ '\n'
+ ' >>> type Alias = 1/0\n'
+ ' >>> Alias.__value__\n'
+ ' Traceback (most recent call last):\n'
+ ' ...\n'
+ ' ZeroDivisionError: division by zero\n'
+ ' >>> def func[T: 1/0](): pass\n'
+ ' >>> T = func.__type_params__[0]\n'
+ ' >>> T.__bound__\n'
+ ' Traceback (most recent call last):\n'
+ ' ...\n'
+ ' ZeroDivisionError: division by zero\n'
+ '\n'
+ 'Here the exception is raised only when the "__value__" attribute '
+ 'of\n'
+ 'the type alias or the "__bound__" attribute of the type variable '
+ 'is\n'
+ 'accessed.\n'
+ '\n'
+ 'This behavior is primarily useful for references to types that '
+ 'have\n'
+ 'not yet been defined when the type alias or type variable is '
+ 'created.\n'
+ 'For example, lazy evaluation enables creation of mutually '
+ 'recursive\n'
+ 'type aliases:\n'
+ '\n'
+ ' from typing import Literal\n'
+ '\n'
+ ' type SimpleExpr = int | Parenthesized\n'
+ ' type Parenthesized = tuple[Literal["("], Expr, Literal[")"]]\n'
+ ' type Expr = SimpleExpr | tuple[SimpleExpr, Literal["+", "-"], '
+ 'Expr]\n'
+ '\n'
+ 'Lazily evaluated values are evaluated in annotation scope, which '
+ 'means\n'
+ 'that names that appear inside the lazily evaluated value are '
+ 'looked up\n'
+ 'as if they were used in the immediately enclosing scope.\n'
+ '\n'
+ 'Added in version 3.12.\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'
+ 'When the definition of a function or class is nested (enclosed) '
+ 'within\n'
+ 'the definitions of other functions, its nonlocal scopes are the '
+ 'local\n'
+ 'scopes of the enclosing functions. The "nonlocal" statement '
+ 'causes the\n'
+ 'listed identifiers to refer to names previously bound in '
+ 'nonlocal\n'
+ 'scopes. It allows encapsulated code to rebind such nonlocal\n'
+ 'identifiers. If a name is bound in more than one nonlocal '
+ 'scope, the\n'
+ 'nearest binding is used. If a name is not bound in any nonlocal '
+ 'scope,\n'
+ 'or if there is no nonlocal scope, a "SyntaxError" is raised.\n'
+ '\n'
+ 'The "nonlocal" statement applies to the entire scope of a '
+ 'function or\n'
+ 'class body. A "SyntaxError" is raised if a variable is used or\n'
+ 'assigned to prior to its nonlocal declaration in the scope.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 3104** - Access to Names in Outer Scopes\n'
+ ' The specification for the "nonlocal" statement.\n'
+ '\n'
+ '**Programmer’s note:** "nonlocal" is a directive to the parser '
+ 'and\n'
+ 'applies only to code parsed along with it. See the note for '
+ 'the\n'
+ '"global" 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, '
+ '"type(x).__add__(x, y)" is\n'
+ ' called. The "__divmod__()" method should be the '
+ 'equivalent to\n'
+ ' using "__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[, modulo])\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 '
+ 'operands are of\n'
+ ' different types, when the left operand does not support '
+ 'the\n'
+ ' corresponding operation [3], or the right operand’s '
+ 'class is\n'
+ ' derived from the left operand’s class. [4] For instance, '
+ 'to\n'
+ ' evaluate the expression "x - y", where *y* is an '
+ 'instance of a\n'
+ ' class that has an "__rsub__()" method, '
+ '"type(y).__rsub__(y, x)" is\n'
+ ' called if "type(x).__sub__(x, y)" returns '
+ '"NotImplemented" or\n'
+ ' "type(y)" is a subclass of "type(x)". [5]\n'
+ '\n'
+ ' Note that ternary "pow()" will not try calling '
+ '"__rpow__()" (the\n'
+ ' coercion rules would become too complicated).\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' If the right operand’s type is a subclass of the left '
+ 'operand’s\n'
+ ' type and that subclass provides a different '
+ 'implementation of the\n'
+ ' reflected method for the operation, this method will '
+ 'be called\n'
+ ' before the left operand’s non-reflected method. This '
+ 'behavior\n'
+ ' allows subclasses 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, or if that method returns '
+ '"NotImplemented",\n'
+ ' the augmented assignment falls back to the normal '
+ 'methods. For\n'
+ ' instance, if *x* is an instance of a class with an '
+ '"__iadd__()"\n'
+ ' method, "x += y" is equivalent to "x = x.__iadd__(y)" . '
+ 'If\n'
+ ' "__iadd__()" does not exist, or if "x.__iadd__(y)" '
+ 'returns\n'
+ ' "NotImplemented", "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'
+ ' If "__int__()", "__float__()" and "__complex__()" are '
+ 'not defined\n'
+ ' then corresponding built-in functions "int()", "float()" '
+ 'and\n'
+ ' "complex()" fall back to "__index__()".\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'
+ ' Changed in version 3.14: "int()" no longer delegates to '
+ 'the\n'
+ ' "__trunc__()" method.\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 '
+ 'convenient\n'
+ '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. For example, after "a = '
+ '1; b\n'
+ '= 1", *a* and *b* may or may not refer to the same object with '
+ 'the\n'
+ 'value one, depending on the implementation. This is because "int" '
+ 'is\n'
+ 'an immutable type, so the reference to "1" can be reused. This\n'
+ 'behaviour depends on the implementation used, so should not be '
+ 'relied\n'
+ 'upon, but is something to be aware of when making use of object\n'
+ 'identity tests. However, after "c = []; d = []", *c* and *d* are\n'
+ 'guaranteed to refer to two different, unique, newly created '
+ 'empty\n'
+ 'lists. (Note that "e = f = []" assigns the *same* object to both '
+ '*e*\n'
+ 'and *f*.)\n',
+ 'operator-summary': 'Operator precedence\n'
+ '*******************\n'
+ '\n'
+ 'The following table summarizes the operator precedence '
+ 'in Python, from\n'
+ 'highest precedence (most binding) to lowest precedence '
+ '(least\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 and\n'
+ 'conditional expressions, which group 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'
+ '| "(expressions...)", "[expressions...]", "{key: | '
+ 'Binding or parenthesized expression, |\n'
+ '| value...}", "{expressions...}" | list '
+ 'display, dictionary display, set |\n'
+ '| | '
+ 'display |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "x[index]", "x[index:index]", | '
+ 'Subscription, slicing, call, |\n'
+ '| "x(arguments...)", "x.attribute" | '
+ 'attribute reference |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "await x" | '
+ 'Await expression |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "**" | '
+ 'Exponentiation [5] |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "+x", "-x", "~x" | '
+ 'Positive, negative, bitwise NOT |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "*", "@", "/", "//", "%" | '
+ 'Multiplication, matrix |\n'
+ '| | '
+ 'multiplication, division, floor |\n'
+ '| | '
+ 'division, remainder [6] |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "+", "-" | '
+ 'Addition and subtraction |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "<<", ">>" | '
+ 'Shifts |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "&" | '
+ 'Bitwise AND |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "^" | '
+ 'Bitwise XOR |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "|" | '
+ 'Bitwise OR |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "in", "not in", "is", "is not", "<", "<=", ">", | '
+ 'Comparisons, including membership |\n'
+ '| ">=", "!=", "==" | '
+ 'tests and identity tests |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "not x" | '
+ 'Boolean NOT |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "and" | '
+ 'Boolean AND |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "or" | '
+ 'Boolean OR |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "if" – "else" | '
+ 'Conditional expression |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| "lambda" | '
+ 'Lambda expression |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '| ":=" | '
+ 'Assignment expression |\n'
+ '+-------------------------------------------------+---------------------------------------+\n'
+ '\n'
+ '-[ Footnotes ]-\n'
+ '\n'
+ '[1] While "abs(x%y) < abs(y)" is true mathematically, '
+ 'for floats it\n'
+ ' 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 dynamic\n'
+ ' nature of descriptors, you may notice seemingly '
+ 'unusual behaviour\n'
+ ' in certain uses of the "is" operator, like those '
+ 'involving\n'
+ ' comparisons between instance methods, or constants. '
+ 'Check their\n'
+ ' documentation for more info.\n'
+ '\n'
+ '[5] The power operator "**" binds less tightly than an '
+ 'arithmetic or\n'
+ ' bitwise unary operator on its right, that is, '
+ '"2**-1" is "0.5".\n'
+ '\n'
+ '[6] The "%" operator is also used for string formatting; '
+ 'the same\n'
+ ' precedence applies.\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'
+ '\n'
+ 'This operation can be customized using the special "__pow__()" and\n'
+ '"__rpow__()" methods.\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 exception that '
+ 'is\n'
+ 'currently being handled, which is also known as the *active\n'
+ 'exception*. If there isn’t currently an active exception, a\n'
+ '"RuntimeError" exception is raised indicating 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. You '
+ 'can\n'
+ 'create an exception and set your own traceback in one step using '
+ 'the\n'
+ '"with_traceback()" exception method (which returns the same '
+ 'exception\n'
+ 'instance, with its traceback set to its argument), 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. If the\n'
+ 'second expression is an exception instance, it will be attached to '
+ 'the\n'
+ 'raised exception as the "__cause__" attribute (which is writable). '
+ 'If\n'
+ 'the expression is an exception class, the class will be '
+ 'instantiated\n'
+ 'and the resulting exception instance will be attached to the '
+ 'raised\n'
+ 'exception as the "__cause__" attribute. If the raised exception is '
+ 'not\n'
+ 'handled, both 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'
+ ' print(1 / 0)\n'
+ ' ~~^~~\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'
+ ' raise RuntimeError("Something bad happened") from exc\n'
+ ' RuntimeError: Something bad happened\n'
+ '\n'
+ 'A similar mechanism works implicitly if a new exception is raised '
+ 'when\n'
+ 'an exception is already being handled. An exception may be '
+ 'handled\n'
+ 'when an "except" or "finally" clause, or a "with" statement, is '
+ 'used.\n'
+ 'The previous exception is then attached as the new exception’s\n'
+ '"__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'
+ ' print(1 / 0)\n'
+ ' ~~^~~\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'
+ ' raise RuntimeError("Something bad happened")\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".Added the "__suppress_context__" attribute to suppress\n'
+ 'automatic display of the exception context.\n'
+ '\n'
+ 'Changed in version 3.11: If the traceback of the active exception '
+ 'is\n'
+ 'modified in an "except" clause, a subsequent "raise" statement re-\n'
+ 'raises the exception with the modified traceback. Previously, the\n'
+ 'exception was re-raised with the traceback it had when it was '
+ 'caught.\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'
+ 'None of them are provided by the "object" class itself. '
+ 'Containers\n'
+ 'usually are *sequences* (such as "lists" or "tuples") or '
+ '*mappings*\n'
+ '(like *dictionaries*), but can represent other containers '
+ 'as well.\n'
+ 'The 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.abc" module provides a "MutableMapping" '
+ '*abstract\n'
+ 'base class* to help create those methods from a base set '
+ 'of\n'
+ '"__getitem__()", "__setitem__()", "__delitem__()", and '
+ '"keys()".\n'
+ 'Mutable sequences should provide methods "append()", '
+ '"count()",\n'
+ '"index()", "extend()", "insert()", "pop()", "remove()", '
+ '"reverse()"\n'
+ 'and "sort()", like Python standard "list" objects. '
+ 'Finally, sequence\n'
+ 'types should implement addition (meaning concatenation) '
+ 'and\n'
+ 'multiplication (meaning repetition) by defining the '
+ 'methods\n'
+ '"__add__()", "__radd__()", "__iadd__()", "__mul__()", '
+ '"__rmul__()" and\n'
+ '"__imul__()" described below; they should not define other '
+ 'numerical\n'
+ 'operators. It is recommended that both mappings and '
+ 'sequences\n'
+ 'implement the "__contains__()" method to allow efficient '
+ 'use of the\n'
+ '"in" operator; for mappings, "in" should search the '
+ 'mapping’s keys;\n'
+ 'for sequences, it should search through the values. It is '
+ 'further\n'
+ 'recommended that both mappings and sequences implement '
+ 'the\n'
+ '"__iter__()" method to allow efficient iteration through '
+ 'the\n'
+ 'container; for mappings, "__iter__()" should iterate '
+ 'through the\n'
+ 'object’s keys; for sequences, it should iterate 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. The\n'
+ ' return value may also be "NotImplemented", which is '
+ 'treated the\n'
+ ' same as if the "__length_hint__" method didn’t exist at '
+ 'all. This\n'
+ ' method is purely an optimization and is never required '
+ 'for\n'
+ ' correctness.\n'
+ '\n'
+ ' Added in version 3.4.\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Slicing is done exclusively with the following three '
+ 'methods. A\n'
+ ' 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*\n'
+ ' types, the accepted keys should be integers. '
+ 'Optionally, they may\n'
+ ' support "slice" objects as well. Negative index '
+ 'support is also\n'
+ ' optional. If *key* is of an inappropriate type, '
+ '"TypeError" may be\n'
+ ' raised; if *key* is a value outside the set of indexes '
+ 'for the\n'
+ ' sequence (after any special interpretation of negative '
+ 'values),\n'
+ ' "IndexError" should be raised. For *mapping* types, if '
+ '*key* is\n'
+ ' missing (not in the container), "KeyError" should be '
+ 'raised.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' "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'
+ ' Note:\n'
+ '\n'
+ ' When subscripting a *class*, the special class '
+ 'method\n'
+ ' "__class_getitem__()" may be called instead of '
+ '"__getitem__()".\n'
+ ' See __class_getitem__ versus __getitem__ for more '
+ 'details.\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\n'
+ ' container. This method should return a new iterator '
+ 'object that can\n'
+ ' iterate over all the objects in the container. For '
+ 'mappings, it\n'
+ ' should iterate over the keys of the container.\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 container. However, '
+ 'container\n'
+ 'objects can supply the following special method with a '
+ 'more efficient\n'
+ 'implementation, which also does not require the object be '
+ 'iterable.\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'
+ 'The left shift operation can be customized using the special\n'
+ '"__lshift__()" and "__rlshift__()" methods. The right shift '
+ 'operation\n'
+ 'can be customized using the special "__rshift__()" and '
+ '"__rrshift__()"\n'
+ 'methods.\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',
+ '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'
+ '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'
+ ' Added in version 3.3.\n'
+ '\n'
+ 'definition.__module__\n'
+ '\n'
+ ' The name of the module in which a class or function was '
+ 'defined.\n'
+ '\n'
+ 'definition.__doc__\n'
+ '\n'
+ ' The documentation string of a class or function, or '
+ '"None" if\n'
+ ' undefined.\n'
+ '\n'
+ 'definition.__type_params__\n'
+ '\n'
+ ' The type parameters of generic classes, functions, and '
+ 'type\n'
+ ' aliases. For classes and functions that are not generic, '
+ 'this will\n'
+ ' be an empty tuple.\n'
+ '\n'
+ ' Added in version 3.12.\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__()" is invoked during object construction and '
+ 'it returns\n'
+ ' an instance of *cls*, then the new instance’s '
+ '"__init__()" method\n'
+ ' will be invoked like "__init__(self[, ...])", where '
+ '*self* is the\n'
+ ' new instance and the remaining arguments are the same as '
+ 'were\n'
+ ' passed to the object constructor.\n'
+ '\n'
+ ' If "__new__()" does not return an instance of *cls*, then '
+ 'the new\n'
+ ' instance’s "__init__()" method will not be invoked.\n'
+ '\n'
+ ' "__new__()" is intended mainly to allow subclasses of '
+ 'immutable\n'
+ ' types (like int, str, or tuple) to customize instance '
+ 'creation. It\n'
+ ' is also commonly overridden in custom metaclasses in '
+ 'order to\n'
+ ' customize class creation.\n'
+ '\n'
+ 'object.__init__(self[, ...])\n'
+ '\n'
+ ' Called after the instance has been created (by '
+ '"__new__()"), but\n'
+ ' before it is returned to the caller. The arguments are '
+ 'those\n'
+ ' passed to the class constructor expression. If a base '
+ 'class has an\n'
+ ' "__init__()" method, the derived class’s "__init__()" '
+ 'method, if\n'
+ ' any, must explicitly call it to ensure proper '
+ 'initialization of the\n'
+ ' base class part of the instance; for example:\n'
+ ' "super().__init__([args...])".\n'
+ '\n'
+ ' Because "__new__()" and "__init__()" work together in '
+ 'constructing\n'
+ ' objects ("__new__()" to create it, and "__init__()" to '
+ 'customize\n'
+ ' it), no non-"None" value may be returned by "__init__()"; '
+ 'doing so\n'
+ ' will cause a "TypeError" to be raised at runtime.\n'
+ '\n'
+ 'object.__del__(self)\n'
+ '\n'
+ ' Called when the instance is about to be destroyed. This '
+ 'is also\n'
+ ' 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'
+ ' "weakref.finalize" provides a straightforward way to '
+ 'register a\n'
+ ' cleanup function to be called when an object is garbage '
+ 'collected.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' "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:\n'
+ '\n'
+ ' Due to the precarious circumstances under which '
+ '"__del__()"\n'
+ ' methods are invoked, exceptions that occur during their '
+ 'execution\n'
+ ' are ignored, and a warning is printed to "sys.stderr" '
+ 'instead.\n'
+ ' In particular:\n'
+ '\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 a\n'
+ ' consequence, the global variables it needs to access '
+ '(including\n'
+ ' other modules) may already have been deleted or set '
+ 'to "None".\n'
+ ' Python guarantees that globals whose name begins with '
+ 'a single\n'
+ ' underscore are deleted from their module before other '
+ 'globals\n'
+ ' are deleted; if no other references to such globals '
+ 'exist, this\n'
+ ' may help in assuring that imported modules are still '
+ 'available\n'
+ ' at the time when the "__del__()" method is called.\n'
+ '\n'
+ 'object.__repr__(self)\n'
+ '\n'
+ ' Called by the "repr()" built-in function to compute the '
+ '“official”\n'
+ ' string representation of an object. If at all possible, '
+ 'this\n'
+ ' should look like a valid Python expression that could be '
+ 'used to\n'
+ ' recreate an object with the same value (given an '
+ 'appropriate\n'
+ ' environment). If this is not possible, a string of the '
+ 'form\n'
+ ' "<...some useful description...>" should be returned. The '
+ 'return\n'
+ ' value must be a string object. If a class defines '
+ '"__repr__()" but\n'
+ ' not "__str__()", then "__repr__()" is also used when an '
+ '“informal”\n'
+ ' string representation of instances of that class is '
+ 'required.\n'
+ '\n'
+ ' This is typically used for debugging, so it is important '
+ 'that the\n'
+ ' representation is information-rich and unambiguous. A '
+ 'default\n'
+ ' implementation is provided by the "object" class itself.\n'
+ '\n'
+ 'object.__str__(self)\n'
+ '\n'
+ ' Called by "str(object)", the default "__format__()" '
+ 'implementation,\n'
+ ' and the built-in function "print()", to compute the '
+ '“informal” or\n'
+ ' nicely printable string representation of an object. The '
+ 'return\n'
+ ' value must be a str 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. The "object" '
+ 'class\n'
+ ' itself does not provide this method.\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'
+ ' The default implementation by the "object" class should '
+ 'be given an\n'
+ ' empty *format_spec* string. It delegates to "__str__()".\n'
+ '\n'
+ ' Changed in version 3.4: The __format__ method of "object" '
+ 'itself\n'
+ ' raises a "TypeError" if passed any non-empty string.\n'
+ '\n'
+ ' Changed in version 3.7: "object.__format__(x, \'\')" is '
+ 'now\n'
+ ' equivalent to "str(x)" rather than "format(str(x), '
+ '\'\')".\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, "object" implements "__eq__()" by using "is", '
+ 'returning\n'
+ ' "NotImplemented" in the case of a false comparison: "True '
+ 'if x is y\n'
+ ' else NotImplemented". For "__ne__()", by default it '
+ 'delegates to\n'
+ ' "__eq__()" and inverts the result unless it is '
+ '"NotImplemented".\n'
+ ' There are no other implied relationships among the '
+ 'comparison\n'
+ ' operators or default implementations; for example, the '
+ 'truth of\n'
+ ' "(x<y or x==y)" does not imply "x<=y". To automatically '
+ 'generate\n'
+ ' ordering operations from a single root operation, see\n'
+ ' "functools.total_ordering()".\n'
+ '\n'
+ ' By default, the "object" class provides implementations '
+ 'consistent\n'
+ ' with Value comparisons: equality compares according to '
+ 'object\n'
+ ' identity, and order comparisons raise "TypeError". Each '
+ 'default\n'
+ ' method may generate these results directly, but may also '
+ 'return\n'
+ ' "NotImplemented".\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 the 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'
+ ' When no appropriate method returns any value other than\n'
+ ' "NotImplemented", the "==" and "!=" operators will fall '
+ 'back to\n'
+ ' "is" and "is not", respectively.\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'
+ ' The "__hash__()" method should return an integer. The '
+ 'only required\n'
+ ' property is that objects which compare equal have the '
+ 'same hash\n'
+ ' value; it is advised to mix together the hash values of '
+ 'the\n'
+ ' components of the object that also play a part in '
+ 'comparison of\n'
+ ' objects by packing them into a tuple and hashing the '
+ 'tuple.\n'
+ ' Example:\n'
+ '\n'
+ ' def __hash__(self):\n'
+ ' return hash((self.name, self.nick, self.color))\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' "hash()" truncates the value returned from an object’s '
+ 'custom\n'
+ ' "__hash__()" method to the size of a "Py_ssize_t". '
+ 'This is\n'
+ ' typically 8 bytes on 64-bit builds and 4 bytes on '
+ '32-bit builds.\n'
+ ' If an object’s "__hash__()" must interoperate on '
+ 'builds of\n'
+ ' different bit sizes, be sure to check the width on all '
+ 'supported\n'
+ ' builds. An easy way to do this is with "python -c '
+ '"import sys;\n'
+ ' print(sys.hash_info.width)"".\n'
+ '\n'
+ ' If a class does not define an "__eq__()" method it should '
+ 'not\n'
+ ' define a "__hash__()" operation either; if it defines '
+ '"__eq__()"\n'
+ ' but not "__hash__()", its instances will not be usable as '
+ 'items in\n'
+ ' hashable collections. If a class defines mutable objects '
+ 'and\n'
+ ' implements an "__eq__()" method, it should not implement\n'
+ ' "__hash__()", since the implementation of *hashable* '
+ 'collections\n'
+ ' requires that a key’s hash value is immutable (if the '
+ 'object’s hash\n'
+ ' value changes, it will be in the wrong hash bucket).\n'
+ '\n'
+ ' User-defined classes have "__eq__()" and "__hash__()" '
+ 'methods by\n'
+ ' default (inherited from the "object" class); with them, '
+ 'all objects\n'
+ ' compare unequal (except with themselves) and '
+ '"x.__hash__()" returns\n'
+ ' an appropriate value such that "x == y" implies both that '
+ '"x is y"\n'
+ ' and "hash(x) == hash(y)".\n'
+ '\n'
+ ' A class that overrides "__eq__()" and does not define '
+ '"__hash__()"\n'
+ ' will have its "__hash__()" implicitly set to "None". '
+ 'When the\n'
+ ' "__hash__()" method of a class is "None", instances of '
+ 'the class\n'
+ ' will raise an appropriate "TypeError" when a program '
+ 'attempts to\n'
+ ' retrieve their hash value, and will also be correctly '
+ 'identified as\n'
+ ' unhashable when checking "isinstance(obj,\n'
+ ' collections.abc.Hashable)".\n'
+ '\n'
+ ' If a class that overrides "__eq__()" needs to retain the\n'
+ ' implementation of "__hash__()" from a parent class, the '
+ 'interpreter\n'
+ ' must be told this explicitly by setting "__hash__ =\n'
+ ' <ParentClass>.__hash__".\n'
+ '\n'
+ ' If a class that does not override "__eq__()" wishes to '
+ 'suppress\n'
+ ' hash support, it should include "__hash__ = None" in the '
+ 'class\n'
+ ' definition. A class which defines its own "__hash__()" '
+ 'that\n'
+ ' explicitly raises a "TypeError" would be incorrectly '
+ 'identified as\n'
+ ' hashable by an "isinstance(obj, '
+ 'collections.abc.Hashable)" call.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' By default, the "__hash__()" values of str and bytes '
+ 'objects are\n'
+ ' “salted” with an unpredictable random value. Although '
+ 'they\n'
+ ' remain constant within an individual Python process, '
+ 'they are not\n'
+ ' predictable between repeated invocations of Python.This '
+ 'is\n'
+ ' intended to provide protection against a '
+ 'denial-of-service caused\n'
+ ' by carefully chosen inputs that exploit the worst case\n'
+ ' performance of a dict insertion, *O*(*n*^2) '
+ 'complexity. See\n'
+ ' http://ocert.org/advisories/ocert-2011-003.html for\n'
+ ' details.Changing hash values affects the iteration '
+ 'order of sets.\n'
+ ' Python has never made guarantees about this ordering '
+ '(and it\n'
+ ' typically varies between 32-bit and 64-bit builds).See '
+ 'also\n'
+ ' "PYTHONHASHSEED".\n'
+ '\n'
+ ' Changed in version 3.3: Hash randomization is enabled by '
+ 'default.\n'
+ '\n'
+ 'object.__bool__(self)\n'
+ '\n'
+ ' Called to implement truth value testing and the built-in '
+ 'operation\n'
+ ' "bool()"; should return "False" or "True". When this '
+ 'method is not\n'
+ ' defined, "__len__()" is called, if it is defined, and the '
+ 'object is\n'
+ ' considered true if its result is nonzero. If a class '
+ 'defines\n'
+ ' neither "__len__()" nor "__bool__()" (which is true of '
+ 'the "object"\n'
+ ' class itself), all its instances are 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. The "object" class itself does not provide '
+ 'this method.\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 take 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:\n'
+ '\n'
+ ' This method may still be bypassed when looking up '
+ 'special methods\n'
+ ' as the result of implicit invocation via language '
+ 'syntax or\n'
+ ' built-in functions. See Special method lookup.\n'
+ '\n'
+ ' For certain sensitive attribute accesses, raises an '
+ 'auditing event\n'
+ ' "object.__getattr__" with arguments "obj" and "name".\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'
+ ' For certain sensitive attribute assignments, raises an '
+ 'auditing\n'
+ ' event "object.__setattr__" with arguments "obj", "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'
+ ' For certain sensitive attribute deletions, raises an '
+ 'auditing event\n'
+ ' "object.__delattr__" with arguments "obj" and "name".\n'
+ '\n'
+ 'object.__dir__(self)\n'
+ '\n'
+ ' Called when "dir()" is called on the object. An iterable '
+ 'must be\n'
+ ' returned. "dir()" converts the returned iterable to a '
+ 'list and\n'
+ ' sorts it.\n'
+ '\n'
+ '\n'
+ 'Customizing module attribute access\n'
+ '-----------------------------------\n'
+ '\n'
+ 'Special names "__getattr__" and "__dir__" can be also used '
+ 'to\n'
+ 'customize access to module attributes. The "__getattr__" '
+ 'function at\n'
+ 'the module level should accept one argument which is the '
+ 'name of an\n'
+ 'attribute and return the computed value or raise an '
+ '"AttributeError".\n'
+ 'If an attribute is not found on a module object through the '
+ 'normal\n'
+ 'lookup, i.e. "object.__getattribute__()", then "__getattr__" '
+ 'is\n'
+ 'searched in the module "__dict__" before raising an '
+ '"AttributeError".\n'
+ 'If found, it is called with the attribute name and the '
+ 'result is\n'
+ 'returned.\n'
+ '\n'
+ 'The "__dir__" function should accept no arguments, and '
+ 'return an\n'
+ 'iterable of strings that represents the names accessible on '
+ 'module. If\n'
+ 'present, this function overrides the standard "dir()" search '
+ 'on a\n'
+ 'module.\n'
+ '\n'
+ 'For a more fine grained customization of the module behavior '
+ '(setting\n'
+ 'attributes, properties, etc.), one can set the "__class__" '
+ 'attribute\n'
+ 'of a module object to a subclass of "types.ModuleType". For '
+ 'example:\n'
+ '\n'
+ ' import sys\n'
+ ' from types import ModuleType\n'
+ '\n'
+ ' class VerboseModule(ModuleType):\n'
+ ' def __repr__(self):\n'
+ " return f'Verbose {self.__name__}'\n"
+ '\n'
+ ' def __setattr__(self, attr, value):\n'
+ " print(f'Setting {attr}...')\n"
+ ' super().__setattr__(attr, value)\n'
+ '\n'
+ ' sys.modules[__name__].__class__ = VerboseModule\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Defining module "__getattr__" and setting module '
+ '"__class__" only\n'
+ ' affect lookups made using the attribute access syntax – '
+ 'directly\n'
+ ' accessing the module globals (whether by code within the '
+ 'module, or\n'
+ ' via a reference to the module’s globals dictionary) is '
+ 'unaffected.\n'
+ '\n'
+ 'Changed in version 3.5: "__class__" module attribute is now '
+ 'writable.\n'
+ '\n'
+ 'Added in version 3.7: "__getattr__" and "__dir__" module '
+ 'attributes.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 562** - Module __getattr__ and __dir__\n'
+ ' Describes the "__getattr__" and "__dir__" functions on '
+ 'modules.\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__". The '
+ '"object"\n'
+ 'class itself does not implement any of these protocols.\n'
+ '\n'
+ 'object.__get__(self, instance, owner=None)\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). The optional *owner* argument is the owner '
+ 'class, while\n'
+ ' *instance* is the instance that the attribute was '
+ 'accessed through,\n'
+ ' or "None" when the attribute is accessed through the '
+ '*owner*.\n'
+ '\n'
+ ' This method should return the computed attribute value or '
+ 'raise an\n'
+ ' "AttributeError" exception.\n'
+ '\n'
+ ' **PEP 252** specifies that "__get__()" is callable with '
+ 'one or two\n'
+ ' arguments. Python’s own built-in descriptors support '
+ 'this\n'
+ ' specification; however, it is likely that some '
+ 'third-party tools\n'
+ ' have descriptors that require both arguments. Python’s '
+ 'own\n'
+ ' "__getattribute__()" implementation always passes in both '
+ 'arguments\n'
+ ' whether they are required or not.\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'
+ ' Note, adding "__set__()" or "__delete__()" changes the '
+ 'kind of\n'
+ ' descriptor to a “data descriptor”. See Invoking '
+ 'Descriptors for\n'
+ ' more details.\n'
+ '\n'
+ 'object.__delete__(self, instance)\n'
+ '\n'
+ ' Called to delete the attribute on an instance *instance* '
+ 'of the\n'
+ ' owner class.\n'
+ '\n'
+ 'Instances of descriptors may also have the "__objclass__" '
+ 'attribute\n'
+ 'present:\n'
+ '\n'
+ 'object.__objclass__\n'
+ '\n'
+ ' The attribute "__objclass__" is interpreted by the '
+ '"inspect" module\n'
+ ' as 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'
+ ' A dotted lookup such as "super(A, a).x" searches\n'
+ ' "a.__class__.__mro__" for a base class "B" following "A" '
+ 'and then\n'
+ ' returns "B.__dict__[\'x\'].__get__(a, A)". If not a '
+ 'descriptor, "x"\n'
+ ' is returned unchanged.\n'
+ '\n'
+ 'For instance bindings, the precedence of descriptor '
+ 'invocation depends\n'
+ 'on which descriptor methods are defined. A descriptor can '
+ 'define any\n'
+ '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 "__get__()" and '
+ '"__set__()"\n'
+ '(and/or "__delete__()") defined always override a '
+ 'redefinition in an\n'
+ 'instance dictionary. In contrast, non-data descriptors can '
+ 'be\n'
+ 'overridden by instances.\n'
+ '\n'
+ 'Python methods (including those decorated with '
+ '"@staticmethod" and\n'
+ '"@classmethod") are implemented as non-data descriptors. '
+ 'Accordingly,\n'
+ 'instances can redefine and override methods. This allows '
+ 'individual\n'
+ 'instances to acquire behaviors that differ from other '
+ 'instances of the\n'
+ '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. '
+ 'Attribute\n'
+ 'lookup speed can be significantly improved as well.\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'
+ 'Notes on using *__slots__*:\n'
+ '\n'
+ '* When inheriting from a class without *__slots__*, the '
+ '"__dict__" and\n'
+ ' *__weakref__* attribute of the instances will always be '
+ '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 defining\n'
+ ' *__slots__* do not support "weak references" to its '
+ 'instances. If\n'
+ ' weak reference support is needed, then add '
+ '"\'__weakref__\'" to the\n'
+ ' sequence of strings in the *__slots__* declaration.\n'
+ '\n'
+ '* *__slots__* are implemented at the class level by '
+ 'creating\n'
+ ' descriptors for each variable name. As a result, class '
+ 'attributes\n'
+ ' cannot be used to set default values for instance '
+ 'variables defined\n'
+ ' by *__slots__*; otherwise, the class attribute would '
+ 'overwrite the\n'
+ ' descriptor assignment.\n'
+ '\n'
+ '* The action of a *__slots__* declaration is not limited to '
+ 'the class\n'
+ ' where it is defined. *__slots__* declared in parents are '
+ 'available\n'
+ ' in child classes. However, instances of a child subclass '
+ 'will get a\n'
+ ' "__dict__" and *__weakref__* unless the subclass also '
+ 'defines\n'
+ ' *__slots__* (which should only contain names of any '
+ '*additional*\n'
+ ' slots).\n'
+ '\n'
+ '* If a class defines a slot also defined in a base class, '
+ 'the instance\n'
+ ' variable defined by the base class slot is inaccessible '
+ '(except by\n'
+ ' retrieving its descriptor directly from the base class). '
+ 'This\n'
+ ' renders the meaning of the program undefined. In the '
+ 'future, a\n'
+ ' check may be added to prevent this.\n'
+ '\n'
+ '* "TypeError" will be raised if nonempty *__slots__* are '
+ 'defined for a\n'
+ ' class derived from a ""variable-length" built-in type" '
+ 'such as\n'
+ ' "int", "bytes", and "tuple".\n'
+ '\n'
+ '* Any non-string *iterable* may be assigned to *__slots__*.\n'
+ '\n'
+ '* If a "dictionary" is used to assign *__slots__*, the '
+ 'dictionary keys\n'
+ ' will be used as the slot names. The values of the '
+ 'dictionary can be\n'
+ ' used to provide per-attribute docstrings that will be '
+ 'recognised by\n'
+ ' "inspect.getdoc()" and displayed in the output of '
+ '"help()".\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'
+ '* If an *iterator* is used for *__slots__* then a '
+ '*descriptor* is\n'
+ ' created for each of the iterator’s values. However, the '
+ '*__slots__*\n'
+ ' attribute will be an empty iterator.\n'
+ '\n'
+ '\n'
+ 'Customizing class creation\n'
+ '==========================\n'
+ '\n'
+ 'Whenever a class inherits from another class, '
+ '"__init_subclass__()" is\n'
+ 'called on the parent class. This way, it is possible to '
+ 'write classes\n'
+ 'which change the behavior of subclasses. This is closely '
+ 'related to\n'
+ 'class decorators, but where class decorators only affect the '
+ 'specific\n'
+ 'class 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 class’s "__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:\n'
+ '\n'
+ ' The metaclass hint "metaclass" is consumed by the rest '
+ 'of the\n'
+ ' 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'
+ ' Added in version 3.6.\n'
+ '\n'
+ 'When a class is created, "type.__new__()" scans the class '
+ 'variables\n'
+ 'and makes callbacks to those with a "__set_name__()" hook.\n'
+ '\n'
+ 'object.__set_name__(self, owner, name)\n'
+ '\n'
+ ' Automatically called at the time the owning class *owner* '
+ 'is\n'
+ ' created. The object has been assigned to *name* in that '
+ 'class:\n'
+ '\n'
+ ' class A:\n'
+ ' x = C() # Automatically calls: x.__set_name__(A, '
+ "'x')\n"
+ '\n'
+ ' If the class variable is assigned after the class is '
+ 'created,\n'
+ ' "__set_name__()" will not be called automatically. If '
+ 'needed,\n'
+ ' "__set_name__()" can be called directly:\n'
+ '\n'
+ ' class A:\n'
+ ' pass\n'
+ '\n'
+ ' c = C()\n'
+ ' A.x = c # The hook is not called\n'
+ " c.__set_name__(A, 'x') # Manually invoke the hook\n"
+ '\n'
+ ' See Creating the class object for more details.\n'
+ '\n'
+ ' Added 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'
+ '* MRO entries are resolved;\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'
+ 'Resolving MRO entries\n'
+ '---------------------\n'
+ '\n'
+ 'object.__mro_entries__(self, bases)\n'
+ '\n'
+ ' If a base that appears in a class definition is not an '
+ 'instance of\n'
+ ' "type", then an "__mro_entries__()" method is searched on '
+ 'the base.\n'
+ ' If an "__mro_entries__()" method is found, the base is '
+ 'substituted\n'
+ ' with the result of a call to "__mro_entries__()" when '
+ 'creating the\n'
+ ' class. The method is called with the original bases tuple '
+ 'passed to\n'
+ ' the *bases* parameter, and must return a tuple of classes '
+ 'that will\n'
+ ' be used instead of the base. The returned tuple may be '
+ 'empty: in\n'
+ ' these cases, the original base is ignored.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' "types.resolve_bases()"\n'
+ ' Dynamically resolve bases that are not instances of '
+ '"type".\n'
+ '\n'
+ ' "types.get_original_bases()"\n'
+ ' Retrieve a class’s “original bases” prior to '
+ 'modifications by\n'
+ ' "__mro_entries__()".\n'
+ '\n'
+ ' **PEP 560**\n'
+ ' Core support for typing module and generic types.\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). The "__prepare__" method should be '
+ 'implemented\n'
+ 'as a "classmethod". The namespace returned by "__prepare__" '
+ 'is passed\n'
+ 'in to "__new__", but when the final class object is created '
+ 'the\n'
+ 'namespace is copied into a new "dict".\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 "RuntimeError" '
+ 'in Python\n'
+ '3.8.\n'
+ '\n'
+ 'When using the default metaclass "type", or any metaclass '
+ 'that\n'
+ 'ultimately calls "type.__new__", the following additional\n'
+ 'customization steps are invoked after creating the class '
+ 'object:\n'
+ '\n'
+ '1. The "type.__new__" method collects all of the attributes '
+ 'in the\n'
+ ' class namespace that define a "__set_name__()" method;\n'
+ '\n'
+ '2. Those "__set_name__" methods are called with the class '
+ 'being\n'
+ ' defined and the assigned name of that particular '
+ 'attribute;\n'
+ '\n'
+ '3. The "__init_subclass__()" hook is called on the immediate '
+ 'parent of\n'
+ ' 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'
+ 'type.__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'
+ 'type.__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 generic types\n'
+ '=======================\n'
+ '\n'
+ 'When using *type annotations*, it is often useful to '
+ '*parameterize* a\n'
+ '*generic type* using Python’s square-brackets notation. For '
+ 'example,\n'
+ 'the annotation "list[int]" might be used to signify a "list" '
+ 'in which\n'
+ 'all the elements are of type "int".\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 484** - Type Hints\n'
+ ' Introducing Python’s framework for type annotations\n'
+ '\n'
+ ' Generic Alias Types\n'
+ ' Documentation for objects representing parameterized '
+ 'generic\n'
+ ' classes\n'
+ '\n'
+ ' Generics, user-defined generics and "typing.Generic"\n'
+ ' Documentation on how to implement generic classes that '
+ 'can be\n'
+ ' parameterized at runtime and understood by static '
+ 'type-checkers.\n'
+ '\n'
+ 'A class can *generally* only be parameterized if it defines '
+ 'the\n'
+ 'special class method "__class_getitem__()".\n'
+ '\n'
+ 'classmethod object.__class_getitem__(cls, key)\n'
+ '\n'
+ ' Return an object representing the specialization of a '
+ 'generic class\n'
+ ' by type arguments found in *key*.\n'
+ '\n'
+ ' When defined on a class, "__class_getitem__()" is '
+ 'automatically a\n'
+ ' class method. As such, there is no need for it to be '
+ 'decorated with\n'
+ ' "@classmethod" when it is defined.\n'
+ '\n'
+ '\n'
+ 'The purpose of *__class_getitem__*\n'
+ '----------------------------------\n'
+ '\n'
+ 'The purpose of "__class_getitem__()" is to allow runtime\n'
+ 'parameterization of standard-library generic classes in '
+ 'order to more\n'
+ 'easily apply *type hints* to these classes.\n'
+ '\n'
+ 'To implement custom generic classes that can be '
+ 'parameterized at\n'
+ 'runtime and understood by static type-checkers, users should '
+ 'either\n'
+ 'inherit from a standard library class that already '
+ 'implements\n'
+ '"__class_getitem__()", or inherit from "typing.Generic", '
+ 'which has its\n'
+ 'own implementation of "__class_getitem__()".\n'
+ '\n'
+ 'Custom implementations of "__class_getitem__()" on classes '
+ 'defined\n'
+ 'outside of the standard library may not be understood by '
+ 'third-party\n'
+ 'type-checkers such as mypy. Using "__class_getitem__()" on '
+ 'any class\n'
+ 'for purposes other than type hinting is discouraged.\n'
+ '\n'
+ '\n'
+ '*__class_getitem__* versus *__getitem__*\n'
+ '----------------------------------------\n'
+ '\n'
+ 'Usually, the subscription of an object using square brackets '
+ 'will call\n'
+ 'the "__getitem__()" instance method defined on the object’s '
+ 'class.\n'
+ 'However, if the object being subscribed is itself a class, '
+ 'the class\n'
+ 'method "__class_getitem__()" may be called instead.\n'
+ '"__class_getitem__()" should return a GenericAlias object if '
+ 'it is\n'
+ 'properly defined.\n'
+ '\n'
+ 'Presented with the *expression* "obj[x]", the Python '
+ 'interpreter\n'
+ 'follows something like the following process to decide '
+ 'whether\n'
+ '"__getitem__()" or "__class_getitem__()" should be called:\n'
+ '\n'
+ ' from inspect import isclass\n'
+ '\n'
+ ' def subscribe(obj, x):\n'
+ ' """Return the result of the expression \'obj[x]\'"""\n'
+ '\n'
+ ' class_of_obj = type(obj)\n'
+ '\n'
+ ' # If the class of obj defines __getitem__,\n'
+ ' # call class_of_obj.__getitem__(obj, x)\n'
+ " if hasattr(class_of_obj, '__getitem__'):\n"
+ ' return class_of_obj.__getitem__(obj, x)\n'
+ '\n'
+ ' # Else, if obj is a class and defines '
+ '__class_getitem__,\n'
+ ' # call obj.__class_getitem__(x)\n'
+ ' elif isclass(obj) and hasattr(obj, '
+ "'__class_getitem__'):\n"
+ ' return obj.__class_getitem__(x)\n'
+ '\n'
+ ' # Else, raise an exception\n'
+ ' else:\n'
+ ' raise TypeError(\n'
+ ' f"\'{class_of_obj.__name__}\' object is not '
+ 'subscriptable"\n'
+ ' )\n'
+ '\n'
+ 'In Python, all classes are themselves instances of other '
+ 'classes. The\n'
+ 'class of a class is known as that class’s *metaclass*, and '
+ 'most\n'
+ 'classes have the "type" class as their metaclass. "type" '
+ 'does not\n'
+ 'define "__getitem__()", meaning that expressions such as '
+ '"list[int]",\n'
+ '"dict[str, float]" and "tuple[str, bytes]" all result in\n'
+ '"__class_getitem__()" being called:\n'
+ '\n'
+ ' >>> # list has class "type" as its metaclass, like most '
+ 'classes:\n'
+ ' >>> type(list)\n'
+ " <class 'type'>\n"
+ ' >>> type(dict) == type(list) == type(tuple) == type(str) '
+ '== type(bytes)\n'
+ ' True\n'
+ ' >>> # "list[int]" calls "list.__class_getitem__(int)"\n'
+ ' >>> list[int]\n'
+ ' list[int]\n'
+ ' >>> # list.__class_getitem__ returns a GenericAlias '
+ 'object:\n'
+ ' >>> type(list[int])\n'
+ " <class 'types.GenericAlias'>\n"
+ '\n'
+ 'However, if a class has a custom metaclass that defines\n'
+ '"__getitem__()", subscribing the class may result in '
+ 'different\n'
+ 'behaviour. An example of this can be found in the "enum" '
+ 'module:\n'
+ '\n'
+ ' >>> from enum import Enum\n'
+ ' >>> class Menu(Enum):\n'
+ ' ... """A breakfast menu"""\n'
+ " ... SPAM = 'spam'\n"
+ " ... BACON = 'bacon'\n"
+ ' ...\n'
+ ' >>> # Enum classes have a custom metaclass:\n'
+ ' >>> type(Menu)\n'
+ " <class 'enum.EnumMeta'>\n"
+ ' >>> # EnumMeta defines __getitem__,\n'
+ ' >>> # so __class_getitem__ is not called,\n'
+ ' >>> # and the result is not a GenericAlias object:\n'
+ " >>> Menu['SPAM']\n"
+ " <Menu.SPAM: 'spam'>\n"
+ " >>> type(Menu['SPAM'])\n"
+ " <enum 'Menu'>\n"
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 560** - Core Support for typing module and generic '
+ 'types\n'
+ ' Introducing "__class_getitem__()", and outlining when '
+ 'a\n'
+ ' subscription results in "__class_getitem__()" being '
+ 'called\n'
+ ' instead of "__getitem__()"\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, ...)" roughly translates to\n'
+ ' "type(x).__call__(x, arg1, ...)". The "object" class '
+ 'itself does\n'
+ ' not provide this method.\n'
+ '\n'
+ '\n'
+ 'Emulating container types\n'
+ '=========================\n'
+ '\n'
+ 'The following methods can be defined to implement container '
+ 'objects.\n'
+ 'None of them are provided by the "object" class itself. '
+ 'Containers\n'
+ 'usually are *sequences* (such as "lists" or "tuples") or '
+ '*mappings*\n'
+ '(like *dictionaries*), but can represent other containers as '
+ 'well.\n'
+ 'The 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.abc" module provides a "MutableMapping" '
+ '*abstract\n'
+ 'base class* to help create those methods from a base set of\n'
+ '"__getitem__()", "__setitem__()", "__delitem__()", and '
+ '"keys()".\n'
+ 'Mutable sequences should provide methods "append()", '
+ '"count()",\n'
+ '"index()", "extend()", "insert()", "pop()", "remove()", '
+ '"reverse()"\n'
+ 'and "sort()", like Python standard "list" objects. Finally, '
+ 'sequence\n'
+ 'types should implement addition (meaning concatenation) and\n'
+ 'multiplication (meaning repetition) by defining the methods\n'
+ '"__add__()", "__radd__()", "__iadd__()", "__mul__()", '
+ '"__rmul__()" and\n'
+ '"__imul__()" described below; they should not define other '
+ 'numerical\n'
+ 'operators. It is recommended that both mappings and '
+ 'sequences\n'
+ 'implement the "__contains__()" method to allow efficient use '
+ 'of the\n'
+ '"in" operator; for mappings, "in" should search the '
+ 'mapping’s keys;\n'
+ 'for sequences, it should search through the values. It is '
+ 'further\n'
+ 'recommended that both mappings and sequences implement the\n'
+ '"__iter__()" method to allow efficient iteration through '
+ 'the\n'
+ 'container; for mappings, "__iter__()" should iterate through '
+ 'the\n'
+ 'object’s keys; for sequences, it should iterate 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. '
+ 'The\n'
+ ' return value may also be "NotImplemented", which is '
+ 'treated the\n'
+ ' same as if the "__length_hint__" method didn’t exist at '
+ 'all. This\n'
+ ' method is purely an optimization and is never required '
+ 'for\n'
+ ' correctness.\n'
+ '\n'
+ ' Added in version 3.4.\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' Slicing is done exclusively with the following three '
+ 'methods. A\n'
+ ' 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*\n'
+ ' types, the accepted keys should be integers. Optionally, '
+ 'they may\n'
+ ' support "slice" objects as well. Negative index support '
+ 'is also\n'
+ ' optional. If *key* is of an inappropriate type, '
+ '"TypeError" may be\n'
+ ' raised; if *key* is a value outside the set of indexes '
+ 'for the\n'
+ ' sequence (after any special interpretation of negative '
+ 'values),\n'
+ ' "IndexError" should be raised. For *mapping* types, if '
+ '*key* is\n'
+ ' missing (not in the container), "KeyError" should be '
+ 'raised.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' "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'
+ ' Note:\n'
+ '\n'
+ ' When subscripting a *class*, the special class method\n'
+ ' "__class_getitem__()" may be called instead of '
+ '"__getitem__()".\n'
+ ' See __class_getitem__ versus __getitem__ for more '
+ 'details.\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\n'
+ ' container. This method should return a new iterator '
+ 'object that can\n'
+ ' iterate over all the objects in the container. For '
+ 'mappings, it\n'
+ ' should iterate over the keys of the container.\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 container. However, '
+ 'container\n'
+ 'objects can supply the following special method with a more '
+ 'efficient\n'
+ 'implementation, which also does not require the object be '
+ 'iterable.\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, "type(x).__add__(x, '
+ 'y)" is\n'
+ ' called. The "__divmod__()" method should be the '
+ 'equivalent to\n'
+ ' using "__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[, modulo])\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 '
+ 'operands are of\n'
+ ' different types, when the left operand does not support '
+ 'the\n'
+ ' corresponding operation [3], or the right operand’s class '
+ 'is\n'
+ ' derived from the left operand’s class. [4] For instance, '
+ 'to\n'
+ ' evaluate the expression "x - y", where *y* is an instance '
+ 'of a\n'
+ ' class that has an "__rsub__()" method, '
+ '"type(y).__rsub__(y, x)" is\n'
+ ' called if "type(x).__sub__(x, y)" returns '
+ '"NotImplemented" or\n'
+ ' "type(y)" is a subclass of "type(x)". [5]\n'
+ '\n'
+ ' Note that ternary "pow()" will not try calling '
+ '"__rpow__()" (the\n'
+ ' coercion rules would become too complicated).\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' If the right operand’s type is a subclass of the left '
+ 'operand’s\n'
+ ' type and that subclass provides a different '
+ 'implementation of the\n'
+ ' reflected method for the operation, this method will be '
+ 'called\n'
+ ' before the left operand’s non-reflected method. This '
+ 'behavior\n'
+ ' allows subclasses 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, or if that method returns '
+ '"NotImplemented",\n'
+ ' the augmented assignment falls back to the normal '
+ 'methods. For\n'
+ ' instance, if *x* is an instance of a class with an '
+ '"__iadd__()"\n'
+ ' method, "x += y" is equivalent to "x = x.__iadd__(y)" . '
+ 'If\n'
+ ' "__iadd__()" does not exist, or if "x.__iadd__(y)" '
+ 'returns\n'
+ ' "NotImplemented", "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'
+ ' If "__int__()", "__float__()" and "__complex__()" are not '
+ 'defined\n'
+ ' then corresponding built-in functions "int()", "float()" '
+ 'and\n'
+ ' "complex()" fall back to "__index__()".\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'
+ ' Changed in version 3.14: "int()" no longer delegates to '
+ 'the\n'
+ ' "__trunc__()" method.\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'
+ 'The "object" class itself does not provide the context '
+ 'manager\n'
+ 'methods.\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'
+ 'Customizing positional arguments in class pattern matching\n'
+ '==========================================================\n'
+ '\n'
+ 'When using a class name in a pattern, positional arguments '
+ 'in the\n'
+ 'pattern are not allowed by default, i.e. "case MyClass(x, '
+ 'y)" is\n'
+ 'typically invalid without special support in "MyClass". To '
+ 'be able to\n'
+ 'use that kind of pattern, the class needs to define a '
+ '*__match_args__*\n'
+ 'attribute.\n'
+ '\n'
+ 'object.__match_args__\n'
+ '\n'
+ ' This class variable can be assigned a tuple of strings. '
+ 'When this\n'
+ ' class is used in a class pattern with positional '
+ 'arguments, each\n'
+ ' positional argument will be converted into a keyword '
+ 'argument,\n'
+ ' using the corresponding value in *__match_args__* as the '
+ 'keyword.\n'
+ ' The absence of this attribute is equivalent to setting it '
+ 'to "()".\n'
+ '\n'
+ 'For example, if "MyClass.__match_args__" is "("left", '
+ '"center",\n'
+ '"right")" that means that "case MyClass(x, y)" is equivalent '
+ 'to "case\n'
+ 'MyClass(left=x, center=y)". Note that the number of '
+ 'arguments in the\n'
+ 'pattern must be smaller than or equal to the number of '
+ 'elements in\n'
+ '*__match_args__*; if it is larger, the pattern match attempt '
+ 'will\n'
+ 'raise a "TypeError".\n'
+ '\n'
+ 'Added in version 3.10.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 634** - Structural Pattern Matching\n'
+ ' The specification for the Python "match" statement.\n'
+ '\n'
+ '\n'
+ 'Emulating buffer types\n'
+ '======================\n'
+ '\n'
+ 'The buffer protocol provides a way for Python objects to '
+ 'expose\n'
+ 'efficient access to a low-level memory array. This protocol '
+ 'is\n'
+ 'implemented by builtin types such as "bytes" and '
+ '"memoryview", and\n'
+ 'third-party libraries may define additional buffer types.\n'
+ '\n'
+ 'While buffer types are usually implemented in C, it is also '
+ 'possible\n'
+ 'to implement the protocol in Python.\n'
+ '\n'
+ 'object.__buffer__(self, flags)\n'
+ '\n'
+ ' Called when a buffer is requested from *self* (for '
+ 'example, by the\n'
+ ' "memoryview" constructor). The *flags* argument is an '
+ 'integer\n'
+ ' representing the kind of buffer requested, affecting for '
+ 'example\n'
+ ' whether the returned buffer is read-only or writable.\n'
+ ' "inspect.BufferFlags" provides a convenient way to '
+ 'interpret the\n'
+ ' flags. The method must return a "memoryview" object.\n'
+ '\n'
+ 'object.__release_buffer__(self, buffer)\n'
+ '\n'
+ ' Called when a buffer is no longer needed. The *buffer* '
+ 'argument is\n'
+ ' a "memoryview" object that was previously returned by\n'
+ ' "__buffer__()". The method must release any resources '
+ 'associated\n'
+ ' with the buffer. This method should return "None". Buffer '
+ 'objects\n'
+ ' that do not need to perform any cleanup are not required '
+ 'to\n'
+ ' implement this method.\n'
+ '\n'
+ 'Added in version 3.12.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 688** - Making the buffer protocol accessible in '
+ 'Python\n'
+ ' Introduces the Python "__buffer__" and '
+ '"__release_buffer__"\n'
+ ' methods.\n'
+ '\n'
+ ' "collections.abc.Buffer"\n'
+ ' ABC for buffer types.\n'
+ '\n'
+ '\n'
+ 'Annotations\n'
+ '===========\n'
+ '\n'
+ 'Functions, classes, and modules may contain *annotations*, '
+ 'which are a\n'
+ 'way to associate information (usually *type hints*) with a '
+ 'symbol.\n'
+ '\n'
+ 'object.__annotations__\n'
+ '\n'
+ ' This attribute contains the annotations for an object. It '
+ 'is lazily\n'
+ ' evaluated, so accessing the attribute may execute '
+ 'arbitrary code\n'
+ ' and raise exceptions. If evaluation is successful, the '
+ 'attribute is\n'
+ ' set to a dictionary mapping from variable names to '
+ 'annotations.\n'
+ '\n'
+ ' Changed in version 3.14: Annotations are now lazily '
+ 'evaluated.\n'
+ '\n'
+ 'object.__annotate__(format)\n'
+ '\n'
+ ' An *annotate function*. Returns a new dictionary object '
+ 'mapping\n'
+ ' attribute/parameter names to their annotation values.\n'
+ '\n'
+ ' Takes a format parameter specifying the format in which '
+ 'annotations\n'
+ ' values should be provided. It must be a member of the\n'
+ ' "annotationlib.Format" enum, or an integer with a value\n'
+ ' corresponding to a member of the enum.\n'
+ '\n'
+ ' If an annotate function doesn’t support the requested '
+ 'format, it\n'
+ ' must raise "NotImplementedError". Annotate functions must '
+ 'always\n'
+ ' support "VALUE" format; they must not raise '
+ '"NotImplementedError()"\n'
+ ' when called with this format.\n'
+ '\n'
+ ' When called with "VALUE" format, an annotate function '
+ 'may raise\n'
+ ' "NameError"; it must not raise "NameError" when called '
+ 'requesting\n'
+ ' any other format.\n'
+ '\n'
+ ' If an object does not have any annotations, '
+ '"__annotate__" should\n'
+ ' preferably be set to "None" (it can’t be deleted), rather '
+ 'than set\n'
+ ' to a function that returns an empty dict.\n'
+ '\n'
+ ' Added in version 3.14.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' **PEP 649** — Deferred evaluation of annotation using '
+ 'descriptors\n'
+ ' Introduces lazy evaluation of annotations and the '
+ '"__annotate__"\n'
+ ' function.\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'
+ ' Changed in version 3.8: The first character is now put '
+ 'into\n'
+ ' titlecase rather than uppercase. This means that '
+ 'characters like\n'
+ ' digraphs will only have their first letter capitalized, '
+ 'instead of\n'
+ ' the full character.\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 '
+ '‘Default\n'
+ ' Case Folding’ of the Unicode Standard.\n'
+ '\n'
+ ' Added 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'
+ ' If *sub* is empty, returns the number of empty strings '
+ 'between\n'
+ ' characters which is the length of the string plus one.\n'
+ '\n'
+ "str.encode(encoding='utf-8', errors='strict')\n"
+ '\n'
+ ' Return the string encoded to "bytes".\n'
+ '\n'
+ ' *encoding* defaults to "\'utf-8\'"; see Standard '
+ 'Encodings for\n'
+ ' possible values.\n'
+ '\n'
+ ' *errors* controls how encoding errors are handled. If '
+ '"\'strict\'"\n'
+ ' (the default), a "UnicodeError" exception is raised. '
+ 'Other possible\n'
+ ' values are "\'ignore\'", "\'replace\'", '
+ '"\'xmlcharrefreplace\'",\n'
+ ' "\'backslashreplace\'" and any other name registered '
+ 'via\n'
+ ' "codecs.register_error()". See Error Handlers for '
+ 'details.\n'
+ '\n'
+ ' For performance reasons, the value of *errors* is not '
+ 'checked for\n'
+ ' validity unless an encoding error actually occurs, '
+ 'Python\n'
+ ' Development Mode is enabled or a debug build is used.\n'
+ '\n'
+ ' Changed in version 3.1: Added support for keyword '
+ 'arguments.\n'
+ '\n'
+ ' Changed in version 3.9: The value of the *errors* '
+ 'argument is now\n'
+ ' checked in Python Development Mode and in debug mode.\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:\n'
+ '\n'
+ ' The "find()" method should be used only if you need '
+ 'to know the\n'
+ ' position of *sub*. To check if *sub* is a substring '
+ 'or not, use\n'
+ ' 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:\n'
+ '\n'
+ ' 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.7: When formatting a number with '
+ 'the "n" type,\n'
+ ' 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'
+ ' Added 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\n'
+ ' "c" 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 '
+ 'section 4.10\n'
+ ' ‘Letters, Alphabetic, and Ideographic’ of the Unicode '
+ 'Standard.\n'
+ '\n'
+ 'str.isascii()\n'
+ '\n'
+ ' Return "True" if the string is empty or all characters '
+ 'in the\n'
+ ' string are ASCII, "False" otherwise. ASCII characters '
+ 'have code\n'
+ ' points in the range U+0000-U+007F.\n'
+ '\n'
+ ' Added in version 3.7.\n'
+ '\n'
+ 'str.isdecimal()\n'
+ '\n'
+ ' Return "True" if all characters in the string are '
+ 'decimal\n'
+ ' characters and there is at least one character, "False" '
+ 'otherwise.\n'
+ ' Decimal characters are those that can be used to form '
+ 'numbers in\n'
+ ' base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. '
+ 'Formally a decimal\n'
+ ' character 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\n'
+ ' is at least one character, "False" otherwise. Digits '
+ 'include\n'
+ ' decimal characters and digits that need special '
+ 'handling, such as\n'
+ ' the compatibility superscript digits. This covers '
+ 'digits which\n'
+ ' cannot be used to form numbers in base 10, like the '
+ 'Kharosthi\n'
+ ' numbers. Formally, a digit is a character that has the '
+ 'property\n'
+ ' value 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'
+ ' "keyword.iskeyword()" can be used to test whether '
+ 'string "s" is a\n'
+ ' reserved identifier, such as "def" and "class".\n'
+ '\n'
+ ' Example:\n'
+ '\n'
+ ' >>> from keyword import iskeyword\n'
+ '\n'
+ " >>> 'hello'.isidentifier(), iskeyword('hello')\n"
+ ' (True, False)\n'
+ " >>> 'def'.isidentifier(), iskeyword('def')\n"
+ ' (True, True)\n'
+ '\n'
+ 'str.islower()\n'
+ '\n'
+ ' Return "True" if all cased characters [4] in the string '
+ 'are\n'
+ ' lowercase and there is at least one cased character, '
+ '"False"\n'
+ ' otherwise.\n'
+ '\n'
+ 'str.isnumeric()\n'
+ '\n'
+ ' Return "True" if all characters in the string are '
+ 'numeric\n'
+ ' characters, and there is at least one character, '
+ '"False" otherwise.\n'
+ ' Numeric characters include digit characters, and all '
+ 'characters\n'
+ ' that have the Unicode numeric value property, e.g. '
+ 'U+2155, VULGAR\n'
+ ' FRACTION ONE FIFTH. Formally, numeric characters are '
+ 'those with\n'
+ ' the 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, false if\n'
+ ' it contains at least one non-printable character.\n'
+ '\n'
+ ' Here “printable” means the character is suitable for '
+ '"repr()" to\n'
+ ' use in its output; “non-printable” means that "repr()" '
+ 'on built-in\n'
+ ' types will hex-escape the character. It has no bearing '
+ 'on the\n'
+ ' handling of strings written to "sys.stdout" or '
+ '"sys.stderr".\n'
+ '\n'
+ ' The printable characters are those which in the Unicode '
+ 'character\n'
+ ' database (see "unicodedata") have a general category in '
+ 'group\n'
+ ' Letter, Mark, Number, Punctuation, or Symbol (L, M, N, '
+ 'P, or S);\n'
+ ' plus the ASCII space 0x20. Nonprintable characters are '
+ 'those in\n'
+ ' group Separator or Other (Z or C), except the ASCII '
+ 'space.\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.\n'
+ '\n'
+ ' A character is *whitespace* if in the Unicode character '
+ 'database\n'
+ ' (see "unicodedata"), either its general category is '
+ '"Zs"\n'
+ ' (“Separator, space”), or its bidirectional class is one '
+ 'of "WS",\n'
+ ' "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\n'
+ ' uppercase and there is at least one cased character, '
+ '"False"\n'
+ ' otherwise.\n'
+ '\n'
+ " >>> 'BANANA'.isupper()\n"
+ ' True\n'
+ " >>> 'banana'.isupper()\n"
+ ' False\n'
+ " >>> 'baNana'.isupper()\n"
+ ' False\n'
+ " >>> ' '.isupper()\n"
+ ' False\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\n'
+ ' ‘Default Case Folding’ of the 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'
+ ' See "str.removeprefix()" for a method that will remove '
+ 'a single\n'
+ ' prefix string rather than all of a set of characters. '
+ 'For example:\n'
+ '\n'
+ " >>> 'Arthur: three!'.lstrip('Arthur: ')\n"
+ " 'ee!'\n"
+ " >>> 'Arthur: three!'.removeprefix('Arthur: ')\n"
+ " 'three!'\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.removeprefix(prefix, /)\n'
+ '\n'
+ ' If the string starts with the *prefix* string, return\n'
+ ' "string[len(prefix):]". Otherwise, return a copy of the '
+ 'original\n'
+ ' string:\n'
+ '\n'
+ " >>> 'TestHook'.removeprefix('Test')\n"
+ " 'Hook'\n"
+ " >>> 'BaseTestCase'.removeprefix('Test')\n"
+ " 'BaseTestCase'\n"
+ '\n'
+ ' Added in version 3.9.\n'
+ '\n'
+ 'str.removesuffix(suffix, /)\n'
+ '\n'
+ ' If the string ends with the *suffix* string and that '
+ '*suffix* is\n'
+ ' not empty, return "string[:-len(suffix)]". Otherwise, '
+ 'return a copy\n'
+ ' of the original string:\n'
+ '\n'
+ " >>> 'MiscTests'.removesuffix('Tests')\n"
+ " 'Misc'\n"
+ " >>> 'TmpDirMixin'.removesuffix('Tests')\n"
+ " 'TmpDirMixin'\n"
+ '\n'
+ ' Added in version 3.9.\n'
+ '\n'
+ 'str.replace(old, new, count=-1)\n'
+ '\n'
+ ' Return a copy of the string with all occurrences of '
+ 'substring *old*\n'
+ ' replaced by *new*. If *count* is given, only the first '
+ '*count*\n'
+ ' occurrences are replaced. If *count* is not specified '
+ 'or "-1", then\n'
+ ' all occurrences are replaced.\n'
+ '\n'
+ ' Changed in version 3.13: *count* is now supported as a '
+ 'keyword\n'
+ ' argument.\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'
+ ' See "str.removesuffix()" for a method that will remove '
+ 'a single\n'
+ ' suffix string rather than all of a set of characters. '
+ 'For example:\n'
+ '\n'
+ " >>> 'Monty Python'.rstrip(' Python')\n"
+ " 'M'\n"
+ " >>> 'Monty Python'.removesuffix(' Python')\n"
+ " 'Monty'\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 as a single '
+ 'delimiter (to split\n'
+ ' with multiple delimiters, use "re.split()"). Splitting '
+ 'an empty\n'
+ ' 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"
+ " >>> '1<>2<>3<4'.split('<>')\n"
+ " ['1', '2', '3<4']\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=False)\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'
+ ' The "string.capwords()" function does not have this '
+ 'problem, as it\n'
+ ' splits words on spaces only.\n'
+ '\n'
+ ' Alternatively, a workaround for apostrophes can be '
+ 'constructed\n'
+ ' using regular 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).capitalize(),\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\n'
+ ' ‘Default Case Folding’ of the 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 give special meaning to otherwise ordinary\n'
+ 'characters like "n", which means ‘newline’ when escaped ("\\n"). '
+ 'It can\n'
+ 'also be used to escape characters that otherwise have a special\n'
+ 'meaning, such as newline, backslash itself, or the quote '
+ 'character.\n'
+ 'See escape sequences below for examples.\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 constructs are called *raw '
+ 'string\n'
+ 'literals* and *raw bytes literals* respectively and treat '
+ 'backslashes\n'
+ 'as literal characters. As a result, in raw string literals, '
+ '"\'\\U\'"\n'
+ 'and "\'\\u\'" escapes are not treated specially.\n'
+ '\n'
+ 'Added in version 3.3: The "\'rb\'" prefix of raw bytes literals '
+ 'has been\n'
+ 'added as a synonym of "\'br\'".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 f-strings. The "\'f\'" may be combined with '
+ '"\'r\'",\n'
+ 'but not with "\'b\'" or "\'u\'", therefore raw formatted strings '
+ 'are\n'
+ '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'
+ '\n'
+ 'Escape sequences\n'
+ '================\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 '
+ '| (1) |\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* '
+ '| (2,4) |\n'
+ '+---------------------------+-----------------------------------+---------+\n'
+ '| "\\x*hh*" | Character with hex value *hh* '
+ '| (3,4) |\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 '
+ '| (5) |\n'
+ '| | Unicode database '
+ '| |\n'
+ '+---------------------------+-----------------------------------+---------+\n'
+ '| "\\u*xxxx*" | Character with 16-bit hex value '
+ '| (6) |\n'
+ '| | *xxxx* '
+ '| |\n'
+ '+---------------------------+-----------------------------------+---------+\n'
+ '| "\\U*xxxxxxxx*" | Character with 32-bit hex value '
+ '| (7) |\n'
+ '| | *xxxxxxxx* '
+ '| |\n'
+ '+---------------------------+-----------------------------------+---------+\n'
+ '\n'
+ 'Notes:\n'
+ '\n'
+ '1. A backslash can be added at the end of a line to ignore the\n'
+ ' newline:\n'
+ '\n'
+ " >>> 'This string will not include \\\n"
+ " ... backslashes or newline characters.'\n"
+ " 'This string will not include backslashes or newline "
+ "characters.'\n"
+ '\n'
+ ' The same result can be achieved using triple-quoted strings, '
+ 'or\n'
+ ' parentheses and string literal concatenation.\n'
+ '\n'
+ '2. As in Standard C, up to three octal digits are accepted.\n'
+ '\n'
+ ' Changed in version 3.11: Octal escapes with value larger than\n'
+ ' "0o377" produce a "DeprecationWarning".\n'
+ '\n'
+ ' Changed in version 3.12: Octal escapes with value larger than\n'
+ ' "0o377" produce a "SyntaxWarning". In a future Python version '
+ 'they\n'
+ ' will be eventually a "SyntaxError".\n'
+ '\n'
+ '3. Unlike in Standard C, exactly two hex digits are required.\n'
+ '\n'
+ '4. In a bytes literal, hexadecimal and octal escapes denote the '
+ 'byte\n'
+ ' with the given value. In a string literal, these escapes '
+ 'denote a\n'
+ ' Unicode character with the given value.\n'
+ '\n'
+ '5. Changed in version 3.3: Support for name aliases [1] has been\n'
+ ' added.\n'
+ '\n'
+ '6. Exactly four hex digits are required.\n'
+ '\n'
+ '7. Any Unicode character can be encoded this way. Exactly eight '
+ 'hex\n'
+ ' 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".\n'
+ '\n'
+ 'Changed in version 3.12: Unrecognized escape sequences produce a\n'
+ '"SyntaxWarning". In a future Python version they will be '
+ 'eventually a\n'
+ '"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'
+ 'The subscription of an instance of a container class will '
+ 'generally\n'
+ 'select an element from the container. The subscription of a '
+ '*generic\n'
+ 'class* will generally return a GenericAlias object.\n'
+ '\n'
+ ' **subscription**: "primary" "[" '
+ '"flexible_expression_list" "]"\n'
+ '\n'
+ 'When an object is subscripted, the interpreter will '
+ 'evaluate the\n'
+ 'primary and the expression list.\n'
+ '\n'
+ 'The primary must evaluate to an object that supports '
+ 'subscription. An\n'
+ 'object may support subscription through defining one or '
+ 'both of\n'
+ '"__getitem__()" and "__class_getitem__()". When the primary '
+ 'is\n'
+ 'subscripted, the evaluated result of the expression list '
+ 'will be\n'
+ 'passed to one of these methods. For more details on when\n'
+ '"__class_getitem__" is called instead of "__getitem__", '
+ 'see\n'
+ '__class_getitem__ versus __getitem__.\n'
+ '\n'
+ 'If the expression list contains at least one comma, or if '
+ 'any of the\n'
+ 'expressions are starred, the expression list will evaluate '
+ 'to a\n'
+ '"tuple" containing the items of the expression list. '
+ 'Otherwise, the\n'
+ 'expression list will evaluate to the value of the list’s '
+ 'sole member.\n'
+ '\n'
+ 'Changed in version 3.11: Expressions in an expression list '
+ 'may be\n'
+ 'starred. See **PEP 646**.\n'
+ '\n'
+ 'For built-in objects, there are two types of objects that '
+ 'support\n'
+ 'subscription via "__getitem__()":\n'
+ '\n'
+ '1. Mappings. If the primary is a *mapping*, the expression '
+ 'list must\n'
+ ' evaluate to an object whose value is one of the keys of '
+ 'the\n'
+ ' mapping, and the subscription selects the value in the '
+ 'mapping that\n'
+ ' corresponds to that key. An example of a builtin mapping '
+ 'class is\n'
+ ' the "dict" class.\n'
+ '\n'
+ '2. Sequences. If the primary is a *sequence*, the '
+ 'expression list must\n'
+ ' evaluate to an "int" or a "slice" (as discussed in the '
+ 'following\n'
+ ' section). Examples of builtin sequence classes include '
+ 'the "str",\n'
+ ' "list" and "tuple" classes.\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, for example, "x[-1]" selects '
+ 'the last\n'
+ 'item of "x". The resulting value must be a nonnegative '
+ 'integer less\n'
+ 'than the number of items in the sequence, and the '
+ 'subscription selects\n'
+ 'the item whose index is that value (counting from zero). '
+ 'Since the\n'
+ 'support for negative indices and slicing occurs in the '
+ 'object’s\n'
+ '"__getitem__()" method, subclasses overriding this method '
+ 'will need to\n'
+ 'explicitly add that support.\n'
+ '\n'
+ 'A "string" is a special kind of sequence whose items are '
+ '*characters*.\n'
+ 'A character is not a separate data type but a string of '
+ 'exactly one\n'
+ '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" | "try3_stmt"\n'
+ ' **try1_stmt**: "try" ":" "suite"\n'
+ ' ("except" ["expression" ["as" "identifier"]] ":" '
+ '"suite")+\n'
+ ' ["else" ":" "suite"]\n'
+ ' ["finally" ":" "suite"]\n'
+ ' **try2_stmt**: "try" ":" "suite"\n'
+ ' ("except" "*" "expression" ["as" "identifier"] ":" '
+ '"suite")+\n'
+ ' ["else" ":" "suite"]\n'
+ ' ["finally" ":" "suite"]\n'
+ ' **try3_stmt**: "try" ":" "suite"\n'
+ ' "finally" ":" "suite"\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'
+ '"except" clause\n'
+ '===============\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"\n'
+ 'clauses in turn until one is found that matches the exception. An\n'
+ 'expression-less "except" clause, if present, must be last; it '
+ 'matches\n'
+ 'any exception.\n'
+ '\n'
+ 'For an "except" clause with an expression, the expression must\n'
+ 'evaluate to an exception type or a tuple of exception types. The\n'
+ 'raised exception matches an "except" clause whose expression '
+ 'evaluates\n'
+ 'to the class or a *non-virtual base class* of the exception object, '
+ 'or\n'
+ 'to a tuple that contains such a class.\n'
+ '\n'
+ 'If no "except" clause matches the exception, the search for an\n'
+ 'exception handler continues in the surrounding code and on the\n'
+ 'invocation stack. [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,\n'
+ 'if 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"\n'
+ 'statement. (This means that if two nested handlers exist for the '
+ 'same\n'
+ 'exception, and the exception occurs in the "try" clause of the inner\n'
+ 'handler, the 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, the exception is '
+ 'stored\n'
+ 'in the "sys" module, where it can be accessed from within the body '
+ 'of\n'
+ 'the "except" clause by calling "sys.exception()". When leaving an\n'
+ 'exception handler, the exception stored in the "sys" module is reset\n'
+ 'to its previous value:\n'
+ '\n'
+ ' >>> print(sys.exception())\n'
+ ' None\n'
+ ' >>> try:\n'
+ ' ... raise TypeError\n'
+ ' ... except:\n'
+ ' ... print(repr(sys.exception()))\n'
+ ' ... try:\n'
+ ' ... raise ValueError\n'
+ ' ... except:\n'
+ ' ... print(repr(sys.exception()))\n'
+ ' ... print(repr(sys.exception()))\n'
+ ' ...\n'
+ ' TypeError()\n'
+ ' ValueError()\n'
+ ' TypeError()\n'
+ ' >>> print(sys.exception())\n'
+ ' None\n'
+ '\n'
+ '\n'
+ '"except*" clause\n'
+ '================\n'
+ '\n'
+ 'The "except*" clause(s) are used for handling "ExceptionGroup"s. The\n'
+ 'exception type for matching is interpreted as in the case of '
+ '"except",\n'
+ 'but in the case of exception groups we can have partial matches when\n'
+ 'the type matches some of the exceptions in the group. This means '
+ 'that\n'
+ 'multiple "except*" clauses can execute, each handling part of the\n'
+ 'exception group. Each clause executes at most once and handles an\n'
+ 'exception group of all matching exceptions. Each exception in the\n'
+ 'group is handled by at most one "except*" clause, the first that\n'
+ 'matches it.\n'
+ '\n'
+ ' >>> try:\n'
+ ' ... raise ExceptionGroup("eg",\n'
+ ' ... [ValueError(1), TypeError(2), OSError(3), '
+ 'OSError(4)])\n'
+ ' ... except* TypeError as e:\n'
+ " ... print(f'caught {type(e)} with nested {e.exceptions}')\n"
+ ' ... except* OSError as e:\n'
+ " ... print(f'caught {type(e)} with nested {e.exceptions}')\n"
+ ' ...\n'
+ " caught <class 'ExceptionGroup'> with nested (TypeError(2),)\n"
+ " caught <class 'ExceptionGroup'> with nested (OSError(3), "
+ 'OSError(4))\n'
+ ' + Exception Group Traceback (most recent call last):\n'
+ ' | File "<stdin>", line 2, in <module>\n'
+ ' | ExceptionGroup: eg\n'
+ ' +-+---------------- 1 ----------------\n'
+ ' | ValueError: 1\n'
+ ' +------------------------------------\n'
+ '\n'
+ 'Any remaining exceptions that were not handled by any "except*" '
+ 'clause\n'
+ 'are re-raised at the end, along with all exceptions that were raised\n'
+ 'from within the "except*" clauses. If this list contains more than '
+ 'one\n'
+ 'exception to reraise, they are combined into an exception group.\n'
+ '\n'
+ 'If the raised exception is not an exception group and its type '
+ 'matches\n'
+ 'one of the "except*" clauses, it is caught and wrapped by an '
+ 'exception\n'
+ 'group with an empty message string.\n'
+ '\n'
+ ' >>> try:\n'
+ ' ... raise BlockingIOError\n'
+ ' ... except* BlockingIOError as e:\n'
+ ' ... print(repr(e))\n'
+ ' ...\n'
+ " ExceptionGroup('', (BlockingIOError()))\n"
+ '\n'
+ 'An "except*" clause must have a matching expression; it cannot be\n'
+ '"except*:". Furthermore, this expression cannot contain exception\n'
+ 'group types, because that would have ambiguous semantics.\n'
+ '\n'
+ 'It is not possible to mix "except" and "except*" in the same "try".\n'
+ '"break", "continue" and "return" cannot appear in an "except*" '
+ 'clause.\n'
+ '\n'
+ '\n'
+ '"else" clause\n'
+ '=============\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'
+ '\n'
+ '"finally" clause\n'
+ '================\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", "break" or "continue" statement, the '
+ 'saved\n'
+ 'exception 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.’\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'
+ 'Changed in version 3.8: Prior to Python 3.8, a "continue" statement\n'
+ 'was illegal in the "finally" clause due to a problem with the\n'
+ 'implementation.\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'
+ '\n'
+ 'None\n'
+ '====\n'
+ '\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 '
+ 'is\n'
+ 'used to signify the absence of a value in many situations, e.g., it '
+ 'is\n'
+ 'returned from functions that don’t explicitly return anything. Its\n'
+ 'truth value is false.\n'
+ '\n'
+ '\n'
+ 'NotImplemented\n'
+ '==============\n'
+ '\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 '
+ 'should\n'
+ 'return this value if they do not implement the operation for the\n'
+ 'operands provided. (The interpreter will then try the reflected\n'
+ 'operation, or some other fallback, depending on the operator.) It\n'
+ 'should not be evaluated in a boolean context.\n'
+ '\n'
+ 'See Implementing the arithmetic operations for more details.\n'
+ '\n'
+ 'Changed in version 3.9: Evaluating "NotImplemented" in a boolean\n'
+ 'context was deprecated.\n'
+ '\n'
+ 'Changed in version 3.14: Evaluating "NotImplemented" in a boolean\n'
+ 'context now raises a "TypeError". It previously evaluated to '
+ '"True"\n'
+ 'and emitted a "DeprecationWarning" since Python 3.9.\n'
+ '\n'
+ '\n'
+ 'Ellipsis\n'
+ '========\n'
+ '\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 '
+ 'built-\n'
+ 'in name "Ellipsis". Its truth value is true.\n'
+ '\n'
+ '\n'
+ '"numbers.Number"\n'
+ '================\n'
+ '\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. '
+ 'Python\n'
+ 'numbers are of course strongly related to mathematical numbers, '
+ 'but\n'
+ 'subject to the limitations of numerical representation in '
+ 'computers.\n'
+ '\n'
+ 'The string representations of the numeric classes, computed by\n'
+ '"__repr__()" and "__str__()", have the following properties:\n'
+ '\n'
+ '* They are valid numeric literals which, when passed to their '
+ 'class\n'
+ ' constructor, produce an object having the value of the original\n'
+ ' numeric.\n'
+ '\n'
+ '* The representation is in base 10, when possible.\n'
+ '\n'
+ '* Leading zeros, possibly excepting a single zero before a decimal\n'
+ ' point, are not shown.\n'
+ '\n'
+ '* Trailing zeros, possibly excepting a single zero after a decimal\n'
+ ' point, are not shown.\n'
+ '\n'
+ '* A sign is shown only when the number is negative.\n'
+ '\n'
+ 'Python distinguishes between integers, floating-point numbers, and\n'
+ 'complex numbers:\n'
+ '\n'
+ '\n'
+ '"numbers.Integral"\n'
+ '------------------\n'
+ '\n'
+ 'These represent elements from the mathematical set of integers\n'
+ '(positive and negative).\n'
+ '\n'
+ 'Note:\n'
+ '\n'
+ ' The rules for integer representation are intended to give the '
+ 'most\n'
+ ' meaningful interpretation of shift and mask operations involving\n'
+ ' negative integers.\n'
+ '\n'
+ 'There are two types of integers:\n'
+ '\n'
+ 'Integers ("int")\n'
+ ' These represent numbers in an unlimited range, subject to '
+ 'available\n'
+ ' (virtual) memory only. For the purpose of shift and mask\n'
+ ' operations, a binary representation is assumed, and negative\n'
+ ' numbers are represented in a variant of 2’s complement which '
+ 'gives\n'
+ ' the illusion of an infinite string of sign bits extending to '
+ 'the\n'
+ ' left.\n'
+ '\n'
+ 'Booleans ("bool")\n'
+ ' These represent the truth values False and True. The two '
+ 'objects\n'
+ ' representing the values "False" and "True" are the only Boolean\n'
+ ' objects. The Boolean type is a subtype of the integer type, and\n'
+ ' Boolean values behave like the values 0 and 1, respectively, in\n'
+ ' almost all contexts, the exception being that when converted to '
+ 'a\n'
+ ' string, the strings ""False"" or ""True"" are returned,\n'
+ ' respectively.\n'
+ '\n'
+ '\n'
+ '"numbers.Real" ("float")\n'
+ '------------------------\n'
+ '\n'
+ 'These represent machine-level double precision floating-point '
+ 'numbers.\n'
+ 'You are at the mercy of the underlying machine architecture (and C '
+ 'or\n'
+ 'Java implementation) for the accepted range and handling of '
+ 'overflow.\n'
+ 'Python does not support single-precision floating-point numbers; '
+ 'the\n'
+ 'savings in processor and memory usage that are usually the reason '
+ 'for\n'
+ 'using these are dwarfed by the overhead of using objects in Python, '
+ 'so\n'
+ 'there is no reason to complicate the language with two kinds of\n'
+ 'floating-point numbers.\n'
+ '\n'
+ '\n'
+ '"numbers.Complex" ("complex")\n'
+ '-----------------------------\n'
+ '\n'
+ 'These represent complex numbers as a pair of machine-level double\n'
+ 'precision floating-point numbers. The same caveats apply as for\n'
+ 'floating-point numbers. The real and imaginary parts of a complex\n'
+ 'number "z" can be retrieved through the read-only attributes '
+ '"z.real"\n'
+ 'and "z.imag".\n'
+ '\n'
+ '\n'
+ 'Sequences\n'
+ '=========\n'
+ '\n'
+ 'These represent finite ordered sets indexed by non-negative '
+ 'numbers.\n'
+ 'The built-in function "len()" returns the number of items of a\n'
+ 'sequence. When the length of a sequence is *n*, the index set '
+ 'contains\n'
+ 'the numbers 0, 1, …, *n*-1. Item *i* of sequence *a* is selected '
+ 'by\n'
+ '"a[i]". Some sequences, including built-in sequences, interpret\n'
+ 'negative subscripts by adding the sequence length. For example,\n'
+ '"a[-2]" equals "a[n-2]", the second to last item of sequence a '
+ 'with\n'
+ 'length "n".\n'
+ '\n'
+ 'Sequences also support slicing: "a[i:j]" selects all items with '
+ 'index\n'
+ '*k* such that *i* "<=" *k* "<" *j*. When used as an expression, a\n'
+ 'slice is a sequence of the same type. The comment above about '
+ 'negative\n'
+ 'indexes also applies to negative slice positions.\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 '
+ '"x\n'
+ '= i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n'
+ '\n'
+ 'Sequences are distinguished according to their mutability:\n'
+ '\n'
+ '\n'
+ 'Immutable sequences\n'
+ '-------------------\n'
+ '\n'
+ 'An object of an immutable sequence type cannot change once it is\n'
+ 'created. (If the object contains references to other objects, '
+ 'these\n'
+ 'other objects may be mutable and may be changed; however, the\n'
+ 'collection of objects directly referenced by an immutable object\n'
+ '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" can '
+ 'be\n'
+ ' represented in a string. Python doesn’t have a char type; '
+ 'instead,\n'
+ ' every code point in the string is represented as a string '
+ 'object\n'
+ ' with length "1". The built-in function "ord()" converts a code\n'
+ ' point from its string form to an integer in the range "0 - '
+ '10FFFF";\n'
+ ' "chr()" converts an integer in the range "0 - 10FFFF" to the\n'
+ ' corresponding length "1" string object. "str.encode()" can be '
+ 'used\n'
+ ' to convert a "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 two '
+ 'or\n'
+ ' more items are formed by comma-separated lists of expressions. '
+ 'A\n'
+ ' tuple of one item (a ‘singleton’) can be formed by affixing a '
+ 'comma\n'
+ ' to an expression (an expression by itself does not create a '
+ 'tuple,\n'
+ ' since parentheses must be usable for grouping of expressions). '
+ 'An\n'
+ ' empty tuple can be formed by an empty pair of parentheses.\n'
+ '\n'
+ 'Bytes\n'
+ ' A bytes object is an immutable array. The items are 8-bit '
+ 'bytes,\n'
+ ' represented by integers in the range 0 <= x < 256. Bytes '
+ 'literals\n'
+ ' (like "b\'abc\'") and the built-in "bytes()" constructor can be '
+ 'used\n'
+ ' to create bytes objects. Also, bytes objects can be decoded to\n'
+ ' strings via the "decode()" method.\n'
+ '\n'
+ '\n'
+ 'Mutable sequences\n'
+ '-----------------\n'
+ '\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'
+ 'Note:\n'
+ '\n'
+ ' The "collections" and "array" module provide additional examples '
+ 'of\n'
+ ' mutable sequence types.\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 '
+ 'formed\n'
+ ' by placing a comma-separated list of expressions in square\n'
+ ' brackets. (Note that there are no special cases needed to form\n'
+ ' lists of length 0 or 1.)\n'
+ '\n'
+ 'Byte Arrays\n'
+ ' A bytearray object is a mutable array. They are created by the\n'
+ ' built-in "bytearray()" constructor. Aside from being mutable '
+ '(and\n'
+ ' hence unhashable), byte arrays otherwise provide the same '
+ 'interface\n'
+ ' and functionality as immutable "bytes" objects.\n'
+ '\n'
+ '\n'
+ 'Set types\n'
+ '=========\n'
+ '\n'
+ 'These represent unordered, finite sets of unique, immutable '
+ 'objects.\n'
+ 'As such, they cannot be indexed by any subscript. However, they can '
+ 'be\n'
+ 'iterated over, and the built-in function "len()" returns the number '
+ 'of\n'
+ 'items in a set. Common uses for sets are fast membership testing,\n'
+ 'removing duplicates from a sequence, and computing mathematical\n'
+ 'operations such as intersection, union, difference, and symmetric\n'
+ 'difference.\n'
+ '\n'
+ 'For set elements, the same immutability rules apply as for '
+ 'dictionary\n'
+ 'keys. Note that numeric types obey the normal rules for numeric\n'
+ 'comparison: if two numbers compare equal (e.g., "1" and "1.0"), '
+ 'only\n'
+ '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 '
+ 'built-in\n'
+ ' "frozenset()" constructor. As a frozenset is immutable and\n'
+ ' *hashable*, it can be used again as an element of another set, '
+ 'or\n'
+ ' as a dictionary key.\n'
+ '\n'
+ '\n'
+ 'Mappings\n'
+ '========\n'
+ '\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'
+ '\n'
+ 'Dictionaries\n'
+ '------------\n'
+ '\n'
+ 'These represent finite sets of objects indexed by nearly arbitrary\n'
+ 'values. The only types of values not acceptable as keys are '
+ 'values\n'
+ 'containing lists or dictionaries or other mutable types that are\n'
+ 'compared by value rather than by object identity, the reason being\n'
+ 'that the efficient implementation of dictionaries requires a key’s\n'
+ 'hash value to remain constant. Numeric types used for keys obey '
+ 'the\n'
+ 'normal rules for numeric comparison: if two numbers compare equal\n'
+ '(e.g., "1" and "1.0") then they can be used interchangeably to '
+ 'index\n'
+ 'the same dictionary entry.\n'
+ '\n'
+ 'Dictionaries preserve insertion order, meaning that keys will be\n'
+ 'produced in the same order they were added sequentially over the\n'
+ 'dictionary. Replacing an existing key does not change the order,\n'
+ 'however removing a key and re-inserting it will add it to the end\n'
+ 'instead of keeping its old place.\n'
+ '\n'
+ 'Dictionaries are mutable; they can be created by the "{}" notation\n'
+ '(see section Dictionary displays).\n'
+ '\n'
+ 'The extension modules "dbm.ndbm" and "dbm.gnu" provide additional\n'
+ 'examples of mapping types, as does the "collections" module.\n'
+ '\n'
+ 'Changed in version 3.7: Dictionaries did not preserve insertion '
+ 'order\n'
+ 'in versions of Python before 3.6. In CPython 3.6, insertion order '
+ 'was\n'
+ 'preserved, but it was considered an implementation detail at that '
+ 'time\n'
+ 'rather than a language guarantee.\n'
+ '\n'
+ '\n'
+ 'Callable types\n'
+ '==============\n'
+ '\n'
+ 'These are the types to which the function call operation (see '
+ 'section\n'
+ 'Calls) can be applied:\n'
+ '\n'
+ '\n'
+ 'User-defined functions\n'
+ '----------------------\n'
+ '\n'
+ 'A user-defined function object is created by a function definition\n'
+ '(see section Function definitions). It should be called with an\n'
+ 'argument list containing the same number of items as the '
+ 'function’s\n'
+ 'formal parameter list.\n'
+ '\n'
+ '\n'
+ 'Special read-only attributes\n'
+ '~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| Attribute | '
+ 'Meaning |\n'
+ '|====================================================|====================================================|\n'
+ '| function.__globals__ | A reference '
+ 'to the "dictionary" that holds the |\n'
+ '| | function’s '
+ 'global variables – the global namespace |\n'
+ '| | of the '
+ 'module in which the function was defined. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__closure__ | "None" or a '
+ '"tuple" of cells that contain bindings |\n'
+ '| | for the '
+ 'names specified in the "co_freevars" |\n'
+ '| | attribute of '
+ 'the function’s "code object". A cell |\n'
+ '| | object has '
+ 'the attribute "cell_contents". This can |\n'
+ '| | be used to '
+ 'get the value of the cell, as well as |\n'
+ '| | set the '
+ 'value. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '\n'
+ '\n'
+ 'Special writable attributes\n'
+ '~~~~~~~~~~~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ 'Most of these attributes check the type of the assigned value:\n'
+ '\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| Attribute | '
+ 'Meaning |\n'
+ '|====================================================|====================================================|\n'
+ '| function.__doc__ | The '
+ 'function’s documentation string, or "None" if |\n'
+ '| | '
+ 'unavailable. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__name__ | The '
+ 'function’s name. See also: "__name__ |\n'
+ '| | '
+ 'attributes". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__qualname__ | The '
+ 'function’s *qualified name*. See also: |\n'
+ '| | '
+ '"__qualname__ attributes". Added in version 3.3. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__module__ | The name of '
+ 'the module the function was defined |\n'
+ '| | in, or '
+ '"None" if unavailable. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__defaults__ | A "tuple" '
+ 'containing default *parameter* values |\n'
+ '| | for those '
+ 'parameters that have defaults, or "None" |\n'
+ '| | if no '
+ 'parameters have a default value. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__code__ | The code '
+ 'object representing the compiled function |\n'
+ '| | '
+ 'body. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__dict__ | The '
+ 'namespace supporting arbitrary function |\n'
+ '| | attributes. '
+ 'See also: "__dict__ attributes". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__annotations__ | A '
+ '"dictionary" containing annotations of |\n'
+ '| | '
+ '*parameters*. The keys of the dictionary are the |\n'
+ '| | parameter '
+ 'names, and "\'return\'" for the return |\n'
+ '| | annotation, '
+ 'if provided. See also: |\n'
+ '| | '
+ '"object.__annotations__". Changed in version |\n'
+ '| | 3.14: '
+ 'Annotations are now lazily evaluated. See |\n'
+ '| | **PEP '
+ '649**. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__annotate__ | The '
+ '*annotate function* for this function, or |\n'
+ '| | "None" if '
+ 'the function has no annotations. See |\n'
+ '| | '
+ '"object.__annotate__". Added in version 3.14. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__kwdefaults__ | A '
+ '"dictionary" containing defaults for keyword- |\n'
+ '| | only '
+ '*parameters*. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| function.__type_params__ | A "tuple" '
+ 'containing the type parameters of a |\n'
+ '| | generic '
+ 'function. Added in version 3.12. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '\n'
+ 'Function objects also support getting and setting arbitrary\n'
+ 'attributes, which can be used, for example, to attach metadata to\n'
+ 'functions. Regular attribute dot-notation is used to get and set '
+ 'such\n'
+ 'attributes.\n'
+ '\n'
+ '**CPython implementation detail:** CPython’s current '
+ 'implementation\n'
+ 'only supports function attributes on user-defined functions. '
+ 'Function\n'
+ 'attributes on built-in functions may be supported in the future.\n'
+ '\n'
+ 'Additional information about a function’s definition can be '
+ 'retrieved\n'
+ 'from its code object (accessible via the "__code__" attribute).\n'
+ '\n'
+ '\n'
+ 'Instance methods\n'
+ '----------------\n'
+ '\n'
+ 'An instance method object combines a class, a class instance and '
+ 'any\n'
+ 'callable object (normally a user-defined function).\n'
+ '\n'
+ 'Special read-only attributes:\n'
+ '\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| method.__self__ | Refers to '
+ 'the class instance object to which the |\n'
+ '| | method is '
+ 'bound |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| method.__func__ | Refers to '
+ 'the original function object |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| method.__doc__ | The method’s '
+ 'documentation (same as |\n'
+ '| | '
+ '"method.__func__.__doc__"). A "string" if the |\n'
+ '| | original '
+ 'function had a docstring, else "None". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| method.__name__ | The name of '
+ 'the method (same as |\n'
+ '| | '
+ '"method.__func__.__name__") |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| method.__module__ | The name of '
+ 'the module the method was defined in, |\n'
+ '| | or "None" if '
+ 'unavailable. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\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 '
+ 'attribute\n'
+ 'of a class (perhaps via an instance of that class), if that '
+ 'attribute\n'
+ 'is a user-defined function object or a "classmethod" object.\n'
+ '\n'
+ 'When an instance method object is created by retrieving a '
+ 'user-defined\n'
+ 'function object from a class via one of its instances, its '
+ '"__self__"\n'
+ 'attribute is the instance, and the method object is said to be\n'
+ '*bound*. The new method’s "__func__" attribute is the original\n'
+ 'function object.\n'
+ '\n'
+ 'When an instance method object is created by retrieving a\n'
+ '"classmethod" object from a class or instance, its "__self__"\n'
+ 'attribute 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 function\n'
+ '("__func__") is called, inserting the class instance ("__self__") '
+ 'in\n'
+ 'front of the argument list. For instance, when "C" is a class '
+ 'which\n'
+ 'contains a definition for a function "f()", and "x" is an instance '
+ 'of\n'
+ '"C", calling "x.f(1)" is equivalent to calling "C.f(x, 1)".\n'
+ '\n'
+ 'When an instance method object is derived from a "classmethod" '
+ 'object,\n'
+ 'the “class instance” stored in "__self__" will actually be the '
+ 'class\n'
+ 'itself, so that calling either "x.f(1)" or "C.f(1)" is equivalent '
+ 'to\n'
+ 'calling "f(C,1)" where "f" is the underlying function.\n'
+ '\n'
+ 'It is important to note that user-defined functions which are\n'
+ 'attributes of a class instance are not converted to bound methods;\n'
+ 'this *only* happens when the function is an attribute of the '
+ 'class.\n'
+ '\n'
+ '\n'
+ 'Generator functions\n'
+ '-------------------\n'
+ '\n'
+ 'A function or method which uses the "yield" statement (see section '
+ 'The\n'
+ 'yield statement) is called a *generator function*. Such a '
+ 'function,\n'
+ 'when called, always returns an *iterator* object which can be used '
+ 'to\n'
+ 'execute the body of the function: calling the iterator’s\n'
+ '"iterator.__next__()" method will cause the function to execute '
+ 'until\n'
+ 'it provides a value using the "yield" statement. When the '
+ 'function\n'
+ 'executes a "return" statement or falls off the end, a '
+ '"StopIteration"\n'
+ 'exception is raised and the iterator will have reached the end of '
+ 'the\n'
+ 'set of values to be returned.\n'
+ '\n'
+ '\n'
+ 'Coroutine functions\n'
+ '-------------------\n'
+ '\n'
+ 'A function or method which is defined using "async def" is called '
+ 'a\n'
+ '*coroutine function*. Such a function, when called, returns a\n'
+ '*coroutine* object. It may contain "await" expressions, as well '
+ 'as\n'
+ '"async with" and "async for" statements. See also the Coroutine\n'
+ 'Objects section.\n'
+ '\n'
+ '\n'
+ 'Asynchronous generator functions\n'
+ '--------------------------------\n'
+ '\n'
+ 'A function or method which is defined using "async def" and which '
+ 'uses\n'
+ 'the "yield" statement is called a *asynchronous generator '
+ 'function*.\n'
+ 'Such a function, when called, returns an *asynchronous iterator*\n'
+ 'object which can be used in an "async for" statement to execute '
+ 'the\n'
+ 'body of the function.\n'
+ '\n'
+ 'Calling the asynchronous iterator’s "aiterator.__anext__" method '
+ 'will\n'
+ 'return an *awaitable* which when awaited will execute until it\n'
+ 'provides a value using the "yield" expression. When the function\n'
+ 'executes an empty "return" statement or falls off the end, a\n'
+ '"StopAsyncIteration" exception is raised and the asynchronous '
+ 'iterator\n'
+ 'will have reached the end of the set of values to be yielded.\n'
+ '\n'
+ '\n'
+ 'Built-in functions\n'
+ '------------------\n'
+ '\n'
+ 'A built-in function object is a wrapper around a C function. '
+ 'Examples\n'
+ 'of built-in functions are "len()" and "math.sin()" ("math" is a\n'
+ 'standard built-in module). The number and type of the arguments '
+ 'are\n'
+ 'determined by the C function. Special read-only attributes:\n'
+ '\n'
+ '* "__doc__" is the function’s documentation string, or "None" if\n'
+ ' unavailable. See "function.__doc__".\n'
+ '\n'
+ '* "__name__" is the function’s name. See "function.__name__".\n'
+ '\n'
+ '* "__self__" is set to "None" (but see the next item).\n'
+ '\n'
+ '* "__module__" is the name of the module the function was defined '
+ 'in\n'
+ ' or "None" if unavailable. See "function.__module__".\n'
+ '\n'
+ '\n'
+ 'Built-in methods\n'
+ '----------------\n'
+ '\n'
+ 'This is really a different disguise of a built-in function, this '
+ 'time\n'
+ 'containing an object passed to the C function as an implicit extra\n'
+ 'argument. An example of a built-in method is "alist.append()",\n'
+ 'assuming *alist* is a list object. In this case, the special '
+ 'read-only\n'
+ 'attribute "__self__" is set to the object denoted by *alist*. (The\n'
+ 'attribute has the same semantics as it does with "other instance\n'
+ 'methods".)\n'
+ '\n'
+ '\n'
+ 'Classes\n'
+ '-------\n'
+ '\n'
+ 'Classes are callable. These objects normally act as factories for '
+ 'new\n'
+ 'instances of themselves, but variations are possible for class '
+ 'types\n'
+ 'that override "__new__()". The arguments of the call are passed '
+ 'to\n'
+ '"__new__()" and, in the typical case, to "__init__()" to '
+ 'initialize\n'
+ 'the new instance.\n'
+ '\n'
+ '\n'
+ 'Class Instances\n'
+ '---------------\n'
+ '\n'
+ 'Instances of arbitrary classes can be made callable by defining a\n'
+ '"__call__()" method in their class.\n'
+ '\n'
+ '\n'
+ 'Modules\n'
+ '=======\n'
+ '\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, or by calling functions such as '
+ '"importlib.import_module()"\n'
+ 'and built-in "__import__()". A module object has a namespace\n'
+ 'implemented by a "dictionary" object (this is the dictionary\n'
+ 'referenced by the "__globals__" attribute of functions defined in '
+ 'the\n'
+ 'module). Attribute references are translated to lookups in this\n'
+ 'dictionary, e.g., "m.x" is equivalent to "m.__dict__["x"]". A '
+ 'module\n'
+ 'object does not contain the code object used to initialize the '
+ 'module\n'
+ '(since it isn’t needed once the initialization is done).\n'
+ '\n'
+ 'Attribute assignment updates the module’s namespace dictionary, '
+ 'e.g.,\n'
+ '"m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n'
+ '\n'
+ '\n'
+ 'Import-related attributes on module objects\n'
+ '-------------------------------------------\n'
+ '\n'
+ 'Module objects have the following attributes that relate to the '
+ 'import\n'
+ 'system. When a module is created using the machinery associated '
+ 'with\n'
+ 'the import system, these attributes are filled in based on the\n'
+ 'module’s *spec*, before the *loader* executes and loads the '
+ 'module.\n'
+ '\n'
+ 'To create a module dynamically rather than using the import '
+ 'system,\n'
+ 'it’s recommended to use "importlib.util.module_from_spec()", which\n'
+ 'will set the various import-controlled attributes to appropriate\n'
+ 'values. It’s also possible to use the "types.ModuleType" '
+ 'constructor\n'
+ 'to create modules directly, but this technique is more error-prone, '
+ 'as\n'
+ 'most attributes must be manually set on the module object after it '
+ 'has\n'
+ 'been created when using this approach.\n'
+ '\n'
+ 'Caution:\n'
+ '\n'
+ ' With the exception of "__name__", it is **strongly** recommended\n'
+ ' that you rely on "__spec__" and its attributes instead of any of '
+ 'the\n'
+ ' other individual attributes listed in this subsection. Note that\n'
+ ' updating an attribute on "__spec__" will not update the\n'
+ ' corresponding attribute on the module itself:\n'
+ '\n'
+ ' >>> import typing\n'
+ ' >>> typing.__name__, typing.__spec__.name\n'
+ " ('typing', 'typing')\n"
+ " >>> typing.__spec__.name = 'spelling'\n"
+ ' >>> typing.__name__, typing.__spec__.name\n'
+ " ('typing', 'spelling')\n"
+ " >>> typing.__name__ = 'keyboard_smashing'\n"
+ ' >>> typing.__name__, typing.__spec__.name\n'
+ " ('keyboard_smashing', 'spelling')\n"
+ '\n'
+ 'module.__name__\n'
+ '\n'
+ ' The name used to uniquely identify the module in the import '
+ 'system.\n'
+ ' For a directly executed module, this will be set to '
+ '""__main__"".\n'
+ '\n'
+ ' This attribute must be set to the fully qualified name of the\n'
+ ' module. It is expected to match the value of\n'
+ ' "module.__spec__.name".\n'
+ '\n'
+ 'module.__spec__\n'
+ '\n'
+ ' A record of the module’s import-system-related state.\n'
+ '\n'
+ ' Set to the "module spec" that was used when importing the '
+ 'module.\n'
+ ' See Module specs for more details.\n'
+ '\n'
+ ' Added in version 3.4.\n'
+ '\n'
+ 'module.__package__\n'
+ '\n'
+ ' The *package* a module belongs to.\n'
+ '\n'
+ ' If the module is top-level (that is, not a part of any specific\n'
+ ' package) then the attribute should be set to "\'\'" (the empty\n'
+ ' string). Otherwise, it should be set to the name of the '
+ 'module’s\n'
+ ' package (which can be equal to "module.__name__" if the module\n'
+ ' itself is a package). See **PEP 366** for further details.\n'
+ '\n'
+ ' This attribute is used instead of "__name__" to calculate '
+ 'explicit\n'
+ ' relative imports for main modules. It defaults to "None" for\n'
+ ' modules created dynamically using the "types.ModuleType"\n'
+ ' constructor; use "importlib.util.module_from_spec()" instead to\n'
+ ' ensure the attribute is set to a "str".\n'
+ '\n'
+ ' It is **strongly** recommended that you use\n'
+ ' "module.__spec__.parent" instead of "module.__package__".\n'
+ ' "__package__" is now only used as a fallback if '
+ '"__spec__.parent"\n'
+ ' is not set, and this fallback path is deprecated.\n'
+ '\n'
+ ' Changed in version 3.4: This attribute now defaults to "None" '
+ 'for\n'
+ ' modules created dynamically using the "types.ModuleType"\n'
+ ' constructor. Previously the attribute was optional.\n'
+ '\n'
+ ' Changed in version 3.6: The value of "__package__" is expected '
+ 'to\n'
+ ' be the same as "__spec__.parent". "__package__" is now only used '
+ 'as\n'
+ ' a fallback during import resolution if "__spec__.parent" is not\n'
+ ' defined.\n'
+ '\n'
+ ' Changed in version 3.10: "ImportWarning" is raised if an import\n'
+ ' resolution falls back to "__package__" instead of\n'
+ ' "__spec__.parent".\n'
+ '\n'
+ ' Changed in version 3.12: Raise "DeprecationWarning" instead of\n'
+ ' "ImportWarning" when falling back to "__package__" during '
+ 'import\n'
+ ' resolution.\n'
+ '\n'
+ ' Deprecated since version 3.13, will be removed in version 3.15:\n'
+ ' "__package__" will cease to be set or taken into consideration '
+ 'by\n'
+ ' the import system or standard library.\n'
+ '\n'
+ 'module.__loader__\n'
+ '\n'
+ ' The *loader* object that the import machinery used to load the\n'
+ ' module.\n'
+ '\n'
+ ' This attribute is mostly useful for introspection, but can be '
+ 'used\n'
+ ' for additional loader-specific functionality, for example '
+ 'getting\n'
+ ' data associated with a loader.\n'
+ '\n'
+ ' "__loader__" defaults to "None" for modules created dynamically\n'
+ ' using the "types.ModuleType" constructor; use\n'
+ ' "importlib.util.module_from_spec()" instead to ensure the '
+ 'attribute\n'
+ ' is set to a *loader* object.\n'
+ '\n'
+ ' It is **strongly** recommended that you use\n'
+ ' "module.__spec__.loader" instead of "module.__loader__".\n'
+ '\n'
+ ' Changed in version 3.4: This attribute now defaults to "None" '
+ 'for\n'
+ ' modules created dynamically using the "types.ModuleType"\n'
+ ' constructor. Previously the attribute was optional.\n'
+ '\n'
+ ' Deprecated since version 3.12, will be removed in version 3.16:\n'
+ ' Setting "__loader__" on a module while failing to set\n'
+ ' "__spec__.loader" is deprecated. In Python 3.16, "__loader__" '
+ 'will\n'
+ ' cease to be set or taken into consideration by the import system '
+ 'or\n'
+ ' the standard library.\n'
+ '\n'
+ 'module.__path__\n'
+ '\n'
+ ' A (possibly empty) *sequence* of strings enumerating the '
+ 'locations\n'
+ ' where the package’s submodules will be found. Non-package '
+ 'modules\n'
+ ' should not have a "__path__" attribute. See __path__ attributes '
+ 'on\n'
+ ' modules for more details.\n'
+ '\n'
+ ' It is **strongly** recommended that you use\n'
+ ' "module.__spec__.submodule_search_locations" instead of\n'
+ ' "module.__path__".\n'
+ '\n'
+ 'module.__file__\n'
+ '\n'
+ 'module.__cached__\n'
+ '\n'
+ ' "__file__" and "__cached__" are both optional attributes that '
+ 'may\n'
+ ' or may not be set. Both attributes should be a "str" when they '
+ 'are\n'
+ ' available.\n'
+ '\n'
+ ' "__file__" indicates the pathname of the file from which the '
+ 'module\n'
+ ' was loaded (if loaded from a file), or the pathname of the '
+ 'shared\n'
+ ' library file for extension modules loaded dynamically from a '
+ 'shared\n'
+ ' library. It might be missing for certain types of modules, such '
+ 'as\n'
+ ' C modules that are statically linked into the interpreter, and '
+ 'the\n'
+ ' import system may opt to leave it unset if it has no semantic\n'
+ ' meaning (for example, a module loaded from a database).\n'
+ '\n'
+ ' If "__file__" is set then the "__cached__" attribute might also '
+ 'be\n'
+ ' set, which is the path to any compiled version of the code '
+ '(for\n'
+ ' example, a byte-compiled file). The file does not need to exist '
+ 'to\n'
+ ' set this attribute; the path can simply point to where the '
+ 'compiled\n'
+ ' file *would* exist (see **PEP 3147**).\n'
+ '\n'
+ ' Note that "__cached__" may be set even if "__file__" is not '
+ 'set.\n'
+ ' However, that scenario is quite atypical. Ultimately, the '
+ '*loader*\n'
+ ' is what makes use of the module spec provided by the *finder* '
+ '(from\n'
+ ' which "__file__" and "__cached__" are derived). So if a loader '
+ 'can\n'
+ ' load from a cached module but otherwise does not load from a '
+ 'file,\n'
+ ' that atypical scenario may be appropriate.\n'
+ '\n'
+ ' It is **strongly** recommended that you use\n'
+ ' "module.__spec__.cached" instead of "module.__cached__".\n'
+ '\n'
+ ' Deprecated since version 3.13, will be removed in version 3.15:\n'
+ ' Setting "__cached__" on a module while failing to set\n'
+ ' "__spec__.cached" is deprecated. In Python 3.15, "__cached__" '
+ 'will\n'
+ ' cease to be set or taken into consideration by the import system '
+ 'or\n'
+ ' standard library.\n'
+ '\n'
+ '\n'
+ 'Other writable attributes on module objects\n'
+ '-------------------------------------------\n'
+ '\n'
+ 'As well as the import-related attributes listed above, module '
+ 'objects\n'
+ 'also have the following writable attributes:\n'
+ '\n'
+ 'module.__doc__\n'
+ '\n'
+ ' The module’s documentation string, or "None" if unavailable. '
+ 'See\n'
+ ' also: "__doc__ attributes".\n'
+ '\n'
+ 'module.__annotations__\n'
+ '\n'
+ ' A dictionary containing *variable annotations* collected during\n'
+ ' module body execution. For best practices on working with\n'
+ ' "__annotations__", see "annotationlib".\n'
+ '\n'
+ ' Changed in version 3.14: Annotations are now lazily evaluated. '
+ 'See\n'
+ ' **PEP 649**.\n'
+ '\n'
+ 'module.__annotate__\n'
+ '\n'
+ ' The *annotate function* for this module, or "None" if the '
+ 'module\n'
+ ' has no annotations. See also: "__annotate__" attributes.\n'
+ '\n'
+ ' Added in version 3.14.\n'
+ '\n'
+ '\n'
+ 'Module dictionaries\n'
+ '-------------------\n'
+ '\n'
+ 'Module objects also have the following special read-only '
+ 'attribute:\n'
+ '\n'
+ 'module.__dict__\n'
+ '\n'
+ ' The module’s namespace as a dictionary object. Uniquely among '
+ 'the\n'
+ ' attributes listed here, "__dict__" cannot be accessed as a '
+ 'global\n'
+ ' variable from within a module; it can only be accessed as an\n'
+ ' attribute on module objects.\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'
+ '\n'
+ 'Custom classes\n'
+ '==============\n'
+ '\n'
+ 'Custom class types are typically created by class definitions (see\n'
+ 'section Class definitions). A class has a namespace implemented by '
+ 'a\n'
+ '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 '
+ 'classes.\n'
+ 'This search of the base classes uses the C3 method resolution '
+ 'order\n'
+ 'which behaves correctly even in the presence of ‘diamond’ '
+ 'inheritance\n'
+ 'structures where there are multiple inheritance paths leading back '
+ 'to\n'
+ 'a common ancestor. Additional details on the C3 MRO used by Python '
+ 'can\n'
+ 'be found at The Python 2.3 Method Resolution Order.\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 '
+ 'object\n'
+ 'whose "__self__" attribute is "C". When it would yield a\n'
+ '"staticmethod" 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 '
+ 'from\n'
+ 'those actually contained in its "__dict__".\n'
+ '\n'
+ 'Class attribute assignments update the class’s dictionary, never '
+ 'the\n'
+ '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'
+ '\n'
+ 'Special attributes\n'
+ '------------------\n'
+ '\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| Attribute | '
+ 'Meaning |\n'
+ '|====================================================|====================================================|\n'
+ '| type.__name__ | The class’s '
+ 'name. See also: "__name__ attributes". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__qualname__ | The class’s '
+ '*qualified name*. See also: |\n'
+ '| | '
+ '"__qualname__ attributes". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__module__ | The name of '
+ 'the module in which the class was |\n'
+ '| | '
+ 'defined. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__dict__ | A "mapping '
+ 'proxy" providing a read-only view of |\n'
+ '| | the class’s '
+ 'namespace. See also: "__dict__ |\n'
+ '| | '
+ 'attributes". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__bases__ | A "tuple" '
+ 'containing the class’s bases. In most |\n'
+ '| | cases, for a '
+ 'class defined as "class X(A, B, C)", |\n'
+ '| | '
+ '"X.__bases__" will be exactly equal to "(A, B, |\n'
+ '| | '
+ 'C)". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__doc__ | The class’s '
+ 'documentation string, or "None" if |\n'
+ '| | undefined. '
+ 'Not inherited by subclasses. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__annotations__ | A dictionary '
+ 'containing *variable annotations* |\n'
+ '| | collected '
+ 'during class body execution. See also: |\n'
+ '| | '
+ '"__annotations__ attributes". For best practices |\n'
+ '| | on working '
+ 'with "__annotations__", please see |\n'
+ '| | '
+ '"annotationlib". Caution: Accessing the |\n'
+ '| | '
+ '"__annotations__" attribute of a class object |\n'
+ '| | directly may '
+ 'yield incorrect results in the |\n'
+ '| | presence of '
+ 'metaclasses. In addition, the |\n'
+ '| | attribute '
+ 'may not exist for some classes. Use |\n'
+ '| | '
+ '"annotationlib.get_annotations()" to retrieve |\n'
+ '| | class '
+ 'annotations safely. Changed in version |\n'
+ '| | 3.14: '
+ 'Annotations are now lazily evaluated. See |\n'
+ '| | **PEP '
+ '649**. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__annotate__() | The '
+ '*annotate function* for this class, or "None" |\n'
+ '| | if the class '
+ 'has no annotations. See also: |\n'
+ '| | '
+ '"__annotate__ attributes". Caution: Accessing |\n'
+ '| | the '
+ '"__annotate__" attribute of a class object |\n'
+ '| | directly may '
+ 'yield incorrect results in the |\n'
+ '| | presence of '
+ 'metaclasses. Use |\n'
+ '| | '
+ '"annotationlib.get_annotate_function()" to |\n'
+ '| | retrieve the '
+ 'annotate function safely. Added in |\n'
+ '| | version '
+ '3.14. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__type_params__ | A "tuple" '
+ 'containing the type parameters of a |\n'
+ '| | generic '
+ 'class. Added in version 3.12. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__static_attributes__ | A "tuple" '
+ 'containing names of attributes of this |\n'
+ '| | class which '
+ 'are assigned through "self.X" from any |\n'
+ '| | function in '
+ 'its body. Added in version 3.13. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__firstlineno__ | The line '
+ 'number of the first line of the class |\n'
+ '| | definition, '
+ 'including decorators. Setting the |\n'
+ '| | "__module__" '
+ 'attribute removes the |\n'
+ '| | '
+ '"__firstlineno__" item from the type’s dictionary. |\n'
+ '| | Added in '
+ 'version 3.13. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| type.__mro__ | The "tuple" '
+ 'of classes that are considered when |\n'
+ '| | looking for '
+ 'base classes during method resolution. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '\n'
+ '\n'
+ 'Special methods\n'
+ '---------------\n'
+ '\n'
+ 'In addition to the special attributes described above, all Python\n'
+ 'classes also have the following two methods available:\n'
+ '\n'
+ 'type.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'
+ 'type.__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. The list is in definition order. Example:\n'
+ '\n'
+ ' >>> class A: pass\n'
+ ' >>> class B(A): pass\n'
+ ' >>> A.__subclasses__()\n'
+ " [<class 'B'>]\n"
+ '\n'
+ '\n'
+ 'Class instances\n'
+ '===============\n'
+ '\n'
+ 'A class instance is created by calling a class object (see above). '
+ 'A\n'
+ 'class instance has a namespace implemented as a dictionary which '
+ 'is\n'
+ 'the first place in which attribute references are searched. When '
+ 'an\n'
+ 'attribute is not found there, and the instance’s class has an\n'
+ '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 '
+ 'class\n'
+ 'method objects are also transformed; see above under “Classes”. '
+ 'See\n'
+ 'section Implementing Descriptors for another way in which '
+ 'attributes\n'
+ 'of a class retrieved via its instances may differ from the objects\n'
+ 'actually stored in the class’s "__dict__". If no class attribute '
+ 'is\n'
+ 'found, and the object’s class has a "__getattr__()" method, that '
+ 'is\n'
+ 'called to satisfy the lookup.\n'
+ '\n'
+ 'Attribute assignments and deletions update the instance’s '
+ 'dictionary,\n'
+ 'never a class’s dictionary. If the class has a "__setattr__()" or\n'
+ '"__delattr__()" method, this is called instead of updating the\n'
+ 'instance dictionary directly.\n'
+ '\n'
+ 'Class instances can pretend to be numbers, sequences, or mappings '
+ 'if\n'
+ 'they have methods with certain special names. See section Special\n'
+ 'method names.\n'
+ '\n'
+ '\n'
+ 'Special attributes\n'
+ '------------------\n'
+ '\n'
+ 'object.__class__\n'
+ '\n'
+ ' The class to which a class instance belongs.\n'
+ '\n'
+ 'object.__dict__\n'
+ '\n'
+ ' A dictionary or other mapping object used to store an object’s\n'
+ ' (writable) attributes. Not all instances have a "__dict__"\n'
+ ' attribute; see the section on __slots__ for more details.\n'
+ '\n'
+ '\n'
+ 'I/O objects (also known as file objects)\n'
+ '========================================\n'
+ '\n'
+ 'A *file object* represents an open file. Various shortcuts are\n'
+ 'available to create file objects: the "open()" built-in function, '
+ 'and\n'
+ 'also "os.popen()", "os.fdopen()", and the "makefile()" method of\n'
+ 'socket objects (and perhaps by other functions or methods provided '
+ 'by\n'
+ 'extension modules).\n'
+ '\n'
+ 'The objects "sys.stdin", "sys.stdout" and "sys.stderr" are '
+ 'initialized\n'
+ 'to file objects corresponding to the interpreter’s standard input,\n'
+ 'output and error streams; they are all open in text mode and '
+ 'therefore\n'
+ 'follow the interface defined by the "io.TextIOBase" abstract '
+ 'class.\n'
+ '\n'
+ '\n'
+ 'Internal types\n'
+ '==============\n'
+ '\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'
+ '\n'
+ 'Code objects\n'
+ '------------\n'
+ '\n'
+ 'Code objects represent *byte-compiled* executable Python code, or\n'
+ '*bytecode*. The difference between a code object and a function '
+ 'object\n'
+ 'is that the function object contains an explicit reference to the\n'
+ 'function’s globals (the module in which it was defined), while a '
+ 'code\n'
+ 'object contains no context; also the default argument values are\n'
+ 'stored in the function object, not in the code object (because '
+ 'they\n'
+ 'represent values calculated at run-time). Unlike function '
+ 'objects,\n'
+ 'code objects are immutable and contain no references (directly or\n'
+ 'indirectly) to mutable objects.\n'
+ '\n'
+ '\n'
+ 'Special read-only attributes\n'
+ '~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_name | The function '
+ 'name |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_qualname | The fully '
+ 'qualified function name Added in |\n'
+ '| | version '
+ '3.11. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_argcount | The total '
+ 'number of positional *parameters* |\n'
+ '| | (including '
+ 'positional-only parameters and |\n'
+ '| | parameters '
+ 'with default values) that the function |\n'
+ '| | '
+ 'has |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_posonlyargcount | The number '
+ 'of positional-only *parameters* |\n'
+ '| | (including '
+ 'arguments with default values) that the |\n'
+ '| | function '
+ 'has |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_kwonlyargcount | The number '
+ 'of keyword-only *parameters* (including |\n'
+ '| | arguments '
+ 'with default values) that the function |\n'
+ '| | '
+ 'has |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_nlocals | The number '
+ 'of local variables used by the function |\n'
+ '| | (including '
+ 'parameters) |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_varnames | A "tuple" '
+ 'containing the names of the local |\n'
+ '| | variables in '
+ 'the function (starting with the |\n'
+ '| | parameter '
+ 'names) |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_cellvars | A "tuple" '
+ 'containing the names of local variables |\n'
+ '| | that are '
+ 'referenced from at least one *nested |\n'
+ '| | scope* '
+ 'inside the function |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_freevars | A "tuple" '
+ 'containing the names of *free (closure) |\n'
+ '| | variables* '
+ 'that a *nested scope* references in an |\n'
+ '| | outer scope. '
+ 'See also "function.__closure__". |\n'
+ '| | Note: '
+ 'references to global and builtin names are |\n'
+ '| | *not* '
+ 'included. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_code | A string '
+ 'representing the sequence of *bytecode* |\n'
+ '| | instructions '
+ 'in the function |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_consts | A "tuple" '
+ 'containing the literals used by the |\n'
+ '| | *bytecode* '
+ 'in the function |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_names | A "tuple" '
+ 'containing the names used by the |\n'
+ '| | *bytecode* '
+ 'in the function |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_filename | The name of '
+ 'the file from which the code was |\n'
+ '| | '
+ 'compiled |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_firstlineno | The line '
+ 'number of the first line of the function |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_lnotab | A string '
+ 'encoding the mapping from *bytecode* |\n'
+ '| | offsets to '
+ 'line numbers. For details, see the |\n'
+ '| | source code '
+ 'of the interpreter. Deprecated since |\n'
+ '| | version '
+ '3.12: This attribute of code objects is |\n'
+ '| | deprecated, '
+ 'and may be removed in Python 3.15. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_stacksize | The required '
+ 'stack size of the code object |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| codeobject.co_flags | An "integer" '
+ 'encoding a number of flags for the |\n'
+ '| | '
+ 'interpreter. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '\n'
+ 'The following flag bits are defined for "co_flags": bit "0x04" is '
+ 'set\n'
+ 'if the function uses the "*arguments" syntax to accept an '
+ 'arbitrary\n'
+ 'number of positional arguments; bit "0x08" is set if the function '
+ 'uses\n'
+ 'the "**keywords" syntax to accept arbitrary keyword arguments; bit\n'
+ '"0x20" is set if the function is a generator. See Code Objects Bit\n'
+ 'Flags for details on the semantics of each flags that might be\n'
+ 'present.\n'
+ '\n'
+ 'Future feature declarations ("from __future__ import division") '
+ 'also\n'
+ 'use bits in "co_flags" to indicate whether a code object was '
+ 'compiled\n'
+ 'with a particular feature enabled: bit "0x2000" is set if the '
+ 'function\n'
+ 'was compiled with future division enabled; bits "0x10" and '
+ '"0x1000"\n'
+ 'were used in earlier versions of Python.\n'
+ '\n'
+ 'Other bits in "co_flags" are reserved for internal use.\n'
+ '\n'
+ 'If a code object represents a function and has a docstring, the '
+ 'first\n'
+ 'item in "co_consts" is the docstring of the function.\n'
+ '\n'
+ '\n'
+ 'Methods on code objects\n'
+ '~~~~~~~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ 'codeobject.co_positions()\n'
+ '\n'
+ ' Returns an iterable over the source code positions of each\n'
+ ' *bytecode* instruction in the code object.\n'
+ '\n'
+ ' The iterator returns "tuple"s containing the "(start_line,\n'
+ ' end_line, start_column, end_column)". The *i-th* tuple '
+ 'corresponds\n'
+ ' to the position of the source code that compiled to the *i-th* '
+ 'code\n'
+ ' unit. Column information is 0-indexed utf-8 byte offsets on the\n'
+ ' given source line.\n'
+ '\n'
+ ' This positional information can be missing. A non-exhaustive '
+ 'lists\n'
+ ' of cases where this may happen:\n'
+ '\n'
+ ' * Running the interpreter with "-X" "no_debug_ranges".\n'
+ '\n'
+ ' * Loading a pyc file compiled while using "-X" '
+ '"no_debug_ranges".\n'
+ '\n'
+ ' * Position tuples corresponding to artificial instructions.\n'
+ '\n'
+ ' * Line and column numbers that can’t be represented due to\n'
+ ' implementation specific limitations.\n'
+ '\n'
+ ' When this occurs, some or all of the tuple elements can be '
+ '"None".\n'
+ '\n'
+ ' Added in version 3.11.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' This feature requires storing column positions in code '
+ 'objects\n'
+ ' which may result in a small increase of disk usage of '
+ 'compiled\n'
+ ' Python files or interpreter memory usage. To avoid storing '
+ 'the\n'
+ ' extra information and/or deactivate printing the extra '
+ 'traceback\n'
+ ' information, the "-X" "no_debug_ranges" command line flag or '
+ 'the\n'
+ ' "PYTHONNODEBUGRANGES" environment variable can be used.\n'
+ '\n'
+ 'codeobject.co_lines()\n'
+ '\n'
+ ' Returns an iterator that yields information about successive '
+ 'ranges\n'
+ ' of *bytecode*s. Each item yielded is a "(start, end, lineno)"\n'
+ ' "tuple":\n'
+ '\n'
+ ' * "start" (an "int") represents the offset (inclusive) of the '
+ 'start\n'
+ ' of the *bytecode* range\n'
+ '\n'
+ ' * "end" (an "int") represents the offset (exclusive) of the end '
+ 'of\n'
+ ' the *bytecode* range\n'
+ '\n'
+ ' * "lineno" is an "int" representing the line number of the\n'
+ ' *bytecode* range, or "None" if the bytecodes in the given '
+ 'range\n'
+ ' have no line number\n'
+ '\n'
+ ' The items yielded will have the following properties:\n'
+ '\n'
+ ' * The first range yielded will have a "start" of 0.\n'
+ '\n'
+ ' * The "(start, end)" ranges will be non-decreasing and '
+ 'consecutive.\n'
+ ' That is, for any pair of "tuple"s, the "start" of the second '
+ 'will\n'
+ ' be equal to the "end" of the first.\n'
+ '\n'
+ ' * No range will be backwards: "end >= start" for all triples.\n'
+ '\n'
+ ' * The last "tuple" yielded will have "end" equal to the size of '
+ 'the\n'
+ ' *bytecode*.\n'
+ '\n'
+ ' Zero-width ranges, where "start == end", are allowed. '
+ 'Zero-width\n'
+ ' ranges are used for lines that are present in the source code, '
+ 'but\n'
+ ' have been eliminated by the *bytecode* compiler.\n'
+ '\n'
+ ' Added in version 3.10.\n'
+ '\n'
+ ' See also:\n'
+ '\n'
+ ' **PEP 626** - Precise line numbers for debugging and other '
+ 'tools.\n'
+ ' The PEP that introduced the "co_lines()" method.\n'
+ '\n'
+ 'codeobject.replace(**kwargs)\n'
+ '\n'
+ ' Return a copy of the code object with new values for the '
+ 'specified\n'
+ ' fields.\n'
+ '\n'
+ ' Code objects are also supported by the generic function\n'
+ ' "copy.replace()".\n'
+ '\n'
+ ' Added in version 3.8.\n'
+ '\n'
+ '\n'
+ 'Frame objects\n'
+ '-------------\n'
+ '\n'
+ 'Frame objects represent execution frames. They may occur in '
+ 'traceback\n'
+ 'objects, and are also passed to registered trace functions.\n'
+ '\n'
+ '\n'
+ 'Special read-only attributes\n'
+ '~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_back | Points to '
+ 'the previous stack frame (towards the |\n'
+ '| | caller), or '
+ '"None" if this is the bottom stack |\n'
+ '| | '
+ 'frame |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_code | The code '
+ 'object being executed in this frame. |\n'
+ '| | Accessing '
+ 'this attribute raises an auditing event |\n'
+ '| | '
+ '"object.__getattr__" with arguments "obj" and |\n'
+ '| | '
+ '""f_code"". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_locals | The mapping '
+ 'used by the frame to look up local |\n'
+ '| | variables. '
+ 'If the frame refers to an *optimized |\n'
+ '| | scope*, this '
+ 'may return a write-through proxy |\n'
+ '| | object. '
+ 'Changed in version 3.13: Return a proxy |\n'
+ '| | for '
+ 'optimized scopes. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_globals | The '
+ 'dictionary used by the frame to look up global |\n'
+ '| | '
+ 'variables |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_builtins | The '
+ 'dictionary used by the frame to look up built- |\n'
+ '| | in '
+ '(intrinsic) names |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_lasti | The “precise '
+ 'instruction” of the frame object |\n'
+ '| | (this is an '
+ 'index into the *bytecode* string of |\n'
+ '| | the code '
+ 'object) |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '\n'
+ '\n'
+ 'Special writable attributes\n'
+ '~~~~~~~~~~~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_trace | If not '
+ '"None", this is a function called for |\n'
+ '| | various '
+ 'events during code execution (this is used |\n'
+ '| | by '
+ 'debuggers). Normally an event is triggered for |\n'
+ '| | each new '
+ 'source line (see "f_trace_lines"). |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_trace_lines | Set this '
+ 'attribute to "False" to disable |\n'
+ '| | triggering a '
+ 'tracing event for each source line. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_trace_opcodes | Set this '
+ 'attribute to "True" to allow per-opcode |\n'
+ '| | events to be '
+ 'requested. Note that this may lead to |\n'
+ '| | undefined '
+ 'interpreter behaviour if exceptions |\n'
+ '| | raised by '
+ 'the trace function escape to the |\n'
+ '| | function '
+ 'being traced. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| frame.f_lineno | The current '
+ 'line number of the frame – writing to |\n'
+ '| | this from '
+ 'within a trace function jumps to the |\n'
+ '| | given line '
+ '(only for the bottom-most frame). A |\n'
+ '| | debugger can '
+ 'implement a Jump command (aka Set |\n'
+ '| | Next '
+ 'Statement) by writing to this attribute. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '\n'
+ '\n'
+ 'Frame object methods\n'
+ '~~~~~~~~~~~~~~~~~~~~\n'
+ '\n'
+ 'Frame objects support one method:\n'
+ '\n'
+ 'frame.clear()\n'
+ '\n'
+ ' This method clears all references to local variables held by '
+ 'the\n'
+ ' frame. Also, if the frame belonged to a *generator*, the '
+ 'generator\n'
+ ' is finalized. This helps break reference cycles involving '
+ 'frame\n'
+ ' objects (for example when catching an exception and storing its\n'
+ ' traceback for later use).\n'
+ '\n'
+ ' "RuntimeError" is raised if the frame is currently executing or\n'
+ ' suspended.\n'
+ '\n'
+ ' Added in version 3.4.\n'
+ '\n'
+ ' Changed in version 3.13: Attempting to clear a suspended frame\n'
+ ' raises "RuntimeError" (as has always been the case for '
+ 'executing\n'
+ ' frames).\n'
+ '\n'
+ '\n'
+ 'Traceback objects\n'
+ '-----------------\n'
+ '\n'
+ 'Traceback objects represent the stack trace of an exception. A\n'
+ 'traceback object is implicitly created when an exception occurs, '
+ 'and\n'
+ 'may also be explicitly created by calling "types.TracebackType".\n'
+ '\n'
+ 'Changed in version 3.7: Traceback objects can now be explicitly\n'
+ 'instantiated from Python code.\n'
+ '\n'
+ 'For implicitly created tracebacks, when the search for an '
+ 'exception\n'
+ 'handler unwinds the execution stack, at each unwound level a '
+ 'traceback\n'
+ 'object is inserted in front of the current traceback. When an\n'
+ 'exception handler is entered, the stack trace is made available to '
+ 'the\n'
+ 'program. (See section The try statement.) It is accessible as the\n'
+ 'third item of the tuple returned by "sys.exc_info()", and as the\n'
+ '"__traceback__" attribute of the caught exception.\n'
+ '\n'
+ 'When the program contains no suitable handler, the stack trace is\n'
+ 'written (nicely formatted) to the standard error stream; if the\n'
+ 'interpreter is interactive, it is also made available to the user '
+ 'as\n'
+ '"sys.last_traceback".\n'
+ '\n'
+ 'For explicitly created tracebacks, it is up to the creator of the\n'
+ 'traceback to determine how the "tb_next" attributes should be '
+ 'linked\n'
+ 'to form a full stack trace.\n'
+ '\n'
+ 'Special read-only attributes:\n'
+ '\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| traceback.tb_frame | Points to '
+ 'the execution frame of the current |\n'
+ '| | level. '
+ 'Accessing this attribute raises an |\n'
+ '| | auditing '
+ 'event "object.__getattr__" with arguments |\n'
+ '| | "obj" and '
+ '""tb_frame"". |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| traceback.tb_lineno | Gives the '
+ 'line number where the exception occurred |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '| traceback.tb_lasti | Indicates '
+ 'the “precise instruction”. |\n'
+ '+----------------------------------------------------+----------------------------------------------------+\n'
+ '\n'
+ 'The line number and last instruction in the traceback may differ '
+ 'from\n'
+ 'the line number of its frame object if the exception occurred in a\n'
+ '"try" statement with no matching except clause or with a "finally"\n'
+ 'clause.\n'
+ '\n'
+ 'traceback.tb_next\n'
+ '\n'
+ ' The special writable attribute "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.\n'
+ '\n'
+ ' Changed in version 3.7: This attribute is now writable\n'
+ '\n'
+ '\n'
+ 'Slice objects\n'
+ '-------------\n'
+ '\n'
+ 'Slice objects are used to represent slices for "__getitem__()"\n'
+ 'methods. They are also created by the built-in "slice()" '
+ 'function.\n'
+ '\n'
+ 'Special read-only attributes: "start" is the lower bound; "stop" '
+ 'is\n'
+ 'the upper bound; "step" is the step value; each is "None" if '
+ 'omitted.\n'
+ '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 '
+ 'computes\n'
+ ' information about the slice that the slice object would describe '
+ 'if\n'
+ ' applied to a sequence of *length* items. It returns a tuple of\n'
+ ' three integers; respectively these are the *start* and *stop*\n'
+ ' indices and the *step* or stride length of the slice. Missing '
+ 'or\n'
+ ' out-of-bounds indices are handled in a manner consistent with\n'
+ ' regular slices.\n'
+ '\n'
+ '\n'
+ 'Static method objects\n'
+ '---------------------\n'
+ '\n'
+ 'Static method objects provide a way of defeating the transformation '
+ 'of\n'
+ 'function objects to method objects described above. A static '
+ 'method\n'
+ 'object is a wrapper around any other object, usually a '
+ 'user-defined\n'
+ 'method object. When a static method object is retrieved from a '
+ 'class\n'
+ 'or a class instance, the object actually returned is the wrapped\n'
+ 'object, which is not subject to any further transformation. Static\n'
+ 'method objects are also callable. Static method objects are created '
+ 'by\n'
+ 'the built-in "staticmethod()" constructor.\n'
+ '\n'
+ '\n'
+ 'Class method objects\n'
+ '--------------------\n'
+ '\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 is\n'
+ 'retrieved from classes and class instances. The behaviour of class\n'
+ 'method objects upon such retrieval is described above, under '
+ '“instance\n'
+ 'methods”. Class method objects are created by the built-in\n'
+ '"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. Values that compare equal '
+ '(such as\n'
+ '"1", "1.0", and "True") can be used interchangeably to index '
+ 'the same\n'
+ 'dictionary entry.\n'
+ '\n'
+ 'class dict(**kwargs)\n'
+ 'class dict(mapping, **kwargs)\n'
+ 'class dict(iterable, **kwargs)\n'
+ '\n'
+ ' Return a new dictionary initialized from an optional '
+ 'positional\n'
+ ' argument and a possibly empty set of keyword arguments.\n'
+ '\n'
+ ' Dictionaries can be created by several means:\n'
+ '\n'
+ ' * Use a comma-separated list of "key: value" pairs within '
+ 'braces:\n'
+ ' "{\'jack\': 4098, \'sjoerd\': 4127}" or "{4098: '
+ "'jack', 4127:\n"
+ ' \'sjoerd\'}"\n'
+ '\n'
+ ' * Use a dict comprehension: "{}", "{x: x ** 2 for x in '
+ 'range(10)}"\n'
+ '\n'
+ ' * Use the type constructor: "dict()", "dict([(\'foo\', '
+ "100), ('bar',\n"
+ ' 200)])", "dict(foo=100, bar=200)"\n'
+ '\n'
+ ' If no positional argument is given, an empty dictionary '
+ 'is created.\n'
+ ' If a positional argument is given and it defines a '
+ '"keys()" method,\n'
+ ' a dictionary is created by calling "__getitem__()" on the '
+ 'argument\n'
+ ' with each returned key from the method. Otherwise, the '
+ 'positional\n'
+ ' argument must be an *iterable* object. Each item in the '
+ 'iterable\n'
+ ' must itself be an iterable with exactly two elements. '
+ 'The first\n'
+ ' element of each item becomes a key in the new dictionary, '
+ 'and the\n'
+ ' second element the corresponding value. If a key occurs '
+ 'more than\n'
+ ' once, the last value for that key becomes the '
+ 'corresponding value\n'
+ ' 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"
+ " >>> f = dict({'one': 1, 'three': 3}, two=2)\n"
+ ' >>> a == b == c == d == e == f\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'
+ ' list(d)\n'
+ '\n'
+ ' Return a list of all the keys used in the dictionary '
+ '*d*.\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'
+ ' ...\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(iterable, value=None, /)\n'
+ '\n'
+ ' Create a new dictionary with keys from *iterable* and '
+ 'values set\n'
+ ' to *value*.\n'
+ '\n'
+ ' "fromkeys()" is a class method that returns a new '
+ 'dictionary.\n'
+ ' *value* defaults to "None". All of the values refer '
+ 'to just a\n'
+ ' single instance, so it generally doesn’t make sense '
+ 'for *value*\n'
+ ' to be a mutable object such as an empty list. To get '
+ 'distinct\n'
+ ' values, use a dict comprehension instead.\n'
+ '\n'
+ ' get(key, default=None)\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 a "(key, value)" pair from the '
+ 'dictionary.\n'
+ ' Pairs are returned in LIFO (last-in, first-out) '
+ 'order.\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'
+ ' Changed in version 3.7: LIFO order is now guaranteed. '
+ 'In prior\n'
+ ' versions, "popitem()" would return an arbitrary '
+ 'key/value pair.\n'
+ '\n'
+ ' reversed(d)\n'
+ '\n'
+ ' Return a reverse iterator over the keys of the '
+ 'dictionary. This\n'
+ ' is a shortcut for "reversed(d.keys())".\n'
+ '\n'
+ ' Added in version 3.8.\n'
+ '\n'
+ ' setdefault(key, default=None)\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 object with a '
+ '"keys()" method\n'
+ ' (in which case "__getitem__()" is called with every '
+ 'key returned\n'
+ ' from the method) or an iterable of key/value pairs (as '
+ 'tuples or\n'
+ ' other iterables of length two). If keyword arguments '
+ 'are\n'
+ ' specified, the dictionary is then updated with those '
+ 'key/value\n'
+ ' pairs: "d.update(red=1, 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'
+ ' An equality comparison between one "dict.values()" '
+ 'view and\n'
+ ' another will always return "False". This also applies '
+ 'when\n'
+ ' comparing "dict.values()" to itself:\n'
+ '\n'
+ " >>> d = {'a': 1}\n"
+ ' >>> d.values() == d.values()\n'
+ ' False\n'
+ '\n'
+ ' d | other\n'
+ '\n'
+ ' Create a new dictionary with the merged keys and '
+ 'values of *d*\n'
+ ' and *other*, which must both be dictionaries. The '
+ 'values of\n'
+ ' *other* take priority when *d* and *other* share '
+ 'keys.\n'
+ '\n'
+ ' Added in version 3.9.\n'
+ '\n'
+ ' d |= other\n'
+ '\n'
+ ' Update the dictionary *d* with keys and values from '
+ '*other*,\n'
+ ' which may be either a *mapping* or an *iterable* of '
+ 'key/value\n'
+ ' pairs. The values of *other* take priority when *d* '
+ 'and *other*\n'
+ ' share keys.\n'
+ '\n'
+ ' Added in version 3.9.\n'
+ '\n'
+ ' Dictionaries compare equal if and only if they have the '
+ 'same "(key,\n'
+ ' value)" pairs (regardless of ordering). Order comparisons '
+ '(‘<’,\n'
+ ' ‘<=’, ‘>=’, ‘>’) raise "TypeError".\n'
+ '\n'
+ ' Dictionaries preserve insertion order. Note that '
+ 'updating a key\n'
+ ' does not affect the order. Keys added after deletion are '
+ 'inserted\n'
+ ' at the end.\n'
+ '\n'
+ ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n'
+ ' >>> d\n'
+ " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n"
+ ' >>> list(d)\n'
+ " ['one', 'two', 'three', 'four']\n"
+ ' >>> list(d.values())\n'
+ ' [1, 2, 3, 4]\n'
+ ' >>> d["one"] = 42\n'
+ ' >>> d\n'
+ " {'one': 42, 'two': 2, 'three': 3, 'four': 4}\n"
+ ' >>> del d["two"]\n'
+ ' >>> d["two"] = None\n'
+ ' >>> d\n'
+ " {'one': 42, 'three': 3, 'four': 4, 'two': None}\n"
+ '\n'
+ ' Changed in version 3.7: Dictionary order is guaranteed to '
+ 'be\n'
+ ' insertion order. This behavior was an implementation '
+ 'detail of\n'
+ ' CPython from 3.6.\n'
+ '\n'
+ ' Dictionaries and dictionary views are reversible.\n'
+ '\n'
+ ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n'
+ ' >>> d\n'
+ " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n"
+ ' >>> list(reversed(d))\n'
+ " ['four', 'three', 'two', 'one']\n"
+ ' >>> list(reversed(d.values()))\n'
+ ' [4, 3, 2, 1]\n'
+ ' >>> list(reversed(d.items()))\n'
+ " [('four', 4), ('three', 3), ('two', 2), ('one', 1)]\n"
+ '\n'
+ ' Changed in version 3.8: Dictionaries are now reversible.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' "types.MappingProxyType" can be used to create a read-only '
+ 'view of a\n'
+ ' "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 insertion order. '
+ 'This allows\n'
+ ' the creation of "(value, key)" pairs using "zip()": '
+ '"pairs =\n'
+ ' zip(d.values(), d.keys())". Another way to create the '
+ 'same list is\n'
+ ' "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'
+ ' Changed in version 3.7: Dictionary order is guaranteed to '
+ 'be\n'
+ ' insertion order.\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'
+ 'reversed(dictview)\n'
+ '\n'
+ ' Return a reverse iterator over the keys, values or items '
+ 'of the\n'
+ ' dictionary. The view will be iterated in reverse order of '
+ 'the\n'
+ ' insertion.\n'
+ '\n'
+ ' Changed in version 3.8: Dictionary views are now '
+ 'reversible.\n'
+ '\n'
+ 'dictview.mapping\n'
+ '\n'
+ ' Return a "types.MappingProxyType" that wraps the '
+ 'original\n'
+ ' dictionary to which the view refers.\n'
+ '\n'
+ ' Added in version 3.10.\n'
+ '\n'
+ 'Keys views are set-like since their entries are unique and '
+ '*hashable*.\n'
+ 'Items views also have set-like operations since the (key, '
+ 'value) pairs\n'
+ 'are unique and the keys are hashable. If all values in an '
+ 'items view\n'
+ 'are hashable as well, then the items view can interoperate '
+ 'with other\n'
+ 'sets. (Values views are not treated as set-like since the '
+ 'entries are\n'
+ 'generally not unique.) For set-like views, all of the '
+ 'operations\n'
+ 'defined for the abstract base class "collections.abc.Set" '
+ 'are\n'
+ 'available (for example, "==", "<", or "^"). While using '
+ 'set\n'
+ 'operators, set-like views accept any iterable as the other '
+ 'operand,\n'
+ 'unlike sets which only accept sets as the input.\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'
+ ' ...\n'
+ ' >>> print(n)\n'
+ ' 504\n'
+ '\n'
+ ' >>> # keys and values are iterated over in the same order '
+ '(insertion order)\n'
+ ' >>> list(keys)\n'
+ " ['eggs', 'sausage', 'bacon', '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'
+ " ['bacon', 'spam']\n"
+ '\n'
+ ' >>> # set operations\n'
+ " >>> keys & {'eggs', 'bacon', 'salad'}\n"
+ " {'bacon'}\n"
+ " >>> keys ^ {'sausage', 'juice'} == {'juice', 'sausage', "
+ "'bacon', 'spam'}\n"
+ ' True\n'
+ " >>> keys | ['juice', 'juice', 'juice'] == {'bacon', "
+ "'spam', 'juice'}\n"
+ ' True\n'
+ '\n'
+ ' >>> # get back a read-only proxy for the original '
+ 'dictionary\n'
+ ' >>> values.mapping\n'
+ " mappingproxy({'bacon': 1, 'spam': 500})\n"
+ " >>> values.mapping['spam']\n"
+ ' 500\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 method. 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 ("method.__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 Instance methods 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'
+ 'Forward and reversed iterators over mutable sequences access '
+ 'values\n'
+ 'using an index. That index will continue to march forward (or\n'
+ 'backward) even if the underlying sequence is mutated. The '
+ 'iterator\n'
+ 'terminates only when an "IndexError" or a "StopIteration" is\n'
+ 'encountered (or when the index drops below zero).\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 '
+ 'object.\n'
+ ' This means that building up a sequence by repeated '
+ 'concatenation\n'
+ ' will have a quadratic runtime cost in the total sequence '
+ 'length.\n'
+ ' To get a linear runtime cost, you must switch to one of the\n'
+ ' 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 '
+ 'sequences\n'
+ ' that follow specific patterns, and hence don’t support '
+ 'sequence\n'
+ ' concatenation or repetition.\n'
+ '\n'
+ '8. "index" raises "ValueError" when *x* is not found in *s*. Not '
+ 'all\n'
+ ' implementations support passing the additional arguments *i* '
+ 'and\n'
+ ' *j*. These arguments allow efficient searching of subsections '
+ 'of\n'
+ ' the sequence. Passing the extra arguments is roughly '
+ 'equivalent to\n'
+ ' using "s[i:j].index(x)", only without copying any data and '
+ 'with the\n'
+ ' returned index being relative to the start of the sequence '
+ 'rather\n'
+ ' 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()" or "s.pop(i)" | retrieves the item at *i* '
+ 'and | (2) |\n'
+ '| | also removes it from '
+ '*s* | |\n'
+ '+--------------------------------+----------------------------------+-----------------------+\n'
+ '| "s.remove(x)" | removes the first item from '
+ '*s* | (3) |\n'
+ '| | where "s[i]" is equal to '
+ '*x* | |\n'
+ '+--------------------------------+----------------------------------+-----------------------+\n'
+ '| "s.reverse()" | reverses the items of *s* '
+ 'in | (4) |\n'
+ '| | '
+ 'place | |\n'
+ '+--------------------------------+----------------------------------+-----------------------+\n'
+ '\n'
+ 'Notes:\n'
+ '\n'
+ '1. If *k* is not equal to "1", *t* must have the same length as '
+ 'the\n'
+ ' slice it is replacing.\n'
+ '\n'
+ '2. The optional argument *i* defaults to "-1", so that by '
+ 'default the\n'
+ ' 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 '
+ 'economy\n'
+ ' of space when reversing a large sequence. To remind users '
+ 'that it\n'
+ ' operates by side effect, it does not return the reversed '
+ '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"). "copy()" is not part '
+ 'of the\n'
+ ' "collections.abc.MutableSequence" ABC, but most concrete '
+ 'mutable\n'
+ ' sequence classes provide it.\n'
+ '\n'
+ ' Added 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]", '
+ '"[a,\n'
+ ' 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'
+ ' For sorting examples and a brief sorting tutorial, see '
+ 'Sorting\n'
+ ' Techniques.\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).Added the "start", "stop" and "step"\n'
+ 'attributes.\n'
+ '\n'
+ 'See also:\n'
+ '\n'
+ ' * The linspace recipe shows how to implement a lazy version of '
+ 'range\n'
+ ' 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()" or "s.pop(i)" | retrieves the item at '
+ '*i* and | (2) |\n'
+ '| | also removes it from '
+ '*s* | |\n'
+ '+--------------------------------+----------------------------------+-----------------------+\n'
+ '| "s.remove(x)" | removes the first '
+ 'item from *s* | (3) |\n'
+ '| | where "s[i]" is equal '
+ 'to *x* | |\n'
+ '+--------------------------------+----------------------------------+-----------------------+\n'
+ '| "s.reverse()" | reverses the items of '
+ '*s* in | (4) |\n'
+ '| | '
+ 'place | '
+ '|\n'
+ '+--------------------------------+----------------------------------+-----------------------+\n'
+ '\n'
+ 'Notes:\n'
+ '\n'
+ '1. If *k* is not equal to "1", *t* must have the same '
+ 'length as the\n'
+ ' slice it is replacing.\n'
+ '\n'
+ '2. The optional argument *i* defaults to "-1", so that '
+ 'by default the\n'
+ ' 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 economy\n'
+ ' of space when reversing a large sequence. To remind '
+ 'users that it\n'
+ ' operates by side effect, it does not return the '
+ 'reversed 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"). "copy()" is '
+ 'not part of the\n'
+ ' "collections.abc.MutableSequence" ABC, but most '
+ 'concrete mutable\n'
+ ' sequence classes provide it.\n'
+ '\n'
+ ' Added 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; the operation can be overridden with the "__neg__()" '
+ 'special\n'
+ 'method.\n'
+ '\n'
+ 'The unary "+" (plus) operator yields its numeric argument '
+ 'unchanged;\n'
+ 'the operation can be overridden with the "__pos__()" special '
+ 'method.\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 or to custom '
+ 'objects\n'
+ 'that override the "__invert__()" special method.\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" "assignment_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_stmt_contents" ","? '
+ '")" | "with_stmt_contents" ) ":" "suite"\n'
+ ' **with_stmt_contents**: "with_item" ("," "with_item")*\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") '
+ 'is\n'
+ ' evaluated to obtain a context manager.\n'
+ '\n'
+ '2. The context manager’s "__enter__()" is loaded for later use.\n'
+ '\n'
+ '3. The context manager’s "__exit__()" is loaded for later use.\n'
+ '\n'
+ '4. The context manager’s "__enter__()" method is invoked.\n'
+ '\n'
+ '5. If a target was included in the "with" statement, the return '
+ 'value\n'
+ ' from "__enter__()" is assigned to it.\n'
+ '\n'
+ ' Note:\n'
+ '\n'
+ ' The "with" statement guarantees that if the "__enter__()" '
+ 'method\n'
+ ' 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 7 below.\n'
+ '\n'
+ '6. The suite is executed.\n'
+ '\n'
+ '7. 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'
+ 'The following code:\n'
+ '\n'
+ ' with EXPRESSION as TARGET:\n'
+ ' SUITE\n'
+ '\n'
+ 'is semantically equivalent to:\n'
+ '\n'
+ ' manager = (EXPRESSION)\n'
+ ' enter = type(manager).__enter__\n'
+ ' exit = type(manager).__exit__\n'
+ ' value = enter(manager)\n'
+ ' hit_except = False\n'
+ '\n'
+ ' try:\n'
+ ' TARGET = value\n'
+ ' SUITE\n'
+ ' except:\n'
+ ' hit_except = True\n'
+ ' if not exit(manager, *sys.exc_info()):\n'
+ ' raise\n'
+ ' finally:\n'
+ ' if not hit_except:\n'
+ ' exit(manager, None, None, None)\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 semantically equivalent to:\n'
+ '\n'
+ ' with A() as a:\n'
+ ' with B() as b:\n'
+ ' SUITE\n'
+ '\n'
+ 'You can also write multi-item context managers in multiple lines if\n'
+ 'the items are surrounded by parentheses. For example:\n'
+ '\n'
+ ' with (\n'
+ ' A() as a,\n'
+ ' B() as b,\n'
+ ' ):\n'
+ ' SUITE\n'
+ '\n'
+ 'Changed in version 3.1: Support for multiple context expressions.\n'
+ '\n'
+ 'Changed in version 3.10: Support for using grouping parentheses to\n'
+ 'break the statement in multiple lines.\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\n'
+ 'cause that definition to create a generator function instead of a\n'
+ 'normal function.\n'
+ '\n'
+ 'For full details of "yield" semantics, refer to the Yield '
+ 'expressions\n'
+ 'section.\n'}
projects / thirdparty / Python / cpython.git / commitdiff
