taskdependencygraph 0.1.0__py3-none-any.whl

taskdependencygraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: taskdependencygraph
+Version: 0.1.0
+Summary: Wrapper around a NetworkX Digraph to model and visualize tasks/todos, their duration and interdependencies
+Project-URL: Changelog, https://github.com/Hochfrequenz/task-dependency-graph/releases
+Project-URL: Homepage, https://github.com/Hochfrequenz/task-dependency-graph
+Author-email: Hochfrequenz Unternehmensberatung GmbH <info+github@hochfrequenz.de>
+License: MIT
+Keywords: digraph,graph,kroki,networkx,task,task dependency
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: aiohttp
+Requires-Dist: networkx
+Requires-Dist: pydantic-settings
+Requires-Dist: pydantic[email]>=2
+Provides-Extra: coverage
+Requires-Dist: coverage==7.6.12; extra == 'coverage'
+Provides-Extra: dev
+Requires-Dist: pip-tools; extra == 'dev'
+Provides-Extra: formatting
+Requires-Dist: black==25.1.0; extra == 'formatting'
+Requires-Dist: isort==6.0.1; extra == 'formatting'
+Provides-Extra: linting
+Requires-Dist: pylint==3.3.4; extra == 'linting'
+Provides-Extra: packaging
+Requires-Dist: build==1.2.2.post1; extra == 'packaging'
+Requires-Dist: twine==6.1.0; extra == 'packaging'
+Provides-Extra: spell-check
+Requires-Dist: codespell==2.4.1; extra == 'spell-check'
+Provides-Extra: tests
+Requires-Dist: pytest-asyncio==0.21.2; extra == 'tests'
+Requires-Dist: pytest==8.3.5; extra == 'tests'
+Requires-Dist: testcontainers; extra == 'tests'
+Provides-Extra: type-check
+Requires-Dist: mypy==1.15.0; extra == 'type-check'
+Requires-Dist: types-docker; extra == 'type-check'
+Description-Content-Type: text/markdown
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+![Python Versions (officially) supported](https://img.shields.io/pypi/pyversions/taskdependencygraph.svg)
+![Pypi status badge](https://img.shields.io/pypi/v/taskdependencygraph)
+
+# Task Dependency Graph
+
+Task Dependency Graph is a Python package that allows to model tasks and dependencies between tasks as a directed graph.
+It also supports visualizing the graph with [dot](https://graphviz.org/docs/layouts/dot/) for a graph-like view
+or [mermaid](https://mermaid.js.org/) for Gantt charts.
+
+The package is built on [networkx](https://networkx.org/) and under the hood the task dependency graph is just a
+networkx [DiGraph](https://networkx.org/documentation/stable/reference/classes/digraph.html).
+For visualization, it uses GraphViz via [kroki](https://kroki.io/) (in a Docker container).
+
+## Example / How to use
+
+Install the package from [PyPI](https://pypi.org/project/taskdependencygraph/)
+
+```bash
+pip install taskdependencygraph
+```
+
+Imagine the following scenario:
+
+You and your partner are invited to a birthday party.
+You promised to bring a cake.
+Baking the cake and the recipe can be divided into atomic tasks, all of which have a duration.
+Those are the **nodes** of the task dependency graph (TDG).
+
+Tasks are created like this:
+
+```python
+import uuid
+from datetime import timedelta
+
+from taskdependencygraph.models import TaskNode
+
+my_task = TaskNode(
+    id=uuid.uuid4(),  # boilerplate only, but you need the ID to find nodes in your graph later on
+    name="Shop groceries",  # human readable description
+    external_id="some unique string",  # technical ID for those who don't like uuids ;)
+    planned_duration=timedelta(minutes=15)  # how long it probably takes
+    # You may also add an assignees or an earliest_possible_start
+    # (The latter is useful, when e.g. the supermarket opens at 7am and you cannot shop groceries before,
+    # even if you were awake and have nothing else todo.)
+)
+```
+
+The tasks depend on each other:
+You cannot prepare the cake without buying the ingredients first.
+You cannot decorate the cake before you've made it.
+Which task has which mandatory predecessor tasks is defined in task dependencies.
+Those are the **edges** of our task dependency graph.
+
+Task dependencies are created like this:
+
+```python
+import uuid
+
+from taskdependencygraph.models import TaskDependencyEdge, TaskNode
+
+shopping_groceries = TaskNode(...)
+mixing_flour_and_sugar = TaskNode(...)
+baking_in_the_oven = TaskNode(...)
+
+buy_ingredients_before_mixing_them = TaskDependencyEdge(
+    id=uuid.uuid4(),  # boilerplate
+    predecessor_task=shopping_groceries.id,
+    successor_task=mixing_flour_and_sugar.id
+)
+mix_ingredients_before_baking_the_cake = TaskDependencyEdge(
+    id=uuid.uuid4(),  # boilerplate
+    predecessor_task=mixing_flour_and_sugar.id,
+    successor_task=baking_in_the_oven.id
+)
+```
+
+The graph is made out of tasks (nodes), task dependencies (edges) and a start datetime.
+
+```python
+from datetime import datetime, UTC
+
+from taskdependencygraph import TaskDependencyGraph
+from taskdependencygraph.models import TaskNode, TaskDependencyEdge
+
+# nodes
+shopping_groceries = TaskNode(...)
+mixing_flour_and_sugar = TaskNode(...)
+baking_in_the_oven = TaskNode(...)
+
+# edges
+buy_ingredients_before_mixing_them = TaskDependencyEdge(...)
+mix_ingredients_before_baking_the_cake = TaskDependencyEdge(...)
+
+# graph
+tdg = TaskDependencyGraph(
+    task_list=[shopping_groceries, mixing_flour_and_sugar, baking_in_the_oven],
+    dependency_list=[buy_ingredients_before_mixing_them, mix_ingredients_before_baking_the_cake],
+    starting_time_of_run=datetime(2025, 1, 1, 12, 0, 0, tzinfo=UTC)
+)
+```
+
+Now you can
+
+* calculate at which time which task is scheduled to start depending on which predecessors it has,
+* find out which tasks are 'critical' in sense that if they're delayed, then the finishing time of the last node is also
+  delayed,
+* assign persons to tasks and check if any person has more than one task assigned at a time.
+
+Find a complete working example in [the demo unittest](unittests/test_demonstration.py).
+This demo test is also the basis for the following visualization examples.
+
+## Visualization with Kroki
+
+You can visualize the dependencies either as rather simple technical graph or as Gantt chart, when you start kroki in a
+docker container:
+
+```yaml
+# docker-compose.yaml
+services:
+  kroki: # see https://docs.kroki.io/kroki/setup/use-docker-or-podman/#_run_multiple_kroki_containers_together
+    image: yuzutech/kroki:0.24.1
+    depends_on:
+      - mermaid
+    environment:
+      - KROKI_MERMAID_HOST=mermaid
+    ports:
+      - "8123:8000"
+  mermaid:
+    image: yuzutech/kroki-mermaid
+# run
+# docker-compose up -d
+# and kroki is ready at localhost:8123
+```
+
+```python
+import asyncio
+
+from taskdependencygraph import TaskDependencyGraph
+from taskdependencygraph.plotting import KrokiClient, KrokiConfig
+
+
+async def plot_a_graph() -> None:
+    tdg = TaskDependencyGraph(...)  # with all nodes and edges and stuff
+
+    config = KrokiConfig(host="http://localhost:8123")  # w/o docker, you may also use kroki.io, but it's rate limited
+    kroki_client = KrokiClient(config=config)
+
+    await kroki_client.plot_as_svg(tdg, mode="gantt")  # or mode="dot"
+
+
+if __name__ == '__main__':
+    loop = asyncio.get_event_loop()
+    loop.run_until_complete(plot_a_graph())
+```
+
+The result may look like this:
+
+### Gantt Chart (Mermaid)
+
+![A Gantt chart](unittests/baking_a_cake_gantt.svg)
+
+The tasks marked in red mark the critical path on which delays affect the finishing time.
+The 🔶 are milestones which mark important moments in your project (often you want to have a group of tasks like '
+Shopping' done before starting with the next step, even though there's no "real" dependency between e.g. Cake Base and
+buying the strawberries.)
+The Gantt chart is useful to get an overview of your project and to identify which tasks are crucial.
+
+### Raw Graph ("dot" engine)
+
+![](unittests/baking_a_cake_dot.svg)
+
+The raw graph helps you to understand the tasks and dependencies setup in a not so shiny but verbose fashion.
+
+## Storing the Graph in a Database
+You can store the nodes and edges on a database.
+We suggest to just use two tables: One for the edges, one for the nodes.
+You can even add trigger-based [DB constraints to prevent loops in the graph](https://gist.github.com/hf-kklein/49f6d05bd29ca850e33f5ccff3e66469) which are faster than you might guess, even for hundreds of tasks.
+
+## Maintainers/ Further Development / Professional Support
+This library was built for and then cut out of a mainly internal project by [@hf-crings](https://github.com/hf-crings), [@OLILHR](https://github.com/OLILHR), [@hf-sheese](https://github.com/hf-sheese) and [@hf-kklein](https://github.com/hf-kklein), but we decided to publish it, because it might be useful to someone.
+This is why some things are hardcoded here and there and why some features might seem unintuitive at first glance.
+
+We at Hochfrequenz also built a SQLAlchemy+FastAPI+htmx web application around this library in which you can plan and schedule time-critical tasks and projects in the browser.
+It's ready to use, but not pretty enough to publish it yet ;)
+Just ping us if interested.

taskdependencygraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+_taskdependencygraph_version.py,sha256=aOHawL1zuHMfBWKXqwUkXcW96oXLNCY-CXdHDqkz4g4,18
+taskdependencygraph/__init__.py,sha256=BPP3kiAUt-k5HhjHH0vVWB8nBxi2Xy2rMx3ihQxBOVU,248
+taskdependencygraph/py.typed,sha256=ZvYa-_QF7Xg7F6Dow8m1zHvSP6kNHuhh3BEBVxjAdUQ,168
+taskdependencygraph/task_dependency_graph.py,sha256=CEsTM1j3366UT-w1QwuflDKmncn4lEznvTfIgg561Gg,29606
+taskdependencygraph/models/__init__.py,sha256=Dho2VKW4qrrzEzcqoOx_dZzY3dyRlNHJhqdEvH5CoQ0,788
+taskdependencygraph/models/ids.py,sha256=3cHAujoJhHzg6NZIdwtehGPf_w506rsr74ynPtTTb4o,898
+taskdependencygraph/models/person.py,sha256=xYYfOdRfVHGTPjq7RLujspFywDhcMkbrmBPSAghLPtM,629
+taskdependencygraph/models/task_dependency_edge.py,sha256=nJTEtPiuEYs6T-aQ_wRs7IQ3QfkzaFoDx_1g3b83_Ps,1297
+taskdependencygraph/models/task_dependency_update.py,sha256=_amKiccJR7K1fkrXehKXNGLtvyFng0wjXnVet7jI2UA,2164
+taskdependencygraph/models/task_execution_status.py,sha256=oENBNxwPmr8TKJE-LmDknYpAdCjlNJd0RE0hwRbCfp0,1113
+taskdependencygraph/models/task_node.py,sha256=S_30Ptq-xR1UcvRrc5oUscqBey4KIo79NWV47ayE8eo,5358
+taskdependencygraph/models/task_node_as_artificial_endnode.py,sha256=oztA175PxdTHry-i7Oq5uv3p7exNeAu5UpolSut3BLY,933
+taskdependencygraph/models/task_node_as_artificial_startnode.py,sha256=zR9OsM5VyCXxZ-3XadJZs0B_hf_cejYIaFBBc9Waz38,984
+taskdependencygraph/plotting/__init__.py,sha256=KhefeR-FCRw-8swt9sds3uW6oik2AjgdYusKhxB30Ps,613
+taskdependencygraph/plotting/kroki.py,sha256=2EvAL2LZw0nQPg7M8uGstfu0CeqFTjgIRs7Hx7U9ezA,5988
+taskdependencygraph/plotting/protocols.py,sha256=lXRF2MZJQLoOYEkROfK7S-eb69qpwiR2kP4Hf2t86Qo,1015
+taskdependencygraph-0.1.0.dist-info/METADATA,sha256=eZ7oZWQ37P9DgXkgdKJ6ROGIgvdJyYI0FQFJ1k8YQsM,9288
+taskdependencygraph-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+taskdependencygraph-0.1.0.dist-info/RECORD,,

taskdependencygraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any