━━━━━━━━━━━━━ c o d e c h u  ·  x d g ━━━━━━━━━━━━━━━

   ~/.config/codechu/                ← every Codechu product
   ├── disk-cleaner/  settings.json
   ├── ascii-painter/ settings.json
   └── snap-monitor/  settings.json

   ~/.cache/codechu/...              ← throwaway, regenerable
   ~/.local/share/codechu/...        ← user data, keep it
   ~/.local/state/codechu/...        ← logs, history
   $XDG_RUNTIME_DIR/codechu/...      ← sockets, pids

━━━━━━━━━━ five dirs. one vendor namespace. ━━━━━━━━━

Vendor-namespaced XDG Base Directory paths — five dirs, one rule.

codechu-xdg

Vendor-namespaced XDG Base Directory paths for Linux desktop apps. Every path lives at $XDG_BASE/<vendor>/<product>/ — multiple products from one publisher share a tidy directory tree, and any user can find or clean all your products at once.

Install

pip install codechu-xdg

Python 3.10+. ~80 LOC, stdlib-only.

Quick example

from codechu_xdg import App

app = App(vendor="codechu", product="disk-cleaner")
app.ensure()                       # mkdir -p for all 5 dirs

settings  = app.settings_file()    # config_dir / settings.json
db_cache  = app.cache_file("du_cache.db")
snapshots = app.data_file("snapshots.db")
log_file  = app.log_file()         # state_dir / app.log
sock_file = app.runtime_file("control.sock")

n = app.remove_cache()             # cleanup is one call

What you get

• App(vendor, product) — five paths in one object: config_dir, cache_dir, data_dir, state_dir, runtime_dir.
• Convenience helpers — settings_file(), cache_file(), data_file(), log_file(), runtime_file() for the common cases.
• ensure() — idempotent mkdir -p for all 5 dirs.
• migrate(mapping) — idempotent legacy → new path mover for upgrading users across directory-layout changes; safe to call on every startup (existing target paths are never overwritten).
• remove_cache() / remove_runtime() — bounded cleanup helpers that return the count of removed entries.
• Vendor namespacing enforced — there is no App(product="…") constructor without a vendor; product-only layouts can't sneak in by mistake.

Read more

• API reference — every public symbol with signatures and edge-case tables.
• Recipes — multi-product layouts, migration patterns, cleanup-at-shutdown, lock files.
• Migration guide — between major versions.
• Changelog

Family

Library	Purpose
codechu-fs	Filesystem primitives — atomic write, XDG trash, safe walk
codechu-config	Schema-driven config — atomic save, migrations
codechu-log	Structured logging — context, JSON, rotation
codechu-ipc	Local IPC — Unix socket, FIFO, JSON-line protocol
codechu-events	Thread-safe multi-channel pub/sub bus

Full ecosystem: github.com/codechu.

Credits

• Path conventions per the freedesktop.org XDG Base Directory Specification.

License

MIT — see LICENSE.

Part of Codechu.