PyREUser3 0.1.0__tar.gz → 0.2.0__tar.gz

{pyreuser3-0.1.0 → pyreuser3-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.1.0
+Version: 0.2.0
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT

{pyreuser3-0.1.0 → pyreuser3-0.2.0}/PyREUser3.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyREUser3
-Version: 0.1.0
+Version: 0.2.0
 Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
 Author: Egg Targaryen
 License-Expression: MIT

{pyreuser3-0.1.0 → pyreuser3-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PyREUser3"
-version = "0.1.0"
+version = "0.2.0"
 description = "Pure Python tools for converting RE Engine .user.3 files to and from JSON."
 readme = "README.md"
 requires-python = ">=3.9"

{pyreuser3-0.1.0 → pyreuser3-0.2.0}/pyreuser3/__init__.py

@@ -1,8 +1,7 @@
-"""RE User3 JSON 工具包的公开导出入口。
+"""Expose the stable public API while keeping expensive converter modules lazy.
 
-较重的转换模块会依赖 Rich 等命令行显示库。这里使用惰性导出，
-让 `pyreuser3-web --help` 和 `python -m pyreuser3.web --help` 这类轻量入口
-不需要提前加载完整导出器或封包器。
+The package-level __getattr__ hook avoids importing Rich and binary conversion code for
+lightweight operations such as version checks and Web UI help output.
 """
 
 from __future__ import annotations
@@ -40,25 +39,19 @@ _EXPORT_MODULES = {
 
 
 def __getattr__(name: str) -> Any:
-    """首次访问公开名称时再惰性导入对应模块。
+    """Resolve a lazily exported package attribute on first access.
 
-    PEP 562 的模块级 ``__getattr__`` 钩子：仅当访问 ``__all__`` 中声明的名称
-    且该名称尚未缓存到模块全局时才会触发，从而实现按需导入的惰性导出。
+    Args:
+        name (str): Symbolic schema, class, field, or enum name being stored or looked up.
 
-    参数：
-        name (str): 正在访问的属性名（通常是 ``__all__`` 中的某个公开名称）。
-
-    返回：
-        Any: 解析并缓存后的目标对象（类、函数或常量）。
-
-    异常：
-        AttributeError: 当 ``name`` 不在惰性导出表 ``_EXPORT_MODULES`` 中时抛出。
+    Returns:
+        Any: Normalized value ready for the next parse, export, post-processing, or pack step.
     """
     module_name = _EXPORT_MODULES.get(name)
     if module_name is None:
         raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-    # 导入后把结果缓存到 globals，后续访问不再触发 __getattr__。
+    # Cache the resolved object in globals so later attribute access bypasses __getattr__ and avoids another import.
     module = import_module(module_name, __name__)
     value = getattr(module, name)
     globals()[name] = value

{pyreuser3-0.1.0 → pyreuser3-0.2.0}/pyreuser3/__main__.py

@@ -1,4 +1,5 @@
-"""Run the PyREUser3 CLI with ``python -m pyreuser3``."""
+"""Provide helpers for __main__.
+"""
 
 from __future__ import annotations
 

pyreuser3-0.2.0/pyreuser3/api.py

@@ -0,0 +1,411 @@
+"""Provide the REUser3Converter facade used by downstream Python code.
+
+The facade hides exporter and packer construction details, keeps schema and il2cpp dump
+configuration in one place, and offers convenient single-file, batch, and patch-and-
+repack workflows.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import re
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from .core import RSZ_MAGIC, USR_MAGIC
+from .export import User3Exporter
+from .pack import User3Packer
+
+# Preserve the exported JSON structure so external scripts and hand-edited files remain
+# compatible across workflows.
+JsonTree = Any
+# Patch callbacks may accept only the parsed data or both the data and source
+# path; returning None means the callback mutated in place.
+PatchCallback = Callable[..., Optional[JsonTree]]
+
+
+class REUser3Converter:
+    """Store shared conversion configuration and expose high-level export, parse, patch, and
+    pack workflows.
+    """
+
+    def __init__(
+        self,
+        schema_path: str | Path | None = None,
+        il2cpp_dump_path: str | Path | None = None,
+        tree_depth: int | str = "auto",
+        schema_dir: str | Path | None = None,
+        user_magic: int = USR_MAGIC,
+        rsz_magic: int = RSZ_MAGIC,
+    ) -> None:
+        """Initialize REUser3Converter with validated configuration and state.
+
+        Args:
+            schema_path (str | Path | None): Explicit RE_RSZ schema JSON file path.
+            il2cpp_dump_path (str | Path | None): Path to il2cpp_dump.json for enum metadata.
+            tree_depth (int | str): Requested reference-tree expansion depth or auto mode.
+            schema_dir (str | Path | None): Compatibility schema argument that must resolve to a
+            schema JSON file.
+            user_magic (int): Expected magic value for the outer .user.3 container header.
+            rsz_magic (int): Expected magic value for embedded RSZ blocks.
+
+        Returns:
+            None. The method performs its documented side effect in place and raises on invalid input.
+
+        Raises:
+            TypeError: The caller supplied a value of an unsupported type.
+        """
+        # Accept the legacy schema_dir alias from older callers, but normalize all internal state to schema_path.
+        if schema_path is None:
+            schema_path = schema_dir
+        if schema_path is None:
+            raise TypeError("schema_path is required")
+        self.schema_path = Path(schema_path)
+        self.il2cpp_dump_path = Path(il2cpp_dump_path) if il2cpp_dump_path else None
+        self.tree_depth = tree_depth
+        self.user_magic = int(user_magic)
+        self.rsz_magic = int(rsz_magic)
+
+    def export_directory(
+        self,
+        user3_root: str | Path,
+        output_root: str | Path,
+        exclude_regexes: list[str] | None = None,
+    ) -> dict[str, int]:
+        """Export every selected .user.3 file under a directory or single-file root.
+
+        Args:
+            user3_root (str | Path): Source .user.3 file or directory root.
+            output_root (str | Path): Directory where generated output is written.
+            exclude_regexes (list[str] | None): Regular expressions used to skip matching
+            relative paths.
+
+        Returns:
+            dict[str, int]: Counters describing total, successful, and failed items.
+        """
+        exporter = self._new_exporter(user3_root, output_root, exclude_regexes)
+        return exporter.run()
+
+    def export_file(
+        self,
+        user3_path: str | Path,
+        json_path: str | Path,
+    ) -> Path:
+        """Export one .user.3 file to the requested JSON path.
+
+        Args:
+            user3_path (str | Path): Path to the .user.3 file being parsed, exported, patched, or packed.
+            json_path (str | Path): Path to the JSON document read from or written by this workflow.
+
+        Returns:
+            Path: Concrete filesystem path returned after the read, write, or resolution step finishes.
+        """
+        # Reuse parse_file so single-file and batch exports keep the same parsed JSON shape and metadata handling.
+        # Preserve the exported JSON structure so external scripts and hand-edited files
+        # remain compatible across workflows.
+        tree = self.parse_file(user3_path, round_floats=True)
+        target = Path(json_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        with target.open("w", encoding="utf-8") as f:
+            json.dump(tree, f, ensure_ascii=False, indent=2)
+        return target
+
+    def parse_file(self, user3_path: str | Path, round_floats: bool = True) -> JsonTree:
+        """Parse one .user.3 file into the compact exported JSON tree.
+
+        Args:
+            user3_path (str | Path): Path to the .user.3 file being parsed, exported, patched, or packed.
+            round_floats (bool): Whether exported floats should be rounded to four decimal places for readability.
+
+        Returns:
+            JsonTree: JSON-compatible tree used by export, editing, or packing workflows.
+        """
+        exporter = self._new_exporter(user3_path, Path.cwd(), [])
+        # Build enum lookup and context metadata in memory; single-file parsing should not create Enums_Internal.json.
+        # Register enum values through the shared lookup tables so readable labels and
+        # numeric packing stay reversible.
+        self._prepare_exporter_metadata(exporter)
+        tree = exporter._parse_user3(Path(user3_path))
+        tree = exporter._postprocess_enum_nodes(tree)
+        tree = exporter._finalize_export_tree(tree)
+        if round_floats:
+            return exporter._round_export_floats(tree)
+        return tree
+
+    def parse_pack_file(self, user3_path: str | Path) -> JsonTree:
+        """Parse one .user.3 file into the full instance-table JSON used for stable repacking.
+
+        Args:
+            user3_path (str | Path): Path to the .user.3 file being parsed, exported, patched, or packed.
+
+        Returns:
+            JsonTree: JSON-compatible tree used by export, editing, or packing workflows.
+        """
+        exporter = self._new_exporter(user3_path, Path.cwd(), [])
+        self._prepare_exporter_metadata(exporter)
+        return exporter._parse_user3_pack(Path(user3_path))
+
+    def pack_directory(
+        self,
+        json_root: str | Path,
+        output_root: str | Path,
+        exclude_regexes: list[str] | None = None,
+    ) -> dict[str, int]:
+        """Pack every selected JSON file under a directory or single-file root.
+
+        Args:
+            json_root (str | Path): JSON file or directory root to process.
+            output_root (str | Path): Directory where generated output is written.
+            exclude_regexes (list[str] | None): Regular expressions used to skip matching
+            relative paths.
+
+        Returns:
+            dict[str, int]: Counters describing total, successful, and failed items.
+        """
+        packer = self._new_packer(output_root)
+        return packer.pack_directory(json_root, output_root, exclude_regexes)
+
+    def pack_file(self, json_path: str | Path, user3_path: str | Path) -> Path:
+        """Pack one JSON document to the requested .user.3 path.
+
+        Args:
+            json_path (str | Path): Path to the JSON document read from or written by this workflow.
+            user3_path (str | Path): Path to the .user.3 file being parsed, exported, patched, or packed.
+
+        Returns:
+            Path: Concrete filesystem path returned after the read, write, or resolution step finishes.
+        """
+        packer = self._new_packer(Path(user3_path).parent)
+        return packer.pack_json_file(json_path, user3_path)
+
+    def pack(self, data: Any) -> bytes:
+        """Encode an in-memory JSON tree as .user.3 bytes.
+
+        Args:
+            data (Any): JSON tree or binary payload consumed by this conversion step.
+
+        Returns:
+            bytes: Encoded binary data ready to write to disk.
+        """
+        return self._new_packer(None).pack(data)
+
+    def patch_file(
+        self,
+        user3_path: str | Path,
+        output_path: str | Path,
+        callback: PatchCallback,
+    ) -> Path:
+        """Patch one .user.3 file through a callback and write the packed result.
+
+        Args:
+            user3_path (str | Path): Path to the .user.3 file being parsed, exported, patched, or packed.
+            output_path (str | Path): Destination path where the generated file is written.
+            callback (PatchCallback): User callback that may inspect or modify parsed JSON.
+
+        Returns:
+            Path: Concrete filesystem path returned after the read, write, or resolution step finishes.
+        """
+        source = Path(user3_path)
+        # Preserve instance numbering and reference identity; RSZ object links depend on
+        # these indexes remaining stable.
+        data = self.parse_pack_file(source)
+        modified = self._run_callback(callback, data, source)
+        if modified is None:
+            modified = data
+        target = Path(output_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(self.pack(modified))
+        return target
+
+    def patch_directory(
+        self,
+        user3_root: str | Path,
+        output_root: str | Path,
+        callback: PatchCallback,
+        include_regexes: list[str] | None = None,
+        exclude_regexes: list[str] | None = None,
+    ) -> dict[str, int]:
+        """Patch every selected .user.3 file under a root directory.
+
+        Args:
+            user3_root (str | Path): Source .user.3 file or directory root.
+            output_root (str | Path): Directory where generated output is written.
+            callback (PatchCallback): User callback that may inspect or modify parsed JSON.
+            include_regexes (list[str] | None): Regular expressions used to include matching
+            relative paths.
+            exclude_regexes (list[str] | None): Regular expressions used to skip matching
+            relative paths.
+
+        Returns:
+            dict[str, int]: Counters describing total, successful, and failed items.
+        """
+        source_root = Path(user3_root)
+        target_root = Path(output_root)
+        files = self._discover_user3_files(source_root)
+        include_patterns = [re.compile(p) for p in (include_regexes or [])]
+        exclude_patterns = [re.compile(p) for p in (exclude_regexes or [])]
+
+        total = success = failed = skipped = 0
+        for file_path in files:
+            # Resolve and validate paths at the boundary so later code never guesses
+            # relative to a surprising working directory.
+            rel = (
+                file_path.name
+                if source_root.is_file()
+                else file_path.relative_to(source_root).as_posix()
+            )
+            if include_patterns and not any(
+                pattern.search(rel) for pattern in include_patterns
+            ):
+                skipped += 1
+                continue
+            if any(pattern.search(rel) for pattern in exclude_patterns):
+                skipped += 1
+                continue
+
+            total += 1
+            output_path = target_root / (
+                file_path.name
+                if source_root.is_file()
+                else file_path.relative_to(source_root)
+            )
+            try:
+                # Treat each file independently so one malformed resource is reported
+                # but does not stop the rest of the batch.
+                self.patch_file(file_path, output_path, callback)
+                success += 1
+            except Exception:
+                failed += 1
+        return {
+            "total": total,
+            "success": success,
+            "failed": failed,
+            "skipped": skipped,
+        }
+
+    def _new_exporter(
+        self,
+        user3_root: str | Path,
+        output_root: str | Path,
+        exclude_regexes: list[str] | None,
+    ) -> User3Exporter:
+        """Create an exporter with this facade's schema, enum metadata, and magic values.
+
+        Args:
+            user3_root (str | Path): Source .user.3 file or directory root.
+            output_root (str | Path): Directory where generated output is written.
+            exclude_regexes (list[str] | None): Regular expressions used to skip matching
+            relative paths.
+
+        Returns:
+            User3Exporter: Configured object or normalized value returned for the caller to use directly.
+
+        Raises:
+            FileNotFoundError: A required file or directory was missing.
+        """
+        if self.il2cpp_dump_path is None:
+            raise FileNotFoundError("il2cpp_dump_path is required for exporting JSON")
+        return User3Exporter(
+            user3_root=user3_root,
+            schema_dir=self.schema_path,
+            output_root=output_root,
+            tree_depth=self.tree_depth,
+            exclude_regexes=exclude_regexes or [],
+            il2cpp_dump_path=self.il2cpp_dump_path,
+            user_magic=self.user_magic,
+            rsz_magic=self.rsz_magic,
+        )
+
+    def _new_packer(self, output_root: str | Path | None) -> User3Packer:
+        """Create a packer with this facade's schema, enum metadata, and magic values.
+
+        Args:
+            output_root (str | Path | None): Directory where generated output is written.
+
+        Returns:
+            User3Packer: Configured object or normalized value returned for the caller to use directly.
+        """
+        return User3Packer(
+            schema_dir=self.schema_path,
+            il2cpp_dump_path=self.il2cpp_dump_path,
+            output_root=output_root,
+            user_magic=self.user_magic,
+            rsz_magic=self.rsz_magic,
+        )
+
+    def _prepare_exporter_metadata(self, exporter: User3Exporter) -> None:
+        """Prepare exporter metadata.
+
+        Args:
+            exporter (User3Exporter): Exporter instance whose metadata caches are being prepared.
+
+        Returns:
+            None. The method performs its documented side effect in place and raises on invalid input.
+
+        Raises:
+            FileNotFoundError: A required file or directory was missing.
+        """
+        if self.il2cpp_dump_path is None or not self.il2cpp_dump_path.is_file():
+            raise FileNotFoundError("il2cpp_dump_path is required for parsing JSON")
+        with self.il2cpp_dump_path.open("r", encoding="utf-8") as f:
+            il2cpp_dump = json.load(f)
+        # Batch export writes Enums_Internal.json for downstream tools; direct
+        # parsing keeps the same lookup only in memory.
+        # Keep the generated metadata attached to the exporter so field parsing can
+        # format enum names consistently.
+        enums_internal = exporter.export_enums_internal(il2cpp_dump)
+        exporter.enum_lookup = exporter._build_enum_lookup_from_enums_internal(
+            enums_internal
+        )
+        enum_context = exporter.export_enum_context_internal(il2cpp_dump)
+        exporter._apply_enum_context(enum_context)
+        exporter._ensure_enum_lookup()
+
+    @staticmethod
+    def _discover_user3_files(user3_root: Path) -> list[Path]:
+        """Discover user3 files.
+
+        Args:
+            user3_root (Path): Source .user.3 file or directory root.
+
+        Returns:
+            list[Path]: Filesystem paths selected for batch processing after suffix and exclusion checks.
+
+        Raises:
+            FileNotFoundError: A required file or directory was missing.
+        """
+        if user3_root.is_file():
+            return [user3_root]
+        if not user3_root.is_dir():
+            raise FileNotFoundError(f"user3 root not found: {user3_root}")
+        files = sorted(user3_root.rglob("*.user.3"))
+        if not files:
+            raise FileNotFoundError(f"no *.user.3 found under: {user3_root}")
+        return files
+
+    @staticmethod
+    def _run_callback(
+        callback: PatchCallback, data: JsonTree, source_path: Path
+    ) -> JsonTree | None:
+        """Run callback.
+
+        Args:
+            callback (PatchCallback): User callback that may inspect or modify parsed JSON.
+            data (JsonTree): JSON tree or binary payload consumed by this conversion step.
+            source_path (Path): Original source path associated with a patch callback or output
+            path.
+
+        Returns:
+            JsonTree | None: Configured object or normalized value returned for the caller to use directly.
+        """
+        try:
+            param_count = len(inspect.signature(callback).parameters)
+        except (TypeError, ValueError):
+            # Some callables do not expose inspectable signatures, so fall back to
+            # the full callback signature when introspection fails.
+            param_count = 2
+        if param_count <= 1:
+            return callback(data)
+        return callback(data, source_path)

{pyreuser3-0.1.0 → pyreuser3-0.2.0}/pyreuser3/cli.py

@@ -1,4 +1,8 @@
-"""Command line interface for the PyREUser3 package."""
+"""Define the pyreuser3 command line interface for exporting .user.3 files to JSON and packing JSON back to .user.3.
+
+Heavy converter imports stay inside subcommand handlers so help and version output
+remain lightweight.
+"""
 
 from __future__ import annotations
 
@@ -8,18 +12,27 @@ from importlib.metadata import PackageNotFoundError, version
 from typing import Sequence
 
 from .core import RSZ_MAGIC, USR_MAGIC
-from .export import User3Exporter
-from .pack import User3Packer
-from .rich_ui import get_console
 
 
 def parse_int_arg(value: str) -> int:
-    """Parse decimal or 0x-prefixed integer command line values."""
+    """Parse a decimal or hexadecimal integer command line value.
+
+    Args:
+        value (str): Value to parse, normalize, compare, or serialize.
+
+    Returns:
+        int: Integer decoded from input data, metadata, or the command-line option being parsed.
+    """
     return int(value, 0)
 
 
 def package_version() -> str:
-    """Return installed package version, with a source-tree fallback."""
+    """Return the installed package version with a source-tree fallback.
+
+
+    Returns:
+        str: Normalized or formatted text.
+    """
     try:
         return version("PyREUser3")
     except PackageNotFoundError:
@@ -27,7 +40,14 @@ def package_version() -> str:
 
 
 def normalize_tree_depth(value: str) -> int | str:
-    """Normalize tree depth argument to an integer or the string 'auto'."""
+    """Normalize a tree-depth CLI value to auto or a non-negative integer.
+
+    Args:
+        value (str): Value to parse, normalize, compare, or serialize.
+
+    Returns:
+        int | str: Parsed integer value or the literal auto mode.
+    """
     text = value.strip().lower()
     if text == "auto":
         return "auto"
@@ -38,7 +58,14 @@ def normalize_tree_depth(value: str) -> int | str:
 
 
 def add_magic_args(parser: argparse.ArgumentParser) -> None:
-    """Add common .user.3 and RSZ magic options to a subparser."""
+    """Add shared USR and RSZ magic number options to a parser.
+
+    Args:
+        parser (argparse.ArgumentParser): Argument parser being populated with CLI subcommands and shared options.
+
+    Returns:
+        None. The method performs its documented side effect in place and raises on invalid input.
+    """
     parser.add_argument(
         "--user-magic",
         type=parse_int_arg,
@@ -54,7 +81,12 @@ def add_magic_args(parser: argparse.ArgumentParser) -> None:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    """Build the top-level CLI parser."""
+    """Build the CLI parser and subcommands.
+
+
+    Returns:
+        argparse.ArgumentParser: Configured argument parser for the command-line interface.
+    """
     parser = argparse.ArgumentParser(
         prog="pyreuser3",
         description="Convert RE Engine .user.3 files to JSON and pack them back.",
@@ -158,7 +190,17 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def run_export(args: argparse.Namespace) -> int:
-    """Run the export subcommand."""
+    """Run the CLI export subcommand.
+
+    Args:
+        args (argparse.Namespace): Parsed command-line namespace for the selected CLI command.
+
+    Returns:
+        int: Integer decoded from input data, metadata, or the command-line option being parsed.
+    """
+    from .export import User3Exporter
+    from .rich_ui import get_console
+
     console = get_console()
     console.log("Exporting .user.3 files to JSON...")
     exporter = User3Exporter(
@@ -177,7 +219,17 @@ def run_export(args: argparse.Namespace) -> int:
 
 
 def run_pack(args: argparse.Namespace) -> int:
-    """Run the pack subcommand."""
+    """Run the CLI pack subcommand.
+
+    Args:
+        args (argparse.Namespace): Parsed command-line namespace for the selected CLI command.
+
+    Returns:
+        int: Integer decoded from input data, metadata, or the command-line option being parsed.
+    """
+    from .pack import User3Packer
+    from .rich_ui import get_console
+
     console = get_console()
     console.log("Packing JSON files to .user.3...")
     packer = User3Packer(
@@ -197,7 +249,14 @@ def run_pack(args: argparse.Namespace) -> int:
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    """CLI entry point used by the pyreuser3 console script."""
+    """Run the command entry point.
+
+    Args:
+        argv (Sequence[str] | None): Optional argument list; None means use the process command line.
+
+    Returns:
+        int: Integer decoded from input data, metadata, or the command-line option being parsed.
+    """
     parser = build_parser()
     args = parser.parse_args(argv)
     return int(args.func(args))