unitytk 0.0.7__tar.gz → 0.0.8__tar.gz

{unitytk-0.0.7/unitytk.egg-info → unitytk-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitytk
-Version: 0.0.7
+Version: 0.0.8
 Summary: A modular Python toolkit for Unity interaction.
 Author-email: Ryan Simpson <m3trik@outlook.com>
 License: MIT
@@ -15,7 +15,7 @@ License-File: LICENSE
 Requires-Dist: pythontk>=0.7.71
 Dynamic: license-file
 
-[![Tests](https://img.shields.io/badge/Tests-124%20passed-brightgreen.svg)](../test/)
+[![Tests](https://img.shields.io/badge/Tests-140%20passed-brightgreen.svg)](../test/)
 
 # unitytk
 

{unitytk-0.0.7 → unitytk-0.0.8}/docs/README.md

@@ -1,4 +1,4 @@
-[![Tests](https://img.shields.io/badge/Tests-124%20passed-brightgreen.svg)](../test/)
+[![Tests](https://img.shields.io/badge/Tests-140%20passed-brightgreen.svg)](../test/)
 
 # unitytk
 

unitytk-0.0.8/test/test_deploy_templates.py

@@ -0,0 +1,412 @@
+# !/usr/bin/python
+# coding=utf-8
+"""Tests for the embedded-UPM-package template deployment (no Unity needed).
+
+The C# controller templates are compile-coupled: every controller calls the
+shared ``ImportGate`` and ``CarrierImport`` classes that only
+``UnitytkSettings.cs`` defines, so a Unity project must hold the *core* plus
+whichever controllers it deploys to compile.  These tests pin that contract on
+the Python side — the only side that can be tested without a licensed Unity
+install — including the per-component selection the DCC panels' script
+checklist drives.
+"""
+import json
+import os
+import shutil
+import tempfile
+import unittest
+from unittest import mock
+
+import unitytk
+from unitytk import TemplateDeployer
+from unitytk.template_deployer import UPM_PACKAGE_NAME
+
+
+class DeployTemplateTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp(prefix="unitytk_deploy_")
+        self.project = os.path.join(self.tmp, "Project")
+        os.makedirs(os.path.join(self.project, "Assets"))
+        self.package = os.path.join(self.project, "Packages", UPM_PACKAGE_NAME)
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_single_template_round_trips(self):
+        dest = os.path.join(self.package, "UnitytkSettings.cs")
+        written = TemplateDeployer.deploy("UnitytkSettings.cs", dest)
+        self.assertTrue(os.path.isfile(written))
+        with open(written, encoding="utf-8") as fh:
+            self.assertIn("class ImportGate", fh.read())
+
+    def test_deploy_package_ships_the_full_coupled_set(self):
+        """Every bundled controller, shader asset, the asmdef, the catalog
+        README and a generated package.json land — no partial deploy."""
+        written = TemplateDeployer.deploy_package(self.project)
+        names = sorted(os.path.basename(p) for p in written)
+        self.assertEqual(
+            names,
+            [
+                "AudioEventController.cs",
+                "EmissiveGroupController.cs",
+                "EmissiveGroups.hlsl",
+                "EmissiveGroupsLit.shader",
+                "LightmapMetadataController.cs",
+                "M3trik.Unitytk.asmdef",
+                "README.md",
+                "RenderOpacityController.cs",
+                "ShadowPlaneController.cs",
+                "ShotMetadataController.cs",
+                "UnitytkSettings.cs",
+                "package.json",
+            ],
+        )
+        for p in written:
+            self.assertTrue(os.path.isfile(p))
+            self.assertGreater(os.path.getsize(p), 0)
+            self.assertTrue(
+                os.path.normcase(p).startswith(os.path.normcase(self.package)),
+                f"{p} escaped the package folder",
+            )
+
+    def test_package_manifest_matches_the_release(self):
+        """package.json carries the UPM identity + this unitytk version, so
+        the Package Manager row is truthful and updates version-bump cleanly."""
+        TemplateDeployer.deploy_package(self.project)
+        with open(os.path.join(self.package, "package.json"), encoding="utf-8") as fh:
+            manifest = json.load(fh)
+        self.assertEqual(manifest["name"], UPM_PACKAGE_NAME)
+        self.assertEqual(manifest["version"], unitytk.__version__)
+        self.assertTrue(manifest["displayName"])
+        self.assertTrue(manifest["unity"])
+
+    def test_deploy_package_rejects_a_non_unity_folder(self):
+        """Guards against scattering the package into a wrong path."""
+        with self.assertRaises(ValueError):
+            TemplateDeployer.deploy_package(self.tmp)
+
+    def test_shader_pair_travels_together(self):
+        """``EmissiveGroupsLit.shader`` includes the .hlsl by RELATIVE path, so
+        deploying one without the other is a shader compile error in Unity."""
+        written = TemplateDeployer.deploy_package(self.project)
+        names = {os.path.basename(p) for p in written}
+        self.assertIn("EmissiveGroups.hlsl", names)
+        shader = os.path.join(self.package, "EmissiveGroupsLit.shader")
+        with open(shader, encoding="utf-8") as fh:
+            self.assertIn('#include "EmissiveGroups.hlsl"', fh.read())
+
+    # ---------------------------------------------------------------- components
+    def test_components_derive_from_the_bundle(self):
+        """One required core plus one optional component per controller, keyed
+        and labelled off the filename — a controller added to the bundle
+        surfaces in the panels' checklist with no registry to update."""
+        comps = TemplateDeployer.components()
+        core = comps[0]
+        self.assertEqual(core.key, "core")
+        self.assertTrue(core.required)
+        self.assertIn("UnitytkSettings.cs", core.files)
+        self.assertIn("M3trik.Unitytk.asmdef", core.files)
+        # No controller hides in core (each is its own opt-in component).
+        self.assertFalse([n for n in core.files if n.endswith("Controller.cs")])
+
+        optional = {c.key: c for c in comps[1:]}
+        self.assertEqual(
+            sorted(optional),
+            [
+                "audio_event",
+                "emissive_group",
+                "lightmap_metadata",
+                "render_opacity",
+                "shadow_plane",
+                "shot_metadata",
+            ],
+        )
+        self.assertEqual(optional["shot_metadata"].label, "Shot Metadata")
+        self.assertFalse(any(c.required for c in optional.values()))
+        # Every bundled file belongs to exactly one component.
+        owned = [n for c in comps for n in c.files]
+        self.assertEqual(sorted(owned), sorted(TemplateDeployer._bundle_names()))
+        self.assertEqual(len(owned), len(set(owned)))
+
+    def test_shader_pair_belongs_to_its_controller(self):
+        """``EmissiveGroupsLit.shader`` includes the .hlsl by RELATIVE path, so
+        the pair travels with the controller that needs it — never on its own,
+        never left behind."""
+        emissive = {c.key: c for c in TemplateDeployer.components()}["emissive_group"]
+        self.assertEqual(
+            sorted(emissive.files),
+            [
+                "EmissiveGroupController.cs",
+                "EmissiveGroups.hlsl",
+                "EmissiveGroupsLit.shader",
+            ],
+        )
+
+    def test_satellite_goes_to_the_longest_matching_controller(self):
+        """Ownership is longest-stem-wins, so adding an `EmissiveController.cs`
+        beside `EmissiveGroupController.cs` can't give the shader pair two
+        owners -- a doubly-owned file deploys twice but survives the first
+        uninstall, desyncing deploy from remove."""
+        bundle = [
+            "EmissiveController.cs",
+            "EmissiveGroupController.cs",
+            "EmissiveGroups.hlsl",
+            "EmissiveGroupsLit.shader",
+            "UnitytkSettings.cs",
+        ]
+        with mock.patch.object(TemplateDeployer, "_bundle_names", staticmethod(lambda: bundle)):
+            comps = {c.key: c for c in TemplateDeployer.components()}
+        self.assertEqual(comps["emissive"].files, ("EmissiveController.cs",))
+        self.assertEqual(
+            comps["emissive_group"].files,
+            (
+                "EmissiveGroupController.cs",
+                "EmissiveGroups.hlsl",
+                "EmissiveGroupsLit.shader",
+            ),
+        )
+        owned = [n for c in comps.values() for n in c.files]
+        self.assertEqual(len(owned), len(set(owned)), "a file has two owners")
+
+    def test_keys_and_labels_survive_an_acronym(self):
+        """Names are split on real word boundaries, so a `UVLayoutController`
+        reads as 'UV Layout' / `uv_layout` rather than 'U V Layout'."""
+        self.assertEqual(TemplateDeployer._component_key("UVLayout"), "uv_layout")
+        self.assertEqual(TemplateDeployer._component_label("UVLayout"), "UV Layout")
+        self.assertEqual(TemplateDeployer._component_key("ShotMetadata"), "shot_metadata")
+
+    def test_selected_deploy_carries_core_and_nothing_else(self):
+        """A checked subset deploys those components + the core they compile
+        against, and leaves the unchecked ones out of the project."""
+        written = TemplateDeployer.deploy_package(self.project, ["audio_event"])
+        names = sorted(os.path.basename(p) for p in written)
+        self.assertEqual(
+            names,
+            [
+                "AudioEventController.cs",
+                "M3trik.Unitytk.asmdef",
+                "README.md",
+                "UnitytkSettings.cs",
+                "package.json",
+            ],
+        )
+
+    def test_selected_deploy_is_additive(self):
+        """Deploying a second component updates in place — it never removes the
+        one already there (Install / Update, not Sync)."""
+        TemplateDeployer.deploy_package(self.project, ["audio_event"])
+        TemplateDeployer.deploy_package(self.project, ["shot_metadata"])
+        present = set(os.listdir(self.package))
+        self.assertIn("AudioEventController.cs", present)
+        self.assertIn("ShotMetadataController.cs", present)
+
+    def test_unknown_component_raises_before_writing(self):
+        """A typo must not silently deploy a smaller set than asked for."""
+        with self.assertRaises(ValueError):
+            TemplateDeployer.deploy_package(self.project, ["audio_events"])
+        self.assertFalse(os.path.isdir(self.package))
+
+    def test_selective_uninstall_keeps_the_rest(self):
+        TemplateDeployer.deploy_package(self.project)
+        removed = TemplateDeployer.uninstall_package(self.project, ["emissive_group"])
+        self.assertEqual(
+            sorted(os.path.basename(p) for p in removed),
+            [
+                "EmissiveGroupController.cs",
+                "EmissiveGroups.hlsl",
+                "EmissiveGroupsLit.shader",
+            ],
+        )
+        present = set(os.listdir(self.package))
+        self.assertNotIn("EmissiveGroupController.cs", present)
+        self.assertIn("AudioEventController.cs", present)
+        self.assertIn("UnitytkSettings.cs", present)
+
+    def test_removing_the_last_component_takes_the_package(self):
+        """Core alone gates nothing — the folder goes with the last controller
+        rather than leaving a settings page for no channels."""
+        TemplateDeployer.deploy_package(self.project, ["audio_event"])
+        TemplateDeployer.uninstall_package(self.project, ["audio_event"])
+        self.assertFalse(os.path.isdir(self.package))
+
+    def test_core_cannot_be_uninstalled_on_its_own(self):
+        TemplateDeployer.deploy_package(self.project)
+        with self.assertRaises(ValueError):
+            TemplateDeployer.uninstall_package(self.project, ["core"])
+        self.assertTrue(os.path.isfile(os.path.join(self.package, "UnitytkSettings.cs")))
+
+    def test_status_reports_not_installed_then_up_to_date(self):
+        """The panels' Status action: absent → installed=False with the full
+        bundle missing; after deploy → current version, nothing missing."""
+        before = TemplateDeployer.status(self.project)
+        self.assertFalse(before["installed"])
+        self.assertFalse(before["up_to_date"])
+        self.assertIn("UnitytkSettings.cs", before["missing"])
+
+        TemplateDeployer.deploy_package(self.project)
+        after = TemplateDeployer.status(self.project)
+        self.assertTrue(after["installed"])
+        self.assertEqual(after["version"], unitytk.__version__)
+        self.assertEqual(after["missing"], [])
+        self.assertTrue(after["up_to_date"])
+
+    def test_status_flags_a_partial_deploy(self):
+        """A deleted file shows in ``missing`` + ``incomplete`` and clears
+        ``up_to_date`` — a component is only valid whole."""
+        TemplateDeployer.deploy_package(self.project)
+        os.remove(os.path.join(self.package, "UnitytkSettings.cs"))
+        info = TemplateDeployer.status(self.project)
+        self.assertEqual(info["missing"], ["UnitytkSettings.cs"])
+        self.assertEqual(info["incomplete"], ["UnitytkSettings.cs"])
+        self.assertFalse(info["up_to_date"])
+
+    def test_status_reports_each_component(self):
+        """The panels' checklist report: deployed components tick, opted-out
+        ones don't, and opting out is NOT a broken install."""
+        TemplateDeployer.deploy_package(self.project, ["audio_event"])
+        info = TemplateDeployer.status(self.project)
+        states = {c["key"]: c["installed"] for c in info["components"]}
+        self.assertTrue(states["core"])
+        self.assertTrue(states["audio_event"])
+        self.assertFalse(states["shot_metadata"])
+        # Not deploying a channel is a choice, not a partial deploy.
+        self.assertEqual(info["incomplete"], [])
+        self.assertTrue(info["up_to_date"])
+        self.assertIn("ShotMetadataController.cs", info["missing"])
+
+    def test_status_flags_a_controller_with_no_core(self):
+        """A controller left without the ImportGate it compiles against is
+        broken even though each file set is individually 'whole'."""
+        TemplateDeployer.deploy_package(self.project, ["audio_event"])
+        for name in ("UnitytkSettings.cs", "M3trik.Unitytk.asmdef", "README.md"):
+            os.remove(os.path.join(self.package, name))
+        info = TemplateDeployer.status(self.project)
+        self.assertIn("UnitytkSettings.cs", info["incomplete"])
+        self.assertFalse(info["up_to_date"])
+
+    # ---------------------------------------------------------------- run_action
+    def test_run_action_status_lists_every_component(self):
+        """One shared report for the Maya / Blender / standalone panels: a
+        header line plus a ticked row per component."""
+        TemplateDeployer.deploy_package(self.project, ["audio_event"])
+        lines = TemplateDeployer.run_action(self.project, "status")
+        self.assertTrue(all(level == "info" for level, _ in lines))
+        text = "\n".join(m for _, m in lines)
+        self.assertIn(f"deployed v{unitytk.__version__}", text)
+        self.assertIn("[x] Audio Event", text)
+        self.assertIn("[ ] Shot Metadata", text)
+
+    def test_run_action_install_and_uninstall_the_checked_set(self):
+        install = TemplateDeployer.run_action(
+            self.project, "install", ["audio_event"]
+        )
+        self.assertEqual([lvl for lvl, _ in install], ["info"])
+        self.assertIn("Audio Event", install[0][1])
+        self.assertTrue(
+            os.path.isfile(os.path.join(self.package, "AudioEventController.cs"))
+        )
+
+        uninstall = TemplateDeployer.run_action(
+            self.project, "uninstall", ["audio_event"]
+        )
+        self.assertEqual([lvl for lvl, _ in uninstall], ["info"])
+        self.assertFalse(os.path.isdir(self.package))
+
+    def test_run_action_rejects_an_empty_selection(self):
+        """Nothing checked is a mistake to report, not a silent no-op (while
+        ``None`` still means the full set)."""
+        for action in ("install", "uninstall"):
+            lines = TemplateDeployer.run_action(self.project, action, [])
+            self.assertEqual([lvl for lvl, _ in lines], ["error"])
+        self.assertFalse(os.path.isdir(self.package))
+
+    def test_run_action_reports_failures_instead_of_raising(self):
+        """The panels log what came back; a bad key or action must not escape
+        as an exception into the DCC's event loop."""
+        for lines in (
+            TemplateDeployer.run_action(self.project, "install", ["nope"]),
+            TemplateDeployer.run_action(self.project, "frobnicate"),
+            TemplateDeployer.run_action(self.tmp, "install"),  # not a Unity project
+        ):
+            self.assertEqual([lvl for lvl, _ in lines], ["error"])
+
+    def test_uninstall_removes_only_our_package(self):
+        """Uninstall deletes the deployed folder (True), no-ops when absent
+        (False), and REFUSES a folder whose package.json is not ours — never
+        delete a directory we merely expected to own."""
+        self.assertFalse(TemplateDeployer.uninstall_package(self.project))
+
+        TemplateDeployer.deploy_package(self.project)
+        self.assertTrue(TemplateDeployer.uninstall_package(self.project))
+        self.assertFalse(os.path.isdir(self.package))
+
+        os.makedirs(self.package)
+        with open(os.path.join(self.package, "package.json"), "w") as fh:
+            json.dump({"name": "com.example.other"}, fh)
+        with self.assertRaises(ValueError):
+            TemplateDeployer.uninstall_package(self.project)
+        self.assertTrue(os.path.isdir(self.package), "foreign folder untouched")
+
+    def test_deploy_package_never_writes_project_config(self):
+        """Per-project settings live in ProjectSettings/UnitytkSettings.json,
+        owned by the project — deploying must not create or clobber them."""
+        TemplateDeployer.deploy_package(self.project)
+        self.assertFalse(
+            os.path.isfile(
+                os.path.join(self.project, "ProjectSettings", "UnitytkSettings.json")
+            )
+        )
+
+    # Every shared class lives in UnitytkSettings.cs; the other controllers
+    # must reference it (definer set / referencer set per class).  Shader
+    # assets (.hlsl/.shader) carry no C# and are excluded.
+    COUPLED_DEFINER = {"UnitytkSettings.cs"}
+    COUPLED_REFERENCERS = {
+        "AudioEventController.cs",
+        "EmissiveGroupController.cs",
+        "LightmapMetadataController.cs",
+        "RenderOpacityController.cs",
+        "ShadowPlaneController.cs",
+        "ShotMetadataController.cs",
+    }
+
+    def _coupling_surface(self, shared_class):
+        """Deploy the set; return ``(definers, referencers)`` of *shared_class*
+        across the C# templates only."""
+        written = [
+            p for p in TemplateDeployer.deploy_package(self.project)
+            if p.endswith(".cs")
+        ]
+        definers, referencers = set(), set()
+        for p in written:
+            with open(p, encoding="utf-8") as fh:
+                text = fh.read()
+            name = os.path.basename(p)
+            if f"class {shared_class}" in text:
+                definers.add(name)
+            elif shared_class in text:
+                referencers.add(name)
+        return definers, referencers
+
+    def test_exactly_one_import_gate_definition_in_the_set(self):
+        """One template defines ``ImportGate``; every other one references it.
+
+        Guards the compile-coupling as templates evolve: a second definition
+        would be a duplicate-class CS error, a dropped reference would mean a
+        controller stopped honoring the channel toggles + FBX allowlist.
+        """
+        definers, referencers = self._coupling_surface("ImportGate")
+        self.assertEqual(definers, self.COUPLED_DEFINER)
+        self.assertEqual(referencers, self.COUPLED_REFERENCERS)
+
+    def test_exactly_one_carrier_import_definition_in_the_set(self):
+        """One template defines ``CarrierImport``; every other one references
+        it — same coupling contract as ``ImportGate`` (both live in
+        ``UnitytkSettings.cs``)."""
+        definers, referencers = self._coupling_surface("CarrierImport")
+        self.assertEqual(definers, self.COUPLED_DEFINER)
+        self.assertEqual(referencers, self.COUPLED_REFERENCERS)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

{unitytk-0.0.7 → unitytk-0.0.8}/unitytk/__init__.py

@@ -1,8 +1,8 @@
-__version__ = "0.0.7"
+__version__ = "0.0.8"
 
 from .launcher import UnityLauncher, UnityFinder
 from .scene_builder import SceneBuilder
-from .template_deployer import TemplateDeployer
+from .template_deployer import TemplateDeployer, PackageComponent
 from .asset_delivery import CopyToAssetsDeliverer, FileToUnityBridge
 
 __all__ = [
@@ -10,6 +10,7 @@ __all__ = [
     "UnityFinder",
     "SceneBuilder",
     "TemplateDeployer",
+    "PackageComponent",
     "CopyToAssetsDeliverer",
     "FileToUnityBridge",
 ]