radixly 0.1.0.dev0__tar.gz → 1.0.0__tar.gz

radixly-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present rayakame
+
+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.

radixly-1.0.0/MANIFEST.in

@@ -0,0 +1,15 @@
+# Ship the complete test suite in the sdist: the reference oracle and the
+# conformance vectors are what let a from-source builder (distro packager,
+# --no-binary install) actually validate the compiled extension. Without
+# graft, setuptools ships the top-level test files but not reference/ or
+# vectors/, leaving an uncollectable suite.
+graft tests
+# Headers are not auto-collected the way ext-modules .c sources are; without
+# this line an sdist cannot compile.
+recursive-include src/radixly *.h
+# Stubs are source too; py.typed is the PEP 561 marker (both also ship in
+# wheels via package-data — decided M9).
+recursive-include src/radixly *.pyi
+include src/radixly/py.typed
+prune changes
+global-exclude __pycache__ *.py[cod]

radixly-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: radixly
+Version: 1.0.0
+Summary: Fast binary-to-text codecs for Python: base32768, uro14, braille and hexagram in C
+Author-email: rayakame <github.android206@passmail.net>
+License-Expression: MIT
+Project-URL: Homepage, https://radixly.rayakame.dev
+Project-URL: Documentation, https://radixly.rayakame.dev/en/latest/
+Project-URL: Source, https://github.com/rayakame/radixly
+Project-URL: Issues, https://github.com/rayakame/radixly/issues
+Keywords: base32768,binary-to-text,codec,encoding,unicode,c-extension
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://radixly.rayakame.dev/en/latest/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rayakame/radixly/main/docs/_static/logo-wordmark-dark.svg">
+      <img src="https://raw.githubusercontent.com/rayakame/radixly/main/docs/_static/logo-wordmark-light.svg" alt="radixly" width="420">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/radixly/"><img src="https://img.shields.io/pypi/v/radixly" alt="PyPI"></a>
+  <a href="https://radixly.rayakame.dev/en/latest/"><img src="https://readthedocs.org/projects/radixly/badge/?version=latest" alt="Documentation"></a>
+  <a href="https://github.com/rayakame/radixly/actions/workflows/ci.yml"><img src="https://github.com/rayakame/radixly/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/rayakame/radixly/actions/workflows/wheels.yml"><img src="https://github.com/rayakame/radixly/actions/workflows/wheels.yml/badge.svg" alt="Wheels"></a>
+  <a href="https://pypi.org/project/radixly/"><img src="https://img.shields.io/pypi/pyversions/radixly" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
+</p>
+
+Fast binary-to-text codecs for Python. Every codec is a hand-written C
+extension behind one small interface: `encode`, `decode` and the size math to
+plan around a length limit. Decoding is strict, the package has no
+dependencies and ships type stubs.
+
+Documentation: <https://radixly.rayakame.dev/en/latest/>
+
+## Install
+
+```bash
+pip install radixly
+```
+
+Releases ship wheels for CPython 3.11 to 3.14 on Linux, macOS and Windows.
+There is no pure-Python fallback; anywhere else pip builds from source and
+needs a C compiler.
+
+## Usage
+
+```python
+import radixly
+
+text = radixly.base32768.encode(b"hello")   # str, 3 characters
+radixly.base32768.decode(text)              # b'hello'
+
+radixly.base32768.max_bytes(100)            # 187: largest payload that fits 100 characters
+
+try:
+    radixly.base32768.decode("hello")
+except radixly.DecodeError as error:        # a ValueError with the position
+    error.position                          # 0
+```
+
+Every codec module has the same four functions; `radixly.get_codec(name)` and
+`radixly.CODECS` pick one at runtime.
+
+## Codecs
+
+| codec | bits per char | 100 chars hold | alphabet | catches truncation |
+|---|---|---|---|---|
+| [base32768](https://radixly.rayakame.dev/en/latest/codecs/base32768.html) | 15 | 187 bytes | qntm's 32,768 BMP code points | no |
+| [uro14](https://radixly.rayakame.dev/en/latest/codecs/uro14.html) | 14 | 173 bytes | one CJK block, plus a length prefix | below 16,384 bytes |
+| [braille](https://radixly.rayakame.dev/en/latest/codecs/braille.html) | 8 | 100 bytes | 256 Braille patterns | no |
+| [hexagram](https://radixly.rayakame.dev/en/latest/codecs/hexagram.html) | 6 | 75 bytes | 64 Yijing hexagrams | partly |
+
+[Choosing a codec](https://radixly.rayakame.dev/en/latest/guides/choosing-a-codec.html) walks through the
+trade-offs.
+
+## Performance
+
+Generated from the committed record run by the benchmark suite in
+[`benchmarks/`](benchmarks/); no number here is typed by hand. Sizes below
+64 KiB show per-call latency, larger ones sustained throughput; "vs reference"
+is the speedup over the pure-Python oracle in `tests/reference/`.
+
+<!-- radixly-bench:begin -->
+*Measured on Intel(R) Core(TM) i9-14900KF (performance governor), CachyOS, kernel 7.2.3-1-cachyos, CPython 3.13.14, gcc 16.2.1 20260810, radixly 0.1.0.dev0 @ cefe701, 2026-09-08T18:59:26+00:00.*
+
+| codec | direction | 1 B | 200 B | 64 KiB | 1 MiB | vs reference |
+|---|---|---|---|---|---|---|
+| base32768 | encode | 0.019 μs | 0.114 μs | 1,963 MB/s | 1,963 MB/s | 117x at 200 B |
+| base32768 | decode | 0.014 μs | 0.173 μs | 1,275 MB/s | 1,269 MB/s | 127x at 200 B |
+| braille | encode | 0.019 μs | 0.168 μs | 1,397 MB/s | 1,404 MB/s | 95x at 200 B |
+| braille | decode | 0.016 μs | 0.269 μs | 800 MB/s | 799 MB/s | 77x at 200 B |
+| hexagram | encode | 0.019 μs | 0.201 μs | 1,137 MB/s | 1,126 MB/s | 108x at 200 B |
+| hexagram | decode | 0.016 μs | 0.328 μs | 616 MB/s | 641 MB/s | 84x at 200 B |
+| uro14 | encode | 0.018 μs | 0.118 μs | 2,020 MB/s | 2,007 MB/s | 122x at 200 B |
+| uro14 | decode | 0.015 μs | 0.242 μs | 899 MB/s | 896 MB/s | 91x at 200 B |
+<!-- radixly-bench:end -->
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rayakame/radixly/main/benchmarks/charts/throughput.dark.svg">
+  <img src="https://raw.githubusercontent.com/rayakame/radixly/main/benchmarks/charts/throughput.svg" alt="Sustained throughput per codec, encode and decode, 1 MiB payloads">
+</picture>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rayakame/radixly/main/benchmarks/charts/latency.dark.svg">
+  <img src="https://raw.githubusercontent.com/rayakame/radixly/main/benchmarks/charts/latency.svg" alt="Per-call latency per codec, encode and decode, 200 B payloads">
+</picture>
+
+Reproduce with `uv run python -m benchmarks` from the repository root.
+
+## Limits
+
+- CPython only, 3.11 and later.
+- No subinterpreters: on 3.12+ the import raises `ImportError` inside one.
+  Free-threaded builds import but switch the GIL back on. Details in
+  [Subinterpreters and threads](https://radixly.rayakame.dev/en/latest/guides/subinterpreters.html).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

radixly-1.0.0/README.md

@@ -0,0 +1,110 @@
+<p align="center">
+  <a href="https://radixly.rayakame.dev/en/latest/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rayakame/radixly/main/docs/_static/logo-wordmark-dark.svg">
+      <img src="https://raw.githubusercontent.com/rayakame/radixly/main/docs/_static/logo-wordmark-light.svg" alt="radixly" width="420">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/radixly/"><img src="https://img.shields.io/pypi/v/radixly" alt="PyPI"></a>
+  <a href="https://radixly.rayakame.dev/en/latest/"><img src="https://readthedocs.org/projects/radixly/badge/?version=latest" alt="Documentation"></a>
+  <a href="https://github.com/rayakame/radixly/actions/workflows/ci.yml"><img src="https://github.com/rayakame/radixly/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/rayakame/radixly/actions/workflows/wheels.yml"><img src="https://github.com/rayakame/radixly/actions/workflows/wheels.yml/badge.svg" alt="Wheels"></a>
+  <a href="https://pypi.org/project/radixly/"><img src="https://img.shields.io/pypi/pyversions/radixly" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
+</p>
+
+Fast binary-to-text codecs for Python. Every codec is a hand-written C
+extension behind one small interface: `encode`, `decode` and the size math to
+plan around a length limit. Decoding is strict, the package has no
+dependencies and ships type stubs.
+
+Documentation: <https://radixly.rayakame.dev/en/latest/>
+
+## Install
+
+```bash
+pip install radixly
+```
+
+Releases ship wheels for CPython 3.11 to 3.14 on Linux, macOS and Windows.
+There is no pure-Python fallback; anywhere else pip builds from source and
+needs a C compiler.
+
+## Usage
+
+```python
+import radixly
+
+text = radixly.base32768.encode(b"hello")   # str, 3 characters
+radixly.base32768.decode(text)              # b'hello'
+
+radixly.base32768.max_bytes(100)            # 187: largest payload that fits 100 characters
+
+try:
+    radixly.base32768.decode("hello")
+except radixly.DecodeError as error:        # a ValueError with the position
+    error.position                          # 0
+```
+
+Every codec module has the same four functions; `radixly.get_codec(name)` and
+`radixly.CODECS` pick one at runtime.
+
+## Codecs
+
+| codec | bits per char | 100 chars hold | alphabet | catches truncation |
+|---|---|---|---|---|
+| [base32768](https://radixly.rayakame.dev/en/latest/codecs/base32768.html) | 15 | 187 bytes | qntm's 32,768 BMP code points | no |
+| [uro14](https://radixly.rayakame.dev/en/latest/codecs/uro14.html) | 14 | 173 bytes | one CJK block, plus a length prefix | below 16,384 bytes |
+| [braille](https://radixly.rayakame.dev/en/latest/codecs/braille.html) | 8 | 100 bytes | 256 Braille patterns | no |
+| [hexagram](https://radixly.rayakame.dev/en/latest/codecs/hexagram.html) | 6 | 75 bytes | 64 Yijing hexagrams | partly |
+
+[Choosing a codec](https://radixly.rayakame.dev/en/latest/guides/choosing-a-codec.html) walks through the
+trade-offs.
+
+## Performance
+
+Generated from the committed record run by the benchmark suite in
+[`benchmarks/`](benchmarks/); no number here is typed by hand. Sizes below
+64 KiB show per-call latency, larger ones sustained throughput; "vs reference"
+is the speedup over the pure-Python oracle in `tests/reference/`.
+
+<!-- radixly-bench:begin -->
+*Measured on Intel(R) Core(TM) i9-14900KF (performance governor), CachyOS, kernel 7.2.3-1-cachyos, CPython 3.13.14, gcc 16.2.1 20260810, radixly 0.1.0.dev0 @ cefe701, 2026-09-08T18:59:26+00:00.*
+
+| codec | direction | 1 B | 200 B | 64 KiB | 1 MiB | vs reference |
+|---|---|---|---|---|---|---|
+| base32768 | encode | 0.019 μs | 0.114 μs | 1,963 MB/s | 1,963 MB/s | 117x at 200 B |
+| base32768 | decode | 0.014 μs | 0.173 μs | 1,275 MB/s | 1,269 MB/s | 127x at 200 B |
+| braille | encode | 0.019 μs | 0.168 μs | 1,397 MB/s | 1,404 MB/s | 95x at 200 B |
+| braille | decode | 0.016 μs | 0.269 μs | 800 MB/s | 799 MB/s | 77x at 200 B |
+| hexagram | encode | 0.019 μs | 0.201 μs | 1,137 MB/s | 1,126 MB/s | 108x at 200 B |
+| hexagram | decode | 0.016 μs | 0.328 μs | 616 MB/s | 641 MB/s | 84x at 200 B |
+| uro14 | encode | 0.018 μs | 0.118 μs | 2,020 MB/s | 2,007 MB/s | 122x at 200 B |
+| uro14 | decode | 0.015 μs | 0.242 μs | 899 MB/s | 896 MB/s | 91x at 200 B |
+<!-- radixly-bench:end -->
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rayakame/radixly/main/benchmarks/charts/throughput.dark.svg">
+  <img src="https://raw.githubusercontent.com/rayakame/radixly/main/benchmarks/charts/throughput.svg" alt="Sustained throughput per codec, encode and decode, 1 MiB payloads">
+</picture>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rayakame/radixly/main/benchmarks/charts/latency.dark.svg">
+  <img src="https://raw.githubusercontent.com/rayakame/radixly/main/benchmarks/charts/latency.svg" alt="Per-call latency per codec, encode and decode, 200 B payloads">
+</picture>
+
+Reproduce with `uv run python -m benchmarks` from the repository root.
+
+## Limits
+
+- CPython only, 3.11 and later.
+- No subinterpreters: on 3.12+ the import raises `ImportError` inside one.
+  Free-threaded builds import but switch the GIL back on. Details in
+  [Subinterpreters and threads](https://radixly.rayakame.dev/en/latest/guides/subinterpreters.html).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

radixly-1.0.0/pyproject.toml

@@ -0,0 +1,163 @@
+[project]
+name = "radixly"
+dynamic = ["version"]
+description = "Fast binary-to-text codecs for Python: base32768, uro14, braille and hexagram in C"
+readme = "README.md"
+authors = [
+    { name = "rayakame", email = "github.android206@passmail.net" }
+]
+requires-python = ">=3.11"
+dependencies = []
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["base32768", "binary-to-text", "codec", "encoding", "unicode", "c-extension"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: C",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://radixly.rayakame.dev"
+Documentation = "https://radixly.rayakame.dev/en/latest/"
+Source = "https://github.com/rayakame/radixly"
+Issues = "https://github.com/rayakame/radixly/issues"
+
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    { include-group = "bench" },
+    { include-group = "clang" },
+    { include-group = "docs" },
+    { include-group = "nox" },
+    { include-group = "pyright" },
+    { include-group = "pytest" },
+    { include-group = "ruff" },
+]
+bench = [
+    "matplotlib>=3.10",
+]
+clang = [
+    "clang-format>=19",
+    "clang-tidy>=19",
+]
+release = [
+    "towncrier>=24.8",
+]
+docs = [
+    "sphinx>=9.0",
+    "furo>=2025.12",
+    "myst-parser>=5.0",
+    "sphinx-design>=0.7",
+    "sphinx-copybutton>=0.5",
+    "sphinx-autodoc-typehints>=3.0",
+    "sphinx-autobuild>=2024.10",
+]
+nox = [
+    "nox>=2026.8.17",
+]
+pytest = [
+    "pytest>=9.1.1",
+    "hypothesis>=6.100",
+]
+ruff = [
+    "ruff>=0.16.3",
+]
+pyright = [
+    "basedpyright>=1.39.10",
+]
+
+[tool.basedpyright]
+typeCheckingMode = "recommended"
+include = ["noxfile.py", "src", "tests", "scripts", "benchmarks"]
+# Resolve radixly from src/ so the checker sees the working tree, not the
+# installed copy; consumers get types via py.typed + the verifytypes gate.
+extraPaths = ["src"]
+executionEnvironments = [
+    { root = "tests", extraPaths = [".", "src"], pythonVersion = "3.11" },
+    { root = "src", pythonVersion = "3.11" },
+    { root = "scripts", pythonVersion = "3.14" },
+    { root = "benchmarks", extraPaths = [".", "src"], pythonVersion = "3.11"  },
+]
+
+reportUnusedCallResult = "none" # every nox.session() triggers this
+
+[tool.towncrier]
+package = "radixly"
+directory = "changes"
+filename = "CHANGELOG.md"
+start_string = "<!-- towncrier release notes start -->\n"
+title_format = "## {version} ({project_date})"
+issue_format = "[#{issue}](https://github.com/rayakame/radixly/pull/{issue})"
+underlines = ["", "", ""]
+ignore = ["README.md"]
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removal"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "doc"
+name = "Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "misc"
+name = "Other"
+showcontent = true
+
+[tool.setuptools.dynamic]
+version = { attr = "radixly._about.__version__" }
+
+[tool.setuptools]
+ext-modules = [
+  {name = "radixly._core", sources=["src/radixly/_core.c", "src/radixly/base32768/base32768.c", "src/radixly/braille/braille.c", "src/radixly/hexagram/hexagram.c", "src/radixly/uro14/uro14.c", "src/radixly/_common/block.c", "src/radixly/_common/errors.c"], include-dirs=["src/radixly"], extra-compile-args=["-std=c11"]}
+]
+
+# Keep C sources and headers out of binary wheels for every (sub)package;
+# sdists still ship them (ext-modules sources + MANIFEST.in headers).
+[tool.setuptools.exclude-package-data]
+"*" = ["*.c", "*.h"]
+
+# PEP 561: the marker and the _core stub must ride the wheel, or installed
+# consumers see an untyped package no matter how typed the source is.
+[tool.setuptools.package-data]
+radixly = ["py.typed", "*.pyi"]
+
+# CPython-only (C-API internals), no free-threading (static globals).
+# Warning flags (-Wall/-Wextra) are dev-only: MSVC rejects them, and the
+# Linux CI matrix already enforces them. 64-bit only; no win32.
+[tool.cibuildwheel]
+build = "cp311-* cp312-* cp313-* cp314-*"
+skip = "*t-* *-win32 *_i686"
+build-verbosity = 1
+test-requires = ["pytest>=9.1.1", "hypothesis>=6.100"]
+# No `cd`: Windows cmd does not switch drives without /d.
+test-command = "python -m pytest {project}/tests --ignore={project}/tests/bench -q"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

radixly-1.0.0/src/radixly/__init__.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2026-present rayakame
+#
+# 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.
+"""Fast binary-to-text codecs."""
+
+from __future__ import annotations
+
+from radixly import base32768 as base32768
+from radixly import braille as braille
+from radixly import hexagram as hexagram
+from radixly import uro14 as uro14
+from radixly._about import __author__ as __author__
+from radixly._about import __copyright__ as __copyright__
+from radixly._about import __license__ as __license__
+from radixly._about import __url__ as __url__
+from radixly._about import __version__ as __version__
+from radixly._codec import *
+from radixly._core import DecodeError as DecodeError

{radixly-0.1.0.dev0 → radixly-1.0.0}/src/radixly/_about.py

@@ -24,5 +24,5 @@ import typing
 __author__: typing.Final[str] = "rayakame"
 __copyright__: typing.Final[str] = "2026-present, Rayakame"
 __url__: typing.Final[str] = "https://github.com/rayakame/radixly"
-__version__: typing.Final[str] = "0.1.0"
+__version__: typing.Final[str] = "1.0.0"
 __license__: typing.Final[str] = "MIT"

radixly-1.0.0/src/radixly/_codec.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2026-present rayakame
+#
+# 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.
+"""The Codec value type and the name registry shared by every codec."""
+
+from __future__ import annotations
+
+import dataclasses
+import types
+import typing
+
+if typing.TYPE_CHECKING:
+    import collections.abc
+
+    from _typeshed import ReadableBuffer
+
+__all__ = ("CODECS", "Codec", "get_codec", "register")
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Codec:
+    """One codec as a value: the C functions bound as attributes, plus its numbers.
+
+    codec.encode(data) is one attribute load and the C call, no Python frame.
+
+    Attributes
+    ----------
+    name
+        The registry key, e.g. ``"base32768"``.
+    bits_per_char
+        Payload bits per output character.
+    """
+
+    name: str
+    bits_per_char: int
+    encode: collections.abc.Callable[[ReadableBuffer], str]
+    decode: collections.abc.Callable[[str], bytes]
+    encoded_len: collections.abc.Callable[[int], int]
+    max_bytes: collections.abc.Callable[[int], int]
+
+
+_registry: dict[str, Codec] = {}
+CODECS = types.MappingProxyType(_registry)
+
+
+def register(codec: Codec) -> None:
+    """Add ``codec`` under its name; a taken name is refused.
+
+    Parameters
+    ----------
+    codec
+        The codec to register.
+
+    Raises
+    ------
+    ValueError
+        If the name is already registered.
+    """
+    if codec.name in _registry:
+        msg = f"codec {codec.name!r} is already registered"
+        raise ValueError(msg)
+
+    _registry[codec.name] = codec
+
+
+def get_codec(name: str) -> Codec:
+    """Look up a registered codec by name.
+
+    Parameters
+    ----------
+    name
+        The registry key.
+
+    Returns
+    -------
+    Codec
+        The registered codec.
+
+    Raises
+    ------
+    KeyError
+        Unknown name; the message lists what is registered.
+
+    Examples
+    --------
+    >>> import radixly
+    >>> radixly.get_codec("uro14").bits_per_char
+    14
+    """
+    codec = _registry.get(name)
+    if codec is None:
+        msg = f"unknown codec {name!r}; registered: {', '.join(sorted(_registry))}"
+        raise KeyError(msg)
+    return codec