python-corekit 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

corekit/docker/__init__.py

@@ -1,7 +1,9 @@
 """
-Docker container control.
+Docker container control and disk inspection.
 """
 
+from corekit.docker.client import DockerClientProvider
+from corekit.docker.disk import ContainerLog, DfCategory, DockerDiskInspector, ImageSize
 from corekit.docker.watchdog import Watchdog
 
-__all__ = ["Watchdog"]
+__all__ = ["ContainerLog", "DfCategory", "DockerClientProvider", "DockerDiskInspector", "ImageSize", "Watchdog"]

corekit/docker/client.py

@@ -0,0 +1,48 @@
+"""
+Getting a Docker SDK client without assuming where the daemon lives.
+
+``DockerClientProvider`` is the one place that resolves the endpoint:
+an explicit host wins, then ``$DOCKER_HOST``, then the first socket that
+actually exists among the usual locations (including snap's), and only
+then the classic default. ``Watchdog`` and ``DockerDiskInspector`` both
+build their clients through here, so a daemon that moves (classic install
+to snap, say) is found by both.
+"""
+
+from __future__ import annotations
+
+import os
+
+from docker import DockerClient
+
+from corekit.docker.constants import DEFAULT_DOCKER_HOST, DOCKER_SOCKET_CANDIDATES
+
+__all__ = ["DockerClientProvider"]
+
+
+class DockerClientProvider:
+    """
+    Resolves Docker endpoints and builds SDK clients for them.
+    """
+
+    @staticmethod
+    def resolve_host(docker_host: str | None = None) -> str:
+        """
+        Resolve the endpoint to use, without connecting to it.
+        """
+        if docker_host:
+            return docker_host
+        from_env = os.environ.get("DOCKER_HOST")
+        if from_env:
+            return from_env
+        for candidate in DOCKER_SOCKET_CANDIDATES:
+            if candidate.exists():
+                return f"unix://{candidate}"
+        return DEFAULT_DOCKER_HOST
+
+    @staticmethod
+    def create_client(docker_host: str | None = None) -> DockerClient:
+        """
+        Build an SDK client for the resolved endpoint.
+        """
+        return DockerClient(base_url=DockerClientProvider.resolve_host(docker_host))

corekit/docker/constants.py

@@ -0,0 +1,19 @@
+"""
+Shared Docker daemon constants.
+"""
+
+from pathlib import Path
+
+DEFAULT_DOCKER_HOST = "unix:///var/run/docker.sock"
+
+# Candidate sockets in preference order. Snap Docker does not use
+# /var/run/docker.sock, which is the single most common reason an SDK
+# client "cannot connect" on an Ubuntu host.
+DOCKER_SOCKET_CANDIDATES: tuple[Path, ...] = (
+    Path("/var/run/docker.sock"),
+    Path("/run/docker.sock"),
+    Path("/var/snap/docker/current/run/docker.sock"),
+)
+
+WATCHDOG_LABEL = "watchdog"
+WATCHDOG_MANAGED = "true"

corekit/docker/disk/__init__.py

@@ -0,0 +1,8 @@
+"""
+Docker disk inspection: what is using the space under the Docker root.
+"""
+
+from corekit.docker.disk.inspector import DockerDiskInspector
+from corekit.docker.disk.models import ContainerLog, DfCategory, ImageSize
+
+__all__ = ["ContainerLog", "DfCategory", "DockerDiskInspector", "ImageSize"]

corekit/docker/disk/constants.py

@@ -0,0 +1,14 @@
+"""
+Constants for Docker disk inspection.
+"""
+
+# (display name, key in the daemon's df report, dot-path to the entry's size)
+# Volumes nest their size under UsageData; everything else is a top-level field.
+DF_CATEGORIES: tuple[tuple[str, str, str], ...] = (
+    ("Images", "Images", "Size"),
+    ("Containers", "Containers", "SizeRw"),
+    ("Volumes", "Volumes", "UsageData.Size"),
+    ("Build Cache", "BuildCache", "Size"),
+)
+
+UNREFERENCED_IMAGE = "<none>:<none>"

corekit/docker/disk/inspector.py

@@ -0,0 +1,217 @@
+"""
+Where Docker's disk went.
+
+``DockerDiskInspector`` is the read-side counterpart to ``Watchdog``:
+Watchdog changes container state, the inspector measures it -- Docker root
+usage, per-container log sizes, largest volumes and images, and a
+``docker system df``-style summary. It can also truncate container logs,
+which is a measurement remedy rather than lifecycle control, and safe:
+truncating in place reclaims space immediately, deleting would not.
+
+Daemon data comes from the Docker SDK (built by ``DockerClientProvider``,
+so snap and classic installs are both found); on-disk sizes come from
+``corekit.files.DiskScanner``, because the daemon does not report log-file
+sizes and its volume accounting does not match ``du``. Filesystem access
+under the Docker root typically needs elevation, which the scanner handles.
+
+Daemon payloads are untrusted-shaped: every field is extracted through the
+``parse_*``/``safe_*`` utilities and ``getval`` rather than raw indexing.
+
+    inspector = DockerDiskInspector()
+    inspector.root_dir()          # snap-aware: the socket is discovered
+    inspector.container_logs()    # every log, biggest first
+    inspector.truncate_log("api") # after you have looked at it
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from docker import DockerClient
+from docker.errors import APIError, NotFound
+
+from corekit.docker.client import DockerClientProvider
+from corekit.docker.disk import constants as disk_constants
+from corekit.docker.disk.models import ContainerLog, DfCategory, ImageSize
+from corekit.files.disk import DiskScanner, PathSize
+from corekit.observability.benchmarkable import Benchmarkable
+from corekit.utils import first_string, getval, parse_dict, safe_dict, safe_int, safe_list, safe_string
+
+__all__ = ["DockerDiskInspector"]
+
+
+class DockerDiskInspector(Benchmarkable):
+    """
+    Measures Docker disk usage via the SDK plus filesystem scans.
+
+    Unlike Watchdog there is no label enforcement: measuring is read-only,
+    and the one mutating operation (log truncation) is addressed by exact
+    container name or ID, never by pattern.
+    """
+
+    def __init__(
+        self,
+        docker_host: str | None = None,
+        scanner: DiskScanner | None = None,
+    ) -> None:
+        """
+        :param docker_host: Docker endpoint; resolved by
+            ``DockerClientProvider`` (``$DOCKER_HOST``, existing sockets
+            including snap's, then the classic default) when omitted.
+        :param scanner: filesystem scanner for on-disk sizes; one with
+            elevation enabled by default.
+        """
+        super().__init__()
+        self.docker_host = DockerClientProvider.resolve_host(docker_host)
+        self._scanner = scanner or DiskScanner()
+        self._client_instance: DockerClient | None = None
+
+    @property
+    def _client(self) -> DockerClient:
+        """
+        The Docker client, connected on first use.
+        """
+        if self._client_instance is None:
+            self._client_instance = DockerClientProvider.create_client(self.docker_host)
+        return self._client_instance
+
+    # =============
+    # Daemon-level queries
+    # =============
+
+    def root_dir(self) -> Path:
+        """
+        The daemon's DockerRootDir (e.g. /var/snap/docker/common/var-lib-docker).
+        """
+        root = safe_string(getval(safe_dict(self._client.info()), "DockerRootDir"))
+        if not root:
+            raise RuntimeError("Daemon did not report a DockerRootDir (is docker running?)")
+        return Path(root)
+
+    def df_summary(self) -> list[DfCategory]:
+        """
+        Aggregate the daemon's df report into per-category counts and sizes.
+        """
+        report = parse_dict(self._client.df()).value
+        categories: list[DfCategory] = []
+        for display_name, report_key, size_path in disk_constants.DF_CATEGORIES:
+            entries = safe_list(getval(report, report_key, default=[]))
+            total = sum(safe_int(getval(entry, size_path, default=0)) for entry in entries)
+            categories.append(DfCategory(name=display_name, count=len(entries), size_bytes=total))
+        return categories
+
+    def images(self) -> list[ImageSize]:
+        """
+        Every image with its daemon-reported size, biggest first.
+        """
+        images = [
+            ImageSize(
+                reference=first_string(safe_list(image.tags), disk_constants.UNREFERENCED_IMAGE),
+                image_id=safe_string(image.short_id),
+                size_bytes=safe_int(getval(parse_dict(image.attrs).value, "Size")),
+            )
+            for image in self._client.images.list()
+        ]
+        return sorted(images, key=lambda img: img.size_bytes, reverse=True)
+
+    # =============
+    # Filesystem-backed queries
+    # =============
+
+    def root_children(self, root: Path | None = None) -> list[PathSize]:
+        """
+        Largest directories directly under the Docker root.
+        """
+        return self._scanner.child_sizes(root or self.root_dir())
+
+    def volumes(self, root: Path | None = None) -> list[PathSize]:
+        """
+        Largest Docker volumes (by on-disk size), biggest first.
+        """
+        return self._scanner.child_sizes((root or self.root_dir()) / "volumes")
+
+    def container_logs(self) -> list[ContainerLog]:
+        """
+        Every container's log with its size, biggest first.
+
+        Containers without a log path (non json-file drivers) or with an
+        unmeasurable log file are skipped.
+        """
+        logs: list[ContainerLog] = []
+        try:
+            containers = self._client.containers.list(all=True)
+        except APIError as exc:
+            self.error(f"Docker API error listing containers: {exc}")
+            return []
+        for container in containers:
+            log = self._measure_container_log(container)
+            if log is not None:
+                logs.append(log)
+        return sorted(logs, key=lambda x: x.size_bytes, reverse=True)
+
+    def logs_above(self, threshold_bytes: int) -> list[ContainerLog]:
+        """
+        Container logs strictly larger than the threshold, biggest first.
+        """
+        return [log for log in self.container_logs() if log.size_bytes > threshold_bytes]
+
+    def log_for(self, identifier: str) -> ContainerLog:
+        """
+        Resolve one container by name or ID and measure its log.
+
+        Raises LookupError if the container does not exist or has no log.
+        """
+        try:
+            container = self._client.containers.get(identifier)
+        except NotFound as exc:
+            raise LookupError(f"Container not found: {identifier}") from exc
+
+        log = self._measure_container_log(container)
+        if log is None:
+            raise LookupError(f"Container has no measurable log file (non json-file driver?): {identifier}")
+        return log
+
+    # =============
+    # Truncation
+    # =============
+
+    def truncate_log(self, identifier: str) -> ContainerLog:
+        """
+        Truncate one container's log; returns its pre-truncate measurement.
+        """
+        log = self.log_for(identifier)
+        self._scanner.truncate(log.log_path)
+        return log
+
+    def truncate_logs(self, logs: list[ContainerLog]) -> None:
+        """
+        Truncate each given container log.
+        """
+        for log in logs:
+            self._scanner.truncate(log.log_path)
+
+    # =============
+    # Private Methods
+    # =============
+
+    def _measure_container_log(self, container: object) -> ContainerLog | None:
+        """
+        Build a ContainerLog for one SDK container, or None when it has no
+        log path or the file cannot be measured.
+        """
+
+        log_path_text = safe_string(getval(container, "attrs.LogPath", default=""))
+        if not log_path_text:
+            return None
+
+        log_path = Path(log_path_text)
+        size = self._scanner.file_size(log_path)
+        if size is None:
+            return None
+
+        return ContainerLog(
+            container_id=safe_string(getval(container, "id")),
+            name=safe_string(getval(container, "name")).lstrip("/"),
+            log_path=log_path,
+            size_bytes=size,
+        )

corekit/docker/disk/models.py

@@ -0,0 +1,44 @@
+"""
+Data shapes returned by DockerDiskInspector.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = ["ContainerLog", "DfCategory", "ImageSize"]
+
+
+@dataclass(frozen=True)
+class ContainerLog:
+    """
+    One container's json-file log and its measured size.
+    """
+
+    container_id: str
+    name: str
+    log_path: Path
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class ImageSize:
+    """
+    One image and its size as reported by the daemon.
+    """
+
+    reference: str
+    image_id: str
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class DfCategory:
+    """
+    One row of a ``docker system df``-style summary.
+    """
+
+    name: str
+    count: int
+    size_bytes: int

corekit/docker/watchdog.py

@@ -18,13 +18,13 @@ from docker import DockerClient
 from docker.errors import APIError, NotFound
 from docker.models.containers import Container
 
+from corekit.docker.client import DockerClientProvider
+from corekit.docker.constants import DEFAULT_DOCKER_HOST, WATCHDOG_LABEL, WATCHDOG_MANAGED
 from corekit.observability.benchmarkable import Benchmarkable
 
-__all__ = ["Watchdog"]
-
-DEFAULT_DOCKER_HOST = "unix:///var/run/docker.sock"
-WATCHDOG_LABEL = "watchdog"
-WATCHDOG_MANAGED = "true"
+# DEFAULT_DOCKER_HOST / WATCHDOG_* are re-exported for backwards
+# compatibility; the canonical definitions live in corekit.docker.constants.
+__all__ = ["DEFAULT_DOCKER_HOST", "WATCHDOG_LABEL", "WATCHDOG_MANAGED", "Watchdog"]
 
 
 def _accept_all(*args: Any, **kwargs: Any) -> bool:
@@ -44,13 +44,15 @@ class Watchdog(Benchmarkable):
 
     def __init__(self, docker_host: str | None = None, enforce_label: bool = True) -> None:
         """
-        :param docker_host: Docker endpoint. Defaults to the local socket.
+        :param docker_host: Docker endpoint. Defaults to the endpoint
+            resolved by ``DockerClientProvider`` (``$DOCKER_HOST``, then an
+            existing socket -- snap included -- then the classic default).
         :param enforce_label: restrict actions to containers carrying the
             managed label. On by default; turn it off only when this watchdog
             is meant to control every container on the host.
         """
         super().__init__()
-        self.docker_host = docker_host or DEFAULT_DOCKER_HOST
+        self.docker_host = DockerClientProvider.resolve_host(docker_host)
         self.enforce_label = enforce_label
         self._client_instance: DockerClient | None = None
 
@@ -63,7 +65,7 @@ class Watchdog(Benchmarkable):
         and inspected on a machine where Docker is not running.
         """
         if self._client_instance is None:
-            self._client_instance = DockerClient(base_url=self.docker_host)
+            self._client_instance = DockerClientProvider.create_client(self.docker_host)
         return self._client_instance
 
     @staticmethod

corekit/exceptions/__init__.py

@@ -7,6 +7,7 @@ a user. ``CoreHTTPException`` is the FastAPI-facing public exception.
 """
 
 from corekit.exceptions.base import (
+    CommandFailedError,
     CoreException,
     CoreHTTPException,
     ExponentialBackoffTimeoutException,
@@ -20,6 +21,7 @@ from corekit.exceptions.types import ArbitraryCoreExceptionType, CoreExceptionTy
 
 __all__ = [
     "ArbitraryCoreExceptionType",
+    "CommandFailedError",
     "CoreException",
     "CoreExceptionType",
     "CoreHTTPException",

corekit/exceptions/base.py

@@ -27,6 +27,7 @@ from fastapi import HTTPException
 from corekit.exceptions.enum import Retryability
 
 __all__ = [
+    "CommandFailedError",
     "CoreException",
     "CoreHTTPException",
     "RetryableCoreHTTPException",
@@ -112,6 +113,24 @@ class ExponentialBackoffTimeoutException(InternalCoreException):
         self.attempts = attempts
 
 
+class CommandFailedError(InternalCoreException):
+    """
+    An external command exited non-zero, timed out, or could not be started.
+
+    ``command`` is the argv that was run; ``detail`` (also carried as the
+    shared ``error`` field) is stderr text or the OS-level reason.
+    """
+
+    def __init__(self, command: list[str], detail: str) -> None:
+        super().__init__(
+            message=f"Command failed: {' '.join(command)}",
+            retryable=Retryability.NON_RETRYABLE,
+            error=detail,
+        )
+        self.command = command
+        self.detail = detail
+
+
 class CoreHTTPException(HTTPException, PublicCoreException):
     """
     FastAPI HTTPException that is also a PublicCoreException.

corekit/files/__init__.py

@@ -9,15 +9,18 @@ File reading and writing, with format handled by the manager.
 """
 
 from corekit.files.base import FileContent, FileError, FileManager
+from corekit.files.disk import DiskScanner, PathSize
 from corekit.files.enum import FileMode
 from corekit.files.json import JsonFileManager
 from corekit.files.toml import TomlFileManager
 
 __all__ = [
+    "DiskScanner",
     "FileContent",
     "FileError",
     "FileManager",
     "FileMode",
     "JsonFileManager",
+    "PathSize",
     "TomlFileManager",
 ]

corekit/files/disk.py

@@ -0,0 +1,123 @@
+"""
+Measuring and truncating files on disk.
+
+``DiskScanner`` answers "how big is this path?" for files and directory
+trees, and truncates files in place. Every operation tries direct access
+first and, on failure, retries elevated through the ``CommandRunner``
+(log files and layer directories under a Docker root are root-owned, so an
+unprivileged process typically cannot stat them). Pass ``elevate=False``
+to disable the retry; unmeasurable paths then report ``None`` instead of
+prompting for a password.
+
+Sizes for single files are apparent sizes (``stat``); directory sizes are
+``du -sb`` totals. Both are byte counts and directly comparable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from corekit.exceptions import CommandFailedError
+from corekit.process import CommandRunner
+
+__all__ = ["DiskScanner", "PathSize"]
+
+
+@dataclass(frozen=True)
+class PathSize:
+    """
+    A filesystem path with its measured size in bytes.
+    """
+
+    path: Path
+    size_bytes: int
+
+
+class DiskScanner:
+    """
+    Filesystem sizing and in-place truncation, with optional elevation.
+    """
+
+    def __init__(self, runner: CommandRunner | None = None, *, elevate: bool = True) -> None:
+        """
+        :param runner: command executor for the elevated fallbacks and for
+            ``du``/``find``; a plain ``CommandRunner`` by default.
+        :param elevate: allow sudo retries when direct access fails.
+        """
+        self._runner = runner or CommandRunner()
+        self._elevate = elevate
+
+    def file_size(self, path: Path) -> int | None:
+        """
+        Size of a single file, or None if it cannot be measured.
+        """
+        try:
+            return path.stat().st_size
+        except OSError:
+            pass
+        if not self._elevate:
+            return None
+        try:
+            output = self._runner.run(["stat", "-c", "%s", str(path)], elevate=True)
+            return int(output.strip())
+        except (CommandFailedError, ValueError):
+            return None
+
+    def dir_size(self, path: Path) -> int | None:
+        """
+        Recursive size of a path (``du -sb``), or None if unmeasurable.
+        """
+        for elevate in (False, True):
+            if elevate and not self._elevate:
+                break
+            try:
+                output = self._runner.run(["du", "-sb", "--", str(path)], elevate=elevate)
+                return int(output.split()[0])
+            except (CommandFailedError, ValueError, IndexError):
+                continue
+        return None
+
+    def child_sizes(self, parent: Path) -> list[PathSize]:
+        """
+        Recursive sizes of every direct child of ``parent``, biggest first.
+        """
+        sizes: list[PathSize] = []
+        for child in self._children(parent):
+            size = self.dir_size(child)
+            if size is not None:
+                sizes.append(PathSize(path=child, size_bytes=size))
+        return sorted(sizes, key=lambda entry: entry.size_bytes, reverse=True)
+
+    def truncate(self, path: Path) -> None:
+        """
+        Truncate a file to zero bytes in place.
+
+        In place matters: deleting a file another process holds open does
+        not reclaim its space, truncating it does.
+        """
+        try:
+            with path.open("r+b") as handle:
+                handle.truncate(0)
+            return
+        except OSError:
+            pass
+        if not self._elevate:
+            raise PermissionError(f"Cannot truncate {path} (elevation disabled)")
+        self._runner.run(["truncate", "-s", "0", str(path)], elevate=True)
+
+    def _children(self, parent: Path) -> list[Path]:
+        """
+        Direct children of ``parent``, via elevated find if listing is denied.
+        """
+        try:
+            return sorted(parent.iterdir())
+        except OSError:
+            pass
+        if not self._elevate:
+            return []
+        try:
+            output = self._runner.run(["find", str(parent), "-mindepth", "1", "-maxdepth", "1"], elevate=True)
+        except CommandFailedError:
+            return []
+        return sorted(Path(line) for line in output.splitlines() if line.strip())

corekit/process/__init__.py

@@ -0,0 +1,7 @@
+"""
+External command execution.
+"""
+
+from corekit.process.runner import CommandRunner
+
+__all__ = ["CommandRunner"]

corekit/process/runner.py

@@ -0,0 +1,47 @@
+"""
+Running external commands.
+
+One place that knows how to spawn a process, capture its output, and report
+failure -- so callers stop re-writing the same ``subprocess.run`` block with
+slightly different error handling each time.
+
+``elevate=True`` prefixes the command with ``sudo``. That is for filesystem
+operations on root-owned paths (the canonical case is files under a Docker
+root); it is not a general "run as root" switch, and commands that have a
+proper unprivileged API should use it instead.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from corekit.exceptions import CommandFailedError
+
+__all__ = ["CommandRunner"]
+
+
+class CommandRunner:
+    """
+    Runs commands and returns stdout as text.
+
+    Deliberately a class rather than a function: tests and callers with
+    unusual needs (a recording fake, a remote executor) substitute their own
+    instance anywhere a runner is accepted.
+    """
+
+    def run(self, args: list[str], *, elevate: bool = False, timeout: float | None = None) -> str:
+        """
+        Run ``args`` and return stdout. Raises CommandFailedError on any
+        failure, including a missing executable or a timeout.
+        """
+        command = ["sudo", *args] if elevate else list(args)
+        try:
+            result = subprocess.run(command, capture_output=True, text=True, check=False, timeout=timeout)
+        except OSError as exc:
+            raise CommandFailedError(command, f"could not execute: {exc}") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise CommandFailedError(command, f"timed out after {timeout}s") from exc
+        if result.returncode != 0:
+            detail = result.stderr.strip() or f"exit code {result.returncode}"
+            raise CommandFailedError(command, detail)
+        return result.stdout

corekit/schemas/__init__.py

@@ -7,10 +7,12 @@ raises where it is introduced rather than somewhere further along.
 
 from corekit.schemas.enum import IntegerEnum, StringEnum, ValidatingEnum
 from corekit.schemas.models.arbitrary import ArbitraryModel
+from corekit.schemas.size import ByteSize
 from corekit.schemas.version import SemanticVersion
 
 __all__ = [
     "ArbitraryModel",
+    "ByteSize",
     "IntegerEnum",
     "SemanticVersion",
     "StringEnum",

corekit/schemas/size.py

@@ -0,0 +1,85 @@
+"""
+A byte size (``ByteSize.parse("100M")``, ``str(ByteSize(38 * 1024**2))``).
+
+Units are binary throughout (1 KB = 1024 bytes), so a value round-trips:
+``ByteSize.parse(str(size))`` returns an equal size, up to formatting
+precision. Suffixes may be bare (``100M``), short (``100MB``), or explicitly
+binary (``100MiB``); all three spellings mean the same thing.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Self
+
+__all__ = ["ByteSize"]
+
+_SIZE_PATTERN = re.compile(r"^(?P<value>[0-9]+(?:\.[0-9]+)?)\s*(?P<unit>[a-zA-Z]{0,3})$")
+_UNIT_MULTIPLIERS: dict[str, int] = {
+    "": 1,
+    "B": 1,
+    "K": 1024,
+    "KB": 1024,
+    "KIB": 1024,
+    "M": 1024**2,
+    "MB": 1024**2,
+    "MIB": 1024**2,
+    "G": 1024**3,
+    "GB": 1024**3,
+    "GIB": 1024**3,
+    "T": 1024**4,
+    "TB": 1024**4,
+    "TIB": 1024**4,
+    "P": 1024**5,
+    "PB": 1024**5,
+    "PIB": 1024**5,
+}
+_FORMAT_UNITS: tuple[str, ...] = ("B", "KB", "MB", "GB", "TB", "PB")
+
+
+@dataclass(frozen=True, order=True)
+class ByteSize:
+    """
+    An immutable byte count that parses and renders itself.
+    """
+
+    bytes: int
+
+    @classmethod
+    def parse(cls, value: ByteSize | int | str) -> Self:
+        """
+        Accept a ByteSize, an int byte count, or text like ``"100M"``.
+
+        Raises ValueError for anything that is not a size.
+        """
+        if isinstance(value, ByteSize):
+            return value
+        if isinstance(value, int):
+            return cls(bytes=value)
+        if isinstance(value, str):
+            match = _SIZE_PATTERN.match(value.strip().upper())
+            if match is not None:
+                multiplier = _UNIT_MULTIPLIERS.get(match.group("unit"))
+                if multiplier is not None:
+                    return cls(bytes=int(float(match.group("value")) * multiplier))
+        raise ValueError(f"Invalid byte size: {value!r} (expected e.g. 500K, 100M, 2G)")
+
+    def __str__(self) -> str:
+        value = float(self.bytes)
+        unit_index = 0
+        while value >= 1024 and unit_index < len(_FORMAT_UNITS) - 1:
+            value /= 1024
+            unit_index += 1
+        if unit_index == 0:
+            return f"{self.bytes} {_FORMAT_UNITS[unit_index]}"
+        return f"{value:.1f} {_FORMAT_UNITS[unit_index]}"
+
+    def __repr__(self) -> str:
+        return f"ByteSize({self})"
+
+    def __int__(self) -> int:
+        return self.bytes
+
+    def __float__(self) -> float:
+        return float(self.bytes)

corekit/utils/__init__.py

@@ -23,10 +23,17 @@ from corekit.utils.collections import (
     MultiMatch,
     aiterator,
     attr_or_key,
+    first,
+    first_float,
+    first_int,
+    first_string,
+    getval,
     iterator,
     keygetter,
     kv_string,
+    list_map,
     repeated_get,
+    set_map,
     split_list,
 )
 from corekit.utils.ids import (
@@ -64,15 +71,21 @@ __all__ = [
     "decode_payload",
     "encode_payload",
     "false_validator",
+    "first",
+    "first_string",
+    "first_int",
+    "first_float",
     "generate_session_token",
     "generate_shortcode",
     "generate_shortcodes",
     "generate_uuid",
+    "getval",
     "isoformat_now",
     "iterator",
     "join_lines",
     "keygetter",
     "kv_string",
+    "list_map",
     "list_to_english",
     "parse_dict",
     "parse_docker_timestamp",
@@ -91,6 +104,7 @@ __all__ = [
     "safe_set",
     "safe_string",
     "safe_tuple",
+    "set_map",
     "sanitize_filename",
     "split_list",
     "time_now",

corekit/utils/coercion.py

@@ -38,7 +38,7 @@ __all__ = [
 ]
 
 
-def safe_string(item: Any, pretty: bool = False) -> str:
+def safe_string(item: Any, pretty: bool = False, default: str = "") -> str:
     """
     Convert anything to a string, or ``""`` if there is no sensible rendering.
 
@@ -46,44 +46,44 @@ def safe_string(item: Any, pretty: bool = False) -> str:
     list instead -- ``"a, b, c"``, or ``"key: value, ..."`` for a mapping --
     which reads better in a notification than raw JSON.
     """
-    return parse_string(item, pretty=pretty, default="").value
+    return parse_string(item, pretty=pretty, default=default).value
 
 
-def safe_int(item: Any) -> int:
+def safe_int(item: Any, default: int = 0) -> int:
     """
     Convert anything to an int, or ``0`` if it will not convert.
     """
-    return parse_int(item, default=0).value
+    return parse_int(item, default=default).value
 
 
-def safe_float(item: Any) -> float:
+def safe_float(item: Any, default: float = 0.0) -> float:
     """
     Convert anything to a float, or ``0.0`` if it will not convert.
     """
-    return parse_float(item, default=0.0).value
+    return parse_float(item, default=default).value
 
 
-def safe_list(item: Any) -> list[Any]:
+def safe_list(item: Any, default: list[Any] | None = None) -> list[Any]:
     """
     Convert a collection to a list, or ``[]`` for anything else.
 
     A mapping yields its values. A string is *not* treated as a collection --
     exploding it into characters is almost never what the caller meant.
     """
-    return parse_list(item, default=[]).value
+    return parse_list(item, default=default if default is not None else []).value
 
 
-def safe_tuple(item: Any) -> tuple[Any, ...]:
+def safe_tuple(item: Any, default: tuple[Any, ...] | None = None) -> tuple[Any, ...]:
     """
     Convert a collection to a tuple, or ``()`` for anything else.
 
     A mapping yields its values. A string is *not* treated as a collection --
     exploding it into characters is almost never what the caller meant.
     """
-    return parse_tuple(item, default=()).value
+    return parse_tuple(item, default=default if default is not None else ()).value
 
 
-def safe_set(item: Any) -> set[Any]:
+def safe_set(item: Any, default: set[Any] | None = None) -> set[Any]:
     """
     Convert a collection to a set, or ``set()`` for anything else.
 
@@ -91,14 +91,14 @@ def safe_set(item: Any) -> set[Any]:
     exploding it into characters is almost never what the caller meant.
     Unhashable elements yield ``set()``.
     """
-    return parse_set(item, default=set()).value
+    return parse_set(item, default=default if default is not None else set()).value
 
 
-def safe_dict(item: Any) -> dict[str, Any]:
+def safe_dict(item: Any, default: dict[str, Any] | None = None) -> dict[str, Any]:
     """
     Return the mapping unchanged, or ``{}`` for anything else.
 
     Also accepts objects that expose ``to_dict``, ``model_dump``, or ``dict``,
     and falls back to ``__dict__`` when present.
     """
-    return parse_dict(item, default={}).value
+    return parse_dict(item, default=default if default is not None else {}).value

corekit/utils/collections.py

@@ -4,7 +4,8 @@ Nested lookup and small collection helpers.
 ``repeated_get`` walks a path into nested dictionaries without a pile of
 ``.get()`` calls, and ``keygetter`` lets a step in that path match many keys at
 once. Built for JSON from somewhere you do not control, where any level may be
-missing or the wrong type.
+missing or the wrong type. ``getval`` is the mixed-source counterpart: it walks
+dicts and attribute-bearing objects alike, with ordered fallback keys.
 """
 
 from __future__ import annotations
@@ -12,16 +13,25 @@ from __future__ import annotations
 import inspect
 from collections.abc import AsyncIterable, AsyncIterator, Iterable, Mapping
 from copy import deepcopy
-from typing import Any, Awaitable, Callable, Iterator, Literal
+from typing import Any, Awaitable, Callable, Iterator, Literal, Sequence
+
+from corekit.utils.coercion import safe_float, safe_int, safe_string
 
 __all__ = [
     "MultiMatch",
     "aiterator",
     "attr_or_key",
+    "first",
+    "first_float",
+    "first_int",
+    "first_string",
+    "getval",
     "iterator",
     "keygetter",
     "kv_string",
+    "list_map",
     "repeated_get",
+    "set_map",
     "split_list",
 ]
 
@@ -94,7 +104,7 @@ def iterator(
         for key, value in obj.items():
             if compact and value is None:
                 continue
-            if where is not None and not where(key, value):  # type: ignore[call-arg, arg-type]
+            if where is not None and not bool(where(key, value)):  # type: ignore[call-arg, arg-type]
                 continue
             yield _mapping_item(key, value, mode)
         return
@@ -102,7 +112,7 @@ def iterator(
     for item in obj:
         if compact and item is None:
             continue
-        if where is not None and not where(item):  # type: ignore[call-arg, arg-type]
+        if where is not None and not bool(where(item)):  # type: ignore[call-arg, arg-type]
             continue
         yield item
 
@@ -166,6 +176,101 @@ async def aiterator(
         yield item
 
 
+def first(seq: Sequence[Any], default: Any = None) -> Any:
+    """
+    Get the first item from a sequence, or ``default`` if empty.
+    """
+    if not seq:
+        return default
+    return next(iter(seq), default)
+
+
+def first_string(seq: Sequence[Any], default: str = "") -> str:
+    """
+    First item of ``seq`` as a string, or ``default`` if empty/unconvertible.
+    """
+    return safe_string(first(seq, default), default=default)
+
+
+def first_int(seq: Sequence[Any], default: int = 0) -> int:
+    """
+    First item of ``seq`` as an int, or ``default`` if empty/unconvertible.
+    """
+    return safe_int(first(seq, default), default=default)
+
+
+def first_float(seq: Sequence[Any], default: float = 0.0) -> float:
+    """
+    First item of ``seq`` as a float, or ``default`` if empty/unconvertible.
+    """
+    return safe_float(first(seq, default), default=default)
+
+
+def list_map(
+    obj: Iterable[Any] | Mapping[Any, Any] | None,
+    func: Callable[[Any], Any],
+    *,
+    mode: IteratorMode = "keys",
+    where: WhereSeq | WhereMap | None = None,
+    compact: bool = False,
+) -> list[Any]:
+    return [func(item) for item in iterator(obj, mode=mode, where=where, compact=compact)]
+
+
+def set_map(
+    obj: Iterable[Any] | Mapping[Any, Any] | None,
+    func: Callable[[Any], Any],
+    *,
+    mode: IteratorMode = "keys",
+    where: WhereSeq | WhereMap | None = None,
+    compact: bool = False,
+) -> set[Any]:
+    return {func(item) for item in iterator(obj, mode=mode, where=where, compact=compact)}
+
+
+def getval(
+    obj: Any,
+    key: str,
+    default: Any = None,
+    default_factory: Callable[[], Any] | None = None,
+    fallback_keys: list[str] | None = None,
+) -> Any:
+    """
+    Read `key` (dot-paths supported) from a dict, pydantic model, dataclass, or any other
+    arbitrary object. Returns `default` on miss, or `default_factory`, if provided. Use
+    `default_factory` for mutable defaults so callers never share an instance. Before the
+    default is applied, we will try each item in `fallback_keys` (in order).
+
+    A key that is present with value ``None`` is a hit, not a miss: ``None``
+    is returned and neither fallbacks nor defaults apply. For dict-only walks
+    with predicate steps, use ``repeated_get`` instead.
+    """
+
+    def _get(_obj: Any, _key: str) -> Any:
+        if _obj is UNSET or _obj is None:
+            return UNSET
+        if isinstance(_obj, dict):
+            return _obj.get(_key, UNSET)
+        if hasattr(_obj, _key):
+            return getattr(_obj, _key, UNSET)
+        return UNSET
+
+    value = obj
+    for next_key in key.split("."):
+        value = _get(value, next_key)
+
+    if value is not UNSET:
+        return value
+
+    if fallback_keys:
+        next_key, *remaining = fallback_keys
+        return getval(obj, next_key, default, default_factory, remaining)
+
+    if default_factory is not None and callable(default_factory):
+        return default_factory()
+    return default
+
+
 def kv_string(key: str, value: Any, sep: str = ": ", prefix: str = "") -> str:
     """
     Format a key-value pair into a string.

{python_corekit-0.5.0.dist-info → python_corekit-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-corekit
-Version: 0.5.0
+Version: 0.6.0
 Summary: Shared foundations for Python projects: logging, benchmarking, registries, FastAPI application and routers, SQL statements and migrations, background tasks, ETL, LLM chat/tool primitives, and HTML scraping
 Author: Steven Jacobsen
 License-Expression: MIT
@@ -433,6 +433,7 @@ corekit/
 
   observability/                   Loggable, Benchmarkable, Timer
   registry/  schemas/  utils/      registries, enums and fields, helpers
+  process/                         CommandRunner (external commands)
   data/                            Dataset and its filter expressions
   jobs/                            queue-independent background tasks
   crypto/  files/  serialization/
@@ -445,7 +446,7 @@ corekit/
   http/                            BaseHttpClient, BaseApiClient, retries, responses
 
   api/                             Application, lifespan, middleware, routers
-  docker/  notifications/  etl/
+  docker/  notifications/  etl/    Watchdog, DockerDiskInspector, client provider
   llm/                             messages, tools, agentic loop (no GenerationClient)
 
   events/  log_monitor/            built on the capabilities above

{python_corekit-0.5.0.dist-info → python_corekit-0.6.0.dist-info}/RECORD

@@ -51,8 +51,14 @@ corekit/data/expressions/target.py,sha256=QSl7sH1qFVUc-mL7gsasTsCahWKhHqdo0bMHt-
 corekit/decorators/__init__.py,sha256=YrBcc_4wkSs7nEb3OjC7C7a8fNEvBk3RzOpD8QccHKM,83
 corekit/decorators/exception_handling.py,sha256=p86gfvdmsmC7_va042NSoGkWrJrbLLuw0ncE131wLWU,2326
 corekit/decorators/warnings.py,sha256=RS7AS6OS05VxiWaMjkj6kYky9FbpT4Z-Cb7TQoPOObk,1109
-corekit/docker/__init__.py,sha256=LtrmEvqorme1-YwL0jGNFLEASdgn69s0eYuh490anmg,104
-corekit/docker/watchdog.py,sha256=kAOF9x-h_oQmyKrkcc4eQ1_HIofRDyYyrfeAULyyBtQ,8855
+corekit/docker/__init__.py,sha256=UnJd13PrmnYIprkDrX34nMhCRXyWPv74X4loobMFq6w,358
+corekit/docker/client.py,sha256=3FO_MNLbMGAfErBv78rmx6052vr5SSaEBlOoRJPVhJQ,1519
+corekit/docker/constants.py,sha256=tIMfN5ii3ht5tiWXowW8UmjQWcr9Rmn681Llysh9qIM,523
+corekit/docker/watchdog.py,sha256=L-yZWlbteShSdMKPDT-7JVzqfQU8MT1XDEFVWF11aY8,9268
+corekit/docker/disk/__init__.py,sha256=ZTr77TJuUdVvv6wbWXvYW0I5oVz45EwzbGjbjrUy1vk,295
+corekit/docker/disk/constants.py,sha256=4fMEAdWwHbiBbe7aj3vV4molxRGZ3eLl1tyIPQ47D1o,465
+corekit/docker/disk/inspector.py,sha256=YBRCX6upUclOPyu2PT2VkfyXKUPXJUv6Wwd_XYvA7lU,8156
+corekit/docker/disk/models.py,sha256=9z8dTUyTEp8NfMmzBul2yp8sLAcEjoMytz_gCj7veKY,733
 corekit/etl/__init__.py,sha256=KFuGv6xstJbEJHHYo_X5akEq_b7muDyKXCGdFeZ3_0M,1369
 corekit/etl/connection.py,sha256=_gWqR36x5f7qb5IYJjrc_7d_6oU2CXm1QeSNCCh0coo,1270
 corekit/etl/orchestrator.py,sha256=GkecTu8gKt17ePDM9PJBUuZTPYoPMdK1yYzBHjMdw3A,7959
@@ -83,14 +89,15 @@ corekit/exceptionator/fingerprint.py,sha256=Fjf02FFOq3pm4o88F0I7QDy7Nq9EwgA01jjp
 corekit/exceptionator/guard.py,sha256=SU95rYpadfqgAUogmXSQyHvHCP7xATADlQyOTwLO_Qk,1180
 corekit/exceptionator/jobs.py,sha256=ufQZNc5bbEsl3IYyCuTtaShXh0-lSbCReTouZHqpv9k,1340
 corekit/exceptionator/models.py,sha256=CQxKKzBBerkEqdUnuPVyXflzx2r9cjFzUpG8K8VizhE,2437
-corekit/exceptions/__init__.py,sha256=8q9EX-0bzOiJI1FOzCbViQFwx53Ugs8NH482Cvpci6k,995
-corekit/exceptions/base.py,sha256=k0AfTfPrLWR6x-l2qvvjqD_sup0fiWhqu1OoNaNM-Lk,5596
+corekit/exceptions/__init__.py,sha256=_csPo9yMZrRTlz2CQfM2bePtDNGPeAksWkKy8EanhLQ,1045
+corekit/exceptions/base.py,sha256=aq_5QSePwI1xowIUv7Tndjlv0r8YI9wT2xJL45fQa-A,6206
 corekit/exceptions/enum.py,sha256=D-YL-cZXs-F2jS1GgRBhPWmuqBfX33B1QP61vAXdAes,324
 corekit/exceptions/types.py,sha256=rxhQ8sghV2TCHh_vB7tX6Yb6Vkyv1PF_0PLtalyFVxY,665
 corekit/exceptions/custom/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 corekit/exceptions/http/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-corekit/files/__init__.py,sha256=IllQEAWtcT72vVUdRaMwfF5VlhzMJ16VIKDhqvWG9Cw,612
+corekit/files/__init__.py,sha256=SnN2PGTQ5D4nkBTb3pnXr5dPzOhpxa9ulYTDJyWLyM0,700
 corekit/files/base.py,sha256=Ca2bhdlwntHh425PedaUG-UW2fEFZsPCss_3f7REsAE,4022
+corekit/files/disk.py,sha256=Jcsdvy8o_UFaYFkC7uSI0vKO7MK_4fsC8I6DZNeBSKE,4176
 corekit/files/enum.py,sha256=mcrQXcp-AizTAp4VoaVMLj9zu5D81XXMsnZwZqe6fz0,597
 corekit/files/json.py,sha256=pRYLKNjeVmkDQsgtjBboFFY5Ljx1Pwa3MFEeQBc4o-g,909
 corekit/files/toml.py,sha256=YFRwghMapbCRSl7srqcI7IhqaTQDyO56XRasGMu_Aug,1273
@@ -146,11 +153,14 @@ corekit/observability/timing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NM
 corekit/observability/timing/constants.py,sha256=Cv6h98NHzJiTJJufVQBVMBpdI0_fNMTnxAZF0j0vrsg,22
 corekit/observability/timing/split.py,sha256=EdzCKx4pwAkcMzG7kmicRKdoyhBTZ-JkftJpsQ73Vww,811
 corekit/observability/timing/timer.py,sha256=rBGYYnBq-1E85Om37dkbPM9wKsXsltyeWeAQHkKSaZQ,1657
+corekit/process/__init__.py,sha256=KRtZx452ICjWpkNhpvcySYtaNGp0WXXGRsZCY_6Y1VM,115
+corekit/process/runner.py,sha256=4ArfL-XxVFCHX_l-gM2oN0bY3h0It0s9yvWN2R5_aLM,1808
 corekit/registry/__init__.py,sha256=R67Jssr06Eyx2u5AbX1omm2LziWvwS_Sd7fExnNv9CM,681
 corekit/registry/ordered.py,sha256=_KS4mWzmLgFvODW2M0_ugxZIBW_dKhwwxrVrtNqLMfs,2506
 corekit/registry/registry.py,sha256=t1iwzxgvd-iyLIf_5wahg_P7eN9V1oumpupkAqi2GdQ,5601
-corekit/schemas/__init__.py,sha256=4EK7QNWP16U6ZKno_ZKTDfgSflc9W2PFMPskc0kvSdw,470
+corekit/schemas/__init__.py,sha256=qAVoXLfxh4fJmT3IhMI-fJGnQEV-MzmQ1pYHBTc08_s,528
 corekit/schemas/enum.py,sha256=gLc44kIXRfpDFkV51JoN4KT1CU92hnb529rd1b88fBM,2033
+corekit/schemas/size.py,sha256=E_6kZ7yXqfxBqDdXnmiNfdzTyakv1YKtnPNigLiyEmk,2478
 corekit/schemas/types.py,sha256=AWIxZHXUiUjJRZjmOhAdCq3RIsRzL-Fy7RvYy4i5Ozo,1347
 corekit/schemas/version.py,sha256=InWtfKf0iyfu_eBLaFm_QNwkSjpgKc1jGJZeWYjQQUc,1753
 corekit/schemas/dataclasses/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -164,9 +174,9 @@ corekit/serialization/enum.py,sha256=pzHuAIXeonEF7-jyN1uYddJk-xvmQGuymDf1U6RWR5w
 corekit/serialization/pickle_file.py,sha256=dudKIxR8ueT3wx_IBxHJeoqnFeP1rT7dlTb_PXlSkd8,2251
 corekit/serialization/serializable.py,sha256=viF3ZCKRJ90hk6m4lbqIfo6ifsY2c4sXr4xZrn1Yz-Q,1999
 corekit/serialization/serializer.py,sha256=XlGE1Rq8M55Jl2a4F5MkvDcba2VI7lrh0v9kwL0DWG8,6617
-corekit/utils/__init__.py,sha256=lNdmVmQBUFckkCIjzxYLHpLe06rudXS9t_evVEv-le4,2419
-corekit/utils/coercion.py,sha256=lnAdPuY7Hha81of1I8oPIu6C8ow6JqWWpuF1sPX17Ek,3084
-corekit/utils/collections.py,sha256=4ieN3r44Y1DPoJQYpoXn8mL_nTKd5i9GjAoBOMXwd40,8335
+corekit/utils/__init__.py,sha256=wh-cMaWtzw1sEjQ9_O7tdQKMxqIPBNyfFcud0uOB-ZY,2633
+corekit/utils/coercion.py,sha256=dnJ-lUW5_MOMrERhRxsL7LBwPAB-mh6Bua6eI-C-q1Q,3448
+corekit/utils/collections.py,sha256=mj-YRUT0sgodqSvTNqJTpRs4lN1vMnJ_piOv9Vr9aRo,11609
 corekit/utils/ids.py,sha256=BVniaYqewM-EosDxcJAT_S_7T9C1c5X8nsaVGs5up34,1731
 corekit/utils/parsers.py,sha256=b7bCaMd7_VKaFnin6vn3v1Eol_Z0vvr3vjDO4ro5ycI,6628
 corekit/utils/payload.py,sha256=T7EgdVU0S5h8MAzvQsmkfRPMatWqUbxjHL9hmZdM9ho,3882
@@ -175,8 +185,8 @@ corekit/utils/text.py,sha256=0322DdZGuDGEagTyejuda6QT1jbbxNIO6loC-_AGml0,2311
 corekit/utils/time.py,sha256=-iPaETXcgDu7J39Kwe938JyZKhPVjl6a572BBqsqcDQ,2215
 corekit/utils/validators.py,sha256=_HVKo3y264KGNaZ-1RyM1x46VPvu7XKcQkrHWDC9uxs,340
 corekit/utils/void.py,sha256=eXDb2QynuguiSgHGJLdgE08MuRnxBdYebRdMD7s1m9o,178
-python_corekit-0.5.0.dist-info/licenses/LICENSE,sha256=357LYxbxAQZ95q5cV-8JK6j-KNgiE6AteRodjEsm-kE,1072
-python_corekit-0.5.0.dist-info/METADATA,sha256=GFJChQrVckK79FiPnCddTLGr36xpxik6BqrtAjskE_A,15185
-python_corekit-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_corekit-0.5.0.dist-info/top_level.txt,sha256=SDK4o8BoaI47E9tPbiNCbbWoc2y6N_wCjwnIEfr-GWI,8
-python_corekit-0.5.0.dist-info/RECORD,,
+python_corekit-0.6.0.dist-info/licenses/LICENSE,sha256=357LYxbxAQZ95q5cV-8JK6j-KNgiE6AteRodjEsm-kE,1072
+python_corekit-0.6.0.dist-info/METADATA,sha256=YrgBgcZgbYS5eB2yhz2B-9Jvx-K3AZ9VhGt4ihLuZCs,15304
+python_corekit-0.6.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_corekit-0.6.0.dist-info/top_level.txt,sha256=SDK4o8BoaI47E9tPbiNCbbWoc2y6N_wCjwnIEfr-GWI,8
+python_corekit-0.6.0.dist-info/RECORD,,

{python_corekit-0.5.0.dist-info → python_corekit-0.6.0.dist-info}/WHEEL

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