Merge tag 'v1.9.2' into parse-bytecode

Double precision math library and support on pyboard, and improved ussl

This release brings general improvements and bug fixes to the core and
various ports, as well as documentation additions, clean-ups and better
consistency.  And effort has been made to clean up the source code to
make it more consistent across the core and all ports.

There is a new tool "mpy_bin2res.py" to convert arbitrary (binary) files
to Python resources for inclusion in source code (frozen or otherwise).

The ussl module has seen improvements, including implementation of
server_hostname (for axtls) and server_side mode (for mbedtls).

There is now a double-precision float math library and stmhal has support
to build firmware with software or hardware double-precision.

A detailed list of changes follows.

py core:
- formatfloat: fix number of digits and exponent sign when rounding
- modthread: raise RuntimeError in release() if lock is not acquired
- compile: raise SyntaxError if positional args are given after */**
- objint: support "big" byte-order in int.to_bytes()
- objint: in to_bytes(), allow length arg to be any int and check sign
- compile: fix bug with break/continue in else of optimised for-range
- compile: optimise emitter label indices to save a word of heap
- builtinimport: remove unreachable code for relative imports
- objnamedtuple: simplify and remove use of alloca building namedtuple
- mpprint: remove unreachable check for neg return of mp_format_float
- binary: add missing "break" statements
- runtime: mark m_malloc_fail() as NORETURN
- objstr: remove unnecessary "sign" variable in formatting code
- vm: make "if" control flow more obvious in YIELD_FROM opcode
- modmath: check for zero division in log with 2 args
- makeversionhdr.py: update to parse new release line in docs/conf.py
- objdict: factorise dict accessor helper to reduce code size
- change mp_uint_t to size_t in builtins code
- repl: change mp_uint_t to size_t in repl helpers
- compile: combine arith and bit-shift ops into 1 compile routine
- compile: use switch-case to match token and operator
- objgenerator: allow to hash generators and generator instances
- gc: refactor assertions in gc_free function
- vm: make n_state variable local to just set-up part of VM
- asmx64: support moving a 64-bit immediate to one of top 8 registers
- modmicropython: cast stack_limit value so it prints correctly
- builtinevex: add typechecking of globals/locals args to eval/exec
- py.mk: make berkeley-db C-defs apply only to relevant source files
- mperrno: allow mperrno.h to be correctly included before other hdrs
- mpz: make mpz_is_zero() an inline function
- implement raising a big-int to a negative power
- mkrules.mk: show frozen modules sizes together with executable size
- objtuple: allow to use inplace-multiplication operator on tuples
- objstr: raise an exception for wrong type on RHS of str binary op
- modsys: initial implementation of sys.getsizeof()
- binary.c: fix bug when packing big-endian 'Q' values
- add verbose debug compile-time flag MICROPY_DEBUG_VERBOSE
- binary: change internal bytearray typecode from 0 to 1
- objstringio: prevent offset wraparound for io.BytesIO objects
- objstringio: fix regression with handling SEEK_SET
- stream: seek: Consistently handle negative offset for SEEK_SET
- mkrules.mk: use "find -path" when searching for frozen obj files
- compile: remove unused pn_colon code when compiling func params
- objcomplex: remove unnecessary assignment of variable
- formatfloat: don't post-increment variable that won't be used again
- use "static inline" for funcs that should be inline
- asmthumb: use existing macro to properly clear the D-cache

extmod:
- modussl_axtls: update for axTLS 2.1.3
- modussl_axtls: implement server_hostname arg to wrap_socket()
- move modonewire.c from esp8266 to extmod directory
- modure: if input string is bytes, return bytes results too
- modubinascii: add check for empty buffer passed to hexlify
- modussl_axtls: allow to close ssl stream multiple times
- modussl_mbedtls: support server_side mode
- modussl_mbedtls: when reading and peer wants to close, return 0
- modframebuf: fix invalid stride for odd widths in GS4_HMSB fmt
- modussl_mbedtls: make socket.close() free all TLS resources
- modframebuf: consistently use "col" as name for colour variables
- modussl_mbedtls: implement non-blocking SSL sockets
- machine_signal: fix parsing of invert arg when Pin is first arg
- modframebuf: use correct initialization for .locals_dict
- modlwip: implement setsockopt(IP_ADD_MEMBERSHIP)
- modussl_mbedtls.c: add ussl.getpeercert() method
- modubinascii: rewrite mod_binascii_a2b_base64
- modubinascii: don't post-increment variable that won't be used
- modonewire: rename public module to mp_module_onewire
- for uos.stat interpret st_size member as an unsigned int
- use "static inline" for funcs that should be inline

lib:
- axtls: upgrade to axTLS 2.1.3 + MicroPython patchset
- libm/math: remove implementations of float conversion functions
- add libm_dbl, a double-precision math library, from musl-1.1.16

drivers:
- onewire: move onewire.py, ds18x20.py from esp8266 to drivers
- onewire: enable pull-up when init'ing the 1-wire pin

tools:
- gen-cpydiff: use case description as 3rd-level heading
- pyboard: add license header
- mpy_bin2res: tools to convert binary resources to Python module
- mpy-tool.py: don't generate const_table if it's empty
- mpy-tool.py: fix missing argument in dump() function

tests:
- net_inet/test_tls_sites.py: integration test for SSL connections
- net_inet: add tests for accept and connect in nonblocking mode
- basics: add tests for for-else statement
- net_inet: move tests which don't require full Internet to net_hosted
- connect_nonblock: refactor towards real net_hosted test
- auto detect floating point capabilites of the target
- import: add a test for the builtin __import__ function
- import: update comment now that uPy raises correct exception
- basics/namedtuple1: add test for creating with pos and kw args
- unix/extra_coverage: add test for mp_vprintf with bad fmt spec
- basics: add tests for arithmetic operators precedence
- cpydiff/modules_deque: elaborate workaround
- cpydiff/core_class_mro: move under Classes, add workaround
- cpydiff/core_arguments: move under Functions subsection
- cpydiff/core_class_supermultiple: same cause as core_class_mro
- cpydiff: improve wording, add more workarounds
- cpydiff: add case for str.ljust/rjust
- rename exec1.py to builtin_exec.py
- basics/builtin_exec: test various globals/locals args to exec()

minimal port:
- Makefile: enable gc-sections to remove unused code
- remove unused stmhal include from Makefile
- use size_t for mp_builtin_open argument

unix port:
- modtime: replace strftime() with localtime()
- mpconfigport.mk: update descriptions of readline and TLS options
- Makefile: disable assertions in the standard unix executable
- modjni: convert to mp_rom_map_elem_t
- for uos.stat interpret st_size member as an unsigned int

stmhal port:
- mpconfigport.h: remove config of PY_THREAD_GIL to use default
- make error messages more consistent across peripherals
- add initial implementation of Pin.irq() method
- add .value() method to Switch object, to mirror Pin and Signal
- move pybstdio.c to lib/utils/sys_stdio_mphal.c for common use
- add "quiet timing" enter/exit functions
- make available the _onewire module, for low-level bus control
- modules: provide sym-link to onewire.py driver
- boards/stm32f405.ld: increase FLASH_TEXT to end of 1MiB flash
- sdcard: allow a board to customise the SDIO pins
- add possibility to build with double-precision floating point
- boards: enable double-prec FP on F76x boards
- Makefile: use hardware double-prec FP for MCUs that support it
- Makefile: rename FLOAT_IMPL to MICROPY_FLOAT_IMPL to match C name
- Makefile: add CFLAGS_EXTRA to CFLAGS so cmdline can add options
- mpconfigport.h: allow MICROPY_PY_THREAD to be overridden
- boards: add configuration files for NUCLEO_F429ZI
- boards/NUCLEO_F429ZI: change USB config from HS to FS peripheral
- reduce size of ESPRUINO_PICO build so it fits in flash
- servo: make pyb.Servo(n) map to Pin('Xn') on all MCUs
- servo: don't compile servo code when it's not enabled
- use "static inline" for funcs that should be inline

cc3200 port:
- modusocket: simplify socket.makefile() function
- make non-zero socket timeout work with connect/accept/send
- modusocket: fix connect() when in non-blocking or timeout mode
- use the name MicroPython consistently in code

esp8266 port:
- Makefile: bump axTLS TLS record buffer size to 5K
- Makefile: allow FROZEN_DIR,FROZEN_MPY_DIR to be overridden
- Makefile: add LIB_SRC_C variable to qstr auto-extraction list
- make onewire module and support code usable by other ports
- modonewire: move low-level 1-wire bus code to modonewire.c
- modonewire: make timings static and remove onewire.timings func
- reinstate 1-wire scripts by sym-linking to drivers/onewire/
- move mp_hal_pin_open_drain from esp_mphal.c to machine_pin.c
- enable MICROPY_ENABLE_FINALISER
- README: make "Documentation" a top-level section
- machine_rtc: use correct arithmetic for aligning RTC mem len
- mpconfigport_512k: use terse error messages to get 512k to fit
- mpconfigport.h: make socket a weak link
- modesp: remove unused constants: STA_MODE, etc
- general: add known issue of WiFi RX buffers overflow
- use size_t for mp_builtin_open argument
- fix UART stop bit constants

zephyr port:
- Makefile: rework dependencies and "clean" target
- Makefile: revert prj.conf construction rule to the previous state
- remove long-obsolete machine_ptr_t typedef's
- Makefile: explicitly define default target as "all"
- modusocket: allow to use socketized net_context in upstream
- modusocket: socket, close: switch to native Zephyr socket calls
- modusocket: bind, connect, listen, accept: Swtich to native sockets
- modusocket: send: switch to native sockets
- modusocket: recv: switch to native sockets
- modusocket: fully switch to native Zephyr sockets
- modzephyr: add current_tid() and stacks_analyze() functions
- prj_base.conf: enable CONFIG_INIT_STACKS
- modusocket: update struct sockaddr family field name
- prj_96b_carbon.conf: re-enable networking on Carbon
- modzephyr: add shell_net_iface() function

docs:
- btree: add hints about opening db file and need to flush db
- select: rename to uselect, to match the actual module name
- license: update copyright year
- esp8266/tutorial/intro: discourage use of 512kb firmwares
- esp8266/tutorial/intro: Sphinx requires blank lines around literal blocks
- conf.py: include 3 levels of ToC in latexpdf output
- gc: mark mem_alloc()/mem_free() as uPy-specific
- gc: document gc.threshold() function
- builtins: list builtin exceptions
- conf.py: set default_role = 'any'
- lcd160cr: group related constants together and use full sentences
- ref/speed_python: update and make more hardware-neutral
- library/gc: fix grammar and improve readability of gc.threshold()
- move all ports docs to the single ToC
- topindex.html: remove link to wipy.io, it's no longer available
- conf.py: add .venv dir to exclude_patterns
- move topindex.html to templates/ subdir
- differences/index_template: use consistent heading casing
- builtins: add AssertionError, SyntaxError, ZeroDivisionError
- add glossary
- conf.py: switch to "new" format of intersphinx_mapping
- conf.py: add file for global replacements definition
- library: add CPython docs xref to each pertinent module
- replace.inc: add |see_cpython|, to xref individual symbols from CPython
- conf.py: set "version" and "release" to the same value
- *_index: drop "Indices and tables" pseudo-section
- pyboard: move hardware info into General Info chapter
- uerrno: document "uerrno" module
- esp8266/general.rst: fix name of NTP module
- pyboard: move info about using Windows from topindex to general
- uzlib: update description of decompress() and mention DecompIO
- pyboard/tutorial/amp_skin: add example for playing large WAV files
- library/ubinascii: update base64 docs
- library/usocket: move socket.error to its own section
- library/usocket: describe complete information on address formats
- glossary: elaborate on possible MicroPython port differences
- glossary: fix typos in micropython-lib paragraph
- index: rewrite introduction paragraph to avoid confusion
- use the name MicroPython consistently in documentation
- consistently link to micropython-lib in glossary

all:
- make more use of mp_raise_{msg,TypeError,ValueError} helpers
- unify header guard usage
- remove trailing spaces, per coding conventions
- don't include system errno.h when it's not needed
- use the name MicroPython consistently in comments
- make use of $(TOP) variable in Makefiles, instead of ".."
- raise exceptions via mp_raise_XXX
- make static dicts use mp_rom_map_elem_t type and MP_ROM_xxx macros

README:
- mention support for bytecode and frozen bytecode
- improve description of precompiled bytecode; mention mpy-cross

CODECONVENTIONS:
- clarify MicroPython changes sign-off process
- start to describe docs conventions
- describe docs use of markup for None/True/False

travis:
- build STM32F769DISC board instead of F7DISC to test dbl-prec FP
- pin cpp-coveralls at 0.3.12

1 files changed, 98 insertions, 56 deletions

diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index 71deaebc41..65e24e2662 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -5,43 +5,72 @@
 .. module:: usocket
    :synopsis: socket module
 
-This module provides access to the BSD socket interface.
-
-See the corresponding `CPython module <https://docs.python.org/3/library/socket.html>`_
-for comparison.
-
-.. admonition:: Difference to CPython
-   :class: attention
+|see_cpython_module| :mod:`python:socket`.
 
-   CPython used to have a ``socket.error`` exception which is now deprecated,
-   and is an alias of OSError. In MicroPython, use OSError directly.
+This module provides access to the BSD socket interface.
 
 .. admonition:: Difference to CPython
    :class: attention
 
    For efficiency and consistency, socket objects in MicroPython implement a stream
    (file-like) interface directly. In CPython, you need to convert a socket to
-   a file-like object using ``makefile()`` method. This method is still supported
+   a file-like object using `makefile()` method. This method is still supported
    by MicroPython (but is a no-op), so where compatibility with CPython matters,
    be sure to use it.
 
 Socket address format(s)
 ------------------------
 
-The 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()``.
+The native socket address format of the ``usocket`` module is an opaque data type
+returned by `getaddrinfo` function, which must be used to resolve textual address
+(including numeric addresses)::
+
+    sockaddr = usocket.getaddrinfo('www.micropython.org', 80)[0][-1]
+    # You must use getaddrinfo() even for numeric addresses
+    sockaddr = usocket.getaddrinfo('127.0.0.1', 80)[0][-1]
+    # Now you can use that address
+    sock.connect(addr)
+
+Using `getaddrinfo` is the most efficient (both in terms of memory and processing
+power) and portable way to work with addresses.
+
+However, ``socket`` module (note the difference with native MicroPython
+``usocket`` module described here) provides CPython-compatible way to specify
+addresses using tuples, as described below. Note that depending on a
+`MicroPython port`, ``socket`` module can be builtin or need to be
+installed from `micropython-lib` (as in the case of `MicroPython Unix port`),
+and some ports still accept only numeric addresses in the tuple format,
+and require to use `getaddrinfo` function to resolve domain names.
+
+Summing up:
+
+* Always use `getaddrinfo` when writing portable applications.
+* Tuple addresses described below can be used as a shortcut for
+  quick hacks and interactive use, if your port supports them.
+
+Tuple address format for ``socket`` module:
+
+* IPv4: *(ipv4_address, port)*, where *ipv4_address* is a string with
+  dot-notation numeric IPv4 address, e.g. ``"8.8.8.8"``, and *port* is and
+  integer port number in the range 1-65535. Note the domain names are not
+  accepted as *ipv4_address*, they should be resolved first using
+  `usocket.getaddrinfo()`.
+* IPv6: *(ipv6_address, port, flowinfo, scopeid)*, where *ipv6_address*
+  is a string with colon-notation numeric IPv6 address, e.g. ``"2001:db8::1"``,
+  and *port* is an integer port number in the range 1-65535. *flowinfo*
+  must be 0. *scopeid* is the interface scope identifier for link-local
+  addresses. Note the domain names are not accepted as *ipv6_address*,
+  they should be resolved first using `usocket.getaddrinfo()`. Availability
+  of IPv6 support depends on a `MicroPython port`.
 
 Functions
 ---------
 
-.. function:: socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_TCP)
+.. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP)
 
    Create a new socket using the given address family, socket type and protocol number.
 
-.. function:: socket.getaddrinfo(host, port)
+.. function:: 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 
@@ -57,11 +86,11 @@ Functions
    .. admonition:: Difference to CPython
       :class: attention
 
-      CPython raises a ``socket.gaierror`` exception (OSError subclass) in case
+      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()``
+      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
+      `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
@@ -70,32 +99,34 @@ Functions
 Constants
 ---------
 
-.. data:: socket.AF_INET
-          socket.AF_INET6
+.. data:: AF_INET
+          AF_INET6
 
    Address family types. Availability depends on a particular board.
 
-.. data:: socket.SOCK_STREAM
-          socket.SOCK_DGRAM
+.. data:: SOCK_STREAM
+          SOCK_DGRAM
 
    Socket types.
 
-.. data:: socket.IPPROTO_UDP
-          socket.IPPROTO_TCP
+.. data:: IPPROTO_UDP
+          IPPROTO_TCP
 
    IP protocol numbers.
 
-.. data:: socket.SOL_*
+.. data:: usocket.SOL_*
 
-   Socket option levels (an argument to ``setsockopt()``). The exact inventory depends on a board.
+   Socket option levels (an argument to `setsockopt()`). The exact
+   inventory depends on a MicroPython port.
 
-.. data:: socket.SO_*
+.. data:: usocket.SO_*
 
-   Socket options (an argument to ``setsockopt()``). The exact inventory depends on a board.
+   Socket options (an argument to `setsockopt()`). The exact
+   inventory depends on a MicroPython port.
 
 Constants specific to WiPy:
 
-.. data:: socket.IPPROTO_SEC
+.. data:: IPPROTO_SEC
 
     Special protocol value to create SSL-compatible socket.
 
@@ -105,21 +136,22 @@ class socket
 Methods
 -------
 
-.. method:: socket.close
+.. 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).
+   Mark the socket closed and release all resources. Once that happens, all future operations
+   on the socket object will fail. The remote end will receive EOF indication if
+   supported by protocol.
 
    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.
+   to `close()` them explicitly as soon you finished working with them.
 
 .. method:: socket.bind(address)
 
-   Bind the socket to address. The socket must not already be bound.
+   Bind the socket to *address*. The socket must not already be bound.
 
 .. method:: socket.listen([backlog])
 
-   Enable a server to accept connections. If backlog is specified, it must be at least 0 
+   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
    that the system will allow before refusing new connections. If not specified, a default
    reasonable value is chosen.
@@ -133,7 +165,7 @@ Methods
 
 .. method:: socket.connect(address)
 
-   Connect to a remote socket at address.
+   Connect to a remote socket at *address*.
 
 .. method:: socket.send(bytes)
 
@@ -144,11 +176,11 @@ Methods
 .. method:: socket.sendall(bytes)
 
    Send all data to the socket. The socket must be connected to a remote socket.
-   Unlike ``send()``, this method will try to send all of data, by sending data
+   Unlike `send()`, this method will try to send all of data, by sending data
    chunk by chunk consecutively.
 
    The behavior of this method on non-blocking sockets is undefined. Due to this,
-   on MicroPython, it's recommended to use ``write()`` method instead, which
+   on MicroPython, it's recommended to use `write()` method instead, which
    has the same "no short writes" policy for blocking sockets, and will return
    number of bytes sent on non-blocking sockets.
 
@@ -160,25 +192,25 @@ Methods
 .. method:: socket.sendto(bytes, address)
 
    Send data to the socket. The socket should not be connected to a remote socket, since the
-   destination socket is specified by `address`.
+   destination socket is specified by *address*.
 
 .. 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
+  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
+   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
-   will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has
+   will raise an `OSError` exception if the timeout period value has elapsed before the operation has
    completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket
    is put in blocking mode.
 
@@ -186,7 +218,7 @@ Methods
       :class: attention
 
       CPython raises a ``socket.timeout`` exception in case of timeout,
-      which is an ``OSError`` subclass. MicroPython raises an OSError directly
+      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.
 
@@ -195,7 +227,7 @@ Methods
    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:
+   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)``
@@ -204,12 +236,12 @@ Methods
 
    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', 'wb', and 'rwb').
-   CPython's arguments: ``encoding``, ``errors`` and ``newline`` are not supported.
+   CPython's arguments: *encoding*, *errors* and *newline* are not supported.
 
    .. admonition:: Difference to CPython
       :class: attention
 
-      As MicroPython doesn't support buffered streams, values of ``buffering``
+      As MicroPython doesn't support buffered streams, values of *buffering*
       parameter is ignored and treated as if it was 0 (unbuffered).
 
    .. admonition:: Difference to CPython
@@ -220,19 +252,19 @@ Methods
 
 .. method:: socket.read([size])
 
-   Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it
-   reads all data available from the socket until ``EOF``; as such the method will not return until
+   Read up to size bytes from the socket. Return a bytes object. If *size* is not given, it
+   reads all data available from the socket until EOF; as such the method will not return until
    the socket is closed. This function tries to read as much data as
    requested (no "short reads"). This may be not possible with
    non-blocking socket though, and then less data will be returned.
 
 .. 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. Just as
-   ``read()``, this method follows "no short reads" policy.
+   Read bytes into the *buf*.  If *nbytes* is specified then read at most
+   that many bytes.  Otherwise, read at most *len(buf)* bytes. Just as
+   `read()`, this method follows "no short reads" policy.
 
-   Return value: number of bytes read and stored into ``buf``.
+   Return value: number of bytes read and stored into *buf*.
 
 .. method:: socket.readline()
 
@@ -245,6 +277,16 @@ Methods
    Write the buffer of bytes to the socket. This function will try to
    write all data to a socket (no "short writes"). This may be not possible
    with a non-blocking socket though, and returned value will be less than
-   the length of ``buf``.
+   the length of *buf*.
 
    Return value: number of bytes written.
+
+.. exception:: socket.error
+
+   MicroPython does NOT have this exception.
+
+   .. 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.