taskdependencygraph 0.1.0__py3-none-any.whl

_taskdependencygraph_version.py

@@ -0,0 +1 @@
+version = "0.1.0"

taskdependencygraph/__init__.py

@@ -0,0 +1,8 @@
+"""
+taskdependencygraph is a library to model tasks and dependencies between tasks in a networkx DiGraph
+and give estimates when which task will be done
+"""
+
+from .task_dependency_graph import TaskDependencyGraph
+
+__all__ = ["TaskDependencyGraph"]

taskdependencygraph/models/__init__.py

@@ -0,0 +1,24 @@
+"""models are python objects which we use to model tasks, dependencies and the graph they form"""
+
+from .ids import PersonId, RunGroupId, RunGroupPersonRelationId, RunId, TaskDependencyId, TaskId
+from .person import Person
+from .task_dependency_edge import TaskDependencyEdge
+from .task_execution_status import TaskExecutionStatus
+from .task_node import TaskNode
+from .task_node_as_artificial_endnode import ID_OF_ARTIFICIAL_ENDNODE
+from .task_node_as_artificial_startnode import ID_OF_ARTIFICIAL_STARTNODE
+
+__all__ = [
+    "Person",
+    "RunId",
+    "RunGroupId",
+    "RunGroupPersonRelationId",
+    "TaskId",
+    "TaskDependencyId",
+    "PersonId",
+    "TaskNode",
+    "TaskDependencyEdge",
+    "TaskExecutionStatus",
+    "ID_OF_ARTIFICIAL_ENDNODE",
+    "ID_OF_ARTIFICIAL_STARTNODE",
+]

taskdependencygraph/models/ids.py

@@ -0,0 +1,38 @@
+"""
+contains ID types we use to differentiate between UUIDs
+"""
+
+import uuid
+from typing import NewType
+
+RunId = NewType("RunId", uuid.UUID)
+"""
+technically unique ID of a run
+"""
+
+RunGroupId = NewType("RunGroupId", uuid.UUID)
+"""
+technically unique ID of a run group
+"""
+
+RunGroupPersonRelationId = NewType("RunGroupPersonRelationId", uuid.UUID)
+"""
+technically unique ID the relation between a run group and a person
+"""
+
+TaskId = NewType("TaskId", uuid.UUID)
+"""
+technically unique ID of a task
+"""
+
+TaskDependencyId = NewType("TaskDependencyId", uuid.UUID)
+"""
+technically unique ID of a task dependency
+"""
+
+PersonId = NewType("PersonId", uuid.UUID)
+"""
+technically unique ID of a person
+"""
+# the __all__ fixes the mypy warning: Module "..." does not explicitly export attribute "TaskId"
+__all__ = ["RunId", "RunGroupId", "RunGroupPersonRelationId", "TaskId", "TaskDependencyId", "PersonId"]

taskdependencygraph/models/person.py

@@ -0,0 +1,27 @@
+"""
+Person domain model
+"""
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+# pylint: disable=too-few-public-methods
+# pylint: disable=duplicate-code
+class Person(BaseModel):
+    """
+    Entity 'person' includes anyone who uses the Cut Over Tool in whichever manner.
+    Persons are always humans. A person can act in multiple roles
+    (e.g. as assignee of one task and manager of another)
+    """
+
+    id: UUID = Field(default_factory=uuid4)
+    name: str
+    email: EmailStr
+    phone_number: str | None = None
+    slack_id: str | None = None
+    is_active: bool = True
+
+
+__all__ = ["Person"]

taskdependencygraph/models/task_dependency_edge.py

@@ -0,0 +1,45 @@
+"""
+task_dependency domain model object
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+from taskdependencygraph.models.ids import TaskDependencyId, TaskId
+
+
+class TaskDependencyEdge(BaseModel):
+    """
+    Task dependencies form the edges - i.e. interconnect task nodes - of the task dependency graph
+    """
+
+    model_config = ConfigDict(frozen=True)
+    # the Task has to be frozen/hashable to be used as a node in a networkx graph
+    # How to use model_config: https://docs.pydantic.dev/latest/api/config/#pydantic.config.ConfigDict.frozen
+    # NetworkX restrictions regarding "nodes have to be hashable":
+    # https://networkx.org/documentation/stable/reference/classes/generated/networkx.DiGraph.add_node.html
+
+    id: TaskDependencyId
+    """
+    Unique ID of this TaskDependency
+    """
+
+    task_predecessor: TaskId
+
+    """
+    Refers to the preceding task by means of its uuid
+    """
+
+    task_successor: TaskId
+    """
+    Refers to the succeeding task by means of its uuid
+    """
+
+    def to_dot(self) -> str:
+        """
+        returns a dot representation of this edge;
+        For details on the dot language see https://graphviz.org/doc/info/lang.html
+        """
+        return f'"{self.task_predecessor}" -> "{self.task_successor}"\n'
+
+
+__all__ = ["TaskDependencyEdge"]

taskdependencygraph/models/task_dependency_update.py

@@ -0,0 +1,61 @@
+"""
+When using the Task Dependency Graph in an application, these models are helpful to give the user feedback on whether
+the can or cannot add a task/node or dependency/edge to the graph.
+"""
+
+from typing import Self
+
+from pydantic import BaseModel, model_validator
+
+
+class AddNodeToGraphPreviewResponse(BaseModel):
+    """
+    Response to the frontends' request to potentially add a node to the TDG.
+    It's named 'preview' because the node is not actually added to the TDG yet.
+    """
+
+    can_be_added: bool  # we can 'translate' this to an 🟢🔴 icon in the FE/jinja template
+    """
+    true iff the node can be added to the TDG
+    """
+    error_message: str | None = None
+    """
+    error message if the node cannot be added to the TDG
+    """
+
+    @model_validator(mode="after")
+    def validate_there_is_an_error_message_if_necessary(self) -> Self:
+        """
+        Ensure that an error message is provided if the node cannot be added
+        """
+        if self.can_be_added is True or (self.can_be_added is False and self.error_message):
+            return self
+        raise ValueError("If the task can not be added, an error message must be provided")
+
+
+class AddEdgeToGraphPreviewResponse(BaseModel):
+    """
+    response to the frontends' request to potentially add an edge to the TDG
+    It's named 'preview' because the edge is not actually added to the TDG yet.
+    """
+
+    can_be_added: bool  # we can 'translate' this to an 🟢🔴 icon in the FE/jinja template
+    """
+    true iff the edge can be added to the TDG
+    """
+    error_message: str | None = None
+    """
+    error message if the edge cannot be added to the TDG
+    """
+
+    @model_validator(mode="after")
+    def validate_there_is_an_error_message_if_necessary(self) -> "Self":
+        """
+        Ensure that an error message is provided if the node cannot be added
+        """
+        if self.can_be_added is True or (self.can_be_added is False and self.error_message):
+            return self
+        raise ValueError("If the task can not be added, an error message must be provided")
+
+
+__all__ = ["AddEdgeToGraphPreviewResponse", "AddNodeToGraphPreviewResponse"]

taskdependencygraph/models/task_execution_status.py

@@ -0,0 +1,37 @@
+"""contains the taskexecutionstatus enum"""
+
+from enum import StrEnum
+
+
+class TaskExecutionStatus(StrEnum):
+    """
+    The task_execution_status specifies which status the execution of one task has.
+    The TaskExecutionStatus class makes sure that there are only four possible values for the execution_status of
+    tasks, which don't report an error.
+    """
+
+    NOT_YET_REQUESTED = "NOT_YET_REQUESTED"
+    """
+    The execution of the task has not yet been requested.
+    """
+    REQUESTED = "REQUESTED"
+    """
+    The execution of the task has been requested, but the assignee hasn't reported yet
+    that s/he has started the task.
+    """
+    STARTED = "STARTED"
+    """
+    The execution of the task has been requested and the assignee has reported that s/he has started
+    executing the task
+    """
+    COMPLETED = "COMPLETED"
+    """
+    The assignee has reported that the execution of the task has been completed.
+    """
+    OBSOLETE = "OBSOLETE"
+    """
+    The assignee has reported that the task is obsolete and does not need to be executed anymore.
+    """
+
+
+__all__ = ["TaskExecutionStatus"]

taskdependencygraph/models/task_node.py

@@ -0,0 +1,124 @@
+"""
+task domain model object
+"""
+
+from datetime import datetime, timedelta
+from typing import Annotated, Any, Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+from taskdependencygraph.models.ids import TaskId
+from taskdependencygraph.models.person import Person
+
+
+class TaskNode(BaseModel):
+    """
+    This is a task domain model for task instances, that we use as nodes in the task dependency graph.
+    It is _not_ the task MODEL, which helps to create task instance in the DB.
+    It is also _not_ the task DTO, which passes through the API.
+    """
+
+    model_config = ConfigDict(frozen=True)
+    # the Task has to be frozen/hashable to be used as a node in a networkx graph
+    # How to use model_config: https://docs.pydantic.dev/latest/api/config/#pydantic.config.ConfigDict.frozen
+    # NetworkX restrictions regarding "nodes have to be hashable":
+    # https://networkx.org/documentation/stable/reference/classes/generated/networkx.DiGraph.add_node.html
+
+    # Q: Why the 2 IDs (internal and external)?
+    # A: The internal ID is to identify tasks technically (e.g. in the database).
+    # It may also be used by the frontend to update 1 specific task instance.
+    # In this case, the external ID is not unique, because tasks with the same ID may exist in different graphs.
+    # The external ID is for human users to identify tasks (within a graph).
+    # In Excel, both internal and external ID were the same, because 2 runs resulted in 2 Excel sheets.
+    # There was no conflict or ambiguity because those tasks which shared the same ID were spread over multiple
+    # Excel files.
+    # We don't have multiple databases or tables for tasks in different graphs.
+    # Hence, we need the 2 IDs.
+
+    id: TaskId
+    """
+    The ID is technically unique.
+    No two task instances ever share the same id.
+    Other than the external_id the ID is usually autogenerated and less handy for the user, because it's a GUID and not
+    a small readable string.
+    """
+    external_id: Annotated[str, Field(min_length=1)]
+    """
+    The external_id is unique within a single TaskDependencyGraph.
+    It is, what the user 'sees' as an ID (Example: 'MS1000').
+    But it's not unique enough to identify a task in the database.
+    The value is initially provided by the frontend/user.
+    """
+    name: Annotated[str, Field(min_length=1)]
+    """
+    The name is not necessarily unique. 
+    Example: 'Beginn der Migrationsvorarbeiten'
+    The value is provided by the frontend.
+    """
+    phase: Annotated[str, Field(min_length=1)] | None = None
+    """ 
+    The task dependency graph is divided into phases by milestones.
+    Example: '1000'
+    The value may be provided by the frontend.
+    """
+    tags: list[Annotated[str, Field(min_length=1)]] | None = None
+    """
+    Tasks can have none, one or more tags. Tags are a possibility to group tasks.
+    Example: ['IS-U', 'Rechnungen'].
+    """
+    planned_duration: Annotated[timedelta, Field(min=timedelta(minutes=0))]
+    """ 
+    The planned_duration_minutes expresses how long the task execution is planned to last (in minutes).
+    Example: timedelta(minutes=600) (for 10h)
+    The value is provided by the frontend.
+    """
+    is_milestone: bool = False
+    """
+    Expresses if a task is a milestone.
+    Milestones are Pseudo-Tasks with duration = 0 and execution_status = COMPLETED.
+    It begins and ends a phase.
+    """
+
+    earliest_starttime: AwareDatetime | None = None
+    """
+    A possibility to set a fixed earliest start time for a task.
+    The task may only start at this datetime or later, even if predecessors finish earlier.
+    """
+
+    planned_duration_of_predecessor_tasks: Annotated[timedelta, Field(min=timedelta(minutes=0))] | None = None
+    """
+    The planned_duration_of_predecessor_tasks is the sum of the duration of the predecessor tasks. 
+    The planned_duration_of_predecessor_tasks expresses, how long it takes from the beginning of the first task 
+    to the task in question.
+    It is needed to calculate the the planned_start_time of the task in question, as the planned_start_time of the task
+    in question is calculated from the planned_start_time of the first task and the 
+    planned_duration_of_predecessor_tasks. 
+    Example: Example: timedelta(minutes=660) (for 11h)
+    This value is computed with the help of NetworkX.
+    """
+    planned_starting_time: datetime | None = None
+    """
+    The planned_start_time is the time when the execution of the task in question is planned to start.
+    It is calculated from the planned_start_time of the first task and the planned_duration_of_predecessor_tasks. 
+    """
+
+    assignee: Person | None = None
+    """
+    The assignee of the task.
+    """
+
+    def to_dot(self, attributes: dict[Literal["label", "color"], Any]) -> str:
+        """
+        returns a dot representation of this task/node
+        For details on the dot language see https://graphviz.org/doc/info/lang.html
+        """
+        # we always pass along the id of the node with the dot string to that the svg element has the ID "svg-<id>"
+        # https://graphviz.org/docs/attrs/id/
+        result = f'"{self.id}"[id="svg-{self.id}";'
+        for key, value in attributes.items():
+            result += f'{key}="{value}";'
+        result += "];\n"
+        return result
+
+
+__all__ = ["TaskNode"]

taskdependencygraph/models/task_node_as_artificial_endnode.py

@@ -0,0 +1,25 @@
+# pylint:disable=anomalous-backslash-in-string
+"""
+The task_node_as_artificial_endnode is a task node, which is added to the task dependency graph due to
+practical reasons: The artificial final task is needed in order to make the duration of the formerly last
+node(s)/task(s) count, when identifying the critical path.
+
+For more information: see app/core/task_dependency_graph/task_dependency_graph.py
+--> add_artificial_nodes_and_edges
+"""
+
+
+from datetime import timedelta
+from uuid import UUID
+
+from taskdependencygraph.models.ids import TaskId
+from taskdependencygraph.models.task_node import TaskNode
+
+ID_OF_ARTIFICIAL_ENDNODE: TaskId = TaskId(UUID("99999999-9999-9999-9999-999999999999"))
+task_node_as_artificial_endnode = TaskNode(
+    id=ID_OF_ARTIFICIAL_ENDNODE,
+    external_id="__END__",
+    name="END",
+    planned_duration=timedelta(minutes=0),
+)
+__all__ = ["ID_OF_ARTIFICIAL_ENDNODE", "task_node_as_artificial_endnode"]

taskdependencygraph/models/task_node_as_artificial_startnode.py

@@ -0,0 +1,22 @@
+"""
+The task_node_as_artificial_startnode is a task node with a duration of 0 minutes, which is added to the
+task dependency graph in order to have one single starting point - rather than one or more.
+This single startnode makes calculations with Networkx easier, i.e. the calculation of the duration of predecessor
+tasks on the critical path --> see app/core/task_dependency_graph/task_dependency_graph.py ->
+calculate_planned_duration_of_predecessor_tasks_on_critical_path
+"""
+
+from datetime import timedelta
+from uuid import UUID
+
+from taskdependencygraph.models.ids import TaskId
+from taskdependencygraph.models.task_node import TaskNode
+
+ID_OF_ARTIFICIAL_STARTNODE: TaskId = TaskId(UUID("11111111-1111-1111-1111-111111111111"))
+task_node_as_artificial_startnode = TaskNode(
+    id=ID_OF_ARTIFICIAL_STARTNODE,
+    external_id="__START__",
+    name="START",
+    planned_duration=timedelta(minutes=0),
+)
+__all__ = ["ID_OF_ARTIFICIAL_STARTNODE", "task_node_as_artificial_startnode"]

taskdependencygraph/plotting/__init__.py

@@ -0,0 +1,11 @@
+"""
+The subpackage 'plotting' converts task dependency graphs to visual representations (images/SVGs).
+We use kroki.io to do the plotting for us because this is way more powerful than matplotlib or builtin tools.
+But instead of using the online kroki.io service, we host it locally in a docker-container (see docker-compose.yml).
+Otherwise, we'd quickly run into rate limits.
+"""
+
+from taskdependencygraph.plotting.kroki import KrokiClient, KrokiConfig
+from taskdependencygraph.plotting.protocols import DotPlottable, MermaidPlottable
+
+__all__ = ["DotPlottable", "MermaidPlottable", "KrokiClient", "KrokiConfig"]

taskdependencygraph/plotting/kroki.py

@@ -0,0 +1,148 @@
+"""
+Classes and methods to interact with kroki.io
+"""
+
+import logging
+import uuid
+import xml.etree.ElementTree as ET
+
+from aiohttp import ClientConnectorError, ClientResponseError, ClientSession, ClientTimeout
+from pydantic import BaseModel, HttpUrl
+from yarl import URL
+
+from taskdependencygraph.plotting.protocols import PlotMode
+from taskdependencygraph.task_dependency_graph import TaskDependencyGraph
+
+_logger = logging.getLogger(__name__)
+
+
+class KrokiConfig(BaseModel):
+    """
+    Configuration to connect with the kroki service
+    """
+
+    host: HttpUrl
+    """
+    host is the base/root URL of the kroki service (e.g. 'http://localhost:8123' or 'https://kroki.io')
+    """
+
+
+def _replace_id_with_svg_id(svg: str) -> str:
+    """replaces the ids of all <rect>-tags with 'svg-<id>' to avoid id-clashes in the overall DOM"""
+    root = ET.fromstring(svg)
+    for rect in root.findall(".//{http://www.w3.org/2000/svg}rect"):
+        if "id" in rect.attrib:
+            try:
+                uuid_id = uuid.UUID(rect.get("id"))  # raises a ValueError if the id is not a valid UUID
+                rect.set("id", f"svg-{uuid_id}")
+            except ValueError:
+                continue
+    ET.register_namespace("", "http://www.w3.org/2000/svg")  # removes the annoying "ns0:" prefix
+    return ET.tostring(root, encoding="unicode", xml_declaration=True)
+
+
+class KrokiClient:
+    """
+    A client to interact with the kroki service
+    """
+
+    def __init__(self, config: KrokiConfig):
+        """initialize the client with a configuration"""
+        self._config = config
+        self._session: ClientSession | None = None
+        _logger.info("Instantiated KrokiClient with server_url %s", str(self._config.host))
+
+    async def _get_session(self) -> ClientSession:
+        """
+        returns a client session (that may be reused or newly created)
+        reusing the same (threadsafe) session will be faster than re-creating a new session for every request.
+        see https://docs.aiohttp.org/en/stable/http_request_lifecycle.html#how-to-use-the-clientsession
+        """
+        if self._session is None or self._session.closed:
+            _logger.info("creating new session")
+            self._session = ClientSession(
+                timeout=ClientTimeout(60),
+                raise_for_status=True,
+            )
+        else:
+            _logger.log(5, "reusing aiohttp session")  # log level 5 is half as "loud" logging.DEBUG
+        return self._session
+
+    async def close_session(self) -> None:
+        """
+        closes the client session
+        """
+        if self._session is not None and not self._session.closed:
+            _logger.info("Closing aiohttp session")
+            await self._session.close()
+            self._session = None
+
+    async def is_ready(self) -> bool:
+        """
+        returns true, iff kroki is available
+        """
+        try:
+            simple_svg = await self._plot_dot_as_svg('digraph G{"A";"B";A->B}')
+            return simple_svg is not None
+        except Exception:  # pylint:disable=broad-except
+            _logger.exception("The is_ready check failed of the kroki client failed")
+            return False
+
+    async def _plot_dot_as_svg(self, dot_string: str) -> str:
+        payload = {"diagram_source": dot_string, "diagram_type": "graphviz", "output_format": "svg"}
+        session = await self._get_session()
+        request_uuid = uuid.uuid4()
+        svg_url = URL(str(self._config.host)) / "graphviz" / "svg"
+        _logger.debug("[%s] Send SVG request to kroki service", request_uuid)
+        try:
+            response = await session.post(svg_url, json=payload)
+        except ClientConnectorError:
+            _logger.exception("Failed to connect to kroki. Is it actually running at '%s'?", self._config.host)
+            raise
+        except ClientResponseError as cre:
+            if cre.status == 400:
+                _logger.warning(
+                    "The kroki service returned a 400 Bad Request. Your dot is probably invalid: %s", dot_string
+                )
+            raise
+        _logger.debug("[%s] Received response from kroki service; Status code %i", request_uuid, response.status)
+        svg = await response.text()
+        return svg
+
+    async def _plot_mermaid_as_svg(self, mermaid_str: str) -> str:
+        payload = {"diagram_source": mermaid_str, "diagram_type": "mermaid", "output_format": "svg"}
+        session = await self._get_session()
+        request_uuid = uuid.uuid4()
+        svg_url = URL(str(self._config.host)) / "mermaid" / "svg" % {"html-labels": "true"}
+        _logger.debug("[%s] Send SVG request to kroki service", request_uuid)
+        try:
+            response = await session.post(svg_url, json=payload)
+        except ClientConnectorError:
+            _logger.exception("Failed to connect to kroki. Is it actually running at '%s'?", self._config.host)
+            raise
+        except ClientResponseError as cre:
+            if cre.status == 400:
+                _logger.warning(
+                    "The kroki service returned a 400 Bad Request. Your dot is probably invalid: %s", mermaid_str
+                )
+            raise
+        _logger.debug("[%s] Received response from kroki service; Status code %i", request_uuid, response.status)
+        response_body = await response.text()
+        return _replace_id_with_svg_id(response_body)
+
+    async def plot_as_svg(self, tdg: TaskDependencyGraph, mode: PlotMode = "gantt") -> str:
+        """
+        returns an XML/SVG string of the task dependency graph
+        """
+        match mode:
+            case "dot":
+                dot_string = tdg.to_dot()
+                return await self._plot_dot_as_svg(dot_string)
+            case "gantt":
+                mermaid_gantt_str = tdg.to_mermaid_gantt()
+                return await self._plot_mermaid_as_svg(mermaid_gantt_str)
+            case _:
+                raise ValueError(f"Unknown mode '{mode}'")
+
+
+__all__ = ["KrokiClient", "KrokiConfig"]

taskdependencygraph/plotting/protocols.py

@@ -0,0 +1,43 @@
+"""
+interface like descriptions for any kind of plotting "client" library
+"""
+
+from typing import Literal, Protocol
+
+PlotMode = Literal["dot", "gantt"]
+
+
+class DotPlottable(Protocol):
+    """
+    something that can be plotted using Dot/GraphViz
+    """
+
+    def to_dot(self) -> str:
+        """
+        returns the dot-representation of this object as plain string
+        """
+
+
+class MermaidPlottable(Protocol):
+    """
+    something that can be plotted using Mermaid
+    """
+
+    def to_mermaid_gantt(self) -> str:
+        """
+        returns the mermaid-gantt chart representation of this object as plain string
+        """
+
+
+class Plotter(Protocol):
+    """
+    a plotter is something that converts a task dependency graph to a visual representation
+    """
+
+    async def plot_as_svg(self, graph: MermaidPlottable | DotPlottable, mode: PlotMode) -> str:
+        """
+        Plots something plottable as SVG; returns the SVG as XML string
+        """
+
+
+__all__ = ["DotPlottable", "MermaidPlottable", "Plotter"]

taskdependencygraph/py.typed

@@ -0,0 +1,2 @@
+# This file marks mypackage as PEP561 compatible.
+# Further reading: https://mypy.readthedocs.io/en/stable/installed_packages.html#creating-pep-561-compatible-packages