Metadata-Version: 2.4
Name: pytrash
Version: 0.3.3
Summary: a high level api for handling recycle bins across platforms
Keywords: recycle bin,trash,recycle,bin,trash-rs
Author: NSPC911
Author-email: NSPC911 <87571998+NSPC911@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# pytrash

a high level api for handling recycle bins across platforms

### Installation
```
uv add pytrash
```

### Usage
```py
import pytrash

# pytrash provides a way to move files to the bin, list entries in bin, and restore files from bin.
# create instance of Bin
bin = pytrash.RecycleBin()

# move a file to the bin
bin.recycle(["path/to/file.txt"])

# list entries
bin.entries()

# restore a file from the bin
entry = bin.entries()[0]
bin.restore([entry])

# permanently delete a file from the bin (irreversible!)
bin.purge([entry])

# permanently delete everything in the bin (irreversible!)
bin.empty()
```

That's it. It doesn't get any simpler than that.

Entries are returned as a list of `TrashEntry` dataclasses, which contain the following attributes:

```py
TrashEntry(
  name='Screenshot from 2026-06-10 17-35-55.png',
  original_path='/home/nspc911/Pictures/Screenshots/Screenshot from 2026-06-10 17-35-55.png',  # this will be None if entry doesn't contain this info
  deleted_at=datetime.datetime(2026, 6, 28, 11, 31, 17),  # this can be None if entry doesn't contain this info
  size=13075  # shouldn't be None, but it is possible.
)
```

For now, only the major 3 OSes are supported (Windows, Linux, MacOS). If you want to add support for your OS, feel free to open a PR.

### CLI
This also includes a CLI for interacting with the recycle bin
```
uv tool install pytrash
```

```
pytrash trash <file1> <file2> ...  # move files to the bin
pytrash list                       # list entries in the bin
pytrash list --json                # list entries in the bin
pytrash restore <entry1> <entry2> ...  # restore entries from the bin
pytrash purge <entry1> <entry2> ...    # permanently delete entries (asks first; -y to skip)
pytrash empty                          # permanently delete everything (asks first; -y to skip)
```

This CLI interface is not to be compared with the [`trashy`](https://github.com/oberblastmeister/trashy) CLI, it is Rust, it doesn't have the Python Interpreter overhead. This project aims to provide an easy interface for cross platform bins. The CLI is simply a way to make use of it.

### Like what I do? Check out similar projects
- [multiarchive](https://github.com/NSPC911/multiarchive): a high level api for handling archives across formats
