klogr 0.1.3__tar.gz

klogr-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+---
+name: Publish to PyPI
+
+on:
+    push:
+        tags:
+            - v*
+
+jobs:
+    build-and-publish:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Check out the code
+              uses: actions/checkout@v4
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: "3.12"
+
+            - name: Install dependencies
+              run: |
+                  python -m pip install --upgrade pip setuptools wheel build twine
+
+            - name: Build the package
+              run: python -m build
+
+            - name: Show wheel metadata (debug)
+              run: |
+                  python -m twine check dist/*
+                  for f in dist/*.whl; do
+                    echo "===== $f ====="
+                    python -c "import zipfile, sys; zf = zipfile.ZipFile(sys.argv[1]); [print(zf.read(n).decode()) for n in zf.namelist() if n.endswith('METADATA')]" "$f"
+                  done
+
+            - name: Publish to PyPI
+              env:
+                  TWINE_USERNAME: __token__
+                  TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+              run: python -m twine upload --verbose --non-interactive dist/*

klogr-0.1.3/.gitignore

@@ -0,0 +1,30 @@
+
+# Pretrained Torch
+pretrained_models/
+
+# PyCache
+__pycache__
+
+# VSCode
+*.code-workspace
+
+# Small Data/Videos
+small_data/
+data/
+*.zip
+
+# Outputs
+outputs/
+logs/
+log/
+.DS_Store
+
+# builds
+build/
+dist/
+.venv/
+*.tar.gz
+*.tar
+
+# Lock file — managed by uv, regenerated per-environment
+uv.lock

klogr-0.1.3/.pre-commit-config.yaml

@@ -0,0 +1,235 @@
+---
+# $ pre-commit install --install-hooks
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+default_install_hook_types:
+    - pre-commit
+    - post-checkout
+    - post-merge
+    - post-rewrite
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v5.0.0
+      hooks:
+          - id: trailing-whitespace
+
+          - id: end-of-file-fixer
+
+          - id: mixed-line-ending
+            args: [--fix, lf]
+
+          - id: check-yaml
+            exclude: .pre-commit-config.yaml
+
+          - id: check-added-large-files
+            args: [--maxkb=2000]
+
+          - id: check-merge-conflict
+          - id: check-case-conflict
+          - id: check-json
+          - id: check-toml
+            exclude: uv\.lock
+          - id: pretty-format-json
+            args: [--autofix, --no-ensure-ascii, --no-sort-keys]
+
+          # - id: double-quote-string-fixer
+          #   exclude: ^dependencies/|^experiments/dependencies/|^experiments/
+
+    # - repo: https://github.com/psf/black-pre-commit-mirror
+    #   rev: 24.10.0
+    #   hooks:
+    #       - id: black
+    #       # It is recommended to specify the latest version of Python
+    #       # supported by your project here, or alternatively use
+    #       # pre-commit's default_language_version, see
+    #       # https://pre-commit.com/#top_level-default_language_version
+    #         language_version: python3.10
+    #         exclude: ^dependencies/|^experiments/dependencies/|^experiments/|uv\.lock|tools/generative/pipelines/|configs/hax_ml/|unittest_logs/
+    #         args: [--line-length=79, --target-version=py310, --quiet]
+
+    # - repo: https://github.com/PyCQA/docformatter # there is an issue with the latest version and python_env - uncomment as soon as possible
+    #   rev: v1.3.1
+    #   hooks:
+    #       - id: docformatter
+    #         language: python
+    #         exclude: ^dependencies/|^experiments/dependencies/|^experiments/|uv\.lock|tools/generative/pipelines/|configs/hax_ml/|unittest_logs/
+    #         args: [--in-place, --wrap-descriptions, '120']
+
+    - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
+      rev: 0.2.3 # or other specific tag
+      hooks:
+          - id: yamlfmt
+            exclude: .pre-commit-config.yaml
+
+
+    # - repo: https://github.com/asottile/pyupgrade
+    #   rev: v3.3.1
+    #   hooks:
+    #       - id: pyupgrade
+    #         args:
+    #             # - --py36-plus
+    #             # - --py37-plus
+    #             # - --py38-plus
+    #             - --py39-plus
+    #         #     # - --py311-plus
+    #         exclude: ^dependencies/|^dependencies/|^experiments/dependencies/|^experiments/
+
+    - repo: https://github.com/lovesegfault/beautysh
+      rev: v6.2.1
+      hooks:
+          - id: beautysh
+            exclude: uv\.lock
+
+
+
+    # - repo: https://github.com/pycqa/isort
+    #   rev: 5.11.2
+    #   hooks:
+    #       - id: isort
+    #         name: isort
+    #         entry: isort
+    #         language: python
+    #         types: [python]
+    #         exclude: ^^dependencies/|^experiments/|^cli/
+    #         args: [--line-length=89, --multi-line=3, --force-grid-wrap=0, --trailing-comma, --use-parentheses, --ensure-newline-before-comments]
+    #         # additional_dependencies: [isort>=5.12.0]
+
+    - repo: local
+      hooks:
+          - id: toml-sort-fix
+            name: toml-sort-fix
+            entry: toml-sort
+            args: [--in-place]
+            language: python
+            exclude: uv\.lock
+            types: [toml]
+            additional_dependencies: [toml-sort>=0.23.1]
+
+          - id: toml-sort
+            name: toml-sort
+            entry: toml-sort
+            args: [--check]
+            language: python
+            exclude: uv\.lock
+            types: [toml]
+            additional_dependencies: [toml-sort>=0.23.1]
+
+    - repo: https://github.com/pycqa/pylint
+      rev: v3.3.7
+      hooks:
+          - id: pylint
+            name: pylint
+            entry: pylint
+            language: system
+            types: [python]
+            exclude: uv\.lock
+            args: [
+              --disable=all, # disable all rules
+              --enable=E0401, # import-error
+              --enable=E1123, # unexpected-keyword-arg
+              --enable=E1125, # missing-kwoa
+              --enable=E1101, # no-member
+            ]
+            stages: [manual]
+          # ruff is trying to include more of this: https://github.com/astral-sh/ruff/issues/970
+
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      # Ruff version.
+      rev: v0.12.7
+      hooks:
+        # Run the linter.
+          - id: ruff
+            args: [
+              --fix,
+              --unsafe-fixes,
+              --select,
+              ALL,
+              --ignore, C901, # class too complex # TODO: remove this at some point
+              --ignore, D203, # 1 blank line required before class docstring
+              --ignore, D211, # No blank lines allowed before class docstring
+              --ignore, D213, # Multi-line docstring summary should start at the second line
+              --ignore, F722, # jaxtyping annotations
+              --ignore, F821, # jaxtyping annotations with the name in strings
+              --ignore, E501, # Line too long ( > 79 characters)
+              --ignore, T201, # Checks for print statements and remove them
+              --ignore, COM812, # Missing trailing comma in a dictionary
+              --ignore, ISC001, # Checks for implicitly concatenated strings on a single line.
+              --ignore, G004, # Logging statement uses f-string
+              --ignore, ERA001, # Found commented-out code
+              --ignore, S607, # Starting a process with a partial executable path
+              --ignore, S603, # `subprocess` call: check for execution of untrusted input
+              --ignore, ANN401, # Dynamically typed expressions (typing.Any) are disallowed in `**kwargs`
+              --ignore, RUF012, # Mutable class attributes should be annotated with `typing.ClassVar
+              --ignore, PERF401, # Use a list comprehension to create a transformed list
+              --ignore, SIM115, # Use a context manager for opening files
+              --ignore, PERF203, # `try`-`except` within a loop incurs performance overhead
+              --ignore, PLW2901, # `for` loop variable overwritten by assignment target
+              --ignore, TCH010, # Invalid string member in `X | Y`-style union type
+              --ignore, N812, # Lowercase `functional` imported as non-lowercase `F`
+              --ignore, SLF001, # Private member accessed
+              --ignore, TRY301, # Abstract `raise` to an inner function
+              --ignore, NPY002, # Replace legacy `np.random.random` call with `np.random.Generator`
+              --ignore, TD003, # Missing issue link on the line following a TODO
+              --ignore, FIX002, # Line contains TODO, consider resolving the issue
+              --ignore, S311, # Standard pseudo-random generators are not suitable for cryptographic purposes
+              --ignore, TC006, # Add quotes to type expression in `typing.cast()`
+              --ignore, TRY401, # Redundant exception object included in `logging.exception` call
+              --ignore, BLE001, # Do not catch blind exception: `Exception`'
+              --ignore, PLR0911, # Too many return statements
+              --ignore, PLR0912, # Too many branches
+              --ignore, PLR0913, # Too many arguments in function definition
+              --ignore, PLR0915, # Too many statements
+              --ignore, PLR2004, # Magic value used in comparison, consider replacing `0.1` with a constant variable
+              --ignore, PLC0415, # `import` should be at the top-level of a file
+              --ignore, PT028, # Test function parameter `<>` has default argument
+            ]
+            exclude: uv\.lock
+        # Run the formatter.
+          - id: ruff-format
+            exclude: uv\.lock
+    # - repo: https://github.com/jvllmr/poetry-types
+    #   rev: v0.4.0
+    #   hooks:
+    #       - id: poetry-types
+
+    - repo: https://github.com/pre-commit/mirrors-mypy
+      rev: v1.18.2
+      hooks:
+          - id: mypy
+            name: mypy
+            entry: mypy
+            language: python
+            types_or: [python, pyi]
+            exclude: uv\.lock
+            require_serial: true
+            # args: [--strict, --ignore-missing-imports]
+            args: [--ignore-missing-imports, --scripts-are-modules, --install-types, --non-interactive, --warn-unused-ignores, --show-error-codes, --check-untyped-defs,
+                --disallow-incomplete-defs, --explicit-package-bases, --warn-redundant-casts, --strict-equality, --strict-equality-for-none, --follow-untyped-imports]
+            additional_dependencies:
+                - pydantic
+                - types-requests
+            # mypy --install-types
+
+
+    - repo: https://github.com/astral-sh/uv-pre-commit
+      # uv version.
+      rev: 0.8.3
+      hooks:
+          - id: uv-sync
+            stages: [pre-commit, pre-merge-commit, pre-push] # not run during manual. manual is run in Github, and this one is expensive
+          - id: uv-export
+            args: [--frozen, --output-file=requirements.txt, --no-hashes]
+            stages: [pre-commit, pre-merge-commit, pre-push]
+
+
+    # - repo: https://github.com/oxsecurity/megalinter # sudo apt install npm && sudo npm install mega-linter-runner -g
+    # # install docker https://docs.docker.com/engine/install/ubuntu/#set-up-the-repository
+    # # install with sudo once: sudo mega-linter-runner .
+    #   rev: v6.8.0 # Git tag specifying the hook, not mega-linter-runner, version
+    #   hooks:
+    #       - id: megalinter-incremental # Faster, less thorough
+    #         stages:
+    #             - commit
+    #       - id: megalinter-full # Slower, more thorough
+    #         stages:
+    #             - push

klogr-0.1.3/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to klogr are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.3] — 2026-05-17
+
+PyPI rejected the name `klog` with `400 The name 'klog' isn't allowed.`
+(likely too close to existing Linux/Go-ecosystem names). Renamed to
+`klogr` — same project, one letter different.
+
+### Changed
+
+- Package renamed `klog` → `klogr`. GitHub repo also renamed from
+  `affromero/klog` to `affromero/klogr`. Imports change accordingly:
+  `from klog import X` → `from klogr import X`.
+- README install instructions, badges, and layout diagram updated for
+  the new name.
+
+### Fixed
+
+- README incorrectly claimed `get_cache_dir()` returns `~/.cache/klog`;
+  it actually returns the XDG cache root directly. Updated the comment.
+
+## [0.1.2] — 2026-05-15
+
+CI/workflow fixes after 0.1.1 also failed PyPI upload with the same
+`400 Bad Request`. Local wheels build cleanly with the SPDX license
+metadata — the failure is somewhere in the upload step. This release
+adds `twine check` and `twine upload --verbose` to surface the actual
+error.
+
+### Fixed
+
+- `.github/workflows/publish.yml`: bump `actions/checkout` to v4,
+  `actions/setup-python` to v5, pin Python to 3.12 (3.x picked 3.14
+  which prints deprecation noise).
+- Add `twine check` and METADATA dump steps so we can see what's in
+  the wheel before upload.
+- `twine upload --verbose --non-interactive` for actionable errors
+  when the upload step itself fails.
+
+## [0.1.1] — 2026-05-15
+
+First successful PyPI upload. Fixes the 0.1.0 build that PyPI rejected
+with `400 Bad Request`.
+
+### Fixed
+
+- `pyproject.toml` `license` field uses the SPDX expression
+  (`license = "MIT"` + `license-files = ["LICENSE.md"]`) instead of the
+  legacy `{text = "MIT"}` form that newer PyPI rejects.
+- Drop redundant `License :: OSI Approved :: MIT License` classifier
+  (the SPDX expression replaces it; PyPI rejects both together).
+- Project URLs in `pyproject.toml` corrected from `github.com/afromero/...`
+  to `github.com/affromero/...` (the actual GitHub handle).
+- README ASCII diagram rewritten with ASCII-safe box characters
+  (`+--+`, `-->`) instead of Unicode box-drawing + `▶`. The previous
+  version rendered crooked in Markdown viewers that gave `▶` a wider
+  glyph than expected.
+
+## [0.1.0] — 2026-05-15
+
+First release under the new name `klogr`. Previously published as `difflogtest`.
+
+### Changed
+
+- **Renamed package** from `difflogtest` to `klogr`. The old name described a snapshot-test framework that is no longer part of this package.
+- **Flattened the module layout.** The old `difflogtest.logging.*` and `difflogtest.utils.*` sub-packages have been merged into top-level modules:
+  - `difflogtest.logging.core` → `klogr.logger`
+  - `difflogtest.logging.cache_tools` → `klogr.cache`
+  - `difflogtest.utils.strings` → `klogr.time`
+  - `difflogtest.utils.path` → `klogr.path/` (split into `ops`, `io`, `query`, `env`)
+- `logger.info_json` now uses stdlib `json` instead of `json5` — Pydantic-emitted JSON doesn't need comment tolerance.
+
+### Removed
+
+- **Snapshot test framework** (`UnitTests`, `@register_unittest`, `LogReplacement`, `is_unittest_mode`, `run-unittests` CLI). Not maintained; rely on `pytest` directly.
+- **`seed_everything`** — pixelcache ships its own; this one only existed for the snapshot framework.
+- **`wait_seconds_bar`** — zero consumers.
+- **`path_download_and_extract_tar`** — drops the `wget` dependency.
+- **`is_file_changed`, `logfile_from_func`, `path_from_pattern`, `keep_local_data`** — snapshot-only path helpers.
+
+### Dropped dependencies
+
+- `tyro` (snapshot CLI)
+- `pytz` (unused)
+- `json5` (info_json rewritten to stdlib json)
+- `torch`, `torchvision` (seed_everything was the only consumer)
+- `wget` (download helper removed)
+- `GitPython` (`is_file_changed` was the only consumer)
+
+### Kept
+
+- `get_logger`, `LoggingRich`, `LoggingTable`, `DEFAULT_VERBOSITY`
+- `lru_cache`, `DisableableLRUCache`, `get_cache_dir`, `sha256sum`
+- All path helpers consumed by Hax-CV (`path_join`, `path_exists`, `path_mkdir`, `path_open`, `path_glob`, `path_basename`, `path_dirname`, `path_stem`, `path_is_s3`, `path_absolute`, `path_abs`, `path_dotenv`, `path_home`, `path_expanduser`, `path_relative_to`, `path_resolve`, `path_replace_suffix`, `path_rstrip`, `path_write_text`, `path_read_text`, `path_listdir`, `path_remove`, `path_remove_dir`, `path_copy`, `path_copy_dir`, `path_move`, `path_rename`, `path_symlink`, `path_islink`, `path_lexists`, `path_is_dir`, `path_is_file`, `path_is_image_file`, `path_is_video_file`, `path_getmtime`, `path_stat`, `path_dir_empty`, `path_exists_and_not_empty`, `path_startswith`, `path_endswith`, `path_newest_dir`, `path_newest_file`, `path_rglob`, `path_s3_bucket_name`, `is_glob_pattern`, `expand_glob_to_temp_dir`)
+- `get_elapsed_time`
+
+### Migration
+
+Replace every `from difflogtest...` import:
+
+| Old | New |
+|-----|-----|
+| `from difflogtest import get_logger` | `from klogr import get_logger` |
+| `from difflogtest import lru_cache, sha256sum` | `from klogr import lru_cache, sha256sum` |
+| `from difflogtest.utils.path import path_X` | `from klogr.path import path_X` |
+| `from difflogtest.logging.core import LoggingTable` | `from klogr import LoggingTable` |
+
+If you depended on `@register_unittest`, `is_unittest_mode`, or `LogReplacement` — those are gone. Use `pytest` directly.

klogr-0.1.3/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: klogr
+Version: 0.1.3
+Summary: Batteries-included structured logger for Python data/ML projects, built on Rich.
+Project-URL: Changelog, https://github.com/affromero/klogr/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/affromero/klogr
+Project-URL: Issues, https://github.com/affromero/klogr/issues
+Author-email: Andres Romero <me@afromero.co>
+License-Expression: MIT
+Keywords: cache,logging,ml,path,rich,s3
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: beartype>=0.21.0
+Requires-Dist: jaxtyping>=0.3.2
+Requires-Dist: natsort>=8.4.0
+Requires-Dist: pydantic>=2.10.2
+Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: rich>=13.9.4
+Requires-Dist: sha256sum>=2024.4.26
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# klogr
+
+**Batteries-included structured logger for Python data/ML projects — built on [Rich](https://github.com/Textualize/rich).**
+
+[![PyPI](https://img.shields.io/pypi/v/klogr)](https://pypi.org/project/klogr/)
+[![Downloads](https://img.shields.io/pypi/dm/klogr)](https://pypi.org/project/klogr/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)](https://pypi.org/project/klogr/)
+[![Publish](https://img.shields.io/github/actions/workflow/status/affromero/klogr/publish.yml?label=publish)](https://github.com/affromero/klogr/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/github/license/affromero/klogr)](https://github.com/affromero/klogr/blob/main/LICENSE.md)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-261230?logo=ruff)](https://github.com/astral-sh/ruff)
+[![mypy](https://img.shields.io/badge/typing-mypy%20strict-blue)](http://mypy-lang.org/)
+[![jaxtyping](https://img.shields.io/badge/shapes-jaxtyping-orange)](https://github.com/patrick-kidger/jaxtyping)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/affromero/klogr/pulls)
+
+</div>
+
+```text
+  get_logger()
+       |
+       v
+  +---------------------------+
+  |        LoggingRich        |
+  +---------------------------+
+  | .info  .success  .warning |  -->  Rich-formatted console
+  | .error .debug    .rule    |       with auto file:line prefix
+  | .track .print    .info_json|
+  +---------------------------+
+
+  plus, from the same package:
+
+    @lru_cache  +  DisableableLRUCache  -->  cached calls,
+                                             with a disable hook for tests
+    path_join / path_exists / path_open      -->  local + s3:// transparent
+    get_elapsed_time(seconds)                -->  "01d : 01h : 12m : 03s"
+    sha256sum(path) / get_cache_dir()        -->  stable on-disk caching
+```
+
+`klogr` is what you reach for when stdlib `logging.basicConfig` doesn't cut it and `print()` feels gross. It wraps Python's `logging` module with `rich.logging.RichHandler` pre-configured, adds stacklevel awareness so every line shows where it came from, and ships a handful of helpers (caching, paths, timing) that show up in every ML/data project.
+
+## Why use it
+
+- **Drop-in `get_logger()`** — module-scoped, cached, zero setup. No `logging.basicConfig`, no handler wiring.
+- **Stacklevel-aware** — every log line auto-prefixes with the caller's `file:line`. Stop hunting for which module shouted what.
+- **`logger.track()`** — wraps `rich.progress.track()` and works inside `ThreadPoolExecutor` / `ProcessPoolExecutor` without going silent.
+- **`logger.print()` / `logger.info_json()`** — pretty-print Pydantic models, dicts, JSON without piping through `print(json.dumps(..., indent=2))`.
+- **`@lru_cache` with a disable hook** — flip an env var to bypass caching globally (handy for tests).
+- **Path helpers that handle S3** — `path_join`, `path_exists`, `path_mkdir`, etc. work whether you pass `/tmp/foo` or `s3://bucket/foo`.
+- **`get_elapsed_time(seconds)`** — formats float seconds as `00d : 01h : 12m : 03s`.
+
+## Install
+
+```bash
+uv add klogr
+# or
+pip install klogr
+```
+
+Requires Python ≥ 3.10. Runtime deps: `rich`, `pydantic`, `python-dotenv`, `beartype`, `jaxtyping`, `natsort`, `sha256sum`.
+
+## Quickstart
+
+```python
+from klogr import get_logger
+
+logger = get_logger()
+
+logger.info("loaded %d samples", 1024)         # auto file:line prefix
+logger.success("training converged")            # green check
+logger.warning("validation loss plateaued")
+logger.error("OOM on batch 42")
+
+# Pretty-print structured data
+logger.print({"epoch": 12, "lr": 3e-4, "loss": 0.21})
+
+# Progress bar that works in parallel
+from concurrent.futures import ThreadPoolExecutor
+with ThreadPoolExecutor(max_workers=8) as pool:
+    for result in logger.track(pool.map(process, items), total=len(items), description="batch"):
+        ...
+```
+
+## What's in the box
+
+### Logger
+
+```python
+from klogr import get_logger, LoggingRich, DEFAULT_VERBOSITY
+
+logger = get_logger()                            # default verbosity
+quiet  = get_logger({"info": False, "debug": False})  # custom
+
+logger.info(msg)            # cyan
+logger.success(msg)         # green check
+logger.warning(msg)         # yellow
+logger.error(msg)           # red
+logger.rule(title)          # horizontal divider
+logger.print(any_object)    # rich.print, soft-wrap aware
+logger.info_json(json_str)  # syntax-colored JSON
+logger.track(iter, total, description)  # progress bar
+```
+
+### Caching
+
+```python
+from klogr import lru_cache, DisableableLRUCache, get_cache_dir, sha256sum
+
+@lru_cache(maxsize=128)
+def expensive(key: str) -> bytes:
+    ...
+
+# Stable on-disk paths
+cache_root = get_cache_dir()                          # XDG cache root
+digest     = sha256sum("/path/to/file.bin")           # hex string
+```
+
+### Path helpers (local + S3 transparent)
+
+```python
+from klogr.path import (
+    path_join, path_exists, path_mkdir, path_dirname,
+    path_basename, path_glob, path_is_s3, path_open,
+)
+
+path_exists("/tmp/local.bin")       # True/False
+path_exists("s3://bucket/key.bin")  # True/False (same call)
+path_mkdir("/tmp/nested/dir", parents=True, exist_ok=True)
+for p in path_glob("/data/*.jpg"):
+    with path_open(p, "rb") as f:
+        ...
+```
+
+### Timing
+
+```python
+from klogr import get_elapsed_time
+
+print(get_elapsed_time(86400 + 3661))   # '01d : 01h : 01m : 01s'
+```
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples/):
+
+- [`01_basic_logger.py`](examples/01_basic_logger.py) — log levels, formatting, file:line prefix
+- [`02_pretty_tables.py`](examples/02_pretty_tables.py) — `LoggingTable` for tabular console output
+- [`03_progress_tracking.py`](examples/03_progress_tracking.py) — `logger.track()` in parallel workers
+- [`04_caching.py`](examples/04_caching.py) — `@lru_cache` with disable-hook
+- [`05_path_helpers.py`](examples/05_path_helpers.py) — local + S3 path ops
+
+```bash
+uv run examples/01_basic_logger.py
+```
+
+## Layout
+
+```
+klogr/
+├── __init__.py     # public re-exports
+├── logger.py       # LoggingRich, LoggingTable, get_logger
+├── cache.py        # lru_cache, DisableableLRUCache, sha256sum, get_cache_dir
+├── path/           # local + S3 path helpers
+│   ├── __init__.py
+│   ├── ops.py      # pure ops (join, dirname, basename, suffix, …)
+│   ├── env.py      # path_dotenv, path_home, path_expanduser
+│   ├── io.py       # mkdir, remove, copy, move, read/write
+│   └── query.py    # exists, is_dir, glob, listdir, stat
+└── time.py         # get_elapsed_time
+```
+
+## Build & test
+
+```bash
+uv sync
+.venv/bin/pre-commit run --all-files
+.venv/bin/pytest
+.venv/bin/mypy klogr/
+```
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).