Accept mutable bytes-like objects

Doc/library/socket.rst

 :mod:`socket` --- Low-level networking interface
 ================================================
 
 .. module:: socket
    :synopsis: Low-level networking interface.
 
 
 This module provides access to the BSD *socket* interface. It is available on
 all modern Unix systems, Windows, MacOS, and probably additional platforms.
 
@@ skipping 28 matching lines @@
 Depending on the system and the build options, various socket families
 are supported by this module.
 
 The address format required by a particular socket object is automatically
 selected based on the address family specified when the socket object was
 created.  Socket addresses are represented as follows:
 
 - The address of an :const:`AF_UNIX` socket bound to a file system node
   is represented as a string, using the file system encoding and the
   ``'surrogateescape'`` error handler (see :pep:`383`).  An address in
-  Linux's abstract namespace is returned as a :class:`bytes` object with
+  Linux's abstract namespace is returned as a :term:`bytes-like object` with
   an initial null byte; note that sockets in this namespace can
   communicate with normal file system sockets, so programs intended to
   run on Linux may need to deal with both types of address.  A string or
-  :class:`bytes` object can be used for either type of address when
+  bytes-like object can be used for either type of address when
   passing it as an argument.
 
    .. versionchanged:: 3.3
       Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
       encoding.
 
+   .. versionchanged: 3.5
+      Writable :term:`bytes-like object` is now accepted.
+
 - A pair ``(host, port)`` is used for the :const:`AF_INET` address family,
   where *host* is a string representing either a hostname in Internet domain
   notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``,
   and *port* is an integer.
 
 - For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
   scopeid)`` is used, where *flowinfo* and *scopeid* represent the ``sin6_flowinfo``
   and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C.  For
   :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for
   backward compatibility.  Note, however, omission of *scopeid* can cause problems
@@ skipping 532 matching lines @@
    If the IPv4 address string passed to this function is invalid,
    :exc:`OSError` will be raised. Note that exactly what is valid depends on
    the underlying C implementation of :c:func:`inet_aton`.
 
    :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used
    instead for IPv4/v6 dual stack support.
 
 
 .. function:: inet_ntoa(packed_ip)
 
-   Convert a 32-bit packed IPv4 address (a bytes object four characters in
-   length) to its standard dotted-quad string representation (for example,
+   Convert a 32-bit packed IPv4 address (a :term:`bytes-like object` four
+   characters in length) to its standard dotted-quad string representation (for example,

[Martin Panter, 2015/03/20 02:41:08]

four bytes in length

[storchaka, 2015/03/20 07:47:34]

Done.

    '123.45.67.89').  This is useful when conversing with a program that uses the
    standard C library and needs objects of type :c:type:`struct in_addr`, which
    is the C type for the 32-bit packed binary data this function takes as an
    argument.
 
    If the byte sequence passed to this function is not exactly 4 bytes in
    length, :exc:`OSError` will be raised. :func:`inet_ntoa` does not
    support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual
    stack support.
+
+   .. versionchanged: 3.5
+      Writable :term:`bytes-like object` is now accepted.
 
 
 .. function:: inet_pton(address_family, ip_string)
 
    Convert an IP address from its family-specific string format to a packed,
    binary format. :func:`inet_pton` is useful when a library or network protocol
    calls for an object of type :c:type:`struct in_addr` (similar to
    :func:`inet_aton`) or :c:type:`struct in6_addr`.
 
    Supported values for *address_family* are currently :const:`AF_INET` and
    :const:`AF_INET6`. If the IP address string *ip_string* is invalid,
    :exc:`OSError` will be raised. Note that exactly what is valid depends on
    both the value of *address_family* and the underlying implementation of
    :c:func:`inet_pton`.
 
    Availability: Unix (maybe not all platforms), Windows.
 
    .. versionchanged:: 3.4
       Windows support added
 
 
 .. function:: inet_ntop(address_family, packed_ip)
 
-   Convert a packed IP address (a bytes object of some number of characters) to its
-   standard, family-specific string representation (for example, ``'7.10.0.5'`` or
-   ``'5aef:2b::8'``). :func:`inet_ntop` is useful when a library or network protocol
-   returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`)
-   or :c:type:`struct in6_addr`.
+   Convert a packed IP address (a :term:`bytes-like object` of some number of
+   characters) to its standard, family-specific string representation (for

[Martin Panter, 2015/03/20 02:41:08]

Probably should be “some number of bytes”, since they are not ASCII characters

[storchaka, 2015/03/20 07:47:34]

Done.

+   example, ``'7.10.0.5'`` or ``'5aef:2b::8'``).
+   :func:`inet_ntop` is useful when a library or network protocol returns an
+   object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`) or
+   :c:type:`struct in6_addr`.
 
    Supported values for *address_family* are currently :const:`AF_INET` and
-   :const:`AF_INET6`. If the string *packed_ip* is not the correct length for the
-   specified address family, :exc:`ValueError` will be raised.  A
-   :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`.
+   :const:`AF_INET6`. If the bytes object *packed_ip* is not the correct
+   length for the specified address family, :exc:`ValueError` will be raised.
+   A :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`.
 
    Availability: Unix (maybe not all platforms), Windows.
 
    .. versionchanged:: 3.4
       Windows support added
 
+   .. versionchanged: 3.5
+      Writable :term:`bytes-like object` is now accepted.
+
 
 ..
    XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any
    non-Unix platforms?  The old (obsolete?) 4.2BSD form of the
    interface, in which struct msghdr has no msg_control or
    msg_controllen members, is not currently supported.
 
 .. function:: CMSG_LEN(length)
 
    Return the total length, without trailing padding, of an ancillary
@@ skipping 528 matching lines @@
 
    For further information, please consult the :ref:`notes on socket timeouts <socket-timeouts>`.
 
 
 .. method:: socket.setsockopt(level, optname, value)
 
    .. index:: module: struct
 
    Set the value of the given socket option (see the Unix manual page
    :manpage:`setsockopt(2)`).  The needed symbolic constants are defined in the
-   :mod:`socket` module (:const:`SO_\*` etc.).  The value can be an integer or a
-   bytes object representing a buffer.  In the latter case it is up to the caller to
+   :mod:`socket` module (:const:`SO_\*` etc.).  The value can be an integer or
+   a :term:`bytes-like object` representing a buffer.  In the latter case it is
+   up to the caller to
    ensure that the bytestring contains the proper bits (see the optional built-in
    module :mod:`struct` for a way to encode C structures as bytestrings).
+
+   .. versionchanged: 3.5
+      Writable :term:`bytes-like object` is now accepted.
 
 
 .. method:: socket.shutdown(how)
 
    Shut down one or both halves of the connection.  If *how* is :const:`SHUT_RD`,
    further receives are disallowed.  If *how* is :const:`SHUT_WR`, further sends
    are disallowed.  If *how* is :const:`SHUT_RDWR`, further sends and receives are
    disallowed.
 
 
@@ skipping 310 matching lines @@
 
    - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J.  Leffler et
      al,
 
    both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
    PS1:7 and PS1:8).  The platform-specific reference material for the various
    socket-related system calls are also a valuable source of information on the
    details of socket semantics.  For Unix, refer to the manual pages; for Windows,
    see the WinSock (or Winsock 2) specification.  For IPv6-ready APIs, readers may
    want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.