From 59540dccf125452a8cf4e55f260788a46f7838dc Mon Sep 17 00:00:00 2001
From: Paul Sokolovsky <pfalcon@users.sourceforge.net>
Date: Sat, 28 Jan 2017 13:55:51 +0300
Subject: [PATCH] docs/usocket: Clarify exceptions used.
---
docs/library/usocket.rst | 25 ++++++++++++++++++-------
1 file changed, 18 insertions(+), 7 deletions(-)
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index c46e8f4c5..64afa6f59 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -10,6 +10,12 @@ This module provides access to the BSD socket interface.
See corresponding `CPython module <https://docs.python.org/3/library/socket.html>`_ for
comparison.
+.. 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.
+
Socket address format(s)
------------------------
@@ -51,13 +57,18 @@ Functions
s = socket.socket()
s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1])
-.. only:: port_wipy
-
- Exceptions
- ----------
-
- .. data:: socket.error
- .. data:: socket.timeout
+ .. 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.
Constants
---------
--
GitLab