pycode-kg 0.26.0__tar.gz → 0.27.0__tar.gz

{pycode_kg-0.26.0 → pycode_kg-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycode-kg
-Version: 0.26.0
+Version: 0.27.0
 Summary: A tool to build a searchable knowledge graph from Python repositories
 License-Expression: Elastic-2.0
 License-File: LICENSE
@@ -21,8 +21,8 @@ Provides-Extra: viz3d
 Requires-Dist: PyQt5 (>=5.15.0) ; extra == "all"
 Requires-Dist: PyQt5 (>=5.15.0) ; extra == "viz3d"
 Requires-Dist: click (>=8.1.0,<9)
-Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.19.0)
-Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.18.1) ; extra == "viz3d"
+Requires-Dist: kgmodule-utils[semantic,viz3d] (>=0.20.0)
+Requires-Dist: kgmodule-utils[viz3d-qt,viz3d-render] (>=0.20.0) ; extra == "viz3d"
 Requires-Dist: markdown (>=3.6) ; extra == "all"
 Requires-Dist: markdown (>=3.6) ; extra == "viz3d"
 Requires-Dist: mcp (>=1.0.0,<2)
@@ -60,7 +60,7 @@ Description-Content-Type: text/markdown
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.26.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.27.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
@@ -255,7 +255,7 @@ src/pycode_kg/
 └── viz3d_timeline.py                # Metric history timeline
 ```
 
-The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.26.0.md](docs/analysis_v0.26.0.md), produced (of course) by `pycodekg analyze` against this very repo.
+The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.27.0.md](docs/analysis_v0.27.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -282,13 +282,13 @@ If you use PyCodeKG in your research or project, please cite it:
 
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.26.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.27.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
 
 ```bibtex
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: A Knowledge Graph for Python Codebases},
-  version   = {0.26.0},
+  version   = {0.27.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.26.0 → pycode_kg-0.27.0}/README.md

@@ -5,7 +5,7 @@
 
 [![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
 [![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.26.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
+[![Version](https://img.shields.io/badge/version-0.27.0-blue.svg)](https://github.com/Flux-Frontiers/pycode_kg/releases)
 [![CI](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/pycode_kg/actions/workflows/ci.yml)
 [![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
@@ -200,7 +200,7 @@ src/pycode_kg/
 └── viz3d_timeline.py                # Metric history timeline
 ```
 
-The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.26.0.md](docs/analysis_v0.26.0.md), produced (of course) by `pycodekg analyze` against this very repo.
+The MCP server, the CLI, and the Streamlit app are thin wrappers over the same store + index + ranking core — there is exactly one code path for each capability. The latest architectural deep-dive is in [docs/analysis_v0.27.0.md](docs/analysis_v0.27.0.md), produced (of course) by `pycodekg analyze` against this very repo.
 
 ---
 
@@ -227,13 +227,13 @@ If you use PyCodeKG in your research or project, please cite it:
 
 [![DOI](https://zenodo.org/badge/1202379010.svg)](https://zenodo.org/badge/latestdoi/1202379010)
 
-> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.26.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
+> Suchanek, E. G. (2026). *PyCodeKG: A Knowledge Graph for Python Codebases* (Version 0.27.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.19737993
 
 ```bibtex
 @software{suchanek_pycode_kg,
   author    = {Suchanek, Eric G.},
   title     = {{PyCodeKG}: A Knowledge Graph for Python Codebases},
-  version   = {0.26.0},
+  version   = {0.27.0},
   year      = {2026},
   publisher = {Flux-Frontiers},
   url       = {https://github.com/Flux-Frontiers/pycode_kg},

{pycode_kg-0.26.0 → pycode_kg-0.27.0}/pyproject.toml

@@ -70,7 +70,7 @@ torch = [
 # ---------------------------------------------------------------------------
 [project]
 name = "pycode-kg"
-version = "0.26.0"
+version = "0.27.0"
 description = "A tool to build a searchable knowledge graph from Python repositories"
 readme = "README.md"
 license = "Elastic-2.0"
@@ -155,7 +155,21 @@ dependencies = [
     # this repo's visitor writes as of 0.24.1 -- against 0.18.0 the stubs are
     # tagged correctly but the tag is silently ignored, so resolution stays on
     # the old untyped trailing-name match with no error to say so.
-    "kgmodule-utils[semantic,viz3d]>=0.19.0",
+    #
+    # 0.19.1 because SnapshotManager.load_snapshot back-fills a missing
+    # vs_previous through _compute_delta_from_metrics as of that release.
+    # Against 0.19.0 the backfill uses a hardcoded nodes/edges dict, so
+    # coverage_delta and critical_issues_delta read as zero in `snapshot show`
+    # for every snapshot whose deltas were not persisted at capture -- which is
+    # the normal path, not a legacy one.
+    #
+    # 0.20.0 is a hard requirement, not a preference: snapshots.py has no
+    # __init__, capture or diff_snapshots of its own any more. It configures
+    # the base through the package_name and dict_metric_deltas class attributes
+    # and the _domain_metrics() hook, none of which exist before 0.20.0.
+    # Against 0.19.x the manager silently reports itself as "kg-utils" and
+    # drops module_node_counts entirely.
+    "kgmodule-utils[semantic,viz3d]>=0.20.0",
 ]
 
 [project.optional-dependencies]
@@ -180,7 +194,7 @@ viz3d = [
     # the four-step build/render/write/cast itself. It subsumes [viz3d-render]
     # (it declares pyvista too), but both are named so the dependency reads as
     # what it is rather than as a side effect.
-    "kgmodule-utils[viz3d-render,viz3d-qt]>=0.18.1",
+    "kgmodule-utils[viz3d-render,viz3d-qt]>=0.20.0",
     "pyvistaqt>=0.11.0",
     "trame-vtk>=2.0.0",
     # Looking Glass quilts. 0.4.0 supplies depth_report() and widened

{pycode_kg-0.26.0 → pycode_kg-0.27.0}/src/pycode_kg/__init__.py

@@ -36,7 +36,7 @@ Author: Eric G. Suchanek, PhD
 License: Elastic 2.0
 """
 
-__version__ = "0.26.0"
+__version__ = "0.27.0"
 __author__ = "Eric G. Suchanek, PhD"
 
 # Low-level primitives (locked v0 contract)

{pycode_kg-0.26.0 → pycode_kg-0.27.0}/src/pycode_kg/cli/cmd_init.py

@@ -277,7 +277,7 @@ def init(
                 version=version,
                 branch=branch,
                 graph_stats_dict=stats,
-                coverage=coverage,
+                docstring_coverage=coverage,
                 coverage_documented=coverage_documented,
                 coverage_total=coverage_total,
                 critical_issues=critical_issues,

{pycode_kg-0.26.0 → pycode_kg-0.27.0}/src/pycode_kg/cli/cmd_snapshot.py

@@ -19,6 +19,7 @@ import json
 from pathlib import Path
 
 import click
+from click.core import ParameterSource
 
 from pycode_kg.cli.main import cli
 from pycode_kg.cli.options import sqlite_option
@@ -34,6 +35,33 @@ from pycode_kg.snapshots import (
 from pycode_kg.store import GraphStore
 
 
+def _graph_for_repo(sqlite: str, repo_root: Path) -> Path:
+    """Resolve the graph path, anchoring the default to ``--repo``.
+
+    ``--sqlite`` defaults to the relative ``.pycodekg/graph.sqlite``, which
+    click resolves against the *current working directory*, while
+    ``--repo`` decides where the snapshot is filed. Left alone, the two
+    disagree: ``pycodekg snapshot save 1.0.0 --repo /other/project`` run from
+    inside this repo reads *this* repo's graph and writes the result into
+    */other/project*'s snapshots directory -- a snapshot whose metrics belong
+    to one project and whose provenance claims another, with no error.
+
+    An explicitly passed ``--sqlite`` is always honoured as given; only the
+    default is re-anchored. The other commands sharing ``sqlite_option``
+    (``query``, ``explain``) take no ``--repo``, so cwd is the right base for
+    them and they are unaffected.
+
+    :param sqlite: The ``--sqlite`` value, explicit or default.
+    :param repo_root: The resolved ``--repo`` path.
+    :return: The graph database path to read.
+    """
+    ctx = click.get_current_context(silent=True)
+    source = ctx.get_parameter_source("sqlite") if ctx is not None else None
+    if source is not None and source is not ParameterSource.DEFAULT:
+        return Path(sqlite)
+    return repo_root / ".pycodekg" / "graph.sqlite"
+
+
 @cli.group("snapshot")
 def snapshot() -> None:
     """Manage temporal snapshots of PyCodeKG metrics."""
@@ -105,7 +133,7 @@ def save_snapshot(
         pycodekg snapshot save 0.5.1 --repo .
     """
     repo_root = Path(repo).resolve()
-    db_path = Path(sqlite)
+    db_path = _graph_for_repo(sqlite, repo_root)
     snapshots_path = (
         Path(snapshots_dir).resolve() if snapshots_dir else (repo_root / ".pycodekg" / "snapshots")
     )
@@ -161,7 +189,7 @@ def save_snapshot(
         version=version,
         branch=branch,
         graph_stats_dict=stats,
-        coverage=coverage,
+        docstring_coverage=coverage,
         coverage_documented=coverage_documented,
         coverage_total=coverage_total,
         critical_issues=critical_issues,

{pycode_kg-0.26.0 → pycode_kg-0.27.0}/src/pycode_kg/snapshots.py

@@ -15,7 +15,7 @@ This module adds:
     ``metrics_from_dict`` / ``metrics_to_dict`` and ``delta_from_dict`` /
     ``delta_to_dict``; a ``Snapshot`` never holds one.
   - a ``SnapshotManager`` subclass that sets ``package_name="pycode-kg"``,
-    names the pycode-kg metric fields in ``capture()``, adds
+    collects the pycode-kg metric fields in ``_domain_metrics()``, adds
     ``coverage_delta`` and ``critical_issues_delta`` to deltas, collects
     per-module node counts from SQLite, and extends a diff with
     ``module_node_counts_delta``, ``issues_delta`` and ``timestamp``.
@@ -44,7 +44,6 @@ from __future__ import annotations
 
 import sqlite3
 from dataclasses import dataclass, field
-from pathlib import Path
 from typing import Any
 
 # ---------------------------------------------------------------------------
@@ -174,147 +173,64 @@ def delta_from_dict(d: dict[str, Any] | None) -> SnapshotDelta | None:
 class SnapshotManager(_BaseSnapshotManager):
     """pycode-kg snapshot manager.
 
-    Subclasses the shared ``kg_utils.snapshots.SnapshotManager`` and adds:
+    Subclasses the shared ``kg_utils.snapshots.SnapshotManager``. Three of the
+    four additions are class attributes rather than methods, because the base
+    supplies the behaviour and this module only names the domain values:
 
-    * ``package_name="pycode-kg"`` default for version detection.
-    * A ``capture()`` naming the pycode-kg metric fields (``coverage``,
-      ``critical_issues``, ``complexity_median`` and the coverage numerator
-      and denominator) and collecting per-module node counts.
+    * ``package_name = "pycode-kg"`` for version detection.
+    * ``dict_metric_deltas`` naming ``module_node_counts``, which the base
+      turns into ``module_node_counts_delta`` in ``diff_snapshots``.
+    * ``_domain_metrics()`` collecting per-module node counts at capture time.
     * ``_compute_delta_from_metrics`` extended with ``coverage_delta`` and
-      ``critical_issues_delta``.
-    * ``diff_snapshots`` extended with ``module_node_counts_delta``,
-      ``issues_delta`` and ``timestamp``.
+      ``critical_issues_delta`` — the one genuinely domain-specific method.
     * ``_collect_module_node_counts()`` — SQLite per-module node counts.
 
-    Everything else -- saving, loading, listing, pruning, key handling -- is
-    inherited unchanged.  Overriding those to convert between dicts and the
-    domain dataclasses is what this module used to do, and is what let the
-    0.25.0 snapshot key regression through.
+    Everything else -- capture, saving, loading, listing, pruning, diffing, key
+    handling -- is inherited unchanged. Overriding those is what this module
+    used to do, and is what let the 0.25.0 snapshot key regression through.
+
+    Note that ``capture()`` takes the coverage fraction as
+    ``docstring_coverage``, the name it is stored under. Until 0.27.0 this
+    class overrode ``capture()`` to accept it as ``coverage`` and rename it on
+    the way through; that override is gone, and with it the signature-restating
+    pattern that let a ``key=`` go missing. ``coverage=`` still works and warns
+    -- see ``capture_aliases`` below.
     """
 
-    def __init__(
-        self,
-        snapshots_dir: Path | str,
-        *,
-        db_path: Path | str | None = None,
-        package_name: str = "pycode-kg",
-    ) -> None:
-        """Initialize the manager rooted at ``snapshots_dir``.
-
-        :param snapshots_dir: Directory where snapshot JSON files live; created
-            on first save if it does not exist.
-        :param db_path: PyCodeKG SQLite graph path; required for collecting
-            per-module node counts during ``capture()``. Optional otherwise.
-        :param package_name: Package name used for version detection in saved
-            snapshots. Defaults to ``"pycode-kg"``.
-        """
-        super().__init__(snapshots_dir, package_name=package_name, db_path=db_path)
+    #: Version detection reads this; the base uses it as the snapshot's ``tool``.
+    package_name = "pycode-kg"
 
-    # ------------------------------------------------------------------
-    # capture — name the pycode-kg metric fields
-    # ------------------------------------------------------------------
+    #: ``diff_snapshots`` emits ``module_node_counts_delta`` from this, holding
+    #: only the modules whose node count actually changed.
+    dict_metric_deltas = ("module_node_counts",)
 
-    def capture(  # ty: ignore[invalid-method-override]
-        self,
-        version: str | None = None,
-        branch: str | None = None,
-        graph_stats_dict: dict[str, Any] | None = None,
-        coverage: float = 0.0,
-        coverage_documented: int = 0,
-        coverage_total: int = 0,
-        critical_issues: int = 0,
-        complexity_median: float = 0.0,
-        hotspots: list[dict[str, Any]] | None = None,
-        issues: list[str] | None = None,
-        tree_hash: str = "",
-        key: str = "",
-        subject: str = "",
-    ) -> Snapshot:
-        """Capture a pycode-kg snapshot.
-
-        Names the pycode-kg metric fields explicitly rather than taking them
-        through ``**extra_metrics``, and adds per-module node counts, then
-        delegates to the shared implementation.
-
-        :param version: Version string (e.g., "0.5.1").
-        :param branch: Git branch name; auto-detected if None.
-        :param graph_stats_dict: Output from ``graph_stats()`` / ``store.stats()``.
-        :param coverage: Docstring coverage fraction (0.0-1.0).
-        :param coverage_documented: Nodes with a non-empty docstring — the
-            numerator behind ``coverage``.  Shown beside the percentage in
-            Snapshot History so a coverage drop caused by adding undocumented
-            nodes reads differently from one caused by removing docstrings.
-        :param coverage_total: Nodes eligible for docstring coverage — the
-            denominator behind ``coverage``.
-        :param critical_issues: Number of critical issues detected.
-        :param complexity_median: Median fan-in across functions.
-        :param hotspots: Top hotspot entries.
-        :param issues: Issue description strings.
-        :param tree_hash: Git tree hash, recorded as provenance; auto-detected
-            if not provided. It is not the snapshot's key.
-        :param key: Snapshot identifier. Pass the release tag at release time;
-            omit it and the base assigns a UTC timestamp.
-        :param subject: What was measured, e.g. ``repo:pycode-kg``.
-        :return: New :class:`~kg_utils.snapshots.Snapshot` (not yet persisted).
-        """
-        return super().capture(
-            version=version,
-            branch=branch,
-            graph_stats_dict=graph_stats_dict,
-            tree_hash=tree_hash,
-            key=key,
-            subject=subject,
-            hotspots=hotspots,
-            issues=issues,
-            docstring_coverage=coverage,
-            coverage_documented=coverage_documented,
-            coverage_total=coverage_total,
-            critical_issues=critical_issues,
-            complexity_median=complexity_median,
-            module_node_counts=self._collect_module_node_counts(),
-        )
+    #: Until 0.27.0 this class overrode ``capture()`` to accept the docstring
+    #: coverage fraction as ``coverage`` and rename it on the way through. The
+    #: override is gone, and the stored name is the only name. Without this
+    #: entry a caller still passing ``coverage=`` would get no error: the base
+    #: ``**extra_metrics`` would record a ``coverage`` metric nobody reads and
+    #: leave ``docstring_coverage`` absent.
+    capture_aliases = {"coverage": "docstring_coverage"}
 
     # ------------------------------------------------------------------
-    # diff_snapshots — adds module_node_counts_delta, issues_delta, timestamp
+    # Capture-time metrics collected by this module
     # ------------------------------------------------------------------
 
-    def diff_snapshots(self, key_a: str, key_b: str) -> dict[str, Any]:
-        """Compare two snapshots side-by-side.
+    def _domain_metrics(self, stats: dict[str, Any]) -> dict[str, Any]:
+        """Collect the metrics this module gathers for itself.
 
-        Extends the shared diff with ``module_node_counts_delta``,
-        ``issues_delta`` (introduced / resolved issue strings) and the
-        ``timestamp`` of each side, which the CLI prints.
+        Called by the inherited ``capture()``. Overriding this rather than
+        ``capture()`` is deliberate: a ``capture()`` override has to restate the
+        base signature, and restating it is what let ``key=`` fall into
+        ``**extra_metrics`` and ship 0.25.0 with every snapshot keyed on a tree
+        hash.
 
-        :param key_a: Earlier snapshot key.
-        :param key_b: Later snapshot key.
-        :return: The shared diff result with the pycode-kg additions.
+        :param stats: Graph stats passed to ``capture()``; unused here, the
+            counts come from SQLite.
+        :return: ``{"module_node_counts": {module_path: node_count}}``, empty
+                 if no SQLite graph is configured.
         """
-        result = super().diff_snapshots(key_a, key_b)
-        if "error" in result:
-            return result
-
-        for side, key in (("a", key_a), ("b", key_b)):
-            snap = self.load_snapshot(key)
-            if snap is not None:
-                result[side]["timestamp"] = snap.timestamp
-
-        m_a: dict[str, Any] = result["a"]["metrics"]
-        m_b: dict[str, Any] = result["b"]["metrics"]
-        counts_a: dict[str, int] = m_a.get("module_node_counts", {})
-        counts_b: dict[str, int] = m_b.get("module_node_counts", {})
-        result["module_node_counts_delta"] = {
-            mod: counts_b.get(mod, 0) - counts_a.get(mod, 0)
-            for mod in set(counts_a) | set(counts_b)
-            if counts_b.get(mod, 0) != counts_a.get(mod, 0)
-        }
-
-        issues_a = set(result["a"]["issues"])
-        issues_b = set(result["b"]["issues"])
-        result["issues_delta"] = {
-            "introduced": list(issues_b - issues_a),
-            "resolved": list(issues_a - issues_b),
-        }
-        return result
+        return {"module_node_counts": self._collect_module_node_counts()}
 
     # ------------------------------------------------------------------
     # Delta computation — adds coverage_delta and critical_issues_delta