usocket.rst 8.41 KB
Newer Older
1
*******************************
2
:mod:`usocket` -- socket module
3
*******************************
4
5
6
7

.. module:: usocket
   :synopsis: socket module

8
This module provides access to the BSD socket interface.
9

10
11
12
See corresponding `CPython module <https://docs.python.org/3/library/socket.html>`_ for
comparison.

13
14
15
16
17
18
.. admonition:: Difference to CPython
   :class: attention

   CPython used to have a ``socket.error`` exception which is now deprecated,
   and is an alias of OSError. In MicroPython, use OSError directly.

19
20
21
22
23
24
25
26
27
Socket address format(s)
------------------------

Functions below which expect a network address, accept it in the format of
`(ipv4_address, port)`, where `ipv4_address` is a string with dot-notation numeric
IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range
1-65535. Note the domain names are not accepted as `ipv4_address`, they should be
resolved first using ``socket.getaddrinfo()``.

28
29
30
Functions
---------

31
.. function:: socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_TCP)
32

33
   Create a new socket using the given address family, socket type and protocol number.
34

35
    .. only:: port_wipy
36

37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
        .. note::

           SSL sockets need to be created the following way before wrapping them with 
           ``ssl.wrap_socket``::

              import socket
              import ssl
              s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC)
              ss = ssl.wrap_socket(s)

.. function:: socket.getaddrinfo(host, port)

   Translate the host/port argument into a sequence of 5-tuples that contain all the 
   necessary arguments for creating a socket connected to that service. The list of 
   5-tuples has following structure::

      (family, type, proto, canonname, sockaddr)

   The following example shows how to connect to a given url::

      s = socket.socket()
58
      s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1])
59

60
61
62
63
64
65
66
67
68
69
70
71
   .. admonition:: Difference to CPython
      :class: attention

      CPython raises a ``socket.gaierror`` exception (OSError subclass) in case
      of error in this function. MicroPython doesn't have ``socket.gaierror``
      and raises OSError directly. Note that error numbers of ``getaddrinfo()``
      form a separate namespace and may not match error numbers from
      ``uerrno`` module. To distinguish ``getaddrinfo()`` errors, they are
      represented by negative numbers, whereas standard system errors are
      positive numbers (error numbers are accessible using ``e.args[0]`` property
      from an exception object). The use of negative values is a provisional
      detail which may change in the future.
72
73
74
75
76

Constants
---------

.. data:: socket.AF_INET
77
          socket.AF_INET6
78

79
   Address family types. Availability depends on a particular board.
80
81

.. data:: socket.SOCK_STREAM
82
          socket.SOCK_DGRAM
83

84
   Socket types.
85
86

.. data:: socket.IPPROTO_UDP
87
          socket.IPPROTO_TCP
88

89
   IP protocol numbers.
90

91
92
93
94
95
96
97
98
99
100
101
102
103
.. data:: socket.SOL_*

   Socket option levels (an argument to ``setsockopt()``). The exact inventory depends on a board.

.. data:: socket.SO_*

   Socket options (an argument to ``setsockopt()``). The exact inventory depends on a board.

Constants specific to WiPy:

.. data:: socket.IPPROTO_SEC

    Special protocol value to create SSL-compatible socket.
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

class socket
============

Methods
-------

    .. method:: socket.close

       Mark the socket closed. Once that happens, all future operations on the socket 
       object will fail. The remote end will receive no more data (after queued data is flushed).

       Sockets are automatically closed when they are garbage-collected, but it is recommended 
       to close() them explicitly, or to use a with statement around them.

    .. method:: socket.bind(address)

121
       Bind the socket to address. The socket must not already be bound.
122
123
124
125
126

    .. method:: socket.listen([backlog])

       Enable a server to accept connections. If backlog is specified, it must be at least 0 
       (if it's lower, it will be set to 0); and specifies the number of unaccepted connections
127
       that the system will allow before refusing new connections. If not specified, a default
128
129
130
131
132
133
134
135
136
137
138
       reasonable value is chosen.

    .. method:: socket.accept()

       Accept a connection. The socket must be bound to an address and listening for connections.
       The return value is a pair (conn, address) where conn is a new socket object usable to send
       and receive data on the connection, and address is the address bound to the socket on the
       other end of the connection.

    .. method:: socket.connect(address)

139
       Connect to a remote socket at address.
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

    .. method:: socket.send(bytes)

       Send data to the socket. The socket must be connected to a remote socket.

    .. method:: socket.sendall(bytes)

       Send data to the socket. The socket must be connected to a remote socket.

    .. method:: socket.recv(bufsize)

       Receive data from the socket. The return value is a bytes object representing the data
       received. The maximum amount of data to be received at once is specified by bufsize.

    .. method:: socket.sendto(bytes, address)

       Send data to the socket. The socket should not be connected to a remote socket, since the
157
       destination socket is specified by `address`.
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174

    .. method:: socket.recvfrom(bufsize)

      Receive data from the socket. The return value is a pair (bytes, address) where bytes is a
      bytes object representing the data received and address is the address of the socket sending
      the data.

    .. method:: socket.setsockopt(level, optname, value)

       Set the value of the given socket option. The needed symbolic constants are defined in the
       socket module (SO_* etc.). The value can be an integer or a bytes-like object representing
       a buffer.

    .. method:: socket.settimeout(value)

       Set a timeout on blocking socket operations. The value argument can be a nonnegative floating
       point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations
175
       will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has
176
177
178
       completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
       is put in blocking mode.

179
180
181
182
183
184
185
186
       .. admonition:: Difference to CPython
          :class: attention

          CPython raises a ``socket.timeout`` exception in case of timeout,
          which is an ``OSError`` subclass. MicroPython raises an OSError directly
          instead. If you use ``except OSError:`` to catch the exception,
          your code will work both in MicroPython and CPython.

187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
    .. method:: socket.setblocking(flag)

       Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking,
       else to blocking mode.

       This method is a shorthand for certain ``settimeout()`` calls::

          sock.setblocking(True) is equivalent to sock.settimeout(None)
          sock.setblocking(False) is equivalent to sock.settimeout(0.0)

    .. method:: socket.makefile(mode='rb')

       Return a file object associated with the socket. The exact returned type depends on the arguments
       given to makefile(). The support is limited to binary modes only ('rb' and 'wb').
       CPython's arguments: ``encoding``, ``errors`` and ``newline`` are not supported.

       The socket must be in blocking mode; it can have a timeout, but the file object’s internal buffer
       may end up in a inconsistent state if a timeout occurs.

206
207
       .. admonition:: Difference to CPython
          :class: attention
208

209
          Closing the file object returned by makefile() WILL close the
210
211
          original socket as well.

212
    .. method:: socket.read([size])
213
214

       Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it
215
       reads all data available from the socket until ``EOF``; as such the method will not return until
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
       the socket is closed.

    .. method:: socket.readinto(buf[, nbytes])

       Read bytes into the ``buf``.  If ``nbytes`` is specified then read at most
       that many bytes.  Otherwise, read at most ``len(buf)`` bytes.

       Return value: number of bytes read and stored into ``buf``.

    .. method:: socket.readline()

       Read a line, ending in a newline character.

       Return value: the line read.

    .. method:: socket.write(buf)

       Write the buffer of bytes to the socket.

       Return value: number of bytes written.