chore: add mypy and update type hints across codebase (#54)

- Update type hints throughout codebase
- Configure mypy for type checking
- Add type checking to CI pipeline and documentation

Author: AlrasheedA

.github/workflows/pr_checks.yml

@@ -27,6 +27,9 @@ jobs:
       - name: 'Ruff Check'
         run: |
           ruff check --output-format=github
+      - name: 'MyPy Check'
+        run: |
+          mypy st_link_analysis/
 
   lint_js:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable changes to this project will be documented in this file.
     Thanks to @drachenbach for the PR.  ([#39](https://github.com/AlrasheedA/st-link-analysis/pull/39))
 -   9 new Material icons to frontend assets. ([#47](https://github.com/AlrasheedA/st-link-analysis/pull/47))
 -   Support for dynamically loading debug pages from the `examples/debug/` directory in demo's `app.py`
+-   Added mypy in the development workflow. Updated type hints throughout the codebase.
 
 ### Fixed
 -   Prevent accumulating multiple `.svg` extensions on repeated calls of `dump` 

README.md

@@ -26,7 +26,7 @@ A demo deployed with Render can be [accessed here](https://st-link-analysis-demo
     -   View control bar for zooming, fitting, and centering the view, making it easier to navigate your graphs.
     -   View all properties of the selected elements in a side panel.
     -   Highlights neighboring nodes or edges when an element is selected.
--   **Node Actions (Expand / Remove):** Enable node removal and expansion using the `node_actions` parameter. Removal can be triggered by a delete keydown or a remove button click, while expansion occurs on a double-click or expand button click. When these events are triggered, the event details and selected node IDs are sent back to the Streamlit app as the component’s return value.
+-   **Node Actions (Expand / Remove):** Enable node removal and expansion using the `node_actions` parameter. Removal can be triggered by a delete keydown or a remove button click, while expansion occurs on a double-click or expand button click. When these events are triggered, the event details and selected node IDs are sent back to the Streamlit app as the component's return value.
 
 ## Installation
 
@@ -136,13 +136,24 @@ streamlit run app.py
 
 ### Testing
 
-Run linting and tests:
+Run linting, type checking, and tests:
 
 ```bash
 ruff check
+mypy st_link_analysis/
 pytest
 ```
 
+### Type Checking
+
+This project uses type hints and mypy for static type checking to improve code maintainability and developer experience. The mypy configuration is defined in `pyproject.toml` with strict settings to catch potential type-related issues early.
+
+To run type checking locally:
+
+```bash
+mypy st_link_analysis/
+```
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

pyproject.toml

@@ -41,6 +41,21 @@ indent-width = 4
 select = ["E4", "E7", "E9", "F"]
 fixable = ["ALL"]
 
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
 [tool.pytest.ini_options]
 addopts = "--reruns=3"
 
@@ -50,4 +65,5 @@ dev = [
   "pytest",
   "pytest-playwright",
   "pytest-rerunfailures",
+  "mypy",
 ]

st_link_analysis/component/component.py

@@ -1,7 +1,7 @@
 import os
 import warnings
 import streamlit.components.v1 as components
-from typing import Optional, Union, Callable, Literal
+from typing import Optional, Union, Callable, Literal, Dict, Any, List
 
 from st_link_analysis.component.layouts import LAYOUTS
 from st_link_analysis.component.styles import NodeStyle, EdgeStyle
@@ -33,17 +33,17 @@ class LinkAnalysisDeprecationWarning(DeprecationWarning):
 
 
 def st_link_analysis(
-    elements: dict,
-    layout: Union[str, dict] = "cose",
-    node_styles: list[NodeStyle] = [],
-    edge_styles: list[EdgeStyle] = [],
+    elements: Dict[str, Any],
+    layout: Union[str, Dict[str, Any]] = "cose",
+    node_styles: List[NodeStyle] = [],
+    edge_styles: List[EdgeStyle] = [],
     height: int = 500,
     key: Optional[str] = None,
     on_change: Optional[Callable[..., None]] = None,
-    node_actions: list[Literal["remove", "expand"]] = [],
+    node_actions: List[Literal["remove", "expand"]] = [],
     enable_node_actions: Optional[bool] = None,  # deprecated
-    events: list[Event] = [],
-) -> None:
+    events: List[Event] = [],
+) -> Any:
     """
     Renders a link analysis graph using Cytoscape in Streamlit.
 
@@ -88,16 +88,18 @@ def st_link_analysis(
         app as the component's return value. NOTE: only defined once. Changing the
         list of events requires remounting the component.
     """
-    node_styles = [n.dump() for n in node_styles]
-    edge_styles = [e.dump() for e in edge_styles]
-    style = node_styles + edge_styles
+    node_styles_dump = [n.dump() for n in node_styles]
+    edge_styles_dump = [e.dump() for e in edge_styles]
+    style = node_styles_dump + edge_styles_dump
 
-    height = str(height) + "px"
+    height_str = str(height) + "px"
 
     if isinstance(layout, str):
-        layout = LAYOUTS[layout]
+        layout_config = LAYOUTS[layout]
+    else:
+        layout_config = layout
 
-    events = [e.dump() for e in events]
+    events_dump = [e.dump() for e in events]
 
     # TODO: remove in next version along with imports, docs, and signature
     if enable_node_actions is not None:
@@ -112,10 +114,10 @@ def st_link_analysis(
     return _component_func(
         elements=elements,
         style=style,
-        layout=layout,
-        height=height,
+        layout=layout_config,
+        height=height_str,
         key=key,
         on_change=on_change,
         nodeActions=node_actions,
-        events=events,
+        events=events_dump,
     )

st_link_analysis/component/events.py

@@ -1,6 +1,7 @@
 """
 For more details refer to https://js.cytoscape.org/#events
 """
+from typing import Dict
 
 RESERVED_NAMES = ["remove", "expand"]
 
@@ -37,7 +38,7 @@ def __init__(
         if name in RESERVED_NAMES:
             raise ValueError(f"{RESERVED_NAMES} are reserved action names")
 
-    def dump(self) -> dict:
+    def dump(self) -> Dict[str, str]:
         return {
             "name": self.name,
             "event_type": self.event_type,

st_link_analysis/component/styles.py

@@ -1,6 +1,5 @@
 import warnings
-
-from typing import Optional
+from typing import Optional, Dict, Any
 
 
 # TODO: remove if no depreciation warnings
@@ -47,7 +46,7 @@ def __init__(
         self.caption = caption
         self.icon = icon
 
-    def dump(self) -> dict:
+    def dump(self) -> Dict[str, Any]:
         selector = f"node[label='{self.label}']"
         style = {}
 
@@ -124,7 +123,7 @@ def __init__(
         if labeled and not caption:
             self.caption = "label"
 
-    def dump(self) -> dict:
+    def dump(self) -> Dict[str, Any]:
         selector = f"edge[label='{self.label}']"
         style = {}