unitytk 0.0.1__tar.gz → 0.0.2__tar.gz

{unitytk-0.0.1 → unitytk-0.0.2}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 m3trik@live.com
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 m3trik@live.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

unitytk-0.0.2/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include docs/README.md
+include pyproject.toml
+recursive-include unitytk *.ui *.gif *.png *.json *.txt *.cs *.hlsl *.shader

unitytk-0.0.2/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: unitytk
+Version: 0.0.2
+Summary: A modular Python toolkit for Unity interaction.
+Author-email: Ryan Simpson <m3trik@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/unitytk/unitytk
+Project-URL: Repository, https://github.com/unitytk/unitytk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pythontk>=0.7.71
+Dynamic: license-file
+
+[![Tests](https://img.shields.io/badge/Tests-111%20passed-brightgreen.svg)](../test/)
+
+# unitytk
+
+A modular Python toolkit for Unity interaction — Python-side helpers for preparing DCC exports for Unity, plus the C# editor scripts they pair with (shipped under [`templates/`](../unitytk/templates/README.md)).
+
+## More
+
+- [`templates/README.md`](../unitytk/templates/README.md) — the C# template catalog (opacity, audio events, shot metadata, lightmaps), the FBX user-property import contract, and deployment (`TemplateDeployer.deploy_all`)
+- [mayatk's `data_nodes.md`](../../mayatk/docs/data_nodes.md) — the DCC-side producer spec these templates consume (`data_export` carrier + channel registry)
+- [`CHANGELOG.md`](../CHANGELOG.md) — notable changes
+- [`CLAUDE.md`](../CLAUDE.md) — contributor / agent conventions

unitytk-0.0.2/docs/README.md

@@ -0,0 +1,12 @@
+[![Tests](https://img.shields.io/badge/Tests-111%20passed-brightgreen.svg)](../test/)
+
+# unitytk
+
+A modular Python toolkit for Unity interaction — Python-side helpers for preparing DCC exports for Unity, plus the C# editor scripts they pair with (shipped under [`templates/`](../unitytk/templates/README.md)).
+
+## More
+
+- [`templates/README.md`](../unitytk/templates/README.md) — the C# template catalog (opacity, audio events, shot metadata, lightmaps), the FBX user-property import contract, and deployment (`TemplateDeployer.deploy_all`)
+- [mayatk's `data_nodes.md`](../../mayatk/docs/data_nodes.md) — the DCC-side producer spec these templates consume (`data_export` carrier + channel registry)
+- [`CHANGELOG.md`](../CHANGELOG.md) — notable changes
+- [`CLAUDE.md`](../CLAUDE.md) — contributor / agent conventions

{unitytk-0.0.1 → unitytk-0.0.2}/pyproject.toml

@@ -1,32 +1,32 @@
-[build-system]
-requires = ["setuptools>=61.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "unitytk"
-dynamic = ["version", "readme"]
-description = "A modular Python toolkit for Unity interaction."
-authors = [{name = "Ryan Simpson", email = "m3trik@outlook.com"}]
-license = {text = "MIT"}
-requires-python = ">=3.9"
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-]
-dependencies = ["pythontk>=0.7.71"]
-
-[project.urls]
-Homepage = "https://github.com/unitytk/unitytk"
-Repository = "https://github.com/unitytk/unitytk"
-
-[tool.setuptools.dynamic]
-version = {attr = "unitytk.__version__"}
-readme = {file = "docs/README.md", content-type = "text/markdown"}
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["unitytk*"]
-
-[tool.setuptools.package-data]
-"*" = ["*.ui", "*.json", "*.txt", "*.md", "*.cs"]
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unitytk"
+dynamic = ["version", "readme"]
+description = "A modular Python toolkit for Unity interaction."
+authors = [{name = "Ryan Simpson", email = "m3trik@outlook.com"}]
+license = {text = "MIT"}
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = ["pythontk>=0.7.71"]
+
+[project.urls]
+Homepage = "https://github.com/unitytk/unitytk"
+Repository = "https://github.com/unitytk/unitytk"
+
+[tool.setuptools.dynamic]
+version = {attr = "unitytk.__version__"}
+readme = {file = "docs/README.md", content-type = "text/markdown"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["unitytk*"]
+
+[tool.setuptools.package-data]
+"*" = ["*.ui", "*.json", "*.txt", "*.md", "*.cs", "*.hlsl", "*.shader"]

{unitytk-0.0.1 → unitytk-0.0.2}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+

unitytk-0.0.2/test/test_asset_delivery.py

@@ -0,0 +1,343 @@
+# !/usr/bin/python
+# coding=utf-8
+"""Tests for unitytk.CopyToAssetsDeliverer -- copy-to-Assets hand-off Strategy (no DCC)."""
+import os
+import shutil
+import tempfile
+import unittest
+
+from pythontk.core_utils.app_handoff import HandoffRequest, Payload
+from unitytk.asset_delivery import (
+    CopyToAssetsDeliverer,
+    FileToUnityBridge,
+    CopyToAssetsDeliverer,
+)
+
+
+class _Logger:
+    """Minimal logger capturing messages by level."""
+
+    def __init__(self):
+        self.errors = []
+        self.warnings = []
+        self.infos = []
+
+    def error(self, m):
+        self.errors.append(m)
+
+    def warning(self, m):
+        self.warnings.append(m)
+
+    def info(self, m):
+        self.infos.append(m)
+
+
+class _StubBridge:
+    """A bare host with the contract the deliverer reads off the bridge."""
+
+    def __init__(self, project_path=None):
+        self.project_path = project_path
+        self.logger = _Logger()
+
+
+def _request(params=None):
+    return HandoffRequest(template="import", mode="copy_to_assets", params=params or {})
+
+
+def _payload(fbx, default_name="Export"):
+    return Payload(primary=fbx, extras={"default_asset_name": default_name})
+
+
+class SanitizeTest(unittest.TestCase):
+    def test_strips_invalid_and_paths(self):
+        self.assertEqual(CopyToAssetsDeliverer.sanitize_asset_name("my/model:v2"), "my_model_v2")
+
+    def test_collapses_and_trims(self):
+        self.assertEqual(CopyToAssetsDeliverer.sanitize_asset_name("  a   b  "), "a b")
+
+    def test_empty_falls_back(self):
+        self.assertEqual(CopyToAssetsDeliverer.sanitize_asset_name("///"), "Export")
+        self.assertEqual(CopyToAssetsDeliverer.sanitize_asset_name(""), "Export")
+
+
+class DeliveryTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+        self.project = os.path.join(self.tmp, "MyUnityProj")
+        os.makedirs(os.path.join(self.project, "Assets"))
+        # A fake exported FBX.
+        self.fbx = os.path.join(self.tmp, "export.fbx")
+        with open(self.fbx, "wb") as fh:
+            fh.write(b"FBX-BYTES")
+        self.deliverer = CopyToAssetsDeliverer()
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def _deliver(self, params, default_name="Export", project=None):
+        bridge = _StubBridge(project_path=project or self.project)
+        result = self.deliverer.deliver(
+            bridge, _payload(self.fbx, default_name), _request(params)
+        )
+        return bridge, result
+
+    def test_preflight_rejects_non_project(self):
+        bridge = _StubBridge(project_path=os.path.join(self.tmp, "not_a_project"))
+        self.assertFalse(self.deliverer.preflight(bridge, _request()))
+        self.assertTrue(bridge.logger.errors)
+
+    def test_preflight_accepts_project(self):
+        bridge = _StubBridge(project_path=self.project)
+        self.assertTrue(self.deliverer.preflight(bridge, _request()))
+
+    def test_deliver_copies_into_assets_subdir(self):
+        _bridge, result = self._deliver(
+            {"ASSETS_SUBDIR": "Models"}, default_name="Robot"
+        )
+        self.assertIsNotNone(result)
+        dest = result["asset"]
+        self.assertEqual(
+            dest, os.path.join(self.project, "Assets", "Models", "Robot.fbx")
+        )
+        self.assertTrue(os.path.isfile(dest))
+        self.assertEqual(open(dest, "rb").read(), b"FBX-BYTES")
+        self.assertFalse(result["launched"])
+
+    def test_deliver_uses_default_subdir_and_asset_name(self):
+        _bridge, result = self._deliver({}, default_name="Cube")
+        self.assertEqual(
+            result["asset"],
+            os.path.join(self.project, "Assets", "Imported", "Cube.fbx"),
+        )
+
+    def test_explicit_asset_name_overrides_and_sanitizes(self):
+        _bridge, result = self._deliver({"ASSET_NAME": "Hero/Mesh:01"}, default_name="Cube")
+        self.assertEqual(os.path.basename(result["asset"]), "Hero_Mesh_01.fbx")
+
+    def test_launch_mode_open_invokes_windowed_launch(self):
+        # Patch the deliverer's launch hook to avoid spawning a real editor.
+        bridge = _StubBridge(project_path=self.project)
+        called = {}
+
+        def _fake_launch(b, params=None, *, batch_mode=False):
+            called["project"] = b.project_path
+            called["batch"] = batch_mode
+            return True
+
+        self.deliverer._launch_editor = staticmethod(_fake_launch)
+        result = self.deliverer.deliver(
+            bridge, _payload(self.fbx, "Cube"), _request({"LAUNCH_MODE": "open"})
+        )
+        self.assertTrue(result["launched"])
+        self.assertEqual(called["project"], self.project)
+        self.assertFalse(called["batch"])  # "open" -> windowed, not batch
+
+    def test_launch_mode_headless_runs_batch(self):
+        bridge = _StubBridge(project_path=self.project)
+        called = {}
+
+        def _fake_launch(b, params=None, *, batch_mode=False):
+            called["batch"] = batch_mode
+            return True
+
+        self.deliverer._launch_editor = staticmethod(_fake_launch)
+        result = self.deliverer.deliver(
+            bridge, _payload(self.fbx, "Cube"), _request({"LAUNCH_MODE": "headless"})
+        )
+        self.assertTrue(result["launched"])
+        self.assertTrue(called["batch"])  # "headless" -> batch mode
+
+    def test_no_launch_mode_does_not_launch(self):
+        bridge = _StubBridge(project_path=self.project)
+        called = {"hit": False}
+
+        def _fake_launch(b, params=None, *, batch_mode=False):
+            called["hit"] = True
+            return True
+
+        self.deliverer._launch_editor = staticmethod(_fake_launch)
+        result = self.deliverer.deliver(
+            bridge, _payload(self.fbx, "Cube"), _request({})
+        )
+        self.assertFalse(result["launched"])
+        self.assertFalse(called["hit"])
+
+    def test_legacy_launch_editor_bool_is_ignored(self):
+        """The legacy boolean LAUNCH_EDITOR is no longer honored — only LAUNCH_MODE
+        drives launching, so an old key resolves to no-launch."""
+        bridge = _StubBridge(project_path=self.project)
+        called = {"hit": False}
+
+        def _fake_launch(b, params=None, *, batch_mode=False):
+            called["hit"] = True
+            return True
+
+        self.deliverer._launch_editor = staticmethod(_fake_launch)
+        result = self.deliverer.deliver(
+            bridge, _payload(self.fbx, "Cube"), _request({"LAUNCH_EDITOR": True})
+        )
+        self.assertFalse(result["launched"])
+        self.assertFalse(called["hit"])
+
+    def test_launch_passes_unity_version_to_launcher(self):
+        """A chosen UNITY_VERSION is forwarded to the launcher's executable_path."""
+        import unitytk.asset_delivery as ad
+
+        bridge = _StubBridge(project_path=self.project)
+        seen = {}
+
+        class _FakeLauncher:
+            def __init__(self, executable_path=None, project_path=None):
+                seen["executable_path"] = executable_path
+                seen["project_path"] = project_path
+                self.executable_path = executable_path or "auto.exe"
+
+            def launch_editor(self, batch_mode=False, extra_args=None, detached=True):
+                seen["launched"] = True
+                seen["batch_mode"] = batch_mode
+                return object()
+
+        orig = ad.CopyToAssetsDeliverer._launch_editor
+        # Patch UnityLauncher inside the real hook (deferred import target).
+        import unitytk.launcher as launcher_mod
+        real = launcher_mod.UnityLauncher
+        launcher_mod.UnityLauncher = _FakeLauncher
+        try:
+            self.deliverer._launch_editor = orig  # use the real hook
+            self.deliverer.deliver(
+                bridge,
+                _payload(self.fbx, "Cube"),
+                _request({"LAUNCH_MODE": "open", "UNITY_VERSION": "2022.3.4f1"}),
+            )
+        finally:
+            launcher_mod.UnityLauncher = real
+        self.assertEqual(seen["executable_path"], "2022.3.4f1")
+        self.assertEqual(seen["project_path"], self.project)
+        self.assertTrue(seen.get("launched"))
+
+    def test_deliver_rejects_missing_assets(self):
+        _bridge, result = self._deliver({}, project=os.path.join(self.tmp, "nope"))
+        self.assertIsNone(result)
+
+    def test_subdir_supports_nested_and_either_separator(self):
+        for raw in ("Models/Hero", r"Models\Hero", "Models//Hero/", "/Models/Hero"):
+            _bridge, result = self._deliver({"ASSETS_SUBDIR": raw}, default_name="Cube")
+            self.assertEqual(
+                result["asset"],
+                os.path.join(self.project, "Assets", "Models", "Hero", "Cube.fbx"),
+                f"raw={raw!r}",
+            )
+            self.assertEqual(result["subdir"], "Models/Hero")
+
+    def test_subdir_cannot_escape_assets_via_traversal(self):
+        # '..' components are dropped -> stays inside Assets/ (no path traversal).
+        _bridge, result = self._deliver(
+            {"ASSETS_SUBDIR": "../../Plugins"}, default_name="Cube"
+        )
+        dest = result["asset"]
+        self.assertEqual(
+            dest, os.path.join(self.project, "Assets", "Plugins", "Cube.fbx")
+        )
+        # The resolved path is genuinely under Assets/ (defensive realpath check).
+        assets = os.path.realpath(os.path.join(self.project, "Assets"))
+        self.assertTrue(os.path.realpath(dest).startswith(assets))
+
+    def test_subdir_cannot_escape_assets_via_drive_letter(self):
+        # A Windows drive designator in a component ('C:/Models', or the
+        # drive-relative 'C:Models') must not make os.path.join produce a path
+        # that escapes Assets/ (which then also crashed os.path.relpath cross-drive).
+        for raw, expected_sub in (
+            ("C:/Models", os.path.join("Assets", "Models")),
+            ("C:Models", os.path.join("Assets", "Models")),
+            ("C:", "Assets"),
+            (r"C:\Models\Hero", os.path.join("Assets", "Models", "Hero")),
+        ):
+            _bridge, result = self._deliver({"ASSETS_SUBDIR": raw}, default_name="Cube")
+            self.assertIsNotNone(result, f"raw={raw!r}")
+            dest = result["asset"]
+            self.assertEqual(
+                dest,
+                os.path.join(self.project, expected_sub, "Cube.fbx"),
+                f"raw={raw!r}",
+            )
+            # Genuinely under Assets/ (no drive escape).
+            assets = os.path.realpath(os.path.join(self.project, "Assets"))
+            self.assertTrue(
+                os.path.realpath(dest).startswith(assets), f"raw={raw!r}"
+            )
+
+    def test_explicit_subdir_reducing_to_nothing_drops_into_assets_root(self):
+        for raw in (".", "/", "../.."):
+            _bridge, result = self._deliver({"ASSETS_SUBDIR": raw}, default_name="Cube")
+            self.assertEqual(
+                result["asset"], os.path.join(self.project, "Assets", "Cube.fbx"),
+                f"raw={raw!r}",
+            )
+            self.assertEqual(result["subdir"], "")
+
+    def test_blank_subdir_falls_back_to_default(self):
+        for raw in ("", "   "):
+            _bridge, result = self._deliver({"ASSETS_SUBDIR": raw}, default_name="Cube")
+            self.assertEqual(
+                result["asset"],
+                os.path.join(self.project, "Assets", "Imported", "Cube.fbx"),
+                f"raw={raw!r}",
+            )
+
+
+class FileToUnityBridgeTest(unittest.TestCase):
+    """The DCC-free file-driven bridge: pick a model file -> copy into Assets/."""
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+        self.project = os.path.join(self.tmp, "MyUnityProj")
+        os.makedirs(os.path.join(self.project, "Assets"))
+        self.fbx = os.path.join(self.tmp, "robot.fbx")
+        with open(self.fbx, "wb") as fh:
+            fh.write(b"FBX-BYTES")
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_send_copies_file_into_assets(self):
+        bridge = FileToUnityBridge(project_path=self.project)
+        result = bridge.send(model_path=self.fbx, params={"ASSETS_SUBDIR": "Models"})
+        self.assertIsNotNone(result)
+        dest = os.path.join(self.project, "Assets", "Models", "robot.fbx")
+        self.assertEqual(result["asset"], dest)
+        self.assertTrue(os.path.isfile(dest))
+        self.assertFalse(result["launched"])
+
+    def test_send_default_asset_name_is_file_stem(self):
+        bridge = FileToUnityBridge(project_path=self.project)
+        result = bridge.send(model_path=self.fbx, params={})
+        self.assertEqual(
+            result["asset"],
+            os.path.join(self.project, "Assets", "Imported", "robot.fbx"),
+        )
+
+    def test_send_preserves_non_fbx_extension(self):
+        obj = os.path.join(self.tmp, "scan.obj")
+        with open(obj, "wb") as fh:
+            fh.write(b"OBJ")
+        bridge = FileToUnityBridge(project_path=self.project)
+        result = bridge.send(model_path=obj, params={})
+        self.assertEqual(os.path.basename(result["asset"]), "scan.obj")
+
+    def test_send_missing_file_returns_none(self):
+        bridge = FileToUnityBridge(project_path=self.project)
+        self.assertIsNone(bridge.send(model_path=os.path.join(self.tmp, "nope.fbx")))
+
+    def test_send_not_a_project_returns_none(self):
+        bridge = FileToUnityBridge(project_path=os.path.join(self.tmp, "not_a_proj"))
+        self.assertIsNone(bridge.send(model_path=self.fbx))
+
+    def test_list_template_modes_matches_deliverer(self):
+        bridge = FileToUnityBridge()
+        self.assertEqual(
+            bridge.list_template_modes(), list(CopyToAssetsDeliverer.DELIVERY_MODES)
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()