gitgraf 0.1.0__tar.gz → 0.2.0__tar.gz

gitgraf-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Haglund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitgraf-0.2.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: gitgraf
+Version: 0.2.0
+Summary: A graph of nodes, facts and edges kept as human-readable YAML files in git, with valid, knowledge and change time on every record
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: networkx>=3.3
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Gitgraf
+
+Gitgraf keeps a graph of nodes, facts and edges as human-readable YAML files in a git repository: `pip install`, no server, no database.
+
+Every fact and edge carries three time axes, and nothing is ever overwritten:
+
+- **Valid time** (`valid_from`, `valid_to`): when it is true in the world.
+- **Knowledge time** (`known_at`): when it was first known.
+- **Change time** (`changed_at`, `superseded_at`): when the record was written or replaced. An update appends a new version, so the graph can be read as it was at any earlier moment.
+
+It is the store that bibliotheke, a knowledge graph framework, is built on, and it works on its own for any register of dated facts.
+
+## Quickstart
+
+```sh
+gitgraf init
+gitgraf add node windfarm "Hornsea 2"
+gitgraf add node bmu "T_HOWBO-1"
+gitgraf add fact hornsea-2 capacity_mw 1386 --valid-from 2022-08-31
+gitgraf add edge t-howbo-1 part_of hornsea-2 --valid-from 2021-12
+
+gitgraf show hornsea-2                      # the current graph
+gitgraf show hornsea-2 --valid-at 2022-01   # what was true then
+gitgraf show hornsea-2 --known-at 2024      # what had been learned by then
+gitgraf show hornsea-2 --at-commit v1.0     # as committed at a git revision
+gitgraf show hornsea-2 --json
+```
+
+`add fact` and `add edge` print a record id. Use it to change a record without losing history:
+
+```sh
+gitgraf update f53fd77 --value 1320   # appends a new version
+gitgraf retract f53fd77               # hides it from the current graph
+gitgraf history hornsea-2             # every version, including superseded ones
+```
+
+## Sources and edge attributes
+
+Any fact or edge can say where it comes from, and an edge can carry attributes of the link itself, such as a share of ownership:
+
+```sh
+gitgraf add fact hornsea-2 capacity_mw 1386 --source "TEC register 2026-03"
+gitgraf add edge hornsea-2 owned_by orsted --set share=0.5 --valid-from 2022-09 --source "company announcement"
+gitgraf update e2778f9 --set share=0.4 --source "annual report 2025"   # a new version; the old share stays in history
+```
+
+A new version keeps the source and attributes it does not change. In a batch for `gitgraf import`, `source` can be set once for the whole batch, per node, or per record, and an edge takes `attrs: {share: 0.5}`.
+
+The data model can type the attributes of a relation and require a source on every record:
+
+```yaml
+source: required          # a write without a source is refused; `check` reports hand edits that drop one
+edges:
+  owned_by:
+    from: windfarm
+    to: company
+    attrs:
+      share: {type: number, required: true}
+      role:  {type: enum, values: [operator, investor]}
+```
+
+`gitgraf model add edge owned_by windfarm company --attr share:number` declares one from the command line. Both are stored only where present, so a graph that uses neither has the same files as before.
+
+## Files
+
+A graph is a directory with a `gitgraf.yaml` marker and one file per node at `nodes/<type>/<id>.yaml`, with optional Markdown next to it at `nodes/<type>/<id>.md`:
+
+```yaml
+id: hornsea-2
+type: windfarm
+name: Hornsea 2
+notes: ''
+facts:
+- id: f53fd77
+  key: capacity_mw
+  value: 1386
+  valid_from: 2022-08-31
+  valid_to: null
+  known_at: 2026-11-14T10:07:00Z
+  changed_at: 2026-11-14T10:07:00Z
+  superseded_at: null
+edges: []
+```
+
+A node's file is dumped deterministically, so a git diff shows only what changed.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `init`, `add node\|fact\|edge`, `update`, `retract`, `import` | Write the graph; `import` merges a batch file and is safe to re-run |
+| `show`, `history`, `list`, `types`, `search`, `export` | Read it; all take `--valid-at`, `--known-at`, `--changed-at` and `--at-commit` |
+| `merge` | Join two nodes that are the same thing; an alias resolves wherever an id is expected |
+| `model`, `model add\|rename\|drop`, `model diff\|log\|version\|tag` | An optional data model: what node types, facts and edges the graph allows, and how it changed |
+| `check` | Validate the files against each other and the model; lists possible duplicates |
+| `diff` | What changed between two git revisions |
+| `hook install`, `ci` | A pre-commit hook and a GitHub Actions workflow that run `check` and refuse destructive model changes |
+
+## From Python
+
+```python
+from gitgraf import At, Graph
+
+graph = Graph.open("registry")
+node = graph.node("hornsea-2")
+facts = graph.facts(node.id, At(valid_at="2022-01", known_at="2024"))
+```
+
+`Graph.nx(at)` returns a frozen `networkx.MultiDiGraph` of what is in view.
+
+## Building on it
+
+A package on top keeps its own names with `gitgraf.settings.configure(cli=..., package=..., markers=...)`, called before `gitgraf.cli` is imported, and adds its own commands to `gitgraf.cli.app`. `gitgraf.hooks.checks` and `gitgraf.hooks.rewrites` let it check and maintain its own sections of the marker file.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+```

gitgraf-0.2.0/README.md

@@ -0,0 +1,120 @@
+# Gitgraf
+
+Gitgraf keeps a graph of nodes, facts and edges as human-readable YAML files in a git repository: `pip install`, no server, no database.
+
+Every fact and edge carries three time axes, and nothing is ever overwritten:
+
+- **Valid time** (`valid_from`, `valid_to`): when it is true in the world.
+- **Knowledge time** (`known_at`): when it was first known.
+- **Change time** (`changed_at`, `superseded_at`): when the record was written or replaced. An update appends a new version, so the graph can be read as it was at any earlier moment.
+
+It is the store that bibliotheke, a knowledge graph framework, is built on, and it works on its own for any register of dated facts.
+
+## Quickstart
+
+```sh
+gitgraf init
+gitgraf add node windfarm "Hornsea 2"
+gitgraf add node bmu "T_HOWBO-1"
+gitgraf add fact hornsea-2 capacity_mw 1386 --valid-from 2022-08-31
+gitgraf add edge t-howbo-1 part_of hornsea-2 --valid-from 2021-12
+
+gitgraf show hornsea-2                      # the current graph
+gitgraf show hornsea-2 --valid-at 2022-01   # what was true then
+gitgraf show hornsea-2 --known-at 2024      # what had been learned by then
+gitgraf show hornsea-2 --at-commit v1.0     # as committed at a git revision
+gitgraf show hornsea-2 --json
+```
+
+`add fact` and `add edge` print a record id. Use it to change a record without losing history:
+
+```sh
+gitgraf update f53fd77 --value 1320   # appends a new version
+gitgraf retract f53fd77               # hides it from the current graph
+gitgraf history hornsea-2             # every version, including superseded ones
+```
+
+## Sources and edge attributes
+
+Any fact or edge can say where it comes from, and an edge can carry attributes of the link itself, such as a share of ownership:
+
+```sh
+gitgraf add fact hornsea-2 capacity_mw 1386 --source "TEC register 2026-03"
+gitgraf add edge hornsea-2 owned_by orsted --set share=0.5 --valid-from 2022-09 --source "company announcement"
+gitgraf update e2778f9 --set share=0.4 --source "annual report 2025"   # a new version; the old share stays in history
+```
+
+A new version keeps the source and attributes it does not change. In a batch for `gitgraf import`, `source` can be set once for the whole batch, per node, or per record, and an edge takes `attrs: {share: 0.5}`.
+
+The data model can type the attributes of a relation and require a source on every record:
+
+```yaml
+source: required          # a write without a source is refused; `check` reports hand edits that drop one
+edges:
+  owned_by:
+    from: windfarm
+    to: company
+    attrs:
+      share: {type: number, required: true}
+      role:  {type: enum, values: [operator, investor]}
+```
+
+`gitgraf model add edge owned_by windfarm company --attr share:number` declares one from the command line. Both are stored only where present, so a graph that uses neither has the same files as before.
+
+## Files
+
+A graph is a directory with a `gitgraf.yaml` marker and one file per node at `nodes/<type>/<id>.yaml`, with optional Markdown next to it at `nodes/<type>/<id>.md`:
+
+```yaml
+id: hornsea-2
+type: windfarm
+name: Hornsea 2
+notes: ''
+facts:
+- id: f53fd77
+  key: capacity_mw
+  value: 1386
+  valid_from: 2022-08-31
+  valid_to: null
+  known_at: 2026-11-14T10:07:00Z
+  changed_at: 2026-11-14T10:07:00Z
+  superseded_at: null
+edges: []
+```
+
+A node's file is dumped deterministically, so a git diff shows only what changed.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `init`, `add node\|fact\|edge`, `update`, `retract`, `import` | Write the graph; `import` merges a batch file and is safe to re-run |
+| `show`, `history`, `list`, `types`, `search`, `export` | Read it; all take `--valid-at`, `--known-at`, `--changed-at` and `--at-commit` |
+| `merge` | Join two nodes that are the same thing; an alias resolves wherever an id is expected |
+| `model`, `model add\|rename\|drop`, `model diff\|log\|version\|tag` | An optional data model: what node types, facts and edges the graph allows, and how it changed |
+| `check` | Validate the files against each other and the model; lists possible duplicates |
+| `diff` | What changed between two git revisions |
+| `hook install`, `ci` | A pre-commit hook and a GitHub Actions workflow that run `check` and refuse destructive model changes |
+
+## From Python
+
+```python
+from gitgraf import At, Graph
+
+graph = Graph.open("registry")
+node = graph.node("hornsea-2")
+facts = graph.facts(node.id, At(valid_at="2022-01", known_at="2024"))
+```
+
+`Graph.nx(at)` returns a frozen `networkx.MultiDiGraph` of what is in view.
+
+## Building on it
+
+A package on top keeps its own names with `gitgraf.settings.configure(cli=..., package=..., markers=...)`, called before `gitgraf.cli` is imported, and adds its own commands to `gitgraf.cli.app`. `gitgraf.hooks.checks` and `gitgraf.hooks.rewrites` let it check and maintain its own sections of the marker file.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+```

gitgraf-0.2.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "gitgraf"
+version = "0.2.0"
+description = "A graph of nodes, facts and edges kept as human-readable YAML files in git, with valid, knowledge and change time on every record"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "networkx>=3.3",
+    "pyyaml>=6.0",
+    "typer>=0.12",
+]
+
+[project.scripts]
+gitgraf = "gitgraf.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["uv_build>=0.9,<0.10"]
+build-backend = "uv_build"

gitgraf-0.2.0/src/gitgraf/__init__.py

@@ -0,0 +1,6 @@
+"""Gitgraf: a graph of nodes, facts and edges kept as files in git, with three time axes."""
+
+from gitgraf.graph import At, Graph, GraphError
+from gitgraf.model import Edge, Fact, Node
+
+__all__ = ["At", "Edge", "Fact", "Graph", "GraphError", "Node"]