feat: add loads(), dump() and dumps() to Workspace for import/export.

Author: yt-ms

src/structurizr/api/structurizr_client.py

@@ -142,7 +142,7 @@ def get_workspace(self) -> Workspace:
             )
         logger.debug(response.text)
         self._archive_workspace(response.text)
-        return Workspace.hydrate(WorkspaceIO.parse_raw(response.text))
+        return Workspace.loads(response.text)
 
     def put_workspace(self, workspace: Workspace) -> None:
         """

src/structurizr/workspace.py

@@ -195,18 +195,54 @@ def __init__(
 
     @classmethod
     def load(cls, filename: Union[str, Path]) -> "Workspace":
-        """Load a workspace from a JSON file (which may optionally be zipped)."""
+        """Load a workspace from a file (which may optionally be gzipped)."""
         filename = Path(filename)
         try:
             with gzip.open(filename, "rt") as handle:
-                ws_io = WorkspaceIO.parse_raw(handle.read())
+                return cls.loads(handle.read())
         except FileNotFoundError as error:
             raise error
         except OSError:
             with filename.open() as handle:
-                ws_io = WorkspaceIO.parse_raw(handle.read())
+                return cls.loads(handle.read())
+
+    @classmethod
+    def loads(cls, json_string: str) -> "Workspace":
+        """Load a workspace from a JSON string."""
+        ws_io = WorkspaceIO.parse_raw(json_string)
         return cls.hydrate(ws_io)
 
+    def dump(
+        self,
+        filename: Union[str, Path],
+        *,
+        zip: bool = False,
+        indent: Optional[int] = None,
+        **kwargs
+    ):
+        """
+        Save a workspace to a file, optionally zipped.
+
+        Arguments:
+            filename (str/Path): filename to write to.
+            zip (bool): if true then contents will be zipped with GZip.
+            indent (int): if specified then pretty-print the JSON with given indent.
+            kwargs: other arguments to pass through to `json.dumps()`.
+        """
+        filename = Path(filename)
+        with gzip.open(filename, "wt") if zip else open(filename, "wt") as handle:
+            handle.write(self.dumps(indent=indent, **kwargs))
+
+    def dumps(self, indent: Optional[int] = None, **kwargs):
+        """
+        Export a workspace as a JSON string.
+
+        Args:
+            indent (int): if specified then pretty-print the JSON with given indent.
+            kwargs: other arguments to pass through to `json.dumps()`.
+        """
+        return WorkspaceIO.from_orm(self).json(indent=indent, **kwargs)
+
     @classmethod
     def hydrate(cls, workspace_io: WorkspaceIO) -> "Workspace":
         """Create a new instance of Workspace from its IO."""

tests/integration/test_workspace_io.py

@@ -85,3 +85,55 @@ def test_serialize_workspace(example, filename, monkeypatch):
     # TODO (Midnighter): This should be equivalent to the above. Why is it not?
     #  Is `.json` not using the same default arguments as `.dict`?
     # assert actual.dict() == expected.dict()
+
+
+def test_save_and_load_workspace_to_string(monkeypatch):
+    """Test saving as a JSON string and reloading."""
+    monkeypatch.syspath_prepend(EXAMPLES)
+    example = import_module("getting_started")
+    workspace = example.main()
+
+    json_string: str = workspace.dumps(indent=2)
+    workspace2 = Workspace.loads(json_string)
+
+    expected = WorkspaceIO.from_orm(workspace)
+    actual = WorkspaceIO.from_orm(workspace2)
+    assert json.loads(actual.json()) == json.loads(expected.json())
+
+
+def test_save_and_load_workspace_to_file(monkeypatch, tmp_path: Path):
+    """Test saving as a JSON file and reloading."""
+    monkeypatch.syspath_prepend(EXAMPLES)
+    example = import_module("getting_started")
+    workspace = example.main()
+
+    filepath = tmp_path / "test_workspace.json"
+
+    workspace.dump(filepath, indent=2)
+    workspace2 = Workspace.load(filepath)
+
+    expected = WorkspaceIO.from_orm(workspace)
+    actual = WorkspaceIO.from_orm(workspace2)
+    assert json.loads(actual.json()) == json.loads(expected.json())
+
+
+def test_save_and_load_workspace_to_zipped_file(monkeypatch, tmp_path: Path):
+    """Test saving as a zipped JSON file and reloading."""
+    monkeypatch.syspath_prepend(EXAMPLES)
+    example = import_module("getting_started")
+    workspace = example.main()
+
+    filepath = tmp_path / "test_workspace.json.gz"
+
+    workspace.dump(filepath, zip=True)
+    workspace2 = Workspace.load(filepath)
+
+    expected = WorkspaceIO.from_orm(workspace)
+    actual = WorkspaceIO.from_orm(workspace2)
+    assert json.loads(actual.json()) == json.loads(expected.json())
+
+
+def test_load_unknown_file_raises_file_not_found():
+    """Test that attempting to load a non-existent file raises FileNotFound."""
+    with pytest.raises(FileNotFoundError):
+        Workspace.load("foobar.json")