Goal

Replace permanent deletion of recoverable user data with FreeDesktop trash:

Instead of	Use
os.remove(path) / os.unlink	rtrash.unlink(path)
pathlib.Path.unlink()	rtrash.unlink(path)
shutil.rmtree(path)	rtrash.rmtree(path)
ad-hoc subprocess to trash-cli	rtrash.put / empty_trash in-process

This does not monkey-patch os or pathlib globally.

Install

pip install maturin
maturin develop --features python
# from repo root; needs a Rust toolchain

API

import rtrash

rtrash.put(path, recursive=False, force=False)
rtrash.put_paths([p1, p2], recursive=False, force=False)
rtrash.unlink(path, recursive=False, force=False)   # os.remove-shaped
rtrash.rmtree(path, force=False)                    # shutil.rmtree-shaped

rtrash.list_trash(trash_dir=None)  # -> list[(date_str, original_path)]
rtrash.empty_trash(days=None, trash_dir=None, dry_run=False)
rtrash.restore_path(path, force=False, trash_dir=None)
rtrash.home_trash()  # Path to $XDG_DATA_HOME/Trash
rtrash.version()

All operations honor XDG_DATA_HOME / FreeDesktop placement from the Rust core (same as the CLI).

Testing

maturin develop --features python
python -m unittest tests.python.test_rtrash -v

Tests set XDG_DATA_HOME to a temporary directory so they never touch the host trash.

Errors

Failed put/empty/restore surfaces as OSError (operation failed) or ValueError (bad arguments), mapped from the CLI-layer exit codes of the shared Rust entry points.