oaknut-codecs 12.7.2__tar.gz

oaknut_codecs-12.7.2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,32 @@
+# 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/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-codecs"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "Text codecs for Acorn computer character sets (BBC Micro / Electron)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# The codecs are implemented entirely against the standard library's
+# `codecs` machinery, so this package has no runtime dependencies. It is
+# the shared bottom layer that lets siblings use the "acorn" encoding
+# without depending on oaknut-file.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-codecs"
+Repository = "https://github.com/rob-smallshire/oaknut"
+Issues = "https://github.com/rob-smallshire/oaknut/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0",
+]
+dev = [
+    "bump-my-version>=0.28.0",
+    "pre-commit>=3.0",
+    {include-group = "test"},
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.codecs.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_codecs-12.7.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oaknut_codecs-12.7.2/src/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-12.7.2/src/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/src/oaknut_codecs.egg-info/PKG-INFO

@@ -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/src/oaknut_codecs.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/oaknut/codecs/__init__.py
+src/oaknut/codecs/acorn.py
+src/oaknut_codecs.egg-info/PKG-INFO
+src/oaknut_codecs.egg-info/SOURCES.txt
+src/oaknut_codecs.egg-info/dependency_links.txt
+src/oaknut_codecs.egg-info/top_level.txt
+tests/test_acorn.py

oaknut_codecs-12.7.2/src/oaknut_codecs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oaknut_codecs-12.7.2/src/oaknut_codecs.egg-info/top_level.txt

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

oaknut_codecs-12.7.2/tests/test_acorn.py

@@ -0,0 +1,139 @@
+"""Tests for the Acorn/BBC Micro character codec."""
+
+import oaknut.codecs  # noqa: F401 - registers the "acorn" codec
+import pytest
+from oaknut.codecs import acorn_to_unicode, unicode_to_acorn
+
+
+class TestAcornToUnicode:
+    """Tests for decoding Acorn bytes to Unicode."""
+
+    def test_standard_ascii(self):
+        assert acorn_to_unicode(b"HELLO") == "HELLO"
+
+    def test_pound_sign_bbc_micro(self):
+        assert acorn_to_unicode(b"COST\x60100") == "COST£100"
+
+    def test_broken_bar_bbc_micro(self):
+        assert acorn_to_unicode(b"A\x7cB") == "A¦B"
+
+    def test_mixed_characters(self):
+        assert acorn_to_unicode(b"PRICE:\x60500") == "PRICE:£500"
+
+    def test_empty_bytes(self):
+        assert acorn_to_unicode(b"") == ""
+
+    def test_high_bit_characters(self):
+        assert len(acorn_to_unicode(bytes([0x80, 0xFF]))) == 2
+
+
+class TestUnicodeToAcorn:
+    """Tests for encoding Unicode to Acorn bytes."""
+
+    def test_standard_ascii(self):
+        assert unicode_to_acorn("HELLO") == b"HELLO"
+
+    def test_pound_sign_bbc_micro(self):
+        assert unicode_to_acorn("COST£100") == b"COST\x60100"
+
+    def test_broken_bar_bbc_micro(self):
+        assert unicode_to_acorn("A¦B") == b"A\x7cB"
+
+    def test_empty_string(self):
+        assert unicode_to_acorn("") == b""
+
+    def test_round_trip_bbc_micro(self):
+        original = "FILE£NAME"
+        assert acorn_to_unicode(unicode_to_acorn(original)) == original
+
+    def test_invalid_character_raises(self):
+        with pytest.raises(ValueError, match="cannot be encoded"):
+            unicode_to_acorn("HELLO\U0001f4be")  # floppy disk emoji
+
+    def test_high_unicode_raises(self):
+        with pytest.raises(ValueError, match="cannot be encoded"):
+            unicode_to_acorn("TEST™")  # U+2122
+
+
+class TestCodecInterface:
+    """Tests for the Python codec interface."""
+
+    def test_encode_with_codec(self):
+        assert "HELLO".encode("acorn") == b"HELLO"
+
+    def test_decode_with_codec(self):
+        assert b"HELLO".decode("acorn") == "HELLO"
+
+    def test_encode_pound_sign(self):
+        assert "£100".encode("acorn") == b"\x60100"
+
+    def test_decode_pound_sign(self):
+        assert b"\x60100".decode("acorn") == "£100"
+
+    def test_codec_round_trip(self):
+        original = "TEST£FILE"
+        assert original.encode("acorn").decode("acorn") == original
+
+    def test_codec_name_is_case_insensitive(self):
+        assert "£".encode("acorn") == b"\x60"
+        assert "£".encode("ACORN") == b"\x60"
+
+    def test_encode_errors_strict(self):
+        with pytest.raises(UnicodeEncodeError):
+            "TEST™".encode("acorn", errors="strict")
+
+    def test_encode_errors_ignore(self):
+        assert "TEST™OK".encode("acorn", errors="ignore") == b"TESTOK"
+
+    def test_encode_errors_replace(self):
+        assert "TEST™".encode("acorn", errors="replace") == b"TEST?"
+
+    def test_codec_with_file_like(self):
+        import io
+
+        buffer = io.BytesIO()
+        writer = io.TextIOWrapper(buffer, encoding="acorn")
+        writer.write("£100")
+        writer.flush()
+
+        buffer.seek(0)
+        reader = io.TextIOWrapper(buffer, encoding="acorn")
+        assert reader.read() == "£100"
+
+
+class TestCodecRegistry:
+    """Exercise the bits of codec registry integration beyond str.encode."""
+
+    def test_codecs_lookup_returns_info(self):
+        import codecs
+
+        assert codecs.lookup("acorn").name == "acorn"
+
+    def test_incremental_encoder_streams_chunks(self):
+        import codecs
+
+        encoder = codecs.getincrementalencoder("acorn")()
+        out = encoder.encode("COST") + encoder.encode("£") + encoder.encode("100", final=True)
+        assert out == b"COST\x60100"
+
+    def test_incremental_decoder_streams_chunks(self):
+        import codecs
+
+        decoder = codecs.getincrementaldecoder("acorn")()
+        out = decoder.decode(b"COST") + decoder.decode(b"\x60") + decoder.decode(b"100", final=True)
+        assert out == "COST£100"
+
+    def test_incremental_encoder_respects_errors(self):
+        import codecs
+
+        encoder = codecs.getincrementalencoder("acorn")(errors="replace")
+        assert encoder.encode("AĀB") == b"A?B"
+
+    def test_iterencode_and_iterdecode(self):
+        import codecs
+
+        out = b"".join(codecs.iterencode(iter(["COST", "£", "100"]), "acorn"))
+        assert out == b"COST\x60100"
+
+        text = "".join(codecs.iterdecode(iter([b"COST", b"\x60", b"100"]), "acorn"))
+        assert text == "COST£100"