Skip to content

log

log #

Log — the tree of entries one to() block writes, and the one place it changes.

  1. Add. add and add_progress put a new entry beneath a parent — or, when the parent lies inside an iterated Progress, revise the entry already in that call site's slot for this iteration (the loop rule), so a line logged every iteration is one line, not thousands. A revised entry is logged anew: its clock restarts, a past failure clears, and what was logged beneath it before is dropped, so it shows only its latest run.
  2. Change. Every mutation runs inside changing(entry): under the log's lock, then the revision bumps and every sink is told.
  3. Read. entries (parents before children), children and json are the views a sink or a renderer takes.

Site = tuple[CodeType, int] #

The code location that logged: a function's code object and a line in it.

Slot = tuple[str, str] | tuple[CodeType, int, int] #

Where an entry sits beneath its parent: a key, or a site and its ordinal this iteration.

Log #

The entries of one to() block; root is the unlogged parent of the top level.

Source code in capturegraph-lib/capturegraph/logging/log.py
class Log:
    """The entries of one ``to()`` block; ``root`` is the unlogged parent of the top level."""

    def __init__(self, sinks: Iterable[Sink]) -> None:
        """An empty log whose entries go to ``sinks``."""
        self._sinks = tuple(sinks)
        self._lock = RLock()
        self._entries: list[Entry] = []
        self._made = 0
        self.root = Entry(self, "", None, "info", "", {}, None)
        self._branches: dict[str, _Branch] = {self.root.id: _Branch(None)}

    def add(
        self,
        parent: Entry,
        level: Level,
        message: str,
        fields: dict[str, JSONValue],
        *,
        key: str | None,
        kind: Kind,
        site: Site | None,
    ) -> Entry:
        """A line beneath ``parent``, or the revised line already in its slot."""
        with self._lock:
            branch = self._branches[parent.id]
            found, slot = self._place(branch, key, site)
            if found is not None and type(found) is Entry:
                with self.changing(found):
                    self._restart(found)
                    found.level = level
                    found.message = message
                    found.kind = kind
                    found.fields = dict(fields)
                    found.iteration = _iteration(branch)
                return found
            entry = Entry(
                self,
                self._next_id(),
                self._id_of(parent),
                level,
                message,
                dict(fields),
                _iteration(branch),
                kind,
            )
            self._attach(branch, entry, slot)
            return entry

    def add_progress[T](
        self,
        parent: Entry,
        label: str,
        *,
        key: str | None,
        site: Site | None,
        total: int | None,
        iterable: Iterable[T] | None,
    ) -> Progress[T]:
        """A count beneath ``parent``, or the one already in its slot, reset to start over."""
        with self._lock:
            branch = self._branches[parent.id]
            found, slot = self._place(branch, key, site)
            if isinstance(found, Progress):
                with self.changing(found):
                    self._restart(found)
                    found.message = label
                    found.done = 0
                    found.total = total
                    found.iteration = None
                    found._iterable = iterable
                return found
            entry = Progress(
                self,
                self._next_id(),
                self._id_of(parent),
                label,
                {},
                _iteration(branch),
                total=total,
                iterable=iterable,
            )
            self._attach(branch, entry, slot)
            return entry

    @contextmanager
    def changing(self, entry: Entry) -> Iterator[None]:
        """Mutate ``entry`` in the block; then its revision bumps and the sinks hear."""
        with self._lock:
            yield
            entry.revision += 1
            self._emit(entry)

    def entries(self) -> list[Entry]:
        """Every entry, parents before children."""
        with self._lock:
            return list(self._entries)

    def children(self, parent: Entry) -> list[Entry]:
        """The entries directly beneath ``parent`` (``root`` for the top level), oldest first."""
        with self._lock:
            return list(self._branches[parent.id].children)

    def json(self) -> list[dict[str, JSONValue]]:
        """Every entry's wire shape, parents before children."""
        return [entry.json() for entry in self.entries()]

    def _place(
        self,
        branch: _Branch,
        key: str | None,
        site: Site | None,
    ) -> tuple[Entry | None, Slot | None]:
        slot: Slot | None = None
        iteration = _iteration(branch)
        if key is not None:
            slot = ("key", key)
        elif site is not None and iteration is not None:
            if branch.counted != iteration:
                branch.counts.clear()
                branch.counted = iteration
            ordinal = branch.counts.get(site, 0)
            branch.counts[site] = ordinal + 1
            slot = (site[0], site[1], ordinal)
        found = branch.slots.get(slot) if slot is not None else None
        return found, slot

    def _attach(self, branch: _Branch, entry: Entry, slot: Slot | None) -> None:
        self._entries.append(entry)
        branch.children.append(entry)
        if slot is not None:
            branch.slots[slot] = entry
        self._branches[entry.id] = _Branch(entry if isinstance(entry, Progress) else branch.loop)
        self._emit(entry)

    def _restart(self, entry: Entry) -> None:
        """``entry`` as just made: started now, ended as a plain line, no failure, no children."""
        entry.started = time.time()
        entry.ended = entry.started
        entry.status = "done"
        entry.error = None
        dropped = self._drop_beneath(entry)
        if dropped:
            self._entries = [kept for kept in self._entries if kept.id not in dropped]

    def _drop_beneath(self, parent: Entry) -> set[str]:
        branch = self._branches[parent.id]
        dropped: set[str] = set()
        for child in branch.children:
            dropped |= self._drop_beneath(child)
            dropped.add(child.id)
            del self._branches[child.id]
        branch.children.clear()
        branch.slots.clear()
        branch.counts.clear()
        branch.counted = None
        return dropped

    def _next_id(self) -> str:
        self._made += 1
        return str(self._made)

    def _id_of(self, parent: Entry) -> str | None:
        return None if parent is self.root else parent.id

    def _emit(self, entry: Entry) -> None:
        for sink in self._sinks:
            try:
                sink.emit(entry)
            except Exception:  # noqa: BLE001 — a broken sink must not break the computation
                logger.exception(f"logging: {sink!r} failed on {entry!r}")

__init__(sinks) #

An empty log whose entries go to sinks.

Source code in capturegraph-lib/capturegraph/logging/log.py
def __init__(self, sinks: Iterable[Sink]) -> None:
    """An empty log whose entries go to ``sinks``."""
    self._sinks = tuple(sinks)
    self._lock = RLock()
    self._entries: list[Entry] = []
    self._made = 0
    self.root = Entry(self, "", None, "info", "", {}, None)
    self._branches: dict[str, _Branch] = {self.root.id: _Branch(None)}

add(parent, level, message, fields, *, key, kind, site) #

A line beneath parent, or the revised line already in its slot.

Source code in capturegraph-lib/capturegraph/logging/log.py
def add(
    self,
    parent: Entry,
    level: Level,
    message: str,
    fields: dict[str, JSONValue],
    *,
    key: str | None,
    kind: Kind,
    site: Site | None,
) -> Entry:
    """A line beneath ``parent``, or the revised line already in its slot."""
    with self._lock:
        branch = self._branches[parent.id]
        found, slot = self._place(branch, key, site)
        if found is not None and type(found) is Entry:
            with self.changing(found):
                self._restart(found)
                found.level = level
                found.message = message
                found.kind = kind
                found.fields = dict(fields)
                found.iteration = _iteration(branch)
            return found
        entry = Entry(
            self,
            self._next_id(),
            self._id_of(parent),
            level,
            message,
            dict(fields),
            _iteration(branch),
            kind,
        )
        self._attach(branch, entry, slot)
        return entry

add_progress(parent, label, *, key, site, total, iterable) #

A count beneath parent, or the one already in its slot, reset to start over.

Source code in capturegraph-lib/capturegraph/logging/log.py
def add_progress[T](
    self,
    parent: Entry,
    label: str,
    *,
    key: str | None,
    site: Site | None,
    total: int | None,
    iterable: Iterable[T] | None,
) -> Progress[T]:
    """A count beneath ``parent``, or the one already in its slot, reset to start over."""
    with self._lock:
        branch = self._branches[parent.id]
        found, slot = self._place(branch, key, site)
        if isinstance(found, Progress):
            with self.changing(found):
                self._restart(found)
                found.message = label
                found.done = 0
                found.total = total
                found.iteration = None
                found._iterable = iterable
            return found
        entry = Progress(
            self,
            self._next_id(),
            self._id_of(parent),
            label,
            {},
            _iteration(branch),
            total=total,
            iterable=iterable,
        )
        self._attach(branch, entry, slot)
        return entry

changing(entry) #

Mutate entry in the block; then its revision bumps and the sinks hear.

Source code in capturegraph-lib/capturegraph/logging/log.py
@contextmanager
def changing(self, entry: Entry) -> Iterator[None]:
    """Mutate ``entry`` in the block; then its revision bumps and the sinks hear."""
    with self._lock:
        yield
        entry.revision += 1
        self._emit(entry)

children(parent) #

The entries directly beneath parent (root for the top level), oldest first.

Source code in capturegraph-lib/capturegraph/logging/log.py
def children(self, parent: Entry) -> list[Entry]:
    """The entries directly beneath ``parent`` (``root`` for the top level), oldest first."""
    with self._lock:
        return list(self._branches[parent.id].children)

entries() #

Every entry, parents before children.

Source code in capturegraph-lib/capturegraph/logging/log.py
def entries(self) -> list[Entry]:
    """Every entry, parents before children."""
    with self._lock:
        return list(self._entries)

json() #

Every entry's wire shape, parents before children.

Source code in capturegraph-lib/capturegraph/logging/log.py
def json(self) -> list[dict[str, JSONValue]]:
    """Every entry's wire shape, parents before children."""
    return [entry.json() for entry in self.entries()]