diff options
Diffstat (limited to 'Lib/pydoc_data/topics.py')
| -rw-r--r-- | Lib/pydoc_data/topics.py | 668 |
1 files changed, 426 insertions, 242 deletions
diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py index 890a616..67a5197 100644 --- a/Lib/pydoc_data/topics.py +++ b/Lib/pydoc_data/topics.py @@ -1,5 +1,5 @@ # -*- coding: utf-8 -*- -# Autogenerated by Sphinx on Mon Nov 15 18:21:10 2021 +# Autogenerated by Sphinx on Thu Jan 13 21:46:32 2022 topics = {'assert': 'The "assert" statement\n' '**********************\n' '\n' @@ -979,7 +979,7 @@ topics = {'assert': 'The "assert" statement\n' '"super(B,\n' ' obj).m()" searches "obj.__class__.__mro__" for the ' 'base class "A"\n' - ' immediately preceding "B" and then invokes the ' + ' immediately following "B" and then invokes the ' 'descriptor with the\n' ' call: "A.__dict__[\'m\'].__get__(obj, ' 'obj.__class__)".\n' @@ -1010,14 +1010,15 @@ topics = {'assert': 'The "assert" statement\n' 'can be\n' 'overridden by instances.\n' '\n' - 'Python methods (including "staticmethod()" and ' - '"classmethod()") are\n' - 'implemented as non-data descriptors. Accordingly, ' - 'instances can\n' - 'redefine and override methods. This allows individual ' - 'instances to\n' - 'acquire behaviors that differ from other instances of ' - 'the same class.\n' + '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' @@ -1030,12 +1031,12 @@ topics = {'assert': 'The "assert" statement\n' '\n' '*__slots__* allow us to explicitly declare data members ' '(like\n' - 'properties) and deny the creation of *__dict__* and ' + '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 ' + 'The space saved over using "__dict__" can be ' 'significant. Attribute\n' 'lookup speed can be significantly improved as well.\n' '\n' @@ -1047,7 +1048,7 @@ topics = {'assert': 'The "assert" statement\n' '*__slots__*\n' ' reserves space for the declared variables and ' 'prevents the\n' - ' automatic creation of *__dict__* and *__weakref__* ' + ' automatic creation of "__dict__" and *__weakref__* ' 'for each\n' ' instance.\n' '\n' @@ -1056,11 +1057,11 @@ topics = {'assert': 'The "assert" statement\n' '--------------------------\n' '\n' '* When inheriting from a class without *__slots__*, the ' - '*__dict__* and\n' + '"__dict__" and\n' ' *__weakref__* attribute of the instances will always ' 'be accessible.\n' '\n' - '* Without a *__dict__* variable, instances cannot be ' + '* Without a "__dict__" variable, instances cannot be ' 'assigned new\n' ' variables not listed in the *__slots__* definition. ' 'Attempts to\n' @@ -1074,28 +1075,28 @@ topics = {'assert': 'The "assert" statement\n' '\n' '* Without a *__weakref__* variable for each instance, ' 'classes defining\n' - ' *__slots__* do not support weak references to its ' - 'instances. If weak\n' - ' reference support is needed, then add ' + ' *__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 (Implementing Descriptors) for each ' - 'variable name. As a\n' - ' result, class attributes cannot be used to set default ' - 'values for\n' - ' instance variables defined by *__slots__*; otherwise, ' - 'the class\n' - ' attribute would overwrite the descriptor assignment.\n' + ' 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, child subclasses will get a ' - '*__dict__*\n' + '"__dict__"\n' ' and *__weakref__* unless they also define *__slots__* ' '(which should\n' ' only contain names of any *additional* slots).\n' @@ -1115,13 +1116,19 @@ topics = {'assert': 'The "assert" statement\n' ' “variable-length” built-in types such as "int", ' '"bytes" and "tuple".\n' '\n' - '* Any non-string iterable may be assigned to ' - '*__slots__*. Mappings may\n' - ' also be used; however, in the future, special meaning ' - 'may be\n' - ' assigned to the values corresponding to each key.\n' + '* Any non-string *iterable* may be assigned to ' + '*__slots__*.\n' '\n' - '* *__class__* assignment works only if both classes have ' + '* 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' @@ -1133,10 +1140,10 @@ topics = {'assert': 'The "assert" statement\n' 'violations\n' ' raise "TypeError".\n' '\n' - '* If an iterator is used for *__slots__* then a ' - 'descriptor is created\n' - ' for each of the iterator’s values. However, the ' - '*__slots__*\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' @@ -3763,17 +3770,16 @@ topics = {'assert': 'The "assert" statement\n' 'debugger will pause execution just before the first line of the\n' 'module.\n' '\n' - 'The typical usage to break into the debugger from a running ' - 'program is\n' - 'to insert\n' + 'The typical usage to break into the debugger is to insert:\n' '\n' ' import pdb; pdb.set_trace()\n' '\n' - 'at the location you want to break into the debugger. You can ' - 'then\n' - 'step through the code following this statement, and continue ' - 'running\n' - 'without the debugger using the "continue" command.\n' + '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' 'New in version 3.7: The built-in "breakpoint()", when called ' 'with\n' @@ -7655,61 +7661,62 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The following methods can be defined to implement ' 'container objects.\n' - 'Containers usually are sequences (such as lists or tuples) ' - 'or mappings\n' - '(like dictionaries), but can represent other containers as ' - 'well. The\n' - 'first set of methods is used either to emulate a sequence ' - 'or to\n' - 'emulate a mapping; the difference is that for a sequence, ' - 'the\n' - 'allowable keys should be the integers *k* for which "0 <= ' - 'k < N" where\n' - '*N* is the length of the sequence, or slice objects, which ' - 'define a\n' - 'range of items. It is also recommended that mappings ' - 'provide the\n' - 'methods "keys()", "values()", "items()", "get()", ' - '"clear()",\n' - '"setdefault()", "pop()", "popitem()", "copy()", and ' - '"update()"\n' - 'behaving similar to those for Python’s standard dictionary ' + 'Containers usually are *sequences* (such as "lists" or ' + '"tuples") or\n' + '*mappings* (like "dictionaries"), but can represent other ' + 'containers\n' + 'as well. The first set of methods is used either to ' + 'emulate a\n' + 'sequence or to emulate a mapping; the difference is that ' + 'for a\n' + 'sequence, the allowable keys should be the integers *k* ' + 'for which "0\n' + '<= k < N" where *N* is the length of the sequence, or ' + '"slice" objects,\n' + 'which define a range of items. It is also recommended ' + 'that mappings\n' + 'provide the methods "keys()", "values()", "items()", ' + '"get()",\n' + '"clear()", "setdefault()", "pop()", "popitem()", "copy()", ' + 'and\n' + '"update()" behaving similar to those for Python’s ' + 'standard\n' + '"dictionary" objects. The "collections.abc" module ' + 'provides a\n' + '"MutableMapping" *abstract base class* to help create ' + 'those methods\n' + 'from a base set of "__getitem__()", "__setitem__()", ' + '"__delitem__()",\n' + 'and "keys()". Mutable sequences should provide methods ' + '"append()",\n' + '"count()", "index()", "extend()", "insert()", "pop()", ' + '"remove()",\n' + '"reverse()" and "sort()", like Python standard "list" ' 'objects.\n' - 'The "collections.abc" module provides a "MutableMapping" ' - 'abstract base\n' - 'class to help create those methods from a base set of ' - '"__getitem__()",\n' - '"__setitem__()", "__delitem__()", and "keys()". Mutable ' - 'sequences\n' - 'should provide methods "append()", "count()", "index()", ' - '"extend()",\n' - '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' - 'like Python\n' - 'standard list objects. Finally, sequence types should ' - 'implement\n' - 'addition (meaning concatenation) and multiplication ' + 'Finally, sequence types should implement addition ' '(meaning\n' - 'repetition) by defining the methods "__add__()", ' - '"__radd__()",\n' - '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' - 'described\n' - 'below; they should not define other numerical operators. ' + 'concatenation) and multiplication (meaning repetition) by ' + 'defining the\n' + 'methods "__add__()", "__radd__()", "__iadd__()", ' + '"__mul__()",\n' + '"__rmul__()" and "__imul__()" described below; they should ' + 'not define\n' + 'other numerical operators. It is recommended that both ' + 'mappings and\n' + 'sequences implement the "__contains__()" method to allow ' + 'efficient use\n' + 'of the "in" operator; for mappings, "in" should search the ' + 'mapping’s\n' + 'keys; for sequences, it should search through the values. ' 'It is\n' - 'recommended that both mappings and sequences implement ' + 'further recommended that both mappings and sequences ' + 'implement the\n' + '"__iter__()" method to allow efficient iteration through ' 'the\n' - '"__contains__()" method to allow efficient use of the "in" ' - 'operator;\n' - 'for mappings, "in" should search the mapping’s keys; for ' - 'sequences, it\n' - 'should search through the values. It is further ' - 'recommended that both\n' - 'mappings and sequences implement the "__iter__()" method ' - 'to allow\n' - 'efficient iteration through the container; for mappings, ' - '"__iter__()"\n' - 'should iterate through the object’s keys; for sequences, ' - 'it should\n' - 'iterate through the values.\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' @@ -7768,22 +7775,24 @@ topics = {'assert': 'The "assert" statement\n' 'object.__getitem__(self, key)\n' '\n' ' Called to implement evaluation of "self[key]". For ' - 'sequence types,\n' - ' the accepted keys should be integers and slice ' - 'objects. Note that\n' - ' the special interpretation of negative indexes (if the ' - 'class wishes\n' - ' to emulate a sequence type) is up to the ' - '"__getitem__()" method. If\n' - ' *key* is of an inappropriate type, "TypeError" may be ' - 'raised; if of\n' - ' a value outside the set of indexes for the sequence ' - '(after any\n' - ' special interpretation of negative values), ' - '"IndexError" should be\n' - ' raised. For mapping types, if *key* is missing (not in ' + '*sequence*\n' + ' types, the accepted keys should be integers and slice ' + 'objects.\n' + ' Note that the special interpretation of negative ' + 'indexes (if the\n' + ' class wishes to emulate a *sequence* type) is up to ' 'the\n' - ' container), "KeyError" should be raised.\n' + ' "__getitem__()" method. If *key* is of an inappropriate ' + 'type,\n' + ' "TypeError" may be raised; if of a value outside the ' + 'set of indexes\n' + ' for the sequence (after any special interpretation of ' + 'negative\n' + ' values), "IndexError" should be raised. For *mapping* ' + 'types, if\n' + ' *key* is missing (not in the container), "KeyError" ' + 'should be\n' + ' raised.\n' '\n' ' Note:\n' '\n' @@ -7793,6 +7802,15 @@ topics = {'assert': 'The "assert" statement\n' '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 ' @@ -8891,7 +8909,7 @@ topics = {'assert': 'The "assert" statement\n' '"super(B,\n' ' obj).m()" searches "obj.__class__.__mro__" for the base ' 'class "A"\n' - ' immediately preceding "B" and then invokes the descriptor ' + ' immediately following "B" and then invokes the descriptor ' 'with the\n' ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n' '\n' @@ -8921,13 +8939,14 @@ topics = {'assert': 'The "assert" statement\n' 'be\n' 'overridden by instances.\n' '\n' - 'Python methods (including "staticmethod()" and ' - '"classmethod()") are\n' - 'implemented as non-data descriptors. Accordingly, instances ' - 'can\n' - 'redefine and override methods. This allows individual ' - 'instances to\n' - 'acquire behaviors that differ from other instances of the ' + '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 ' @@ -8941,12 +8960,12 @@ topics = {'assert': 'The "assert" statement\n' '\n' '*__slots__* allow us to explicitly declare data members ' '(like\n' - 'properties) and deny the creation of *__dict__* and ' + '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. ' + 'The space saved over using "__dict__" can be significant. ' 'Attribute\n' 'lookup speed can be significantly improved as well.\n' '\n' @@ -8958,7 +8977,7 @@ topics = {'assert': 'The "assert" statement\n' '*__slots__*\n' ' reserves space for the declared variables and prevents ' 'the\n' - ' automatic creation of *__dict__* and *__weakref__* for ' + ' automatic creation of "__dict__" and *__weakref__* for ' 'each\n' ' instance.\n' '\n' @@ -8967,11 +8986,11 @@ topics = {'assert': 'The "assert" statement\n' '~~~~~~~~~~~~~~~~~~~~~~~~~~\n' '\n' '* When inheriting from a class without *__slots__*, the ' - '*__dict__* and\n' + '"__dict__" and\n' ' *__weakref__* attribute of the instances will always be ' 'accessible.\n' '\n' - '* Without a *__dict__* variable, instances cannot be ' + '* Without a "__dict__" variable, instances cannot be ' 'assigned new\n' ' variables not listed in the *__slots__* definition. ' 'Attempts to\n' @@ -8984,28 +9003,28 @@ topics = {'assert': 'The "assert" statement\n' '\n' '* Without a *__weakref__* variable for each instance, ' 'classes defining\n' - ' *__slots__* do not support weak references to its ' - 'instances. If weak\n' - ' reference support is needed, then add "\'__weakref__\'" to ' - 'the\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 (Implementing Descriptors) for each variable ' - 'name. As a\n' - ' result, class attributes cannot be used to set default ' - 'values for\n' - ' instance variables defined by *__slots__*; otherwise, the ' - 'class\n' - ' attribute would overwrite the descriptor assignment.\n' + ' 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, child subclasses will get a ' - '*__dict__*\n' + '"__dict__"\n' ' and *__weakref__* unless they also define *__slots__* ' '(which should\n' ' only contain names of any *additional* slots).\n' @@ -9025,13 +9044,18 @@ topics = {'assert': 'The "assert" statement\n' ' “variable-length” built-in types such as "int", "bytes" ' 'and "tuple".\n' '\n' - '* Any non-string iterable may be assigned to *__slots__*. ' - 'Mappings may\n' - ' also be used; however, in the future, special meaning may ' - 'be\n' - ' assigned to the values corresponding to each key.\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 ' + '* "__class__" assignment works only if both classes have the ' 'same\n' ' *__slots__*.\n' '\n' @@ -9043,9 +9067,9 @@ topics = {'assert': 'The "assert" statement\n' 'violations\n' ' raise "TypeError".\n' '\n' - '* If an iterator is used for *__slots__* then a descriptor ' - 'is created\n' - ' for each of the iterator’s values. However, the ' + '* 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' @@ -9054,7 +9078,7 @@ topics = {'assert': 'The "assert" statement\n' '==========================\n' '\n' 'Whenever a class inherits from another class, ' - '*__init_subclass__* is\n' + '"__init_subclass__()" is\n' 'called on that class. This way, it is possible to write ' 'classes which\n' 'change the behavior of subclasses. This is closely related ' @@ -9222,10 +9246,10 @@ topics = {'assert': 'The "assert" statement\n' 'come from\n' 'the class definition). The "__prepare__" method should be ' 'implemented\n' - 'as a "classmethod()". The namespace returned by ' - '"__prepare__" is\n' - 'passed in to "__new__", but when the final class object is ' - 'created the\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 ' @@ -9413,9 +9437,33 @@ topics = {'assert': 'The "assert" statement\n' 'Emulating generic types\n' '=======================\n' '\n' - 'One can implement the generic class syntax as specified by ' - '**PEP 484**\n' - '(for example "List[int]") by defining a special method:\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' @@ -9423,18 +9471,144 @@ topics = {'assert': 'The "assert" statement\n' 'generic class\n' ' by type arguments found in *key*.\n' '\n' - 'This method is looked up on the class object itself, and ' - 'when defined\n' - 'in the class body, this method is implicitly a class ' - 'method. Note,\n' - 'this mechanism is primarily reserved for use with static ' - 'type hints,\n' - 'other usage is discouraged.\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 ' + ' **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' @@ -9453,60 +9627,60 @@ topics = {'assert': 'The "assert" statement\n' '\n' 'The following methods can be defined to implement container ' 'objects.\n' - 'Containers usually are sequences (such as lists or tuples) ' - 'or mappings\n' - '(like dictionaries), but can represent other containers as ' - 'well. The\n' - 'first set of methods is used either to emulate a sequence or ' - 'to\n' - 'emulate a mapping; the difference is that for a sequence, ' - 'the\n' - 'allowable keys should be the integers *k* for which "0 <= k ' - '< N" where\n' - '*N* is the length of the sequence, or slice objects, which ' - 'define a\n' - 'range of items. It is also recommended that mappings ' - 'provide the\n' - 'methods "keys()", "values()", "items()", "get()", ' - '"clear()",\n' - '"setdefault()", "pop()", "popitem()", "copy()", and ' - '"update()"\n' - 'behaving similar to those for Python’s standard dictionary ' + 'Containers usually are *sequences* (such as "lists" or ' + '"tuples") or\n' + '*mappings* (like "dictionaries"), but can represent other ' + 'containers\n' + 'as well. The first set of methods is used either to emulate ' + 'a\n' + 'sequence or to emulate a mapping; the difference is that for ' + 'a\n' + 'sequence, the allowable keys should be the integers *k* for ' + 'which "0\n' + '<= k < N" where *N* is the length of the sequence, or ' + '"slice" objects,\n' + 'which define a range of items. It is also recommended that ' + 'mappings\n' + 'provide the methods "keys()", "values()", "items()", ' + '"get()",\n' + '"clear()", "setdefault()", "pop()", "popitem()", "copy()", ' + 'and\n' + '"update()" behaving similar to those for Python’s standard\n' + '"dictionary" objects. The "collections.abc" module provides ' + 'a\n' + '"MutableMapping" *abstract base class* to help create those ' + 'methods\n' + 'from a base set of "__getitem__()", "__setitem__()", ' + '"__delitem__()",\n' + 'and "keys()". Mutable sequences should provide methods ' + '"append()",\n' + '"count()", "index()", "extend()", "insert()", "pop()", ' + '"remove()",\n' + '"reverse()" and "sort()", like Python standard "list" ' 'objects.\n' - 'The "collections.abc" module provides a "MutableMapping" ' - 'abstract base\n' - 'class to help create those methods from a base set of ' - '"__getitem__()",\n' - '"__setitem__()", "__delitem__()", and "keys()". Mutable ' - 'sequences\n' - 'should provide methods "append()", "count()", "index()", ' - '"extend()",\n' - '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' - 'like Python\n' - 'standard list objects. Finally, sequence types should ' - 'implement\n' - 'addition (meaning concatenation) and multiplication ' - '(meaning\n' - 'repetition) by defining the methods "__add__()", ' - '"__radd__()",\n' - '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' - 'described\n' - 'below; they should not define other numerical operators. It ' - 'is\n' - 'recommended that both mappings and sequences implement the\n' - '"__contains__()" method to allow efficient use of the "in" ' - 'operator;\n' - 'for mappings, "in" should search the mapping’s keys; for ' - 'sequences, it\n' - 'should search through the values. It is further recommended ' - 'that both\n' - 'mappings and sequences implement the "__iter__()" method to ' - 'allow\n' - 'efficient iteration through the container; for mappings, ' - '"__iter__()"\n' - 'should iterate through the object’s keys; for sequences, it ' - 'should\n' - 'iterate through the values.\n' + 'Finally, sequence types should implement addition (meaning\n' + 'concatenation) and multiplication (meaning repetition) by ' + 'defining the\n' + 'methods "__add__()", "__radd__()", "__iadd__()", ' + '"__mul__()",\n' + '"__rmul__()" and "__imul__()" described below; they should ' + 'not define\n' + 'other numerical operators. It is recommended that both ' + 'mappings and\n' + 'sequences implement the "__contains__()" method to allow ' + 'efficient use\n' + 'of the "in" operator; for mappings, "in" should search the ' + 'mapping’s\n' + 'keys; for sequences, it should search through the values. ' + 'It is\n' + 'further 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' @@ -9564,22 +9738,23 @@ topics = {'assert': 'The "assert" statement\n' 'object.__getitem__(self, key)\n' '\n' ' Called to implement evaluation of "self[key]". For ' - 'sequence types,\n' - ' the accepted keys should be integers and slice objects. ' - 'Note that\n' - ' the special interpretation of negative indexes (if the ' - 'class wishes\n' - ' to emulate a sequence type) is up to the "__getitem__()" ' - 'method. If\n' - ' *key* is of an inappropriate type, "TypeError" may be ' - 'raised; if of\n' - ' a value outside the set of indexes for the sequence ' - '(after any\n' - ' special interpretation of negative values), "IndexError" ' + '*sequence*\n' + ' types, the accepted keys should be integers and slice ' + 'objects.\n' + ' Note that the special interpretation of negative indexes ' + '(if the\n' + ' class wishes to emulate a *sequence* type) is up to the\n' + ' "__getitem__()" method. If *key* is of an inappropriate ' + 'type,\n' + ' "TypeError" may be raised; if of a value outside the set ' + 'of indexes\n' + ' for the sequence (after any special interpretation of ' + 'negative\n' + ' values), "IndexError" should be raised. For *mapping* ' + 'types, if\n' + ' *key* is missing (not in the container), "KeyError" ' 'should be\n' - ' raised. For mapping types, if *key* is missing (not in ' - 'the\n' - ' container), "KeyError" should be raised.\n' + ' raised.\n' '\n' ' Note:\n' '\n' @@ -9589,6 +9764,14 @@ topics = {'assert': 'The "assert" statement\n' '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 ' @@ -10376,9 +10559,9 @@ topics = {'assert': 'The "assert" statement\n' ' >>> from keyword import iskeyword\n' '\n' " >>> 'hello'.isidentifier(), iskeyword('hello')\n" - ' True, False\n' + ' (True, False)\n' " >>> 'def'.isidentifier(), iskeyword('def')\n" - ' True, True\n' + ' (True, True)\n' '\n' 'str.islower()\n' '\n' @@ -10729,7 +10912,7 @@ topics = {'assert': 'The "assert" statement\n' " >>> ' 1 2 3 '.split()\n" " ['1', '2', '3']\n" '\n' - 'str.splitlines([keepends])\n' + 'str.splitlines(keepends=False)\n' '\n' ' Return a list of the lines in the string, breaking at ' 'line\n' @@ -12060,14 +12243,14 @@ topics = {'assert': 'The "assert" statement\n' 'for"\n' ' statement to execute the body of the function.\n' '\n' - ' Calling the asynchronous iterator’s "aiterator.__anext__()"\n' - ' method will return an *awaitable* which when awaited will\n' - ' execute until it provides a value using the "yield" ' - 'expression.\n' - ' When the function executes an empty "return" statement or ' - 'falls\n' - ' off the end, a "StopAsyncIteration" exception is raised and ' + ' Calling the asynchronous iterator’s "aiterator.__anext__" ' + 'method\n' + ' will return an *awaitable* which when awaited will execute ' + 'until\n' + ' it provides a value using the "yield" expression. When the\n' + ' function executes an empty "return" statement or falls off ' 'the\n' + ' end, a "StopAsyncIteration" exception is raised and the\n' ' asynchronous iterator will have reached the end of the set ' 'of\n' ' values to be yielded.\n' @@ -12587,9 +12770,9 @@ topics = {'assert': 'The "assert" statement\n' '"dict"\n' 'constructor.\n' '\n' - 'class dict(**kwarg)\n' - 'class dict(mapping, **kwarg)\n' - 'class dict(iterable, **kwarg)\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' @@ -13694,7 +13877,8 @@ topics = {'assert': 'The "assert" statement\n' '\n' ' The arguments to the range constructor must be integers ' '(either\n' - ' built-in "int" or any object that implements the "__index__"\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". ' |