Merge enhancement into master

Author: unsektor

.github/workflows/ci.yaml

@@ -0,0 +1,118 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    tags: '*.*.*'
+  release:
+    types: [ published ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - '3.8'
+          - '3.9'
+          - '3.10'
+          - '3.11'
+          - '3.12'
+          - '3.13'
+          - '3.14'
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install pytest pytest-cov
+        # pip install -e ".[test]"
+
+    - name: Run tests
+      run: |
+        # python -m pytest tests/ --cov=lib --cov-report=xml
+        export PYTHONPATH="$(pwd -P)/lib:$PYTHONPATH"
+        python -m pytest tests/unit/md/python/graph.py --cov=lib --cov-report=term
+
+    # - name: Upload coverage to Codecov
+    #   uses: codecov/codecov-action@v3
+    #   if: matrix.python-version == '3.10'
+    #   with:
+    #     file: ./coverage.xml
+    #     fail_ci_if_error: true
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install safety
+      run: pip install safety
+
+    - name: Check dependencies for vulnerabilities
+      run: safety check --full-report
+
+    - name: Install bandit
+      run: pip install bandit
+
+    - name: Static security analysis
+      run: bandit -r lib/ -f json -o bandit-report.json --skip B101
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install mypy
+      run: pip install mypy
+
+    - name: Type checking
+      run: |
+        export PYTHONPATH="$(pwd -P)/lib:$PYTHONPATH"
+        mypy lib/ --disable-error-code import-untyped
+
+  build:
+    needs: [test, security, type-check]
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install build dependencies
+      run: pip install build wheel
+
+    - name: Build wheel package
+      run: python -m build --wheel
+
+    - name: List artifacts
+      run: ls -la dist/
+
+    - name: Upload wheel to GitHub Releases
+      uses: svenstaro/upload-release-action@v2
+      with:
+        repo_token: ${{ secrets.GITHUB_TOKEN }}
+        file: dist/*.whl
+        tag: ${{ github.ref }}
+        overwrite: true
+        file_glob: true

changelog.md

@@ -5,8 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2025-12-28
+### Added
+
+- [x] feature: add CI/CD github workflow configuration
+
+### Changed
+
+- [x] enhancement: clarify generics types to explicit, fix `mypy` errors
+
 ## [1.0.0] - 2024-09-01
 
 - Initial implementation
 
+[1.1.0]: https://github.com/md-py/md.python.graph/releases/compare/1.0.0...1.1.0
 [1.0.0]: https://github.com/md-py/md.python.graph/releases/tag/1.0.0

docs/_static/architecture-overview.class-diagram.png

@@ -15,19 +15,19 @@ package md.python.graph {
     + CYCLE_DETECTED = 1
   }
 
-  interface TopologicalSortInterface {
-    + sort(graph: GraphType) -> Iterable[NodeType]
+  interface TopologicalSortInterface <NodeType of typing.Hashable> {
+    + sort(graph: GraphType[NodeType]) -> Iterable[NodeType]
   }
 
-  class AscendingTopologicalSort {
-    + sort(graph: GraphType) -> Iterable[NodeType]
+  class AscendingTopologicalSort <NodeType of typing.Hashable> {
+    + sort(graph: GraphType[NodeType]) -> Iterable[NodeType]
   }
 
-  class DescendingTopologicalSort {
-    + sort(graph: GraphType) -> Iterable[NodeType]
+  class DescendingTopologicalSort <NodeType of typing.Hashable> {
+    + sort(graph: GraphType[NodeType]) -> Iterable[NodeType]
   }
 
-  AscendingTopologicalSort .left.> TopologicalSortException : raises
+  AscendingTopologicalSort .left.> TopologicalSortException : raises >
   AscendingTopologicalSort -up-|>  TopologicalSortInterface
   DescendingTopologicalSort -up-|>  TopologicalSortInterface
 }

docs/_static/architecture-overview.class-diagram.puml

@@ -15,19 +15,19 @@ graph type, and provides few useful tools out from box.
 NodeType = typing.TypeVar('NodeType', bound=typing.Hashable)
 GraphType = typing.Mapping[NodeType, typing.Collection[NodeType]]
 GraphPathType = typing.Iterable[NodeType]
-TopologicalSortType = typing.Callable[[GraphType], typing.Iterable[NodeType]]
+TopologicalSortType = typing.Callable[[GraphType[NodeType]], typing.Iterable[NodeType]]
 
 # Implementation 
-def topological_sort_ascending(graph: GraphType) -> typing.Iterable[NodeType]: ...
+def topological_sort_ascending(graph: GraphType[NodeType]) -> typing.Iterable[NodeType]: ...
 
 def topological_sort_descending(
-    graph: GraphType,
+    graph: GraphType[NodeType],
     initial_node: typing.Iterable[NodeType] = None
 ) -> typing.Iterable[NodeType]: ...
 
-def get_paths(graph: GraphType, include_subtree: bool = False) -> typing.Tuple[
-    typing.List[GraphPathType],
-    typing.List[GraphPathType],
+def get_paths(graph: GraphType[NodeType], include_subtree: bool = False) -> typing.Tuple[
+    typing.List[GraphPathType[NodeType]],
+    typing.List[GraphPathType[NodeType]],
 ]: ...
 ```
 
@@ -54,7 +54,7 @@ but defines algorithm direction of nodes traversing.
 #### Ascending topological sorting
 
 ```python3
-def topological_sort_ascending(graph: GraphType) -> typing.Iterable[NodeType]: ...
+def topological_sort_ascending(graph: GraphType[NodeType]) -> typing.Iterable[NodeType]: ...
 ```
 
 Ascending topological sorting performs sorting from the bottom to the top,
@@ -117,7 +117,7 @@ a cycle (see [get_path](#graph-paths-retrieval) below, for example).
 
 ```python3
 def topological_sort_descending(
-    graph: GraphType,
+    graph: GraphType[NodeType],
     initial_node: typing.Iterable[NodeType] = None
 ) -> typing.Iterable[NodeType]: ...
 ```
@@ -188,9 +188,9 @@ and default implementation:
 ### Graph paths retrieval
 
 ```python3
-def get_paths(graph: GraphType, include_subtree: bool = False) -> typing.Tuple[
-    typing.List[GraphPathType],
-    typing.List[GraphPathType],
+def get_paths(graph: GraphType[NodeType], include_subtree: bool = False) -> typing.Tuple[
+    typing.List[GraphPathType[NodeType]],
+    typing.List[GraphPathType[NodeType]],
 ]: ...
 ```
 

docs/_static/architecture-overview.class-diagram.svg

@@ -3,7 +3,7 @@
 
 # Metadata
 __author__ = 'https://md.land/md'
-__version__ = '1.0.0'
+__version__ = '1.1.0'
 __all__ = (
     # Metadata
     '__author__',
@@ -40,13 +40,13 @@ class GraphExceptionInterface:
 class TopologicalSortException(RuntimeError, GraphExceptionInterface):
     CYCLE_DETECTED = 1
 
-    def __init__(self, *args, code: int = 0, graph: GraphType = None, **kwargs) -> None:
-        super().__init__(*args, **kwargs)
+    def __init__(self, *args, code: int = 0, graph: typing.Optional[GraphType] = None) -> None:
+        super().__init__(*args)
         self.code = code
         self.graph = graph
 
     @classmethod
-    def as_cycle_detected(class_, graph: GraphType = None) -> 'TopologicalSortException':
+    def as_cycle_detected(class_, graph: typing.Optional[GraphType] = None) -> 'TopologicalSortException':
         return class_(
             'Unable to perform topological sort, graph contains a cycle',
             code=class_.CYCLE_DETECTED,
@@ -55,8 +55,8 @@ def as_cycle_detected(class_, graph: GraphType = None) -> 'TopologicalSortExcept
 
 
 # Contract
-class TopologicalSortInterface:
-    def sort(self, graph: GraphType) -> typing.Iterable[NodeType]:
+class TopologicalSortInterface(typing.Generic[NodeType]):
+    def sort(self, graph: GraphType[NodeType]) -> typing.Iterable[NodeType]:
         """
         Performs graph topological sorting and returns sequence of nodes
         :param graph: Generic graph structure represented by Mapping of Hashable nodes
@@ -66,7 +66,7 @@ def sort(self, graph: GraphType) -> typing.Iterable[NodeType]:
 
 
 # Implementation
-def topological_sort_ascending(graph: GraphType) -> typing.Iterable[NodeType]:
+def topological_sort_ascending(graph: GraphType[NodeType]) -> typing.Iterable[NodeType]:
     """
     Performs graph topological sorting and returns sequence of nodes (from the bottom)
 
@@ -82,7 +82,7 @@ def topological_sort_ascending(graph: GraphType) -> typing.Iterable[NodeType]:
     for node, related_node_collection in graph.items():
         normalized_graph[node] = set(related_node_collection)
 
-    leave_node_set = set()
+    leave_node_set: typing.Set[NodeType] = set()
 
     # 2. Search for nodes which are not explicitly defined as an empty graph
     for related_node_set in normalized_graph.values():
@@ -100,7 +100,7 @@ def topological_sort_ascending(graph: GraphType) -> typing.Iterable[NodeType]:
             break
 
         try:
-            yield from sorted(leave_node_set)
+            yield from sorted(leave_node_set)  # type: ignore
         except TypeError:
             yield from leave_node_set
 
@@ -116,8 +116,8 @@ def topological_sort_ascending(graph: GraphType) -> typing.Iterable[NodeType]:
 
 
 def topological_sort_descending(
-    graph: GraphType,
-    initial_node: typing.Iterable[NodeType] = None
+    graph: GraphType[NodeType],
+    initial_node: typing.Optional[typing.Iterable[NodeType]] = None
 ) -> typing.Iterable[NodeType]:
     """
     Performs graph topological sorting and returns sequence of nodes (from the top)
@@ -160,9 +160,9 @@ def topological_sort_descending(
                 yield pending_node
 
 
-def get_paths(graph: GraphType, include_subtree: bool = False) -> typing.Tuple[
-    typing.List[GraphPathType],  # path list without cycle
-    typing.List[GraphPathType],  # path list with cycle
+def get_paths(graph: GraphType[NodeType], include_subtree: bool = False) -> typing.Tuple[
+    typing.Sequence[GraphPathType[NodeType]],  # path list without cycle
+    typing.Sequence[GraphPathType[NodeType]],  # path list with cycle
 ]:
     """
     Returns two-sized tuple of graph paths list:
@@ -209,9 +209,9 @@ def get_paths(graph: GraphType, include_subtree: bool = False) -> typing.Tuple[
     # 2. Build result
     node_list = elder_node_heap
     if include_subtree:
-        node_list = node_path_map.keys()
+        node_list = list(node_path_map.keys())
 
-    path_list: typing.List[GraphPathType] = []
+    path_list: typing.List[GraphPathType[NodeType]] = []
     cycle_path_list = []
 
     for root_node in node_list:
@@ -223,11 +223,11 @@ def get_paths(graph: GraphType, include_subtree: bool = False) -> typing.Tuple[
     return path_list, cycle_path_list
 
 
-class AscendingTopologicalSort(TopologicalSortInterface, typing.Generic[NodeType]):
-    def sort(self, graph: GraphType) -> typing.Iterable[NodeType]:
+class AscendingTopologicalSort(TopologicalSortInterface[NodeType]):
+    def sort(self, graph: GraphType[NodeType]) -> typing.Iterable[NodeType]:
         return topological_sort_ascending(graph=graph)
 
 
-class DescendingTopologicalSort(TopologicalSortInterface, typing.Generic[NodeType]):
-    def sort(self, graph: GraphType) -> typing.Iterable[NodeType]:
+class DescendingTopologicalSort(TopologicalSortInterface[NodeType]):
+    def sort(self, graph: GraphType[NodeType]) -> typing.Iterable[NodeType]:
         return topological_sort_descending(graph=graph)

docs/index.md

@@ -14,19 +14,19 @@ graph type, and provides few useful tools out from box.
 NodeType = typing.TypeVar('NodeType', bound=typing.Hashable)
 GraphType = typing.Mapping[NodeType, typing.Collection[NodeType]]
 GraphPathType = typing.Iterable[NodeType]
-TopologicalSortType = typing.Callable[[GraphType], typing.Iterable[NodeType]]
+TopologicalSortType = typing.Callable[[GraphType[NodeType]], typing.Iterable[NodeType]]
 
 # Implementation 
-def topological_sort_ascending(graph: GraphType) -> typing.Iterable[NodeType]: ...
+def topological_sort_ascending(graph: GraphType[NodeType]) -> typing.Iterable[NodeType]: ...
 
 def topological_sort_descending(
-    graph: GraphType,
+    graph: GraphType[NodeType],
     initial_node: typing.Iterable[NodeType] = None
 ) -> typing.Iterable[NodeType]: ...
 
-def get_paths(graph: GraphType, include_subtree: bool = False) -> typing.Tuple[
-    typing.List[GraphPathType],
-    typing.List[GraphPathType],
+def get_paths(graph: GraphType[NodeType], include_subtree: bool = False) -> typing.Tuple[
+    typing.List[GraphPathType[NodeType]],
+    typing.List[GraphPathType[NodeType]],
 ]: ...
 ```
 

lib/md/python/graph.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name='md.python.graph',
-    version='1.0.0',
+    version='1.1.0',
     description='Set of contracts & operations over graph type',
     long_description=long_description,
     long_description_content_type='text/markdown',