flcpy 0.2.6__tar.gz → 0.3.0__tar.gz

flcpy-0.3.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: flcpy
+Version: 0.3.0
+Summary: Python control interface for Flare Live / Flare Real
+Author-email: Jiwei Wang <zmh78879@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Flare Python Controller (flcpy)
+
+Python networking interface for Flare Live / Flare Real.
+
+## Install & Upgrade
+
+```
+pip install --upgrade flcpy
+```
+
+## Use
+
+```
+import flcpy
+
+s = flcpy.connect()  # Connect only; does not clear simulation or recover the World.
+obj = s.get_object(...)
+...
+```
+
+### Temporary experiments
+
+With a current Flare Live server, explicitly begin an experiment before making
+temporary scene edits. Clear simulation before ending the experiment:
+
+```python
+import flcpy
+
+s = flcpy.connect()
+try:
+    if not s.begin_experiment():
+        raise RuntimeError("Could not begin experiment; see the Flare Live log")
+    try:
+        # Clone objects, randomize properties, etc. These edits stay temporary.
+        # s.start() initializes simulation; s.simulate(...) advances it.
+        ...
+    finally:
+        s.clear()  # Required if simulation was initialized.
+        s.end_experiment()  # Discard temporary edits and return to the document.
+finally:
+    s.close()
+```
+
+`begin_experiment()` and `end_experiment()` return `True` on success and `False`
+on failure; failure details appear in the Flare Live log. They do not implicitly
+initialize or clear simulation. Without an experiment, scene edits affect the
+Document World and participate in its undo/redo history.
+
+`recover_world()` is retained for older Flare Live servers. Both `connect()`
+and `Simulator()` now default to `recover_world=False`. For an older server,
+explicitly pass `recover_world=True` to retain the previous clear-and-recover
+behavior on connection. Modern servers reject recovery; use experiments instead.
+
+### Tests
+
+Run the dependency-free client contract tests from this repository:
+
+```sh
+python -m unittest discover -s tests -v
+```

flcpy-0.3.0/README.md

@@ -0,0 +1,60 @@
+# Flare Python Controller (flcpy)
+
+Python networking interface for Flare Live / Flare Real.
+
+## Install & Upgrade
+
+```
+pip install --upgrade flcpy
+```
+
+## Use
+
+```
+import flcpy
+
+s = flcpy.connect()  # Connect only; does not clear simulation or recover the World.
+obj = s.get_object(...)
+...
+```
+
+### Temporary experiments
+
+With a current Flare Live server, explicitly begin an experiment before making
+temporary scene edits. Clear simulation before ending the experiment:
+
+```python
+import flcpy
+
+s = flcpy.connect()
+try:
+    if not s.begin_experiment():
+        raise RuntimeError("Could not begin experiment; see the Flare Live log")
+    try:
+        # Clone objects, randomize properties, etc. These edits stay temporary.
+        # s.start() initializes simulation; s.simulate(...) advances it.
+        ...
+    finally:
+        s.clear()  # Required if simulation was initialized.
+        s.end_experiment()  # Discard temporary edits and return to the document.
+finally:
+    s.close()
+```
+
+`begin_experiment()` and `end_experiment()` return `True` on success and `False`
+on failure; failure details appear in the Flare Live log. They do not implicitly
+initialize or clear simulation. Without an experiment, scene edits affect the
+Document World and participate in its undo/redo history.
+
+`recover_world()` is retained for older Flare Live servers. Both `connect()`
+and `Simulator()` now default to `recover_world=False`. For an older server,
+explicitly pass `recover_world=True` to retain the previous clear-and-recover
+behavior on connection. Modern servers reject recovery; use experiments instead.
+
+### Tests
+
+Run the dependency-free client contract tests from this repository:
+
+```sh
+python -m unittest discover -s tests -v
+```

{flcpy-0.2.6 → flcpy-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flcpy"
-version = "0.2.6"
+version = "0.3.0"
 authors = [
   { name="Jiwei Wang", email="zmh78879@gmail.com" },
 ]

{flcpy-0.2.6 → flcpy-0.3.0}/src/flcpy/flcpy.py

@@ -65,7 +65,7 @@ class MessagingClient:
         self.socket.close()
 
 class Simulator:
-    def __init__(self, host : str = 'localhost', port : int = 25556, recover_world = True):
+    def __init__(self, host : str = 'localhost', port : int = 25556, recover_world = False):
         self.messaging = MessagingClient(host, port)
         if recover_world:
             self.clear()
@@ -300,9 +300,30 @@ class Simulator:
     def set_object_property_reference(self, obj: int, property_path: str, value: int) -> bool:
         return self.set_object_property(obj, property_path, uint_to_bytes(value))
     
-    # Recover the world to initial state. Not available when simulation is started.
-    # Returns: success or not
+    def begin_experiment(self) -> bool:
+        """Begin a temporary editable World without initializing simulation.
+
+        Requires no existing experiment or initialized simulation. Edits in the
+        experiment do not change the document or its undo/redo history.
+        """
+        reply = self.messaging.request(uint_to_bytes(12) + b'\x00')
+        return reply[0:1] == b'\x00'
+
+    def end_experiment(self) -> bool:
+        """Discard the experiment and return to the document.
+
+        Clear any initialized simulation first. Returns False on failure;
+        details are logged by Flare Live.
+        """
+        reply = self.messaging.request(uint_to_bytes(12) + b'\x01')
+        return reply[0:1] == b'\x00'
+
     def recover_world(self) -> bool:
+        """Recover the initial World on older Flare Live versions only.
+
+        Kept for compatibility. Modern Flare Live rejects this request; use
+        begin_experiment()/end_experiment() for temporary edits instead.
+        """
         request = uint_to_bytes(8)
         reply = self.messaging.request(request)
         return reply[0:1] == b'\x00'
@@ -341,5 +362,5 @@ class Simulator:
             self.recover_world()
         self.messaging.close()
 
-def connect(host : str = 'localhost', port : int = 25556, recover_world = True) -> Simulator:
-    return Simulator(host, port, recover_world)
+def connect(host : str = 'localhost', port : int = 25556, recover_world = False) -> Simulator:
+    return Simulator(host, port, recover_world)

flcpy-0.3.0/src/flcpy.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: flcpy
+Version: 0.3.0
+Summary: Python control interface for Flare Live / Flare Real
+Author-email: Jiwei Wang <zmh78879@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Flare Python Controller (flcpy)
+
+Python networking interface for Flare Live / Flare Real.
+
+## Install & Upgrade
+
+```
+pip install --upgrade flcpy
+```
+
+## Use
+
+```
+import flcpy
+
+s = flcpy.connect()  # Connect only; does not clear simulation or recover the World.
+obj = s.get_object(...)
+...
+```
+
+### Temporary experiments
+
+With a current Flare Live server, explicitly begin an experiment before making
+temporary scene edits. Clear simulation before ending the experiment:
+
+```python
+import flcpy
+
+s = flcpy.connect()
+try:
+    if not s.begin_experiment():
+        raise RuntimeError("Could not begin experiment; see the Flare Live log")
+    try:
+        # Clone objects, randomize properties, etc. These edits stay temporary.
+        # s.start() initializes simulation; s.simulate(...) advances it.
+        ...
+    finally:
+        s.clear()  # Required if simulation was initialized.
+        s.end_experiment()  # Discard temporary edits and return to the document.
+finally:
+    s.close()
+```
+
+`begin_experiment()` and `end_experiment()` return `True` on success and `False`
+on failure; failure details appear in the Flare Live log. They do not implicitly
+initialize or clear simulation. Without an experiment, scene edits affect the
+Document World and participate in its undo/redo history.
+
+`recover_world()` is retained for older Flare Live servers. Both `connect()`
+and `Simulator()` now default to `recover_world=False`. For an older server,
+explicitly pass `recover_world=True` to retain the previous clear-and-recover
+behavior on connection. Modern servers reject recovery; use experiments instead.
+
+### Tests
+
+Run the dependency-free client contract tests from this repository:
+
+```sh
+python -m unittest discover -s tests -v
+```

{flcpy-0.2.6 → flcpy-0.3.0}/src/flcpy.egg-info/SOURCES.txt

@@ -7,4 +7,5 @@ src/flcpy/flcpy.py
 src/flcpy.egg-info/PKG-INFO
 src/flcpy.egg-info/SOURCES.txt
 src/flcpy.egg-info/dependency_links.txt
-src/flcpy.egg-info/top_level.txt
+src/flcpy.egg-info/top_level.txt
+tests/test_messaging.py

flcpy-0.3.0/tests/test_messaging.py

@@ -0,0 +1,74 @@
+"""Client wire contracts; no running simulator or third-party packages needed."""
+
+from pathlib import Path
+import struct
+import sys
+import unittest
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import flcpy
+from flcpy.flcpy import Simulator
+
+
+class MessagingCommandsTest(unittest.TestCase):
+    def setUp(self):
+        patcher = patch("flcpy.flcpy.MessagingClient")
+        self.client_class = patcher.start()
+        self.addCleanup(patcher.stop)
+        self.client = self.client_class.return_value
+        self.client.request.return_value = b"\x00"
+
+    def test_connect_defaults_to_no_world_mutation(self):
+        sim = flcpy.connect("localhost", 12345)
+        self.client_class.assert_called_once_with("localhost", 12345)
+        self.client.request.assert_not_called()
+        sim.close()
+        self.client.request.assert_not_called()
+        self.client.close.assert_called_once_with()
+
+    def test_simulator_defaults_to_no_world_mutation(self):
+        Simulator()
+        self.client.request.assert_not_called()
+
+    def test_explicit_no_recover_remains_supported(self):
+        flcpy.connect(recover_world=False)
+        self.client.request.assert_not_called()
+
+    def test_legacy_recovery_on_connection_remains_supported(self):
+        for factory in (flcpy.connect, Simulator):
+            with self.subTest(factory=factory):
+                self.client.request.reset_mock()
+                factory(recover_world=True)
+                self.assertEqual([call.args[0] for call in self.client.request.call_args_list],
+                                 [struct.pack("<IB", 3, 2), struct.pack("<I", 8)])
+
+    def test_experiment_commands_and_status(self):
+        sim = flcpy.connect()
+        for method, command in ((sim.begin_experiment, 0), (sim.end_experiment, 1)):
+            for reply, expected in ((b"\x00", True), (b"\x01", False), (b"\xff", False), (b"", False)):
+                with self.subTest(command=command, reply=reply):
+                    self.client.request.reset_mock()
+                    self.client.request.return_value = reply
+                    self.assertIs(method(), expected)
+                    self.client.request.assert_called_once_with(struct.pack("<IB", 12, command))
+
+    def test_legacy_recover_command_and_status(self):
+        sim = flcpy.connect()
+        for reply, expected in ((b"\x00", True), (b"\x01", False)):
+            self.client.request.reset_mock()
+            self.client.request.return_value = reply
+            self.assertIs(sim.recover_world(), expected)
+            self.client.request.assert_called_once_with(struct.pack("<I", 8))
+
+    def test_legacy_recovery_on_close_remains_supported(self):
+        sim = flcpy.connect()
+        sim.close(recover_world=True)
+        self.assertEqual([call.args[0] for call in self.client.request.call_args_list],
+                         [struct.pack("<IB", 3, 2), struct.pack("<I", 8)])
+        self.client.close.assert_called_once_with()
+
+
+if __name__ == "__main__":
+    unittest.main()

flcpy-0.2.6/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.4
-Name: flcpy
-Version: 0.2.6
-Summary: Python control interface for Flare Live / Flare Real
-Author-email: Jiwei Wang <zmh78879@gmail.com>
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# Flare Python Controller (flcpy)
-
-Python networking interface for Flare Live / Flare Real.
-
-## Install & Upgrade
-
-```
-pip install --upgrade flcpy
-```
-
-## Use
-
-```
-import flcpy
-
-s = flcpy.Simulator()
-obj = s.get_object(...)
-...
-```

flcpy-0.2.6/README.md

@@ -1,19 +0,0 @@
-# Flare Python Controller (flcpy)
-
-Python networking interface for Flare Live / Flare Real.
-
-## Install & Upgrade
-
-```
-pip install --upgrade flcpy
-```
-
-## Use
-
-```
-import flcpy
-
-s = flcpy.Simulator()
-obj = s.get_object(...)
-...
-```

flcpy-0.2.6/src/flcpy.egg-info/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.4
-Name: flcpy
-Version: 0.2.6
-Summary: Python control interface for Flare Live / Flare Real
-Author-email: Jiwei Wang <zmh78879@gmail.com>
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# Flare Python Controller (flcpy)
-
-Python networking interface for Flare Live / Flare Real.
-
-## Install & Upgrade
-
-```
-pip install --upgrade flcpy
-```
-
-## Use
-
-```
-import flcpy
-
-s = flcpy.Simulator()
-obj = s.get_object(...)
-...
-```