From 3c4bfd1dec28ffbefc6379dedeaa24feaa2ef373 Mon Sep 17 00:00:00 2001
From: Damien George
Date: Tue, 20 Apr 2021 17:11:13 +1000
Subject: py/objexcept: Support errno attribute on OSError exceptions.

This commit adds the errno attribute to exceptions, so code can retrieve
errno codes from an OSError using exc.errno.

The implementation here simply lets `errno` (and the existing `value`)
attributes work on any exception instance (they both alias args[0]).  This
is for efficiency and to keep code size down.  The pros and cons of this
are:

Pros:
- more compatible with CPython, less difference to document and learn
- OSError().errno will correctly return None, whereas the current way of
  doing it via OSError().args[0] will raise an IndexError
- it reduces code size on most bare-metal ports (because they already have
  the errno qstr)
- for Python code that uses exc.errno the generated bytecode is 2 bytes
  smaller and more efficient to execute (compared with exc.args[0]); so
  bytecode loaded to RAM saves 2 bytes RAM for each use of this attribute,
  and bytecode that is frozen saves 2 bytes flash/ROM for each use
- it's easier/shorter to type, and saves 2 bytes of space in .py files that
  use it (for each use)

Cons:
- increases code size by 4-8 bytes on minimal ports that don't already have
  the `errno` qstr
- all exceptions now have .errno and .value attributes (a cpydiff test is
  added to address this)

See also #2407.

Signed-off-by: Damien George <damien@micropython.org>
---
 docs/library/builtins.rst | 4 ----
 docs/library/uerrno.rst   | 4 ++--
 2 files changed, 2 insertions(+), 6 deletions(-)

(limited to 'docs/library')

diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst
index 365248dc7..3029cd9e3 100644
--- a/docs/library/builtins.rst
+++ b/docs/library/builtins.rst
@@ -176,10 +176,6 @@ Exceptions
 
 .. exception:: OSError
 
-    |see_cpython| `python:OSError`. MicroPython doesn't implement ``errno``
-    attribute, instead use the standard way to access exception arguments:
-    ``exc.args[0]``.
-
 .. exception:: RuntimeError
 
 .. exception:: StopIteration
diff --git a/docs/library/uerrno.rst b/docs/library/uerrno.rst
index def01362f..1d60c80e1 100644
--- a/docs/library/uerrno.rst
+++ b/docs/library/uerrno.rst
@@ -16,13 +16,13 @@ Constants
 
     Error codes, based on ANSI C/POSIX standard. All error codes start with
     "E". As mentioned above, inventory of the codes depends on
-    :term:`MicroPython port`. Errors are usually accessible as ``exc.args[0]``
+    :term:`MicroPython port`. Errors are usually accessible as ``exc.errno``
     where ``exc`` is an instance of `OSError`. Usage example::
 
         try:
             uos.mkdir("my_dir")
         except OSError as exc:
-            if exc.args[0] == uerrno.EEXIST:
+            if exc.errno == uerrno.EEXIST:
                 print("Directory already exists")
 
 .. data:: errorcode
-- 
cgit v1.2.3