docs: Document str & bytes encoding limitations.

Partially this is documenting some additional limitations
added recently now that the encoding argument is not totally
ignored.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>

Author: projectgus

docs/reference/unicode_support.rst

@@ -49,8 +49,10 @@ The :meth:`bytes.decode` and :meth:`str.encode` methods support the following en
 - UTF-8 (``'utf-8'`` or ``'utf8'``)
 - ASCII (``'ascii'``)
 
-Other encodings (such as ``'latin-1'``, ``'utf-16'``, etc.) are not supported and
-will raise ``LookupError``.
+Other encodings (such as ``'latin-1'``, ``'utf-16'``, etc.) are not supported
+and will raise ``LookupError``. The encoding argument must also match one of the
+supported strings exactly (for example, ``'utf8'`` is valid but ``'UTF8'``
+is not). `More details <cpydiff_types_bytes_decode_encoding>`.
 
 Example::
 
@@ -91,6 +93,21 @@ The same ``errors`` handling applies when decoding any bytes-like object, includ
 via the ``str()`` constructor (for example ``str(buf, 'utf-8', 'replace')`` where
 ``buf`` is a ``bytes``, ``bytearray``, ``memoryview`` or ``array`` object).
 
+Encoding to Bytes
+~~~~~~~~~~~~~~~~~
+
+Function ``str.encode()`` and the ``bytes()`` constructor accept an ``encoding``
+argument which can be ``'utf8'``, ``'utf-8'`` or ``'ascii'``::
+
+  >>> "abc".encode("ascii")
+  b'abc'
+
+If encoding ``'ascii'`` is specified then an exception is raised if the string
+contains non-ASCII characters.
+
+The ``'ignore'`` and ``'replace'`` ``errors`` values are not supported in these
+conversions from string to bytes and `any errors argument is ignored
+<cpydiff_types_str_encode_errors>`.
 
 String Methods
 --------------

tests/cpydiff/types_bytes_decode_encoding.py

@@ -1,11 +1,15 @@
 """
 categories: Types,bytes
-description: bytes.decode() only supports 'utf-8' and 'ascii' encodings, not other encodings like 'latin-1'
-cause: MicroPython is optimized for embedded systems and only includes UTF-8 and ASCII codec support to save memory. Other encodings would require additional codec tables.
-workaround: Convert data to UTF-8 before processing, or implement custom encoding/decoding if needed.
+description: bytes.decode() only supports encoding arguments 'utf8', 'utf-8' and 'ascii'. Other encodings like 'latin-1' are not supported. Other string forms such as 'UTF8' are not supported.
+cause: MicroPython is optimised for embedded systems and only includes UTF-8 and ASCII codec support with simple matching to save memory and code size. `The same restriction applies to str constructor <cpydiff_types_str_encoding>`. See also `unicode_support`.
+workaround: Convert data to UTF-8 before processing, or implement custom encoding/decoding if needed. Ensure encoding argument is one of the accepted forms.
 """
 
-# CPython supports many encodings, MicroPython only utf-8 and ascii
+# Both CPython and MicroPython support utf8 and ascii encodings
+print(b"caf\xc3\xa9".decode("utf8"))  # codespell:ignore caf
+print(b"cafe".decode("ascii"))
+
+# MicroPython does not support additional encodings
 try:
     b"\xe9".decode("latin-1")  # 'é' in latin-1
     print("latin-1 supported")
@@ -17,3 +21,10 @@
     print("cp1252 supported")
 except (ValueError, NotImplementedError, LookupError) as e:
     print("cp1252 not supported:", type(e).__name__)
+
+# Encoding arguments must match exactly in MicroPython
+try:
+    b"hello".decode("ASCII")
+    print("Capital letters ASCII supported")
+except (ValueError, NotImplementedError, LookupError) as e:
+    print("Capital letters ASCII not supported:", type(e).__name__)

tests/cpydiff/types_bytes_encoding.py

@@ -0,0 +1,21 @@
+"""
+categories: Types,bytes
+description: bytes() constructor only supports encoding arguments 'utf8', 'utf-8' and 'ascii'. Other encodings like 'latin-1' are not supported. Other string forms such as 'UTF8' are not supported.
+cause: MicroPython is optimised for embedded systems and has limited codec support to save code size. `A similar restriction applies to str.encode() <cpydiff_types_str_encode_encoding>`. See also `unicode_support`.
+workaround: Implement other encoding conversions manually by parsing the result of str.encode() or bytes() constructor.
+"""
+
+# Both CPython and MicroPython can encode this emoji as UTF-8 bytes
+print(bytes("😀", "utf8"))
+
+# Both CPython and MicroPython will fail to encode this emoji as ASCII bytes
+try:
+    print(bytes("😀", "ascii"))
+except UnicodeError:
+    print("UnicodeError")
+
+# Other encodings or string formats aren't accepted by MicroPython
+try:
+    print(bytes("😀", "UTF-8"))
+except LookupError:
+    print("LookupError")

tests/cpydiff/types_str_encode_encoding.py

@@ -0,0 +1,21 @@
+"""
+categories: Types,str
+description: str.encode() constructor only supports encoding arguments 'utf8', 'utf-8' and 'ascii'. Other encodings like 'latin-1' are not supported. Other string forms such as 'UTF8' are not supported.
+cause: MicroPython is optimised for embedded systems and has limited codec support to save code size. `A similar restriction applies to bytes constructor <cpydiff_types_bytes_encoding>`. See also `unicode_support`.
+workaround: Implement encoding conversions manually by parsing the result of str.encode() or bytes() constructor.
+"""
+
+# Both CPython and MicroPython can encode this emoji as UTF-8 bytes
+print("😀".encode("utf8"))
+
+# Both CPython and MicroPython will fail to encode this emoji as ASCII bytes
+try:
+    print("😀".encode("ascii"))
+except UnicodeError:
+    print("UnicodeError")
+
+# Other encodings or string formats aren't accepted by MicroPython:
+try:
+    print("😀".encode("UTF-8"))
+except LookupError:
+    print("LookupError")

tests/cpydiff/types_str_encode_errors.py

@@ -0,0 +1,19 @@
+"""
+categories: Types,str
+description: str.encode() and bytes() constructor ignore any ``errors`` argument specified. If the encoding is specified as ``'ascii'`` and a non-ASCII byte is found in the string then an exception is always raised.
+cause: MicroPython is optimised for embedded systems and has limited codec support to save code size. See also `unicode_support`.
+workaround: Handle encoding errors manually by parsing the result of str.encode() or bytes() constructor.
+"""
+
+# CPython will replace the emoji with an ASCII '?' but MicroPython will
+# raise an exception
+try:
+    print("😀".encode("ascii", "replace"))
+except UnicodeError:
+    print("UnicodeError")
+
+# CPython will ignore the emoji in the result but MicroPython will raise an exception
+try:
+    print("😀".encode("ascii", "ignore"))
+except UnicodeError:
+    print("UnicodeError")

tests/cpydiff/types_str_encoding.py

@@ -0,0 +1,30 @@
+"""
+categories: Types,str
+description: str() constructor only supports encoding arguments 'utf8', 'utf-8' and 'ascii'. Other encodings like 'latin-1' are not supported. Other string forms such as 'UTF8' are not supported.
+cause: MicroPython is optimised for embedded systems and only includes UTF-8 and ASCII codec support with simple matching to save memory and code size. `The same restriction applies to bytes.decode() <cpydiff_types_bytes_decode_encoding>`. See also `unicode_support`.
+workaround: Convert data to UTF-8 before processing, or implement custom encoding/decoding if needed. Ensure encoding argument is one of the accepted forms.
+"""
+
+# Both CPython and MicroPython support utf8 and ascii encodings
+print(str(b"caf\xc3\xa9", "utf8"))  # codespell:ignore caf
+print(str(b"cafe", "ascii"))
+
+# MicroPython does not support additional encodings
+try:
+    str(b"\xe9", "latin-1")  # 'é' in latin-1
+    print("latin-1 supported")
+except (ValueError, NotImplementedError, LookupError) as e:
+    print("latin-1 not supported:", type(e).__name__)
+
+try:
+    str(b"\x80", "cp1252")  # Euro sign in cp1252
+    print("cp1252 supported")
+except (ValueError, NotImplementedError, LookupError) as e:
+    print("cp1252 not supported:", type(e).__name__)
+
+# Encoding arguments must match exactly in MicroPython
+try:
+    str(b"hello", "ASCII")
+    print("Capital letters ASCII supported")
+except (ValueError, NotImplementedError, LookupError) as e:
+    print("Capital letters ASCII not supported:", type(e).__name__)