https://github.com/nspc911/pytrash
high level api for recycling
https://github.com/nspc911/pytrash
python recyclebin trash
Last synced: 1 day ago
JSON representation
high level api for recycling
- Host: GitHub
- URL: https://github.com/nspc911/pytrash
- Owner: NSPC911
- License: mit
- Created: 2026-07-09T15:50:30.000Z (15 days ago)
- Default Branch: main
- Last Pushed: 2026-07-19T00:57:33.000Z (5 days ago)
- Last Synced: 2026-07-19T02:28:33.959Z (5 days ago)
- Topics: python, recyclebin, trash
- Language: Python
- Homepage: https://pypi.org/project/trashy
- Size: 124 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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 ... # move files to the bin
pytrash list # list entries in the bin
pytrash list --json # list entries in the bin
pytrash restore ... # restore entries from the bin
pytrash purge ... # 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