Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(157673)

Side by Side Diff: Doc/library/socket.rst

Issue 23001: Accept mutable bytes-like objects
Patch Set: Created 4 years, 8 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
OLDNEW
1 :mod:`socket` --- Low-level networking interface 1 :mod:`socket` --- Low-level networking interface
2 ================================================ 2 ================================================
3 3
4 .. module:: socket 4 .. module:: socket
5 :synopsis: Low-level networking interface. 5 :synopsis: Low-level networking interface.
6 6
7 7
8 This module provides access to the BSD *socket* interface. It is available on 8 This module provides access to the BSD *socket* interface. It is available on
9 all modern Unix systems, Windows, MacOS, and probably additional platforms. 9 all modern Unix systems, Windows, MacOS, and probably additional platforms.
10 10
(...skipping 28 matching lines...) Expand all
39 Depending on the system and the build options, various socket families 39 Depending on the system and the build options, various socket families
40 are supported by this module. 40 are supported by this module.
41 41
42 The address format required by a particular socket object is automatically 42 The address format required by a particular socket object is automatically
43 selected based on the address family specified when the socket object was 43 selected based on the address family specified when the socket object was
44 created. Socket addresses are represented as follows: 44 created. Socket addresses are represented as follows:
45 45
46 - The address of an :const:`AF_UNIX` socket bound to a file system node 46 - The address of an :const:`AF_UNIX` socket bound to a file system node
47 is represented as a string, using the file system encoding and the 47 is represented as a string, using the file system encoding and the
48 ``'surrogateescape'`` error handler (see :pep:`383`). An address in 48 ``'surrogateescape'`` error handler (see :pep:`383`). An address in
49 Linux's abstract namespace is returned as a :class:`bytes` object with 49 Linux's abstract namespace is returned as a :term:`bytes-like object` with
50 an initial null byte; note that sockets in this namespace can 50 an initial null byte; note that sockets in this namespace can
51 communicate with normal file system sockets, so programs intended to 51 communicate with normal file system sockets, so programs intended to
52 run on Linux may need to deal with both types of address. A string or 52 run on Linux may need to deal with both types of address. A string or
53 :class:`bytes` object can be used for either type of address when 53 bytes-like object can be used for either type of address when
54 passing it as an argument. 54 passing it as an argument.
55 55
56 .. versionchanged:: 3.3 56 .. versionchanged:: 3.3
57 Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8 57 Previously, :const:`AF_UNIX` socket paths were assumed to use UTF-8
58 encoding. 58 encoding.
59 59
60 .. versionchanged: 3.5
61 Writable :term:`bytes-like object` is now accepted.
62
60 - A pair ``(host, port)`` is used for the :const:`AF_INET` address family, 63 - A pair ``(host, port)`` is used for the :const:`AF_INET` address family,
61 where *host* is a string representing either a hostname in Internet domain 64 where *host* is a string representing either a hostname in Internet domain
62 notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``, 65 notation like ``'daring.cwi.nl'`` or an IPv4 address like ``'100.50.200.5'``,
63 and *port* is an integer. 66 and *port* is an integer.
64 67
65 - For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo, 68 - For :const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
66 scopeid)`` is used, where *flowinfo* and *scopeid* represent the ``sin6_flowin fo`` 69 scopeid)`` is used, where *flowinfo* and *scopeid* represent the ``sin6_flowin fo``
67 and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For 70 and ``sin6_scope_id`` members in :const:`struct sockaddr_in6` in C. For
68 :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for 71 :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for
69 backward compatibility. Note, however, omission of *scopeid* can cause proble ms 72 backward compatibility. Note, however, omission of *scopeid* can cause proble ms
(...skipping 532 matching lines...) Expand 10 before | Expand all | Expand 10 after
602 If the IPv4 address string passed to this function is invalid, 605 If the IPv4 address string passed to this function is invalid,
603 :exc:`OSError` will be raised. Note that exactly what is valid depends on 606 :exc:`OSError` will be raised. Note that exactly what is valid depends on
604 the underlying C implementation of :c:func:`inet_aton`. 607 the underlying C implementation of :c:func:`inet_aton`.
605 608
606 :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used 609 :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used
607 instead for IPv4/v6 dual stack support. 610 instead for IPv4/v6 dual stack support.
608 611
609 612
610 .. function:: inet_ntoa(packed_ip) 613 .. function:: inet_ntoa(packed_ip)
611 614
612 Convert a 32-bit packed IPv4 address (a bytes object four characters in 615 Convert a 32-bit packed IPv4 address (a :term:`bytes-like object` four
613 length) to its standard dotted-quad string representation (for example, 616 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.
614 '123.45.67.89'). This is useful when conversing with a program that uses the 617 '123.45.67.89'). This is useful when conversing with a program that uses the
615 standard C library and needs objects of type :c:type:`struct in_addr`, which 618 standard C library and needs objects of type :c:type:`struct in_addr`, which
616 is the C type for the 32-bit packed binary data this function takes as an 619 is the C type for the 32-bit packed binary data this function takes as an
617 argument. 620 argument.
618 621
619 If the byte sequence passed to this function is not exactly 4 bytes in 622 If the byte sequence passed to this function is not exactly 4 bytes in
620 length, :exc:`OSError` will be raised. :func:`inet_ntoa` does not 623 length, :exc:`OSError` will be raised. :func:`inet_ntoa` does not
621 support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual 624 support IPv6, and :func:`inet_ntop` should be used instead for IPv4/v6 dual
622 stack support. 625 stack support.
626
627 .. versionchanged: 3.5
628 Writable :term:`bytes-like object` is now accepted.
623 629
624 630
625 .. function:: inet_pton(address_family, ip_string) 631 .. function:: inet_pton(address_family, ip_string)
626 632
627 Convert an IP address from its family-specific string format to a packed, 633 Convert an IP address from its family-specific string format to a packed,
628 binary format. :func:`inet_pton` is useful when a library or network protocol 634 binary format. :func:`inet_pton` is useful when a library or network protocol
629 calls for an object of type :c:type:`struct in_addr` (similar to 635 calls for an object of type :c:type:`struct in_addr` (similar to
630 :func:`inet_aton`) or :c:type:`struct in6_addr`. 636 :func:`inet_aton`) or :c:type:`struct in6_addr`.
631 637
632 Supported values for *address_family* are currently :const:`AF_INET` and 638 Supported values for *address_family* are currently :const:`AF_INET` and
633 :const:`AF_INET6`. If the IP address string *ip_string* is invalid, 639 :const:`AF_INET6`. If the IP address string *ip_string* is invalid,
634 :exc:`OSError` will be raised. Note that exactly what is valid depends on 640 :exc:`OSError` will be raised. Note that exactly what is valid depends on
635 both the value of *address_family* and the underlying implementation of 641 both the value of *address_family* and the underlying implementation of
636 :c:func:`inet_pton`. 642 :c:func:`inet_pton`.
637 643
638 Availability: Unix (maybe not all platforms), Windows. 644 Availability: Unix (maybe not all platforms), Windows.
639 645
640 .. versionchanged:: 3.4 646 .. versionchanged:: 3.4
641 Windows support added 647 Windows support added
642 648
643 649
644 .. function:: inet_ntop(address_family, packed_ip) 650 .. function:: inet_ntop(address_family, packed_ip)
645 651
646 Convert a packed IP address (a bytes object of some number of characters) to its 652 Convert a packed IP address (a :term:`bytes-like object` of some number of
647 standard, family-specific string representation (for example, ``'7.10.0.5'`` or 653 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 t
storchaka 2015/03/20 07:47:34 Done.
648 ``'5aef:2b::8'``). :func:`inet_ntop` is useful when a library or network prot ocol 654 example, ``'7.10.0.5'`` or ``'5aef:2b::8'``).
649 returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_nt oa`) 655 :func:`inet_ntop` is useful when a library or network protocol returns an
650 or :c:type:`struct in6_addr`. 656 object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`) or
657 :c:type:`struct in6_addr`.
651 658
652 Supported values for *address_family* are currently :const:`AF_INET` and 659 Supported values for *address_family* are currently :const:`AF_INET` and
653 :const:`AF_INET6`. If the string *packed_ip* is not the correct length for th e 660 :const:`AF_INET6`. If the bytes object *packed_ip* is not the correct
654 specified address family, :exc:`ValueError` will be raised. A 661 length for the specified address family, :exc:`ValueError` will be raised.
655 :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`. 662 A :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`.
656 663
657 Availability: Unix (maybe not all platforms), Windows. 664 Availability: Unix (maybe not all platforms), Windows.
658 665
659 .. versionchanged:: 3.4 666 .. versionchanged:: 3.4
660 Windows support added 667 Windows support added
661 668
669 .. versionchanged: 3.5
670 Writable :term:`bytes-like object` is now accepted.
671
662 672
663 .. 673 ..
664 XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any 674 XXX: Are sendmsg(), recvmsg() and CMSG_*() available on any
665 non-Unix platforms? The old (obsolete?) 4.2BSD form of the 675 non-Unix platforms? The old (obsolete?) 4.2BSD form of the
666 interface, in which struct msghdr has no msg_control or 676 interface, in which struct msghdr has no msg_control or
667 msg_controllen members, is not currently supported. 677 msg_controllen members, is not currently supported.
668 678
669 .. function:: CMSG_LEN(length) 679 .. function:: CMSG_LEN(length)
670 680
671 Return the total length, without trailing padding, of an ancillary 681 Return the total length, without trailing padding, of an ancillary
(...skipping 528 matching lines...) Expand 10 before | Expand all | Expand 10 after
1200 1210
1201 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`. 1211 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`.
1202 1212
1203 1213
1204 .. method:: socket.setsockopt(level, optname, value) 1214 .. method:: socket.setsockopt(level, optname, value)
1205 1215
1206 .. index:: module: struct 1216 .. index:: module: struct
1207 1217
1208 Set the value of the given socket option (see the Unix manual page 1218 Set the value of the given socket option (see the Unix manual page
1209 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the 1219 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
1210 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a 1220 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or
1211 bytes object representing a buffer. In the latter case it is up to the calle r to 1221 a :term:`bytes-like object` representing a buffer. In the latter case it is
1222 up to the caller to
1212 ensure that the bytestring contains the proper bits (see the optional built-i n 1223 ensure that the bytestring contains the proper bits (see the optional built-i n
1213 module :mod:`struct` for a way to encode C structures as bytestrings). 1224 module :mod:`struct` for a way to encode C structures as bytestrings).
1225
1226 .. versionchanged: 3.5
1227 Writable :term:`bytes-like object` is now accepted.
1214 1228
1215 1229
1216 .. method:: socket.shutdown(how) 1230 .. method:: socket.shutdown(how)
1217 1231
1218 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` , 1232 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` ,
1219 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends 1233 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends
1220 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re 1234 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re
1221 disallowed. 1235 disallowed.
1222 1236
1223 1237
(...skipping 310 matching lines...) Expand 10 before | Expand all | Expand 10 after
1534 1548
1535 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et 1549 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et
1536 al, 1550 al,
1537 1551
1538 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections 1552 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
1539 PS1:7 and PS1:8). The platform-specific reference material for the various 1553 PS1:7 and PS1:8). The platform-specific reference material for the various
1540 socket-related system calls are also a valuable source of information on the 1554 socket-related system calls are also a valuable source of information on the
1541 details of socket semantics. For Unix, refer to the manual pages; for Window s, 1555 details of socket semantics. For Unix, refer to the manual pages; for Window s,
1542 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers m ay 1556 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers m ay
1543 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv 6. 1557 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv 6.
OLDNEW
« no previous file with comments | « Doc/library/ossaudiodev.rst ('k') | Doc/library/ssl.rst » ('j') | Modules/fcntlmodule.c » ('J')

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+