syrtis-python-graph 0.0.3__tar.gz

syrtis_python_graph-0.0.3/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.1
+Name: syrtis-python-graph
+Version: 0.0.3
+Author-Email: weeger <contact@syrtis.ai>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Description-Content-Type: text/markdown
+
+# syrtis-python-graph
+
+Version: 0.0.3
+
+## Table of Contents
+
+- [Status Compatibility](#status-compatibility)
+- [Tests](#tests)
+- [Roadmap](#roadmap)
+- [Useful Links](#useful-links)
+
+
+## Status & Compatibility
+
+**Maturity**: Production-ready
+
+**Python Support**: >=3.10
+
+**OS Support**: Linux, macOS, Windows
+
+**Status**: Actively maintained
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-python_graph/issues) for upcoming features and improvements.
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-python-graph
+- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
+- **Issue Tracker**: https://github.com/wexample/python-python-graph/issues
+- **Discussions**: https://github.com/wexample/python-python-graph/discussions
+- **PyPI**: [pypi.org/project/syrtis-python-graph](https://pypi.org/project/syrtis-python-graph/)
+

syrtis_python_graph-0.0.3/README.md

@@ -0,0 +1,85 @@
+# syrtis-python-graph
+
+Version: 0.0.3
+
+## Table of Contents
+
+- [Status Compatibility](#status-compatibility)
+- [Tests](#tests)
+- [Roadmap](#roadmap)
+- [Useful Links](#useful-links)
+
+
+## Status & Compatibility
+
+**Maturity**: Production-ready
+
+**Python Support**: >=3.10
+
+**OS Support**: Linux, macOS, Windows
+
+**Status**: Actively maintained
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-python_graph/issues) for upcoming features and improvements.
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-python-graph
+- **Documentation**: [docs.wexample.com](https://docs.wexample.com)
+- **Issue Tracker**: https://github.com/wexample/python-python-graph/issues
+- **Discussions**: https://github.com/wexample/python-python-graph/discussions
+- **PyPI**: [pypi.org/project/syrtis-python-graph](https://pypi.org/project/syrtis-python-graph/)
+

syrtis_python_graph-0.0.3/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[project]
+name = "syrtis-python-graph"
+version = "0.0.3"
+authors = [
+    { name = "weeger", email = "contact@syrtis.ai" },
+]
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.readme]
+file = "README.md"
+content-type = "text/markdown"
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+]
+
+[tool.setuptools.packages.find]
+include = [
+    "*",
+]
+exclude = [
+    "syrtis_python_graph.testing*",
+]
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.build]
+package-dir = "src"
+packages = [
+    { include = "syrtis_python_graph", from = "src" },
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+pythonpath = [
+    "src",
+]
+
+[tool.coverage.run]
+source = [
+    "syrtis_python_graph",
+]
+omit = [
+    "*/tests/*",
+    "*/.venv/*",
+    "*/venv/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]

syrtis_python_graph-0.0.3/src/syrtis_python_graph/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from syrtis_python_graph.checker.graph_readiness_checker import GraphReadinessChecker
+from syrtis_python_graph.contract.graph_edge_interface import GraphEdgeInterface
+from syrtis_python_graph.contract.graph_node_interface import GraphNodeInterface
+from syrtis_python_graph.detector.graph_cycle_detector import GraphCycleDetector
+from syrtis_python_graph.model.cycle_detection_result import CycleDetectionResult
+from syrtis_python_graph.model.graph_definition import GraphDefinition
+from syrtis_python_graph.resolver.graph_resolver import GraphResolver
+
+__all__ = [
+    "GraphNodeInterface",
+    "GraphEdgeInterface",
+    "GraphDefinition",
+    "CycleDetectionResult",
+    "GraphCycleDetector",
+    "GraphReadinessChecker",
+    "GraphResolver",
+]

syrtis_python_graph-0.0.3/src/syrtis_python_graph/checker/graph_readiness_checker.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from syrtis_python_graph.model.graph_definition import GraphDefinition
+
+
+class GraphReadinessChecker:
+    def is_ready(
+        self,
+        node_id: str | int,
+        completed_ids: list[str | int],
+        definition: GraphDefinition,
+        back_edges: list[tuple[str | int, str | int]] | None = None,
+    ) -> bool:
+        completed_set = {str(i) for i in completed_ids}
+        back_edge_set = {(src, tgt) for src, tgt in (back_edges or [])}
+
+        for edge in definition.get_incoming_edges(node_id):
+            if (edge.get_source_node_id(), edge.get_target_node_id()) in back_edge_set:
+                continue
+            if str(edge.get_source_node_id()) not in completed_set:
+                return False
+
+        return True

syrtis_python_graph-0.0.3/src/syrtis_python_graph/contract/graph_edge_interface.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class GraphEdgeInterface(ABC):
+    @abstractmethod
+    def get_graph_id(self) -> str | int:
+        pass
+
+    @abstractmethod
+    def get_source_node_id(self) -> str | int:
+        pass
+
+    @abstractmethod
+    def get_source_port(self) -> str | None:
+        pass
+
+    @abstractmethod
+    def get_target_node_id(self) -> str | int:
+        pass
+
+    @abstractmethod
+    def get_target_port(self) -> str | None:
+        pass

syrtis_python_graph-0.0.3/src/syrtis_python_graph/contract/graph_node_interface.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class GraphNodeInterface(ABC):
+    @abstractmethod
+    def get_graph_id(self) -> str | int:
+        pass

syrtis_python_graph-0.0.3/src/syrtis_python_graph/detector/graph_cycle_detector.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from syrtis_python_graph.model.cycle_detection_result import CycleDetectionResult
+from syrtis_python_graph.model.graph_definition import GraphDefinition
+
+_WHITE = 0
+_GRAY = 1
+_BLACK = 2
+
+
+class GraphCycleDetector:
+    def detect(self, definition: GraphDefinition) -> CycleDetectionResult:
+        color: dict[str | int, int] = {}
+        parent: dict[str | int, str | int | None] = {}
+        back_edges: list[tuple[str | int, str | int]] = []
+        cycles: list[list[str | int]] = []
+
+        for node_id in definition.get_nodes():
+            color[node_id] = _WHITE
+            parent[node_id] = None
+
+        for node_id in definition.get_nodes():
+            if color[node_id] == _WHITE:
+                self._dfs(node_id, definition, color, parent, back_edges, cycles)
+
+        nodes_in_cycles: set[str | int] = {
+            node_id for cycle in cycles for node_id in cycle
+        }
+
+        return CycleDetectionResult(
+            has_cycles=bool(back_edges),
+            cycles=cycles,
+            back_edges=back_edges,
+            nodes_in_cycles=nodes_in_cycles,
+        )
+
+    def _dfs(
+        self,
+        node_id: str | int,
+        definition: GraphDefinition,
+        color: dict[str | int, int],
+        parent: dict[str | int, str | int | None],
+        back_edges: list[tuple[str | int, str | int]],
+        cycles: list[list[str | int]],
+    ) -> None:
+        color[node_id] = _GRAY
+
+        for edge in definition.get_outgoing_edges(node_id):
+            target_id = edge.get_target_node_id()
+
+            if color.get(target_id) == _GRAY:
+                back_edges.append((node_id, target_id))
+                cycles.append(self._extract_cycle(node_id, target_id, parent))
+            elif color.get(target_id, _WHITE) == _WHITE:
+                parent[target_id] = node_id
+                self._dfs(target_id, definition, color, parent, back_edges, cycles)
+
+        color[node_id] = _BLACK
+
+    def _extract_cycle(
+        self,
+        from_id: str | int,
+        to_id: str | int,
+        parent: dict[str | int, str | int | None],
+    ) -> list[str | int]:
+        cycle: list[str | int] = [from_id]
+        current: str | int = from_id
+
+        while current != to_id:
+            current = parent[current]  # type: ignore[assignment]
+            cycle.append(current)
+
+        return list(reversed(cycle))

syrtis_python_graph-0.0.3/src/syrtis_python_graph/model/cycle_detection_result.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class CycleDetectionResult:
+    back_edges: list[tuple[str | int, str | int]]
+    cycles: list[list[str | int]]
+    has_cycles: bool
+
+    nodes_in_cycles: set[str | int] = field(default_factory=set)
+
+    def is_back_edge(self, source_id: str | int, target_id: str | int) -> bool:
+        return (source_id, target_id) in self.back_edges

syrtis_python_graph-0.0.3/src/syrtis_python_graph/model/graph_definition.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from syrtis_python_graph.contract.graph_edge_interface import GraphEdgeInterface
+from syrtis_python_graph.contract.graph_node_interface import GraphNodeInterface
+
+
+class GraphDefinition:
+    def __init__(self) -> None:
+        self._nodes: dict[str | int, GraphNodeInterface] = {}
+        self._edges: dict[str | int, GraphEdgeInterface] = {}
+        self._outgoing: dict[str | int, list[GraphEdgeInterface]] = {}
+        self._incoming: dict[str | int, list[GraphEdgeInterface]] = {}
+
+    def add_edge(self, edge: GraphEdgeInterface) -> None:
+        edge_id = edge.get_graph_id()
+        source_id = edge.get_source_node_id()
+        target_id = edge.get_target_node_id()
+
+        self._edges[edge_id] = edge
+        self._outgoing.setdefault(source_id, []).append(edge)
+        self._incoming.setdefault(target_id, []).append(edge)
+
+    def add_node(self, node: GraphNodeInterface) -> None:
+        node_id = node.get_graph_id()
+        self._nodes[node_id] = node
+        self._outgoing.setdefault(node_id, [])
+        self._incoming.setdefault(node_id, [])
+
+    def get_edges(self) -> dict[str | int, GraphEdgeInterface]:
+        return self._edges
+
+    def get_incoming_edges(self, node_id: str | int) -> list[GraphEdgeInterface]:
+        return self._incoming.get(node_id, [])
+
+    def get_node(self, node_id: str | int) -> GraphNodeInterface | None:
+        return self._nodes.get(node_id)
+
+    def get_nodes(self) -> dict[str | int, GraphNodeInterface]:
+        return self._nodes
+
+    def get_outgoing_edges(self, node_id: str | int) -> list[GraphEdgeInterface]:
+        return self._outgoing.get(node_id, [])

syrtis_python_graph-0.0.3/src/syrtis_python_graph/resolver/graph_resolver.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from syrtis_python_graph.contract.graph_node_interface import GraphNodeInterface
+from syrtis_python_graph.model.graph_definition import GraphDefinition
+
+
+class GraphResolver:
+    def __init__(self, definition: GraphDefinition) -> None:
+        self._definition = definition
+
+    def get_end_nodes(self) -> list[GraphNodeInterface]:
+        return [
+            node
+            for node in self._definition.get_nodes().values()
+            if not self._definition.get_outgoing_edges(node.get_graph_id())
+        ]
+
+    def get_predecessor_ids(self, node_id: str | int) -> list[str | int]:
+        return [
+            edge.get_source_node_id()
+            for edge in self._definition.get_incoming_edges(node_id)
+        ]
+
+    def get_predecessors(self, node_id: str | int) -> list[GraphNodeInterface]:
+        return [
+            node
+            for edge in self._definition.get_incoming_edges(node_id)
+            if (node := self._definition.get_node(edge.get_source_node_id()))
+            is not None
+        ]
+
+    def get_start_nodes(self) -> list[GraphNodeInterface]:
+        return [
+            node
+            for node in self._definition.get_nodes().values()
+            if not self._definition.get_incoming_edges(node.get_graph_id())
+        ]
+
+    def get_successor_ids(self, node_id: str | int) -> list[str | int]:
+        return [
+            edge.get_target_node_id()
+            for edge in self._definition.get_outgoing_edges(node_id)
+        ]
+
+    def get_successors(self, node_id: str | int) -> list[GraphNodeInterface]:
+        return [
+            node
+            for edge in self._definition.get_outgoing_edges(node_id)
+            if (node := self._definition.get_node(edge.get_target_node_id()))
+            is not None
+        ]