pygeodata-browser 0.1.0__tar.gz

pygeodata_browser-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+# Push a version tag (e.g. `git tag v0.1.0 && git push --tags`) to publish to PyPI;
+# the tag is the version (setuptools-scm).
+# The frontend is compiled here and shipped prebuilt; users never need Node.
+# PyPI authenticates this workflow via trusted publishing (no API token): add it
+# as a trusted publisher on PyPI (workflow `release.yml`, environment `pypi`).
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # setuptools-scm reads the version from git tags
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: app/package-lock.json
+
+      - name: Build the frontend
+        working-directory: app
+        run: |
+          npm ci
+          npm run check
+          npm run build
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+
+      - name: Build distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Check the distributions ship the built frontend
+        run: python scripts/check_dist.py dist
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

pygeodata_browser-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+.DS_Store
+app/node_modules/
+api/static/app/

pygeodata_browser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jasper Roebroek
+
+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.

pygeodata_browser-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+# The source archive ships the prebuilt frontend (api/static/app), not its Svelte source.
+prune app

pygeodata_browser-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: pygeodata-browser
+Version: 0.1.0
+Summary: Registry browser (QC and code-review dashboard) for pygeodata
+Author-email: Jasper Roebroek <roebroek.jasper@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/jasperroebroek/pygeodata-browser
+Project-URL: Issues, https://github.com/jasperroebroek/pygeodata-browser/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygeodata<0.4,>=0.3.0
+Requires-Dist: flask
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Dynamic: license-file
+
+# pygeodata-browser
+
+QC and code-review dashboard for [pygeodata](../pygeodata) projects. Serves the
+registry browser: class column, entries table, entry detail popups, code
+versioning view, export view, and bounds map.
+
+The CLI stays in core — `pygeodata browse` delegates to this package. To run
+standalone:
+
+```
+python -m pygeodata_browser
+```
+
+It reads a pygeodata project's on-disk state: the `.source/` registries, the
+cache roots and `.source/catalog.db`.
+
+## Install
+
+```
+pip install pygeodata-browser
+# or, from the core package:
+pip install pygeodata[browser]
+```
+
+## Development
+
+```
+ruff format . && ruff check .
+python -m pytest -q
+```
+
+### Frontend
+
+The UI is a Svelte app in `app/`. Its build output, `api/static/app/`, is what
+the server serves at `/`; it is not committed.
+
+```
+cd app
+npm ci
+npx vite --port 5173      # dev server with hot reload; proxies /api to the browser on :8780
+npm run check             # type check
+npm run build             # writes api/static/app/ (needed for `pygeodata browse` from a checkout)
+```
+
+`app/e2e/` holds Playwright scripts (screenshots, toggle and detail checks, timings); see its README.
+
+## Release
+
+The version comes from the git tag (setuptools-scm); there is no version string
+to bump. Pushing a version tag publishes to PyPI:
+
+```
+git tag v0.1.0 && git push --tags
+```
+
+`.github/workflows/release.yml` builds the frontend, builds the wheel and sdist
+(both ship the prebuilt frontend, so installing never needs Node), checks them
+with `scripts/check_dist.py`, and publishes through PyPI trusted publishing.
+
+Requires pygeodata 0.3.x; release a compatible pygeodata first when both change.

pygeodata_browser-0.1.0/README.md

@@ -0,0 +1,60 @@
+# pygeodata-browser
+
+QC and code-review dashboard for [pygeodata](../pygeodata) projects. Serves the
+registry browser: class column, entries table, entry detail popups, code
+versioning view, export view, and bounds map.
+
+The CLI stays in core — `pygeodata browse` delegates to this package. To run
+standalone:
+
+```
+python -m pygeodata_browser
+```
+
+It reads a pygeodata project's on-disk state: the `.source/` registries, the
+cache roots and `.source/catalog.db`.
+
+## Install
+
+```
+pip install pygeodata-browser
+# or, from the core package:
+pip install pygeodata[browser]
+```
+
+## Development
+
+```
+ruff format . && ruff check .
+python -m pytest -q
+```
+
+### Frontend
+
+The UI is a Svelte app in `app/`. Its build output, `api/static/app/`, is what
+the server serves at `/`; it is not committed.
+
+```
+cd app
+npm ci
+npx vite --port 5173      # dev server with hot reload; proxies /api to the browser on :8780
+npm run check             # type check
+npm run build             # writes api/static/app/ (needed for `pygeodata browse` from a checkout)
+```
+
+`app/e2e/` holds Playwright scripts (screenshots, toggle and detail checks, timings); see its README.
+
+## Release
+
+The version comes from the git tag (setuptools-scm); there is no version string
+to bump. Pushing a version tag publishes to PyPI:
+
+```
+git tag v0.1.0 && git push --tags
+```
+
+`.github/workflows/release.yml` builds the frontend, builds the wheel and sdist
+(both ship the prebuilt frontend, so installing never needs Node), checks them
+with `scripts/check_dist.py`, and publishes through PyPI trusted publishing.
+
+Requires pygeodata 0.3.x; release a compatible pygeodata first when both change.

pygeodata_browser-0.1.0/api/__init__.py

@@ -0,0 +1,10 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from pygeodata_browser.serve import open_registry_browser
+
+try:
+    __version__ = version('pygeodata-browser')
+except PackageNotFoundError:  # imported from a source tree that is not installed
+    __version__ = '0+unknown'
+
+__all__ = ['open_registry_browser', '__version__']

pygeodata_browser-0.1.0/api/__main__.py

@@ -0,0 +1,27 @@
+import click
+
+from pygeodata_browser.serve import open_registry_browser
+
+
+@click.command()
+@click.option('--port', default=0, show_default=True, help='Port to listen on (0 = random free port).')
+@click.option(
+    '--fast/--no-fast',
+    'fast',
+    default=False,
+    help='Serve the UI immediately from the catalog bootstrap while the full state builds.',
+)
+@click.option(
+    '--reconcile-interval',
+    default=0.0,
+    show_default=True,
+    type=float,
+    help='Minutes between automatic catalog reconciles (0 disables).',
+)
+def main(port: int, fast: bool, reconcile_interval: float) -> None:
+    """Serve the pygeodata registry browser."""
+    open_registry_browser(port, fast=fast, reconcile_interval=reconcile_interval * 60, reimport_on_reconcile=False)
+
+
+if __name__ == '__main__':
+    main()

pygeodata_browser-0.1.0/api/code_service.py

@@ -0,0 +1,289 @@
+"""Domain logic for the /api/code/* routes.
+
+Routes in web.py parse request args, call these functions, and jsonify the
+result.  No Flask imports here.
+"""
+
+from __future__ import annotations
+
+from difflib import SequenceMatcher, unified_diff
+
+from pygeodata.ast import get_source_code
+from pygeodata.catalog.types import CodeClassState
+from pygeodata.hash import calculate_cls_source_hash
+from pygeodata.paths import CodeRegistryPathConstructor
+from pygeodata.registries.versioning import VersionRegistry
+from pygeodata.tracked_object import TrackedObject
+
+
+def _word_segments(text_old: str, text_new: str) -> tuple[list[dict], list[dict]]:
+    """Compute word-level diff segments for a paired del/add line.
+
+    Returns (segments_old, segments_new) where each segment is
+    {'type': 'eq'|'del'|'ins', 'text': str}.
+    """
+
+    def tokenise(s: str) -> list[str]:
+        import re
+
+        return re.findall(r'\w+|\W', s)
+
+    tokens_old = tokenise(text_old)
+    tokens_new = tokenise(text_new)
+    matcher = SequenceMatcher(None, tokens_old, tokens_new, autojunk=False)
+    segs_old: list[dict] = []
+    segs_new: list[dict] = []
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        old_text = ''.join(tokens_old[i1:i2])
+        new_text = ''.join(tokens_new[j1:j2])
+        if tag == 'equal':
+            segs_old.append({'type': 'eq', 'text': old_text})
+            segs_new.append({'type': 'eq', 'text': new_text})
+        elif tag == 'replace':
+            segs_old.append({'type': 'del', 'text': old_text})
+            segs_new.append({'type': 'ins', 'text': new_text})
+        elif tag == 'delete':
+            segs_old.append({'type': 'del', 'text': old_text})
+        elif tag == 'insert':
+            segs_new.append({'type': 'ins', 'text': new_text})
+    return segs_old, segs_new
+
+
+def _build_structured_hunks(text_old: str, text_new: str) -> list[dict]:
+    """Parse a unified diff into structured hunks with line numbers and word segments.
+
+    Each hunk: {header, start_old, start_new, lines: [...]}.
+    Each line: {type, text, line_old, line_new, segments?}.
+    Paired del/add lines (a del immediately followed by an add) get word segments.
+    """
+    raw_diff = ''.join(
+        unified_diff(
+            text_old.splitlines(keepends=True),
+            text_new.splitlines(keepends=True),
+            fromfile='old',
+            tofile='new',
+        ),
+    )
+
+    hunks: list[dict] = []
+    current_hunk: dict | None = None
+    line_old = 0
+    line_new = 0
+
+    for raw in raw_diff.splitlines():
+        if raw.startswith('--- ') or raw.startswith('+++ '):
+            continue
+        if raw.startswith('@@'):
+            import re
+
+            m = re.match(r'@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@', raw)
+            line_old = int(m.group(1)) if m else 1
+            line_new = int(m.group(2)) if m else 1
+            current_hunk = {'header': raw, 'start_old': line_old, 'start_new': line_new, 'lines': []}
+            hunks.append(current_hunk)
+        elif current_hunk is not None:
+            if raw.startswith('+'):
+                current_hunk['lines'].append({'type': 'add', 'text': raw[1:], 'line_old': None, 'line_new': line_new})
+                line_new += 1
+            elif raw.startswith('-'):
+                current_hunk['lines'].append({'type': 'del', 'text': raw[1:], 'line_old': line_old, 'line_new': None})
+                line_old += 1
+            elif raw != '\':
+                current_hunk['lines'].append(
+                    {'type': 'ctx', 'text': raw[1:], 'line_old': line_old, 'line_new': line_new},
+                )
+                line_old += 1
+                line_new += 1
+
+    # Pair consecutive del+add lines and add word segments
+    for hunk in hunks:
+        lines = hunk['lines']
+        i = 0
+        while i < len(lines):
+            if lines[i]['type'] == 'del':
+                # Collect run of dels then run of adds
+                j = i
+                while j < len(lines) and lines[j]['type'] == 'del':
+                    j += 1
+                k = j
+                while k < len(lines) and lines[k]['type'] == 'add':
+                    k += 1
+                dels = lines[i:j]
+                adds = lines[j:k]
+                pairs = min(len(dels), len(adds))
+                for p in range(pairs):
+                    segs_old, segs_new = _word_segments(dels[p]['text'], adds[p]['text'])
+                    dels[p]['segments'] = segs_old
+                    adds[p]['segments'] = segs_new
+                i = k
+            else:
+                i += 1
+
+    return hunks
+
+
+def version_classes(version_id: str, vreg: VersionRegistry) -> list[CodeClassState]:
+    """Return per-class CodeState at the given version, annotated with live staleness.
+
+    Pass a Version.version_id to select that group, or '' for the newest group.
+    """
+    src = vreg.source_registry
+    vi = vreg.version_by_id(version_id) if version_id else (vreg.versions[0] if vreg.versions else None)
+    if vi is None:
+        return []
+
+    snap = vreg.class_snapshot_at_version(vi)
+    result = []
+    for class_name in sorted(src.class_names):
+        source_hash = snap.get(class_name)
+        if source_hash is None:
+            continue
+        best = next((s for s in src.get_states(class_name) if s.source_hash == source_hash), None)
+        if best is None:
+            continue
+        cls = TrackedObject.find_object_class(class_name)
+        is_loaded = cls is not None
+        is_stale = is_loaded and calculate_cls_source_hash(cls) != source_hash
+        result.append(
+            CodeClassState(
+                class_name=class_name,
+                object_type=best.object_type,
+                source_hash=source_hash,
+                is_loaded=is_loaded,
+                is_stale=is_stale,
+            ),
+        )
+    return result
+
+
+def _source_text(source_hash: str, vreg: VersionRegistry) -> tuple[str, str | None] | None:
+    """(source, class_name) for a hash: the stored snapshot, else a loaded class whose code has that hash.
+
+    pygeodata stores a class's source only when it runs, so the live code of an
+    edited-but-not-yet-run class (the 'Live' version) has no stored snapshot.
+    """
+    src = vreg.source_registry
+    text = src.get_source(source_hash)
+    if text is not None:
+        return text, src.get_class_name_from_hash(source_hash)
+    cls = next((c for c in TrackedObject.get_registered_objects() if _live_source_hash(c) == source_hash), None)
+    return (get_source_code(cls), cls.get_class_name()) if cls is not None else None
+
+
+def _live_source_hash(cls: type[TrackedObject]) -> str | None:
+    try:
+        return calculate_cls_source_hash(cls)
+    except (OSError, TypeError):  # source unavailable (e.g. defined interactively)
+        return None
+
+
+def snapshot_html(source_hash: str, vreg: VersionRegistry) -> dict | None:
+    """Return {'class_name': ..., 'lines': [...]} for the given source hash.
+
+    Returns None if the snapshot is not found (caller should abort(404)).
+    """
+    src = vreg.source_registry
+    found = _source_text(source_hash, vreg)
+    if found is None:
+        return None
+
+    source_text, class_name = found
+    known_classes = frozenset(TrackedObject._registry.keys()) | frozenset(src.class_names)
+    lines = [
+        {'text': line, 'cls_link': line.strip() if line.strip() in known_classes else None}
+        for line in source_text.splitlines()
+    ]
+    return {'class_name': class_name, 'lines': lines}
+
+
+def diff_hashes(hash_old: str, hash_new: str, full: bool, vreg: VersionRegistry) -> dict | None:
+    """Return structured diff payload or None if either file is missing.
+
+    Returns {'hunks': [...], 'full_old'?: str, 'full_new'?: str}.
+    """
+    old = _source_text(hash_old, vreg)
+    new = _source_text(hash_new, vreg)
+    if old is None or new is None:
+        return None
+    text_old, text_new = old[0], new[0]
+
+    result: dict = {'hunks': _build_structured_hunks(text_old, text_new)}
+    if full:
+        result['full_old'] = text_old
+        result['full_new'] = text_new
+    return result
+
+
+def unified_diff_payload(
+    hash_old: str,
+    hash_new: str,
+    full: bool,
+    assert_allowed_path: callable,
+    vreg: VersionRegistry,
+) -> dict | None:
+    """HTTP-boundary wrapper around diff_hashes that enforces the path guard.
+
+    ``assert_allowed_path`` is the guard from web.py; calling it here keeps
+    the security check provably on the HTTP boundary for user-facing diffs.
+    Returns None when either source file does not exist (caller should abort(404)).
+    """
+    assert_allowed_path(str(CodeRegistryPathConstructor.from_source_hash(hash_old).source_path))
+    assert_allowed_path(str(CodeRegistryPathConstructor.from_source_hash(hash_new).source_path))
+    return diff_hashes(hash_old, hash_new, full, vreg)
+
+
+def version_diff(
+    vreg: VersionRegistry,
+    *,
+    record_id: str | None = None,
+    entries: dict | None = None,
+    base_version_id: str | None = None,
+    target_version_id: str = 'live',
+) -> dict:
+    """Compare two version snapshots and return a complete diff payload.
+
+    base_version_id is resolved in order:
+      1. Explicit base_version_id argument.
+      2. The version the entry (record_id) was produced at.
+    target_version_id defaults to 'live' (in-memory/disk current state).
+    Either base or target may be 'live'.
+
+    Returns {changes, base_version_id, has_live_stale} or an error dict.
+    Never raises — errors are encoded as {'error': ..., 'message': ...}.
+    """
+
+    def _resolve(version_id: str) -> dict[str, str] | None:
+        if version_id == 'live':
+            return vreg.live_snapshot()
+        if version_id == 'none':
+            return {}
+        return vreg.snapshot_for_version(version_id)
+
+    # Resolve base
+    resolved_base_id = base_version_id
+    if resolved_base_id is None:
+        if record_id is None or entries is None:
+            return {'error': 'bad_request', 'message': 'base_version_id or record_id required'}
+        entry = entries.get(record_id)
+        if entry is None:
+            return {'__not_found__': True}
+        dep_hash = entry.dep_hash
+        if not dep_hash:
+            return {'error': 'no_snapshot', 'message': 'Snapshot not available for this entry'}
+        version = vreg.dep_hash_to_version.get(dep_hash)
+        resolved_base_id = version.version_id if version else None
+
+    base = _resolve(resolved_base_id) if resolved_base_id else None
+    target = _resolve(target_version_id)
+
+    if base is None:
+        return {'error': 'no_snapshot', 'message': 'Base version not found'}
+    if target is None:
+        return {'error': 'no_snapshot', 'message': 'Target version not found'}
+
+    changes = [e.to_dict() for e in vreg.compare_versions(base, target)]
+    return {
+        'changes': changes,
+        'base_version_id': resolved_base_id,
+        'has_live_stale': vreg.has_live_stale(),
+    }