Logging Guide
=============

The ``piethorn.logging`` package is intentionally small: it provides a logger and
two families of counters for tracking work.

Logger
------

``Logger`` prints tagged messages and tracks how many messages of each type were
emitted.

Important methods:

``base_log()``
   Low-level output helper that prints raw messages when the configured debug
   level allows it.

``log()``, ``error()``, ``warn()``, ``info()``
   Higher-level logging entry points that prefix output with a title such as
   ``[INFO]``.

``log_sep()``
   Prints a separator line, optionally centered around a title.

``count()`` and ``percent()``
   Factory helpers that create counters bound to the logger.

Counters
--------

``Counter``
   Tracks visible, hidden, and fractional progress. It supports absolute adds,
   fractional adds, tick-based progression, and formatted status messages.

``Percent``
   Extends counter behavior with a cap and percent-based progress reporting.

``CounterBehavior``
   Controls how reset behavior propagates through parent/child counter trees.

Design Notes
------------

The counter objects are not just numeric containers. They can also:

* emit messages through the logger they are bound to
* create child counters that influence parent progress
* distinguish visible from hidden work
* support configurable reset propagation

This makes the package more suitable for simple CLI progress reporting than for
general-purpose structured logging.