Add type hints and mypy workflow

.github/workflows/mypy.yml

@@ -0,0 +1,19 @@
+name: mypy check
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master, dev]
+
+jobs:
+  static-type-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - run: pip install mypy
+    - name: Type checking and install type stubs for third-party packages
+      run: mypy --install-types --non-interactive src
+

pyproject.toml

@@ -95,3 +95,12 @@ disable = "C0330, C0326"
 
 [tool.pylint.format]
 max-line-length = "88"
+
+[tool.mypy]
+python_version = 3.12
+exclude = ["prov/tests/*"]
+
+[[tool.mypy.overrides]]
+module = "prov.*"
+disallow_untyped_defs = true
+check_untyped_defs = true

src/prov/__init__.py

@@ -1,17 +1,26 @@
+from __future__ import annotations  # needed for | type annotations in Python < 3.10
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from prov.model import ProvDocument
+
 __author__ = "Trung Dong Huynh"
 __email__ = "trungdong@donggiang.com"
 __version__ = "2.0.2"
 
 __all__ = ["Error", "model", "read"]
 
 
+
+
 class Error(Exception):
     """Base class for all errors in this package."""
 
     pass
 
 
-def read(source, format=None):
+def read(source: str | bytes | os.PathLike, format: str | None = None) -> ProvDocument | None:
     """
     Convenience function returning a ProvDocument instance.
 
@@ -39,6 +48,7 @@
         try:
             return ProvDocument.deserialize(source=source, format=format)
         except:
+            # TODO: Specify an exception type for failing to deserialize.
             pass
     else:
         raise TypeError(

src/prov/constants.py

@@ -186,6 +186,7 @@
 PROV_ROLE = PROV["role"]
 
 PROV_QUALIFIEDNAME = PROV["QUALIFIED_NAME"]
+PROV_INTERNATIONALIZEDSTRING = PROV["InternationalizedString"]
 
 # XSD DATA TYPES
 XSD_ANYURI = XSD["anyURI"]

src/prov/dot.py

@@ -11,9 +11,14 @@
 
 .. moduleauthor:: Trung Dong Huynh <trungdong@donggiang.com>
 """
+
+from __future__ import annotations  # needed for | type annotations in Python < 3.10
 from datetime import datetime
+from html import escape
+from typing import Any, Optional
 
 from prov.graph import INFERRED_ELEMENT_CLASS
+from prov.identifier import QualifiedName
 from prov.model import (
     ProvEntity,
     ProvActivity,
@@ -42,13 +47,10 @@
     PROV_ATTRIBUTE_QNAMES,
     sorted_attributes,
     ProvException,
+    ProvRecord,
+    ProvElement,
 )
-import pydot
-
-try:
-    from html import escape
-except ImportError:
-    from cgi import escape
+import pydot  # type: ignore[import]
 
 __author__ = "Trung Dong Huynh"
 __email__ = "trungdong@donggiang.com"
@@ -87,7 +89,7 @@
         "fillcolor": "lightgray",
         "color": "dimgray",
     },
-}
+}  # type: dict[Optional[type[ProvElement | ProvBundle]], dict[str, str]]
 DOT_PROV_STYLE = {
     # Generic node
     0: {
@@ -166,7 +168,7 @@
 ANNOTATION_END_ROW = "    </TABLE>>"
 
 
-def htlm_link_if_uri(value):
+def htlm_link_if_uri(value: Any) -> str:
     try:
         uri = value.uri
         return '<a href="%s">%s</a>' % (uri, str(value))
@@ -175,13 +177,13 @@ def htlm_link_if_uri(value):
 
 
 def prov_to_dot(
-    bundle,
-    show_nary=True,
-    use_labels=False,
-    direction="BT",
-    show_element_attributes=True,
-    show_relation_attributes=True,
-):
+    bundle: ProvBundle,
+    show_nary: bool = True,
+    use_labels: bool = False,
+    direction: str = "BT",
+    show_element_attributes: bool = True,
+    show_relation_attributes: bool = True,
+) -> pydot.Dot:
     """
     Convert a provenance bundle/document into a DOT graphical representation.
 
@@ -203,11 +205,11 @@ def prov_to_dot(
         direction = "BT"  # reset it to the default value
     maindot = pydot.Dot(graph_type="digraph", rankdir=direction, charset="utf-8")
 
-    node_map = {}
+    node_map = {}  # type: dict[str, pydot.Node]
     count = [0, 0, 0, 0]  # counters for node ids
 
-    def _bundle_to_dot(dot, bundle):
-        def _attach_attribute_annotation(node, record):
+    def _bundle_to_dot(dot: pydot.Dot | pydot.Cluster, bundle: ProvBundle) -> None:
+        def _attach_attribute_annotation(node: pydot.Node, record: ProvRecord) -> None:
             # Adding a node to show all attributes
             attributes = list(
                 (attr_name, value)
@@ -244,17 +246,17 @@ def _attach_attribute_annotation(node, record):
             dot.add_node(annotations)
             dot.add_edge(pydot.Edge(annotations, node, **ANNOTATION_LINK_STYLE))
 
-        def _add_bundle(bundle):
+        def _add_bundle(bundle: ProvBundle) -> pydot.Cluster:
             count[2] += 1
             subdot = pydot.Cluster(
-                graph_name="c%d" % count[2], URL=f'"{bundle.identifier.uri}"'
+                graph_name="c%d" % count[2], URL=f'"{bundle.identifier.uri}"'  # type: ignore[union-attr]
             )
             subdot.set_label('"%s"' % str(bundle.identifier))
             _bundle_to_dot(subdot, bundle)
             dot.add_subgraph(subdot)
             return subdot
 
-        def _add_node(record):
+        def _add_node(record: ProvRecord) -> pydot.Node:
             count[0] += 1
             node_id = "n%d" % count[0]
             if use_labels:
@@ -267,12 +269,12 @@ def _add_node(record):
                     node_label = (
                         f"<{record.label}<br />"
                         f'<font color="#333333" point-size="10">'
-                        f'{record.identifier}</font>>'
+                        f"{record.identifier}</font>>"
                     )
             else:
                 node_label = f'"{record.identifier}"'
 
-            uri = record.identifier.uri
+            uri = record.identifier.uri  # type: ignore[union-attr]
             style = DOT_PROV_STYLE[record.get_type()]
             node = pydot.Node(node_id, label=node_label, URL='"%s"' % uri, **style)
             node_map[uri] = node
@@ -282,7 +284,9 @@ def _add_node(record):
                 _attach_attribute_annotation(node, rec)
             return node
 
-        def _add_generic_node(qname, prov_type=None):
+        def _add_generic_node(
+            qname: QualifiedName, prov_type: Optional[type[ProvElement]] = None
+        ) -> pydot.Node:
             count[0] += 1
             node_id = "n%d" % count[0]
             node_label = f'"{qname}"'
@@ -294,14 +298,17 @@ def _add_generic_node(qname, prov_type=None):
             dot.add_node(node)
             return node
 
-        def _get_bnode():
+        def _get_bnode() -> pydot.Node:
             count[1] += 1
             bnode_id = "b%d" % count[1]
             bnode = pydot.Node(bnode_id, label='""', shape="point", color="gray")
             dot.add_node(bnode)
             return bnode
 
-        def _get_node(qname, prov_type=None):
+        def _get_node(
+            qname: Optional[QualifiedName],
+            prov_type: Optional[type[ProvElement]] = None,
+        ) -> pydot.Node:
             if qname is None:
                 return _get_bnode()
             uri = qname.uri
@@ -382,7 +389,7 @@ def _get_node(qname, prov_type=None):
                 if add_attribute_annotation:
                     _attach_attribute_annotation(bnode, rec)
             else:
-                # show a simple binary relations with no annotation
+                # show a simple binary relation with no annotation
                 dot.add_edge(
                     pydot.Edge(
                         _get_node(nodes[0], inferred_types[0]),

src/prov/graph.py

@@ -56,15 +56,15 @@
 }
 
 
-def prov_to_graph(prov_document):
+def prov_to_graph(prov_document: ProvDocument) -> nx.MultiDiGraph:
     """
     Convert a :class:`~prov.model.ProvDocument` to a `MultiDiGraph
     <https://networkx.github.io/documentation/stable/reference/classes/multidigraph.html>`_
     instance of the `NetworkX <https://networkx.github.io/>`_ library.
 
     :param prov_document: The :class:`~prov.model.ProvDocument` instance to convert.
     """
-    g = nx.MultiDiGraph()
+    g = nx.MultiDiGraph()  # type: nx.MultiDiGraph
     unified = prov_document.unified()
     node_map = dict()
     for element in unified.get_records(ProvElement):
@@ -89,7 +89,7 @@ def prov_to_graph(prov_document):
     return g
 
 
-def graph_to_prov(g):
+def graph_to_prov(g: nx.MultiDiGraph) -> ProvDocument:
     """
     Convert a `MultiDiGraph
     <https://networkx.github.io/documentation/stable/reference/classes/multidigraph.html>`_