mirror of https://github.com/python/cpython
bpo-30052: Link `bytes` & `bytearray` to stdtypes not functions (GH-1271)
Builtin container types have two potential link targets in the docs: - their entry in the list of builtin callables - their type documentation This change brings `bytes` and `bytearray` into line with other container types by having cross-references default to linking to their type documentation, rather than their builtin callable entry.
This commit is contained in:
csabella
Nick Coghlan
parent
d819ad9832
commit
c6db4811f9
|
|
@ -16,8 +16,8 @@ are always available. They are listed here in alphabetical order.
|
|||
:func:`ascii` :func:`enumerate` :func:`input` :func:`oct` :func:`staticmethod`
|
||||
: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-bytearray|_ :func:`filter` :func:`issubclass` :func:`pow` :func:`super`
|
||||
|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:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip`
|
||||
|
|
@ -37,7 +37,8 @@ are always available. They are listed here in alphabetical order.
|
|||
.. |func-str| replace:: ``str()``
|
||||
.. |func-tuple| replace:: ``tuple()``
|
||||
.. |func-range| replace:: ``range()``
|
||||
|
||||
.. |func-bytearray| replace:: ``bytearray()``
|
||||
.. |func-bytes| replace:: ``bytes()``
|
||||
|
||||
.. function:: abs(x)
|
||||
|
||||
|
|
@ -99,6 +100,7 @@ are always available. They are listed here in alphabetical order.
|
|||
|
||||
.. _func-bytearray:
|
||||
.. class:: bytearray([source[, encoding[, errors]]])
|
||||
:noindex:
|
||||
|
||||
Return a new array of bytes. The :class:`bytearray` class is a mutable
|
||||
sequence of integers in the range 0 <= x < 256. It has most of the usual
|
||||
|
|
@ -128,6 +130,7 @@ are always available. They are listed here in alphabetical order.
|
|||
|
||||
.. _func-bytes:
|
||||
.. class:: bytes([source[, encoding[, errors]]])
|
||||
:noindex:
|
||||
|
||||
Return a new "bytes" object, which is an immutable sequence of integers in
|
||||
the range ``0 <= x < 256``. :class:`bytes` is an immutable version of
|
||||
|
|
|
|||
|
|
@ -2265,8 +2265,8 @@ The :mod:`array` module supports efficient storage of basic data types like
|
|||
|
||||
.. _typebytes:
|
||||
|
||||
Bytes
|
||||
-----
|
||||
Bytes Objects
|
||||
-------------
|
||||
|
||||
.. index:: object: bytes
|
||||
|
||||
|
|
@ -2275,69 +2275,71 @@ binary protocols are based on the ASCII text encoding, bytes objects offer
|
|||
several methods that are only valid when working with ASCII compatible
|
||||
data and are closely related to string objects in a variety of other ways.
|
||||
|
||||
Firstly, the syntax for bytes literals is largely the same as that for string
|
||||
literals, except that a ``b`` prefix is added:
|
||||
.. class:: bytes([source[, encoding[, errors]]])
|
||||
|
||||
* Single quotes: ``b'still allows embedded "double" quotes'``
|
||||
* Double quotes: ``b"still allows embedded 'single' quotes"``.
|
||||
* Triple quoted: ``b'''3 single quotes'''``, ``b"""3 double quotes"""``
|
||||
Firstly, the syntax for bytes literals is largely the same as that for string
|
||||
literals, except that a ``b`` prefix is added:
|
||||
|
||||
Only ASCII characters are permitted in bytes literals (regardless of the
|
||||
declared source code encoding). Any binary values over 127 must be entered
|
||||
into bytes literals using the appropriate escape sequence.
|
||||
* Single quotes: ``b'still allows embedded "double" quotes'``
|
||||
* Double quotes: ``b"still allows embedded 'single' quotes"``.
|
||||
* Triple quoted: ``b'''3 single quotes'''``, ``b"""3 double quotes"""``
|
||||
|
||||
As with string literals, bytes literals may also use a ``r`` prefix to disable
|
||||
processing of escape sequences. See :ref:`strings` for more about the various
|
||||
forms of bytes literal, including supported escape sequences.
|
||||
Only ASCII characters are permitted in bytes literals (regardless of the
|
||||
declared source code encoding). Any binary values over 127 must be entered
|
||||
into bytes literals using the appropriate escape sequence.
|
||||
|
||||
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
|
||||
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
|
||||
text processing algorithms to binary data formats that are not ASCII
|
||||
compatible will usually lead to data corruption).
|
||||
As with string literals, bytes literals may also use a ``r`` prefix to disable
|
||||
processing of escape sequences. See :ref:`strings` for more about the various
|
||||
forms of bytes literal, including supported escape sequences.
|
||||
|
||||
In addition to the literal forms, bytes objects can be created in a number 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
|
||||
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
|
||||
text processing algorithms to binary data formats that are not ASCII
|
||||
compatible will usually lead to data corruption).
|
||||
|
||||
* A zero-filled bytes object of a specified length: ``bytes(10)``
|
||||
* From an iterable of integers: ``bytes(range(20))``
|
||||
* Copying existing binary data via the buffer protocol: ``bytes(obj)``
|
||||
In addition to the literal forms, bytes objects can be created in a number of
|
||||
other ways:
|
||||
|
||||
Also see the :ref:`bytes <func-bytes>` built-in.
|
||||
* A zero-filled bytes object of a specified length: ``bytes(10)``
|
||||
* From an iterable of integers: ``bytes(range(20))``
|
||||
* Copying existing binary data via the buffer protocol: ``bytes(obj)``
|
||||
|
||||
Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
|
||||
numbers are a commonly used format for describing binary data. Accordingly,
|
||||
the bytes type has an additional class method to read data in that format:
|
||||
Also see the :ref:`bytes <func-bytes>` built-in.
|
||||
|
||||
.. classmethod:: bytes.fromhex(string)
|
||||
Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
|
||||
numbers are a commonly used format for describing binary data. Accordingly,
|
||||
the bytes type has an additional class method to read data in that format:
|
||||
|
||||
This :class:`bytes` class method returns a bytes object, decoding the
|
||||
given string object. The string must contain two hexadecimal digits per
|
||||
byte, with ASCII whitespace being ignored.
|
||||
.. classmethod:: fromhex(string)
|
||||
|
||||
>>> bytes.fromhex('2Ef0 F1f2 ')
|
||||
b'.\xf0\xf1\xf2'
|
||||
This :class:`bytes` class method returns a bytes object, decoding the
|
||||
given string object. The string must contain two hexadecimal digits per
|
||||
byte, with ASCII whitespace being ignored.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
:meth:`bytes.fromhex` now skips all ASCII whitespace in the string,
|
||||
not just spaces.
|
||||
>>> bytes.fromhex('2Ef0 F1f2 ')
|
||||
b'.\xf0\xf1\xf2'
|
||||
|
||||
A reverse conversion function exists to transform a bytes object into its
|
||||
hexadecimal representation.
|
||||
.. versionchanged:: 3.7
|
||||
:meth:`bytes.fromhex` now skips all ASCII whitespace in the string,
|
||||
not just spaces.
|
||||
|
||||
.. method:: bytes.hex()
|
||||
A reverse conversion function exists to transform a bytes object into its
|
||||
hexadecimal representation.
|
||||
|
||||
Return a string object containing two hexadecimal digits for each
|
||||
byte in the instance.
|
||||
.. method:: hex()
|
||||
|
||||
>>> b'\xf0\xf1\xf2'.hex()
|
||||
'f0f1f2'
|
||||
Return a string object containing two hexadecimal digits for each
|
||||
byte in the instance.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
>>> b'\xf0\xf1\xf2'.hex()
|
||||
'f0f1f2'
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
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
|
||||
|
|
@ -2367,49 +2369,53 @@ Bytearray Objects
|
|||
.. index:: object: bytearray
|
||||
|
||||
:class:`bytearray` objects are a mutable counterpart to :class:`bytes`
|
||||
objects. There is no dedicated literal syntax for bytearray objects, instead
|
||||
they are always created by calling the constructor:
|
||||
objects.
|
||||
|
||||
* Creating an empty instance: ``bytearray()``
|
||||
* Creating a zero-filled instance with a given length: ``bytearray(10)``
|
||||
* From an iterable of integers: ``bytearray(range(20))``
|
||||
* Copying existing binary data via the buffer protocol: ``bytearray(b'Hi!')``
|
||||
.. class:: bytearray([source[, encoding[, errors]]])
|
||||
|
||||
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`.
|
||||
There is no dedicated literal syntax for bytearray objects, instead
|
||||
they are always created by calling the constructor:
|
||||
|
||||
Also see the :ref:`bytearray <func-bytearray>` built-in.
|
||||
* Creating an empty instance: ``bytearray()``
|
||||
* Creating a zero-filled instance with a given length: ``bytearray(10)``
|
||||
* From an iterable of integers: ``bytearray(range(20))``
|
||||
* Copying existing binary data via the buffer protocol: ``bytearray(b'Hi!')``
|
||||
|
||||
Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
|
||||
numbers are a commonly used format for describing binary data. Accordingly,
|
||||
the bytearray type has an additional class method to read data in that format:
|
||||
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`.
|
||||
|
||||
.. classmethod:: bytearray.fromhex(string)
|
||||
Also see the :ref:`bytearray <func-bytearray>` built-in.
|
||||
|
||||
This :class:`bytearray` class method returns bytearray object, decoding
|
||||
the given string object. The string must contain two hexadecimal digits
|
||||
per byte, with ASCII whitespace being ignored.
|
||||
Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
|
||||
numbers are a commonly used format for describing binary data. Accordingly,
|
||||
the bytearray type has an additional class method to read data in that format:
|
||||
|
||||
>>> bytearray.fromhex('2Ef0 F1f2 ')
|
||||
bytearray(b'.\xf0\xf1\xf2')
|
||||
.. classmethod:: fromhex(string)
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
:meth:`bytearray.fromhex` now skips all ASCII whitespace in the string,
|
||||
not just spaces.
|
||||
This :class:`bytearray` class method returns bytearray object, decoding
|
||||
the given string object. The string must contain two hexadecimal digits
|
||||
per byte, with ASCII whitespace being ignored.
|
||||
|
||||
A reverse conversion function exists to transform a bytearray object into its
|
||||
hexadecimal representation.
|
||||
>>> bytearray.fromhex('2Ef0 F1f2 ')
|
||||
bytearray(b'.\xf0\xf1\xf2')
|
||||
|
||||
.. method:: bytearray.hex()
|
||||
.. versionchanged:: 3.7
|
||||
:meth:`bytearray.fromhex` now skips all ASCII whitespace in the string,
|
||||
not just spaces.
|
||||
|
||||
Return a string object containing two hexadecimal digits for each
|
||||
byte in the instance.
|
||||
A reverse conversion function exists to transform a bytearray object into its
|
||||
hexadecimal representation.
|
||||
|
||||
>>> bytearray(b'\xf0\xf1\xf2').hex()
|
||||
'f0f1f2'
|
||||
.. method:: hex()
|
||||
|
||||
.. versionadded:: 3.5
|
||||
Return a string object containing two hexadecimal digits for each
|
||||
byte in the instance.
|
||||
|
||||
>>> bytearray(b'\xf0\xf1\xf2').hex()
|
||||
'f0f1f2'
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -320,9 +320,9 @@ Sequences
|
|||
|
||||
A bytes object is an immutable array. The items are 8-bit bytes,
|
||||
represented by integers in the range 0 <= x < 256. Bytes literals
|
||||
(like ``b'abc'``) and the built-in function :func:`bytes` can be used to
|
||||
construct bytes objects. Also, bytes objects can be decoded to strings
|
||||
via the :meth:`~bytes.decode` method.
|
||||
(like ``b'abc'``) and the built-in :func:`bytes()` constructor
|
||||
can be used to create bytes objects. Also, bytes objects can be
|
||||
decoded to strings via the :meth:`~bytes.decode` method.
|
||||
|
||||
Mutable sequences
|
||||
.. index::
|
||||
|
|
@ -349,9 +349,9 @@ Sequences
|
|||
.. index:: bytearray
|
||||
|
||||
A bytearray object is a mutable array. They are created by the built-in
|
||||
:func:`bytearray` constructor. Aside from being mutable (and hence
|
||||
unhashable), byte arrays otherwise provide the same interface and
|
||||
functionality as immutable bytes objects.
|
||||
:func:`bytearray` constructor. Aside from being mutable
|
||||
(and hence unhashable), byte arrays otherwise provide the same interface
|
||||
and functionality as immutable :class:`bytes` objects.
|
||||
|
||||
.. index:: module: array
|
||||
|
||||
|
|
@ -1253,8 +1253,8 @@ Basic customization
|
|||
|
||||
.. index:: builtin: bytes
|
||||
|
||||
Called by :func:`bytes` to compute a byte-string representation of an
|
||||
object. This should return a ``bytes`` object.
|
||||
Called by :ref:`bytes <func-bytes>` to compute a byte-string representation
|
||||
of an object. This should return a :class:`bytes` object.
|
||||
|
||||
.. index::
|
||||
single: string; __format__() (object method)
|
||||
|
|
|
|||
Loading…
Reference in New Issue