diff options
| -rw-r--r-- | Doc/library/functions.rst | 109 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 327 |
2 files changed, 247 insertions, 189 deletions
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index ddc946b..61e4932 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -17,9 +17,9 @@ are always available. They are listed here in alphabetical order. :func:`bin` :func:`eval` :func:`int` :func:`open` :func:`str` :func:`bool` :func:`exec` :func:`isinstance` :func:`ord` :func:`sum` :func:`bytearray` :func:`filter` :func:`issubclass` :func:`pow` :func:`super` -:func:`bytes` :func:`float` :func:`iter` :func:`print` :func:`tuple` +:func:`bytes` :func:`float` :func:`iter` :func:`print` |func-tuple|_ :func:`callable` :func:`format` :func:`len` :func:`property` :func:`type` -:func:`chr` |func-frozenset|_ :func:`list` :func:`range` :func:`vars` +:func:`chr` |func-frozenset|_ |func-list|_ |func-range|_ :func:`vars` :func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip` :func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__` :func:`complex` :func:`hasattr` :func:`max` :func:`round` @@ -33,6 +33,9 @@ are always available. They are listed here in alphabetical order. .. |func-frozenset| replace:: ``frozenset()`` .. |func-memoryview| replace:: ``memoryview()`` .. |func-set| replace:: ``set()`` +.. |func-list| replace:: ``list()`` +.. |func-tuple| replace:: ``tuple()`` +.. |func-range| replace:: ``range()`` .. function:: abs(x) @@ -93,6 +96,7 @@ are always available. They are listed here in alphabetical order. .. index:: pair: Boolean; type +.. _func-bytearray: .. function:: bytearray([source[, encoding[, errors]]]) Return a new array of bytes. The :class:`bytearray` type is a mutable @@ -119,6 +123,7 @@ are always available. They are listed here in alphabetical order. Without an argument, an array of size 0 is created. +.. _func-bytes: .. function:: bytes([source[, encoding[, errors]]]) Return a new "bytes" object, which is an immutable sequence of integers in @@ -692,16 +697,12 @@ are always available. They are listed here in alphabetical order. sequence (string, tuple or list) or a mapping (dictionary). +.. _func-list: .. function:: list([iterable]) + :noindex: - Return a list whose items are the same and in the same order as *iterable*'s - items. *iterable* may be either a sequence, a container that supports - iteration, or an iterator object. If *iterable* is already a list, a copy is - made and returned, similar to ``iterable[:]``. For instance, ``list('abc')`` - returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. - If no argument is given, returns a new empty list, ``[]``. - - :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`. + Rather than being a function, :class:`list` is actually a mutable + sequence type, as documented in :ref:`typesseq`. .. function:: locals() @@ -1059,79 +1060,12 @@ are always available. They are listed here in alphabetical order. ``fdel`` corresponding to the constructor arguments. -.. XXX does accept objects with __index__ too +.. _func-range: .. function:: range([start,] stop[, step]) + :noindex: - This is a versatile function to create iterables yielding arithmetic - progressions. It is most often used in :keyword:`for` loops. The arguments - must be integers. If the *step* argument is omitted, it defaults to ``1``. - If the *start* argument is omitted, it defaults to ``0``. The full form - returns an iterable of integers ``[start, start + step, start + 2 * step, - ...]``. If *step* is positive, the last element is the largest ``start + i * - step`` less than *stop*; if *step* is negative, the last element is the - smallest ``start + i * step`` greater than *stop*. *step* must not be zero - (or else :exc:`ValueError` is raised). Range objects have read-only data - attributes :attr:`start`, :attr:`stop` and :attr:`step` which return the - argument values (or their default). Example: - - >>> list(range(10)) - [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] - >>> list(range(1, 11)) - [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - >>> list(range(0, 30, 5)) - [0, 5, 10, 15, 20, 25] - >>> list(range(0, 10, 3)) - [0, 3, 6, 9] - >>> list(range(0, -10, -1)) - [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] - >>> list(range(0)) - [] - >>> list(range(1, 0)) - [] - - Range objects implement the :class:`collections.Sequence` ABC, and provide - features such as containment tests, element index lookup, slicing and - support for negative indices (see :ref:`typesseq`): - - >>> r = range(0, 20, 2) - >>> r - range(0, 20, 2) - >>> 11 in r - False - >>> 10 in r - True - >>> r.index(10) - 5 - >>> r[5] - 10 - >>> r[:5] - range(0, 10, 2) - >>> r[-1] - 18 - - Testing range objects for equality with ``==`` and ``!=`` compares - them as sequences. That is, two range objects are considered equal if - they represent the same sequence of values. (Note that two range - objects that compare equal might have different :attr:`start`, - :attr:`stop` and :attr:`step` attributes, for example ``range(0) == - range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.) - - Ranges containing absolute values larger than :data:`sys.maxsize` are permitted - but some features (such as :func:`len`) will raise :exc:`OverflowError`. - - .. versionchanged:: 3.2 - Implement the Sequence ABC. - Support slicing and negative indices. - Test integers for membership in constant time instead of iterating - through all items. - - .. versionchanged:: 3.3 - Define '==' and '!=' to compare range objects based on the - sequence of values they define (instead of comparing based on - object identity). - - .. versionadded:: 3.3 - The :attr:`start`, :attr:`stop` and :attr:`step` attributes. + Rather than being a function, :class:`range` is actually an immutable + sequence type, as documented in :ref:`typesseq`. .. function:: repr(object) @@ -1251,6 +1185,7 @@ are always available. They are listed here in alphabetical order. standard type hierarchy in :ref:`types`. +.. _func-str: .. function:: str([object[, encoding[, errors]]]) Return a string version of an object, using one of the following modes: @@ -1352,16 +1287,12 @@ are always available. They are listed here in alphabetical order. <http://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_. +.. _func-tuple: .. function:: tuple([iterable]) + :noindex: - Return a tuple whose items are the same and in the same order as *iterable*'s - items. *iterable* may be a sequence, a container that supports iteration, or an - iterator object. If *iterable* is already a tuple, it is returned unchanged. - For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2, - 3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty - tuple, ``()``. - - :class:`tuple` is an immutable sequence type, as documented in :ref:`typesseq`. + Rather than being a function, :class:`tuple` is actually an immutable + sequence type, as documented in :ref:`typesseq`. .. function:: type(object) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 3242d4a..8adbabe 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -829,6 +829,20 @@ The ``in`` and ``not in`` operations have the same priorities as the comparison operations. The ``+`` (concatenation) and ``*`` (repetition) operations have the same priority as the corresponding numeric operations. +.. index:: + triple: operations on; sequence; types + builtin: len + builtin: min + builtin: max + pair: concatenation; operation + pair: repetition; operation + pair: subscript; operation + pair: slice; operation + operator: in + operator: not in + single: count() (sequence method) + single: index() (sequence method) + +--------------------------+--------------------------------+----------+ | Operation | Result | Notes | +==========================+================================+==========+ @@ -841,8 +855,8 @@ operations have the same priority as the corresponding numeric operations. | ``s + t`` | the concatenation of *s* and | (6)(7) | | | *t* | | +--------------------------+--------------------------------+----------+ -| ``s * n, n * s`` | *n* shallow copies of *s* | (2)(7) | -| | concatenated | | +| ``s * n`` or | *n* shallow copies of *s* | (2)(7) | +| ``n * s`` | concatenated | | +--------------------------+--------------------------------+----------+ | ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) | +--------------------------+--------------------------------+----------+ @@ -857,7 +871,7 @@ operations have the same priority as the corresponding numeric operations. +--------------------------+--------------------------------+----------+ | ``max(s)`` | largest item of *s* | | +--------------------------+--------------------------------+----------+ -| ``s.index(x, [i[, j]])`` | index of the first occurence | \(8) | +| ``s.index(x[, i[, j]])`` | index of the first occurence | \(8) | | | of *x* in *s* (at or after | | | | index *i* and before index *j*)| | +--------------------------+--------------------------------+----------+ @@ -871,18 +885,6 @@ This means that to compare equal, every element must compare equal and the two sequences must be of the same type and have the same length. (For full details see :ref:`comparisons` in the language reference.) -.. index:: - triple: operations on; sequence; types - builtin: len - builtin: min - builtin: max - pair: concatenation; operation - pair: repetition; operation - pair: subscript; operation - pair: slice; operation - operator: in - operator: not in - Notes: (1) @@ -948,14 +950,14 @@ Notes: * if concatenating :class:`str` objects, you can build a list and use :meth:`str.join` at the end or else write to a :class:`io.StringIO` - instance and retrieve its value when complete; + instance and retrieve its value when complete * if concatenating :class:`bytes` objects, you can similarly use :meth:`bytes.join` or :class:`io.BytesIO`, or you can do in-place concatenation with a :class:`bytearray` object. :class:`bytearray` - objects are mutable and have an efficient overallocation mechanism. + objects are mutable and have an efficient overallocation mechanism - * if concatenating :class:`tuple` objects, extend a :class:`list` instead. + * if concatenating :class:`tuple` objects, extend a :class:`list` instead * for other types, investigate the relevant class documentation @@ -982,6 +984,7 @@ Immutable Sequence Types .. index:: triple: immutable; sequence; types object: tuple + builtin: hash The only operation that immutable sequence types generally implement that is not also implemented by mutable sequence types is support for the :func:`hash` @@ -1022,9 +1025,9 @@ accepts integers that meet the value restriction ``0 <= x <= 255``). pair: slice; assignment statement: del single: append() (sequence method) + single: clear() (sequence method) + single: copy() (sequence method) single: extend() (sequence method) - single: count() (sequence method) - single: index() (sequence method) single: insert() (sequence method) single: pop() (sequence method) single: remove() (sequence method) @@ -1048,24 +1051,29 @@ accepts integers that meet the value restriction ``0 <= x <= 255``). | ``del s[i:j:k]`` | removes the elements of | | | | ``s[i:j:k]`` from the list | | +------------------------------+--------------------------------+---------------------+ -| ``s.append(x)`` | same as ``s[len(s):len(s)] = | | -| | [x]`` | | +| ``s.append(x)`` | appends *x* to the end of the | | +| | sequence (same as | | +| | ``s[len(s):len(s)] = [x]``) | | +------------------------------+--------------------------------+---------------------+ -| ``s.clear()`` | remove all items from ``s`` | \(5) | +| ``s.clear()`` | removes all items from ``s`` | \(5) | | | (same as ``del s[:]``) | | +------------------------------+--------------------------------+---------------------+ -| ``s.copy()`` | return a shallow copy of ``s`` | \(5) | +| ``s.copy()`` | creates a shallow copy of ``s``| \(5) | | | (same as ``s[:]``) | | +------------------------------+--------------------------------+---------------------+ -| ``s.extend(t)`` | same as ``s[len(s):len(s)] = | | -| | t`` | | +| ``s.extend(t)`` | extends *s* with the | | +| | contents of *t* (same as | | +| | ``s[len(s):len(s)] = t``) | | +------------------------------+--------------------------------+---------------------+ -| ``s.insert(i, x)`` | same as ``s[i:i] = [x]`` | | +| ``s.insert(i, x)`` | inserts *x* into *s* at the | | +| | index given by *i* | | +| | (same as ``s[i:i] = [x]``) | | +------------------------------+--------------------------------+---------------------+ -| ``s.pop([i])`` | same as ``x = s[i]; del s[i]; | \(2) | -| | return x`` | | +| ``s.pop([i])`` | retrieves the item at *i* and | \(2) | +| | also removes it from *s* | | +------------------------------+--------------------------------+---------------------+ -| ``s.remove(x)`` | same as ``del s[s.index(x)]`` | \(3) | +| ``s.remove(x)`` | remove the first item from *s* | \(3) | +| | where ``s[i] == x`` | | +------------------------------+--------------------------------+---------------------+ | ``s.reverse()`` | reverses the items of *s* in | \(4) | | | place | | @@ -1109,55 +1117,67 @@ Lists are mutable sequences, typically used to store collections of homogeneous items (where the precise degree of similarity will vary by application). -Lists may be constructed in several ways: +.. class:: list([iterable]) + + Lists may be constructed in several ways: + + * Using a pair of square brackets to denote the empty list: ``[]`` + * Using square brackets, separating items with commas: ``[a]``, ``[a, b, c]`` + * Using a list comprehension: ``[x for x in iterable]`` + * Using the type constructor: ``list()`` or ``list(iterable)`` -* Using a pair of square brackets to denote the empty list: ``[]`` -* Using square brackets, separating items with commas: ``[a]``, ``[a, b, c]`` -* Using a list comprehension: ``[x for x in iterable]`` -* Using the :func:`list` built-in: ``list()`` or ``list(iterable)`` + The constructor builds a list whose items are the same and in the same + order as *iterable*'s items. *iterable* may be either a sequence, a + container that supports iteration, or an iterator object. If *iterable* + is already a list, a copy is made and returned, similar to ``iterable[:]``. + For example, ``list('abc')`` returns ``['a', 'b', 'c']`` and + ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. + If no argument is given, the constructor creates a new empty list, ``[]``. -Many other operations also produce lists, including the :func:`sorted` built-in. -Lists implement all of the :ref:`common <typesseq-common>` and -:ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the -following additional method: + Many other operations also produce lists, including the :func:`sorted` + built-in. -.. method:: list.sort(*, key=None, reverse=None) + Lists implement all of the :ref:`common <typesseq-common>` and + :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the + following additional method: - This method sorts the list in place, using only ``<`` comparisons - between items. Exceptions are not suppressed - if any comparison operations - fail, the entire sort operation will fail (and the list will likely be left - in a partially modified state). + .. method:: list.sort(*, key=None, reverse=None) - *key* specifies a function of one argument that is used to extract a - comparison key from each list element (for example, ``key=str.lower``). - The key corresponding to each item in the list is calculated once and - then used for the entire sorting process. The default value of ``None`` - means that list items are sorted directly without calculating a separate - key value. + This method sorts the list in place, using only ``<`` comparisons + between items. Exceptions are not suppressed - if any comparison operations + fail, the entire sort operation will fail (and the list will likely be left + in a partially modified state). - The :func:`functools.cmp_to_key` utility is available to convert a 2.x - style *cmp* function to a *key* function. + *key* specifies a function of one argument that is used to extract a + comparison key from each list element (for example, ``key=str.lower``). + The key corresponding to each item in the list is calculated once and + then used for the entire sorting process. The default value of ``None`` + means that list items are sorted directly without calculating a separate + key value. - *reverse* is a boolean value. If set to ``True``, then the list elements - are sorted as if each comparison were reversed. + The :func:`functools.cmp_to_key` utility is available to convert a 2.x + style *cmp* function to a *key* function. - This method modifies the sequence in place for economy of space when - sorting a large sequence. To remind users that it operates by side - effect, it does not return the sorted sequence (use :func:`sorted` to - explicitly request a new sorted list instance). + *reverse* is a boolean value. If set to ``True``, then the list elements + are sorted as if each comparison were reversed. - The :meth:`sort` method is guaranteed to be stable. A sort is stable if it - guarantees not to change the relative order of elements that compare equal - --- this is helpful for sorting in multiple passes (for example, sort by - department, then by salary grade). + This method modifies the sequence in place for economy of space when + sorting a large sequence. To remind users that it operates by side + effect, it does not return the sorted sequence (use :func:`sorted` to + explicitly request a new sorted list instance). - .. impl-detail:: + The :meth:`sort` method is guaranteed to be stable. A sort is stable if it + guarantees not to change the relative order of elements that compare equal + --- this is helpful for sorting in multiple passes (for example, sort by + department, then by salary grade). - While a list is being sorted, the effect of attempting to mutate, or even - inspect, the list is undefined. The C implementation of Python makes the - list appear empty for the duration, and raises :exc:`ValueError` if it can - detect that the list has been mutated during a sort. + .. impl-detail:: + + While a list is being sorted, the effect of attempting to mutate, or even + inspect, the list is undefined. The C implementation of Python makes the + list appear empty for the duration, and raises :exc:`ValueError` if it can + detect that the list has been mutated during a sort. .. _typesseq-tuple: @@ -1173,22 +1193,35 @@ built-in). Tuples are also used for cases where an immutable sequence of homogeneous data is needed (such as allowing storage in a :class:`set` or :class:`dict` instance). -Tuples may be constructed in a number of ways: +.. class:: tuple([iterable]) + + Tuples may be constructed in a number of ways: + + * Using a pair of parentheses to denote the empty tuple: ``()`` + * Using a trailing comma for a singleton tuple: ``a,`` or ``(a,)`` + * Separating items with commas: ``a, b, c`` or ``(a, b, c)`` + * Using the :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)`` -* Using a pair of parentheses to denote the empty tuple: ``()`` -* Using a trailing comma for a singleton tuple: ``a,`` or ``(a,)`` -* Separating items with commas: ``a, b, c`` or ``(a, b, c)`` -* Using the :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)`` + The constructor builds a tuple whose items are the same and in the same + order as *iterable*'s items. *iterable* may be either a sequence, a + container that supports iteration, or an iterator object. If *iterable* + is already a tuple, it is returned unchanged. For example, + ``tuple('abc')`` returns ``('a', 'b', 'c')`` and + ``tuple( [1, 2, 3] )`` returns ``(1, 2, 3)``. + If no argument is given, the constructor creates a new empty tuple, ``()``. -Note that the parentheses are optional (except in the empty tuple case, or -when needed to avoid syntactic ambiguity). It is actually the comma which -makes a tuple, not the parentheses. + Note that it is actually the comma which makes a tuple, not the parentheses. + The parentheses are optional, except in the empty tuple case, or + when they are needed to avoid syntactic ambiguity. For example, + ``f(a, b, c)`` is a function call with three arguments, while + ``f((a, b, c))`` is a function call with a 3-tuple as the sole argument. -Tuples implement all of the :ref:`common <typesseq-common>` sequence -operations. + Tuples implement all of the :ref:`common <typesseq-common>` sequence + operations. -For heterogeneous collections of data, :func:`collections.namedtuple` may -be more appropriate than a simple tuple object. +For heterogeneous collections of data where access by name is clearer than +access by index, :func:`collections.namedtuple` may be a more appropriate +choice than a simple tuple object. .. _typesseq-range: @@ -1199,17 +1232,69 @@ Ranges .. index:: object: range The :class:`range` type represents an immutable sequence of numbers and is -commonly used for looping a specific number of times. Instances are created -using the :func:`range` built-in. +commonly used for looping a specific number of times in :keyword:`for` +loops. + +.. class:: range([start, ]stop[, step]) + + The arguments to the range constructor must be integers (either built-in + :class:`int` or any object that implements the ``__index__`` special + method). If the *step* argument is omitted, it defaults to ``1``. + If the *start* argument is omitted, it defaults to ``0``. + If *step* is zero, :exc:`ValueError` is raised. + + For a positive *step*, the contents of a range ``r`` are determined by the + formula ``r[i] = start + step*i`` where ``i >= 0`` and + ``r[i] < stop``. + + For a negative *step*, the contents of the range are still determined by + the formula ``r[i] = start + step*i``, but the constraints are ``i >= 0`` + and ``r[i] > stop``. + + A range object will be empty if ``r[0]`` does not meant the value + constraint. Ranges do support negative indices, but these are interpreted + as indexing from the end of the sequence determined by the positive + indices. + + Ranges containing absolute values larger than :data:`sys.maxsize` are + permitted but some features (such as :func:`len`) may raise + :exc:`OverflowError`. -For positive indices with results between the defined ``start`` and ``stop`` -values, integers within the range are determined by the formula: -``r[i] = start + step*i`` + Range examples:: -For negative indices and slicing operations, a range instance determines the -appropriate result for the corresponding tuple and returns either the -appropriate integer (for negative indices) or an appropriate range object -(for slicing operations) . + >>> list(range(10)) + [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + >>> list(range(1, 11)) + [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] + >>> list(range(0, 30, 5)) + [0, 5, 10, 15, 20, 25] + >>> list(range(0, 10, 3)) + [0, 3, 6, 9] + >>> list(range(0, -10, -1)) + [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] + >>> list(range(0)) + [] + >>> list(range(1, 0)) + [] + + Ranges implement all of the :ref:`common <typesseq-common>` sequence operations + except concatenation and repetition (due to the fact that range objects can + only represent sequences that follow a strict pattern and repetition and + concatenation will usually violate that pattern). + + .. data: start + + The value of the *start* parameter (or ``0`` if the parameter was + not supplied) + + .. data: stop + + The value of the *stop* parameter + + .. data: step + + The value of the *step* parameter (or ``1`` if the parameter was + not supplied) The advantage of the :class:`range` type over a regular :class:`list` or :class:`tuple` is that a :class:`range` object will always take the same @@ -1217,10 +1302,46 @@ The advantage of the :class:`range` type over a regular :class:`list` or only stores the ``start``, ``stop`` and ``step`` values, calculating individual items and subranges as needed). -Ranges implement all of the :ref:`common <typesseq-common>` sequence operations -except concatenation and repetition (due to the fact that range objects can -only represent sequences that follow a strict pattern and repetition and -concatenation will usually violate that pattern). +Range objects implement the :class:`collections.Sequence` ABC, and provide +features such as containment tests, element index lookup, slicing and +support for negative indices (see :ref:`typesseq`): + + >>> r = range(0, 20, 2) + >>> r + range(0, 20, 2) + >>> 11 in r + False + >>> 10 in r + True + >>> r.index(10) + 5 + >>> r[5] + 10 + >>> r[:5] + range(0, 10, 2) + >>> r[-1] + 18 + +Testing range objects for equality with ``==`` and ``!=`` compares +them as sequences. That is, two range objects are considered equal if +they represent the same sequence of values. (Note that two range +objects that compare equal might have different :attr:`start`, +:attr:`stop` and :attr:`step` attributes, for example ``range(0) == +range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.) + +.. versionchanged:: 3.2 + Implement the Sequence ABC. + Support slicing and negative indices. + Test :class:`int` objects for membership in constant time instead of + iterating through all items. + +.. versionchanged:: 3.3 + Define '==' and '!=' to compare range objects based on the + sequence of values they define (instead of comparing based on + object identity). + +.. versionadded:: 3.3 + The :attr:`start`, :attr:`stop` and :attr:`step` attributes. .. _textseq: @@ -1247,13 +1368,15 @@ Triple quoted strings may span multiple lines - all associated whitespace will be included in the string literal. String literals that are part of a single expression and have only whitespace -between them will be implicitly converted to a single string literal. +between them will be implicitly converted to a single string literal. That +is, ``("spam " "eggs") == "spam eggs"``. See :ref:`strings` for more about the various forms of string literal, including supported escape sequences, and the ``r`` ("raw") prefix that disables most escape sequence processing. -Strings may also be created from other objects with the :func:`str` built-in. +Strings may also be created from other objects with the :ref:`str <func-str>` +built-in. Since there is no separate "character" type, indexing a string produces strings of length 1. That is, for a non-empty string *s*, ``s[0] == s[0:1]``. @@ -2002,6 +2125,8 @@ other ways: * From an iterable of integers: ``bytes(range(20))`` * Copying existing binary data via the buffer protocol: ``bytes(obj)`` +Also see the :ref:`bytes <func-bytes>` built-in. + Since bytes objects are sequences of integers, 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 and @@ -2043,6 +2168,8 @@ As bytearray objects are mutable, they support the :ref:`mutable <typesseq-mutable>` sequence operations in addition to the common bytes and bytearray operations described in :ref:`bytes-methods`. +Also see the :ref:`bytearray <func-bytearray>` built-in. + .. _bytes-methods: @@ -2097,15 +2224,15 @@ the ASCII character set is assumed (text strings use Unicode semantics). The search operations (:keyword:`in`, :meth:`count`, :meth:`find`, :meth:`index`, :meth:`rfind` and :meth:`rindex`) all accept both integers -in the range 0 to 255 as well as bytes and byte array sequences. +in the range 0 to 255 (inclusive) as well as bytes and byte array sequences. .. versionchanged:: 3.3 - All of the search methods also accept an integer in range 0 to 255 - (a byte) as their first argument. + All of the search methods also accept an integer in the range 0 to 255 + (inclusive) as their first argument. Each bytes and bytearray instance provides a :meth:`decode` convenience -method that is the inverse of "meth:`str.encode`: +method that is the inverse of :meth:`str.encode`: .. method:: bytes.decode(encoding="utf-8", errors="strict") bytearray.decode(encoding="utf-8", errors="strict") @@ -2563,7 +2690,7 @@ A :dfn:`set` object is an unordered collection of distinct :term:`hashable` obje Common uses include membership testing, removing duplicates from a sequence, and computing mathematical operations such as intersection, union, difference, and symmetric difference. -(For other containers see the built in :class:`dict`, :class:`list`, +(For other containers see the built-in :class:`dict`, :class:`list`, and :class:`tuple` classes, and the :mod:`collections` module.) Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in @@ -2763,7 +2890,7 @@ Mapping Types --- :class:`dict` A :dfn:`mapping` object maps :term:`hashable` values to arbitrary objects. Mappings are mutable objects. There is currently only one standard mapping -type, the :dfn:`dictionary`. (For other containers see the built in +type, the :dfn:`dictionary`. (For other containers see the built-in :class:`list`, :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.) |