zppy 0.1.0__py3-none-any.whl

zppy/__init__.py

@@ -0,0 +1,5 @@
+"""Zig progress protocol client for Python."""
+
+from .progress import Node, Progress
+
+__all__ = ["Node", "Progress"]

zppy/progress.py

@@ -0,0 +1,587 @@
+"""Report task trees through a Zig progress pipe."""
+
+from __future__ import annotations
+
+import os
+import stat
+import struct
+import subprocess
+import threading
+import weakref
+from contextlib import ExitStack
+from dataclasses import dataclass, field
+from types import TracebackType
+
+if os.name == "posix":
+    import fcntl
+
+_MAX_NODES = 253
+_MAX_COMPLETED = 0xFFFFFFFF
+# Zig uses this value plus one to mark an internal IPC node.
+_MAX_TOTAL = 0xFFFFFFFE
+
+# Keep construction and explicit forks from racing over reporter descriptors.
+_fork_lock = threading.Lock()
+_reporters: weakref.WeakSet[Progress] = weakref.WeakSet()
+# In a fork child this owns the source descriptor exposed through ZIG_PROGRESS.
+_fork_channel: int | None = None
+
+
+def _interval(value: float, name: str, *, allow_zero: bool = False) -> float:
+    if not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a number")
+    if not 0 <= value <= threading.TIMEOUT_MAX or (value == 0 and not allow_zero):
+        lower = "nonnegative" if allow_zero else "positive"
+        raise ValueError(
+            f"{name} must be {lower} and at most {threading.TIMEOUT_MAX} seconds"
+        )
+    return float(value)
+
+
+def _count(value: int) -> int:
+    if not isinstance(value, int):
+        raise TypeError("item counts must be integers")
+    if value < 0:
+        raise ValueError("item counts must be nonnegative")
+    return value
+
+
+def _name(value: str | bytes, size: int) -> bytes:
+    if isinstance(value, str):
+        # Do not split a UTF-8 character at the wire limit.
+        return (
+            value.split("\0", 1)[0]
+            .encode("utf-8")[:size]
+            .decode("utf-8", errors="ignore")
+            .encode("utf-8")
+        )
+    if isinstance(value, bytes):
+        return value.split(b"\0", 1)[0][:size]
+    raise TypeError("name must be str or bytes")
+
+
+def _environment_fd() -> int | None:
+    value = os.environ.get("ZIG_PROGRESS", "")
+    if not value or not value.isascii() or not value.isdecimal():
+        return None
+    # Avoid Python's limit on the number of digits in an integer string.
+    value = value.lstrip("0") or "0"
+    if len(value) > 5:
+        return None
+    fd = int(value)
+    return fd if fd <= 65535 else None
+
+
+@dataclass
+class _State:
+    parent: Node | None
+    name: bytes
+    total: int
+    completed: int = 0
+
+
+@dataclass
+class _Child:
+    fd: int | None
+    pending: bytearray = field(default_factory=bytearray)
+    # Records are in parent-before-child order, with remapped parent indices.
+    snapshot: list[tuple[int, int, bytes, int]] = field(default_factory=list)
+
+    def close(self) -> None:
+        if self.fd is not None:
+            os.close(self.fd)
+            self.fd = None
+        self.pending.clear()
+
+    def read(self, record: struct.Struct) -> None:
+        # Bound work per update even if a child writes without pause. Keep at
+        # most one incomplete packet, and retain the last complete valid tree.
+        budget = 65536
+        while self.fd is not None and budget:
+            try:
+                chunk = os.read(self.fd, min(4096, budget))
+            except (BlockingIOError, InterruptedError):
+                return
+            except OSError:
+                self.close()
+                return
+            if not chunk:
+                self.close()
+                return
+            budget -= len(chunk)
+            self.pending.extend(chunk)
+            while self.pending:
+                count = self.pending[0]
+                if not 1 <= count <= _MAX_NODES:
+                    self.close()
+                    return
+                size = 1 + count * (record.size + 1)
+                if len(self.pending) < size:
+                    break
+                packet = self.pending[:size]
+                del self.pending[:size]
+                snapshot = self._decode(packet, count, record)
+                if snapshot is None:
+                    self.close()
+                    return
+                self.snapshot = snapshot
+
+    @staticmethod
+    def _decode(
+        packet: bytes, count: int, record: struct.Struct
+    ) -> list[tuple[int, int, bytes, int]] | None:
+        parents = packet[1 + count * record.size :]
+        if parents[0] != 255:
+            return None
+        children: list[list[int]] = [[] for _ in range(count)]
+        for index in range(1, count):
+            parent = parents[index]
+            if parent >= count:
+                return None
+            children[parent].append(index)
+        # A tree may use forward parent references. Traversal both orders the
+        # records and detects cycles or branches not connected to the root.
+        order = [0]
+        for index in order:
+            order.extend(children[index])
+        if len(order) != count:
+            return None
+        indices = {old: new for new, old in enumerate(order)}
+        result = []
+        for index in order:
+            completed, total, name = record.unpack_from(packet, 1 + index * record.size)
+            if total > _MAX_TOTAL:
+                return None
+            parent = 255 if index == 0 else indices[parents[index]]
+            result.append((completed, total, name.split(b"\0", 1)[0], parent))
+        return result
+
+
+class Node:
+    """A task in a Progress tree. Use start() to create a child task.
+
+    Operations are thread-safe. end() removes the task and its descendants,
+    then completes one item in its parent. Repeated end() calls and task updates
+    on ended or disabled nodes have no effect. spawn() and fork() still start
+    a process.
+    """
+
+    def __init__(self, progress: Progress | None = None) -> None:
+        self._progress = progress
+
+    def start(self, name: str | bytes, estimated_total_items: int = 0) -> Node:
+        """Start a child task. Zero means the total is unknown."""
+        progress = self._progress
+        name_bytes = _name(name, progress.name_size if progress else 120)
+        total = min(_count(estimated_total_items), _MAX_TOTAL)
+        if progress is not None:
+            with progress._lock:
+                if self in progress._nodes and len(progress._nodes) < _MAX_NODES:
+                    node = Node(progress)
+                    progress._nodes[node] = _State(self, name_bytes, total)
+                    return node
+        return Node()
+
+    def spawn(self, args, **kwargs) -> subprocess.Popen:
+        """Start a process whose progress tree replaces this task in reports.
+
+        Arguments follow subprocess.Popen. A private nonblocking pipe is added
+        to pass_fds and ZIG_PROGRESS is set in a copy of the child environment.
+        close_fds must be True. Use one process per node. Wait for the process,
+        then end this node; neither operation is automatic. Disabled or ended
+        nodes still start the process, without a progress channel.
+        """
+        if not kwargs.get("close_fds", True):
+            raise ValueError("spawn requires close_fds=True")
+        source_env = kwargs.pop("env", None)
+        env = dict(os.environ if source_env is None else source_env)
+        env.pop("ZIG_PROGRESS", None)
+        env.pop(b"ZIG_PROGRESS", None)
+        kwargs["env"] = env
+        progress = self._progress
+        if progress is not None:
+            with progress._lock:
+                if self in progress._nodes and os.name == "posix":
+                    if self in progress._children:
+                        raise ValueError("a process is already attached to this node")
+                    read_fd, write_fd = os.pipe()
+                    child = _Child(read_fd)
+                    try:
+                        os.set_blocking(read_fd, False)
+                        os.set_blocking(write_fd, False)
+                        if write_fd > 65535:
+                            raise ValueError("child progress fd exceeds 65535")
+                        env["ZIG_PROGRESS"] = str(write_fd)
+                        kwargs["pass_fds"] = (
+                            *kwargs.get("pass_fds", ()),
+                            write_fd,
+                        )
+                        process = subprocess.Popen(args, **kwargs)
+                    except BaseException:
+                        child.close()
+                        raise
+                    finally:
+                        os.close(write_fd)
+                    progress._children[self] = child
+                    return process
+        return subprocess.Popen(args, **kwargs)
+
+    def fork(self) -> int:
+        """Fork with a private progress channel attached to this node.
+
+        Return the child's PID in the parent and zero in the child, like
+        os.fork(). In the child, inherited reporters are disabled; create a
+        fresh Progress with the same name_size to use the new ZIG_PROGRESS
+        channel. The parent must waitpid() and end this node. Disabled or ended
+        nodes still fork, but supply no channel. Requires os.fork().
+        """
+        global _fork_channel
+        if not hasattr(os, "fork"):
+            raise NotImplementedError("fork requires os.fork()")
+        # Freeze every reporter, including unrelated ones: the child must not
+        # inherit an in-flight write, descriptor change, or locked reporter.
+        # ExitStack retains the original locks so resetting child objects does
+        # not change which locks are released when this method returns.
+        with _fork_lock, ExitStack() as stack:
+            reporters = list(_reporters)
+            for reporter in reporters:
+                stack.enter_context(reporter._lock)
+            progress = self._progress
+            child = None
+            write_fd = None
+            if progress is not None and self in progress._nodes:
+                if self in progress._children:
+                    raise ValueError("a process is already attached to this node")
+                read_fd, write_fd = os.pipe()
+                child = _Child(read_fd)
+            try:
+                if child is not None:
+                    os.set_blocking(child.fd, False)
+                    os.set_blocking(write_fd, False)
+                    if write_fd > 65535:
+                        raise ValueError("child progress fd exceeds 65535")
+                    progress._children[self] = child
+                pid = os.fork()
+            except BaseException:
+                if child is not None:
+                    progress._children.pop(self, None)
+                    child.close()
+                    os.close(write_fd)
+                raise
+            if pid:
+                if write_fd is not None:
+                    os.close(write_fd)
+                return pid
+
+            # Only the calling thread survives. Do not join old threads or
+            # touch their Events, which can contain locks held at fork time.
+            for reporter in reporters:
+                reporter._lock = threading.Lock()
+                reporter._stop = threading.Event()
+                reporter._thread = None
+                reporter._closed = True
+                reporter._disconnect()
+            if _fork_channel is not None:
+                os.close(_fork_channel)
+            _fork_channel = write_fd
+            if write_fd is None:
+                os.environ.pop("ZIG_PROGRESS", None)
+            else:
+                os.environ["ZIG_PROGRESS"] = str(write_fd)
+            return 0
+
+    def complete_one(self) -> None:
+        """Complete one item, up to the protocol's counter limit."""
+        progress = self._progress
+        if progress is not None:
+            with progress._lock:
+                if state := progress._nodes.get(self):
+                    state.completed = min(state.completed + 1, _MAX_COMPLETED)
+
+    def set_completed_items(self, count: int) -> None:
+        """Set an absolute completed count. Large counts saturate at u32 max."""
+        count = min(_count(count), _MAX_COMPLETED)
+        progress = self._progress
+        if progress is not None:
+            with progress._lock:
+                if state := progress._nodes.get(self):
+                    state.completed = count
+
+    def set_estimated_total_items(self, count: int) -> None:
+        """Set the total; zero means unknown. Large totals saturate at 2**32-2."""
+        count = min(_count(count), _MAX_TOTAL)
+        progress = self._progress
+        if progress is not None:
+            with progress._lock:
+                if state := progress._nodes.get(self):
+                    state.total = count
+
+    def increase_estimated_total_items(self, count: int) -> None:
+        """Add to the estimated total, up to 2**32-2."""
+        count = _count(count)
+        progress = self._progress
+        if progress is not None:
+            with progress._lock:
+                if state := progress._nodes.get(self):
+                    state.total = min(state.total + count, _MAX_TOTAL)
+
+    def set_name(self, name: str | bytes) -> None:
+        """Set the task label, limited to the reporter's name_size in bytes."""
+        progress = self._progress
+        name_bytes = _name(name, progress.name_size if progress else 120)
+        if progress is not None:
+            with progress._lock:
+                if state := progress._nodes.get(self):
+                    state.name = name_bytes
+
+    def end(self) -> None:
+        """End this task. Ending the root closes its reporter."""
+        progress = self._progress
+        if progress is None:
+            return
+        if self is progress.root:
+            progress.close()
+            return
+        with progress._lock:
+            state = progress._nodes.get(self)
+            if state is None:
+                return
+            # Parents precede children in insertion order. Remove the whole
+            # branch so no packet can contain an edge to a missing parent.
+            removed = {self}
+            for node, child in list(progress._nodes.items()):
+                if node in removed or child.parent in removed:
+                    removed.add(node)
+                    del progress._nodes[node]
+                    if child_process := progress._children.pop(node, None):
+                        child_process.close()
+            if parent := progress._nodes.get(state.parent):
+                parent.completed = min(parent.completed + 1, _MAX_COMPLETED)
+
+    def __enter__(self) -> Node:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.end()
+
+
+class Progress:
+    """A reporter for the process-wide ZIG_PROGRESS channel.
+
+    Construction starts a daemon thread unless refresh_rate is None. Times
+    are in seconds. Missing, malformed, or unusable channels disable reporting.
+    No terminal output is produced. Use one reporter per pipe and close it
+    with a context manager or close(). The caller retains ownership of fd.
+    """
+
+    def __init__(
+        self,
+        root_name: str | bytes = "",
+        estimated_total_items: int = 0,
+        *,
+        refresh_rate: float | None = 0.08,
+        initial_delay: float = 0.2,
+        fd: int | None = None,
+        disable: bool = False,
+        name_size: int = 120,
+    ) -> None:
+        if not isinstance(name_size, int) or name_size not in (40, 120):
+            raise ValueError("name_size must be 40 (published) or 120 (Zig 0.17)")
+        self._record = struct.Struct(f"<II{name_size}s")
+        self._name_size = name_size
+        name = _name(root_name, name_size)
+        total = min(_count(estimated_total_items), _MAX_TOTAL)
+        if refresh_rate is not None:
+            refresh_rate = _interval(refresh_rate, "refresh_rate")
+        initial_delay = _interval(initial_delay, "initial_delay", allow_zero=True)
+        if fd is not None and (not isinstance(fd, int) or not 0 <= fd <= 65535):
+            raise ValueError("fd must be an integer from 0 to 65535")
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._fd: int | None = None
+        self._pending = b""
+        self._pending_snapshot = b""
+        self._last_snapshot = b""
+        self._closed = False
+        self._nodes: dict[Node, _State] = {}
+        self._children: dict[Node, _Child] = {}
+        self.root = Node(self)
+        with _fork_lock:
+            if not disable and os.name == "posix":
+                source = _environment_fd() if fd is None else fd
+                if source is not None:
+                    try:
+                        self._fd = os.dup(source)
+                        # Check the duplicate before changing shared flags or
+                        # writing. A stale environment entry can name a file.
+                        if (
+                            not stat.S_ISFIFO(os.fstat(self._fd).st_mode)
+                            or fcntl.fcntl(self._fd, fcntl.F_GETFL) & os.O_ACCMODE
+                            == os.O_RDONLY
+                        ):
+                            self._disconnect()
+                        else:
+                            # Duplicates share this flag with the caller's fd.
+                            os.set_blocking(self._fd, False)
+                    except OSError:
+                        self._disconnect()
+            if self._fd is not None:
+                self._nodes[self.root] = _State(None, name, total)
+                if refresh_rate is not None:
+                    self._thread = threading.Thread(
+                        target=self._run,
+                        args=(initial_delay, refresh_rate),
+                        name="zppy-progress",
+                        daemon=True,
+                    )
+                    try:
+                        self._thread.start()
+                    except RuntimeError:
+                        self._thread = None
+                        self._disconnect()
+            _reporters.add(self)
+
+    @property
+    def name_size(self) -> int:
+        """Name field size: 120 by default, or 40 for the published protocol."""
+        return self._name_size
+
+    @property
+    def enabled(self) -> bool:
+        """Whether the reporter has an open progress channel."""
+        with self._lock:
+            return self._fd is not None
+
+    def _snapshot(self) -> bytes:
+        indices = {node: index for index, node in enumerate(self._nodes)}
+        records = bytearray()
+        parents = bytearray()
+        for state in self._nodes.values():
+            records.extend(self._record.pack(state.completed, state.total, state.name))
+            parents.append(255 if state.parent is None else indices[state.parent])
+        for node, child in self._children.items():
+            child.read(self._record)
+            if not child.snapshot:
+                continue
+            root_index = indices[node]
+            completed, total, name, _ = child.snapshot[0]
+            # Zig retains the task label if the child root has no name.
+            name = name or self._nodes[node].name
+            self._record.pack_into(
+                records, root_index * self._record.size, completed, total, name
+            )
+            mapped = {0: root_index}
+            for index, (completed, total, name, parent) in enumerate(
+                child.snapshot[1:], 1
+            ):
+                if len(parents) == _MAX_NODES:
+                    break
+                mapped[index] = len(parents)
+                records.extend(self._record.pack(completed, total, name))
+                parents.append(mapped[parent])
+        return bytes([len(parents)]) + records + parents
+
+    def _disconnect(self) -> None:
+        if self._fd is not None:
+            try:
+                os.close(self._fd)
+            except OSError:
+                pass
+            self._fd = None
+        self._pending = b""
+        self._pending_snapshot = b""
+        self._last_snapshot = b""
+        for child in self._children.values():
+            child.close()
+        self._children.clear()
+        self._nodes.clear()
+        self._stop.set()
+
+    def _write(self, packet: bytes) -> bool:
+        try:
+            written = os.write(self._fd, packet)
+        except (BlockingIOError, InterruptedError):
+            # Keep an existing partial packet, but discard a new snapshot if
+            # none of its bytes reached the pipe. The next one supersedes it.
+            return False
+        except OSError:
+            self._disconnect()
+            return False
+        if written == 0:
+            self._disconnect()
+            return False
+        if not self._pending:
+            self._pending_snapshot = packet
+        self._pending = packet[written:]
+        if not self._pending:
+            self._last_snapshot = self._pending_snapshot
+            self._pending_snapshot = b""
+        return not self._pending
+
+    def flush(self) -> bool:
+        """Try to send the current tree without waiting for pipe space.
+
+        Return True if the current snapshot was sent in full. Partial writes
+        resume before any newer snapshot. A full pipe delays or drops updates;
+        a permanent I/O error disables reporting without raising an exception.
+        """
+        with self._lock:
+            if self._fd is None or self._closed:
+                return False
+            snapshot = self._snapshot()
+            if self._pending:
+                pending_snapshot = self._pending_snapshot
+                if not self._write(self._pending):
+                    return False
+                if pending_snapshot == snapshot:
+                    return True
+            return self._write(snapshot)
+
+    def _run(self, initial_delay: float, refresh_rate: float) -> None:
+        if self._stop.wait(initial_delay):
+            return
+        while not self._stop.is_set():
+            self.flush()
+            if self._stop.wait(refresh_rate):
+                return
+
+    def close(self) -> None:
+        """Stop reports and try to send the final state. Safe to call again.
+
+        This does not wait for a receiver to drain a full pipe. Final delivery
+        is best effort; a pending large packet can remain incomplete if the
+        pipe is still full. The original descriptor is never closed.
+        """
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join()
+        with self._lock:
+            if self._closed:
+                return
+            if self._fd is not None:
+                snapshot = self._snapshot()
+                pending_snapshot = self._pending_snapshot
+                if not self._pending:
+                    if snapshot != self._last_snapshot:
+                        self._write(snapshot)
+                elif self._write(self._pending) and pending_snapshot != snapshot:
+                    self._write(snapshot)
+            self._closed = True
+            self._disconnect()
+
+    def __enter__(self) -> Progress:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()

zppy-0.1.0.dist-info/METADATA

@@ -0,0 +1,359 @@
+Metadata-Version: 2.4
+Name: zppy
+Version: 0.1.0
+Summary: Zig progress protocol client for Python
+License-Expression: CC0-1.0
+Project-URL: Repository, https://github.com/asciimoth/zppy
+Project-URL: Issues, https://github.com/asciimoth/zppy/issues
+Project-URL: Documentation, https://github.com/asciimoth/zppy#readme
+Keywords: zig,progress,zig-progress-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# zppy
+
+`zppy` is a Python library that reports task progress through the Zig progress
+protocol. Use it to report tasks, subtasks, and progress from child processes.
+
+`zppy` requires Python 3.11 or later. The library has no runtime dependencies.
+The pipe transport supports POSIX systems, including Linux and macOS.
+
+## Installation
+
+```sh
+python -m pip install zppy
+```
+
+The package uses the [CC0 1.0 Universal license](LICENSE).
+
+## Zig progress protocol
+
+The Zig progress protocol lets a process send a tree of tasks to its parent
+through a pipe. Each task has a name, a completed item count, and an estimated
+total. The `ZIG_PROGRESS` environment variable identifies the pipe. The parent
+can combine progress from child processes and display it in one place.
+
+You can use the protocol outside the Zig toolchain. For example,
+[`zpg`](https://github.com/asciimoth/zpg) runs commands and displays their
+progress in a terminal. With `zppy`, Python programs can send progress to
+`zpg` or another compatible receiver.
+
+See Andrew Kelley's [Zig progress protocol specification][protocol] for the
+protocol design.
+
+![zpg displaying a task tree](https://raw.githubusercontent.com/asciimoth/zpg/master/demo.gif)
+
+## Library usage
+
+If you use this library, [open an issue][issues] or [send a pull
+request][pulls] with a link to your project. This helps us track use of the
+Zig progress protocol outside the Zig toolchain.
+
+Add the [`zig-progress-protocol` topic][topic] to your GitHub repository. Use
+the same tag on other platforms so people can find related projects.
+
+[issues]: https://github.com/asciimoth/zppy/issues
+[pulls]: https://github.com/asciimoth/zppy/pulls
+[topic]: https://github.com/topics/zig-progress-protocol
+
+### Report tasks
+
+Save this example as `build.py`:
+
+```python
+import time
+
+from zppy import Progress
+
+with Progress("build", estimated_total_items=2) as progress:
+    for name in ("assets", "code"):
+        with progress.root.start(name, estimated_total_items=10) as task:
+            for _ in range(10):
+                time.sleep(0.1)  # Replace this with one item of work.
+                task.complete_one()
+```
+
+Run `build.py` with a progress display:
+
+```sh
+zpg python build.py
+```
+
+Each child task can start more child tasks. When a child task ends, it leaves
+the tree and adds one completed item to its parent task. Do not also call
+`parent.complete_one()` for the same child task.
+
+A context manager ends its task on normal exit and on exceptions. The context
+manager does not suppress exceptions or report task success or failure.
+
+Without a valid `ZIG_PROGRESS` channel, reporting is disabled. Task operations
+have no effect. The library does not print to stdout or stderr. It does not
+draw its own terminal display.
+
+### Run the combined example
+
+From the repository root, run:
+
+```sh
+PYTHONPATH=src zpg python -u examples/mock.py
+```
+
+This example requires `zpg` on `PATH` and a system with `os.fork()`. It runs
+`zpg --mock` as a subprocess and a Python worker as a forked process at the
+same time. Both task trees appear under `demo`. Python task labels start with
+`PY`. Both workers also write messages to stdout and stderr.
+
+### Child processes
+
+Use `Node.spawn()` to start a process with its own progress pipe.
+`Node.spawn()` accepts the arguments to `subprocess.Popen` and returns a
+`Popen` object:
+
+```python
+import sys
+
+from zppy import Progress
+
+with Progress("build", estimated_total_items=1) as progress:
+    with progress.root.start("compile") as task:
+        with task.spawn([sys.executable, "worker.py"]) as process:
+            returncode = process.wait()
+```
+
+In `worker.py`, use `Progress`. The parent process combines the child's task
+tree with its own tasks and sends the combined tree upstream. A child process
+can use `Node.spawn()` to start more processes. Use a separate task node for
+each process. Processes on different nodes can run at the same time.
+
+`Node.spawn()` follows [Zig's child progress behavior][zig-child]. The child's
+root replaces the task node in each report. The child root's descendants
+appear below that node. If the child root has no name, the task keeps its
+local name. Until the first complete report arrives, the task keeps its local
+state. The last complete tree stays visible after the child closes its pipe or
+exits.
+
+Wait for the process, then end its task, as in the example above. Process exit
+does not end the task or mark success or failure. Ending the task completes
+one item in its parent.
+
+Ending a task or closing the reporter closes its child progress pipes. Neither
+operation waits for or terminates processes. Use one process per active node.
+A second `spawn()` or `fork()` on the same node raises `ValueError`.
+
+The update thread collects child reports. With `refresh_rate=None`, call
+`flush()` regularly while children run.
+
+`spawn()` copies the child environment and sets `ZIG_PROGRESS` to the new
+pipe. It preserves other environment entries and adds the pipe to `pass_fds`.
+`close_fds` must be true. `spawn()` does not change the parent environment.
+Disabled, ended, or closed nodes still start processes, but remove
+`ZIG_PROGRESS` from the child environment. Do not pass the upstream progress
+descriptor to children.
+
+All processes in the tree must use the same `name_size`. There is no format
+negotiation.
+
+[zig-child]: https://github.com/ziglang/zig/blob/0.15.2/lib/std/process/Child.zig#L96-L104
+
+### Forked processes
+
+On systems with `os.fork()`, use `Node.fork()` to attach a forked process to a
+task. It returns the child's PID in the parent and `0` in the child:
+
+```python
+import os
+
+from zppy import Progress
+
+with Progress("parent", estimated_total_items=1) as progress:
+    with progress.root.start("worker") as task:
+        pid = task.fork()
+        if pid == 0:
+            with Progress("worker", estimated_total_items=10) as child:
+                for _ in range(10):
+                    child.root.complete_one()
+            os._exit(0)
+        _, status = os.waitpid(pid, 0)
+```
+
+The child gets a private `ZIG_PROGRESS` pipe. Create a new `Progress` in the
+child, with the same `name_size` as its parent. All inherited reporters and
+their nodes are disabled in the child. Caller-owned descriptors remain the
+caller's responsibility. The parent's reporters and environment stay
+unchanged.
+
+The forked child's tree replaces its task node, as for `spawn()`. Forked
+children can use either `fork()` or `spawn()` to create more children. Wait
+for the child with `os.waitpid()`, then end its task in the parent. Close the
+child's reporter before `os._exit()`, which skips normal cleanup. Handle child
+errors and exit status as required by your application.
+
+Forks on disabled, ended, or closed nodes still run, but the child has no
+`ZIG_PROGRESS` channel. A failed fork leaves the parent reporter usable.
+
+Use `Node.fork()` to connect a forked process to a task. Direct `os.fork()`
+calls and `multiprocessing` do not create this connection. `Node.fork()`
+protects `zppy`'s own state. Application code and other libraries must also
+meet the platform's [fork
+requirements](https://docs.python.org/3/library/os.html#os.fork).
+
+### API reference
+
+`Progress(root_name="", estimated_total_items=0, *, refresh_rate=0.08,
+initial_delay=0.2, fd=None, disable=False, name_size=120)` creates a reporter.
+Use `progress.root` to access its root task.
+
+| Option | Meaning |
+| --- | --- |
+| `root_name` | Root label, as `str` or `bytes`. |
+| `estimated_total_items` | Estimated root item count. Zero means unknown. |
+| `refresh_rate` | Seconds between reports. Use `None` for manual reports. |
+| `initial_delay` | Seconds before the first automatic report. |
+| `fd` | Explicit pipe descriptor. `None` reads `ZIG_PROGRESS`. |
+| `disable` | Disable all reporting when true. |
+| `name_size` | Name field size: `120` by default, or `40` for the old format. |
+
+Timer values must be finite numbers no greater than `threading.TIMEOUT_MAX`.
+`refresh_rate` must be positive, and `initial_delay` must be nonnegative.
+
+`progress.enabled` shows whether the channel is open. `progress.flush()` tries
+to send a snapshot immediately. It returns `True` if the current snapshot was
+sent in full, or `False` if reporting is disabled or the write could not
+finish. It does not wait for pipe space.
+
+`progress.close()` stops the update thread, tries to send the final state, and
+releases its descriptor. Use a context manager or call `close()` directly.
+Closing the reporter does not set counts to their totals or remove the final
+tree from the receiver. Ending the root also closes the reporter.
+
+Nodes provide these methods:
+
+| Method | Action |
+| --- | --- |
+| `start(name, estimated_total_items=0)` | Create a child task. |
+| `spawn(args, **kwargs)` | Start a process and collect its progress. |
+| `fork()` | Fork and collect the child's progress at this node. |
+| `complete_one()` | Add one completed item. |
+| `set_completed_items(count)` | Set the absolute completed count. |
+| `set_estimated_total_items(count)` | Set the estimated total. |
+| `increase_estimated_total_items(count)` | Add to the estimated total. |
+| `set_name(name)` | Change the task label. |
+| `end()` | Remove this branch and complete one item in its parent. |
+
+Calls are thread-safe. Repeated `end()` calls have no effect. Task updates on
+ended nodes also have no effect. Calls to `spawn()` and `fork()` still start a
+process on ended nodes, as described in the child process sections. Invalid
+arguments raise `TypeError` or `ValueError`, including when reporting is
+disabled.
+
+Counts must be nonnegative integers. Completed counts are limited to
+`4294967295`. Totals are limited to `4294967294`, because Zig reserves the
+next value. The library reduces larger values to these limits. Completed
+counts can exceed totals.
+
+Names are zero-padded to the field size. Text is encoded as UTF-8 and
+shortened at a character boundary. Byte names are shortened without decoding.
+Bytes after the first NUL are ignored.
+
+The reporter tracks up to 253 active nodes, including the root. Additional
+nodes have no effect. Ending nodes makes space for new nodes. Combined reports
+also have a 253-node limit. Local nodes take priority, followed by child trees
+in process creation order. Child roots replace local nodes without using more
+slots. The reporter omits excess descendants and their branches. These
+descendants can appear in later reports when space is available.
+
+## Technical details
+
+### Protocol compatibility
+
+The default uses a 120-byte name field. Each node has two little-endian 32-bit
+counters and 120 name bytes. A packet contains the node count, all node
+records, then all parent indices. The root's parent is `255`.
+
+The [published specification][protocol] uses 40-byte names. Select that format
+explicitly with `Progress(name_size=40)`. The two formats are not wire
+compatible. Both use `ZIG_PROGRESS`, and there is no version handshake. Select
+the format that matches your receiver.
+
+[protocol]: https://andrewkelley.me/post/zig-new-cli-progress-bar-explained.html#the-zig-progress-protocol-specification
+
+Use one reporter per pipe. Each packet replaces the previous tree. A packet
+does not add tasks to the previous tree. Multiple writers can replace each
+other's progress or interleave packet bytes. Use `Node.spawn()` or
+`Node.fork()` to combine progress from separate processes through private
+pipes. Create a new reporter in each child, and use the same `name_size`
+throughout the process tree.
+
+### Platforms and pipe handling
+
+The reporter accepts only writable POSIX pipes, such as those on Linux and
+macOS. Other descriptors, including regular files and read-only pipes, disable
+reporting without changing their data or blocking mode. Reporting is disabled
+on other platforms.
+
+The reporter duplicates the supplied descriptor and never closes the original.
+The duplicate is not inherited across exec. The reporter sets the channel to
+nonblocking mode. This flag also applies to the original descriptor. When you
+create a reporter, it does not change `ZIG_PROGRESS` in the environment.
+`Node.fork()` sets `ZIG_PROGRESS` in the forked child only.
+
+A full pipe can delay or drop updates. The reporter resumes partial packets
+before it sends a new snapshot. A permanent write error disables reporting.
+
+Closing the reporter never waits for pipe space. The final report can be lost.
+If the receiver stops reading, a large partial packet can remain incomplete.
+If final delivery is required, retry `flush()` while the receiver is active
+before you close the reporter.
+
+## Release notes
+
+### 0.1.0
+
+Initial release:
+
+- Report tasks and nested tasks through the Zig progress protocol.
+- Combine progress from subprocesses and forked Python workers.
+- Support both 120-byte and 40-byte task names.
+- Send updates through POSIX pipes without runtime dependencies.
+
+## Manual releases
+
+Use the Nix development shell on this machine:
+
+```sh
+nix develop
+```
+
+The shell includes the build tools and Twine. Before each release:
+
+1. Set the version in `pyproject.toml`. The Nix package reads this version too.
+2. Update the release notes above.
+3. Run `just check`, then `just build` and `just check-dist`.
+4. Install the wheel in a fresh virtual environment outside the source tree
+   and check that it works.
+5. Commit the release changes and create an annotated tag, for example
+   `git tag -a v0.1.0 -m "Release 0.1.0"`.
+6. Run `just publish` to upload the checked source archive and wheel to PyPI.
+7. Push the release commit and tag to the repository.
+
+`just publish` checks the files again but does not rebuild them. It selects
+only the two files for the version in `pyproject.toml`, so older releases in
+`dist/` are not uploaded. If you change the source, rebuild and check it before
+you publish.
+
+For the first upload, create a PyPI account, verify its email address, enable
+two-factor authentication, and create an API token with account-wide scope.
+Enter the token at Twine's password prompt. After the first upload, replace
+that token with a token scoped to `zppy`. Do not commit tokens to the
+repository. See the [PyPI publishing guide][pypi-publishing] for account and
+authentication details.
+
+[pypi-publishing]: https://docs.pypi.org/publishing/publishing-to-pypi/

zppy-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+zppy/__init__.py,sha256=ZEUdkeMKBTfcBig5hyigCRLPGlEbooO0srGdn-FxGTI,117
+zppy/progress.py,sha256=53Gf31eRvxUYGMGT-tLU-ZJmT31sqzDgZgEfE1z8mBc,23138
+zppy-0.1.0.dist-info/licenses/LICENSE,sha256=ogEPNDSH0_dhiv_lT3ifVIdgIzHAqNA_SemnxUfPBJk,7048
+zppy-0.1.0.dist-info/METADATA,sha256=LQJxeC0IxfKze6qtd4InRYlyJ2CqIt68zlPmC1_zpX8,15011
+zppy-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+zppy-0.1.0.dist-info/top_level.txt,sha256=C91XdzScKNBjWOHxpZIBOSd-t8EWJlwjEjKWIQmn-2E,5
+zppy-0.1.0.dist-info/RECORD,,

zppy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zppy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

zppy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zppy