'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

| "*" target

(See section Primaries for the syntax definitions for *attributeref*

and *subscription*.)

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 or subscription), 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. Next, the subscript expression is evaluated.

Then, the primary’s "__setitem__()" method is called with two

arguments: the subscript and the assigned object.

Typically, "__setitem__()" is defined on mutable sequence objects

(such as lists) and mapping objects (such as dictionaries), and

behaves as follows.

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).

If the target is a slicing: The primary expression should evaluate

to a mutable sequence object (such as a list). The assigned object

should be *iterable*. The slicing’s lower and upper bounds should be

integers; if they are "None" (or not present), the defaults are zero

and the sequence’s length. 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.

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

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).__aiter__()

running = True

while running:

try:

TARGET = await iter.__anext__()

except StopAsyncIteration:

running = False

else:

SUITE

else:

SUITE2

except that implicit special method lookup is used for "__aiter__()"

and "__anext__()".

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 = manager.__aenter__

aexit = manager.__aexit__

value = await aenter()

hit_except = False

try:

TARGET = value

SUITE

except:

hit_except = True

if not await aexit(*sys.exc_info()):

raise

finally:

if not hit_except:

await aexit(None, None, None)

except that implicit special method lookup is used for "__aenter__()"

and "__aexit__()".

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 Names

(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

********

A *literal* is a textual representation of a value. Python supports

numeric, string and bytes literals. Format strings and template

strings are treated as string literals.

Numeric literals consist of a single "NUMBER" token, which names an

integer, floating-point number, or an imaginary number. See the

Numeric literals section in Lexical analysis documentation for

details.

String and bytes literals may consist of several tokens. See section

String literal concatenation for details.

Note that negative and complex numbers, like "-3" or "3+4.2j", are

syntactically not literals, but unary or binary arithmetic operations

involving the "-" or "+" operator.

Evaluation of a literal yields an object of the given type ("int",

"float", "complex", "str", "bytes", or "Template") with the given

value. The value may be approximated in the case of floating-point and

imaginary literals.

The formal grammar for literals is:

literal: strings | NUMBER

Literals and object identity

============================

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.

CPython implementation detail: For example, in CPython, *small*

integers with the same value evaluate to the same object:

>>> x = 7

>>> y = 7

>>> x is y

True

However, large integers evaluate to different objects:

>>> x = 123456789

>>> y = 123456789

>>> x is y

False

This behavior may change in future versions of CPython. In particular,

the boundary between “small” and “large” integers has already changed

in the past.CPython will emit a "SyntaxWarning" when you compare

literals using "is":

>>> x = 7

>>> x is 7

<input>:1: SyntaxWarning: "is" with 'int' literal. Did you mean "=="?

True

See When can I rely on identity tests with the is operator? for more

information.

Template strings are immutable but may reference mutable objects as

"Interpolation" values. For the purposes of this section, two

t-strings have the “same value” if both their structure and the

*identity* of the values match.

**CPython implementation detail:** Currently, each evaluation of a

template string results in a different object.

String literal concatenation

============================

Multiple adjacent string or bytes literals, possibly using different

quoting conventions, are allowed, and their meaning is the same as

their concatenation:

>>> "hello" 'world'

"helloworld"

This feature is defined at the syntactical level, so it only works

with literals. To concatenate string expressions at run time, the ‘+’

operator may be used:

>>> greeting = "Hello"

>>> space = " "

>>> name = "Blaise"

>>> print(greeting + space + name) # not: print(greeting space name)

Hello Blaise

Literal concatenation can freely mix raw strings, triple-quoted

strings, and formatted string literals. For example:

>>> "Hello" r', ' f"{name}!"

"Hello, Blaise!"

This feature can be used to reduce the number of backslashes needed,

to split long strings conveniently across long lines, or even to add

comments to parts of strings. For example:

re.compile("[A-Za-z_]" # letter or underscore

"[A-Za-z0-9_]*" # letter, digit or underscore

)

However, bytes literals may only be combined with other byte literals;

not with string literals of any kind. Also, template string literals

may only be combined with other template string literals:

>>> t"Hello" t"{name}!"

Template(strings=('Hello', '!'), interpolations=(...))

Formally:

strings: (STRING | fstring)+ | tstring+

''',

'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

===================================

module.__getattr__()

module.__dir__()

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.

module.__class__

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 *__slots__* other than *__dict__* and

*__weakref__* are defined for a class derived from a ""variable-

length" built-in type" such as "int", "bytes", and "type", except

"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.

Changed in version 3.15: Allowed defining the *__dict__* and

*__weakref__* *__slots__* for any class. Allowed defining any

*__slots__* for a class derived from "tuple".

''',

'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

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