diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 514ca04ab3c528..9fb07650681d08 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -16,9 +16,6 @@ Is there a source code level debugger with breakpoints, single-stepping, etc.? Yes. -Several debuggers for Python are described below, and the built-in function -:func:`breakpoint` allows you to drop into any of them. - The pdb module is a simple but adequate console-mode debugger for Python. It is part of the standard Python library, and is :mod:`documented in the Library Reference Manual `. You can also write your own debugger by using the code @@ -35,6 +32,12 @@ for Windows Extensions `__ project an as a part of the ActivePython distribution (see https://www.activestate.com/activepython\ ). +`Boa Constructor `_ is an IDE and GUI +builder that uses wxWidgets. It offers visual frame creation and manipulation, +an object inspector, many views on the source like object browsers, inheritance +hierarchies, doc string generated html documentation, an advanced debugger, +integrated help, and Zope support. + `Eric `_ is an IDE built on PyQt and the Scintilla editing component. @@ -51,19 +54,22 @@ They include: * PyCharm (https://www.jetbrains.com/pycharm/) -Are there tools to help find bugs or perform static analysis? +Is there a tool to help find bugs or perform static analysis? ------------------------------------------------------------- Yes. -`Pylint `_ and -`Pyflakes `_ do basic checking that will -help you catch bugs sooner. +PyChecker is a static analysis tool that finds bugs in Python source code and +warns about code complexity and style. You can get PyChecker from +http://pychecker.sourceforge.net/. -Static type checkers such as `Mypy `_, -`Pyre `_, and -`Pytype `_ can check type hints in Python -source code. +`Pylint `_ is another tool that checks +if a module satisfies a coding standard, and also makes it possible to write +plug-ins to add a custom feature. In addition to the bug checking that +PyChecker performs, Pylint offers some additional features such as checking line +length, whether variable names are well-formed according to your coding +standard, whether declared interfaces are fully implemented, and more. +https://docs.pylint.org/ provides a full list of Pylint's features. How can I create a stand-alone binary from a Python script? @@ -365,8 +371,8 @@ compute, a common technique is to cache the parameters and the resulting value of each call to the function, and return the cached value if the same value is requested again. This is called "memoizing", and can be implemented like this:: - # Callers can only provide two parameters and optionally pass _cache by keyword - def expensive(arg1, arg2, *, _cache={}): + # Callers will never provide a third parameter for this function. + def expensive(arg1, arg2, _cache={}): if (arg1, arg2) in _cache: return _cache[(arg1, arg2)] @@ -504,14 +510,14 @@ desired effect in a number of ways. 1) By returning a tuple of the results:: - >>> def func1(a, b): - ... a = 'new-value' # a and b are local names - ... b = b + 1 # assigned to new objects - ... return a, b # return new values - ... - >>> x, y = 'old-value', 99 - >>> func1(x, y) - ('new-value', 100) + def func2(a, b): + a = 'new-value' # a and b are local names + b = b + 1 # assigned to new objects + return a, b # return new values + + x, y = 'old-value', 99 + x, y = func2(x, y) + print(x, y) # output: new-value 100 This is almost always the clearest solution. @@ -519,41 +525,38 @@ desired effect in a number of ways. 3) By passing a mutable (changeable in-place) object:: - >>> def func2(a): - ... a[0] = 'new-value' # 'a' references a mutable list - ... a[1] = a[1] + 1 # changes a shared object - ... - >>> args = ['old-value', 99] - >>> func2(args) - >>> args - ['new-value', 100] + def func1(a): + a[0] = 'new-value' # 'a' references a mutable list + a[1] = a[1] + 1 # changes a shared object + + args = ['old-value', 99] + func1(args) + print(args[0], args[1]) # output: new-value 100 4) By passing in a dictionary that gets mutated:: - >>> def func3(args): - ... args['a'] = 'new-value' # args is a mutable dictionary - ... args['b'] = args['b'] + 1 # change it in-place - ... - >>> args = {'a': 'old-value', 'b': 99} - >>> func3(args) - >>> args - {'a': 'new-value', 'b': 100} + def func3(args): + args['a'] = 'new-value' # args is a mutable dictionary + args['b'] = args['b'] + 1 # change it in-place + + args = {'a': 'old-value', 'b': 99} + func3(args) + print(args['a'], args['b']) 5) Or bundle up values in a class instance:: - >>> class Namespace: - ... def __init__(self, /, **args): - ... for key, value in args.items(): - ... setattr(self, key, value) - ... - >>> def func4(args): - ... args.a = 'new-value' # args is a mutable Namespace - ... args.b = args.b + 1 # change object in-place - ... - >>> args = Namespace(a='old-value', b=99) - >>> func4(args) - >>> vars(args) - {'a': 'new-value', 'b': 100} + class callByRef: + def __init__(self, **args): + for (key, value) in args.items(): + setattr(self, key, value) + + def func4(args): + args.a = 'new-value' # args is a mutable callByRef + args.b = args.b + 1 # change object in-place + + args = callByRef(a='old-value', b=99) + func4(args) + print(args.a, args.b) There's almost never a good reason to get this complicated. @@ -648,7 +651,7 @@ How can my code discover the name of an object? ----------------------------------------------- Generally speaking, it can't, because objects don't really have names. -Essentially, assignment always binds a name to a value; the same is true of +Essentially, assignment always binds a name to a value; The same is true of ``def`` and ``class`` statements, but in that case the value is a callable. Consider the following code:: @@ -730,7 +733,7 @@ Is it possible to write obfuscated one-liners in Python? -------------------------------------------------------- Yes. Usually this is done by nesting :keyword:`lambda` within -:keyword:`!lambda`. See the following three examples, due to Ulf Bartelt:: +:keyword:`lambda`. See the following three examples, due to Ulf Bartelt:: from functools import reduce @@ -759,34 +762,6 @@ Yes. Usually this is done by nesting :keyword:`lambda` within Don't try this at home, kids! -.. _faq-positional-only-arguments: - -What does the slash(/) in the parameter list of a function mean? ----------------------------------------------------------------- - -A slash in the argument list of a function denotes that the parameters prior to -it are positional-only. Positional-only parameters are the ones without an -externally-usable name. Upon calling a function that accepts positional-only -parameters, arguments are mapped to parameters based solely on their position. -For example, :func:`divmod` is a function that accepts positional-only -parameters. Its documentation looks like this:: - - >>> help(divmod) - Help on built-in function divmod in module builtins: - - divmod(x, y, /) - Return the tuple (x//y, x%y). Invariant: div*y + mod == x. - -The slash at the end of the parameter list means that both parameters are -positional-only. Thus, calling :func:`divmod` with keyword arguments would lead -to an error:: - - >>> divmod(x=3, y=4) - Traceback (most recent call last): - File "", line 1, in - TypeError: divmod() takes no keyword arguments - - Numbers and strings =================== @@ -813,6 +788,8 @@ or uppercase. For example, in the Python interpreter:: 178 +.. _faq-floordivision: + Why does -22 // 10 return -3? ----------------------------- @@ -821,10 +798,13 @@ If you want that, and also want:: i == (i // j) * j + (i % j) -then integer division has to return the floor. C also requires that identity to -hold, and then compilers that truncate ``i // j`` need to make ``i % j`` have +then integer division has to return the floor, and Floor division rounds towards -infinity. +C also requires that identity to hold, and then compilers that truncate ``i // j`` need to make ``i % j`` have the same sign as ``i``. +Note that the identity and the definition of floor division also means that ``(i % -j) != - (i % j)``. For example +with i and j being 22 and -12 respectively then``22 // -12 == -2`` and therefore ``22 % -12 == -2`` + There are few real use cases for ``i % j`` when ``j`` is negative. When ``j`` is positive, there are many, and in virtually all of them it's more useful for ``i % j`` to be ``>= 0``. If the clock says 10 now, what did it say 200 hours @@ -840,11 +820,10 @@ For integers, use the built-in :func:`int` type constructor, e.g. ``int('144') e.g. ``float('144') == 144.0``. By default, these interpret the number as decimal, so that ``int('0144') == -144`` holds true, and ``int('0x144')`` raises :exc:`ValueError`. ``int(string, -base)`` takes the base to convert from as a second optional argument, so ``int( -'0x144', 16) == 324``. If the base is specified as 0, the number is interpreted -using Python's rules: a leading '0o' indicates octal, and '0x' indicates a hex -number. +144`` and ``int('0x144')`` raises :exc:`ValueError`. ``int(string, base)`` takes +the base to convert from as a second optional argument, so ``int('0x144', 16) == +324``. If the base is specified as 0, the number is interpreted using Python's +rules: a leading '0o' indicates octal, and '0x' indicates a hex number. Do not use the built-in function :func:`eval` if all you need is to convert strings to numbers. :func:`eval` will be significantly slower and it presents a @@ -942,7 +921,7 @@ There are various techniques. f() -* Use :func:`locals` to resolve the function name:: +* Use :func:`locals` or :func:`eval` to resolve the function name:: def myFunc(): print("hello") @@ -952,6 +931,12 @@ There are various techniques. f = locals()[fname] f() + f = eval(fname) + f() + + Note: Using :func:`eval` is slow and dangerous. If you don't have absolute + control over the contents of the string, someone could pass a string that + resulted in an arbitrary function being executed. Is there an equivalent to Perl's chomp() for removing trailing newlines from strings? ------------------------------------------------------------------------------------- @@ -1003,7 +988,7 @@ That's a tough one, in general. First, here are a list of things to remember before diving further: * Performance characteristics vary across Python implementations. This FAQ - focuses on :term:`CPython`. + focusses on :term:`CPython`. * Behaviour can vary across operating systems, especially when talking about I/O or multi-threading. * You should always find the hot spots in your program *before* attempting to @@ -1116,7 +1101,7 @@ trailing newline from a string. How do I iterate over a sequence in reverse order? -------------------------------------------------- -Use the :func:`reversed` built-in function:: +Use the :func:`reversed` built-in function, which is new in Python 2.4:: for x in reversed(sequence): ... # do something with x ... @@ -1124,6 +1109,11 @@ Use the :func:`reversed` built-in function:: This won't touch your original sequence, but build a new copy with reversed order to iterate over. +With Python 2.3, you can use an extended slice syntax:: + + for x in sequence[::-1]: + ... # do something with x ... + How do you remove duplicates from a list? ----------------------------------------- @@ -1153,21 +1143,6 @@ This converts the list into a set, thereby removing duplicates, and then back into a list. -How do you remove multiple items from a list --------------------------------------------- - -As with removing duplicates, explicitly iterating in reverse with a -delete condition is one possibility. However, it is easier and faster -to use slice replacement with an implicit or explicit forward iteration. -Here are three variations.:: - - mylist[:] = filter(keep_function, mylist) - mylist[:] = (x for x in mylist if keep_condition) - mylist[:] = [x for x in mylist if keep_condition] - -The list comprehension may be fastest. - - How do you make an array in Python? ----------------------------------- @@ -1180,7 +1155,7 @@ difference is that a Python list can contain objects of many different types. The ``array`` module also provides methods for creating arrays of fixed types with compact representations, but they are slower to index than lists. Also -note that NumPy and other third party packages define array-like structures with +note that the Numeric extensions and others define array-like structures with various characteristics as well. To get Lisp-style linked lists, you can emulate cons cells using tuples:: @@ -1342,6 +1317,14 @@ The ``__iadd__`` succeeds, and thus the list is extended, but even though that final assignment still results in an error, because tuples are immutable. +Dictionaries +============ + +How can I get a dictionary to store and display its keys in a consistent order? +------------------------------------------------------------------------------- + +Use :class:`collections.OrderedDict`. + I want to do a complicated sort: can you do a Schwartzian Transform in Python? ------------------------------------------------------------------------------ @@ -1370,6 +1353,20 @@ out the element you want. :: ['else', 'sort', 'to', 'something'] +An alternative for the last step is:: + + >>> result = [] + >>> for p in pairs: result.append(p[1]) + +If you find this more legible, you might prefer to use this instead of the final +list comprehension. However, it is almost twice as slow for long lists. Why? +First, the ``append()`` operation has to reallocate memory, and while it uses +some tricks to avoid doing that each time, it still has to do it occasionally, +and that costs quite a bit. Second, the expression "result.append" requires an +extra attribute lookup, and third, there's a speed reduction from having to make +all those function calls. + + Objects ======= @@ -1420,41 +1417,6 @@ single class, e.g. ``isinstance(obj, (class1, class2, ...))``, and can also check whether an object is one of Python's built-in types, e.g. ``isinstance(obj, str)`` or ``isinstance(obj, (int, float, complex))``. -Note that :func:`isinstance` also checks for virtual inheritance from an -:term:`abstract base class`. So, the test will return ``True`` for a -registered class even if hasn't directly or indirectly inherited from it. To -test for "true inheritance", scan the :term:`MRO` of the class: - -.. testcode:: - - from collections.abc import Mapping - - class P: - pass - - class C(P): - pass - - Mapping.register(P) - -.. doctest:: - - >>> c = C() - >>> isinstance(c, C) # direct - True - >>> isinstance(c, P) # indirect - True - >>> isinstance(c, Mapping) # virtual - True - - # Actual inheritance chain - >>> type(c).__mro__ - (, , ) - - # Test for "true inheritance" - >>> Mapping in type(c).__mro__ - False - Note that most programs do not use :func:`isinstance` on user-defined classes very often. If you are developing the classes yourself, a more proper object-oriented style is to define methods on the classes that encapsulate a @@ -1509,8 +1471,8 @@ to uppercase:: Here the ``UpperOut`` class redefines the ``write()`` method to convert the argument string to uppercase before calling the underlying -``self._outfile.write()`` method. All other methods are delegated to the -underlying ``self._outfile`` object. The delegation is accomplished via the +``self.__outfile.write()`` method. All other methods are delegated to the +underlying ``self.__outfile`` object. The delegation is accomplished via the ``__getattr__`` method; consult :ref:`the language reference ` for more information about controlling attribute access. @@ -1529,36 +1491,37 @@ Most :meth:`__setattr__` implementations must modify ``self.__dict__`` to store local state for self without causing an infinite recursion. -How do I call a method defined in a base class from a derived class that extends it? ------------------------------------------------------------------------------------- +How do I call a method defined in a base class from a derived class that overrides it? +-------------------------------------------------------------------------------------- Use the built-in :func:`super` function:: class Derived(Base): def meth(self): - super().meth() # calls Base.meth + super(Derived, self).meth() -In the example, :func:`super` will automatically determine the instance from -which it was called (the ``self`` value), look up the :term:`method resolution -order` (MRO) with ``type(self).__mro__``, and return the next in line after -``Derived`` in the MRO: ``Base``. +For version prior to 3.0, you may be using classic classes: For a class +definition such as ``class Derived(Base): ...`` you can call method ``meth()`` +defined in ``Base`` (or one of ``Base``'s base classes) as ``Base.meth(self, +arguments...)``. Here, ``Base.meth`` is an unbound method, so you need to +provide the ``self`` argument. How can I organize my code to make it easier to change the base class? ---------------------------------------------------------------------- -You could assign the base class to an alias and derive from the alias. Then all +You could define an alias for the base class, assign the real base class to it +before your class definition, and use the alias throughout your class. Then all you have to change is the value assigned to the alias. Incidentally, this trick is also handy if you want to decide dynamically (e.g. depending on availability of resources) which base class to use. Example:: - class Base: - ... - - BaseAlias = Base + BaseAlias = class Derived(BaseAlias): - ... + def meth(self): + BaseAlias.meth(self) + ... How do I create static class data and static class methods? @@ -1736,93 +1699,6 @@ to the object: 13891296 -When can I rely on identity tests with the *is* operator? ---------------------------------------------------------- - -The ``is`` operator tests for object identity. The test ``a is b`` is -equivalent to ``id(a) == id(b)``. - -The most important property of an identity test is that an object is always -identical to itself, ``a is a`` always returns ``True``. Identity tests are -usually faster than equality tests. And unlike equality tests, identity tests -are guaranteed to return a boolean ``True`` or ``False``. - -However, identity tests can *only* be substituted for equality tests when -object identity is assured. Generally, there are three circumstances where -identity is guaranteed: - -1) Assignments create new names but do not change object identity. After the -assignment ``new = old``, it is guaranteed that ``new is old``. - -2) Putting an object in a container that stores object references does not -change object identity. After the list assignment ``s[0] = x``, it is -guaranteed that ``s[0] is x``. - -3) If an object is a singleton, it means that only one instance of that object -can exist. After the assignments ``a = None`` and ``b = None``, it is -guaranteed that ``a is b`` because ``None`` is a singleton. - -In most other circumstances, identity tests are inadvisable and equality tests -are preferred. In particular, identity tests should not be used to check -constants such as :class:`int` and :class:`str` which aren't guaranteed to be -singletons:: - - >>> a = 1000 - >>> b = 500 - >>> c = b + 500 - >>> a is c - False - - >>> a = 'Python' - >>> b = 'Py' - >>> c = b + 'thon' - >>> a is c - False - -Likewise, new instances of mutable containers are never identical:: - - >>> a = [] - >>> b = [] - >>> a is b - False - -In the standard library code, you will see several common patterns for -correctly using identity tests: - -1) As recommended by :pep:`8`, an identity test is the preferred way to check -for ``None``. This reads like plain English in code and avoids confusion with -other objects that may have boolean values that evaluate to false. - -2) Detecting optional arguments can be tricky when ``None`` is a valid input -value. In those situations, you can create an singleton sentinel object -guaranteed to be distinct from other objects. For example, here is how -to implement a method that behaves like :meth:`dict.pop`:: - - _sentinel = object() - - def pop(self, key, default=_sentinel): - if key in self: - value = self[key] - del self[key] - return value - if default is _sentinel: - raise KeyError(key) - return default - -3) Container implementations sometimes need to augment equality tests with -identity tests. This prevents the code from being confused by objects such as -``float('NaN')`` that are not equal to themselves. - -For example, here is the implementation of -:meth:`collections.abc.Sequence.__contains__`:: - - def __contains__(self, value): - for v in self: - if v is value or v == value: - return True - return False - - Modules ======= diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 0929f3271e0519..a881e410d9055a 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -20,10 +20,10 @@ rearrange their members in place, and don't return a specific item, never return the collection instance itself but ``None``. Some operations are supported by several object types; in particular, -practically all objects can be compared for equality, tested for truth -value, and converted to a string (with the :func:`repr` function or the -slightly different :func:`str` function). The latter function is implicitly -used when an object is written by the :func:`print` function. +practically all objects can be compared, tested for truth value, and converted +to a string (with the :func:`repr` function or the slightly different +:func:`str` function). The latter function is implicitly used when an object is +written by the :func:`print` function. .. _truth: @@ -74,8 +74,8 @@ one of their operands.) .. _boolean: -Boolean Operations --- :keyword:`!and`, :keyword:`!or`, :keyword:`!not` -======================================================================= +Boolean Operations --- :keyword:`and`, :keyword:`or`, :keyword:`not` +==================================================================== .. index:: pair: Boolean; operations @@ -123,9 +123,9 @@ Comparisons pair: chaining; comparisons pair: operator; comparison operator: == - operator: < (less) + operator: < operator: <= - operator: > (greater) + operator: > operator: >= operator: != operator: is @@ -164,10 +164,12 @@ This table summarizes the comparison operations: pair: objects; comparing Objects of different types, except different numeric types, never compare equal. -The ``==`` operator is always defined but for some object types (for example, -class objects) is equivalent to :keyword:`is`. The ``<``, ``<=``, ``>`` and ``>=`` -operators are only defined where they make sense; for example, they raise a -:exc:`TypeError` exception when one of the arguments is a complex number. +Furthermore, some types (for example, function objects) support only a degenerate +notion of comparison where any two objects of that type are unequal. The ``<``, +``<=``, ``>`` and ``>=`` operators will raise a :exc:`TypeError` exception when +comparing a complex number with another built-in numeric type, when the objects +are of different types that cannot be compared, or in other cases where there is +no defined ordering. .. index:: single: __eq__() (instance method) @@ -195,8 +197,8 @@ exception. operator: not in Two more operations with the same syntactic priority, :keyword:`in` and -:keyword:`not in`, are supported by types that are :term:`iterable` or -implement the :meth:`__contains__` method. +:keyword:`not in`, are supported only by sequence types (below). + .. _typesnumeric: @@ -220,8 +222,8 @@ numbers for the machine on which your program is running is available in :data:`sys.float_info`. Complex numbers have a real and imaginary part, which are each a floating point number. To extract these parts from a complex number *z*, use ``z.real`` and ``z.imag``. (The standard -library includes the additional numeric types :mod:`fractions.Fraction`, for -rationals, and :mod:`decimal.Decimal`, for floating-point numbers with +library includes additional numeric types, :mod:`fractions` that hold +rationals, and :mod:`decimal` that hold floating-point numbers with user-definable precision.) .. index:: @@ -246,29 +248,24 @@ and imaginary parts. builtin: int builtin: float builtin: complex - single: operator; + (plus) - single: + (plus); unary operator - single: + (plus); binary operator - single: operator; - (minus) - single: - (minus); unary operator - single: - (minus); binary operator - operator: * (asterisk) - operator: / (slash) + operator: + + operator: - + operator: * + operator: / operator: // - operator: % (percent) + operator: % operator: ** Python fully supports mixed arithmetic: when a binary arithmetic operator has operands of different numeric types, the operand with the "narrower" type is widened to that of the other, where integer is narrower than floating point, -which is narrower than complex. A comparison between numbers of different types -behaves as though the exact values of those numbers were being compared. [2]_ - -The constructors :func:`int`, :func:`float`, and +which is narrower than complex. Comparisons between numbers of mixed type use +the same rule. [2]_ The constructors :func:`int`, :func:`float`, and :func:`complex` can be used to produce numbers of a specific type. -All numeric types (except complex) support the following operations (for priorities of -the operations, see :ref:`operator-summary`): +All numeric types (except complex) support the following operations, sorted by +ascending priority (all numeric operations have a higher priority than +comparison operations): +---------------------+---------------------------------+---------+--------------------+ | Operation | Result | Notes | Full documentation | @@ -326,6 +323,8 @@ Notes: (2) Not for complex numbers. Instead convert to floats using :func:`abs` if appropriate. + For non-complex numbers x and y the identity ``x = (x//y)*y + (x%y)`` always holds. + See :ref:`faq-floordivision` for more details. (3) .. index:: @@ -352,7 +351,7 @@ Notes: The numeric literals accepted include the digits ``0`` to ``9`` or any Unicode equivalent (code points with the ``Nd`` property). - See https://www.unicode.org/Public/13.0.0/ucd/extracted/DerivedNumericType.txt + See http://www.unicode.org/Public/10.0.0/ucd/extracted/DerivedNumericType.txt for a complete list of code points with the ``Nd`` property. @@ -385,23 +384,23 @@ modules. .. _bitstring-ops: Bitwise Operations on Integer Types ------------------------------------ +-------------------------------------- .. index:: triple: operations on; integer; types pair: bitwise; operations pair: shifting; operations pair: masking; operations - operator: | (vertical bar) - operator: ^ (caret) - operator: & (ampersand) + operator: | + operator: ^ + operator: & operator: << operator: >> - operator: ~ (tilde) + operator: ~ -Bitwise operations only make sense for integers. The result of bitwise -operations is calculated as though carried out in two's complement with an -infinite number of sign bits. +Bitwise operations only make sense for integers. Negative numbers are treated +as their 2's complement value (this assumes that there are enough bits so that +no overflow occurs during the operation). The priorities of the binary bitwise operations are all lower than the numeric operations and higher than the comparisons; the unary operation ``~`` has the @@ -412,13 +411,13 @@ This table lists the bitwise operations sorted in ascending priority: +------------+--------------------------------+----------+ | Operation | Result | Notes | +============+================================+==========+ -| ``x | y`` | bitwise :dfn:`or` of *x* and | \(4) | +| ``x | y`` | bitwise :dfn:`or` of *x* and | | | | *y* | | +------------+--------------------------------+----------+ -| ``x ^ y`` | bitwise :dfn:`exclusive or` of | \(4) | +| ``x ^ y`` | bitwise :dfn:`exclusive or` of | | | | *x* and *y* | | +------------+--------------------------------+----------+ -| ``x & y`` | bitwise :dfn:`and` of *x* and | \(4) | +| ``x & y`` | bitwise :dfn:`and` of *x* and | | | | *y* | | +------------+--------------------------------+----------+ | ``x << n`` | *x* shifted left by *n* bits | (1)(2) | @@ -434,16 +433,12 @@ Notes: Negative shift counts are illegal and cause a :exc:`ValueError` to be raised. (2) - A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``. + A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)`` + without overflow check. (3) - A right shift by *n* bits is equivalent to floor division by ``pow(2, n)``. - -(4) - Performing these calculations with at least one extra sign extension bit in - a finite two's complement representation (a working bit-width of - ``1 + max(x.bit_length(), y.bit_length())`` or more) is sufficient to get the - same result as if there were an infinite number of sign bits. + A right shift by *n* bits is equivalent to division by ``pow(2, n)`` without + overflow check. Additional Methods on Integer Types @@ -478,28 +473,7 @@ class`. In addition, it provides a few more methods: .. versionadded:: 3.1 -.. method:: int.bit_count() - - Return the number of ones in the binary representation of the absolute - value of the integer. This is also known as the population count. - Example:: - - >>> n = 19 - >>> bin(n) - '0b10011' - >>> n.bit_count() - 3 - >>> (-n).bit_count() - 3 - - Equivalent to:: - - def bit_count(self): - return bin(self).count("1") - - .. versionadded:: 3.10 - -.. method:: int.to_bytes(length, byteorder, *, signed=False) +.. method:: int.to_bytes(length, byteorder, \*, signed=False) Return an array of bytes representing an integer. @@ -531,7 +505,7 @@ class`. In addition, it provides a few more methods: .. versionadded:: 3.2 -.. classmethod:: int.from_bytes(bytes, byteorder, *, signed=False) +.. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False) Return the integer represented by the given array of bytes. @@ -561,14 +535,6 @@ class`. In addition, it provides a few more methods: .. versionadded:: 3.2 -.. method:: int.as_integer_ratio() - - Return a pair of integers whose ratio is exactly equal to the original - integer and with a positive denominator. The integer ratio of integers - (whole numbers) is always the integer as the numerator and ``1`` as the - denominator. - - .. versionadded:: 3.8 Additional Methods on Float --------------------------- @@ -1095,10 +1061,10 @@ accepts integers that meet the value restriction ``0 <= x <= 255``). | | sequence (same as | | | | ``s[len(s):len(s)] = [x]``) | | +------------------------------+--------------------------------+---------------------+ -| ``s.clear()`` | removes all items from *s* | \(5) | +| ``s.clear()`` | removes all items from ``s`` | \(5) | | | (same as ``del s[:]``) | | +------------------------------+--------------------------------+---------------------+ -| ``s.copy()`` | creates a shallow copy of *s* | \(5) | +| ``s.copy()`` | creates a shallow copy of ``s``| \(5) | | | (same as ``s[:]``) | | +------------------------------+--------------------------------+---------------------+ | ``s.extend(t)`` or | extends *s* with the | | @@ -1134,7 +1100,7 @@ Notes: item is removed and returned. (3) - :meth:`remove` raises :exc:`ValueError` when *x* is not found in *s*. + ``remove`` raises :exc:`ValueError` when *x* is not found in *s*. (4) The :meth:`reverse` method modifies the sequence in place for economy of @@ -1144,9 +1110,7 @@ Notes: (5) :meth:`clear` and :meth:`!copy` are included for consistency with the interfaces of mutable containers that don't support slicing operations - (such as :class:`dict` and :class:`set`). :meth:`!copy` is not part of the - :class:`collections.abc.MutableSequence` ABC, but most concrete - mutable sequence classes provide it. + (such as :class:`dict` and :class:`set`) .. versionadded:: 3.3 :meth:`clear` and :meth:`!copy` methods. @@ -1227,8 +1191,6 @@ application). --- 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 :ref:`sortinghowto`. - .. impl-detail:: While a list is being sorted, the effect of attempting to mutate, or even @@ -1405,7 +1367,7 @@ objects that compare equal might have different :attr:`~range.start`, .. seealso:: * The `linspace recipe `_ - shows how to implement a lazy version of range suitable for floating + shows how to implement a lazy version of range that suitable for floating point applications. .. index:: @@ -1531,10 +1493,6 @@ expression support in the :mod:`re` module). Return a copy of the string with its first character capitalized and the rest lowercased. - .. versionchanged:: 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. .. method:: str.casefold() @@ -1579,16 +1537,9 @@ expression support in the :mod:`re` module). :func:`codecs.register_error`, see section :ref:`error-handlers`. For a list of possible encodings, see section :ref:`standard-encodings`. - By default, the *errors* argument is not checked for best performances, but - only used at the first encoding error. Enable the :ref:`Python Development - Mode `, or use a debug build to check *errors*. - .. versionchanged:: 3.1 Support for keyword arguments added. - .. versionchanged:: 3.9 - The *errors* is now checked in development mode and in debug mode. - .. method:: str.endswith(suffix[, start[, end]]) @@ -1651,14 +1602,13 @@ expression support in the :mod:`re` module). that can be specified in format strings. .. note:: - When formatting a number (:class:`int`, :class:`float`, :class:`complex`, - :class:`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 :c:func:`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. + When formatting a number (:class:`int`, :class:`float`, :class:`float` + and subclasses) with the ``n`` type (ex: ``'{:n}'.format(1234)``), the + function sets temporarily the ``LC_CTYPE`` locale to the ``LC_NUMERIC`` + locale to decode ``decimal_point`` and ``thousands_sep`` fields of + :c:func:`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. .. versionchanged:: 3.7 When formatting a number with the ``n`` type, the function sets @@ -1690,16 +1640,16 @@ expression support in the :mod:`re` module). .. method:: 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 + 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()``. .. method:: 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 + 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 Unicode Standard. @@ -1707,8 +1657,8 @@ expression support in the :mod:`re` module). .. method:: str.isascii() - Return ``True`` if the string is empty or all characters in the string are ASCII, - ``False`` otherwise. + 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. .. versionadded:: 3.7 @@ -1716,8 +1666,8 @@ expression support in the :mod:`re` module). .. method:: str.isdecimal() - Return ``True`` if all characters in the string are decimal - characters and there is at least one character, ``False`` + 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 @@ -1726,8 +1676,8 @@ expression support in the :mod:`re` module). .. method:: 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 + 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 @@ -1736,33 +1686,22 @@ expression support in the :mod:`re` module). .. method:: str.isidentifier() - Return ``True`` if the string is a valid identifier according to the language + Return true if the string is a valid identifier according to the language definition, section :ref:`identifiers`. - Call :func:`keyword.iskeyword` to test whether string ``s`` is a reserved - identifier, such as :keyword:`def` and :keyword:`class`. - - Example: - :: - - >>> from keyword import iskeyword - - >>> 'hello'.isidentifier(), iskeyword('hello') - True, False - >>> 'def'.isidentifier(), iskeyword('def') - True, True - + Use :func:`keyword.iskeyword` to test for reserved identifiers such as + :keyword:`def` and :keyword:`class`. .. method:: str.islower() - Return ``True`` if all cased characters [4]_ in the string are lowercase and - there is at least one cased character, ``False`` otherwise. + Return true if all cased characters [4]_ in the string are lowercase and + there is at least one cased character, false otherwise. .. method:: str.isnumeric() - Return ``True`` if all characters in the string are numeric - characters, and there is at least one character, ``False`` + 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 @@ -1771,8 +1710,8 @@ expression support in the :mod:`re` module). .. method:: 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 + 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 @@ -1782,36 +1721,22 @@ expression support in the :mod:`re` module). .. method:: 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 :mod:`unicodedata`), either its general category is ``Zs`` - ("Separator, space"), or its bidirectional class is one of ``WS``, - ``B``, or ``S``. - + Return true if there are only whitespace characters in the string and there is + at least one character, false otherwise. Whitespace characters are those + characters defined in the Unicode character database as "Other" or "Separator" + and those with bidirectional property being one of "WS", "B", or "S". .. method:: str.istitle() - Return ``True`` if the string is a titlecased string and there is at least one + 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. + and lowercase characters only cased ones. Return false otherwise. .. method:: 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 - + Return true if all cased characters [4]_ in the string are uppercase and + there is at least one cased character, false otherwise. .. method:: str.join(iterable) @@ -1850,14 +1775,6 @@ expression support in the :mod:`re` module). >>> 'www.example.com'.lstrip('cmowz.') 'example.com' - See :meth:`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!' - .. staticmethod:: str.maketrans(x[, y[, z]]) @@ -1882,34 +1799,6 @@ expression support in the :mod:`re` module). the string itself, followed by two empty strings. -.. method:: 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' - - .. versionadded:: 3.9 - - -.. method:: 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' - - .. versionadded:: 3.9 - - .. method:: str.replace(old, new[, count]) Return a copy of the string with all occurrences of substring *old* replaced by @@ -1966,13 +1855,6 @@ expression support in the :mod:`re` module). >>> 'mississippi'.rstrip('ipz') 'mississ' - See :meth:`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' .. method:: str.split(sep=None, maxsplit=-1) @@ -2142,7 +2024,8 @@ expression support in the :mod:`re` module). >>> import re >>> def titlecase(s): ... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?", - ... lambda mo: mo.group(0).capitalize(), + ... lambda mo: mo.group(0)[0].upper() + + ... mo.group(0)[1:].lower(), ... s) ... >>> titlecase("they're bill's friends.") @@ -2170,7 +2053,7 @@ expression support in the :mod:`re` module). .. method:: 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`` + uppercase. Note that ``str.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). @@ -2208,7 +2091,8 @@ expression support in the :mod:`re` module). single: string; interpolation, printf single: printf-style formatting single: sprintf-style formatting - single: % (percent); printf-style formatting + single: % formatting + single: % interpolation .. note:: @@ -2231,11 +2115,6 @@ object. [5]_ Otherwise, *values* must be a tuple with exactly the number of items specified by the format string, or a single mapping object (for example, a dictionary). -.. index:: - single: () (parentheses); in printf-style formatting - single: * (asterisk); in printf-style formatting - single: . (dot); in printf-style formatting - A conversion specifier contains two or more characters and has the following components, which must occur in this order: @@ -2274,12 +2153,6 @@ sequential parameter list). The conversion flag characters are: -.. index:: - single: # (hash); in printf-style formatting - single: - (minus); in printf-style formatting - single: + (plus); in printf-style formatting - single: space; in printf-style formatting - +---------+---------------------------------------------------------------------+ | Flag | Meaning | +=========+=====================================================================+ @@ -2444,7 +2317,7 @@ data and are closely related to string objects in a variety of other ways. While bytes literals and representations are based on ASCII text, bytes objects actually behave like immutable sequences of integers, with each value in the sequence restricted such that ``0 <= x < 256`` (attempts to - violate this restriction will trigger :exc:`ValueError`). This is done + violate this restriction will trigger :exc:`ValueError`. This is done deliberately to emphasise that while many binary formats include ASCII based elements and can be usefully manipulated with some text-oriented algorithms, this is not generally the case for arbitrary binary data (blindly applying @@ -2480,7 +2353,7 @@ data and are closely related to string objects in a variety of other ways. A reverse conversion function exists to transform a bytes object into its hexadecimal representation. - .. method:: hex([sep[, bytes_per_sep]]) + .. method:: hex() Return a string object containing two hexadecimal digits for each byte in the instance. @@ -2488,26 +2361,8 @@ data and are closely related to string objects in a variety of other ways. >>> b'\xf0\xf1\xf2'.hex() 'f0f1f2' - If you want to make the hex string easier to read, you can specify a - single character separator *sep* parameter to include in the output. - By default between each byte. A second optional *bytes_per_sep* - parameter controls the spacing. Positive values calculate the - separator position from the right, negative values from the left. - - >>> value = b'\xf0\xf1\xf2' - >>> value.hex('-') - 'f0-f1-f2' - >>> value.hex('_', 2) - 'f0_f1f2' - >>> b'UUDDLRLRAB'.hex(' ', -4) - '55554444 4c524c52 4142' - .. versionadded:: 3.5 - .. versionchanged:: 3.8 - :meth:`bytes.hex` now supports optional *sep* and *bytes_per_sep* - parameters to insert separators between bytes in the hex output. - Since bytes objects are sequences of integers (akin to a tuple), for a bytes object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be a bytes object of length 1. (This contrasts with text strings, where both indexing @@ -2574,7 +2429,7 @@ objects. A reverse conversion function exists to transform a bytearray object into its hexadecimal representation. - .. method:: hex([sep[, bytes_per_sep]]) + .. method:: hex() Return a string object containing two hexadecimal digits for each byte in the instance. @@ -2584,11 +2439,6 @@ objects. .. versionadded:: 3.5 - .. versionchanged:: 3.8 - Similar to :meth:`bytes.hex`, :meth:`bytearray.hex` now supports - optional *sep* and *bytes_per_sep* parameters to insert separators - between bytes in the hex output. - Since bytearray objects are sequences of integers (akin to a list), for a bytearray object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be a bytearray object of length 1. (This contrasts with text strings, where @@ -2653,50 +2503,6 @@ arbitrary binary data. Also accept an integer in the range 0 to 255 as the subsequence. -.. method:: bytes.removeprefix(prefix, /) - bytearray.removeprefix(prefix, /) - - If the binary data starts with the *prefix* string, return - ``bytes[len(prefix):]``. Otherwise, return a copy of the original - binary data:: - - >>> b'TestHook'.removeprefix(b'Test') - b'Hook' - >>> b'BaseTestCase'.removeprefix(b'Test') - b'BaseTestCase' - - The *prefix* may be any :term:`bytes-like object`. - - .. note:: - - The bytearray version of this method does *not* operate in place - - it always produces a new object, even if no changes were made. - - .. versionadded:: 3.9 - - -.. method:: bytes.removesuffix(suffix, /) - bytearray.removesuffix(suffix, /) - - If the binary data ends with the *suffix* string and that *suffix* is - not empty, return ``bytes[:-len(suffix)]``. Otherwise, return a copy of - the original binary data:: - - >>> b'MiscTests'.removesuffix(b'Tests') - b'Misc' - >>> b'TmpDirMixin'.removesuffix(b'Tests') - b'TmpDirMixin' - - The *suffix* may be any :term:`bytes-like object`. - - .. note:: - - The bytearray version of this method does *not* operate in place - - it always produces a new object, even if no changes were made. - - .. versionadded:: 3.9 - - .. method:: bytes.decode(encoding="utf-8", errors="strict") bytearray.decode(encoding="utf-8", errors="strict") @@ -2708,10 +2514,6 @@ arbitrary binary data. :func:`codecs.register_error`, see section :ref:`error-handlers`. For a list of possible encodings, see section :ref:`standard-encodings`. - By default, the *errors* argument is not checked for best performances, but - only used at the first decoding error. Enable the :ref:`Python Development - Mode `, or use a debug build to check *errors*. - .. note:: Passing the *encoding* argument to :class:`str` allows decoding any @@ -2721,9 +2523,6 @@ arbitrary binary data. .. versionchanged:: 3.1 Added support for keyword arguments. - .. versionchanged:: 3.9 - The *errors* is now checked in development mode and in debug mode. - .. method:: bytes.endswith(suffix[, start[, end]]) bytearray.endswith(suffix[, start[, end]]) @@ -2859,8 +2658,8 @@ arbitrary binary data. containing the part before the separator, the separator itself or its bytearray copy, and the part after the separator. If the separator is not found, return a 3-tuple - containing two empty bytes or bytearray objects, followed by a copy of the - original sequence. + containing a copy of the original sequence, followed by two empty bytes or + bytearray objects. The separator to search for may be any :term:`bytes-like object`. @@ -2876,8 +2675,8 @@ arbitrary binary data. The prefix(es) to search for may be any :term:`bytes-like object`. -.. method:: bytes.translate(table, /, delete=b'') - bytearray.translate(table, /, delete=b'') +.. method:: bytes.translate(table, delete=b'') + bytearray.translate(table, delete=b'') Return a copy of the bytes or bytearray object where all bytes occurring in the optional argument *delete* are removed, and the remaining bytes have @@ -2947,14 +2746,7 @@ produce new objects. b'example.com' The binary sequence of byte values to remove may be any - :term:`bytes-like object`. See :meth:`~bytes.removeprefix` for a method - that will remove a single prefix string rather than all of a set of - characters. For example:: - - >>> b'Arthur: three!'.lstrip(b'Arthur: ') - b'ee!' - >>> b'Arthur: three!'.removeprefix(b'Arthur: ') - b'three!' + :term:`bytes-like object`. .. note:: @@ -3003,14 +2795,7 @@ produce new objects. b'mississ' The binary sequence of byte values to remove may be any - :term:`bytes-like object`. See :meth:`~bytes.removesuffix` for a method - that will remove a single suffix string rather than all of a set of - characters. For example:: - - >>> b'Monty Python'.rstrip(b' Python') - b'M' - >>> b'Monty Python'.removesuffix(b' Python') - b'Monty' + :term:`bytes-like object`. .. note:: @@ -3137,8 +2922,8 @@ place, and instead produce new objects. .. method:: bytes.isalnum() bytearray.isalnum() - Return ``True`` if all bytes in the sequence are alphabetical ASCII characters - or ASCII decimal digits and the sequence is not empty, ``False`` otherwise. + Return true if all bytes in the sequence are alphabetical ASCII characters + or ASCII decimal digits and the sequence is not empty, false otherwise. Alphabetic ASCII characters are those byte values in the sequence ``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. ASCII decimal digits are those byte values in the sequence ``b'0123456789'``. @@ -3154,8 +2939,8 @@ place, and instead produce new objects. .. method:: bytes.isalpha() bytearray.isalpha() - Return ``True`` if all bytes in the sequence are alphabetic ASCII characters - and the sequence is not empty, ``False`` otherwise. Alphabetic ASCII + Return true if all bytes in the sequence are alphabetic ASCII characters + and the sequence is not empty, false otherwise. Alphabetic ASCII characters are those byte values in the sequence ``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. @@ -3170,8 +2955,8 @@ place, and instead produce new objects. .. method:: bytes.isascii() bytearray.isascii() - Return ``True`` if the sequence is empty or all bytes in the sequence are ASCII, - ``False`` otherwise. + Return true if the sequence is empty or all bytes in the sequence are ASCII, + false otherwise. ASCII bytes are in the range 0-0x7F. .. versionadded:: 3.7 @@ -3180,8 +2965,8 @@ place, and instead produce new objects. .. method:: bytes.isdigit() bytearray.isdigit() - Return ``True`` if all bytes in the sequence are ASCII decimal digits - and the sequence is not empty, ``False`` otherwise. ASCII decimal digits are + Return true if all bytes in the sequence are ASCII decimal digits + and the sequence is not empty, false otherwise. ASCII decimal digits are those byte values in the sequence ``b'0123456789'``. For example:: @@ -3195,8 +2980,8 @@ place, and instead produce new objects. .. method:: bytes.islower() bytearray.islower() - Return ``True`` if there is at least one lowercase ASCII character - in the sequence and no uppercase ASCII characters, ``False`` otherwise. + Return true if there is at least one lowercase ASCII character + in the sequence and no uppercase ASCII characters, false otherwise. For example:: @@ -3213,8 +2998,8 @@ place, and instead produce new objects. .. method:: bytes.isspace() bytearray.isspace() - Return ``True`` if all bytes in the sequence are ASCII whitespace and the - sequence is not empty, ``False`` otherwise. ASCII whitespace characters are + Return true if all bytes in the sequence are ASCII whitespace and the + sequence is not empty, false otherwise. ASCII whitespace characters are those byte values in the sequence ``b' \t\n\r\x0b\f'`` (space, tab, newline, carriage return, vertical tab, form feed). @@ -3222,8 +3007,8 @@ place, and instead produce new objects. .. method:: bytes.istitle() bytearray.istitle() - Return ``True`` if the sequence is ASCII titlecase and the sequence is not - empty, ``False`` otherwise. See :meth:`bytes.title` for more details on the + Return true if the sequence is ASCII titlecase and the sequence is not + empty, false otherwise. See :meth:`bytes.title` for more details on the definition of "titlecase". For example:: @@ -3237,8 +3022,8 @@ place, and instead produce new objects. .. method:: bytes.isupper() bytearray.isupper() - Return ``True`` if there is at least one uppercase alphabetic ASCII character - in the sequence and no lowercase ASCII characters, ``False`` otherwise. + Return true if there is at least one uppercase alphabetic ASCII character + in the sequence and no lowercase ASCII characters, false otherwise. For example:: @@ -3397,7 +3182,7 @@ place, and instead produce new objects. Return a copy of the sequence left filled with ASCII ``b'0'`` digits to make a sequence of length *width*. A leading sign prefix (``b'+'``/ - ``b'-'``) is handled by inserting the padding *after* the sign character + ``b'-'`` is handled by inserting the padding *after* the sign character rather than before. For :class:`bytes` objects, the original sequence is returned if *width* is less than or equal to ``len(seq)``. @@ -3420,17 +3205,18 @@ place, and instead produce new objects. ---------------------------------- .. index:: - single: formatting; bytes (%) - single: formatting; bytearray (%) - single: interpolation; bytes (%) - single: interpolation; bytearray (%) + single: formatting, bytes (%) + single: formatting, bytearray (%) + single: interpolation, bytes (%) + single: interpolation, bytearray (%) single: bytes; formatting single: bytearray; formatting single: bytes; interpolation single: bytearray; interpolation single: printf-style formatting single: sprintf-style formatting - single: % (percent); printf-style formatting + single: % formatting + single: % interpolation .. note:: @@ -3451,11 +3237,6 @@ object. [5]_ Otherwise, *values* must be a tuple with exactly the number of items specified by the format bytes object, or a single mapping object (for example, a dictionary). -.. index:: - single: () (parentheses); in printf-style formatting - single: * (asterisk); in printf-style formatting - single: . (dot); in printf-style formatting - A conversion specifier contains two or more characters and has the following components, which must occur in this order: @@ -3494,12 +3275,6 @@ sequential parameter list). The conversion flag characters are: -.. index:: - single: # (hash); in printf-style formatting - single: - (minus); in printf-style formatting - single: + (plus); in printf-style formatting - single: space; in printf-style formatting - +---------+---------------------------------------------------------------------+ | Flag | Meaning | +=========+=====================================================================+ @@ -3615,10 +3390,7 @@ Notes: The bytearray version of this method does *not* operate in place - it always produces a new object, even if no changes were made. -.. seealso:: - - :pep:`461` - Adding % formatting to bytes and bytearray - +.. seealso:: :pep:`461`. .. versionadded:: 3.5 .. _typememoryview: @@ -3777,7 +3549,7 @@ copying. Previous versions compared the raw memory disregarding the item format and the logical array structure. - .. method:: tobytes(order=None) + .. method:: tobytes() Return the data in the buffer as a bytestring. This is equivalent to calling the :class:`bytes` constructor on the memoryview. :: @@ -3793,14 +3565,7 @@ copying. supports all format strings, including those that are not in :mod:`struct` module syntax. - .. versionadded:: 3.8 - *order* can be {'C', 'F', 'A'}. When *order* is 'C' or 'F', the data - of the original array is converted to C or Fortran order. For contiguous - views, 'A' returns an exact copy of the physical memory. In particular, - in-memory Fortran order is preserved. For non-contiguous views, the - data is converted to C first. *order=None* is the same as *order='C'*. - - .. method:: hex([sep[, bytes_per_sep]]) + .. method:: hex() Return a string object containing two hexadecimal digits for each byte in the buffer. :: @@ -3811,11 +3576,6 @@ copying. .. versionadded:: 3.5 - .. versionchanged:: 3.8 - Similar to :meth:`bytes.hex`, :meth:`memoryview.hex` now supports - optional *sep* and *bytes_per_sep* parameters to insert separators - between bytes in the hex output. - .. method:: tolist() Return the data in the buffer as a list of elements. :: @@ -3833,25 +3593,6 @@ copying. :mod:`struct` module syntax as well as multi-dimensional representations. - .. method:: toreadonly() - - Return a readonly version of the memoryview object. The original - memoryview object is unchanged. :: - - >>> m = memoryview(bytearray(b'abc')) - >>> mm = m.toreadonly() - >>> mm.tolist() - [89, 98, 99] - >>> mm[0] = 42 - Traceback (most recent call last): - File "", line 1, in - TypeError: cannot modify read-only memory - >>> m[0] = 43 - >>> mm.tolist() - [43, 98, 99] - - .. versionadded:: 3.8 - .. method:: release() Release the underlying buffer exposed by the memoryview object. Many @@ -3960,7 +3701,7 @@ copying. >>> z.nbytes 48 - Cast 1D/unsigned long to 2D/unsigned long:: + Cast 1D/unsigned char to 2D/unsigned long:: >>> buf = struct.pack("L"*6, *list(range(6))) >>> x = memoryview(buf) @@ -3994,7 +3735,7 @@ copying. ``nbytes == product(shape) * itemsize == len(m.tobytes())``. This is the amount of space in bytes that the array would use in a contiguous - representation. It is not necessarily equal to ``len(m)``:: + representation. It is not necessarily equal to len(m):: >>> import array >>> a = array.array('i', [1,2,3,4,5]) @@ -4140,12 +3881,6 @@ The constructors for both classes work the same: objects. If *iterable* is not specified, a new empty set is returned. - Sets can be created by several means: - - * Use a comma-separated list of elements within braces: ``{'jack', 'sjoerd'}`` - * Use a set comprehension: ``{c for c in 'abracadabra' if c not in 'abc'}`` - * Use the type constructor: ``set()``, ``set('foobar')``, ``set(['a', 'b', 'foo'])`` - Instances of :class:`set` and :class:`frozenset` provide the following operations: @@ -4208,11 +3943,11 @@ The constructors for both classes work the same: .. method:: copy() - Return a shallow copy of the set. + Return a new set with a shallow copy of *s*. Note, the non-operator versions of :meth:`union`, :meth:`intersection`, - :meth:`difference`, :meth:`symmetric_difference`, :meth:`issubset`, and + :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and :meth:`issuperset` methods will accept any iterable as an argument. In contrast, their operator based counterparts require their arguments to be sets. This precludes error-prone constructions like ``set('abc') & 'cbs'`` @@ -4338,14 +4073,6 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 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 is a mapping object, a dictionary is created with the same key-value pairs as the mapping object. Otherwise, @@ -4369,8 +4096,7 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: >>> 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 + >>> a == b == c == d == e True Providing keyword arguments as in the first example only works for keys that @@ -4380,10 +4106,6 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: These are the operations that dictionaries support (and therefore, custom mapping types should support too): - .. describe:: list(d) - - Return a list of all the keys used in the dictionary *d*. - .. describe:: len(d) Return the number of items in the dictionary *d*. @@ -4447,15 +4169,12 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: Return a shallow copy of the dictionary. - .. classmethod:: fromkeys(iterable[, value]) + .. classmethod:: fromkeys(seq[, value]) - Create a new dictionary with keys from *iterable* and values set to *value*. + Create a new dictionary with keys from *seq* and values set to *value*. :meth:`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 :ref:`dict - comprehension ` instead. + defaults to ``None``. .. method:: get(key[, default]) @@ -4481,24 +4200,12 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: .. method:: popitem() - Remove and return a ``(key, value)`` pair from the dictionary. - Pairs are returned in :abbr:`LIFO (last-in, first-out)` order. + Remove and return an arbitrary ``(key, value)`` pair from the dictionary. :meth:`popitem` is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, calling :meth:`popitem` raises a :exc:`KeyError`. - .. versionchanged:: 3.7 - LIFO order is now guaranteed. In prior versions, :meth:`popitem` would - return an arbitrary key/value pair. - - .. describe:: reversed(d) - - Return a reverse iterator over the keys of the dictionary. This is a - shortcut for ``reversed(d.keys())``. - - .. versionadded:: 3.8 - .. method:: setdefault(key[, default]) If *key* is in the dictionary, return its value. If not, insert *key* @@ -4520,72 +4227,10 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: Return a new view of the dictionary's values. See the :ref:`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 - - .. describe:: 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. - - .. versionadded:: 3.9 - - .. describe:: d |= other - - Update the dictionary *d* with keys and values from *other*, which may be - either a :term:`mapping` or an :term:`iterable` of key/value pairs. The - values of *other* take priority when *d* and *other* share keys. - - .. versionadded:: 3.9 - Dictionaries compare equal if and only if they have the same ``(key, - value)`` pairs (regardless of ordering). Order comparisons ('<', '<=', '>=', '>') raise + value)`` pairs. Order comparisons ('<', '<=', '>=', '>') raise :exc:`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} - - .. versionchanged:: 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)] - - .. versionchanged:: 3.8 - Dictionaries are now reversible. - - .. seealso:: :class:`types.MappingProxyType` can be used to create a read-only view of a :class:`dict`. @@ -4613,36 +4258,22 @@ support membership tests: 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 + Keys and values are iterated over in an arbitrary order which is non-random, + varies across Python implementations, and depends on the dictionary's history + of insertions and deletions. If keys, values and items views are iterated + over with no intervening modifications to the dictionary, the order of items + will directly correspond. This allows the creation of ``(value, key)`` pairs using :func:`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 :exc:`RuntimeError` or fail to iterate over all entries. - .. versionchanged:: 3.7 - Dictionary order is guaranteed to be insertion order. - .. describe:: 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). -.. describe:: 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. - - .. versionchanged:: 3.8 - Dictionary views are now reversible. - -.. describe:: dictview.mapping - - Return a :class:`types.MappingProxyType` that wraps the original - dictionary to which the view refers. - - .. versionadded:: 3.10 Keys views are set-like since their entries are unique and hashable. If all values are hashable, so that ``(key, value)`` pairs are unique and hashable, @@ -4664,9 +4295,9 @@ An example of dictionary view usage:: >>> print(n) 504 - >>> # keys and values are iterated over in the same order (insertion order) + >>> # keys and values are iterated over in the same order >>> list(keys) - ['eggs', 'sausage', 'bacon', 'spam'] + ['eggs', 'bacon', 'sausage', 'spam'] >>> list(values) [2, 1, 1, 500] @@ -4674,7 +4305,7 @@ An example of dictionary view usage:: >>> del dishes['eggs'] >>> del dishes['sausage'] >>> list(keys) - ['bacon', 'spam'] + ['spam', 'bacon'] >>> # set operations >>> keys & {'eggs', 'bacon', 'salad'} @@ -4682,12 +4313,6 @@ An example of dictionary view usage:: >>> keys ^ {'sausage', 'juice'} {'juice', 'sausage', 'bacon', 'spam'} - >>> # get back a read-only proxy for the original dictionary - >>> values.mapping - mappingproxy({'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}) - >>> values.mapping['spam'] - 500 - .. _typecontextmanager: @@ -4709,7 +4334,7 @@ before the statement body is executed and exited when the statement ends: Enter the runtime context and return either this object or another object related to the runtime context. The value returned by this method is bound to - the identifier in the :keyword:`!as` clause of :keyword:`with` statements using + the identifier in the :keyword:`as` clause of :keyword:`with` statements using this context manager. An example of a context manager that returns itself is a :term:`file object`. @@ -4721,7 +4346,7 @@ before the statement body is executed and exited when the statement ends: decimal context to a copy of the original decimal context and then return the copy. This allows changes to be made to the current decimal context in the body of the :keyword:`with` statement without affecting code outside the - :keyword:`!with` statement. + :keyword:`with` statement. .. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb) @@ -4733,10 +4358,10 @@ before the statement body is executed and exited when the statement ends: Returning a true value from this method will cause the :keyword:`with` statement to suppress the exception and continue execution with the statement immediately - following the :keyword:`!with` statement. Otherwise the exception continues + following the :keyword:`with` statement. Otherwise the exception continues propagating after this method has finished executing. Exceptions that occur during execution of this method will replace any exception that occurred in the - body of the :keyword:`!with` statement. + body of the :keyword:`with` statement. The exception passed in should never be reraised explicitly - instead, this method should return a false value to indicate that the method completed @@ -4764,316 +4389,6 @@ Compared to the overhead of setting up the runtime context, the overhead of a single class dictionary lookup is negligible. -Type Annotation Types --- :ref:`Generic Alias `, :ref:`Union ` -=============================================================================================== - -.. index:: - single: annotation; type annotation; type hint - -The core built-in types for :term:`type annotations ` are -:ref:`Generic Alias ` and :ref:`Union `. - - -.. _types-genericalias: - -Generic Alias Type ------------------- - -.. index:: - object: GenericAlias - pair: Generic; Alias - -``GenericAlias`` objects are created by subscripting a class (usually a -container), such as ``list[int]``. They are intended primarily for -:term:`type annotations `. - -Usually, the :ref:`subscription ` of container objects calls the -method :meth:`__getitem__` of the object. However, the subscription of some -containers' classes may call the classmethod :meth:`__class_getitem__` of the -class instead. The classmethod :meth:`__class_getitem__` should return a -``GenericAlias`` object. - -.. note:: - If the :meth:`__getitem__` of the class' metaclass is present, it will take - precedence over the :meth:`__class_getitem__` defined in the class (see - :pep:`560` for more details). - -The ``GenericAlias`` object acts as a proxy for :term:`generic types -`, implementing *parameterized generics* - a specific instance -of a generic which provides the types for container elements. - -The user-exposed type for the ``GenericAlias`` object can be accessed from -:class:`types.GenericAlias` and used for :func:`isinstance` checks. It can -also be used to create ``GenericAlias`` objects directly. - -.. describe:: T[X, Y, ...] - - Creates a ``GenericAlias`` representing a type ``T`` containing elements - of types *X*, *Y*, and more depending on the ``T`` used. - For example, a function expecting a :class:`list` containing - :class:`float` elements:: - - def average(values: list[float]) -> float: - return sum(values) / len(values) - - Another example for :term:`mapping` objects, using a :class:`dict`, which - is a generic type expecting two type parameters representing the key type - and the value type. In this example, the function expects a ``dict`` with - keys of type :class:`str` and values of type :class:`int`:: - - def send_post_request(url: str, body: dict[str, int]) -> None: - ... - -The builtin functions :func:`isinstance` and :func:`issubclass` do not accept -``GenericAlias`` types for their second argument:: - - >>> isinstance([1, 2], list[str]) - Traceback (most recent call last): - File "", line 1, in - TypeError: isinstance() argument 2 cannot be a parameterized generic - -The Python runtime does not enforce :term:`type annotations `. -This extends to generic types and their type parameters. When creating -an object from a ``GenericAlias``, container elements are not checked -against their type. For example, the following code is discouraged, but will -run without errors:: - - >>> t = list[str] - >>> t([1, 2, 3]) - [1, 2, 3] - -Furthermore, parameterized generics erase type parameters during object -creation:: - - >>> t = list[str] - >>> type(t) - - - >>> l = t() - >>> type(l) - - -Calling :func:`repr` or :func:`str` on a generic shows the parameterized type:: - - >>> repr(list[int]) - 'list[int]' - - >>> str(list[int]) - 'list[int]' - -The :meth:`__getitem__` method of generics will raise an exception to disallow -mistakes like ``dict[str][str]``:: - - >>> dict[str][str] - Traceback (most recent call last): - File "", line 1, in - TypeError: There are no type variables left in dict[str] - -However, such expressions are valid when :ref:`type variables ` are -used. The index must have as many elements as there are type variable items -in the ``GenericAlias`` object's :attr:`__args__ `. :: - - >>> from typing import TypeVar - >>> Y = TypeVar('Y') - >>> dict[str, Y][int] - dict[str, int] - - -Standard Generic Collections -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -These standard library collections support parameterized generics. - -* :class:`tuple` -* :class:`list` -* :class:`dict` -* :class:`set` -* :class:`frozenset` -* :class:`type` -* :class:`collections.deque` -* :class:`collections.defaultdict` -* :class:`collections.OrderedDict` -* :class:`collections.Counter` -* :class:`collections.ChainMap` -* :class:`collections.abc.Awaitable` -* :class:`collections.abc.Coroutine` -* :class:`collections.abc.AsyncIterable` -* :class:`collections.abc.AsyncIterator` -* :class:`collections.abc.AsyncGenerator` -* :class:`collections.abc.Iterable` -* :class:`collections.abc.Iterator` -* :class:`collections.abc.Generator` -* :class:`collections.abc.Reversible` -* :class:`collections.abc.Container` -* :class:`collections.abc.Collection` -* :class:`collections.abc.Callable` -* :class:`collections.abc.Set` -* :class:`collections.abc.MutableSet` -* :class:`collections.abc.Mapping` -* :class:`collections.abc.MutableMapping` -* :class:`collections.abc.Sequence` -* :class:`collections.abc.MutableSequence` -* :class:`collections.abc.ByteString` -* :class:`collections.abc.MappingView` -* :class:`collections.abc.KeysView` -* :class:`collections.abc.ItemsView` -* :class:`collections.abc.ValuesView` -* :class:`contextlib.AbstractContextManager` -* :class:`contextlib.AbstractAsyncContextManager` -* :ref:`re.Pattern ` -* :ref:`re.Match ` - - -Special Attributes of Generic Alias -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -All parameterized generics implement special read-only attributes. - -.. attribute:: genericalias.__origin__ - - This attribute points at the non-parameterized generic class:: - - >>> list[int].__origin__ - - - -.. attribute:: genericalias.__args__ - - This attribute is a :class:`tuple` (possibly of length 1) of generic - types passed to the original :meth:`__class_getitem__` - of the generic container:: - - >>> dict[str, list[int]].__args__ - (, list[int]) - - -.. attribute:: genericalias.__parameters__ - - This attribute is a lazily computed tuple (possibly empty) of unique type - variables found in ``__args__``:: - - >>> from typing import TypeVar - - >>> T = TypeVar('T') - >>> list[T].__parameters__ - (~T,) - - - .. note:: - A ``GenericAlias`` object with :class:`typing.ParamSpec` parameters may not - have correct ``__parameters__`` after substitution because - :class:`typing.ParamSpec` is intended primarily for static type checking. - -.. seealso:: - - * :pep:`585` -- "Type Hinting Generics In Standard Collections" - * :meth:`__class_getitem__` -- Used to implement parameterized generics. - * :ref:`generics` -- Generics in the :mod:`typing` module. - -.. versionadded:: 3.9 - - -.. _types-union: - -Union Type ----------- - -.. index:: - object: Union - pair: union; type - -A union object holds the value of the ``|`` (bitwise or) operation on -multiple :ref:`type objects `. These types are intended -primarily for :term:`type annotations `. The union type expression -enables cleaner type hinting syntax compared to :data:`typing.Union`. - -.. describe:: X | Y | ... - - Defines a union object which holds types *X*, *Y*, and so forth. ``X | Y`` - means either X or Y. It is equivalent to ``typing.Union[X, Y]``. - For example, the following function expects an argument of type - :class:`int` or :class:`float`:: - - def square(number: int | float) -> int | float: - return number ** 2 - -.. describe:: union_object == other - - Union objects can be tested for equality with other union objects. Details: - - * Unions of unions are flattened:: - - (int | str) | float == int | str | float - - * Redundant types are removed:: - - int | str | int == int | str - - * When comparing unions, the order is ignored:: - - int | str == str | int - - * It is compatible with :data:`typing.Union`:: - - int | str == typing.Union[int, str] - - * Optional types can be spelled as a union with ``None``:: - - str | None == typing.Optional[str] - -.. describe:: isinstance(obj, union_object) -.. describe:: issubclass(obj, union_object) - - Calls to :func:`isinstance` and :func:`issubclass` are also supported with a - union object:: - - >>> isinstance("", int | str) - True - - However, union objects containing :ref:`parameterized generics - ` cannot be used:: - - >>> isinstance(1, int | list[int]) - Traceback (most recent call last): - File "", line 1, in - TypeError: isinstance() argument 2 cannot contain a parameterized generic - -The user-exposed type for the union object can be accessed from -:data:`types.Union` and used for :func:`isinstance` checks. An object cannot be -instantiated from the type:: - - >>> import types - >>> isinstance(int | str, types.Union) - True - >>> types.Union() - Traceback (most recent call last): - File "", line 1, in - TypeError: cannot create 'types.Union' instances - -.. note:: - The :meth:`__or__` method for type objects was added to support the syntax - ``X | Y``. If a metaclass implements :meth:`__or__`, the Union may - override it:: - - >>> class M(type): - ... def __or__(self, other): - ... return "Hello" - ... - >>> class C(metaclass=M): - ... pass - ... - >>> C | int - 'Hello' - >>> int | C - int | __main__.C - -.. seealso:: - - :pep:`604` -- PEP proposing the ``X | Y`` syntax and the Union type. - -.. versionadded:: 3.10 - - .. _typesother: Other Built-in Types @@ -5232,7 +4547,6 @@ supports no special operations. There is exactly one null object, named It is written as ``None``. -.. index:: single: ...; ellipsis literal .. _bltin-ellipsis-object: The Ellipsis Object @@ -5345,8 +4659,8 @@ types, where they are relevant. Some of these are not reported by the .. method:: class.__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:: + method returns a list of all those references still alive. + Example:: >>> int.__subclasses__() [] diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 17705b117c372b..d686b6694f4397 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -13,7 +13,7 @@ This chapter explains the meaning of the elements of expressions in Python. be used to describe syntax, not lexical analysis. When (one alternative of) a syntax rule has the form -.. productionlist:: python-grammar +.. productionlist:: * name: `othername` and no semantics are given, the semantics of this form of ``name`` are the same @@ -28,7 +28,7 @@ Arithmetic conversions .. index:: pair: arithmetic; conversion When a description of an arithmetic operator below uses the phrase "the numeric -arguments are converted to a common type", this means that the operator +arguments are converted to a common type," this means that the operator implementation for built-in types works as follows: * If either argument is a complex number, the other is converted to complex; @@ -54,7 +54,7 @@ Atoms are the most basic elements of expressions. The simplest atoms are identifiers or literals. Forms enclosed in parentheses, brackets or braces are also categorized syntactically as atoms. The syntax for atoms is: -.. productionlist:: python-grammar +.. productionlist:: atom: `identifier` | `literal` | `enclosure` enclosure: `parenth_form` | `list_display` | `dict_display` | `set_display` : | `generator_expression` | `yield_atom` @@ -77,8 +77,6 @@ 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 :exc:`NameError` exception. -.. _private-name-mangling: - .. index:: pair: name; mangling pair: private; names @@ -105,7 +103,7 @@ Literals Python supports string and bytes literals and various numeric literals: -.. productionlist:: python-grammar +.. productionlist:: literal: `stringliteral` | `bytesliteral` : | `integer` | `floatnumber` | `imagnumber` @@ -130,13 +128,11 @@ value. Parenthesized forms ------------------- -.. index:: - single: parenthesized form - single: () (parentheses); tuple display +.. index:: single: parenthesized form A parenthesized form is an optional expression list enclosed in parentheses: -.. productionlist:: python-grammar +.. productionlist:: parenth_form: "(" [`starred_expression`] ")" A parenthesized expression list yields whatever that expression list yields: if @@ -146,12 +142,12 @@ the single expression that makes up the expression list. .. index:: pair: empty; tuple An empty pair of parentheses yields an empty tuple object. Since tuples are -immutable, the same rules as for literals apply (i.e., two occurrences of the empty +immutable, the rules for literals apply (i.e., two occurrences of the empty tuple may or may not yield the same object). .. index:: single: comma - single: , (comma) + pair: tuple; display Note that tuples are not formed by the parentheses, but rather by use of the comma operator. The exception is the empty tuple, for which parentheses *are* @@ -164,8 +160,6 @@ ambiguities and allow common typos to pass uncaught. Displays for lists, sets and dictionaries ----------------------------------------- -.. index:: single: comprehensions - For constructing a list, a set or a dictionary Python provides special syntax called "displays", each of them in two flavors: @@ -174,34 +168,29 @@ called "displays", each of them in two flavors: * they are computed via a set of looping and filtering instructions, called a :dfn:`comprehension`. -.. index:: - single: for; in comprehensions - single: if; in comprehensions - single: async for; in comprehensions - Common syntax elements for comprehensions are: -.. productionlist:: python-grammar - comprehension: `assignment_expression` `comp_for` - comp_for: ["async"] "for" `target_list` "in" `or_test` [`comp_iter`] +.. productionlist:: + comprehension: `expression` `comp_for` + comp_for: [ASYNC] "for" `target_list` "in" `or_test` [`comp_iter`] comp_iter: `comp_for` | `comp_if` comp_if: "if" `expression_nocond` [`comp_iter`] The comprehension consists of a single expression followed by at least one -:keyword:`!for` clause and zero or more :keyword:`!for` or :keyword:`!if` clauses. +:keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if` clauses. In this case, the elements of the new container are those that would be produced -by considering each of the :keyword:`!for` or :keyword:`!if` clauses a block, +by considering each of the :keyword:`for` or :keyword:`if` clauses a block, nesting from left to right, and evaluating the expression to produce an element each time the innermost block is reached. -However, aside from the iterable expression in the leftmost :keyword:`!for` clause, +However, aside from the iterable expression in the leftmost :keyword:`for` clause, the comprehension is executed in a separate implicitly nested scope. This ensures that names assigned to in the target list don't "leak" into the enclosing scope. -The iterable expression in the leftmost :keyword:`!for` clause is evaluated -directly in the enclosing scope and then passed as an argument to the implicitly -nested scope. Subsequent :keyword:`!for` clauses and any filter condition in the -leftmost :keyword:`!for` clause cannot be evaluated in the enclosing scope as +The iterable expression in the leftmost :keyword:`for` clause is evaluated +directly in the enclosing scope and then passed as an argument to the implictly +nested scope. Subsequent :keyword:`for` clauses and any filter condition in the +leftmost :keyword:`for` clause cannot be evaluated in the enclosing scope as they may depend on the values obtained from the leftmost iterable. For example: ``[x*y for x in range(10) for y in range(x, x+10)]``. @@ -209,17 +198,14 @@ To ensure the comprehension always results in a container of the appropriate type, ``yield`` and ``yield from`` expressions are prohibited in the implicitly nested scope. -.. index:: - single: await; in comprehensions - -Since Python 3.6, in an :keyword:`async def` function, an :keyword:`!async for` +Since Python 3.6, in an :keyword:`async def` function, an :keyword:`async for` clause may be used to iterate over a :term:`asynchronous iterator`. -A comprehension in an :keyword:`!async def` function may consist of either a -:keyword:`!for` or :keyword:`!async for` clause following the leading -expression, may contain additional :keyword:`!for` or :keyword:`!async for` +A comprehension in an :keyword:`async def` function may consist of either a +:keyword:`for` or :keyword:`async for` clause following the leading +expression, may contain additional :keyword:`for` or :keyword:`async for` clauses, and may also use :keyword:`await` expressions. -If a comprehension contains either :keyword:`!async for` clauses -or :keyword:`!await` expressions it is called an +If a comprehension contains either :keyword:`async for` clauses +or :keyword:`await` expressions it is called an :dfn:`asynchronous comprehension`. An asynchronous comprehension may suspend the execution of the coroutine function in which it appears. See also :pep:`530`. @@ -241,13 +227,11 @@ List displays pair: list; comprehensions pair: empty; list object: list - single: [] (square brackets); list expression - single: , (comma); expression list A list display is a possibly empty series of expressions enclosed in square brackets: -.. productionlist:: python-grammar +.. productionlist:: list_display: "[" [`starred_list` | `comprehension`] "]" A list display yields a new list object, the contents being specified by either @@ -262,17 +246,13 @@ the list is constructed from the elements resulting from the comprehension. Set displays ------------ -.. index:: - pair: set; display - pair: set; comprehensions - object: set - single: {} (curly brackets); set expression - single: , (comma); expression list +.. index:: pair: set; display + object: set A set display is denoted by curly braces and distinguishable from dictionary displays by the lack of colons separating keys and values: -.. productionlist:: python-grammar +.. productionlist:: set_display: "{" (`starred_list` | `comprehension`) "}" A set display yields a new mutable set object, the contents being specified by @@ -290,19 +270,14 @@ dictionary. Dictionary displays ------------------- -.. index:: - pair: dictionary; display - pair: dictionary; comprehensions - key, datum, key/datum pair - object: dictionary - single: {} (curly brackets); dictionary expression - single: : (colon); in dictionary expressions - single: , (comma); in dictionary displays +.. index:: pair: dictionary; display + key, datum, key/datum pair + object: dictionary A dictionary display is a possibly empty series of key/datum pairs enclosed in curly braces: -.. productionlist:: python-grammar +.. productionlist:: dict_display: "{" [`key_datum_list` | `dict_comprehension`] "}" key_datum_list: `key_datum` ("," `key_datum`)* [","] key_datum: `expression` ":" `expression` | "**" `or_expr` @@ -316,9 +291,7 @@ used as a key into the dictionary to store the corresponding datum. This means that you can specify the same key multiple times in the key/datum list, and the final dictionary's value for that key will be the last one given. -.. index:: - unpacking; dictionary - single: **; in dictionary displays +.. index:: unpacking; dictionary, **; in dictionary displays A double asterisk ``**`` denotes :dfn:`dictionary unpacking`. Its operand must be a :term:`mapping`. Each mapping item is added @@ -342,26 +315,18 @@ all mutable objects.) Clashes between duplicate keys are not detected; the last datum (textually rightmost in the display) stored for a given key value prevails. -.. versionchanged:: 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`. - .. _genexpr: Generator expressions --------------------- -.. index:: - pair: generator; expression - object: generator - single: () (parentheses); generator expression +.. index:: pair: generator; expression + object: generator A generator expression is a compact generator notation in parentheses: -.. productionlist:: python-grammar +.. productionlist:: generator_expression: "(" `expression` `comp_for` ")" A generator expression yields a new generator object. Its syntax is the same as @@ -371,11 +336,11 @@ brackets or curly braces. Variables used in the generator expression are evaluated lazily when the :meth:`~generator.__next__` method is called for the generator object (in the same fashion as normal generators). However, the iterable expression in the -leftmost :keyword:`!for` clause is immediately evaluated, so that an error +leftmost :keyword:`for` clause is immediately evaluated, so that an error produced by it will be emitted at the point where the generator expression is defined, rather than at the point where the first value is retrieved. -Subsequent :keyword:`!for` clauses and any filter condition in the leftmost -:keyword:`!for` clause cannot be evaluated in the enclosing scope as they may +Subsequent :keyword:`for` clauses and any filter condition in the leftmost +:keyword:`for` clause cannot be evaluated in the enclosing scope as they may depend on the values obtained from the leftmost iterable. For example: ``(x*y for x in range(10) for y in range(x, x+10))``. @@ -386,7 +351,7 @@ To avoid interfering with the expected operation of the generator expression itself, ``yield`` and ``yield from`` expressions are prohibited in the implicitly defined generator. -If a generator expression contains either :keyword:`!async for` +If a generator expression contains either :keyword:`async for` clauses or :keyword:`await` expressions it is called an :dfn:`asynchronous generator expression`. An asynchronous generator expression returns a new asynchronous generator object, @@ -411,11 +376,10 @@ Yield expressions .. index:: keyword: yield - keyword: from pair: yield; expression pair: generator; function -.. productionlist:: python-grammar +.. productionlist:: yield_atom: "(" `yield_expression` ")" yield_expression: "yield" [`expression_list` | "from" `expression`] @@ -429,7 +393,7 @@ coroutine function to be an asynchronous generator. For example:: def gen(): # defines a generator function yield 123 - async def agen(): # defines an asynchronous generator function + async def agen(): # defines an asynchronous generator function (PEP 525) yield 123 Due to their side effects on the containing scope, ``yield`` expressions @@ -475,11 +439,8 @@ finalized (by reaching a zero reference count or by being garbage collected), the generator-iterator's :meth:`~generator.close` method will be called, allowing any pending :keyword:`finally` clauses to execute. -.. index:: - single: from; yield from expression - -When ``yield from `` is used, the supplied expression must be an -iterable. The values produced by iterating that iterable are passed directly +When ``yield from `` is used, it treats the supplied expression as +a subiterator. All values produced by that subiterator are passed directly to the caller of the current generator's methods. Any values passed in with :meth:`~generator.send` and any exceptions passed in with :meth:`~generator.throw` are passed to the underlying iterator if it has the @@ -490,8 +451,8 @@ will raise :exc:`AttributeError` or :exc:`TypeError`, while When the underlying iterator is complete, the :attr:`~StopIteration.value` attribute of the raised :exc:`StopIteration` instance becomes the value of the yield expression. It can be either set explicitly when raising -:exc:`StopIteration`, or automatically when the subiterator is a generator -(by returning a value from the subgenerator). +:exc:`StopIteration`, or automatically when the sub-iterator is a generator +(by returning a value from the sub-generator). .. versionchanged:: 3.3 Added ``yield from `` to delegate control flow to a subiterator. @@ -510,11 +471,7 @@ on the right hand side of an assignment statement. :pep:`380` - Syntax for Delegating to a Subgenerator The proposal to introduce the :token:`yield_from` syntax, making delegation - to subgenerators easy. - - :pep:`525` - Asynchronous Generators - The proposal that expanded on :pep:`492` by adding generator capabilities to - coroutine functions. + to sub-generators easy. .. index:: object: generator .. _generator-methods: @@ -619,7 +576,7 @@ Asynchronous generator functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The presence of a yield expression in a function or method defined using -:keyword:`async def` further defines the function as an +:keyword:`async def` further defines the function as a :term:`asynchronous generator` function. When an asynchronous generator function is called, it returns an @@ -645,30 +602,20 @@ after resuming depends on the method which resumed the execution. If :meth:`~agen.asend` is used, then the result will be the value passed in to that method. -If an asynchronous generator happens to exit early by :keyword:`break`, the caller -task being cancelled, or other exceptions, the generator's async cleanup code -will run and possibly raise exceptions or access context variables in an -unexpected context--perhaps after the lifetime of tasks it depends, or -during the event loop shutdown when the async-generator garbage collection hook -is called. -To prevent this, the caller must explicitly close the async generator by calling -:meth:`~agen.aclose` method to finalize the generator and ultimately detach it -from the event loop. - In an asynchronous generator function, yield expressions are allowed anywhere in a :keyword:`try` construct. However, if an asynchronous generator is not resumed before it is finalized (by reaching a zero reference count or by -being garbage collected), then a yield expression within a :keyword:`!try` +being garbage collected), then a yield expression within a :keyword:`try` construct could result in a failure to execute pending :keyword:`finally` clauses. In this case, it is the responsibility of the event loop or scheduler running the asynchronous generator to call the asynchronous generator-iterator's :meth:`~agen.aclose` method and run the resulting -coroutine object, thus allowing any pending :keyword:`!finally` clauses +coroutine object, thus allowing any pending :keyword:`finally` clauses to execute. -To take care of finalization upon event loop termination, an event loop should -define a *finalizer* function which takes an asynchronous generator-iterator and -presumably calls :meth:`~agen.aclose` and executes the coroutine. +To take care of finalization, an event loop should define +a *finalizer* function which takes an asynchronous generator-iterator +and presumably calls :meth:`~agen.aclose` and executes the coroutine. This *finalizer* may be registered by calling :func:`sys.set_asyncgen_hooks`. When first iterated over, an asynchronous generator-iterator will store the registered *finalizer* to be called upon finalization. For a reference example @@ -694,13 +641,13 @@ which are used to control the execution of a generator function. Returns an awaitable which when run starts to execute the asynchronous generator or resumes it at the last executed yield expression. When an - asynchronous generator function is resumed with an :meth:`~agen.__anext__` + asynchronous generator function is resumed with a :meth:`~agen.__anext__` method, the current yield expression always evaluates to :const:`None` in the returned awaitable, which when run will continue to the next yield expression. The value of the :token:`expression_list` of the yield expression is the value of the :exc:`StopIteration` exception raised by the completing coroutine. If the asynchronous generator exits without - yielding another value, the awaitable instead raises a + yielding another value, the awaitable instead raises an :exc:`StopAsyncIteration` exception, signalling that the asynchronous iteration has completed. @@ -728,7 +675,7 @@ which are used to control the execution of a generator function. where the asynchronous generator was paused, and returns the next value yielded by the generator function as the value of the raised :exc:`StopIteration` exception. If the asynchronous generator exits - without yielding another value, a :exc:`StopAsyncIteration` exception is + without yielding another value, an :exc:`StopAsyncIteration` exception is raised by the awaitable. If the generator function does not catch the passed-in exception, or raises a different exception, then when the awaitable is run that exception @@ -762,7 +709,7 @@ Primaries Primaries represent the most tightly bound operations of the language. Their syntax is: -.. productionlist:: python-grammar +.. productionlist:: primary: `atom` | `attributeref` | `subscription` | `slicing` | `call` @@ -771,13 +718,11 @@ syntax is: Attribute references -------------------- -.. index:: - pair: attribute; reference - single: . (dot); attribute reference +.. index:: pair: attribute; reference An attribute reference is a primary followed by a period and a name: -.. productionlist:: python-grammar +.. productionlist:: attributeref: `primary` "." `identifier` .. index:: @@ -799,9 +744,7 @@ same attribute reference may yield different objects. Subscriptions ------------- -.. index:: - single: subscription - single: [] (square brackets); subscription +.. index:: single: subscription .. index:: object: sequence @@ -812,10 +755,10 @@ Subscriptions object: dictionary pair: sequence; item -Subscription of a sequence (string, tuple or list) or mapping (dictionary) -object usually selects an item from the collection: +A subscription selects an item of a sequence (string, tuple or list) or mapping +(dictionary) object: -.. productionlist:: python-grammar +.. productionlist:: subscription: `primary` "[" `expression_list` "]" The primary must evaluate to an object that supports subscription (lists or @@ -829,7 +772,7 @@ whose value is one of the keys of the mapping, and the subscription selects the value in the mapping that corresponds to that key. (The expression list is a tuple except if it has exactly one item.) -If the primary is a sequence, the expression list must evaluate to an integer +If the primary is a sequence, the expression (list) must evaluate to an integer or a slice (as discussed in the following section). The formal syntax makes no special provision for negative indices in @@ -849,11 +792,6 @@ this method will need to explicitly add that support. A string's items are characters. A character is not a separate data type but a string of exactly one character. -Subscription of certain :term:`classes ` or :term:`types ` -creates a :ref:`generic alias `. -In this case, user-defined classes can support subscription by providing a -:meth:`__class_getitem__` classmethod. - .. _slicings: @@ -863,8 +801,6 @@ Slicings .. index:: single: slicing single: slice - single: : (colon); slicing - single: , (comma); slicing .. index:: object: sequence @@ -876,7 +812,7 @@ 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 :keyword:`del` statements. The syntax for a slicing: -.. productionlist:: python-grammar +.. productionlist:: slicing: `primary` "[" `slice_list` "]" slice_list: `slice_item` ("," `slice_item`)* [","] slice_item: `expression` | `proper_slice` @@ -914,9 +850,6 @@ substituting ``None`` for missing expressions. object: callable single: call single: argument; call semantics - single: () (parentheses); call - single: , (comma); argument list - single: = (equals); in function calls .. _calls: @@ -926,14 +859,13 @@ Calls A call calls a callable object (e.g., a :term:`function`) with a possibly empty series of :term:`arguments `: -.. productionlist:: python-grammar +.. productionlist:: 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` + positional_arguments: ["*"] `expression` ("," ["*"] `expression`)* starred_and_keywords: ("*" `expression` | `keyword_item`) : ("," "*" `expression` | "," `keyword_item`)* keywords_arguments: (`keyword_item` | "**" `expression`) @@ -994,7 +926,7 @@ and the argument values as corresponding values), or a (new) empty dictionary if there were no excess keyword arguments. .. index:: - single: * (asterisk); in function calls + single: *; in function calls single: unpacking; in function calls If the syntax ``*expression`` appears in the function call, ``expression`` must @@ -1100,7 +1032,6 @@ a class instance: if that method was called. -.. index:: keyword: await .. _await: Await expression @@ -1109,7 +1040,7 @@ Await expression Suspend the execution of :term:`coroutine` on an :term:`awaitable` object. Can only be used inside a :term:`coroutine function`. -.. productionlist:: python-grammar +.. productionlist:: await_expr: "await" `primary` .. versionadded:: 3.5 @@ -1120,15 +1051,11 @@ Can only be used inside a :term:`coroutine function`. The power operator ================== -.. index:: - pair: power; operation - 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: -.. productionlist:: python-grammar - power: (`await_expr` | `primary`) ["**" `u_expr`] +.. productionlist:: + 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 @@ -1160,27 +1087,21 @@ Unary arithmetic and bitwise operations All unary arithmetic and bitwise operations have the same priority: -.. productionlist:: python-grammar +.. productionlist:: u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr` .. index:: single: negation single: minus - single: operator; - (minus) - single: - (minus); unary operator The unary ``-`` (minus) operator yields the negation of its numeric argument. -.. index:: - single: plus - single: operator; + (plus) - single: + (plus); unary operator +.. index:: single: plus The unary ``+`` (plus) operator yields its numeric argument unchanged. -.. index:: - single: inversion - operator: ~ (tilde) +.. index:: single: inversion + The unary ``~`` (invert) operator yields the bitwise inversion of its integer argument. The bitwise inversion of ``x`` is defined as ``-(x+1)``. It only @@ -1204,15 +1125,13 @@ 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: -.. productionlist:: python-grammar +.. productionlist:: m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "@" `m_expr` | - : `m_expr` "//" `u_expr` | `m_expr` "/" `u_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` -.. index:: - single: multiplication - operator: * (asterisk) +.. index:: single: multiplication The ``*`` (multiplication) operator yields the product of its arguments. The arguments must either both be numbers, or one argument must be an integer and @@ -1220,9 +1139,7 @@ the other must be a sequence. In the former case, the numbers are converted to a common type and then multiplied together. In the latter case, sequence repetition is performed; a negative repetition factor yields an empty sequence. -.. index:: - single: matrix multiplication - operator: @ (at) +.. index:: single: matrix multiplication The ``@`` (at) operator is intended to be used for matrix multiplication. No builtin Python types implement this operator. @@ -1232,19 +1149,20 @@ builtin Python types implement this operator. .. index:: exception: ZeroDivisionError single: division - operator: / (slash) operator: // + 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 :exc:`ZeroDivisionError` -exception. +applied to the result. + +Division by zero raises the :exc:`ZeroDivisionError` exception. .. index:: - single: modulo - operator: % (percent) + single: modulo + operator: % 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 @@ -1256,8 +1174,13 @@ the result is strictly smaller than the absolute value of the second operand [#]_. 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 :func:`divmod`: ``divmod(x, y) == (x//y, +identity: + +``x == (x//y)*y + (x%y)`` + +.. index:: single: divmod + +Floor division and modulo are also connected with the built-in function :func:`divmod`: ``divmod(x, y) == (x//y, x%y)``. [#]_. In addition to performing the modulo operation on numbers, the ``%`` operator is @@ -1269,20 +1192,14 @@ The floor division operator, the modulo operator, and the :func:`divmod` function are not defined for complex numbers. Instead, convert to a floating point number using the :func:`abs` function if appropriate. -.. index:: - single: addition - single: operator; + (plus) - single: + (plus); binary operator +.. index:: single: addition 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 type and then added together. In the latter case, the sequences are concatenated. -.. index:: - single: subtraction - single: operator; - (minus) - single: - (minus); binary operator +.. index:: single: subtraction The ``-`` (subtraction) operator yields the difference of its arguments. The numeric arguments are first converted to a common type. @@ -1293,15 +1210,12 @@ numeric arguments are first converted to a common type. Shifting operations =================== -.. index:: - pair: shifting; operation - operator: << - operator: >> +.. index:: pair: shifting; operation The shifting operations have lower priority than the arithmetic operations: -.. productionlist:: python-grammar - shift_expr: `a_expr` | `shift_expr` ("<<" | ">>") `a_expr` +.. productionlist:: + 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. @@ -1321,14 +1235,12 @@ Binary bitwise operations Each of the three bitwise operations has a different priority level: -.. productionlist:: python-grammar +.. productionlist:: and_expr: `shift_expr` | `and_expr` "&" `shift_expr` xor_expr: `and_expr` | `xor_expr` "^" `and_expr` or_expr: `xor_expr` | `or_expr` "|" `xor_expr` -.. index:: - pair: bitwise; and - operator: & (ampersand) +.. index:: pair: bitwise; and The ``&`` operator yields the bitwise AND of its arguments, which must be integers. @@ -1336,7 +1248,6 @@ integers. .. index:: pair: bitwise; xor pair: exclusive; or - operator: ^ (caret) The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which must be integers. @@ -1344,7 +1255,6 @@ must be integers. .. index:: pair: bitwise; or pair: inclusive; or - operator: | (vertical bar) The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which must be integers. @@ -1355,23 +1265,17 @@ must be integers. Comparisons =========== -.. index:: - single: comparison - pair: C; language - operator: < (less) - operator: > (greater) - operator: <= - operator: >= - operator: == - operator: != +.. index:: single: comparison + +.. index:: pair: C; language 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: -.. productionlist:: python-grammar - comparison: `or_expr` (`comp_operator` `or_expr`)* +.. productionlist:: + comparison: `or_expr` ( `comp_operator` `or_expr` )* comp_operator: "<" | ">" | "==" | ">=" | "<=" | "!=" : | "is" ["not"] | ["not"] "in" @@ -1440,16 +1344,12 @@ built-in 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. + The not-a-number values :const:`float('NaN')` and :const:`Decimal('NaN')` + are special. They are identical to themselves (``x is x`` is true) but + are not equal to themselves (``x == x`` is false). Additionally, + comparing any number to a not-a-number value + will return ``False``. For example, both ``3 < float('NaN')`` and + ``float('NaN') < 3`` will return ``False``. * Binary sequences (instances of :class:`bytes` or :class:`bytearray`) can be compared within and across their types. They compare lexicographically using @@ -1468,9 +1368,25 @@ built-in types. :exc:`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. + elements, whereby reflexivity of the elements is enforced. + + In enforcing reflexivity of elements, the comparison of collections assumes + that for a collection element ``x``, ``x == x`` is always true. Based on + that assumption, element identity is compared first, and element comparison + is performed only for distinct elements. This approach yields the same + result as a strict element comparison would, if the compared elements are + reflexive. For non-reflexive elements, the result is different than for + strict element comparison, and may be surprising: The non-reflexive + not-a-number values for example result in the following comparison behavior + when used in a list:: + + >>> nan = float('NaN') + >>> nan is nan + True + >>> nan == nan + False <-- the defined non-reflexive behavior of NaN + >>> [nan] == [nan] + True <-- list enforces reflexivity and tests identity first Lexicographical comparison between built-in collections works as follows: @@ -1564,7 +1480,7 @@ Membership test operations The operators :keyword:`in` and :keyword:`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 :keyword:`!in` tests +set types support this as well as dictionary, for which :keyword:`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)``. @@ -1579,15 +1495,14 @@ y`` returns ``True`` if ``y.__contains__(x)`` returns a true value, and ``False`` otherwise. For user-defined classes which do not define :meth:`__contains__` but do define -:meth:`__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 :keyword:`in` raised -that exception. +:meth:`__iter__`, ``x in y`` is ``True`` if some value ``z`` with ``x == z`` is +produced while iterating over ``y``. If an exception is raised during the +iteration, it is as if :keyword:`in` raised that exception. Lastly, the old-style iteration protocol is tried: if a class defines :meth:`__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 :exc:`IndexError` exception. (If any other exception is raised, it is as +integer index *i* such that ``x == y[i]``, and all lower integer indices do not +raise :exc:`IndexError` exception. (If any other exception is raised, it is as if :keyword:`in` raised that exception). .. index:: @@ -1596,7 +1511,7 @@ if :keyword:`in` raised that exception). pair: membership; test object: sequence -The operator :keyword:`not in` is defined to have the inverse truth value of +The operator :keyword:`not in` is defined to have the inverse true value of :keyword:`in`. .. index:: @@ -1611,8 +1526,8 @@ The operator :keyword:`not in` is defined to have the inverse truth value of Identity comparisons -------------------- -The operators :keyword:`is` and :keyword:`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 +The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x +is y`` is true if and only if *x* and *y* are the same object. Object identity is determined using the :meth:`id` function. ``x is not y`` yields the inverse truth value. [#]_ @@ -1629,7 +1544,7 @@ Boolean operations pair: Conditional; expression pair: Boolean; operation -.. productionlist:: python-grammar +.. productionlist:: or_test: `and_test` | `or_test` "or" `and_test` and_test: `not_test` | `and_test` "and" `not_test` not_test: `comparison` | "not" `not_test` @@ -1656,7 +1571,7 @@ 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 :keyword:`and` nor :keyword:`or` restrict the value and type +(Note that neither :keyword:`and` nor :keyword:`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 @@ -1665,46 +1580,14 @@ returns a boolean value regardless of the type of its argument (for example, ``not 'foo'`` produces ``False`` rather than ``''``.) -Assignment expressions -====================== - -.. productionlist:: python-grammar - assignment_expression: [`identifier` ":="] `expression` - -An assignment expression (sometimes also called a "named expression" or -"walrus") assigns an :token:`expression` to an :token:`identifier`, while also -returning the value of the :token:`expression`. - -One common use case is when handling matched regular expressions: - -.. code-block:: python - - if matching := pattern.search(data): - do_something(matching) - -Or, when processing a file stream in chunks: - -.. code-block:: python - - while chunk := file.read(9000): - process(chunk) - -.. versionadded:: 3.8 - See :pep:`572` for more details about assignment expressions. - - -.. _if_expr: - Conditional expressions ======================= .. index:: pair: conditional; expression pair: ternary; operator - single: if; conditional expression - single: else; conditional expression -.. productionlist:: python-grammar +.. productionlist:: conditional_expression: `or_test` ["if" `or_test` "else" `expression`] expression: `conditional_expression` | `lambda_expr` expression_nocond: `or_test` | `lambda_expr_nocond` @@ -1729,19 +1612,18 @@ Lambdas pair: lambda; expression pair: lambda; form pair: anonymous; function - single: : (colon); lambda expression -.. productionlist:: python-grammar - lambda_expr: "lambda" [`parameter_list`] ":" `expression` - lambda_expr_nocond: "lambda" [`parameter_list`] ":" `expression_nocond` +.. productionlist:: + lambda_expr: "lambda" [`parameter_list`]: `expression` + lambda_expr_nocond: "lambda" [`parameter_list`]: `expression_nocond` Lambda expressions (sometimes called lambda forms) are used to create anonymous -functions. The expression ``lambda parameters: expression`` yields a function +functions. The expression ``lambda arguments: expression`` yields a function object. The unnamed object behaves like a function object defined with: .. code-block:: none - def (parameters): + def (arguments): return expression See section :ref:`function` for the syntax of parameter lists. Note that @@ -1754,15 +1636,13 @@ annotations. Expression lists ================ -.. index:: - pair: expression; list - single: , (comma); expression list +.. index:: pair: expression; list -.. productionlist:: python-grammar - expression_list: `expression` ("," `expression`)* [","] - starred_list: `starred_item` ("," `starred_item`)* [","] - starred_expression: `expression` | (`starred_item` ",")* [`starred_item`] - starred_item: `assignment_expression` | "*" `or_expr` +.. productionlist:: + expression_list: `expression` ( "," `expression` )* [","] + starred_list: `starred_item` ( "," `starred_item` )* [","] + starred_expression: `expression` | ( `starred_item` "," )* [`starred_item`] + starred_item: `expression` | "*" `or_expr` .. index:: object: tuple @@ -1773,7 +1653,7 @@ evaluated from left to right. .. index:: pair: iterable; unpacking - single: * (asterisk); in expression lists + single: *; in expression lists An asterisk ``*`` denotes :dfn:`iterable unpacking`. Its operand must be an :term:`iterable`. The iterable is expanded into a sequence of items, @@ -1818,8 +1698,7 @@ their suffixes:: Operator precedence =================== -.. index:: - pair: operator; precedence +.. index:: pair: operator; precedence The following table summarizes the operator precedence in Python, from lowest precedence (least binding) to highest precedence (most binding). Operators in @@ -1835,11 +1714,9 @@ precedence and have a left-to-right chaining feature as described in the +-----------------------------------------------+-------------------------------------+ | Operator | Description | +===============================================+=====================================+ -| ``:=`` | Assignment expression | -+-----------------------------------------------+-------------------------------------+ | :keyword:`lambda` | Lambda expression | +-----------------------------------------------+-------------------------------------+ -| :keyword:`if ` -- :keyword:`!else` | Conditional expression | +| :keyword:`if` -- :keyword:`else` | Conditional expression | +-----------------------------------------------+-------------------------------------+ | :keyword:`or` | Boolean OR | +-----------------------------------------------+-------------------------------------+ @@ -1869,13 +1746,12 @@ precedence and have a left-to-right chaining feature as described in the +-----------------------------------------------+-------------------------------------+ | ``**`` | Exponentiation [#]_ | +-----------------------------------------------+-------------------------------------+ -| :keyword:`await` ``x`` | Await expression | +| ``await`` ``x`` | Await expression | +-----------------------------------------------+-------------------------------------+ | ``x[index]``, ``x[index:index]``, | Subscription, slicing, | | ``x(arguments...)``, ``x.attribute`` | call, attribute reference | +-----------------------------------------------+-------------------------------------+ -| ``(expressions...)``, | Binding or parenthesized | -| | expression, | +| ``(expressions...)``, | Binding or tuple display, | | ``[expressions...]``, | list display, | | ``{key: value...}``, | dictionary display, | | ``{expressions...}`` | set display | diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index 2a1666128a2015..da684b8ad5026b 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -11,8 +11,6 @@ with a prompt are output from the interpreter. Note that a secondary prompt on a line by itself in an example means you must type a blank line; this is used to end a multi-line command. -.. index:: single: # (hash); comment - Many of the examples in this manual, even those entered at the interactive prompt, include comments. Comments in Python start with the hash character, ``#``, and extend to the end of the physical line. A comment may appear at the @@ -38,6 +36,15 @@ Let's try some simple Python commands. Start the interpreter and wait for the primary prompt, ``>>>``. (It shouldn't take long.) +.. index:: + operator: / + operator: // + operator: % + operator: + + operator: * + operator: - + operator: ** + .. _tut-numbers: Numbers @@ -76,6 +83,8 @@ operator; to calculate the remainder you can use ``%``:: >>> 5 * 3 + 2 # result * divisor + remainder 17 +For more details on how the ``//`` and ``%`` operators work with negative numbers see :ref:`faq-floordivision` + With Python, it is possible to use the ``**`` operator to calculate powers [#]_:: >>> 5 ** 2 # 5 squared @@ -145,12 +154,12 @@ to escape quotes:: "doesn't" >>> "doesn't" # ...or use double quotes instead "doesn't" - >>> '"Yes," they said.' - '"Yes," they said.' - >>> "\"Yes,\" they said." - '"Yes," they said.' - >>> '"Isn\'t," they said.' - '"Isn\'t," they said.' + >>> '"Yes," he said.' + '"Yes," he said.' + >>> "\"Yes,\" he said." + '"Yes," he said.' + >>> '"Isn\'t," she said.' + '"Isn\'t," she said.' In the interactive interpreter, the output string is enclosed in quotes and special characters are escaped with backslashes. While this might sometimes @@ -161,10 +170,10 @@ enclosed in single quotes. The :func:`print` function produces a more readable output, by omitting the enclosing quotes and by printing escaped and special characters:: - >>> '"Isn\'t," they said.' - '"Isn\'t," they said.' - >>> print('"Isn\'t," they said.') - "Isn't," they said. + >>> '"Isn\'t," she said.' + '"Isn\'t," she said.' + >>> print('"Isn\'t," she said.') + "Isn't," she said. >>> s = 'First line.\nSecond line.' # \n means newline >>> s # without print(), \n is included in the output 'First line.\nSecond line.' @@ -225,14 +234,10 @@ This only works with two literals though, not with variables or expressions:: >>> prefix = 'Py' >>> prefix 'thon' # can't concatenate a variable and a string literal - File "", line 1 - prefix 'thon' - ^ + ... SyntaxError: invalid syntax >>> ('un' * 3) 'ium' - File "", line 1 - ('un' * 3) 'ium' - ^ + ... SyntaxError: invalid syntax If you want to concatenate variables or a variable and a literal, use ``+``:: @@ -326,12 +331,10 @@ Python strings cannot be changed --- they are :term:`immutable`. Therefore, assigning to an indexed position in the string results in an error:: >>> word[0] = 'J' - Traceback (most recent call last): - File "", line 1, in + ... TypeError: 'str' object does not support item assignment >>> word[2:] = 'py' - Traceback (most recent call last): - File "", line 1, in + ... TypeError: 'str' object does not support item assignment If you need a different string, you should create a new one:: @@ -383,7 +386,7 @@ items of different types, but usually the items all have the same type. :: >>> squares [1, 4, 9, 16, 25] -Like strings (and all other built-in :term:`sequence` types), lists can be +Like strings (and all other built-in :term:`sequence` type), lists can be indexed and sliced:: >>> squares[0] # indexing returns the item @@ -394,8 +397,7 @@ indexed and sliced:: [9, 16, 25] All slice operations return a new list containing the requested elements. This -means that the following slice returns a -:ref:`shallow copy ` of the list:: +means that the following slice returns a new (shallow) copy of the list:: >>> squares[:] [1, 4, 9, 16, 25]