bethkit 1.0.0__py3-none-win_amd64.whl

bethkit/strings/strings.py

@@ -0,0 +1,522 @@
+"""
+Copyright (c) Modding Forge
+"""
+from __future__ import annotations
+
+import ctypes
+from pathlib import Path
+from typing import Optional
+
+from .. import _ffi
+from .._error import BethkitClosedError
+from ..enums import StringFileKind
+
+
+def _buf_from_bytes(data: bytes) -> ctypes.Array[ctypes.c_uint8]:
+    """
+    Wrap *data* in a ctypes ``c_uint8`` array for FFI calls.
+
+    Args:
+        data (bytes): Byte sequence to wrap.
+
+    Returns:
+        ctypes.Array: A ``c_uint8`` array backed by a copy of *data*.
+    """
+
+    return (ctypes.c_uint8 * len(data)).from_buffer_copy(data)
+
+
+class StringTable:
+    """
+    A Bethesda string localisation table (``.STRINGS``, ``.DLSTRINGS``,
+    or ``.ILSTRINGS`` files).
+
+    String tables map numeric IDs to UTF-8 string payloads.  They can be
+    loaded from disk with :meth:`open`, or created fresh with :meth:`new`
+    and written back with :meth:`write_to_file`.
+
+    Use as a context manager to guarantee that the native handle is
+    freed::
+
+        with StringTable.open(path) as tbl:
+            text = tbl.get_str(0x0001)
+    """
+
+    __ptr: int
+
+    def __init__(self, ptr: int) -> None:
+        """
+        Args:
+            ptr (int): Native handle returned by the FFI open/new call.
+        """
+
+        self.__ptr = ptr
+
+    def __check_open(self) -> int:
+        """
+        Return the native pointer, raising if the handle has been closed.
+
+        Returns:
+            int: Valid native pointer.
+
+        Raises:
+            BethkitClosedError: If the table has been closed.
+        """
+
+        if not self.__ptr:
+            raise BethkitClosedError("StringTable is closed")
+        return self.__ptr
+
+    @classmethod
+    def new(cls, kind: StringFileKind) -> StringTable:
+        """
+        Create an empty string table of the given kind.
+
+        Args:
+            kind (StringFileKind): Type of string file to create.
+
+        Returns:
+            StringTable: A new, empty ``StringTable``.
+
+        Raises:
+            BethkitNativeError: If the native table cannot be created.
+        """
+
+        lib = _ffi.load_lib()
+        ptr = lib.bethkit_string_table_new(int(kind))
+        if not ptr:
+            _ffi.raise_last_error(lib)
+        return cls(ptr)
+
+    @classmethod
+    def open(cls, path: Path) -> StringTable:
+        """
+        Open a string table file from disk.
+
+        Args:
+            path (Path): Filesystem path to the string file.
+
+        Returns:
+            StringTable: A new ``StringTable`` loaded from *path*.
+
+        Raises:
+            BethkitNativeError: If the file cannot be opened or parsed.
+        """
+
+        lib = _ffi.load_lib()
+        ptr = lib.bethkit_string_table_open(_ffi.enc(path))
+        if not ptr:
+            _ffi.raise_last_error(lib)
+        return cls(ptr)
+
+    def close(self) -> None:
+        """
+        Release the native string-table handle.
+
+        Safe to call multiple times; subsequent calls are no-ops.
+        """
+
+        if self.__ptr:
+            _ffi.load_lib().bethkit_string_table_free(self.__ptr)
+            self.__ptr = 0
+
+    def __enter__(self) -> StringTable:
+        """Return *self* for use as a context manager."""
+
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Free the table when exiting the context."""
+
+        self.close()
+
+    def __del__(self) -> None:
+        """Free the native handle on garbage collection."""
+
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    @property
+    def kind(self) -> StringFileKind:
+        """
+        The string-file format of this table.
+
+        Returns:
+            StringFileKind: ``STRINGS``, ``DL_STRINGS``, or
+            ``IL_STRINGS``.
+
+        Raises:
+            BethkitClosedError: If the table has been closed.
+        """
+
+        return StringFileKind(
+            _ffi.load_lib().bethkit_string_table_kind(self.__check_open())
+        )
+
+    def __len__(self) -> int:
+        """
+        Returns:
+            int: Number of entries in the table.
+        """
+
+        return _ffi.load_lib().bethkit_string_table_len(
+            self.__check_open()
+        )
+
+    def get(self, id: int) -> Optional[bytes]:
+        """
+        Retrieve a string entry as raw bytes by its ID.
+
+        Args:
+            id (int): Numeric string ID.
+
+        Returns:
+            Optional[bytes]: Raw string bytes, or ``None`` if not found.
+
+        Raises:
+            BethkitClosedError: If the table has been closed.
+        """
+
+        lib = _ffi.load_lib()
+        out_len = ctypes.c_size_t(0)
+        ptr = lib.bethkit_string_table_get(
+            self.__check_open(), id, ctypes.byref(out_len)
+        )
+        if not ptr:
+            return None
+        return bytes(ctypes.string_at(ptr, out_len.value))
+
+    def get_str(self, id: int) -> Optional[str]:
+        """
+        Retrieve a string entry decoded as UTF-8 by its ID.
+
+        Args:
+            id (int): Numeric string ID.
+
+        Returns:
+            Optional[str]: Decoded string without trailing null, or
+            ``None`` if not found.
+        """
+
+        raw = self.get(id)
+        if raw is None:
+            return None
+        return raw.rstrip(b"\x00").decode("utf-8")
+
+    def insert(self, id: int, data: bytes) -> None:
+        """
+        Insert or overwrite an entry with the given ID.
+
+        Args:
+            id (int): Numeric string ID.
+            data (bytes): String payload (may include trailing null).
+
+        Raises:
+            BethkitClosedError: If the table has been closed.
+            BethkitNativeError: If the native call fails.
+        """
+
+        lib = _ffi.load_lib()
+        buf = _buf_from_bytes(data)
+        if lib.bethkit_string_table_insert(
+            self.__check_open(), id, buf, len(data)
+        ) != 0:
+            _ffi.raise_last_error(lib)
+
+    def insert_new(self, data: bytes) -> int:
+        """
+        Insert a new entry and return the auto-assigned ID.
+
+        Args:
+            data (bytes): String payload.
+
+        Returns:
+            int: The ID assigned to the new entry.
+
+        Raises:
+            BethkitClosedError: If the table has been closed.
+            BethkitNativeError: If the native call fails.
+        """
+
+        lib = _ffi.load_lib()
+        buf = _buf_from_bytes(data)
+        out_id = ctypes.c_uint32(0)
+        if (
+            lib.bethkit_string_table_insert_new(
+                self.__check_open(), buf, len(data), ctypes.byref(out_id)
+            )
+            != 0
+        ):
+            _ffi.raise_last_error(lib)
+        return out_id.value
+
+    def remove(self, id: int) -> bool:
+        """
+        Remove the entry with the given ID.
+
+        Args:
+            id (int): Numeric string ID to remove.
+
+        Returns:
+            bool: ``True`` if the entry existed and was removed.
+        """
+
+        return bool(
+            _ffi.load_lib().bethkit_string_table_remove(
+                self.__check_open(), id
+            )
+        )
+
+    def write_to_file(self, path: Path) -> None:
+        """
+        Serialise the table and write it to *path* on disk.
+
+        Args:
+            path (Path): Destination file path.
+
+        Raises:
+            BethkitClosedError: If the table has been closed.
+            BethkitNativeError: If serialisation or the write fails.
+        """
+
+        lib = _ffi.load_lib()
+        if lib.bethkit_string_table_write_to_file(
+            self.__check_open(), _ffi.enc(path)
+        ) != 0:
+            _ffi.raise_last_error(lib)
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            str: Developer-friendly representation with kind and entry
+            count.
+        """
+
+        try:
+            return f"<StringTable kind={self.kind.name} len={len(self)}>"
+        except BethkitClosedError:
+            return "<StringTable closed>"
+
+
+class LocalizationSet:
+    """
+    A combined set of all three localisation tables for a single plugin.
+
+    A :class:`LocalizationSet` bundles the ``.STRINGS``, ``.DLSTRINGS``,
+    and ``.ILSTRINGS`` files for a given language.  Load them together
+    with :meth:`open`, or create an empty set with :meth:`new` and
+    populate it manually.
+    """
+
+    __ptr: int
+
+    def __init__(self, ptr: int) -> None:
+        """
+        Args:
+            ptr (int): Native handle returned by the FFI open/new call.
+        """
+
+        self.__ptr = ptr
+
+    def __check_open(self) -> int:
+        """
+        Return the native pointer, raising if the handle has been closed.
+
+        Returns:
+            int: Valid native pointer.
+
+        Raises:
+            BethkitClosedError: If the set has been closed.
+        """
+
+        if not self.__ptr:
+            raise BethkitClosedError("LocalizationSet is closed")
+        return self.__ptr
+
+    @classmethod
+    def new(cls) -> LocalizationSet:
+        """
+        Create an empty localisation set.
+
+        Returns:
+            LocalizationSet: A new, empty set with no strings loaded.
+
+        Raises:
+            BethkitNativeError: If the native set cannot be created.
+        """
+
+        lib = _ffi.load_lib()
+        ptr = lib.bethkit_localization_set_new()
+        if not ptr:
+            _ffi.raise_last_error(lib)
+        return cls(ptr)
+
+    @classmethod
+    def open(
+        cls, plugin_path: Path, language: str
+    ) -> LocalizationSet:
+        """
+        Load all localisation files for the given plugin and language.
+
+        The method looks for ``<plugin_stem>_<language>.STRINGS`` and
+        sibling ``.DLSTRINGS`` / ``.ILSTRINGS`` files next to the plugin.
+
+        Args:
+            plugin_path (Path): Filesystem path to the plugin file.
+            language (str): BCP 47-style language code
+                (e.g. ``"english"``).
+
+        Returns:
+            LocalizationSet: The loaded set.
+
+        Raises:
+            BethkitNativeError: If any required string file cannot be
+                opened.
+        """
+
+        lib = _ffi.load_lib()
+        ptr = lib.bethkit_localization_set_open(
+            _ffi.enc(plugin_path), _ffi.senc(language)
+        )
+        if not ptr:
+            _ffi.raise_last_error(lib)
+        return cls(ptr)
+
+    def close(self) -> None:
+        """
+        Release the native localisation-set handle.
+
+        Safe to call multiple times; subsequent calls are no-ops.
+        """
+
+        if self.__ptr:
+            _ffi.load_lib().bethkit_localization_set_free(self.__ptr)
+            self.__ptr = 0
+
+    def __enter__(self) -> LocalizationSet:
+        """Return *self* for use as a context manager."""
+
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Free the set when exiting the context."""
+
+        self.close()
+
+    def __del__(self) -> None:
+        """Free the native handle on garbage collection."""
+
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def get(
+        self, kind: StringFileKind, id: int
+    ) -> Optional[bytes]:
+        """
+        Retrieve a string from the specified sub-table by its ID.
+
+        Args:
+            kind (StringFileKind): Which sub-table to query.
+            id (int): Numeric string ID.
+
+        Returns:
+            Optional[bytes]: Raw string bytes, or ``None`` if not found.
+
+        Raises:
+            BethkitClosedError: If the set has been closed.
+        """
+
+        lib = _ffi.load_lib()
+        out_len = ctypes.c_size_t(0)
+        ptr = lib.bethkit_localization_set_get(
+            self.__check_open(), int(kind), id, ctypes.byref(out_len)
+        )
+        if not ptr:
+            return None
+        return bytes(ctypes.string_at(ptr, out_len.value))
+
+    def get_str(
+        self, kind: StringFileKind, id: int
+    ) -> Optional[str]:
+        """
+        Retrieve a string from the specified sub-table decoded as UTF-8.
+
+        Args:
+            kind (StringFileKind): Which sub-table to query.
+            id (int): Numeric string ID.
+
+        Returns:
+            Optional[str]: Decoded string without trailing null, or
+            ``None`` if not found.
+        """
+
+        raw = self.get(kind, id)
+        if raw is None:
+            return None
+        return raw.rstrip(b"\x00").decode("utf-8")
+
+    def set(
+        self, kind: StringFileKind, id: int, data: bytes
+    ) -> None:
+        """
+        Insert or overwrite an entry in the specified sub-table.
+
+        Args:
+            kind (StringFileKind): Which sub-table to modify.
+            id (int): Numeric string ID.
+            data (bytes): String payload.
+
+        Raises:
+            BethkitClosedError: If the set has been closed.
+            BethkitNativeError: If the native call fails.
+        """
+
+        lib = _ffi.load_lib()
+        buf = _buf_from_bytes(data)
+        if (
+            lib.bethkit_localization_set_set(
+                self.__check_open(), int(kind), id, buf, len(data)
+            )
+            != 0
+        ):
+            _ffi.raise_last_error(lib)
+
+    def write(
+        self, plugin_path: Path, language: str
+    ) -> None:
+        """
+        Write all sub-tables to disk next to *plugin_path*.
+
+        Args:
+            plugin_path (Path): Path to the plugin file whose name is
+                used to derive the output file names.
+            language (str): BCP 47-style language code
+                (e.g. ``"english"``).
+
+        Raises:
+            BethkitClosedError: If the set has been closed.
+            BethkitNativeError: If any write fails.
+        """
+
+        lib = _ffi.load_lib()
+        if (
+            lib.bethkit_localization_set_write(
+                self.__check_open(),
+                _ffi.enc(plugin_path),
+                _ffi.senc(language),
+            )
+            != 0
+        ):
+            _ffi.raise_last_error(lib)
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            str: Developer-friendly representation of the set.
+        """
+
+        return "<LocalizationSet>"

bethkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: bethkit
+Version: 1.0.0
+Summary: Python bindings for bethkit — a Bethesda plugin and archive toolkit
+Project-URL: Homepage, https://moddingforge.com/
+Project-URL: Repository, https://github.com/Modding-Forge/bethkit.py
+Author-email: Modding Forge <info@moddingforge.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ba2,bethesda,bsa,esm,esp,fallout,modding,skyrim
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bethkit.py
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python)](https://www.python.org) [![PyPI](https://img.shields.io/pypi/v/bethkit?logo=pypi&logoColor=white)](https://pypi.org/project/bethkit/)
+
+Python bindings for [bethkit](https://github.com/Modding-Forge/bethkit) - a fast Rust library for reading and writing Bethesda game plugin and archive files. `bethkit.py` wraps the `bethkit_ffi` C ABI via `ctypes`; no compiler or build tools required.
+
+## Features
+
+- **Plugin reading** - open `.esp`/`.esm`/`.esl` files by path or from in-memory bytes; iterate groups and records; look up records by FormID or EditorID; inspect sub-records
+- **Plugin writing** - build new plugins from scratch with `PluginWriter`, `WritableGroup`, and `WritableRecord`
+- **BSA / BA2 archives** - open and extract entries from BSA (TES4/SSE) and BA2 (GNRL/DX10) archives; write new archives with `BsaWriter`, `Ba2GnrlWriter`, and `Ba2Dx10Writer`
+- **String tables** - read, edit, and write `.STRINGS`/`.DLSTRINGS`/`.ILSTRINGS` localisation files; apply translation sets with `LocalizationSet`
+- **Schema** - decode sub-records into typed `FieldValue` variants (integers, floats, FormIDs, enums with resolved names, flags, structs, arrays) via `RecordView` and `SchemaRegistry`
+- **Load-order utilities** - `LoadOrder`, `GlobalFormId`, and `PluginCache` for winning-override lookups and EditorID search across multiple plugins
+
+## Requirements
+
+| Requirement  | Version  |
+| ------------ | -------- |
+| Python       | ≥ 3.10  |
+| pydantic     | ≥ 2.0   |
+| bethkit\_ffi | matching |
+
+Place `bethkit_ffi.dll` (Windows), `libbethkit_ffi.so` (Linux), or `libbethkit_ffi.dylib` (macOS) next to the package, or set the `BETHKIT_LIB` environment variable to the full path of the library.
+
+## Installation
+
+```sh
+uv add bethkit
+```
+
+or
+
+```sh
+pip install bethkit
+```
+
+## Quick Start
+
+### Reading a plugin
+
+```python
+from pathlib import Path
+from bethkit import Plugin, Game
+
+with Plugin.open(Path("Ordinator - Perks of Skyrim.esp"), Game.SKYRIM_SE) as plugin:
+    print("Masters:", plugin.masters)
+    print("Kind:", plugin.kind)
+
+    for group in plugin:
+        for child in group:
+            if hasattr(child, "form_id"):
+                print(f"  0x{child.form_id:08X}  {child.editor_id}")
+```
+
+### Building a plugin from scratch
+
+```python
+from pathlib import Path
+from bethkit import Game, PluginWriter, WritableGroup, WritableRecord
+
+with PluginWriter(Game.SKYRIM_SE) as writer:
+    with WritableGroup.new(b"NPC_") as group:
+        rec = WritableRecord.new(b"NPC_", form_id=0x000D62)
+        rec.add_subrecord(b"EDID", b"MyNPC\x00")
+        group.add_record(rec)
+        writer.add_group(group)
+    writer.write_to_file(Path("MyMod.esp"))
+```
+
+### Extracting from an archive
+
+```python
+from pathlib import Path
+from bethkit import Archive
+
+with Archive.open(Path("Skyrim - Meshes.bsa")) as arc:
+    data = arc.extract("meshes/actors/character/character assets/skeleton.nif")
+    if data:
+        Path("skeleton.nif").write_bytes(data)
+```
+
+### Load-order and FormID resolution
+
+```python
+from pathlib import Path
+from bethkit import Game, Plugin, PluginCache, PluginKind, LoadOrder
+
+lo = LoadOrder()
+lo.push("Skyrim.esm", PluginKind.FULL)
+lo.push("MyMod.esp", PluginKind.FULL)
+
+cache = PluginCache()
+cache.add("Skyrim.esm", Plugin.open(Path("Skyrim.esm"), Game.SKYRIM_SE))
+
+hit = cache.find_by_editor_id("ArmorIronCuirass")
+if hit:
+    print(hit.global_form_id)   # Skyrim.esm:0x012E49
+    print(hit.record.editor_id)
+```
+
+## Development
+
+```sh
+git clone https://github.com/Modding-Forge/bethkit.py
+cd bethkit.py
+uv sync --extra dev
+uv run pytest
+```
+
+Linting and type-checking:
+
+```sh
+uv tool run ruff check src/ tests/
+uv tool run pyright src/ tests/
+```
+
+## Related projects
+
+- [bethkit](https://github.com/Modding-Forge/bethkit) - the underlying Rust library; `bethkit.py` wraps its C ABI
+- [SSE-Auto-Translator](https://github.com/Modding-Forge/SSE-Auto-Translator) - uses `bethkit.py` to patch localised strings
+
+## License
+
+Apache-2.0 - see [LICENSE](LICENSE).

bethkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+bethkit/__init__.py,sha256=T6x3LQzo8hV1KcHIoXckWqWxNAgqhFuewcYLqS6zmik,2440
+bethkit/_error.py,sha256=-7fHK_bNxlQTXW-9W6a8b2_6df_mF9vUAwy4PTKsCTU,2498
+bethkit/enums.py,sha256=6yhMv13mCuEenz3hoXNGNFny8JUvvYdLr0CuNg3LSZs,3059
+bethkit/load_order.py,sha256=6S3W-GKGvxPm_7UpnV2aOsynRLMJvmVyljifizvHp9g,5550
+bethkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bethkit/_ffi/__init__.py,sha256=Wzsh11GwBnOX8ryruuJg2bTMVL-UdgMhidsEuQdlips,905
+bethkit/_ffi/_loader.py,sha256=ehI8DwiUJwDNDPPEj4ewrKu-kbiGbZH_enbuIHiieNc,18508
+bethkit/_ffi/_types.py,sha256=hHPTH8ADrh2-RMwhyGzT0MpZCRZdHCA4L-Ispm1R9ZI,3052
+bethkit/archive/__init__.py,sha256=i41QKSXbSoExxnjO33hu89fj9UKJpyWj6e4iu3fi1Ac,352
+bethkit/archive/archive.py,sha256=4qJkOPKrNOoj6rY_NnbVmg9aMchVhr91hnCZB604I7k,19135
+bethkit/plugin/__init__.py,sha256=XrNzsbXdGYEJ8EUCa143gHX-Vl8KIADgAoqZx4dAZYo,499
+bethkit/plugin/cache.py,sha256=b-KWKeDf26iVVBtlwzu4_zC-6pb6iv4jrETYMgTcU4k,7423
+bethkit/plugin/plugin.py,sha256=C0rPNF5nDABt9KEIafcvYU_XdovX6s2_u1_d0h8jARY,22439
+bethkit/plugin/writer.py,sha256=nkZAitR-AvVRnDIwnVS6nNrWWtUmgrj-7HSnI55lkQA,14571
+bethkit/schema/__init__.py,sha256=XZKez2ApXIaioy6pd3AAZoCujjlf_8QIjrFXOxYEOQc,456
+bethkit/schema/schema.py,sha256=q8MksAXDdfH7hvw6GNOI8u5aqxBDb3YCoOU5wA0z50E,13238
+bethkit/strings/__init__.py,sha256=NK6bWOX2txWMWfd3vE9aT7JYhT-AfNaNVttS-u2OvPs,273
+bethkit/strings/strings.py,sha256=8PMaC_W0m4y20xhMdeFd5upDmnfIHuJ4jYzjdhKXsd0,14409
+bethkit-1.0.0.dist-info/METADATA,sha256=vhR7PuHBFzAyG5LlYSrwFMIqVa1gAniFwYHmAsqPogQ,5383
+bethkit-1.0.0.dist-info/WHEEL,sha256=y3FWwPRFPfRewdaamNJ2TA-_oj6MYMwqJXYgc-1N3nY,93
+bethkit-1.0.0.dist-info/licenses/LICENSE,sha256=zpP_oxrFUIxGN0S1gDhVrmhk75Fytp74iwyh4dXNwGs,11617
+bethkit-1.0.0.dist-info/RECORD,,

bethkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-win_amd64