PyREUser3 0.2.0__tar.gz → 0.4.0__tar.gz

pyreuser3-0.4.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: PyREUser3
+Version: 0.4.0
+Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
+Author: Egg Targaryen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dzxrly/PyREUser3
+Project-URL: Repository, https://github.com/dzxrly/PyREUser3
+Project-URL: Issues, https://github.com/dzxrly/PyREUser3/issues
+Keywords: RE Engine,user.3,JSON,modding,RSZ
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: File Formats
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# PyREUser3
+
+PyREUser3 is a pure Python package for converting RE Engine `.user.3` database files to JSON and packing compatible JSON back to `.user.3`.
+
+## Installation
+
+```bash
+pip install pyreuser3
+```
+
+## What Is Included
+
+- `.user.3 -> JSON` export.
+- `JSON -> .user.3` packing.
+- A reusable Python API through `REUser3Converter`.
+- CLI commands through `pyreuser3`.
+- A local `.user.3` export Web UI through `pyreuser3-web`.
+
+The published package intentionally does not include game resources, dumped game data, RE_RSZ templates,
+`il2cpp_dump.json`, or repository-specific helper scripts. You need to provide data files that match the target game and
+version.
+
+## Requirements
+
+- Python 3.9 or newer.
+- A RE_RSZ schema JSON file for the target game/version.
+- An `il2cpp_dump.json` file when exporting readable enum labels.
+- One or more unpacked `.user.3` files.
+
+## Usage
+
+Usage details may change as the package evolves. For the latest command-line and Python API examples, read the GitHub README:
+
+https://github.com/dzxrly/PyREUser3#readme
+
+## Links
+
+- Homepage: https://github.com/dzxrly/PyREUser3
+- Issues: https://github.com/dzxrly/PyREUser3/issues
+- License: MIT License

pyreuser3-0.4.0/PyREUser3.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: PyREUser3
+Version: 0.4.0
+Summary: Pure Python tools for converting RE Engine .user.3 files to and from JSON.
+Author: Egg Targaryen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dzxrly/PyREUser3
+Project-URL: Repository, https://github.com/dzxrly/PyREUser3
+Project-URL: Issues, https://github.com/dzxrly/PyREUser3/issues
+Keywords: RE Engine,user.3,JSON,modding,RSZ
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: File Formats
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# PyREUser3
+
+PyREUser3 is a pure Python package for converting RE Engine `.user.3` database files to JSON and packing compatible JSON back to `.user.3`.
+
+## Installation
+
+```bash
+pip install pyreuser3
+```
+
+## What Is Included
+
+- `.user.3 -> JSON` export.
+- `JSON -> .user.3` packing.
+- A reusable Python API through `REUser3Converter`.
+- CLI commands through `pyreuser3`.
+- A local `.user.3` export Web UI through `pyreuser3-web`.
+
+The published package intentionally does not include game resources, dumped game data, RE_RSZ templates,
+`il2cpp_dump.json`, or repository-specific helper scripts. You need to provide data files that match the target game and
+version.
+
+## Requirements
+
+- Python 3.9 or newer.
+- A RE_RSZ schema JSON file for the target game/version.
+- An `il2cpp_dump.json` file when exporting readable enum labels.
+- One or more unpacked `.user.3` files.
+
+## Usage
+
+Usage details may change as the package evolves. For the latest command-line and Python API examples, read the GitHub README:
+
+https://github.com/dzxrly/PyREUser3#readme
+
+## Links
+
+- Homepage: https://github.com/dzxrly/PyREUser3
+- Issues: https://github.com/dzxrly/PyREUser3/issues
+- License: MIT License

{pyreuser3-0.2.0 → pyreuser3-0.4.0}/PyREUser3.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ PyREUser3.egg-info/dependency_links.txt
 PyREUser3.egg-info/entry_points.txt
 PyREUser3.egg-info/requires.txt
 PyREUser3.egg-info/top_level.txt
+docs/PYPI.md
 docs/README.zh-CN.md
 pyreuser3/__init__.py
 pyreuser3/__main__.py
@@ -37,4 +38,6 @@ pyreuser3/web/page.py
 pyreuser3/web/picker.py
 pyreuser3/web/runners.py
 pyreuser3/web/server.py
-pyreuser3/web/settings.py
+pyreuser3/web/settings.py
+tests/test_enum_binary.py
+tests/test_export_enums.py

{pyreuser3-0.2.0 → pyreuser3-0.4.0}/README.md

@@ -1,6 +1,15 @@
-# PyREUser3
+<h1 align="center">PyREUser3</h1>
 
-English | [简体中文](./docs/README.zh-CN.md)
+<p align="center">
+  English | <a href="https://github.com/dzxrly/PyREUser3/blob/main/docs/README.zh-CN.md">简体中文</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/PyREUser3/"><img alt="PyPI Project" src="https://img.shields.io/badge/PyPI-PyREUser3-blue"></a>
+  <a href="https://pypi.org/project/PyREUser3/"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/PyREUser3"></a>
+  <a href="https://pepy.tech/project/PyREUser3"><img alt="Downloads" src="https://static.pepy.tech/badge/PyREUser3"></a>
+  <a href="https://github.com/dzxrly/PyREUser3/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/PyREUser3"></a>
+</p>
 
 PyREUser3 is a pure Python package for converting RE Engine `.user.3` database files to JSON and packing compatible JSON back to `.user.3`.
 
@@ -24,7 +33,8 @@ from pyreuser3 import REUser3Converter
 - CLI commands through `pyreuser3`.
 - A local `.user.3` export Web UI through `pyreuser3-web`.
 
-This PyPI package intentionally does not include game resources, dumped game data, RE_RSZ templates, `il2cpp_dump.json`, `.msg.23` conversion tools, or repository-specific helper scripts.
+This PyPI package intentionally does not include game resources, dumped game data, RE_RSZ templates, `il2cpp_dump.json`,
+or repository-specific helper scripts.
 
 ## Requirements
 
@@ -63,7 +73,7 @@ Start the local `.user.3` export Web UI:
 pyreuser3-web --port 8765
 ```
 
-The Web UI only handles `.user.3` export. It does not pack files and does not provide `.msg.23` conversion.
+The Web UI only handles `.user.3` export. It does not pack files.
 
 ## Python API
 
@@ -86,6 +96,22 @@ converter.pack_file(
 )
 ```
 
+Convert a `.user.3` file to an in-memory JSON-compatible Python object without writing a JSON file:
+
+```python
+readable_data = converter.user3_to_json(
+    "input/OtomonData.user.3",
+    json_format="readable",
+)
+
+repack_data = converter.user3_to_json(
+    "input/OtomonData.user.3",
+    json_format="repack",
+)
+```
+
+Use `json_format="readable"` for the same shape produced by `export_file()`, or `json_format="repack"` for the full instance-table document accepted by `pack()`.
+
 For stable patch-and-repack workflows, use `patch_file()` or `parse_pack_file()`:
 
 ```python

pyreuser3-0.4.0/docs/PYPI.md

@@ -0,0 +1,40 @@
+# PyREUser3
+
+PyREUser3 is a pure Python package for converting RE Engine `.user.3` database files to JSON and packing compatible JSON back to `.user.3`.
+
+## Installation
+
+```bash
+pip install pyreuser3
+```
+
+## What Is Included
+
+- `.user.3 -> JSON` export.
+- `JSON -> .user.3` packing.
+- A reusable Python API through `REUser3Converter`.
+- CLI commands through `pyreuser3`.
+- A local `.user.3` export Web UI through `pyreuser3-web`.
+
+The published package intentionally does not include game resources, dumped game data, RE_RSZ templates,
+`il2cpp_dump.json`, or repository-specific helper scripts. You need to provide data files that match the target game and
+version.
+
+## Requirements
+
+- Python 3.9 or newer.
+- A RE_RSZ schema JSON file for the target game/version.
+- An `il2cpp_dump.json` file when exporting readable enum labels.
+- One or more unpacked `.user.3` files.
+
+## Usage
+
+Usage details may change as the package evolves. For the latest command-line and Python API examples, read the GitHub README:
+
+https://github.com/dzxrly/PyREUser3#readme
+
+## Links
+
+- Homepage: https://github.com/dzxrly/PyREUser3
+- Issues: https://github.com/dzxrly/PyREUser3/issues
+- License: MIT License

{pyreuser3-0.2.0 → pyreuser3-0.4.0}/docs/README.zh-CN.md

@@ -1,6 +1,15 @@
-# PyREUser3
+<h1 align="center">PyREUser3</h1>
 
-[English](../README.md) | 简体中文
+<p align="center">
+  <a href="https://github.com/dzxrly/PyREUser3/blob/main/README.md">English</a> | 简体中文
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/PyREUser3/"><img alt="PyPI 项目" src="https://img.shields.io/badge/PyPI-PyREUser3-blue"></a>
+  <a href="https://pypi.org/project/PyREUser3/"><img alt="PyPI 版本" src="https://img.shields.io/pypi/v/PyREUser3"></a>
+  <a href="https://pepy.tech/project/PyREUser3"><img alt="下载量" src="https://static.pepy.tech/badge/PyREUser3"></a>
+  <a href="https://github.com/dzxrly/PyREUser3/blob/main/LICENSE"><img alt="许可证" src="https://img.shields.io/pypi/l/PyREUser3"></a>
+</p>
 
 PyREUser3 是一个纯 Python 包，用于在 RE Engine 的 `.user.3` 数据库文件和 JSON 之间进行双向转换。
 
@@ -26,7 +35,7 @@ PyREUser3 当前提供：
 - `pyreuser3` 命令行工具；
 - `pyreuser3-web` 本地 Web 导出界面。
 
-PyPI 包不会包含游戏资源、游戏 dump、RE_RSZ 模板、`il2cpp_dump.json`、`.msg.23` 转换工具或特定仓库脚本。调用方需要自己准备与目标游戏版本匹配的数据文件。
+PyPI 包不会包含游戏资源、游戏 dump、RE_RSZ 模板、`il2cpp_dump.json`、或特定仓库脚本。调用方需要自己准备与目标游戏版本匹配的数据文件。
 
 ## 环境要求
 
@@ -90,7 +99,7 @@ pyreuser3-web --port 8765
 http://127.0.0.1:8765/
 ```
 
-Web UI 只提供 `.user.3` 导出，不提供 JSON 封包，也不提供 `.msg.23` 转换。
+Web UI 只提供 `.user.3` 导出，不提供 JSON 封包。
 
 ## Python API
 
@@ -115,6 +124,22 @@ converter.pack_file(
 )
 ```
 
+不写入 JSON 文件，直接把 `.user.3` 转成内存中的 JSON 兼容 Python 对象：
+
+```python
+readable_data = converter.user3_to_json(
+    "input/OtomonData.user.3",
+    json_format="readable",
+)
+
+repack_data = converter.user3_to_json(
+    "input/OtomonData.user.3",
+    json_format="repack",
+)
+```
+
+使用 `json_format="readable"` 时返回与 `export_file()` 一致的可读导出结构；使用 `json_format="repack"` 时返回可传给 `pack()` 的完整实例表结构。
+
 批量处理目录：
 
 ```python

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

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

{pyreuser3-0.2.0 → pyreuser3-0.4.0}/pyreuser3/api.py

@@ -11,7 +11,7 @@ import inspect
 import json
 import re
 from pathlib import Path
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Literal, Optional
 
 from .core import RSZ_MAGIC, USR_MAGIC
 from .export import User3Exporter
@@ -20,6 +20,7 @@ from .pack import User3Packer
 # Preserve the exported JSON structure so external scripts and hand-edited files remain
 # compatible across workflows.
 JsonTree = Any
+JsonFormat = Literal["readable", "repack"]
 # 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]]
@@ -104,7 +105,11 @@ class REUser3Converter:
         # 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)
+        tree = self.user3_to_json(
+            user3_path,
+            json_format="readable",
+            round_floats=True,
+        )
         target = Path(json_path)
         target.parent.mkdir(parents=True, exist_ok=True)
 
@@ -112,6 +117,37 @@ class REUser3Converter:
             json.dump(tree, f, ensure_ascii=False, indent=2)
         return target
 
+    def user3_to_json(
+        self,
+        user3_path: str | Path,
+        json_format: JsonFormat = "readable",
+        round_floats: bool = True,
+    ) -> JsonTree:
+        """Convert one .user.3 file to an in-memory JSON-compatible tree.
+
+        Args:
+            user3_path (str | Path): Path to the .user.3 file being parsed.
+            json_format (JsonFormat): Return "readable" for the same shape written by
+            export_file(), or "repack" for the full instance-table document accepted by
+            pack().
+            round_floats (bool): Whether readable-format floats should be rounded to four
+            decimal places.
+
+        Returns:
+            JsonTree: JSON-compatible Python data. The readable format preserves the
+            existing export shape; the repack format returns a dictionary with pack
+            metadata and instance tables.
+
+        Raises:
+            ValueError: json_format was not "readable" or "repack".
+        """
+        normalized_format = self._normalize_json_format(json_format)
+        if normalized_format == "readable":
+            return self.parse_file(user3_path, round_floats=round_floats)
+        if normalized_format == "repack":
+            return self.parse_pack_file(user3_path)
+        raise ValueError("json_format must be 'readable' or 'repack'")
+
     def parse_file(self, user3_path: str | Path, round_floats: bool = True) -> JsonTree:
         """Parse one .user.3 file into the compact exported JSON tree.
 
@@ -147,6 +183,23 @@ class REUser3Converter:
         self._prepare_exporter_metadata(exporter)
         return exporter._parse_user3_pack(Path(user3_path))
 
+    @staticmethod
+    def _normalize_json_format(json_format: str) -> str:
+        """Normalize the public in-memory JSON format selector.
+
+        Args:
+            json_format (str): Requested JSON output shape.
+
+        Returns:
+            str: Normalized format name.
+
+        Raises:
+            TypeError: The caller supplied a non-string format selector.
+        """
+        if not isinstance(json_format, str):
+            raise TypeError("json_format must be a string")
+        return json_format.strip().lower().replace("-", "_")
+
     def pack_directory(
         self,
         json_root: str | Path,
@@ -349,17 +402,16 @@ class REUser3Converter:
         """
         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)
+        enums_internal, enum_context = exporter.export_il2cpp_metadata_from_path(
+            self.il2cpp_dump_path
+        )
         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()
 

{pyreuser3-0.2.0 → pyreuser3-0.4.0}/pyreuser3/core.py

@@ -28,6 +28,41 @@ HEX32_RE = re.compile(r"^[0-9a-fA-F]{32}$")
 # packing stay reversible.
 ENUM_UNUSED_KEY = "value__"
 
+ENUM_UNDERLYING_TYPE_MAP = {
+    "byte": "U8",
+    "system.byte": "U8",
+    "u8": "U8",
+    "uint8": "U8",
+    "sbyte": "S8",
+    "system.sbyte": "S8",
+    "s8": "S8",
+    "int8": "S8",
+    "short": "S16",
+    "system.int16": "S16",
+    "int16": "S16",
+    "s16": "S16",
+    "ushort": "U16",
+    "system.uint16": "U16",
+    "uint16": "U16",
+    "u16": "U16",
+    "int": "S32",
+    "system.int32": "S32",
+    "int32": "S32",
+    "s32": "S32",
+    "uint": "U32",
+    "system.uint32": "U32",
+    "uint32": "U32",
+    "u32": "U32",
+    "long": "S64",
+    "system.int64": "S64",
+    "int64": "S64",
+    "s64": "S64",
+    "ulong": "U64",
+    "system.uint64": "U64",
+    "uint64": "U64",
+    "u64": "U64",
+}
+
 
 class ParseError(RuntimeError):
     """Signal expected binary-format problems separately from programming errors.
@@ -52,6 +87,38 @@ def align(value: int, alignment: int) -> int:
     return (value + (alignment - 1)) & ~(alignment - 1)
 
 
+def normalize_enum_storage_type(type_name: Any) -> str | None:
+    """Normalize an il2cpp enum underlying type name to an RSZ scalar storage code."""
+    if not isinstance(type_name, str):
+        return None
+    text = type_name.strip()
+    if not text:
+        return None
+    return ENUM_UNDERLYING_TYPE_MAP.get(text.lower())
+
+
+def enum_storage_type_from_size(size: int) -> str:
+    """Choose a conservative enum storage type from a schema-declared byte size."""
+    if size == 1:
+        return "U8"
+    if size == 2:
+        return "U16"
+    if size == 8:
+        return "S64"
+    return "S32"
+
+
+def enum_storage_size(storage_type: str) -> int:
+    """Return the byte width for a normalized enum storage type."""
+    if storage_type in {"S8", "U8"}:
+        return 1
+    if storage_type in {"S16", "U16"}:
+        return 2
+    if storage_type in {"S64", "U64"}:
+        return 8
+    return 4
+
+
 def format_guid_text_from_hex32(hex32: str) -> str:
     """Format compact hexadecimal GUID text with canonical separators.
 

pyreuser3-0.4.0/pyreuser3/export/__init__.py

@@ -0,0 +1,27 @@
+"""Expose the public exporter type for the export subpackage.
+
+Implementation details are split across mixins, but callers can import User3Exporter
+from this package directly.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__all__ = ["User3Exporter"]
+
+_EXPORT_MODULES = {
+    "User3Exporter": ".base",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve lazily exported subpackage attributes on first access."""
+    module_name = _EXPORT_MODULES.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module = import_module(module_name, __name__)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value

{pyreuser3-0.2.0 → pyreuser3-0.4.0}/pyreuser3/export/base.py

@@ -88,7 +88,9 @@ class User3Exporter(
         self.serializable_to_fixed: dict[str, str] = {}
         self.generic_container_rules: dict[str, tuple[str, str]] = {}
         self.param_type_default_enum: dict[str, str] = {}
+        self.enum_underlying_types: dict[str, str] = {}
         self.enum_member_to_types: dict[str, list[str]] = {}
+        self._pending_enum_context: dict | None = None
 
     def run(self) -> dict[str, int]:
         """Run the batch exporter and return conversion counters.