adrian-utils 0.1.1__tar.gz

adrian_utils-0.1.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: adrian-utils
+Version: 0.1.1
+Summary: Generic Python utilities (DX-first terminal logger, XDG directories, number/percentage/currency formatting). Python 3.12+.
+Author-email: Adrian Galilea <adriangalilea@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=14.1.0
+Requires-Dist: ruff>=0.13.2
+
+# adrian-utils
+
+Generic Python utilities — DX-first terminal logger, XDG directories, number/percentage/currency formatting. Python 3.12+.
+
+## Install
+
+```bash
+pip install adrian-utils
+# or with uv
+uv add adrian-utils
+```
+
+## Install (local dev)
+
+```bash
+uv add -e .
+```
+
+## Usage
+
+```python
+from py_utils import log, xdg, usd, percentage
+
+# XDG directories
+config_file = xdg.config / "myapp" / "config.toml"
+data_file = xdg.data / "myapp" / "database.db"
+cache_dir = xdg.cache / "myapp"
+
+# Narration
+log.info("Connected to postgres:5432")
+
+# Task with steps
+with log.task("Build assets"):
+    log.step("Transpiling")
+    log.step("Bundling")
+
+# Status
+log.success("Deployed")
+log.warn_once("Flag --fast is deprecated")
+
+# Progress
+with log.task("Sync"):
+    p = log.progress(total=3, title="Uploading")
+    p.tick(); p.tick(); p.tick(); p.done(success=True)
+
+# Formatting
+usd(1234.56)                  # "+$1,234.56" (color and + by default)
+usd(1234.56, signed=False)    # "$1,234.56" (no leading +)
+percentage(15.234)            # "+15.2%"
+percentage(15.234, signed=False)  # "15.2%"
+```
+
+Colors automatically disable when stdout is not a TTY. To override:
+
+```python
+from py_utils import set_color_enabled
+
+set_color_enabled(True)   # force color on
+set_color_enabled(False)  # force color off
+set_color_enabled(None)   # return to auto detection
+```
+
+Run the bundled demo:
+
+```bash
+# After `uv add -e .`
+uv run python example_usage.py
+```
+
+## Linting / Formatting
+
+```bash
+uv run ruff check src
+uv run ruff format src
+```
+
+## TODO
+
+- Port the KEV environment manager (see `ts-utils/src/platform/kev.ts` and `go-utils/kev.go`).
+
+Part of the utils suite by Adrian Galilea.

adrian_utils-0.1.1/README.md

@@ -0,0 +1,81 @@
+# adrian-utils
+
+Generic Python utilities — DX-first terminal logger, XDG directories, number/percentage/currency formatting. Python 3.12+.
+
+## Install
+
+```bash
+pip install adrian-utils
+# or with uv
+uv add adrian-utils
+```
+
+## Install (local dev)
+
+```bash
+uv add -e .
+```
+
+## Usage
+
+```python
+from py_utils import log, xdg, usd, percentage
+
+# XDG directories
+config_file = xdg.config / "myapp" / "config.toml"
+data_file = xdg.data / "myapp" / "database.db"
+cache_dir = xdg.cache / "myapp"
+
+# Narration
+log.info("Connected to postgres:5432")
+
+# Task with steps
+with log.task("Build assets"):
+    log.step("Transpiling")
+    log.step("Bundling")
+
+# Status
+log.success("Deployed")
+log.warn_once("Flag --fast is deprecated")
+
+# Progress
+with log.task("Sync"):
+    p = log.progress(total=3, title="Uploading")
+    p.tick(); p.tick(); p.tick(); p.done(success=True)
+
+# Formatting
+usd(1234.56)                  # "+$1,234.56" (color and + by default)
+usd(1234.56, signed=False)    # "$1,234.56" (no leading +)
+percentage(15.234)            # "+15.2%"
+percentage(15.234, signed=False)  # "15.2%"
+```
+
+Colors automatically disable when stdout is not a TTY. To override:
+
+```python
+from py_utils import set_color_enabled
+
+set_color_enabled(True)   # force color on
+set_color_enabled(False)  # force color off
+set_color_enabled(None)   # return to auto detection
+```
+
+Run the bundled demo:
+
+```bash
+# After `uv add -e .`
+uv run python example_usage.py
+```
+
+## Linting / Formatting
+
+```bash
+uv run ruff check src
+uv run ruff format src
+```
+
+## TODO
+
+- Port the KEV environment manager (see `ts-utils/src/platform/kev.ts` and `go-utils/kev.go`).
+
+Part of the utils suite by Adrian Galilea.

adrian_utils-0.1.1/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "adrian-utils"
+version = "0.1.1"
+description = "Generic Python utilities (DX-first terminal logger, XDG directories, number/percentage/currency formatting). Python 3.12+."
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    { name = "Adrian Galilea", email = "adriangalilea@gmail.com" },
+]
+dependencies = [
+    "rich>=14.1.0",
+    "ruff>=0.13.2",
+]

adrian_utils-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adrian_utils-0.1.1/src/adrian_utils.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: adrian-utils
+Version: 0.1.1
+Summary: Generic Python utilities (DX-first terminal logger, XDG directories, number/percentage/currency formatting). Python 3.12+.
+Author-email: Adrian Galilea <adriangalilea@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=14.1.0
+Requires-Dist: ruff>=0.13.2
+
+# adrian-utils
+
+Generic Python utilities — DX-first terminal logger, XDG directories, number/percentage/currency formatting. Python 3.12+.
+
+## Install
+
+```bash
+pip install adrian-utils
+# or with uv
+uv add adrian-utils
+```
+
+## Install (local dev)
+
+```bash
+uv add -e .
+```
+
+## Usage
+
+```python
+from py_utils import log, xdg, usd, percentage
+
+# XDG directories
+config_file = xdg.config / "myapp" / "config.toml"
+data_file = xdg.data / "myapp" / "database.db"
+cache_dir = xdg.cache / "myapp"
+
+# Narration
+log.info("Connected to postgres:5432")
+
+# Task with steps
+with log.task("Build assets"):
+    log.step("Transpiling")
+    log.step("Bundling")
+
+# Status
+log.success("Deployed")
+log.warn_once("Flag --fast is deprecated")
+
+# Progress
+with log.task("Sync"):
+    p = log.progress(total=3, title="Uploading")
+    p.tick(); p.tick(); p.tick(); p.done(success=True)
+
+# Formatting
+usd(1234.56)                  # "+$1,234.56" (color and + by default)
+usd(1234.56, signed=False)    # "$1,234.56" (no leading +)
+percentage(15.234)            # "+15.2%"
+percentage(15.234, signed=False)  # "15.2%"
+```
+
+Colors automatically disable when stdout is not a TTY. To override:
+
+```python
+from py_utils import set_color_enabled
+
+set_color_enabled(True)   # force color on
+set_color_enabled(False)  # force color off
+set_color_enabled(None)   # return to auto detection
+```
+
+Run the bundled demo:
+
+```bash
+# After `uv add -e .`
+uv run python example_usage.py
+```
+
+## Linting / Formatting
+
+```bash
+uv run ruff check src
+uv run ruff format src
+```
+
+## TODO
+
+- Port the KEV environment manager (see `ts-utils/src/platform/kev.ts` and `go-utils/kev.go`).
+
+Part of the utils suite by Adrian Galilea.

adrian_utils-0.1.1/src/adrian_utils.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/adrian_utils.egg-info/PKG-INFO
+src/adrian_utils.egg-info/SOURCES.txt
+src/adrian_utils.egg-info/dependency_links.txt
+src/adrian_utils.egg-info/requires.txt
+src/adrian_utils.egg-info/top_level.txt
+src/py_utils/__init__.py
+src/py_utils/currency.py
+src/py_utils/format.py
+src/py_utils/log.py
+src/py_utils/xdg.py

adrian_utils-0.1.1/src/adrian_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

adrian_utils-0.1.1/src/adrian_utils.egg-info/requires.txt

@@ -0,0 +1,2 @@
+rich>=14.1.0
+ruff>=0.13.2

adrian_utils-0.1.1/src/adrian_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+py_utils

adrian_utils-0.1.1/src/py_utils/__init__.py

@@ -0,0 +1,81 @@
+"""
+py_utils: Generic Python utilities (Python 3.12+)
+
+Currently includes:
+- TTY-focused logger with tasks/steps/indentation, symbols, colors
+- Number/percentage formatting helpers
+- Currency formatting utilities with optimal decimals
+
+This package intentionally avoids stdlib logging and JSON outputs.
+It focuses on crisp terminal output for interactive use and CI-friendly
+plain text when not attached to a TTY.
+"""
+
+from .log import (
+    log,
+    Logger,
+)
+
+from .format import (
+    number,
+    number_plain,
+    with_commas,
+    compact,
+    bytes_fmt,
+    duration,
+    percentage,
+    percentage_change,
+    percentage_diff,
+    bps,
+    sign,
+    apply_sign,
+    set_color_enabled,
+    color_enabled,
+)
+
+from .currency import (
+    get_symbol,
+    get_optimal_decimals,
+    usd,
+    btc,
+    eth,
+    auto,
+    is_crypto,
+    is_fiat,
+    is_stablecoin,
+    bps_to_percent,
+    percent_to_bps,
+)
+
+__all__ = [
+    # logger
+    "log",
+    "Logger",
+    # format
+    "number",
+    "number_plain",
+    "with_commas",
+    "compact",
+    "bytes_fmt",
+    "duration",
+    "percentage",
+    "percentage_change",
+    "percentage_diff",
+    "bps",
+    "sign",
+    "apply_sign",
+    "set_color_enabled",
+    "color_enabled",
+    # currency
+    "get_symbol",
+    "get_optimal_decimals",
+    "usd",
+    "btc",
+    "eth",
+    "auto",
+    "is_crypto",
+    "is_fiat",
+    "is_stablecoin",
+    "bps_to_percent",
+    "percent_to_bps",
+]

adrian_utils-0.1.1/src/py_utils/currency.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+from math import fabs
+
+from .format import number_plain, color_by_sign, apply_sign
+
+
+SYMBOLS: dict[str, str] = {
+    "BTC": "₿",
+    "XBT": "₿",
+    "ETH": "Ξ",
+    "USD": "$",
+    "EUR": "€",
+    "GBP": "£",
+    "JPY": "¥",
+    "CNY": "¥",
+    "KRW": "₩",
+    "INR": "₹",
+    "RUB": "₽",
+    "TRY": "₺",
+    "AUD": "A$",
+    "CAD": "C$",
+    "CHF": "Fr",
+    "HKD": "HK$",
+    "SGD": "S$",
+    "NZD": "NZ$",
+    "SEK": "kr",
+    "NOK": "kr",
+    "DKK": "kr",
+    "PLN": "zł",
+    "THB": "฿",
+    "USDT": "₮",
+    "USDC": "$",
+    "DAI": "$",
+    "BUSD": "$",
+}
+
+
+def get_symbol(code: str) -> str:
+    return SYMBOLS.get(code.upper(), code)
+
+
+def is_stablecoin(code: str) -> bool:
+    return code.upper() in {
+        "USDT",
+        "USDC",
+        "DAI",
+        "BUSD",
+        "UST",
+        "TUSD",
+        "USDP",
+        "GUSD",
+        "FRAX",
+        "LUSD",
+    }
+
+
+def is_fiat(code: str) -> bool:
+    return code.upper() in {
+        "USD",
+        "EUR",
+        "GBP",
+        "JPY",
+        "CNY",
+        "CAD",
+        "AUD",
+        "CHF",
+        "HKD",
+        "SGD",
+        "NZD",
+        "KRW",
+        "SEK",
+        "NOK",
+        "DKK",
+        "PLN",
+        "THB",
+        "INR",
+        "RUB",
+        "TRY",
+        "BRL",
+        "MXN",
+        "ARS",
+        "CLP",
+        "COP",
+        "PEN",
+        "UYU",
+        "ZAR",
+        "NGN",
+        "KES",
+    }
+
+
+def is_crypto(code: str) -> bool:
+    return code.upper() in {
+        "BTC",
+        "XBT",
+        "ETH",
+        "BNB",
+        "XRP",
+        "ADA",
+        "DOGE",
+        "SOL",
+        "DOT",
+        "MATIC",
+        "SHIB",
+        "TRX",
+        "AVAX",
+        "UNI",
+        "ATOM",
+        "LINK",
+        "XMR",
+        "XLM",
+        "ALGO",
+        "VET",
+        "MANA",
+        "SAND",
+        "AXS",
+        "THETA",
+        "FTM",
+        "NEAR",
+        "HNT",
+        "GRT",
+        "ENJ",
+        "CHZ",
+    }
+
+
+def get_optimal_decimals(value: float, code: str) -> int:
+    if value == 0:
+        return 8 if is_crypto(code) else 2
+    abs_v = fabs(value)
+
+    if code.upper() in {"BTC", "XBT"}:
+        if abs_v < 0.00001:
+            return 10
+        if abs_v < 0.0001:
+            return 9
+        if abs_v < 0.001:
+            return 8
+        if abs_v < 0.01:
+            return 7
+        if abs_v < 0.1:
+            return 6
+        if abs_v < 1:
+            return 5
+        return 4
+
+    if code.upper() == "ETH":
+        if abs_v < 0.001:
+            return 8
+        if abs_v < 0.01:
+            return 7
+        if abs_v < 0.1:
+            return 6
+        if abs_v < 1:
+            return 5
+        return 4
+
+    if code.upper() in {"USD", "USDT", "USDC", "DAI", "BUSD"}:
+        if abs_v < 0.01:
+            return 6
+        if abs_v < 0.1:
+            return 4
+        if abs_v < 1:
+            return 3
+        return 2
+
+    if is_crypto(code):
+        if abs_v < 0.00001:
+            return 8
+        if abs_v < 0.0001:
+            return 6
+        if abs_v < 0.001:
+            return 5
+        if abs_v < 0.01:
+            return 4
+        if abs_v < 0.1:
+            return 3
+        if abs_v < 1:
+            return 3
+        if abs_v < 100:
+            return 2
+        return 0
+
+    # fiat defaults
+    if abs_v < 0.01:
+        return 4
+    if abs_v < 0.1:
+        return 3
+    if abs_v < 1000:
+        return 2
+    return 0
+
+
+def usd(value: float, *, signed: bool = True) -> str:
+    decimals = get_optimal_decimals(value, "USD")
+    body = f"${number_plain(abs(value), decimals)}"
+    token = apply_sign(value, body, signed=signed)
+    return color_by_sign(value, token)
+
+
+def btc(value: float, *, signed: bool = True) -> str:
+    decimals = get_optimal_decimals(value, "BTC")
+    body = f"{number_plain(abs(value), decimals)} ₿"
+    token = apply_sign(value, body, signed=signed)
+    return color_by_sign(value, token)
+
+
+def eth(value: float, *, signed: bool = True) -> str:
+    decimals = get_optimal_decimals(value, "ETH")
+    body = f"{number_plain(abs(value), decimals)} Ξ"
+    token = apply_sign(value, body, signed=signed)
+    return color_by_sign(value, token)
+
+
+def auto(value: float, code: str, *, signed: bool = True) -> str:
+    decimals = get_optimal_decimals(value, code)
+    symbol = get_symbol(code)
+
+    if is_fiat(code) or is_stablecoin(code):
+        body = f"{symbol}{number_plain(abs(value), decimals)}"
+        token = apply_sign(value, body, signed=signed)
+        return color_by_sign(value, token)
+
+    base_body = (
+        f"{number_plain(abs(value), decimals)} {symbol if symbol != code else code}"
+    )
+    token = apply_sign(value, base_body, signed=signed)
+    return color_by_sign(value, token)
+
+
+def bps_to_percent(bps: int) -> float:
+    return bps / 100.0
+
+
+def percent_to_bps(percent: float) -> int:
+    return int(round(percent * 100))
+
+
+__all__ = [
+    "get_symbol",
+    "is_stablecoin",
+    "is_fiat",
+    "is_crypto",
+    "get_optimal_decimals",
+    "usd",
+    "btc",
+    "eth",
+    "auto",
+    "bps_to_percent",
+    "percent_to_bps",
+]

adrian_utils-0.1.1/src/py_utils/format.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import os
+import sys
+from math import isfinite
+from typing import Optional
+
+
+SI_SUFFIXES = [
+    (1_000_000_000_000_000_000, "E"),
+    (1_000_000_000_000_000, "P"),
+    (1_000_000_000_000, "T"),
+    (1_000_000_000, "G"),
+    (1_000_000, "M"),
+    (1_000, "K"),
+]
+
+
+def _detect_color() -> bool:
+    if os.getenv("NO_COLOR"):
+        return False
+    if os.getenv("FORCE_COLOR"):
+        return True
+    try:
+        return sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+_COLOR_ENABLED: bool = _detect_color()
+
+
+def set_color_enabled(enabled: Optional[bool]) -> None:
+    """Override automatic color detection (None resets to auto)."""
+
+    global _COLOR_ENABLED
+    if enabled is None:
+        _COLOR_ENABLED = _detect_color()
+    else:
+        _COLOR_ENABLED = bool(enabled)
+
+
+def color_enabled() -> bool:
+    return _COLOR_ENABLED
+
+
+def _apply_style(text: str, style: str, *, enable_color: Optional[bool] = None) -> str:
+    use_color = _COLOR_ENABLED if enable_color is None else bool(enable_color)
+    if not use_color:
+        return text
+    return f"[{style}]{text}[/]"
+
+
+def _style_by_sign(
+    value: float, text: str, *, enable_color: Optional[bool] = None
+) -> str:
+    if value > 0:
+        return _apply_style(text, "green", enable_color=enable_color)
+    if value < 0:
+        return _apply_style(text, "red", enable_color=enable_color)
+    return _apply_style(text, "grey50", enable_color=enable_color)
+
+
+def color_by_sign(value: float, text: str) -> str:
+    return _style_by_sign(value, text)
+
+
+def apply_sign(value: float, body: str, *, signed: bool = True) -> str:
+    if value < 0:
+        return f"-{body}"
+    if value > 0 and signed:
+        return f"+{body}"
+    return body
+
+
+def number(value: float, decimals: int, *, signed: bool = True) -> str:
+    body = number_plain(abs(value), decimals)
+    text = apply_sign(value, body, signed=signed)
+    return _style_by_sign(value, text)
+
+
+def number_plain(value: float, decimals: int) -> str:
+    return f"{value:.{decimals}f}"
+
+
+def with_commas(value: float, decimals: int | None = None) -> str:
+    if decimals is None:
+        text = f"{value:,}"
+    else:
+        text = f"{value:,.{decimals}f}"
+    return _style_by_sign(value, text)
+
+
+def compact(value: float) -> str:
+    v = float(value)
+    if not isfinite(v) or v == 0:
+        return _apply_style("0", "grey50")
+    abs_v = abs(v)
+    for threshold, suffix in SI_SUFFIXES:
+        if abs_v >= threshold:
+            short = v / threshold
+            text = f"{short:.1f}{suffix}"
+            return _style_by_sign(v, text)
+    text = f"{v:.0f}"
+    return _style_by_sign(v, text)
+
+
+def bytes_fmt(n: int) -> str:
+    if n < 1024:
+        return _style_by_sign(n, f"{n} B")
+    units = ["KiB", "MiB", "GiB", "TiB", "PiB", "EiB"]
+    v = float(n)
+    for unit in units:
+        v /= 1024.0
+        if abs(v) < 1024.0:
+            text = f"{v:.1f} {unit}"
+            return _style_by_sign(n, text)
+    return _style_by_sign(n, f"{v:.1f} ZiB")
+
+
+def duration(ms: float) -> str:
+    if ms >= 10_000:
+        text = f"{ms / 1000:.1f}s"
+    elif ms >= 1000:
+        text = f"{ms / 1000:.2f}s"
+    else:
+        text = f"{ms:.0f}ms"
+    return text
+
+
+def _percentage_decimals(value: float) -> int:
+    av = abs(value)
+    if av < 0.1:
+        return 2
+    if av >= 100:
+        return 0
+    return 1
+
+
+def percentage(value: float, *, signed: bool = True) -> str:
+    d = _percentage_decimals(value)
+    body = f"{abs(value):.{d}f}%"
+    text = apply_sign(value, body, signed=signed)
+    return _style_by_sign(value, text)
+
+
+def percentage_change(old: float, new: float, *, signed: bool = True) -> str:
+    if old == 0:
+        if new == 0:
+            return percentage(0.0, signed=signed)
+        return percentage(100.0 if new > 0 else -100.0, signed=signed)
+    pct = ((new - old) / abs(old)) * 100.0
+    return percentage(pct, signed=signed)
+
+
+def percentage_diff(a: float, b: float, *, signed: bool = True) -> str:
+    if a == 0 and b == 0:
+        return percentage(0.0, signed=signed)
+    avg = (abs(a) + abs(b)) / 2.0
+    if avg == 0:
+        return percentage(0.0, signed=signed)
+    pct = (abs(a - b) / avg) * 100.0
+    return percentage(pct, signed=signed)
+
+
+def bps(basis_points: int) -> str:
+    return f"{basis_points} bps"
+
+
+def sign(value: float) -> str:
+    return "+" if value > 0 else ""
+
+
+__all__ = [
+    "number",
+    "number_plain",
+    "with_commas",
+    "compact",
+    "bytes_fmt",
+    "duration",
+    "percentage",
+    "percentage_change",
+    "percentage_diff",
+    "bps",
+    "sign",
+    "color_by_sign",
+    "apply_sign",
+    "set_color_enabled",
+    "color_enabled",
+]

adrian_utils-0.1.1/src/py_utils/log.py

@@ -0,0 +1,450 @@
+from __future__ import annotations
+
+import os
+import sys
+import time
+import traceback
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from typing import Any, Callable, Optional
+import threading
+
+try:
+    from rich.console import Console
+    from rich.text import Text
+    from rich.theme import Theme
+    from rich.status import Status
+    from rich.markup import MarkupError
+
+    HAVE_RICH = True
+except Exception:  # pragma: no cover - optional dependency
+    HAVE_RICH = False
+    Console = None  # type: ignore
+
+
+# Levels
+_LEVELS = {"trace": 10, "debug": 20, "info": 30, "warn": 40, "error": 50, "fatal": 60}
+
+
+def _env_level() -> str:
+    return os.getenv("LOG_LEVEL", "info").lower()
+
+
+def _isatty() -> bool:
+    try:
+        return sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+@dataclass(slots=True)
+class _Config:
+    level: str = _env_level()
+    color_enabled: bool = (
+        os.getenv("NO_COLOR") is None or os.getenv("FORCE_COLOR") is not None
+    )
+    live_updates: bool = True
+    show_tracebacks: bool = True
+    time_enabled: bool = False
+    symbols_enabled: bool = True
+    indent_width: int = 2
+
+
+_DEFAULT_THEME = Theme(
+    {
+        "info": "bold blue",
+        "warn": "bold yellow",
+        "error": "bold red",
+        "success": "bold green",
+        "ready": "bold green",
+        "wait": "bright_white",
+        "trace": "magenta",
+        "dim": "dim",
+    }
+)
+
+
+class _State(threading.local):
+    def __init__(self) -> None:
+        super().__init__()
+        self.indent: int = 0
+        self.warn_once_keys: set[str] = set()
+        self.timers: dict[str, float] = {}
+
+
+class Logger:
+    """TTY-focused logger with tasks, steps, and indentation.
+
+    This logger writes to stdout. When attached to a terminal (TTY), it uses
+    colors and symbols (via Rich if installed). When not attached to a TTY,
+    it prints plain text and avoids live updates.
+    """
+
+    def __init__(
+        self, *, prefix: str | None = None, tags: tuple[str, ...] = ()
+    ) -> None:
+        self._cfg = _Config()
+        self._state = _State()
+        self._prefix = prefix
+        self._tags = tags
+
+        if HAVE_RICH:
+            self._console = Console(theme=_DEFAULT_THEME)
+        else:
+            self._console = None
+
+        self._sync_format_color()
+
+    # ----- configuration -----
+    def set_level(self, level: str) -> None:
+        self._cfg.level = level.lower()
+
+    def get_level(self) -> str:
+        return self._cfg.level
+
+    def enable_color(self, enabled: bool) -> None:
+        self._cfg.color_enabled = enabled
+        self._sync_format_color()
+
+    def enable_live_updates(self, enabled: bool) -> None:
+        self._cfg.live_updates = enabled
+
+    def set_time_enabled(self, enabled: bool) -> None:
+        self._cfg.time_enabled = enabled
+
+    def set_show_tracebacks(self, enabled: bool) -> None:
+        self._cfg.show_tracebacks = enabled
+
+    def set_symbols(self, enabled: bool) -> None:
+        self._cfg.symbols_enabled = enabled
+
+    # ----- derived props -----
+    @property
+    def _active_console(self) -> Optional[Console]:
+        return self._console if (HAVE_RICH and self._cfg.color_enabled) else None
+
+    @property
+    def _is_tty(self) -> bool:
+        if self._active_console is not None:
+            try:
+                return self._active_console.is_terminal
+            except Exception:
+                pass
+        return _isatty()
+
+    def _should_log(self, level: str) -> bool:
+        return _LEVELS[level] >= _LEVELS.get(self._cfg.level, 30)
+
+    # ----- helpers -----
+    def _indent_str(self) -> str:
+        return " " * (self._state.indent * self._cfg.indent_width)
+
+    def _prefix_text(self) -> str:
+        parts = []
+        if self._prefix:
+            parts.append(self._prefix)
+        if self._tags:
+            parts.extend(self._tags)
+        if not parts:
+            return ""
+        return f"[{' '.join(parts)}] "
+
+    def _symbol(self, kind: str) -> str:
+        if not self._cfg.symbols_enabled:
+            return ""
+        return {
+            "info": "ℹ",
+            "warn": "⚠",
+            "error": "⨯",
+            "fatal": "⨯",
+            "success": "✓",
+            "fail": "⨯",
+            "wait": "○",
+            "ready": "▶",
+            "trace": "»",
+            "step": "•",
+            "section": "▸",
+        }.get(kind, "")
+
+    def _color_active(self) -> bool:
+        return self._cfg.color_enabled and self._is_tty
+
+    def _sync_format_color(self) -> None:
+        try:
+            from . import format as _format
+
+            _format.set_color_enabled(self._color_active())
+        except Exception:
+            pass
+
+    def _coerce_text(self, message: Any) -> Text:
+        if isinstance(message, Text):
+            return message
+        msg_str = str(message)
+        try:
+            return Text.from_markup(msg_str, emoji=False)
+        except (MarkupError, ValueError):
+            return Text(msg_str)
+
+    def _write_line(self, kind: str, message: Any) -> None:
+        prefix = self._prefix_text()
+        indent = self._indent_str()
+        sym = self._symbol(kind)
+
+        if self._active_console and self._is_tty:
+            style = {
+                "info": "info",
+                "warn": "warn",
+                "error": "error",
+                "fatal": "error",
+                "success": "success",
+                "fail": "error",
+                "wait": "wait",
+                "ready": "ready",
+                "trace": "trace",
+                "step": "dim",
+                "section": "dim",
+            }.get(kind, "info")
+
+            pieces: list[Text] = []
+            if indent:
+                pieces.append(Text(indent))
+            if prefix:
+                pieces.append(Text(prefix, style="dim"))
+            if sym:
+                pieces.append(Text(f"{sym} ", style=style))
+            pieces.append(self._coerce_text(message))
+            self._active_console.print(Text.assemble(*pieces))
+        else:
+            # Plain text fallback
+            plain = str(message)
+            if HAVE_RICH:
+                try:
+                    plain = Text.from_markup(plain, emoji=False).plain
+                except (MarkupError, ValueError):
+                    plain = str(message)
+            base = f"{prefix}{(sym + ' ') if sym else ''}{plain}"
+            sys.stdout.write(indent + base + "\n")
+            sys.stdout.flush()
+
+    # ----- public logging -----
+    def trace(self, message: str) -> None:
+        if self._should_log("trace"):
+            self._write_line("trace", message)
+
+    def debug(self, message: str) -> None:
+        if self._should_log("debug"):
+            self._write_line("trace", message)  # use trace style for visual distinction
+
+    def info(self, message: str) -> None:
+        if self._should_log("info"):
+            self._write_line("info", message)
+
+    def warn(self, message: str) -> None:
+        if self._should_log("warn"):
+            self._write_line("warn", message)
+
+    def warn_once(self, message: str) -> None:
+        key = message
+        if key in self._state.warn_once_keys:
+            return
+        self._state.warn_once_keys.add(key)
+        self.warn(message)
+
+    def error(self, msg_or_exc: Any, *, exc: bool | None = None) -> None:
+        if not self._should_log("error"):
+            return
+        message = str(msg_or_exc)
+        self._write_line("error", message)
+        want_tb = exc or isinstance(msg_or_exc, BaseException)
+        if want_tb and self._cfg.show_tracebacks:
+            tb = traceback.format_exc()
+            for line in tb.strip().splitlines():
+                self._with_extra_indent(lambda: self._write_line("step", line))
+
+    def fatal(
+        self, msg_or_exc: Any, *, exit_code: int = 1, exc: bool | None = None
+    ) -> None:
+        self.error(msg_or_exc, exc=exc)
+        try:
+            sys.exit(exit_code)
+        except SystemExit:
+            raise
+
+    def success(self, message: str) -> None:
+        if self._should_log("info"):
+            self._write_line("success", message)
+
+    def fail(self, message: str) -> None:
+        if self._should_log("error"):
+            self._write_line("fail", message)
+
+    def event(self, message: str) -> None:
+        if self._should_log("info"):
+            self._write_line("info", message)
+
+    def wait(self, message: str) -> None:
+        if self._should_log("info"):
+            self._write_line("wait", message)
+
+    def ready(self, message: str) -> None:
+        if self._should_log("info"):
+            self._write_line("ready", message)
+
+    # ----- indentation & grouping -----
+    @contextmanager
+    def _with_extra_indent(self, fn: Optional[Callable[[], None]] = None):
+        self._state.indent += 1
+        try:
+            if fn is not None:
+                fn()
+            else:
+                yield
+        finally:
+            self._state.indent -= 1
+
+    def step(self, message: str) -> None:
+        self._with_extra_indent(lambda: self._write_line("step", message))
+
+    @contextmanager
+    def section(self, title: str):
+        self._write_line("section", title)
+        with self._with_extra_indent():
+            yield
+
+    @contextmanager
+    def task(self, title: str):
+        start = time.perf_counter()
+        self._write_line("wait", title)
+        self._state.indent += 1
+        failed = False
+        try:
+            yield
+        except BaseException:
+            failed = True
+            raise
+        finally:
+            self._state.indent -= 1
+            dur_ms = (time.perf_counter() - start) * 1000.0
+            from .format import duration as _dur
+
+            if failed:
+                self._write_line("fail", f"{title} ({_dur(dur_ms)})")
+                if self._cfg.show_tracebacks:
+                    tb = traceback.format_exc()
+                    for line in tb.strip().splitlines():
+                        self._with_extra_indent(lambda: self._write_line("step", line))
+            else:
+                self._write_line("success", f"{title} ({_dur(dur_ms)})")
+
+    def step_run(self, title: str, fn: Callable[..., Any], *args, **kwargs) -> Any:
+        with self.task(title):
+            return fn(*args, **kwargs)
+
+    # ----- timers -----
+    def time(self, label: str) -> None:
+        self._state.timers[label] = time.perf_counter()
+
+    def time_end(self, label: str, *, level: str = "trace") -> float:
+        start = self._state.timers.pop(label, None)
+        if start is None:
+            self.warn(f"Timer '{label}' does not exist")
+            return 0.0
+        ms = (time.perf_counter() - start) * 1000.0
+        from .format import duration as _dur
+
+        if self._should_log(level):
+            self._write_line("trace", f"{label}: {_dur(ms)}")
+        return ms
+
+    # ----- progress -----
+    class _Progress:
+        def __init__(
+            self, logger: "Logger", total: int | None, title: str | None
+        ) -> None:
+            self.logger = logger
+            self.total = total
+            self.title = title or ""
+            self.count = 0
+            self._start = time.perf_counter()
+            self._status: Optional[Status] = None
+
+            if (
+                HAVE_RICH
+                and logger._active_console is not None
+                and logger._is_tty
+                and logger._cfg.live_updates
+            ):
+                msg = (
+                    logger._indent_str()
+                    + (logger._prefix_text() or "")
+                    + f"{self.title}…"
+                )
+                self._status = logger._active_console.status(msg, spinner="dots")
+                self._status.start()
+
+        def tick(self) -> None:
+            self.update(1)
+
+        def update(self, n: int = 1) -> None:
+            self.count += n
+            if self._status is not None:
+                suffix = (
+                    f" {self.count}/{self.total}"
+                    if self.total is not None
+                    else f" {self.count}"
+                )
+                msg = (
+                    self.logger._indent_str()
+                    + (self.logger._prefix_text() or "")
+                    + f"{self.title}{suffix}…"
+                )
+                self._status.update(msg)
+
+        def done(self, *, success: bool = True) -> None:
+            if self._status is not None:
+                self._status.stop()
+            dur_ms = (time.perf_counter() - self._start) * 1000.0
+            from .format import duration as _dur
+
+            suffix = (
+                f" ({self.count}/{self.total}, {_dur(dur_ms)})"
+                if self.total is not None
+                else f" ({self.count}, {_dur(dur_ms)})"
+            )
+            line = (
+                f"{self.title}{suffix}"
+                if self.title
+                else (
+                    f"{self.count}/{self.total} ({_dur(dur_ms)})"
+                    if self.total is not None
+                    else f"{self.count} ({_dur(dur_ms)})"
+                )
+            )
+            if success:
+                self.logger._write_line("success", line)
+            else:
+                self.logger._write_line("fail", line)
+
+    def progress(
+        self, total: int | None = None, title: str | None = None
+    ) -> "Logger._Progress":
+        return Logger._Progress(self, total, title)
+
+    # ----- context binding -----
+    def with_prefix(self, text: str) -> "Logger":
+        return self._child(prefix=text, tags=self._tags)
+
+    def tag(self, *tags: str) -> "Logger":
+        return self._child(prefix=self._prefix, tags=self._tags + tuple(tags))
+
+    def _child(self, *, prefix: str | None, tags: tuple[str, ...]) -> "Logger":
+        child = Logger(prefix=prefix, tags=tags)
+        child._cfg = replace(self._cfg)
+        child._state = self._state  # share indent, timers, warn_once within thread
+        child._console = self._console
+        return child
+
+
+# Global logger instance
+log = Logger()

adrian_utils-0.1.1/src/py_utils/xdg.py

@@ -0,0 +1,85 @@
+"""XDG Base Directory Specification.
+
+Exposes XDG base directories respecting environment variables.
+https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+
+Usage:
+    from py_utils import xdg
+
+    config_file = xdg.config / "myapp" / "config.toml"
+    data_file = xdg.data / "myapp" / "data.db"
+
+TODO: Consider fallbacks if env vars not set
+    - Option 1: Use platformdirs dependency
+    - Option 2: Bespoke cross-platform implementation to avoid extra dep
+    Current: Fails if env vars not set (offensive programming)
+"""
+
+import os
+from pathlib import Path
+
+
+class _XDG:
+    """XDG base directory paths."""
+
+    @property
+    def config(self) -> Path:
+        """XDG_CONFIG_HOME - User-specific configuration files.
+
+        Raises:
+            RuntimeError: If XDG_CONFIG_HOME is not set
+        """
+        env_path = os.getenv("XDG_CONFIG_HOME")
+        assert env_path, "XDG_CONFIG_HOME not set"
+        return Path(env_path)
+
+    @property
+    def data(self) -> Path:
+        """XDG_DATA_HOME - User-specific data files.
+
+        Raises:
+            RuntimeError: If XDG_DATA_HOME is not set
+        """
+        env_path = os.getenv("XDG_DATA_HOME")
+        assert env_path, "XDG_DATA_HOME not set"
+        return Path(env_path)
+
+    @property
+    def cache(self) -> Path:
+        """XDG_CACHE_HOME - User-specific non-essential cached data.
+
+        Raises:
+            RuntimeError: If XDG_CACHE_HOME is not set
+        """
+        env_path = os.getenv("XDG_CACHE_HOME")
+        assert env_path, "XDG_CACHE_HOME not set"
+        return Path(env_path)
+
+    @property
+    def state(self) -> Path:
+        """XDG_STATE_HOME - User-specific state files.
+
+        Raises:
+            RuntimeError: If XDG_STATE_HOME is not set
+        """
+        env_path = os.getenv("XDG_STATE_HOME")
+        assert env_path, "XDG_STATE_HOME not set"
+        return Path(env_path)
+
+    @property
+    def runtime(self) -> Path:
+        """XDG_RUNTIME_DIR - User-specific runtime files.
+
+        Raises:
+            RuntimeError: If XDG_RUNTIME_DIR is not set
+        """
+        env_path = os.getenv("XDG_RUNTIME_DIR")
+        assert env_path, "XDG_RUNTIME_DIR not set"
+        return Path(env_path)
+
+
+# Module-level instance for clean imports
+# Usage: from py_utils import xdg; xdg.config
+xdg = _XDG()
+
+__all__ = ["xdg"]