docworkspace 0.2.0__tar.gz → 0.2.2__tar.gz

{docworkspace-0.2.0 → docworkspace-0.2.2}/.gitignore

@@ -15,7 +15,6 @@ env/
 
 # uv
 .python-version
-uv.lock
 
 # Pytest
 .pytest_cache/

{docworkspace-0.2.0 → docworkspace-0.2.2}/PKG-INFO

@@ -1,18 +1,14 @@
 Metadata-Version: 2.4
 Name: docworkspace
-Version: 0.2.0
+Version: 0.2.2
 Summary: A workspace library for managing Polars dataframes with parent-child relationships and lazy evaluation
 Requires-Python: >=3.14
-Requires-Dist: polars
-Requires-Dist: polars-text>=0.1.0
-Provides-Extra: cpu
-Requires-Dist: polars; extra == 'cpu'
-Requires-Dist: polars-text>=0.1.0; extra == 'cpu'
+Requires-Dist: polars-text>=0.1.2
 Description-Content-Type: text/markdown
 
 # DocWorkspace
 
-A powerful Python library for managing Polars DataFrames and LazyFrames with parent-child relationships, lazy evaluation, and FastAPI integration. Part of the LDaCA (Language Data Commons of Australia) ecosystem.
+A powerful Python library for managing Polars LazyFrames with parent-child relationships, lazy evaluation, and FastAPI integration. Part of the LDaCA (Language Data Commons of Australia) ecosystem.
 
 ## Overview
 
@@ -20,21 +16,31 @@ DocWorkspace provides a workspace-based approach to data analysis, where data tr
 
 - **Relationship Tracking**: Understand data lineage and transformation history
 - **Lazy Evaluation**: Optimize performance with Polars LazyFrames
-- **Multiple Data Types**: Support for Polars DataFrames and LazyFrames
+- **LazyFrame-Native Graphs**: Node data is stored as Polars LazyFrames
 - **FastAPI Integration**: Ready-to-use models and utilities for web APIs
 - **Serialization**: Save and restore entire workspaces with their relationships
 
 ## Installation
 
 ```bash
-pip install docworkspace
+pip install "docworkspace>=0.2.0"
+```
+
+`docworkspace` is published on PyPI as a pure-Python package.
+
+### Install From Source
+
+```bash
+git clone https://github.com/Australian-Text-Analytics-Platform/docworkspace.git
+cd docworkspace
+uv sync --group dev
 ```
 
 ### Dependencies
 
 - Python ≥ 3.14
 - polars
-- polars-text
+- polars-text >= 0.1.0
 
 For FastAPI integration:
 
@@ -57,8 +63,8 @@ df = pl.DataFrame({
     "score": [0.8, 0.9, 0.95]
 })
 
-# Add data to workspace
-data_node = workspace.add_node(Node(df, name="raw_data"))
+# Convert to LazyFrame before adding data to the workspace
+data_node = workspace.add_node(Node(df.lazy(), name="raw_data"))
 
 # Apply transformations (creates new nodes automatically)
 filtered = data_node.filter(pl.col("score") > 0.85)
@@ -77,16 +83,17 @@ print(workspace.visualize_graph())
 
 ### Node
 
-A `Node` wraps your data (DataFrames, LazyFrames) and tracks relationships with other nodes. Nodes support:
+A `Node` wraps a Polars `LazyFrame` and tracks relationships with other nodes. Nodes support:
 
 - **Transparent Data Access**: All DataFrame methods work directly on nodes
+- **Transparent Data Access**: All LazyFrame methods work directly on nodes
 - **Automatic Relationship Tracking**: Operations create child nodes
 - **Lazy Evaluation**: Maintains laziness for performance
 - **Metadata**: Store operation descriptions and custom metadata
 
 ```python
-# Node automatically creates workspace if none provided
-node = Node(df, name="my_data")
+# Convert eager data before creating a node when needed
+node = Node(df.lazy(), name="my_data")
 
 # All DataFrame operations work directly
 filtered_node = node.filter(pl.col("value") > 10)
@@ -123,28 +130,23 @@ leaves = workspace.get_leaf_nodes()
 
 ## Supported Data Types
 
-DocWorkspace supports multiple data types from the Polars ecosystem:
-
-### Polars Types
-
-- **`pl.DataFrame`**: Materialized, in-memory data
-- **`pl.LazyFrame`**: Lazy evaluation for performance optimization
+DocWorkspace stores node data as Polars `LazyFrame` objects.
 
-### Example with Different Types
+### Creating LazyFrame Nodes
 
 ```python
 import polars as pl
 
-# Polars DataFrame (eager)
+# Convert an eager Polars DataFrame when needed
 df = pl.DataFrame({"text": ["hello", "world"], "id": [1, 2]})
-node1 = Node(df, "eager_data")
+node1 = Node(df.lazy(), "eager_data")
 
 # Polars LazyFrame (lazy)
 lazy_df = pl.LazyFrame({"text": ["foo", "bar"], "id": [3, 4]})
 node2 = Node(lazy_df, "lazy_data")
 
-# All work seamlessly in the same workspace
-workspace = Workspace("mixed_types")
+# Both nodes remain LazyFrames inside the workspace
+workspace = Workspace("lazyframe_nodes")
 for node in [node1, node2]:
     workspace.add_node(node)
 ```
@@ -175,7 +177,7 @@ Understand your data lineage:
 
 ```python
 # Create a processing pipeline
-raw_data = Node(df, "raw")
+raw_data = Node(df.lazy(), "raw")
 cleaned = raw_data.filter(pl.col("value").is_not_null())
 normalized = cleaned.with_columns(pl.col("value") / pl.col("value").max())
 final = normalized.select(["id", "normalized_value"])
@@ -230,7 +232,7 @@ def custom_transform(node: Node, operation_name: str) -> Node:
     """Apply custom transformation and track the operation."""
     # Your custom logic here
     result_data = node.data.with_columns(pl.col("value") * 2)
-    
+
     # Create new node with relationship tracking
     return Node(
         data=result_data,
@@ -274,7 +276,7 @@ df = pl.DataFrame({
     "metadata": ["type1", "type2", "type1"]
 })
 
-node = Node(df, "corpus")
+node = Node(df.lazy(), "corpus")
 node.document = "text"
 
 # Document metadata is preserved across operations
@@ -295,7 +297,7 @@ Node(data, name=None, workspace=None, parents=None, operation=None)
 #### Properties
 
 - `document: Optional[str]` - Document column tracked in node metadata
-- `data: DataFrame | LazyFrame` - Underlying frame-like object
+- `data: pl.LazyFrame` - Underlying frame-like object
 
 #### Methods
 
@@ -304,9 +306,9 @@ Node(data, name=None, workspace=None, parents=None, operation=None)
 - `info(json=False) -> Dict` - Get node information
 - `json_schema() -> Dict[str, str]` - Get JSON-compatible schema
 
-#### DataFrame Operations
+#### Data Operations
 
-All Polars DataFrame/LazyFrame operations are available directly:
+All Polars LazyFrame operations are available directly:
 
 - `filter(condition) -> Node`
 - `select(columns) -> Node`
@@ -402,7 +404,7 @@ df = pl.DataFrame({
 workspace = Workspace("text_analysis")
 
 # Track the document column for text analysis
-corpus = workspace.add_node(Node(df, "full_corpus"))
+corpus = workspace.add_node(Node(df.lazy(), "full_corpus"))
 corpus.document = "text"
 
 # Filter by category
@@ -514,44 +516,64 @@ for node in workspace.get_leaf_nodes():
 
 ```bash
 # Install development dependencies
-pip install pytest
+uv sync --group dev
 
 # Run all tests
-pytest
+uv run pytest
 
 # Run with coverage
-pytest --cov=docworkspace
+uv run pytest --cov=docworkspace
 
 # Run specific test file
-pytest tests/test_workspace.py -v
+uv run pytest tests/test_workspace.py -v
+```
+
+### Building Distributions
+
+```bash
+uv build
 ```
 
+This produces a universal wheel and source distribution suitable for PyPI.
+
 ### Contributing
 
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feature-name`
 3. Make your changes and add tests
-4. Run the test suite: `pytest`
+4. Run the test suite: `uv run pytest`
 5. Submit a pull request
 
 ### Project Structure
 
 ```text
 docworkspace/
-├── docworkspace/           # Main package
-│   ├── __init__.py        # Package exports
-│   ├── node.py            # Node class implementation
-│   ├── workspace.py       # Workspace class implementation
-│   ├── api_models.py      # FastAPI Pydantic models
-│   └── api_utils.py       # FastAPI utility functions
+├── .github/
+│   └── workflows/         # CI and release automation
+├── src/
+│   └── docworkspace/
+│       ├── __init__.py    # Public package exports
+│       ├── node/
+│       │   ├── __init__.py
+│       │   ├── core.py    # Node implementation
+│       │   └── io.py      # Node serialization helpers
+│       └── workspace/
+│           ├── __init__.py
+│           ├── core.py    # Workspace implementation
+│           ├── io.py      # Workspace serialization helpers
+│           └── analysis.py
 ├── tests/                 # Test suite
-│   ├── test_node.py       # Node class tests
-│   ├── test_workspace.py  # Workspace class tests
-│   ├── test_integration.py # Integration tests
-│   └── test_coverage.py   # Coverage tests
-├── examples/              # Example scripts and data
-├── README.md             # This file
-└── pyproject.toml        # Project configuration
+│   ├── conftest.py
+│   ├── test_fastapi_integration.py
+│   ├── test_node.py
+│   ├── test_node_io.py
+│   ├── test_simple_operations.py
+│   ├── test_workspace.py
+│   ├── test_workspace_serialization_types.py
+│   └── test_workspace_shim.py
+├── PUBLISH.md             # Release runbook
+├── README.md              # This file
+└── pyproject.toml         # Project configuration
 ```
 
 ## License
@@ -560,15 +582,12 @@ Part of the LDaCA (Language Data Commons of Australia) ecosystem.
 
 ## Changelog
 
-### Version 0.1.0
+### Version 0.2.0
 
-- Initial release
-- Core Node and Workspace functionality
-- Support for Polars data types
-- Lazy evaluation support
-- FastAPI integration
-- Serialization capabilities
-- Comprehensive test suite
+- Published on PyPI as `docworkspace`
+- PyPI consumers can install the package directly instead of relying on a local workspace checkout
+- Added release automation and publishing runbook for future releases
+- Continued support for Polars data types, lazy evaluation, FastAPI integration, and serialization
 
 ## Related Projects
 

{docworkspace-0.2.0 → docworkspace-0.2.2}/README.md

@@ -1,6 +1,6 @@
 # DocWorkspace
 
-A powerful Python library for managing Polars DataFrames and LazyFrames with parent-child relationships, lazy evaluation, and FastAPI integration. Part of the LDaCA (Language Data Commons of Australia) ecosystem.
+A powerful Python library for managing Polars LazyFrames with parent-child relationships, lazy evaluation, and FastAPI integration. Part of the LDaCA (Language Data Commons of Australia) ecosystem.
 
 ## Overview
 
@@ -8,21 +8,31 @@ DocWorkspace provides a workspace-based approach to data analysis, where data tr
 
 - **Relationship Tracking**: Understand data lineage and transformation history
 - **Lazy Evaluation**: Optimize performance with Polars LazyFrames
-- **Multiple Data Types**: Support for Polars DataFrames and LazyFrames
+- **LazyFrame-Native Graphs**: Node data is stored as Polars LazyFrames
 - **FastAPI Integration**: Ready-to-use models and utilities for web APIs
 - **Serialization**: Save and restore entire workspaces with their relationships
 
 ## Installation
 
 ```bash
-pip install docworkspace
+pip install "docworkspace>=0.2.0"
+```
+
+`docworkspace` is published on PyPI as a pure-Python package.
+
+### Install From Source
+
+```bash
+git clone https://github.com/Australian-Text-Analytics-Platform/docworkspace.git
+cd docworkspace
+uv sync --group dev
 ```
 
 ### Dependencies
 
 - Python ≥ 3.14
 - polars
-- polars-text
+- polars-text >= 0.1.0
 
 For FastAPI integration:
 
@@ -45,8 +55,8 @@ df = pl.DataFrame({
     "score": [0.8, 0.9, 0.95]
 })
 
-# Add data to workspace
-data_node = workspace.add_node(Node(df, name="raw_data"))
+# Convert to LazyFrame before adding data to the workspace
+data_node = workspace.add_node(Node(df.lazy(), name="raw_data"))
 
 # Apply transformations (creates new nodes automatically)
 filtered = data_node.filter(pl.col("score") > 0.85)
@@ -65,16 +75,17 @@ print(workspace.visualize_graph())
 
 ### Node
 
-A `Node` wraps your data (DataFrames, LazyFrames) and tracks relationships with other nodes. Nodes support:
+A `Node` wraps a Polars `LazyFrame` and tracks relationships with other nodes. Nodes support:
 
 - **Transparent Data Access**: All DataFrame methods work directly on nodes
+- **Transparent Data Access**: All LazyFrame methods work directly on nodes
 - **Automatic Relationship Tracking**: Operations create child nodes
 - **Lazy Evaluation**: Maintains laziness for performance
 - **Metadata**: Store operation descriptions and custom metadata
 
 ```python
-# Node automatically creates workspace if none provided
-node = Node(df, name="my_data")
+# Convert eager data before creating a node when needed
+node = Node(df.lazy(), name="my_data")
 
 # All DataFrame operations work directly
 filtered_node = node.filter(pl.col("value") > 10)
@@ -111,28 +122,23 @@ leaves = workspace.get_leaf_nodes()
 
 ## Supported Data Types
 
-DocWorkspace supports multiple data types from the Polars ecosystem:
-
-### Polars Types
-
-- **`pl.DataFrame`**: Materialized, in-memory data
-- **`pl.LazyFrame`**: Lazy evaluation for performance optimization
+DocWorkspace stores node data as Polars `LazyFrame` objects.
 
-### Example with Different Types
+### Creating LazyFrame Nodes
 
 ```python
 import polars as pl
 
-# Polars DataFrame (eager)
+# Convert an eager Polars DataFrame when needed
 df = pl.DataFrame({"text": ["hello", "world"], "id": [1, 2]})
-node1 = Node(df, "eager_data")
+node1 = Node(df.lazy(), "eager_data")
 
 # Polars LazyFrame (lazy)
 lazy_df = pl.LazyFrame({"text": ["foo", "bar"], "id": [3, 4]})
 node2 = Node(lazy_df, "lazy_data")
 
-# All work seamlessly in the same workspace
-workspace = Workspace("mixed_types")
+# Both nodes remain LazyFrames inside the workspace
+workspace = Workspace("lazyframe_nodes")
 for node in [node1, node2]:
     workspace.add_node(node)
 ```
@@ -163,7 +169,7 @@ Understand your data lineage:
 
 ```python
 # Create a processing pipeline
-raw_data = Node(df, "raw")
+raw_data = Node(df.lazy(), "raw")
 cleaned = raw_data.filter(pl.col("value").is_not_null())
 normalized = cleaned.with_columns(pl.col("value") / pl.col("value").max())
 final = normalized.select(["id", "normalized_value"])
@@ -218,7 +224,7 @@ def custom_transform(node: Node, operation_name: str) -> Node:
     """Apply custom transformation and track the operation."""
     # Your custom logic here
     result_data = node.data.with_columns(pl.col("value") * 2)
-    
+
     # Create new node with relationship tracking
     return Node(
         data=result_data,
@@ -262,7 +268,7 @@ df = pl.DataFrame({
     "metadata": ["type1", "type2", "type1"]
 })
 
-node = Node(df, "corpus")
+node = Node(df.lazy(), "corpus")
 node.document = "text"
 
 # Document metadata is preserved across operations
@@ -283,7 +289,7 @@ Node(data, name=None, workspace=None, parents=None, operation=None)
 #### Properties
 
 - `document: Optional[str]` - Document column tracked in node metadata
-- `data: DataFrame | LazyFrame` - Underlying frame-like object
+- `data: pl.LazyFrame` - Underlying frame-like object
 
 #### Methods
 
@@ -292,9 +298,9 @@ Node(data, name=None, workspace=None, parents=None, operation=None)
 - `info(json=False) -> Dict` - Get node information
 - `json_schema() -> Dict[str, str]` - Get JSON-compatible schema
 
-#### DataFrame Operations
+#### Data Operations
 
-All Polars DataFrame/LazyFrame operations are available directly:
+All Polars LazyFrame operations are available directly:
 
 - `filter(condition) -> Node`
 - `select(columns) -> Node`
@@ -390,7 +396,7 @@ df = pl.DataFrame({
 workspace = Workspace("text_analysis")
 
 # Track the document column for text analysis
-corpus = workspace.add_node(Node(df, "full_corpus"))
+corpus = workspace.add_node(Node(df.lazy(), "full_corpus"))
 corpus.document = "text"
 
 # Filter by category
@@ -502,44 +508,64 @@ for node in workspace.get_leaf_nodes():
 
 ```bash
 # Install development dependencies
-pip install pytest
+uv sync --group dev
 
 # Run all tests
-pytest
+uv run pytest
 
 # Run with coverage
-pytest --cov=docworkspace
+uv run pytest --cov=docworkspace
 
 # Run specific test file
-pytest tests/test_workspace.py -v
+uv run pytest tests/test_workspace.py -v
+```
+
+### Building Distributions
+
+```bash
+uv build
 ```
 
+This produces a universal wheel and source distribution suitable for PyPI.
+
 ### Contributing
 
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feature-name`
 3. Make your changes and add tests
-4. Run the test suite: `pytest`
+4. Run the test suite: `uv run pytest`
 5. Submit a pull request
 
 ### Project Structure
 
 ```text
 docworkspace/
-├── docworkspace/           # Main package
-│   ├── __init__.py        # Package exports
-│   ├── node.py            # Node class implementation
-│   ├── workspace.py       # Workspace class implementation
-│   ├── api_models.py      # FastAPI Pydantic models
-│   └── api_utils.py       # FastAPI utility functions
+├── .github/
+│   └── workflows/         # CI and release automation
+├── src/
+│   └── docworkspace/
+│       ├── __init__.py    # Public package exports
+│       ├── node/
+│       │   ├── __init__.py
+│       │   ├── core.py    # Node implementation
+│       │   └── io.py      # Node serialization helpers
+│       └── workspace/
+│           ├── __init__.py
+│           ├── core.py    # Workspace implementation
+│           ├── io.py      # Workspace serialization helpers
+│           └── analysis.py
 ├── tests/                 # Test suite
-│   ├── test_node.py       # Node class tests
-│   ├── test_workspace.py  # Workspace class tests
-│   ├── test_integration.py # Integration tests
-│   └── test_coverage.py   # Coverage tests
-├── examples/              # Example scripts and data
-├── README.md             # This file
-└── pyproject.toml        # Project configuration
+│   ├── conftest.py
+│   ├── test_fastapi_integration.py
+│   ├── test_node.py
+│   ├── test_node_io.py
+│   ├── test_simple_operations.py
+│   ├── test_workspace.py
+│   ├── test_workspace_serialization_types.py
+│   └── test_workspace_shim.py
+├── PUBLISH.md             # Release runbook
+├── README.md              # This file
+└── pyproject.toml         # Project configuration
 ```
 
 ## License
@@ -548,15 +574,12 @@ Part of the LDaCA (Language Data Commons of Australia) ecosystem.
 
 ## Changelog
 
-### Version 0.1.0
+### Version 0.2.0
 
-- Initial release
-- Core Node and Workspace functionality
-- Support for Polars data types
-- Lazy evaluation support
-- FastAPI integration
-- Serialization capabilities
-- Comprehensive test suite
+- Published on PyPI as `docworkspace`
+- PyPI consumers can install the package directly instead of relying on a local workspace checkout
+- Added release automation and publishing runbook for future releases
+- Continued support for Polars data types, lazy evaluation, FastAPI integration, and serialization
 
 ## Related Projects
 

{docworkspace-0.2.0 → docworkspace-0.2.2}/pyproject.toml

@@ -1,26 +1,14 @@
 [project]
 name = "docworkspace"
-version = "0.2.0"
+version = "0.2.2"
 description = "A workspace library for managing Polars dataframes with parent-child relationships and lazy evaluation"
 readme = "README.md"
 requires-python = ">=3.14"
-dependencies = [
-    "polars",
-    "polars-text>=0.1.0",
-]
-
-[project.optional-dependencies]
-cpu = [
-    "polars",
-    "polars-text>=0.1.0",
-]
+dependencies = ["polars-text>=0.1.2"]
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [dependency-groups]
-dev = [
-    "pytest>=8.0.0",
-]
-
+dev = ["pytest>=8.0.0"]

{docworkspace-0.2.0 → docworkspace-0.2.2}/src/docworkspace/node/core.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 import uuid
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, cast
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, Sequence, cast
 
 import polars as pl
 
@@ -27,9 +27,9 @@ class Node:
     def __init__(
         self,
         data: pl.LazyFrame,
-        name: str | None = None,
+        name: str,
         workspace: Optional["Workspace"] = None,
-        parents: list["Node | str"] | None = None,
+        parents: Sequence["Node | str"] = (),
         operation: str | None = None,
         id: str | None = None,
         document: str | None = None,
@@ -46,7 +46,7 @@ class Node:
         self._redo_stack: list[pl.LazyFrame] = []
         self._data: pl.LazyFrame = data
         self._document_column: Optional[str] = document
-        self.parents: list[Node | str] = list(parents or [])
+        self.parents: list[Node | str] = list(parents)
         self.workspace: Optional[Workspace] = workspace
         self.operation = operation
 

{docworkspace-0.2.0 → docworkspace-0.2.2}/src/docworkspace/node/io.py

@@ -79,7 +79,7 @@ def from_dict(
     if workspace is None:
         return Node(data=lf, workspace=None, parents=list(parent_ids), **node_metadata)
 
-    parents = [
+    parents: list[Node | str] = [
         workspace.nodes[parent_id]
         for parent_id in parent_ids
         if parent_id in workspace.nodes

{docworkspace-0.2.0 → docworkspace-0.2.2}/tests/test_fastapi_integration.py

@@ -4,7 +4,11 @@ This module tests that the core docworkspace library is properly separated
 from API-specific functionality and can operate independently.
 """
 
+from typing import cast
+
+import polars as pl
 import pytest
+
 from docworkspace import Node, Workspace
 
 
@@ -25,10 +29,12 @@ class TestCoreLibraryIndependence:
 
     def test_no_api_dependencies(self):
         """Test that core classes don't have API-specific methods."""
-        df = pytest.importorskip("polars").DataFrame({
-            "id": [1, 2, 3],
-            "text": ["a", "b", "c"],
-        })
+        df = pytest.importorskip("polars").DataFrame(
+            {
+                "id": [1, 2, 3],
+                "text": ["a", "b", "c"],
+            }
+        )
 
         workspace = Workspace("test")
         node = workspace.add_node(Node(df.lazy(), "test_node"))
@@ -64,14 +70,14 @@ class TestCoreLibraryIndependence:
         # Test core functionality
         assert len(workspace.nodes) == 1
         assert node.name == "test_data"
-        assert node.data.collect().height == 3
+        assert cast(pl.DataFrame, node.data.collect()).height == 3
         assert node.data.collect_schema().len() == 2
         assert isinstance(node.data, pl.LazyFrame)
 
         # Test node operations (polars delegation)
         filtered = node.filter(pl.col("x") > 1)
         assert isinstance(filtered, Node)
-        assert filtered.data.collect().height == 2
+        assert cast(pl.DataFrame, filtered.data.collect()).height == 2
 
     def test_lazy_frame_support(self):
         """Test that lazy frame support works without API dependencies."""
@@ -89,3 +95,4 @@ class TestCoreLibraryIndependence:
         filtered_lazy = lazy_node.filter(pl.col("a") > 1)
         assert isinstance(filtered_lazy, Node)
         assert isinstance(filtered_lazy.data, pl.LazyFrame)
+        assert isinstance(filtered_lazy.data, pl.LazyFrame)

{docworkspace-0.2.0 → docworkspace-0.2.2}/tests/test_node.py

@@ -1,7 +1,11 @@
 """Tests for the Node class."""
 
+from inspect import signature
+from typing import Optional, Sequence, cast, get_type_hints
+
 import polars as pl
 import pytest
+
 from docworkspace import Node, Workspace
 
 
@@ -50,6 +54,23 @@ class TestNode:
         assert node.parents == ["parent-123"]
         assert node.children == []
 
+    def test_node_init_contract_uses_non_optional_parents(self):
+        """Constructor type contract should not advertise optional parents."""
+        hints = get_type_hints(
+            Node.__init__,
+            globalns={
+                "Node": Node,
+                "Workspace": Workspace,
+                "Sequence": Sequence,
+                "Optional": Optional,
+                "pl": pl,
+            },
+        )
+
+        assert hints["name"] is str
+        assert hints["parents"] == Sequence[Node | str]
+        assert signature(Node.__init__).parameters["parents"].default == ()
+
     def test_node_lazy_status_polars_dataframe(self, sample_df):
         """Test lazy status for polars DataFrame."""
         node = Node(sample_df.lazy(), "test_node")
@@ -82,7 +103,7 @@ class TestNode:
 
         assert len(sliced.parents) == 1
         assert sliced.parents[0] == node
-        assert sliced.data.collect().height == 2
+        assert cast(pl.DataFrame, sliced.data.collect()).height == 2
 
     def test_node_drop_creates_child_and_drops_column(self, sample_df):
         """Dropping columns returns a child node with updated schema."""
@@ -303,11 +324,13 @@ class TestNodeRelationships:
     @pytest.fixture
     def sample_df(self):
         """Create a sample DataFrame."""
-        return pl.DataFrame({
-            "id": [1, 2, 3, 4, 5],
-            "category": ["A", "B", "A", "B", "C"],
-            "value": [10, 20, 30, 40, 50],
-        })
+        return pl.DataFrame(
+            {
+                "id": [1, 2, 3, 4, 5],
+                "category": ["A", "B", "A", "B", "C"],
+                "value": [10, 20, 30, 40, 50],
+            }
+        )
 
     def test_filter_creates_parent_child_relationship(self, workspace, sample_df):
         """Test that filter operation creates proper parent-child relationship."""
@@ -376,3 +399,4 @@ class TestNodeRelationships:
         assert parent2 in merged.parents
         assert merged in parent1.children
         assert merged in parent2.children
+        assert merged in parent2.children

{docworkspace-0.2.0 → docworkspace-0.2.2}/tests/test_node_io.py

@@ -1,8 +1,10 @@
 import json
 import os
 from pathlib import Path
+from typing import cast
 
 import polars as pl
+
 from docworkspace import Node, Workspace
 from docworkspace.node.io import dumps, from_dict, loads, to_dict
 
@@ -36,7 +38,7 @@ def test_node_to_dict_persists_lazyframe_payload(tmp_path: Path):
     data_file = tmp_path / payload["data_path"]
     assert data_file.exists()
     restored = pl.LazyFrame.deserialize(data_file.open("rb"), format="binary")
-    assert restored.collect().to_dict(as_series=False) == {
+    assert cast(pl.DataFrame, restored.collect()).to_dict(as_series=False) == {
         "text": ["a", "b"],
         "value": [1, 2],
     }
@@ -62,7 +64,9 @@ def test_node_exposes_instance_and_class_serialization_helpers(tmp_path: Path):
 
     assert payload["node_metadata"]["id"] == node.id
     assert restored.id == node.id
-    assert restored.data.collect().to_dict(as_series=False) == {"value": [1, 2, 3]}
+    assert cast(pl.DataFrame, restored.data.collect()).to_dict(as_series=False) == {
+        "value": [1, 2, 3]
+    }
 
 
 def test_node_dumps_returns_json_payload_and_persists_data_file(tmp_path: Path):
@@ -110,7 +114,7 @@ def test_node_from_dict_restores_node_state(tmp_path: Path):
     assert restored.children == []
     assert restored.can_undo is False
     assert restored.can_redo is False
-    assert restored.data.collect().to_dict(as_series=False) == {
+    assert cast(pl.DataFrame, restored.data.collect()).to_dict(as_series=False) == {
         "text": ["x", "y"],
         "value": [10, 20],
     }
@@ -136,7 +140,9 @@ def test_node_loads_round_trip_from_json_string(tmp_path: Path):
 
     assert restored.id == node.id
     assert restored.name == "round_trip"
-    assert restored.data.collect().to_dict(as_series=False) == {"value": [3, 4]}
+    assert cast(pl.DataFrame, restored.data.collect()).to_dict(as_series=False) == {
+        "value": [3, 4]
+    }
 
 
 def test_node_from_dict_uses_constructor_defaults_for_runtime_state(tmp_path: Path):
@@ -226,3 +232,4 @@ def test_node_from_dict_ignores_missing_parent_ids(tmp_path: Path):
     )
 
     assert restored.parents == []
+    assert restored.parents == []

{docworkspace-0.2.0 → docworkspace-0.2.2}/tests/test_workspace.py

@@ -3,9 +3,11 @@
 import os
 import tempfile
 from pathlib import Path
+from typing import Any, cast
 
 import polars as pl
 import pytest
+
 from docworkspace import Node, Workspace
 
 
@@ -203,11 +205,13 @@ class TestWorkspaceSerialization:
         workspace.modified_at = "2024-01-01T12:00:00Z"
 
         # Create nodes
-        df1 = pl.DataFrame({
-            "id": [1, 2, 3],
-            "category": ["A", "B", "A"],
-            "value": [10, 20, 30],
-        })
+        df1 = pl.DataFrame(
+            {
+                "id": [1, 2, 3],
+                "category": ["A", "B", "A"],
+                "value": [10, 20, 30],
+            }
+        )
 
         df2 = pl.DataFrame({"id": [1, 2, 3], "extra": ["x", "y", "z"]})
 
@@ -323,7 +327,7 @@ class TestWorkspaceSerialization:
     def test_load_from_dict_rejected(self):
         """Workspace.load should accept path-like values only."""
         with pytest.raises(TypeError):
-            Workspace.load({"workspace_metadata": {}, "nodes": []})
+            cast(Any, Workspace.load)({"workspace_metadata": {}, "nodes": []})
 
     def test_workspace_serialized_file_structure(self, populated_workspace):
         """Validate on-disk JSON structure contains expected envelope keys."""
@@ -449,11 +453,13 @@ class TestWorkspaceGraphOperations:
     def test_workspace_csv_loading(self):
         """Test explicit CSV loading workflow for workspaces."""
         # Create a temporary CSV file
-        df = pl.DataFrame({
-            "name": ["Alice", "Bob", "Charlie"],
-            "age": [25, 30, 35],
-            "city": ["NYC", "LA", "Chicago"],
-        })
+        df = pl.DataFrame(
+            {
+                "name": ["Alice", "Bob", "Charlie"],
+                "age": [25, 30, 35],
+                "city": ["NYC", "LA", "Chicago"],
+            }
+        )
 
         with tempfile.NamedTemporaryFile(mode="w", suffix=".csv", delete=False) as f:
             df.write_csv(f.name)
@@ -603,3 +609,4 @@ class TestWorkspaceGraphOperations:
         assert node_c in node_d.parents
         assert node_a not in node_d.parents
         assert node_a not in workspace.nodes.values()
+        assert node_a not in workspace.nodes.values()

{docworkspace-0.2.0 → docworkspace-0.2.2}/tests/test_workspace_serialization_types.py

@@ -1,9 +1,11 @@
 import json
+from typing import Any, cast
 
 import polars as pl
 import pytest
-from docworkspace.node import Node  # type: ignore
-from docworkspace.workspace import Workspace  # type: ignore
+
+from docworkspace.node import Node
+from docworkspace.workspace import Workspace
 
 
 def build_sample_objects():
@@ -34,7 +36,9 @@ def test_workspace_save_load_preserves_types(tmp_path):
     # Round-trip data content sanity
     df_node = next(n for n in ws2.nodes.values() if n.name == "df")
     assert isinstance(df_node.data, pl.LazyFrame)
-    assert df_node.data.select(pl.col("a")).collect().to_series().to_list() == [1, 2, 3]
+    assert cast(
+        pl.DataFrame, df_node.data.select(pl.col("a")).collect()
+    ).to_series().to_list() == [1, 2, 3]
 
 
 def test_workspace_save_load_no_format_argument(tmp_path):
@@ -43,14 +47,16 @@ def test_workspace_save_load_no_format_argument(tmp_path):
 
     # API no longer accepts a format argument.
     with pytest.raises(TypeError):
-        ws.save(tmp_path / "ws.bin", format="binary")
+        cast(Any, ws.save)(tmp_path / "ws.bin", format="binary")
 
     dummy = tmp_path / "ws.json"
     dummy.write_text(
-        json.dumps({
-            "workspace_metadata": {"id": "x", "name": "n"},
-            "nodes": [],
-        })
+        json.dumps(
+            {
+                "workspace_metadata": {"id": "x", "name": "n"},
+                "nodes": [],
+            }
+        )
     )
     with pytest.raises(TypeError):
-        Workspace.load(dummy, format="binary")
+        cast(Any, Workspace.load)(dummy, format="binary")

docworkspace-0.2.2/uv.lock

@@ -0,0 +1,125 @@
+version = 1
+revision = 3
+requires-python = ">=3.14"
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "docworkspace"
+version = "0.2.2"
+source = { editable = "." }
+dependencies = [
+    { name = "polars-text" },
+]
+
+[package.dev-dependencies]
+dev = [
+    { name = "pytest" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "polars-text", specifier = ">=0.1.2" }]
+
+[package.metadata.requires-dev]
+dev = [{ name = "pytest", specifier = ">=8.0.0" }]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/65/ee/299d360cdc32edc7d2cf530f3accf79c4fca01e96ffc950d8a52213bd8e4/packaging-26.0.tar.gz", hash = "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", size = 143416, upload-time = "2026-01-21T20:50:39.064Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/b9/c538f279a4e237a006a2c98387d081e9eb060d203d8ed34467cc0f0b9b53/packaging-26.0-py3-none-any.whl", hash = "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529", size = 74366, upload-time = "2026-01-21T20:50:37.788Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
+[[package]]
+name = "polars"
+version = "1.39.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "polars-runtime-32" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/93/ab/f19e592fce9e000da49c96bf35e77cef67f9cb4b040bfa538a2764c0263e/polars-1.39.3.tar.gz", hash = "sha256:2e016c7f3e8d14fa777ef86fe0477cec6c67023a20ba4c94d6e8431eefe4a63c", size = 728987, upload-time = "2026-03-20T11:16:24.836Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b4/db/08f4ca10c5018813e7e0b59e4472302328b3d2ab1512f5a2157a814540e0/polars-1.39.3-py3-none-any.whl", hash = "sha256:c2b955ccc0a08a2bc9259785decf3d5c007b489b523bf2390cf21cec2bb82a56", size = 823985, upload-time = "2026-03-20T11:14:23.619Z" },
+]
+
+[[package]]
+name = "polars-runtime-32"
+version = "1.39.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/17/39/c8688696bc22b6c501e3b82ef3be10e543c07a785af5660f30997cd22dd2/polars_runtime_32-1.39.3.tar.gz", hash = "sha256:c728e4f469cafab501947585f36311b8fb222d3e934c6209e83791e0df20b29d", size = 2872335, upload-time = "2026-03-20T11:16:26.581Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3b/74/1b41205f7368c9375ab1dea91178eaa20435fe3eff036390a53a7660b416/polars_runtime_32-1.39.3-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:425c0b220b573fa097b4042edff73114cc6d23432a21dfd2dc41adf329d7d2e9", size = 45273243, upload-time = "2026-03-20T11:14:26.691Z" },
+    { url = "https://files.pythonhosted.org/packages/90/bf/297716b3095fe719be20fcf7af1d2b6ab069c38199bbace2469608a69b3a/polars_runtime_32-1.39.3-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:ef5884711e3c617d7dc93519a7d038e242f5741cfe5fe9afd32d58845d86c562", size = 40842924, upload-time = "2026-03-20T11:14:31.154Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/3e/e65236d9d0d9babfa0ecba593413c06530fca60a8feb8f66243aa5dba92e/polars_runtime_32-1.39.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:06b47f535eb1f97a9a1e5b0053ef50db3a4276e241178e37bbb1a38b1fa53b14", size = 43220650, upload-time = "2026-03-20T11:14:35.458Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/15/fc3e43f3fdf3f20b7dfb5abe871ab6162cf8fb4aeabf4cfad822d5dc4c79/polars_runtime_32-1.39.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8bc9e13dc1d2e828331f2fe8ccbc9757554dc4933a8d3e85e906b988178f95ed", size = 46877498, upload-time = "2026-03-20T11:14:40.14Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/81/bd5f895919e32c6ab0a7786cd0c0ca961cb03152c47c3645808b54383f31/polars_runtime_32-1.39.3-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:363d49e3a3e638fc943e2b9887940300a7d06789930855a178a4727949259dc2", size = 43380176, upload-time = "2026-03-20T11:14:45.566Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/3e/c86433c3b5ec0315bdfc7640d0c15d41f1216c0103a0eab9a9b5147d6c4c/polars_runtime_32-1.39.3-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:7c206bdcc7bc62ea038d6adea8e44b02f0e675e0191a54c810703b4895208ea4", size = 46485933, upload-time = "2026-03-20T11:14:51.155Z" },
+    { url = "https://files.pythonhosted.org/packages/54/ce/200b310cf91f98e652eb6ea09fdb3a9718aa0293ebf113dce325797c8572/polars_runtime_32-1.39.3-cp310-abi3-win_amd64.whl", hash = "sha256:d66ca522517554a883446957539c40dc7b75eb0c2220357fb28bc8940d305339", size = 46995458, upload-time = "2026-03-20T11:14:56.074Z" },
+    { url = "https://files.pythonhosted.org/packages/da/76/2d48927e0aa2abbdde08cbf4a2536883b73277d47fbeca95e952de86df34/polars_runtime_32-1.39.3-cp310-abi3-win_arm64.whl", hash = "sha256:f49f51461de63f13e5dd4eb080421c8f23f856945f3f8bd5b2b1f59da52c2860", size = 41857648, upload-time = "2026-03-20T11:15:01.142Z" },
+]
+
+[[package]]
+name = "polars-text"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "polars" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/42/b9/1653c8ac742e3b84ebe328d213b5eb09ee96ce6241c27364911a2e29e2aa/polars_text-0.1.2.tar.gz", hash = "sha256:2a080c8e7e0ecef10b3b431fb14dbb90de6faf552e24ffa30f52f0876c5fe5e8", size = 53365, upload-time = "2026-04-07T23:41:59.225Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b4/60/829e2048d45aa63ec9c2634f63bf750b9569aded969920db3240737ea9e9/polars_text-0.1.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:f7dbd56bc3c90d87defc9e682e816ff7cdf264f19ee458df190322ba92c10c20", size = 7659172, upload-time = "2026-04-07T23:41:53.444Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/60/6417a5e73915e0dbc4c1f0643b41c715428a5350f4b2a97903655b526342/polars_text-0.1.2-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:0283306eb5c185cac89db3abf1ecf877b47c4e18a2afc4ad8892a5ab12116b8f", size = 10981911, upload-time = "2026-04-07T23:41:55.388Z" },
+    { url = "https://files.pythonhosted.org/packages/da/a6/ff1dd58b29c7ac03e7344311e2b82f211d043321d8f9705a9e8e664db900/polars_text-0.1.2-cp314-cp314-win_amd64.whl", hash = "sha256:5b80da5e9902ecaefc4db227a38d20fc6c328ee4254678319329b38248c2ea4e", size = 7771979, upload-time = "2026-04-07T23:41:57.646Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.20.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.0.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
+]