dstrack 0.1.0__py3-none-any.whl

dstrack/_log.py

@@ -0,0 +1,268 @@
+"""The ``dstrack log`` command: show a tracked dataset's history."""
+
+import os
+import sqlite3
+import sys
+import uuid
+from datetime import UTC, datetime
+from itertools import pairwise
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dstrack import cache, console, store
+from dstrack._log_render import render_history
+from dstrack.errors import (
+    DatasetNotFoundError,
+    StoreCorruptionError,
+    StoreNotFoundError,
+)
+from dstrack.paths import resolve_store_root
+
+
+def log(
+    target: Annotated[
+        str,
+        typer.Argument(
+            metavar="TARGET",
+            help="Dataset to show the history of: either a dataset id, or the "
+            "path to a tracked dataset file.",
+        ),
+    ],
+    limit: Annotated[
+        int | None,
+        typer.Option(
+            "-n",
+            "--limit",
+            min=1,
+            help="Show at most this many snapshots, counting back from the latest.",
+        ),
+    ] = None,
+    reverse: Annotated[
+        bool,
+        typer.Option("--reverse", help="Show oldest first instead of newest first."),
+    ] = False,
+    oneline: Annotated[
+        bool,
+        typer.Option("--oneline", help="Condense each snapshot to a single line."),
+    ] = False,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "-y",
+            "--yes",
+            help="Build the snapshot index without asking, if it does not exist yet.",
+        ),
+    ] = False,
+    rebuild: Annotated[
+        bool,
+        typer.Option(
+            "--rebuild",
+            help="Discard the snapshot index and rebuild it from the dataset logs.",
+        ),
+    ] = False,
+    root: Annotated[
+        Path | None,
+        typer.Option(
+            "--root",
+            help="Path root a TARGET path is made relative to, matching the one "
+            "`dstrack track` recorded it with. Defaults to the store root (the "
+            "directory containing .dstrack/). Ignored when TARGET is a dataset id.",
+        ),
+    ] = None,
+) -> None:
+    """Show the snapshot history of a tracked dataset."""
+    # Locate the .dstrack/ store; without one there is no history to show.
+    try:
+        store_root = resolve_store_root()
+    except StoreNotFoundError as e:
+        console.error(str(e))
+        raise typer.Exit(code=1) from e
+
+    _ensure_index(store_root, yes=yes, rebuild=rebuild)
+
+    try:
+        # Sync before resolving: the index does not travel with the repository,
+        # so a dataset tracked elsewhere is only visible once its log is read.
+        reason = cache.sync(store_root)
+        if reason is not None:
+            console.warning(f"Rebuilt the snapshot index: {reason}.")
+
+        dataset_id = _resolve_target(target, store_root=store_root, root=root)
+        history = cache.query_history(dataset_id, store_root=store_root)
+    except (
+        DatasetNotFoundError,
+        StoreCorruptionError,
+        ValueError,
+        OSError,
+        sqlite3.DatabaseError,
+    ) as e:
+        console.error(str(e))
+        raise typer.Exit(code=1) from e
+
+    if not history:
+        console.warning(f"Dataset {dataset_id} has no snapshots yet.")
+        return
+
+    # Deltas are keyed by lineage, not by display position, so that slicing and
+    # reversing below cannot change what a snapshot is compared against.
+    parents = {entry.snapshot_id: parent for entry, parent in pairwise(history)}
+    head = history[0].snapshot_id
+
+    # Limit counts back from HEAD, then --reverse flips what is shown; the two
+    # compose the way `git log -n ... --reverse` does.
+    shown = history if limit is None else history[:limit]
+    if reverse:
+        shown = list(reversed(shown))
+
+    console.display(
+        render_history(
+            shown,
+            parents=parents,
+            head_id=head,
+            now=datetime.now(UTC),
+            oneline=oneline,
+        )
+    )
+
+
+def _ensure_index(store_root: Path, *, yes: bool, rebuild: bool) -> None:
+    """Make sure the snapshot index may be built, asking first if need be.
+
+    Building parses every dataset's log, so it is offered rather than done
+    silently. Consent is only about the first build: an index that exists but
+    cannot be used is rebuilt without asking, since it holds nothing that the
+    logs do not.
+
+    Args:
+        store_root: Path to the ``.dstrack/`` directory.
+        yes: Consent given up front, so nothing is asked.
+        rebuild: Discard any existing index, which implies consent.
+
+    Raises:
+        typer.Exit: Code 0 if the user declines to build it; code 1 if there
+            is no index and no terminal to ask at.
+    """
+    path = cache.index_path(store_root)
+    if rebuild:
+        path.unlink(missing_ok=True)
+        console.info("Rebuilding the snapshot index from the dataset logs...")
+        return
+    if cache.index_exists(store_root):
+        return
+
+    if not yes:
+        if not sys.stdin.isatty():
+            console.error(
+                f"No snapshot index at `{path}`, and there is no terminal to "
+                "ask whether to build one. Re-run with `--yes` to build it."
+            )
+            raise typer.Exit(code=1)
+        console.info(f"No snapshot index at `{path}` yet.")
+        if not typer.confirm("Build it now from the dataset logs?"):
+            console.warning(
+                "Not building the index; there is nothing to show without it."
+            )
+            raise typer.Exit(code=0)
+
+    console.info("Building the snapshot index from the dataset logs...")
+
+
+def _resolve_target(target: str, *, store_root: Path, root: Path | None) -> str:
+    """Resolve a user-supplied dataset id or path to a dataset id.
+
+    A ``dataset_id`` is a random UUID4, so nothing about it can be
+    derived from a path: a path is resolved by matching it against what each
+    dataset last recorded. `target` is read as an id first and as a path
+    second, but only when the id names a dataset that exists. Reading it as a
+    path first would let any file in the current directory shadow a real id,
+    and would send a mistyped path into the id lookup, which can only report
+    that no dataset goes by that name.
+
+    Args:
+        target: A dataset id, or a path to a tracked dataset file.
+        store_root: Path to the ``.dstrack/`` directory.
+        root: Path root a `target` path is made relative to, or ``None`` to
+            use the store root.
+
+    Returns:
+        The id of the dataset `target` names.
+
+    Raises:
+        DatasetNotFoundError: If `target` is an id no dataset goes by, or a
+            path no dataset last recorded.
+        ValueError: If `target` and the path root are on different drives, so
+            no relative path exists between them.
+    """
+    canonical = _canonical_uuid(target)
+    if canonical is not None and store.dataset_exists(canonical, store_root=store_root):
+        return canonical
+
+    path_root = root if root is not None else store_root.parent
+    dataset_path = Path(
+        os.path.relpath(Path(target).resolve(), Path(path_root).resolve())
+    ).as_posix()
+
+    matched = cache.find_dataset_by_path(dataset_path, store_root=store_root)
+    if matched is not None:
+        return matched
+
+    if canonical is not None:
+        raise DatasetNotFoundError(
+            f"No dataset {target!r} in the store.\n{_known_datasets(store_root)}"
+        )
+    raise DatasetNotFoundError(
+        f"No tracked dataset at {target!r} (recorded as {dataset_path!r} "
+        f"relative to {path_root}).\n"
+        "If the file was renamed or moved, its recorded path no longer "
+        "matches; pass the dataset id instead. Use `--root` to change the "
+        "path root the recorded path is computed against.\n"
+        f"{_known_datasets(store_root)}"
+    )
+
+
+def _canonical_uuid(value: str) -> str | None:
+    """Return `value` as a canonical UUID string, or ``None`` if it is not one.
+
+    Datasets are named by ``str(uuid.uuid4())``, but a user may paste an id
+    uppercased, braced, or without its dashes, all of which name the same
+    dataset. Canonicalizing accepts those spellings, and makes the result
+    provably free of path separators before it is joined onto the store.
+
+    Args:
+        value: The string to interpret.
+
+    Returns:
+        The canonical form of `value` if it is a UUID in any spelling, else
+        ``None``.
+    """
+    try:
+        return str(uuid.UUID(value))
+    except (ValueError, AttributeError, TypeError):
+        return None
+
+
+def _known_datasets(store_root: Path) -> str:
+    """List the store's datasets, for an error message to end on.
+
+    A dataset id says nothing on its own, so each is shown with the name and
+    path its latest snapshot recorded: that is what lets a reader recognize
+    the dataset they meant and copy its id.
+
+    Args:
+        store_root: Path to the ``.dstrack/`` directory.
+
+    Returns:
+        An indented listing of every dataset, or a note that there are none.
+    """
+    datasets = cache.list_datasets(store_root=store_root)
+    lines = [
+        f"  {d.dataset_id}  {(d.head.dataset_name if d.head else None) or '-'}  "
+        f"{(d.head.dataset_path if d.head else None) or '-'}"
+        for d in datasets
+    ]
+    if not lines:
+        return "Known datasets:\n  (none)\nRun `dstrack track <path>` to record one."
+    listing = "\n".join(lines)
+    return f"Known datasets:\n{listing}"

dstrack/_log_render.py

@@ -0,0 +1,282 @@
+"""Rendering of a dataset's history as a timeline.
+
+This is the only layer that knows what a dataset's history looks like on
+screen. It builds renderables and returns them; printing is the caller's job.
+
+The timeline is a two-column ``Table.grid``: a rail on the left, one glyph per
+line, and the snapshot's facts on the right. Keeping one grid row per rendered
+line is what holds the rail in step with the text beside it, and it is why the
+content column must keep rich's default overflow: a column told not to wrap is
+dropped entirely when the grid has to shrink, taking the rail's glyphs with it
+and leaving a plausible-looking but railless timeline on narrow terminals.
+
+Every value that reaches a cell comes from the store, which means it comes from
+whatever the user passed to `dstrack track --name` or from a path on disk.
+Cells are therefore assembled as `Text`, never interpolated into rich's markup:
+a dataset named ``sales[/]report`` is not markup to be parsed, and treating it
+as such raises rather than prints.
+"""
+
+from collections.abc import Mapping, Sequence
+from datetime import UTC, datetime
+from typing import Final
+
+from rich.console import Group, RenderableType
+from rich.table import Table
+from rich.text import Text
+
+from dstrack.store import LogEntry
+
+_MISSING: Final = "\N{EM DASH}"
+_NODE: Final = "\N{BLACK CIRCLE}"
+_RAIL: Final = "\N{BOX DRAWINGS LIGHT VERTICAL}"
+_SHORT_ID_LEN: Final = 8
+
+# Largest unit first; each is the number of seconds in one of that unit.
+_UNITS: Final[tuple[tuple[str, int], ...]] = (
+    ("year", 365 * 24 * 3600),
+    ("month", 30 * 24 * 3600),
+    ("week", 7 * 24 * 3600),
+    ("day", 24 * 3600),
+    ("hour", 3600),
+    ("minute", 60),
+    ("second", 1),
+)
+
+
+def render_history(
+    entries: Sequence[LogEntry],
+    *,
+    parents: Mapping[str, LogEntry],
+    head_id: str,
+    now: datetime,
+    oneline: bool = False,
+) -> RenderableType:
+    """Render a dataset's snapshots as a timeline.
+
+    Args:
+        entries: The snapshots to show, in display order. May be a slice of
+            the dataset's full history.
+        parents: Each snapshot's predecessor, keyed by ``snapshot_id``, built
+            from the *full* history rather than `entries`. Passed separately
+            so that a snapshot whose parent was sliced off or reordered still
+            shows how it differed from it.
+        head_id: Id of the dataset's latest snapshot, marked in the output.
+        now: The moment to measure each snapshot's age against.
+        oneline: Condense each snapshot to a single line.
+
+    Returns:
+        A renderable timeline, newest or oldest first according to the order
+        of `entries`.
+    """
+    grid = Table.grid(padding=(0, 1))
+    grid.add_column(no_wrap=True)
+    # No overflow or wrap settings: rich's defaults ellipsize each cell to one
+    # line, which is what keeps every content line paired with one rail glyph.
+    grid.add_column()
+
+    for position, entry in enumerate(entries):
+        is_last = position == len(entries) - 1
+        parent = parents.get(entry.snapshot_id)
+        lines = (
+            [_oneline(entry, parent=parent, head_id=head_id, now=now)]
+            if oneline
+            else _detail_lines(entry, parent=parent, head_id=head_id, now=now)
+        )
+
+        for offset, line in enumerate(lines):
+            grid.add_row(
+                _glyph(entry, head_id=head_id, first=offset == 0, last=is_last), line
+            )
+        if not oneline and not is_last:
+            grid.add_row(Text(_RAIL, style="dim cyan"), "")
+
+    return Group(grid)
+
+
+def _glyph(entry: LogEntry, *, head_id: str, first: bool, last: bool) -> Text:
+    """Return the rail character for one rendered line.
+
+    Args:
+        entry: The snapshot the line belongs to.
+        head_id: Id of the dataset's latest snapshot.
+        first: Whether this is the snapshot's first line, which carries the
+            node rather than the rail.
+        last: Whether this is the oldest snapshot shown. Its continuation lines
+            carry no rail, so the timeline ends at the node instead of trailing
+            off below it.
+
+    Returns:
+        The styled glyph to place in the rail column.
+    """
+    if first:
+        style = "bold cyan" if entry.snapshot_id == head_id else "cyan"
+        return Text(_NODE, style=style)
+    return Text(" " if last else _RAIL, style="dim cyan")
+
+
+def _detail_lines(
+    entry: LogEntry, *, parent: LogEntry | None, head_id: str, now: datetime
+) -> list[Text]:
+    """Render one snapshot as its multi-line timeline entry.
+
+    Args:
+        entry: The snapshot to render.
+        parent: The snapshot it succeeds, for computing deltas, or ``None``.
+        head_id: Id of the dataset's latest snapshot.
+        now: The moment to measure the snapshot's age against.
+
+    Returns:
+        One `Text` per line, each rendered beside its own rail glyph.
+    """
+    title = Text()
+    title.append(_short_id(entry.snapshot_id), style="bold yellow")
+    title.append("  ")
+    title.append(entry.dataset_name or _MISSING, style="bold")
+    if entry.snapshot_id == head_id:
+        title.append("  HEAD", style="bold cyan")
+
+    when = Text()
+    when.append(_humanize(entry.created_at, now))
+    when.append("  by ", style="dim")
+    when.append(entry.created_by or _MISSING)
+
+    counts = Text()
+    counts.append_text(
+        _count(entry.num_rows, "row", parent.num_rows if parent else None)
+    )
+    counts.append("   ")
+    counts.append_text(
+        _count(entry.num_columns, "col", parent.num_columns if parent else None)
+    )
+
+    return [title, when, counts, Text(entry.dataset_path or _MISSING, style="dim")]
+
+
+def _oneline(
+    entry: LogEntry, *, parent: LogEntry | None, head_id: str, now: datetime
+) -> Text:
+    """Render one snapshot as a single timeline line.
+
+    Args:
+        entry: The snapshot to render.
+        parent: The snapshot it succeeds, for computing deltas, or ``None``.
+        head_id: Id of the dataset's latest snapshot.
+        now: The moment to measure the snapshot's age against.
+
+    Returns:
+        The snapshot's identity, age, name and row count on one line.
+    """
+    line = Text()
+    line.append(_short_id(entry.snapshot_id), style="bold yellow")
+    line.append("  ")
+    line.append(_humanize(entry.created_at, now), style="dim")
+    line.append("  ")
+    line.append(entry.dataset_name or _MISSING, style="bold")
+    line.append("  ")
+    line.append_text(_count(entry.num_rows, "row", parent.num_rows if parent else None))
+    if entry.snapshot_id == head_id:
+        line.append("  HEAD", style="bold cyan")
+    return line
+
+
+def _count(value: int | None, unit: str, parent: int | None) -> Text:
+    """Render a count and how it changed from its parent.
+
+    Args:
+        value: The count, or ``None`` if the snapshot did not record one.
+        unit: Singular name of what is being counted, e.g. ``"row"``.
+        parent: The parent snapshot's count, or ``None`` if there is no parent
+            or it recorded none.
+
+    Returns:
+        The count, or an em-dash if it is missing, followed by its signed
+        change when one can be computed.
+    """
+    text = Text()
+    text.append(_MISSING if value is None else f"{value:,}", style="bold")
+    text.append(f" {unit}" if value == 1 else f" {unit}s", style="dim")
+
+    delta = _delta(value, parent)
+    if delta is not None:
+        text.append(" ")
+        text.append(delta[0], style=delta[1])
+    return text
+
+
+def _delta(value: int | None, parent: int | None) -> tuple[str, str] | None:
+    """Return a count's signed change and the style to render it in.
+
+    Args:
+        value: The snapshot's count.
+        parent: The parent snapshot's count.
+
+    Returns:
+        The change and its style, or ``None`` when there is nothing to say:
+        no parent, an unrecorded count on either side, or no change at all. An
+        em-dash marks a missing *value*; a delta that cannot be computed is
+        simply not shown, rather than shown as unknown.
+    """
+    if value is None or parent is None or value == parent:
+        return None
+    change = value - parent
+    return f"{change:+,}", "green" if change > 0 else "red"
+
+
+def _short_id(snapshot_id: str) -> str:
+    """Return the leading characters of a snapshot id, as git shows a commit."""
+    return snapshot_id[:_SHORT_ID_LEN]
+
+
+def _humanize(created_at: str | None, now: datetime) -> str:
+    """Render when a snapshot was taken, relative to `now`.
+
+    Args:
+        created_at: The recorded timestamp, as it appears in the log.
+        now: The moment to measure against.
+
+    Returns:
+        An approximate age such as ``"3 days ago"``, or an em-dash if the
+        timestamp is missing or unreadable. A snapshot dated in the future
+        reads as ``"in 3 days"``: the store travels between machines by git,
+        so a teammate's clock can legitimately be ahead of this one.
+    """
+    when = _parse_created_at(created_at)
+    if when is None:
+        return _MISSING
+
+    seconds = int((now - when).total_seconds())
+    magnitude = abs(seconds)
+    if magnitude < 1:
+        return "just now"
+
+    for unit, size in _UNITS:
+        if magnitude >= size:
+            count = magnitude // size
+            plural = "" if count == 1 else "s"
+            return (
+                f"{count} {unit}{plural} ago"
+                if seconds > 0
+                else f"in {count} {unit}{plural}"
+            )
+    return "just now"
+
+
+def _parse_created_at(created_at: str | None) -> datetime | None:
+    """Parse a recorded timestamp into an aware datetime.
+
+    Args:
+        created_at: The recorded timestamp, as it appears in the log.
+
+    Returns:
+        The timestamp, or ``None`` if it is missing or unparsable. A timestamp
+        without an offset is read as UTC, which is what the store writes; it
+        cannot be left naive, since subtracting it from an aware `now` raises.
+    """
+    if created_at is None:
+        return None
+    try:
+        parsed = datetime.fromisoformat(created_at)
+    except ValueError:
+        return None
+    return parsed.replace(tzinfo=UTC) if parsed.tzinfo is None else parsed

dstrack/_logging.py

@@ -0,0 +1,60 @@
+"""Logging setup for dstrack.
+
+Every module gets its own logger via ``logging.getLogger(__name__)``, all of
+which are children of, and propagate to, the top-level ``"dstrack"`` logger
+configured here. Applications embedding dstrack are free to configure that
+hierarchy however they like: ``logging.basicConfig()``, attaching handlers to
+the root logger, or attaching handlers directly to ``logging.getLogger("dstrack")``.
+
+If the application does none of that,
+[_DefaultHandler][dstrack._logging._DefaultHandler] prints
+``WARNING``-and-above records to stderr with a sensible default format so
+messages are never silently dropped. It steps aside automatically the moment
+it detects that the application has configured logging itself.
+"""
+
+import logging
+from typing import TextIO
+
+_FORMAT = "%(asctime)s %(levelname)-8s %(name)s: %(message)s"
+
+logger = logging.getLogger("dstrack")
+
+
+class _DefaultHandler(logging.StreamHandler[TextIO]):
+    """Stderr handler used only until the application configures logging.
+
+    Yields to any handler the application attaches to the root logger or to
+    the ``dstrack`` logger, so it never produces duplicate output.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if logging.root.handlers:
+            return
+        if any(h is not self for h in logger.handlers):
+            return
+        super().emit(record)
+
+
+def _configure_default_logging() -> None:
+    """Attach the fallback stderr handler to the ``dstrack`` logger.
+
+    Called once, at import time. The handler installed here checks, on every
+    record, whether the application has since configured logging itself and
+    stays silent if so, see
+    [_DefaultHandler.emit()][dstrack._logging._DefaultHandler.emit].
+
+    A no-op if a [_DefaultHandler][dstrack._logging._DefaultHandler] is already
+    attached: since two of them would each treat the other as an
+    application-supplied handler and both step aside, re-running this (e.g. via
+    ``importlib.reload`` under Jupyter's autoreload) would otherwise silence
+    dstrack's logging entirely.
+    """
+    if any(isinstance(h, _DefaultHandler) for h in logger.handlers):
+        return
+    handler = _DefaultHandler()
+    handler.setFormatter(logging.Formatter(_FORMAT))
+    logger.addHandler(handler)
+
+
+_configure_default_logging()

dstrack/_store_template.py

@@ -0,0 +1,58 @@
+"""Declarative description of the local store's directory structure."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Final
+
+from dstrack.paths import STORE_DIRNAME
+
+
+@dataclass(frozen=True)
+class TemplateFile:
+    """A file to create, with its literal content."""
+
+    name: str
+    content: str = ""
+
+
+@dataclass(frozen=True)
+class TemplateDir:
+    """A directory to create, optionally containing files and subdirectories."""
+
+    name: str
+    entries: "tuple[TemplateDir | TemplateFile, ...]" = field(default_factory=tuple)
+
+
+STORE_TEMPLATE: Final[TemplateDir] = TemplateDir(
+    name=STORE_DIRNAME,
+    entries=(
+        TemplateDir(name="datasets"),
+        TemplateFile(name=".gitignore", content=".cache/"),
+    ),
+)
+
+
+def materialize(template: TemplateDir, parent: Path) -> Path:
+    """Recursively create `template`'s directory structure under `parent`.
+
+    Args:
+        template: Directory template to materialize, including the
+            top-level directory itself.
+        parent: Existing directory that `template`'s directory is created in.
+
+    Returns:
+        The path created for `template`.
+
+    Raises:
+        FileExistsError: If any file or directory in the template already
+            exists under `parent`.
+    """
+    path = parent / template.name
+    path.mkdir()
+    for entry in template.entries:
+        if isinstance(entry, TemplateDir):
+            materialize(entry, path)
+        else:
+            with open(path / entry.name, "x") as f:
+                f.write(entry.content)
+    return path