bethkit 1.0.0__py3-none-win_amd64.whl

bethkit/__init__.py

@@ -0,0 +1,102 @@
+"""
+Copyright (c) Modding Forge
+
+bethkit — Python bindings for the bethkit Bethesda plugin and archive toolkit.
+
+Place ``bethkit_ffi.dll`` (Windows), ``libbethkit_ffi.so`` (Linux), or
+``libbethkit_ffi.dylib`` (macOS) next to this package, or set the
+``BETHKIT_LIB`` environment variable to the full path of the library before
+importing.
+
+Quick example::
+
+    from bethkit import Plugin, Game
+
+    with Plugin.open(Path("Ordinator - Perks of Skyrim.esp"), Game.SKYRIM_SE) as p:
+        for master in p.masters:
+            print(master)
+        for group in p:
+            for child in group:
+                if hasattr(child, "form_id"):
+                    print(f"0x{child.form_id:08X}", child.editor_id)
+"""
+from __future__ import annotations
+
+from ._error import (
+    BethkitClosedError,
+    BethkitError,
+    BethkitLibraryNotFoundError,
+    BethkitNativeError,
+    BethkitNotFoundError,
+    BethkitOwnershipError,
+)
+from .archive import Archive, ArchiveEntry, Ba2Dx10Writer, Ba2GnrlWriter, BsaWriter
+from .enums import (
+    Ba2Version,
+    BsaVersion,
+    FieldValueKind,
+    Game,
+    PluginKind,
+    StringFileKind,
+)
+from .load_order import GlobalFormId, LoadOrder
+from .plugin import (
+    CacheHit,
+    Group,
+    Plugin,
+    PluginCache,
+    PluginWriter,
+    Record,
+    SubRecord,
+    WritableGroup,
+    WritableRecord,
+)
+from .schema import EnumVal, FlagsVal, NamedField, RecordView, SchemaRegistry, TypedFormId
+from .strings import LocalizationSet, StringTable
+
+__all__ = [
+    # Exceptions
+    "BethkitError",
+    "BethkitLibraryNotFoundError",
+    "BethkitNativeError",
+    "BethkitClosedError",
+    "BethkitOwnershipError",
+    "BethkitNotFoundError",
+    # Enums
+    "Game",
+    "PluginKind",
+    "StringFileKind",
+    "BsaVersion",
+    "Ba2Version",
+    "FieldValueKind",
+    # Plugin reading
+    "Plugin",
+    "Group",
+    "Record",
+    "SubRecord",
+    # Archives
+    "Archive",
+    "ArchiveEntry",
+    "BsaWriter",
+    "Ba2GnrlWriter",
+    "Ba2Dx10Writer",
+    # Schema
+    "SchemaRegistry",
+    "RecordView",
+    "NamedField",
+    "TypedFormId",
+    "EnumVal",
+    "FlagsVal",
+    # Load order & cache
+    "LoadOrder",
+    "GlobalFormId",
+    "PluginCache",
+    "CacheHit",
+    # Strings
+    "StringTable",
+    "LocalizationSet",
+    # Writing
+    "PluginWriter",
+    "WritableGroup",
+    "WritableRecord",
+]

bethkit/_error.py

@@ -0,0 +1,85 @@
+"""
+Copyright (c) Modding Forge
+"""
+from __future__ import annotations
+
+
+class BethkitError(Exception):
+    """
+    Base exception for all bethkit errors.
+
+    All exceptions raised by bethkit.py are subclasses of this class,
+    so callers can catch everything with a single ``except BethkitError``.
+    """
+
+
+class BethkitLibraryNotFoundError(BethkitError):
+    """
+    Raised when the native bethkit shared library cannot be loaded.
+
+    Check that ``bethkit_ffi.dll`` / ``libbethkit_ffi.so`` /
+    ``libbethkit_ffi.dylib`` is placed next to the package directory or
+    that the ``BETHKIT_LIB`` environment variable points to the file.
+    """
+
+
+class BethkitNativeError(BethkitError):
+    """
+    Raised when a native FFI call returns an error code.
+
+    The error message is the text returned by ``bethkit_last_error()``
+    immediately after the failing call, copied before any subsequent
+    FFI call can overwrite the thread-local error buffer.
+
+    Attributes:
+        message (str): Human-readable error text from the native library.
+    """
+
+    message: str
+    """Human-readable error text from the native library."""
+
+    def __init__(self, message: str) -> None:
+        """
+        Args:
+            message (str): Error text returned by the native library.
+        """
+
+        super().__init__(message)
+        self.message = message
+
+    def __repr__(self) -> str:
+        """
+        Returns:
+            str: Developer-friendly representation including the message.
+        """
+
+        return f"BethkitNativeError({self.message!r})"
+
+
+class BethkitClosedError(BethkitError):
+    """
+    Raised when a method is called on an already-closed native handle.
+
+    Once :meth:`close` has been called (or the context manager has
+    exited), the wrapper object is invalid and must not be used.
+    """
+
+
+class BethkitOwnershipError(BethkitError):
+    """
+    Raised when ownership of a handle is transferred more than once.
+
+    After a handle has been moved into a container (e.g.
+    :meth:`~bethkit.PluginCache.add`), the original wrapper is consumed
+    and must not be used again.
+    """
+
+
+class BethkitNotFoundError(BethkitNativeError):
+    """
+    Raised by ``*_required`` convenience methods when a lookup fails.
+
+    Normal lookup methods return ``None`` on not-found; this exception
+    is raised only by the strict ``*_required`` variants that must
+    succeed or fail loudly.
+    """

bethkit/_ffi/__init__.py

@@ -0,0 +1,44 @@
+"""
+Copyright (c) Modding Forge
+
+Internal FFI package — loads the native library and declares ctypes types.
+
+Not part of the public API; import from ``bethkit`` directly.
+"""
+from __future__ import annotations
+
+from ._loader import (
+    copy_and_free_str,
+    enc,
+    last_error,
+    load_lib,
+    raise_last_error,
+    senc,
+)
+from ._types import (
+    BethkitEnumVal,
+    BethkitFieldValue,
+    BethkitFieldValuePayload,
+    BethkitFlagsVal,
+    BethkitGlobalFormId,
+    BethkitNamedField,
+    BethkitSlice,
+    BethkitTypedFormId,
+)
+
+__all__ = [
+    "copy_and_free_str",
+    "enc",
+    "last_error",
+    "load_lib",
+    "raise_last_error",
+    "senc",
+    "BethkitEnumVal",
+    "BethkitFieldValue",
+    "BethkitFieldValuePayload",
+    "BethkitFlagsVal",
+    "BethkitGlobalFormId",
+    "BethkitNamedField",
+    "BethkitSlice",
+    "BethkitTypedFormId",
+]