bpo-30052: Link `bytes` & `bytearray` to stdtypes not functions (GH-1271) (GH-1915)

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..
(cherry picked from commit c6db4811f9)

Doc/library/functions.rst

@@ -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-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:`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

Doc/library/stdtypes.rst

@@ -2264,8 +2264,8 @@ The :mod:`array` module supports efficient storage of basic data types like
 
 .. _typebytes:
 
-Bytes
+Bytes Objects
------
+-------------
 
 .. index:: object: bytes
 
@@ -2274,65 +2274,67 @@ 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
+.. class:: bytes([source[, encoding[, errors]]])
-literals, except that a ``b`` prefix is added:
 
-* Single quotes: ``b'still allows embedded "double" quotes'``
+   Firstly, the syntax for bytes literals is largely the same as that for string
-* Double quotes: ``b"still allows embedded 'single' quotes"``.
+   literals, except that a ``b`` prefix is added:
-* Triple quoted: ``b'''3 single quotes'''``, ``b"""3 double quotes"""``
 
-Only ASCII characters are permitted in bytes literals (regardless of the
+   * Single quotes: ``b'still allows embedded "double" quotes'``
-declared source code encoding). Any binary values over 127 must be entered
+   * Double quotes: ``b"still allows embedded 'single' quotes"``.
-into bytes literals using the appropriate escape sequence.
+   * Triple quoted: ``b'''3 single quotes'''``, ``b"""3 double quotes"""``
 
-As with string literals, bytes literals may also use a ``r`` prefix to disable
+   Only ASCII characters are permitted in bytes literals (regardless of the
-processing of escape sequences. See :ref:`strings` for more about the various
+   declared source code encoding). Any binary values over 127 must be entered
-forms of bytes literal, including supported escape sequences.
+   into bytes literals using the appropriate escape sequence.
 
-While bytes literals and representations are based on ASCII text, bytes
+   As with string literals, bytes literals may also use a ``r`` prefix to disable
-objects actually behave like immutable sequences of integers, with each
+   processing of escape sequences. See :ref:`strings` for more about the various
-value in the sequence restricted such that ``0 <= x < 256`` (attempts to
+   forms of bytes literal, including supported escape sequences.
-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).
 
-In addition to the literal forms, bytes objects can be created in a number of
+   While bytes literals and representations are based on ASCII text, bytes
-other ways:
+   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)``
+   In addition to the literal forms, bytes objects can be created in a number of
-* From an iterable of integers: ``bytes(range(20))``
+   other ways:
-* Copying existing binary data via the buffer protocol:  ``bytes(obj)``
 
-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
+   Also see the :ref:`bytes <func-bytes>` built-in.
-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:
 
-.. 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
+   .. classmethod:: fromhex(string)
-   given string object.  The string must contain two hexadecimal digits per
-   byte, with ASCII spaces being ignored.
 
-   >>> bytes.fromhex('2Ef0 F1f2  ')
+      This :class:`bytes` class method returns a bytes object, decoding the
-   b'.\xf0\xf1\xf2'
+      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 bytes object into its
+      >>> bytes.fromhex('2Ef0 F1f2  ')
-hexadecimal representation.
+      b'.\xf0\xf1\xf2'
 
-.. 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
+   .. method:: hex()
-   byte in the instance.
 
-   >>> b'\xf0\xf1\xf2'.hex()
+      Return a string object containing two hexadecimal digits for each
-   'f0f1f2'
+      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
@@ -2362,45 +2364,49 @@ 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
+objects.
-they are always created by calling the constructor:
 
-* Creating an empty instance: ``bytearray()``
+.. class:: bytearray([source[, encoding[, errors]]])
-* 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!')``
 
-As bytearray objects are mutable, they support the
+   There is no dedicated literal syntax for bytearray objects, instead
-:ref:`mutable <typesseq-mutable>` sequence operations in addition to the
+   they are always created by calling the constructor:
-common bytes and bytearray operations described in :ref:`bytes-methods`.
 
-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
+   As bytearray objects are mutable, they support the
-numbers are a commonly used format for describing binary data. Accordingly,
+   :ref:`mutable <typesseq-mutable>` sequence operations in addition to the
-the bytearray type has an additional class method to read data in that format:
+   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
+   Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal
-   the given string object.  The string must contain two hexadecimal digits
+   numbers are a commonly used format for describing binary data. Accordingly,
-   per byte, with ASCII spaces being ignored.
+   the bytearray type has an additional class method to read data in that format:
 
-   >>> bytearray.fromhex('2Ef0 F1f2  ')
+   .. classmethod:: fromhex(string)
-   bytearray(b'.\xf0\xf1\xf2')
 
-A reverse conversion function exists to transform a bytearray object into its
+      This :class:`bytearray` class method returns bytearray object, decoding
-hexadecimal representation.
+      the given string object.  The string must contain two hexadecimal digits
+      per byte, with ASCII whitespace being ignored.
 
-.. method:: bytearray.hex()
+      >>> bytearray.fromhex('2Ef0 F1f2  ')
+      bytearray(b'.\xf0\xf1\xf2')
 
-   Return a string object containing two hexadecimal digits for each
+   A reverse conversion function exists to transform a bytearray object into its
-   byte in the instance.
+   hexadecimal representation.
 
-   >>> bytearray(b'\xf0\xf1\xf2').hex()
+   .. method:: hex()
-   'f0f1f2'
 
-   .. 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

Doc/reference/datamodel.rst

@@ -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
+         (like ``b'abc'``) and the built-in :func:`bytes()` constructor
-         construct bytes objects.  Also, bytes objects can be decoded to strings
+         can be used to create bytes objects.  Also, bytes objects can be
-         via the :meth:`~bytes.decode` method.
+         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
+         :func:`bytearray` constructor.  Aside from being mutable
-         unhashable), byte arrays otherwise provide the same interface and
+         (and hence unhashable), byte arrays otherwise provide the same interface
-         functionality as immutable bytes objects.
+         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
+   Called by :ref:`bytes <func-bytes>` to compute a byte-string representation
-   object. This should return a ``bytes`` object.
+   of an object. This should return a :class:`bytes` object.
 
    .. index::
       single: string; __format__() (object method)