bethkit 1.0.0__py3-none-win_amd64.whl

bethkit/enums.py

@@ -0,0 +1,139 @@
+"""
+Copyright (c) Modding Forge
+"""
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class Game(IntEnum):
+    """
+    Supported Bethesda game titles.
+
+    These values are passed to the native library to select the correct
+    plugin and archive format for a given game.
+    """
+
+    SKYRIM_SE = 0
+    """Skyrim Special Edition (64-bit, AE/SE)."""
+
+    FALLOUT4 = 1
+    """Fallout 4."""
+
+    SKYRIM = 2
+    """The Elder Scrolls V: Skyrim (Classic, 32-bit)."""
+
+    FALLOUT3 = 3
+    """Fallout 3."""
+
+    FALLOUT_NV = 4
+    """Fallout: New Vegas."""
+
+
+class PluginKind(IntEnum):
+    """
+    Plugin type as declared in the file header.
+    """
+
+    FULL = 0
+    """Standard full plugin (ESP/ESM with a complete load-order slot)."""
+
+    LIGHT = 1
+    """Light plugin (ESL) with a 12-bit FormID range."""
+
+    OVERLAY = 2
+    """Overlay plugin (ESM override) introduced in Starfield."""
+
+
+class StringFileKind(IntEnum):
+    """
+    The three localisation string-file types used by Bethesda games.
+    """
+
+    STRINGS = 0
+    """Plain null-terminated strings (.STRINGS)."""
+
+    DL_STRINGS = 1
+    """Length-prefixed strings (.DLSTRINGS)."""
+
+    IL_STRINGS = 2
+    """Length-prefixed localised strings (.ILSTRINGS)."""
+
+
+class BsaVersion(IntEnum):
+    """
+    BSA (Bethesda Softworks Archive) format version selector.
+    """
+
+    TES3 = 0
+    """Morrowind BSA format."""
+
+    TES4 = 1
+    """Oblivion BSA format."""
+
+    FO3 = 2
+    """Fallout 3 / New Vegas BSA format."""
+
+    SSE = 3
+    """Skyrim Special Edition BSA format."""
+
+
+class Ba2Version(IntEnum):
+    """
+    BA2 (Bethesda Archive 2) format version selector.
+    """
+
+    V1 = 0
+    """Fallout 4 original BA2 version."""
+
+    V7 = 1
+    """Fallout 4 Next-Gen patch BA2 version 7."""
+
+    V8 = 2
+    """Fallout 4 Next-Gen patch BA2 version 8."""
+
+
+class FieldValueKind(IntEnum):
+    """
+    Discriminant tag for the ``BethkitFieldValue`` tagged union.
+
+    Each variant corresponds to a concrete Python type returned by the
+    schema decoding layer.
+    """
+
+    INT = 0
+    """Signed or unsigned integer field, decoded as ``int``."""
+
+    FLOAT = 1
+    """Floating-point field, decoded as ``float``."""
+
+    STR = 2
+    """Zero-terminated string field, decoded as ``str``."""
+
+    FORM_ID = 3
+    """Raw 32-bit FormID, decoded as ``int``."""
+
+    FORM_ID_TYPED = 4
+    """FormID with type constraints, decoded as :class:`TypedFormId`."""
+
+    BYTES = 5
+    """Raw byte slice, decoded as ``bytes``."""
+
+    ENUM = 6
+    """Enumeration field, decoded as :class:`EnumVal`."""
+
+    FLAGS = 7
+    """Bit-flags field, decoded as :class:`FlagsVal`."""
+
+    STRUCT = 8
+    """Inline struct, decoded as ``list[NamedField]``."""
+
+    ARRAY = 9
+    """Repeated field, decoded as ``list[FieldValue]``."""
+
+    LOCALIZED_ID = 10
+    """Localisation string ID, decoded as ``int``."""
+
+    MISSING = 11
+    """Field absent or unknown; value is ``None``."""
+

bethkit/load_order.py

@@ -0,0 +1,198 @@
+"""
+Copyright (c) Modding Forge
+"""
+from __future__ import annotations
+
+import ctypes
+from typing import Optional
+
+from pydantic import BaseModel
+
+from . import _ffi
+from ._error import BethkitClosedError
+from ._ffi import BethkitGlobalFormId
+from .enums import PluginKind
+
+
+class GlobalFormId(BaseModel, frozen=True):
+    """
+    A globally unique FormID consisting of a plugin name and a 24-bit
+    object ID.
+    """
+
+    plugin_name: str
+    """Name of the owning plugin (e.g. ``"Skyrim.esm"``)."""
+
+    object_id: int
+    """24-bit object identifier within *plugin_name*."""
+
+    def __str__(self) -> str:
+        """
+        Return a human-readable representation of this FormID.
+
+        Returns:
+            str: Human-readable ``"PluginName:0xOBJECTID"`` representation.
+        """
+
+        return f"{self.plugin_name}:0x{self.object_id:06X}"
+
+
+class LoadOrder:
+    """
+    An ordered list of plugins that mirrors the active load order.
+
+    Use :meth:`push` to register plugins in load order, then call
+    :meth:`resolve` to translate a local FormID into a
+    :class:`GlobalFormId`.
+
+    Use as a context manager to guarantee that the native handle is
+    freed::
+
+        with LoadOrder() as lo:
+            lo.push("Skyrim.esm", PluginKind.FULL)
+            gfid = lo.resolve(0x00012E49, "Skyrim.esm")
+    """
+
+    __ptr: int
+
+    def __init__(self) -> None:
+        """
+        Raises:
+            BethkitNativeError: If the native load-order object cannot be
+                created.
+        """
+
+        lib = _ffi.load_lib()
+        ptr = lib.bethkit_load_order_new()
+        if not ptr:
+            _ffi.raise_last_error(lib)
+        self.__ptr = ptr
+
+    def __check_open(self) -> int:
+        """
+        Return the native pointer, raising if the handle is already closed.
+
+        Returns:
+            int: Non-zero native pointer.
+
+        Raises:
+            BethkitClosedError: If :meth:`close` has already been called.
+        """
+
+        if not self.__ptr:
+            raise BethkitClosedError(
+                "LoadOrder has already been closed."
+            )
+        return self.__ptr
+
+    def close(self) -> None:
+        """
+        Release the native load-order handle.
+
+        Safe to call multiple times; subsequent calls are no-ops.
+        """
+
+        if self.__ptr:
+            _ffi.load_lib().bethkit_load_order_free(self.__ptr)
+            self.__ptr = 0
+
+    def __enter__(self) -> LoadOrder:
+        """
+        Return *self* for use as a context manager.
+
+        Returns:
+            LoadOrder: This instance.
+        """
+
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Close the load order when exiting the context."""
+
+        self.close()
+
+    def __del__(self) -> None:
+        """Free the native handle on garbage collection."""
+
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def push(self, name: str, kind: PluginKind) -> None:
+        """
+        Append a plugin to the end of the load order.
+
+        Args:
+            name (str): Plugin file name (e.g. ``"Skyrim.esm"``).
+            kind (PluginKind): Whether the plugin is a full, light, or
+                overlay plugin.
+
+        Raises:
+            BethkitClosedError: If this load order has already been closed.
+            BethkitNativeError: If the native call fails.
+        """
+
+        lib = _ffi.load_lib()
+        ptr = self.__check_open()
+        if lib.bethkit_load_order_push(
+            ptr, _ffi.senc(name), int(kind)
+        ) != 0:
+            _ffi.raise_last_error(lib)
+
+    def __len__(self) -> int:
+        """
+        Returns:
+            int: Number of plugins currently in the load order.
+
+        Raises:
+            BethkitClosedError: If this load order has already been closed.
+        """
+
+        return _ffi.load_lib().bethkit_load_order_len(self.__check_open())
+
+    def resolve(self, form_id: int, source_plugin: str) -> GlobalFormId:
+        """
+        Resolve a local FormID to a globally unique :class:`GlobalFormId`.
+
+        Args:
+            form_id (int): The raw 32-bit FormID as stored in a plugin
+                record.
+            source_plugin (str): Name of the plugin that contains the
+                FormID.
+
+        Returns:
+            GlobalFormId: The resolved global FormID.
+
+        Raises:
+            BethkitClosedError: If this load order has already been closed.
+            BethkitNativeError: If *form_id* or *source_plugin* cannot be
+                resolved.
+        """
+
+        lib = _ffi.load_lib()
+        ptr = self.__check_open()
+        out = BethkitGlobalFormId()
+        if (
+            lib.bethkit_load_order_resolve(
+                ptr,
+                form_id,
+                _ffi.senc(source_plugin),
+                ctypes.byref(out),
+            )
+            != 0
+        ):
+            _ffi.raise_last_error(lib)
+        plugin_name_raw: Optional[bytes] = out.plugin_name
+        plugin_name = plugin_name_raw.decode("utf-8") if plugin_name_raw else ""
+        return GlobalFormId(plugin_name=plugin_name, object_id=out.object_id)
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            str: Developer-friendly representation with plugin count.
+        """
+
+        if not self.__ptr:
+            return "<LoadOrder closed>"
+        return f"<LoadOrder len={len(self)}>"

bethkit/plugin/__init__.py

@@ -0,0 +1,22 @@
+"""
+Copyright (c) Modding Forge
+
+Plugin subpackage — reading, writing, and caching Bethesda plugin files.
+"""
+from __future__ import annotations
+
+from .cache import CacheHit, PluginCache
+from .plugin import Group, Plugin, Record, SubRecord
+from .writer import PluginWriter, WritableGroup, WritableRecord
+
+__all__ = [
+    "CacheHit",
+    "Group",
+    "Plugin",
+    "PluginCache",
+    "PluginWriter",
+    "Record",
+    "SubRecord",
+    "WritableGroup",
+    "WritableRecord",
+]

bethkit/plugin/cache.py

@@ -0,0 +1,251 @@
+"""
+Copyright (c) Modding Forge
+"""
+from __future__ import annotations
+
+import ctypes
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+from .. import _ffi
+from .._error import BethkitClosedError, BethkitOwnershipError
+from .._ffi import BethkitGlobalFormId
+from ..load_order import GlobalFormId
+
+
+class CacheHit(BaseModel):
+    """
+    Result of a successful :meth:`PluginCache.find_by_editor_id` lookup.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    record: object
+    """The matched record (borrowed, valid while the cache is open)."""
+
+    global_form_id: GlobalFormId
+    """The resolved global FormID of the matched record."""
+
+
+class PluginCache:
+    """
+    An in-memory cache that indexes records across multiple loaded plugins.
+
+    Add plugins with :meth:`add`, then use :meth:`resolve` or
+    :meth:`find_by_editor_id` to look up records across all loaded
+    plugins.
+
+    Use as a context manager to guarantee that the native handle is
+    freed::
+
+        with PluginCache() as cache:
+            cache.add("Skyrim.esm", plugin)
+            rec = cache.resolve("Skyrim.esm", 0x12E49)
+    """
+
+    __ptr: int
+
+    def __init__(self) -> None:
+        """
+        Raises:
+            BethkitNativeError: If the native cache object cannot be created.
+        """
+
+        lib = _ffi.load_lib()
+        ptr = lib.bethkit_plugin_cache_new()
+        if not ptr:
+            _ffi.raise_last_error(lib)
+        self.__ptr = ptr
+
+    def __check_open(self) -> int:
+        """
+        Return the native pointer, raising if the handle is already closed.
+
+        Returns:
+            int: Non-zero native pointer.
+
+        Raises:
+            BethkitClosedError: If :meth:`close` has already been called.
+        """
+
+        if not self.__ptr:
+            raise BethkitClosedError("PluginCache has already been closed.")
+        return self.__ptr
+
+    def close(self) -> None:
+        """
+        Release the native cache handle.
+
+        Safe to call multiple times; subsequent calls are no-ops.
+        """
+
+        if self.__ptr:
+            _ffi.load_lib().bethkit_plugin_cache_free(self.__ptr)
+            self.__ptr = 0
+
+    def __enter__(self) -> PluginCache:
+        """
+        Return *self* for use as a context manager.
+
+        Returns:
+            PluginCache: This instance.
+        """
+
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Free the cache when exiting the context."""
+
+        self.close()
+
+    def __del__(self) -> None:
+        """Free the native handle on garbage collection."""
+
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def add(self, name: str, plugin: object) -> None:
+        """
+        Transfer a :class:`~bethkit.Plugin` into the cache.
+
+        Ownership of the native plugin handle is transferred to the cache;
+        the :class:`~bethkit.Plugin` wrapper becomes invalid after this call.
+
+        Args:
+            name (str): Plugin file name used as the lookup key
+                (e.g. ``"Skyrim.esm"``).
+            plugin: The plugin to add.  Must be a valid, open
+                :class:`~bethkit.Plugin` instance.
+
+        Raises:
+            BethkitClosedError: If this cache or the plugin is already closed.
+            BethkitOwnershipError: If the plugin handle has already been
+                transferred to another container.
+            BethkitNativeError: If the native call fails.
+            TypeError: If *plugin* is not a ``Plugin`` instance.
+        """
+
+        from .plugin import Plugin
+
+        if not isinstance(plugin, Plugin):
+            raise TypeError(
+                f"plugin must be a Plugin instance, got {type(plugin).__name__!r}"
+            )
+        ptr = self.__check_open()
+        lib = _ffi.load_lib()
+        plugin_ptr: int = plugin._transfer_ptr()
+        if not plugin_ptr:
+            raise BethkitOwnershipError(
+                "Plugin handle has already been transferred or closed."
+            )
+        if lib.bethkit_plugin_cache_add(
+            ptr, _ffi.senc(name), plugin_ptr
+        ) != 0:
+            _ffi.raise_last_error(lib)
+
+    def __len__(self) -> int:
+        """
+        Return the number of plugins currently held in the cache.
+
+        Returns:
+            int: Number of plugins.
+
+        Raises:
+            BethkitClosedError: If this cache has already been closed.
+        """
+
+        return _ffi.load_lib().bethkit_plugin_cache_len(self.__check_open())
+
+    @property
+    def record_count(self) -> int:
+        """
+        Total number of records indexed across all cached plugins.
+
+        Returns:
+            int: Aggregate record count.
+
+        Raises:
+            BethkitClosedError: If this cache has already been closed.
+        """
+
+        return _ffi.load_lib().bethkit_plugin_cache_record_count(
+            self.__check_open()
+        )
+
+    def resolve(
+        self, plugin_name: str, object_id: int
+    ) -> Optional[object]:
+        """
+        Look up a record by its global FormID components.
+
+        Args:
+            plugin_name (str): Name of the owning plugin.
+            object_id (int): 24-bit object ID within that plugin.
+
+        Returns:
+            Optional[Record]: The matching :class:`~bethkit.Record`, or
+            ``None`` if not found.
+
+        Raises:
+            BethkitClosedError: If this cache has already been closed.
+        """
+
+        from .plugin import Record
+
+        lib = _ffi.load_lib()
+        ptr_val = lib.bethkit_plugin_cache_resolve(
+            self.__check_open(), _ffi.senc(plugin_name), object_id
+        )
+        if not ptr_val:
+            return None
+        return Record(ptr_val, self)
+
+    def find_by_editor_id(self, edid: str) -> Optional[CacheHit]:
+        """
+        Search for a record by its EDID (editor ID) string.
+
+        Args:
+            edid (str): The editor ID to search for (e.g. ``"ArmorIron"``).
+
+        Returns:
+            Optional[CacheHit]: A :class:`CacheHit` containing the matched
+            record and its :class:`~bethkit.GlobalFormId`, or ``None`` if
+            not found.
+
+        Raises:
+            BethkitClosedError: If this cache has already been closed.
+        """
+
+        from .plugin import Record
+
+        lib = _ffi.load_lib()
+        out = BethkitGlobalFormId()
+        ptr_val = lib.bethkit_plugin_cache_find_by_editor_id(
+            self.__check_open(), _ffi.senc(edid), ctypes.byref(out)
+        )
+        if not ptr_val:
+            return None
+        plugin_name_raw: Optional[bytes] = out.plugin_name
+        plugin_name = (
+            plugin_name_raw.decode("utf-8") if plugin_name_raw else ""
+        )
+        gfid = GlobalFormId(plugin_name=plugin_name, object_id=out.object_id)
+        return CacheHit(record=Record(ptr_val, self), global_form_id=gfid)
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            str: Developer-friendly representation with plugin and record
+            counts.
+        """
+
+        if not self.__ptr:
+            return "<PluginCache closed>"
+        return (
+            f"<PluginCache plugins={len(self)} records={self.record_count}>"
+        )
+
+