Metadata-Version: 2.4
Name: codechu-xdg
Version: 0.1.0
Summary: Vendor-namespaced XDG Base Directory paths for Linux desktop apps.
Author: Codechu
License: MIT License
        
        Copyright (c) 2026 Codechu
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/codechu/xdg-py
Project-URL: Source, https://github.com/codechu/xdg-py
Project-URL: Issues, https://github.com/codechu/xdg-py/issues
Keywords: xdg,base-directory,linux,config,cache
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
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 :: System :: Filesystems
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# codechu-xdg

Vendor-namespaced [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/)
paths for Linux desktop apps. Tiny — ~80 LOC, stdlib-only, no dependencies.

```bash
pip install codechu-xdg
```

## What it gives you

- 5 standard XDG path types: **config, cache, data, state, runtime**
- **Mandatory vendor + product namespace** — every path is
  `$XDG_BASE/<vendor>/<product>/`, so multiple products from the same
  publisher live under one directory (one `~/.config/<vendor>/` reveals
  all your products)
- `ensure()` — `mkdir -p` for all 5 dirs
- `migrate()` — idempotent legacy → new path mover (run once at startup
  to upgrade users from earlier layouts)

## Quick examples

### Basic

```python
from codechu_xdg import App

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

# Paths
settings  = app.config_dir  / "settings.json"
db_cache  = app.cache_dir   / "du_cache.db"
snapshots = app.data_dir    / "snapshots.db"
log_file  = app.state_dir   / "app.log"
pid_file  = app.runtime_dir / "watchdog.pid"
sock_file = app.runtime_dir / "control.sock"
```

### Convenience helpers

For common file types, helpers eliminate `dir / "name"` boilerplate:

```python
app.settings_file()                # config_dir / settings.json (default name)
app.settings_file("themes.json")   # config_dir / themes.json
app.cache_file("du_cache.db")
app.data_file("snapshots.db")
app.log_file()                     # state_dir / app.log
app.runtime_file("watchdog.pid")
```

### Cleanup at shutdown / on demand

```python
# Wipe stale sockets and pid files — recreated on next run.
app.remove_runtime()

# Or full cache wipe (regeneratable). Returns count of removed entries.
n = app.remove_cache()
print(f"cleared {n} cache entries")
```

## Migration from earlier layouts

When you change directory conventions across versions, `migrate()`
moves files idempotently — runs safely on every startup:

```python
from pathlib import Path

moved = app.migrate({
    # v0.0 layout: everything under ~/.config/<product>/
    Path.home() / ".config" / "disk_cleaner" / "settings.json":
        app.config_dir / "settings.json",
    Path.home() / ".config" / "disk_cleaner" / "du_cache.db":
        app.cache_dir / "du_cache.db",
    Path.home() / ".config" / "disk_cleaner" / "snapshots.db":
        app.data_dir / "snapshots.db",
})
print(f"migrated {moved} files")
```

Files at the new path are **never overwritten** — if `new` exists, the
`old` is left in place. This makes it safe to run on every startup.

## Why a vendor namespace

Single-vendor apps put files at `~/.config/<product>/` — fine for one
product. Multi-product publishers benefit from grouping:

```
~/.config/codechu/
├── disk-cleaner/
├── file-explorer/
└── system-monitor/
```

One directory, full inventory. Pattern used by JetBrains
(`~/.config/JetBrains/`) and Mozilla (`~/.mozilla/`).

## Path resolution

Standard XDG environment variables:

| Path | Env var | Default |
|---|---|---|
| config | `XDG_CONFIG_HOME` | `~/.config` |
| cache | `XDG_CACHE_HOME` | `~/.cache` |
| data | `XDG_DATA_HOME` | `~/.local/share` |
| state | `XDG_STATE_HOME` | `~/.local/state` |
| runtime | `XDG_RUNTIME_DIR` | `/run/user/$UID` |

Honored at module import time. Re-import / reload for env changes
during tests.

## Validation

- `vendor` and `product` must be non-empty and not contain `/`.
- All directories use safe `mkdir -p` semantics — no race-on-create.

## Multi-platform?

This library is **Linux-only** (XDG is a Linux/Unix spec). For macOS
or Windows in addition to Linux, see `platformdirs` on PyPI — note
that it does not enforce a vendor namespace on Linux.

## License

MIT — see [LICENSE](LICENSE).

Part of [Codechu](https://github.com/codechu).
