cpp-kana2 2.0.0__tar.gz

cpp_kana2-2.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (C) 2023-2026 wolfgitpr
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cpp_kana2-2.0.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: cpp-kana2
+Version: 2.0.0
+Summary: Japanese kana <-> Hepburn romaji, over the cpp-kana2 C ABI
+Home-page: https://github.com/wolfgitpr/cpp-kana
+Author: wolfgitpr
+License: Apache-2.0
+Project-URL: Documentation, https://github.com/wolfgitpr/cpp-kana/blob/v2/docs/README.md
+Project-URL: API reference, https://github.com/wolfgitpr/cpp-kana/blob/v2/docs/API.md
+Project-URL: Source, https://github.com/wolfgitpr/cpp-kana/tree/v2
+Project-URL: Changelog, https://github.com/wolfgitpr/cpp-kana/blob/v2/CHANGELOG.md
+Project-URL: Issues, https://github.com/wolfgitpr/cpp-kana/issues
+Keywords: japanese kana hiragana katakana romaji hepburn nlp
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: C++
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: Japanese
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# cpp-kana2
+
+`cpp-kana2` converts Japanese kana to Hepburn romaji and back. Kana input may be hiragana, katakana,
+half-width katakana, or a kana followed by a dakuten/handakuten mark, precomposed or combining; romaji input
+accepts the Hepburn spellings plus the common input aliases. The library is C++17 and has no third-party
+dependencies: the mora table is compiled in, and the tests use an assertion harness that ships with the tree.
+It offers three calling surfaces — the C++ API, the C ABI, and the Python and C# bindings, which sit on top of
+the C ABI.
+
+## Status
+
+This is the `v2` branch. The package is `cpp-kana2`, the C++ namespace is `cpp_kana::v2`, the public headers
+live under `<cpp-kana2/...>`, and the C surface carries its own tokens: `cppk2_` on symbols and typedefs,
+`CPPK2_` on enum constants and macros. The version is `2.0.0`; this development line has not been released
+yet, so that number is the contract for its first release rather than a bump of the v1 line.
+
+It is a from-scratch rewrite that does not aim for behavioural compatibility with v1: v1's output is not a
+contract here, and where v2 deliberately answers differently, the reason is recorded per case in
+[docs/V1_DIFFERENCES.md](docs/V1_DIFFERENCES.md).
+
+## Quick start
+
+### C++
+
+```cpp
+#include <cstdio>
+
+#include <cpp-kana2/core/Convert.h>
+
+int main() {
+    using namespace cpp_kana::v2;
+    const auto romanised = kanaToRomaji("きって");
+    if (!romanised.ok()) {
+        std::printf("%s\n", codeText(romanised.error().code));
+        return 1;
+    }
+    std::puts(romanised.value().rendered().c_str()); // kitte
+    return 0;
+}
+```
+
+A failure is a value (`Outcome<T>`), not an exception, so no `try`/`catch` is needed. `Conversion` also
+exposes the per-unit breakdown through `moras()`. Linking is `target_link_libraries(app PRIVATE
+cpp-kana2::cpp-kana2)`; the include directory is `include/`.
+
+### C
+
+```c
+#include <stdio.h>
+
+#include <cpp-kana2/ext/c_api.h>
+
+int main(void) {
+    cppk2_conversion *conversion = NULL;
+    cppk2_error error = {0};
+    const int32_t status = cppk2_kana_to_romaji("きって", NULL, &conversion, &error);
+    if (status != CPPK2_OK) {
+        printf("%s\n", error.detail != NULL ? error.detail : "(no detail)");
+        cppk2_string_free(error.detail); /* ownership rule below */
+        return 1;
+    }
+    printf("%s\n", conversion->rendered);
+    cppk2_conversion_free(conversion);
+    return 0;
+}
+```
+
+Ownership rule: every allocation the library makes is freed by the library. A conversion (and every string
+inside it) goes to `cppk2_conversion_free`; a detached string such as `cppk2_error.detail` goes to
+`cppk2_string_free`. Calling the C runtime's `free()` on those pointers is heap corruption on Windows, not a
+leak. Strings are NUL-terminated UTF-8 and failures are returned as status codes; no C++ exception crosses
+the boundary.
+
+### Python
+
+```python
+import cpp_kana2
+
+cpp_kana2.kana_to_romaji("こんにちは").rendered
+```
+
+### C#
+
+```csharp
+using CppKana2;
+
+var romaji = Kana.KanaToRomaji("こんにちは").Rendered;
+```
+
+### Build and test from source
+
+```bash
+cmake --preset default
+cmake --build --preset default
+ctest --preset default
+```
+
+The `default` preset is a Release, shared-library build with tests and install enabled; `CMakePresets.json`
+also defines `static` and `sanitize`. Using presets needs CMake 3.21 or newer, while the library itself only
+needs 3.17. Build output goes under `.tmp/`.
+
+Staging the Python package (builds the native library, writes `_version.py`, records the library's file
+name):
+
+```bash
+python python/tools/build_native.py
+python -m pytest python/tests -q
+```
+
+The C# suite (needs `dotnet`; it reuses the native library the Python step staged unless `--native-dir` is
+given):
+
+```bash
+python csharp/tools/run_tests.py
+```
+
+## Behaviour
+
+The romanisation is Hepburn. There is no "scheme" switch: what varies between the ways people write the same
+text down is captured by the policy enums in
+[include/cpp-kana2/core/Types.h](include/cpp-kana2/core/Types.h).
+
+Default options for `kanaToRomaji` (`RomajiOptions`):
+
+| Option | Default | Meaning |
+|---|---|---|
+| `sokuon` | `SokuonPolicy::Geminate` | A sokuon doubles the next consonant: きって → `kitte`, まっちゃ → `matcha` |
+| `hatsuon` | `HatsuonPolicy::Apostrophe` | A hatsuon before a vowel or `y` is written `n'`: しんよう → `shin'you` |
+| `longVowel` | `LongVowelPolicy::Repeat` | A long vowel repeats the previous vowel: コーヒー → `koohii` |
+| `letterCase` | `CasePolicy::Lower` | Lower-case output |
+| `separator` | `SeparatorPolicy::None` | Compact output with no separator between morae |
+| `unknown` | `UnknownPolicy::Keep` | A character the table does not know is kept and marked per mora |
+
+`KanaOptions` (for `romajiToKana`) defaults to `Script::Hiragana` and `UnknownPolicy::Keep`.
+
+The policy enums and their values:
+
+- `Script`: `Hiragana` = 0, `Katakana` = 1, `AsIs` = 2 (`AsIs` applies to `convertScript` only).
+- `SokuonPolicy`: `Geminate` = 0, `Drop` = 1 (renders nothing for the sokuon).
+- `HatsuonPolicy`: `Apostrophe` = 0, `Plain` = 1 (always writes `n`).
+- `LongVowelPolicy`: `Repeat` = 0, `Drop` = 1 (`kohi`), `KatakanaDash` = 2 (`ko-hi-`).
+- `CasePolicy`: `Lower` = 0, `Upper` = 1, `Capitalize` = 2.
+- `SeparatorPolicy`: `Space` = 0, `None` = 1.
+- `UnknownPolicy`: `Keep` = 0, `Ignore` = 1, `Fail` = 2 (`Fail` makes the call fail instead of marking the
+  mora).
+
+The C ABI mirrors these enums by number (`CPPK2_SOKUON_*`, `CPPK2_LONG_VOWEL_*`, ...), so a binding does not
+need its own table. Per-unit results carry a `MoraKind` (`Syllable`, `Sokuon`, `Hatsuon`, `LongVowel`,
+`Other`, `Archaic`, `Romaji`) and a per-unit `Code`, which is how a caller tells an ordinary syllable from a
+kept unknown character without parsing the rendered string.
+
+## Gates
+
+The repository-wide checks are Python scripts under `tools/` and are registered by name in
+[tools/run_all_gates.py](tools/run_all_gates.py):
+
+- `check_source_list` — the explicit source lists in `CMakeLists.txt` describe `src/` and `include/` in both
+  directions, so a file cannot join or leave the tree silently.
+- `check_layers` — `src/` includes only point downwards through the layer table, and every `src/` file
+  belongs to a layer.
+- `check_public_surface` — the public headers, the C ABI symbols and the namespace-level names match the
+  frozen lists in `tests/abi/`, in both directions.
+- `check_bindings` — the Python and C# bindings transcribe the C ABI exactly: same entry points, same
+  structures, same field order.
+- `check_version_tokens` — `project(cpp-kana2 VERSION ...)` is the single authority, and the version header,
+  the Python `_version.py`, the C# `version.props` and the CHANGELOG's top entry agree with it.
+- `check_data_tables` — re-runs the table derivation and audits `data/moras.tsv` itself (duplicate kana,
+  ambiguous aliases, lying `secondary` flags, stray carriage returns).
+- `check_conformance` — pins `conformance/cases.json` by its sha256 and checks the provenance field.
+- `check_doc_links` — every relative link in every Markdown file resolves (a link to a generated, gitignored
+  file is a NOTE, not a failure).
+- `check_doc_citations` — every `file:line` reference in the docs points at a line that still exists, so a
+  cleanup that deletes code cannot leave a citation pointing at nothing.
+- `check_gate_inventory` — the gate registry, the scripts on disk and the `CPP_KANA2_GATES` list in
+  `tests/CMakeLists.txt` name the same gates.
+
+Each gate is also a ctest test (`Gate_<name>`) when a Python 3 interpreter is found, and each one has a
+`--self-test` that drives a synthetic failure through it. `tools/run_all_gates.py` runs the self-test before
+the real check and stops the run if a self-test fails. When Python 3 is not found the gates are not
+registered, and the C++ suite stays runnable on a compiler-only machine.
+
+ctest also carries the non-Python assertions: `Smoke` and `CapiSmoke` (the C ABI smoke test is compiled as C),
+`ConformanceFixture` (re-derives the fixture and compares it with the tracked bytes), `Gate_ExportGate` and its
+self-test (the shared library's export table against the frozen symbol list), `Gate_SonameGate` on ELF, and
+`Gate_InstallConsumer` (installs into a throwaway prefix and builds a consumer, including one that must be
+refused for asking for a different major version).
+
+## Project layout
+
+```
+include/cpp-kana2/core/   Convert.h Global.h Mora.h Types.h Utf8.h Version.h
+include/cpp-kana2/ext/    c_api.h
+src/infra/                UTF-8, Unicode and status-code text
+src/data/                 the compiled-in mora table (generated from data/moras.tsv)
+src/mora/                 normalisation, segmentation, kana -> romaji, romaji -> kana
+src/core/                 the public entry points
+src/c_api/                the C ABI implementation
+python/cpp_kana2/         the Python package (ctypes)
+python/tests/             the pytest suite
+csharp/CppKana2/          the C# binding (P/Invoke)
+csharp/CppKana2.Tests/    the C# suite
+tests/                    cpp/ suites, abi/ frozen lists, install/ consumer check, data/corpus/
+tools/                    the gates, the table generator, the conformance emitter
+data/                     moras.tsv, the table's source
+conformance/              cases.json + cases.sha256, the fixture all three suites read
+```
+
+## License
+
+Apache License 2.0; see [LICENSE](LICENSE).

cpp_kana2-2.0.0/cpp_kana2/__init__.py

@@ -0,0 +1,237 @@
+"""cpp-kana2 for Python: a thin, honest shell over the C ABI.
+
+Design rules, all of which exist because a binding that invents behaviour is worse than no binding:
+
+* One-to-one with the C surface. ``kana_to_romaji``, ``romaji_to_kana``, ``convert_script``, ``version`` and
+  ``code_text`` are the whole API; the option objects mirror the option structs field for field.
+* Failures raise, because that is what a Python caller expects -- and each status code maps to its own
+  exception class (see ``_errors``). The detail text always comes from the library, never from here.
+* Every native allocation is released in a ``finally``. The conversion is copied into plain Python objects
+  before the native one is freed, so a returned object never points into freed memory.
+* No hidden retries, no normalisation, no silent replacement characters: what the library says is what you
+  get.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Optional, Tuple
+
+from . import _errors, _ffi, _native
+from ._errors import (  # re-exported: callers should not have to import a private module to catch them
+    CppKanaError,
+    DataCorruptError,
+    InternalError,
+    InvalidArgumentError,
+    InvalidUtf8Error,
+    NotReadyError,
+    UnsupportedCharacterError,
+)
+from ._native import NativeLibraryError
+
+__all__ = [
+    "Conversion",
+    "KanaOptions",
+    "Mora",
+    "MoraKind",
+    "RomajiOptions",
+    "Script",
+    "code_text",
+    "convert_script",
+    "kana_to_romaji",
+    "romaji_to_kana",
+    "version",
+    "CppKanaError",
+    "DataCorruptError",
+    "InternalError",
+    "InvalidArgumentError",
+    "InvalidUtf8Error",
+    "NativeLibraryError",
+    "NotReadyError",
+    "UnsupportedCharacterError",
+]
+
+_library = _ffi.declare(_native.load())
+
+try:  # generated by tools/build_native.py; git-ignored
+    from ._version import __version__  # type: ignore
+except ImportError:  # pragma: no cover - a checkout nobody staged
+    __version__ = "0.0.0+unknown"
+
+
+class MoraKind(IntEnum):
+    SYLLABLE = _ffi.MORA_SYLLABLE
+    SOKUON = _ffi.MORA_SOKUON
+    HATSUON = _ffi.MORA_HATSUON
+    LONG_VOWEL = _ffi.MORA_LONG_VOWEL
+    OTHER = _ffi.MORA_OTHER
+    ARCHAIC = _ffi.MORA_ARCHAIC
+    ROMAJI = _ffi.MORA_ROMAJI
+
+
+class Script(IntEnum):
+    HIRAGANA = _ffi.SCRIPT_HIRAGANA
+    KATAKANA = _ffi.SCRIPT_KATAKANA
+    AS_IS = _ffi.SCRIPT_AS_IS
+
+
+@dataclass(frozen=True)
+class Mora:
+    """One unit of a conversion, copied out of the native structure."""
+
+    text: str
+    rendered: str
+    kind: MoraKind
+    code: int
+
+    @property
+    def ok(self) -> bool:
+        return self.code == _ffi.OK
+
+
+@dataclass(frozen=True)
+class Conversion:
+    """The whole result: the rendered string plus the per-unit breakdown."""
+
+    text: str
+    rendered: str
+    moras: Tuple[Mora, ...]
+    ok: bool
+
+    def __str__(self) -> str:
+        return self.rendered
+
+    def __len__(self) -> int:
+        return len(self.moras)
+
+
+_SCRIPT_NAMES = {"hiragana": Script.HIRAGANA, "katakana": Script.KATAKANA, "as_is": Script.AS_IS}
+_SOKUON_NAMES = {"geminate": _ffi.SOKUON_GEMINATE, "drop": _ffi.SOKUON_DROP}
+_HATSUON_NAMES = {"apostrophe": _ffi.HATSUON_APOSTROPHE, "plain": _ffi.HATSUON_PLAIN}
+_LONG_VOWEL_NAMES = {"repeat": _ffi.LONG_VOWEL_REPEAT, "drop": _ffi.LONG_VOWEL_DROP, "dash": _ffi.LONG_VOWEL_KATAKANA_DASH}
+_CASE_NAMES = {"lower": _ffi.CASE_LOWER, "upper": _ffi.CASE_UPPER, "capitalize": _ffi.CASE_CAPITALIZE}
+_SEPARATOR_NAMES = {"space": _ffi.SEPARATOR_SPACE, "none": _ffi.SEPARATOR_NONE}
+_UNKNOWN_NAMES = {"keep": _ffi.UNKNOWN_KEEP, "ignore": _ffi.UNKNOWN_IGNORE, "fail": _ffi.UNKNOWN_FAIL}
+
+
+def _lookup(table: dict, value, what: str) -> int:
+    if isinstance(value, int):
+        return int(value)
+    try:
+        return table[value]
+    except (KeyError, TypeError):
+        raise InvalidArgumentError(
+            _ffi.ERR_INVALID_ARGUMENT, f"{what}={value!r} is not one of {sorted(table)}"
+        ) from None
+
+
+@dataclass(frozen=True)
+class RomajiOptions:
+    """Mirrors ``cppk2_romaji_options``. Defaults are the library's own defaults."""
+
+    sokuon: str = "geminate"
+    hatsuon: str = "apostrophe"
+    long_vowel: str = "repeat"
+    case: str = "lower"
+    separator: str = "none"
+    unknown: str = "keep"
+
+    def _to_struct(self) -> _ffi.RomajiOptionsStruct:
+        struct = _ffi.RomajiOptionsStruct()
+        struct.struct_size = ctypes.sizeof(_ffi.RomajiOptionsStruct)
+        status = _library.cppk2_romaji_options_init(ctypes.byref(struct), struct.struct_size)
+        _errors.raise_for_status(status)
+        struct.sokuon = _lookup(_SOKUON_NAMES, self.sokuon, "sokuon")
+        struct.hatsuon = _lookup(_HATSUON_NAMES, self.hatsuon, "hatsuon")
+        struct.long_vowel = _lookup(_LONG_VOWEL_NAMES, self.long_vowel, "long_vowel")
+        struct.letter_case = _lookup(_CASE_NAMES, self.case, "case")
+        struct.separator = _lookup(_SEPARATOR_NAMES, self.separator, "separator")
+        struct.unknown = _lookup(_UNKNOWN_NAMES, self.unknown, "unknown")
+        return struct
+
+
+@dataclass(frozen=True)
+class KanaOptions:
+    """Mirrors ``cppk2_kana_options``."""
+
+    script: str = "hiragana"
+    unknown: str = "keep"
+
+    def _to_struct(self) -> _ffi.KanaOptionsStruct:
+        struct = _ffi.KanaOptionsStruct()
+        struct.struct_size = ctypes.sizeof(_ffi.KanaOptionsStruct)
+        status = _library.cppk2_kana_options_init(ctypes.byref(struct), struct.struct_size)
+        _errors.raise_for_status(status)
+        struct.script = int(_lookup(_SCRIPT_NAMES, self.script, "script"))
+        struct.unknown = _lookup(_UNKNOWN_NAMES, self.unknown, "unknown")
+        return struct
+
+
+def _encode(text: str) -> bytes:
+    if not isinstance(text, str):
+        raise InvalidArgumentError(_ffi.ERR_INVALID_ARGUMENT, f"expected str, got {type(text).__name__}")
+    if "\x00" in text:
+        # The C ABI takes NUL-terminated strings; an embedded NUL would truncate silently.
+        raise InvalidArgumentError(_ffi.ERR_INVALID_ARGUMENT, "text must not contain U+0000")
+    return text.encode("utf-8")
+
+
+def _convert(call) -> Conversion:
+    out = ctypes.POINTER(_ffi.ConversionStruct)()
+    error = _ffi.ErrorStruct()
+    status = call(out, error)
+    if status != _ffi.OK:
+        detail = _ffi.take_detail(_library, error)
+        _errors.raise_for_status(status, detail)
+    try:
+        native = out.contents
+        moras = tuple(
+            Mora(text=view.text, rendered=view.rendered, kind=MoraKind(view.kind), code=view.code)
+            for view in _ffi.moras_of(native)
+        )
+        return Conversion(
+            text=(native.text or b"").decode("utf-8", "replace"),
+            rendered=(native.rendered or b"").decode("utf-8", "replace"),
+            moras=moras,
+            ok=bool(native.ok),
+        )
+    finally:
+        _library.cppk2_conversion_free(out)
+
+
+def kana_to_romaji(text: str, options: Optional[RomajiOptions] = None) -> Conversion:
+    """Kana (hiragana, katakana, half-width, combining dakuten) -> Hepburn romaji."""
+    data = _encode(text)
+    if options is None:
+        return _convert(lambda out, err: _library.cppk2_kana_to_romaji(data, None, out, err))
+    struct = options._to_struct()
+    return _convert(lambda out, err: _library.cppk2_kana_to_romaji(data, ctypes.byref(struct), out, err))
+
+
+def romaji_to_kana(text: str, options: Optional[KanaOptions] = None) -> Conversion:
+    """Hepburn romaji (plus Kunrei/IME aliases) -> kana."""
+    data = _encode(text)
+    if options is None:
+        return _convert(lambda out, err: _library.cppk2_romaji_to_kana(data, None, out, err))
+    struct = options._to_struct()
+    return _convert(lambda out, err: _library.cppk2_romaji_to_kana(data, ctypes.byref(struct), out, err))
+
+
+def convert_script(text: str, target: str = "hiragana", unknown: str = "keep") -> Conversion:
+    """Hiragana <-> katakana, with half-width input normalised first."""
+    data = _encode(text)
+    script = int(_lookup(_SCRIPT_NAMES, target, "target"))
+    unknown_code = _lookup(_UNKNOWN_NAMES, unknown, "unknown")
+    return _convert(lambda out, err: _library.cppk2_convert_script(data, script, unknown_code, out, err))
+
+
+def version() -> str:
+    """The native library's package version (not this module's)."""
+    return _library.cppk2_version().decode("utf-8")
+
+
+def code_text(code: int) -> str:
+    """The library's wording for a status code -- the only place that wording lives."""
+    return _library.cppk2_code_text(int(code)).decode("utf-8")