oaknut-codecs 12.7.2__py3-none-any.whl

oaknut/codecs/__init__.py

@@ -0,0 +1,32 @@
+"""Text codecs for Acorn computer character sets.
+
+This is the bottom layer of the oaknut workspace alongside
+``oaknut-exception``: a dependency-free home for the character-set codecs
+shared by the file, filesystem and language packages. Splitting the
+codecs out lets siblings such as ``oaknut-basic`` use the ``"acorn"``
+encoding without taking a dependency on ``oaknut-file``.
+
+Importing this package registers the ``"acorn"`` codec as a side effect,
+so ``"text".encode("acorn")`` works anywhere once any oaknut package has
+been imported.
+"""
+
+from __future__ import annotations
+
+from oaknut.codecs.acorn import (
+    BBC_MICRO_TO_UNICODE,
+    UNICODE_TO_BBC_MICRO,
+    AcornCodec,
+    acorn_to_unicode,
+    unicode_to_acorn,
+)
+
+__version__ = "12.7.2"
+
+__all__ = [
+    "BBC_MICRO_TO_UNICODE",
+    "UNICODE_TO_BBC_MICRO",
+    "AcornCodec",
+    "acorn_to_unicode",
+    "unicode_to_acorn",
+]

oaknut/codecs/acorn.py

@@ -0,0 +1,161 @@
+"""Character encoding for the Acorn/BBC Micro character set.
+
+The BBC Micro and Acorn Electron used a variant of ASCII with a couple
+of UK-specific characters. This module implements a Python codec for
+that encoding and registers it under the name ``"acorn"``::
+
+    text = "COST£100"
+    data = text.encode("acorn")   # b"COST\\x60100"
+    back = data.decode("acorn")   # "COST£100"
+
+Importing this module (or its package, :mod:`oaknut.codecs`) registers
+the codec as a side effect, after which ``"acorn"`` resolves alongside
+the stdlib encodings everywhere in the process.
+
+References:
+- https://beebwiki.mdfs.net/ASCII
+- https://www.acornelectron.co.uk/ugs/electron/acorn_computers/ug-english/appendix_f_eng.html
+- https://tobylobster.github.io/mos/mos/S-s4.html
+"""
+
+from __future__ import annotations
+
+import codecs
+
+# BBC Micro (MODEs 0-6) character mappings: Acorn byte values that differ
+# from ASCII, mapped to the Unicode characters they stand for.
+BBC_MICRO_TO_UNICODE = {
+    0x60: "£",  # Backtick replaced with pound sign
+    0x7C: "¦",  # Vertical bar replaced with broken bar
+}
+
+# Reverse mapping for encoding Unicode to BBC Micro bytes.
+UNICODE_TO_BBC_MICRO = {v: k for k, v in BBC_MICRO_TO_UNICODE.items()}
+
+
+class AcornCodec(codecs.Codec):
+    """Codec for the Acorn/BBC Micro character encoding."""
+
+    def encode(self, input: str, errors: str = "strict") -> tuple[bytes, int]:
+        """Encode a Unicode string to Acorn bytes.
+
+        Args:
+            input: Unicode string to encode.
+            errors: Error handling ('strict', 'ignore', 'replace').
+
+        Returns:
+            Tuple of (encoded bytes, length of input consumed).
+        """
+        output = bytearray()
+        for i, char in enumerate(input):
+            if char in UNICODE_TO_BBC_MICRO:
+                output.append(UNICODE_TO_BBC_MICRO[char])
+            else:
+                code_point = ord(char)
+                if code_point > 255:
+                    if errors == "strict":
+                        raise UnicodeEncodeError(
+                            "acorn",
+                            input,
+                            i,
+                            i + 1,
+                            f"Character '{char}' (U+{code_point:04X}) cannot be "
+                            f"encoded in Acorn character set",
+                        )
+                    elif errors == "ignore":
+                        continue
+                    elif errors == "replace":
+                        output.append(ord("?"))
+                    else:
+                        raise ValueError(f"Unknown error handling: {errors}")
+                else:
+                    output.append(code_point)
+
+        return bytes(output), len(input)
+
+    def decode(self, input: bytes, errors: str = "strict") -> tuple[str, int]:
+        """Decode Acorn bytes to a Unicode string.
+
+        Args:
+            input: Bytes in Acorn encoding.
+            errors: Error handling ('strict', 'ignore', 'replace').
+
+        Returns:
+            Tuple of (decoded string, length of input consumed).
+        """
+        output = []
+        for byte in input:
+            if byte in BBC_MICRO_TO_UNICODE:
+                output.append(BBC_MICRO_TO_UNICODE[byte])
+            else:
+                # Standard ASCII or high-bit characters.
+                output.append(chr(byte))
+
+        return "".join(output), len(input)
+
+
+# The Acorn codec is byte-for-byte stateless, so a single shared instance
+# backs every registry entry point — the incremental encoder and decoder,
+# the stream reader/writer, and the non-incremental encode/decode callables.
+_SHARED_ACORN_CODEC = AcornCodec()
+
+
+class AcornIncrementalEncoder(codecs.IncrementalEncoder):
+    """Incremental encoder for Acorn encoding."""
+
+    def encode(self, input: str, final: bool = False) -> bytes:
+        return _SHARED_ACORN_CODEC.encode(input, self.errors)[0]
+
+
+class AcornIncrementalDecoder(codecs.IncrementalDecoder):
+    """Incremental decoder for Acorn encoding."""
+
+    def decode(self, input: bytes, final: bool = False) -> str:
+        return _SHARED_ACORN_CODEC.decode(input, self.errors)[0]
+
+
+class AcornStreamWriter(AcornCodec, codecs.StreamWriter):
+    """Stream writer for Acorn encoding."""
+
+
+class AcornStreamReader(AcornCodec, codecs.StreamReader):
+    """Stream reader for Acorn encoding."""
+
+
+def getregentry(name: str | None = None) -> codecs.CodecInfo:
+    """Return the codec registry entry for the Acorn encoding."""
+    return codecs.CodecInfo(
+        name="acorn",
+        encode=_SHARED_ACORN_CODEC.encode,
+        decode=_SHARED_ACORN_CODEC.decode,
+        incrementalencoder=AcornIncrementalEncoder,
+        incrementaldecoder=AcornIncrementalDecoder,
+        streamreader=AcornStreamReader,
+        streamwriter=AcornStreamWriter,
+    )
+
+
+def search_function(encoding: str) -> codecs.CodecInfo | None:
+    """Codec registry search function recognising the ``"acorn"`` name."""
+    if encoding.lower() == "acorn":
+        return getregentry(encoding)
+    return None
+
+
+# Register the codec as an import side effect.
+codecs.register(search_function)
+
+
+def acorn_to_unicode(data: bytes) -> str:
+    """Decode Acorn-encoded bytes to a Unicode string."""
+    return data.decode("acorn")
+
+
+def unicode_to_acorn(text: str) -> bytes:
+    """Encode a Unicode string to Acorn-encoded bytes.
+
+    Raises:
+        UnicodeEncodeError: If *text* contains characters that cannot be
+            encoded in the Acorn character set.
+    """
+    return text.encode("acorn")

oaknut_codecs-12.7.2.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: oaknut-codecs
+Version: 12.7.2
+Summary: Text codecs for Acorn computer character sets (BBC Micro / Electron)
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-codecs
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# oaknut-codecs
+
+Text codecs for Acorn computer character sets, part of the
+[oaknut](https://github.com/rob-smallshire/oaknut) family of packages for
+working with Acorn computer filesystems, files, and formats.
+
+This package provides a Python codec for the **Acorn/BBC Micro character
+set** — a variant of ASCII in which `&60` is the pound sign `£` and `&7C`
+is the broken bar `¦`. Importing the package registers the codec under
+the name `"acorn"`, so it works with the standard `str.encode` /
+`bytes.decode` machinery:
+
+```python
+import oaknut.codecs  # registers the "acorn" codec
+
+"COST£100".encode("acorn")   # b'COST\x60100'
+b"COST\x60100".decode("acorn")  # 'COST£100'
+```
+
+It is the dependency-free bottom layer of the workspace, alongside
+`oaknut-exception`, so that language and file packages can share one
+codec implementation without taking a dependency on each other.
+
+## Installation
+
+```sh
+uv add oaknut-codecs
+```
+
+## Licence
+
+MIT

oaknut_codecs-12.7.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+oaknut/codecs/__init__.py,sha256=db6OPz9MkxKhHGIhLMcxTfrlsiKGRf9WYK9xFvCYNvs,891
+oaknut/codecs/acorn.py,sha256=_Zi0fdGZWun7oSU2et-iX89EIfEP2XcRMxoHq908q4E,5521
+oaknut_codecs-12.7.2.dist-info/licenses/LICENSE,sha256=L_Uw2MQC3xsCy2nOzWmY_DYRQMHC-Yu2_zTvUTadNAY,1074
+oaknut_codecs-12.7.2.dist-info/METADATA,sha256=rOPon958hHnD0EIVpSggi8euMzFxLd_TZRpZKNEgXXc,1756
+oaknut_codecs-12.7.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+oaknut_codecs-12.7.2.dist-info/top_level.txt,sha256=QLKweXQ1HlrA4vuJ4fj2AKq-_qs54zd2M4O0DahuKzw,7
+oaknut_codecs-12.7.2.dist-info/RECORD,,

oaknut_codecs-12.7.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

oaknut_codecs-12.7.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Smallshire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oaknut_codecs-12.7.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+oaknut