Trashman. A Python trash manager.

Note

This documentation is for Trashman version 1.5.0. Some parts of this documentation might not apply to other versions.

Trashman is a trash manager, i.e. an application which manages trash folders. It provides several backends.

How to use

Install it from PyPI or the AUR.

To trash a file, just type trash FILE [FILE ...] into your shell. To restore a file from the trash, add the -r (--restore) argument. To empty the trash and delete the files forever, use the -e (--empty) switch. Verbose output can be provided by -v (--verbose). The location of your trash will be printed by -w (--trash-location) and the files location will be presented by -W (--files-location); w as in where. Other switches, related to Trashman, are -V (--version) and -h (--help).

Features

Currently implemented in most backends:

  • trashing
  • trash conflict resolution
  • restore
  • localization support
  • tests

Not yet ready:

  • restore to inexisting directory (KDE refuses to do that, so we’ll probably do so, too)

Useless features that are planned:

  • CLI
  • Qt GUI

Developers using Trashman as a library may want to look at the Global functions list or Backends info (and maybe TODO). Other people may want to look at the README.

Additional documents, indices and tables

Trashman

Author:Chris Warrick <chris@chriswarrick.com>
Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE or Appendix B.)
Date:2015-03-07
Version:1.5.0
Manual section:1
Manual group:Trashman manual

SYNOPSIS

trashman [-hVerlvwW] [FILE [FILE…]]

DESCRIPTION

Trashman is a trash manager, i.e. an application which manages trash folders. It provides several backends.

OPERATIONS

[FILE [FILE…]]
Trashes the FILE(s).
-e, –empty
Empties the trash.
-r, –restore
Restores the FILE(s) from the trash.
-l, –list
Lists the trash contents using ls.
-w, –trash-location
Prints the trash root location.
-W, –files-location
Prints the location of trashed files, which may be different from the root.

OPTIONS

-b BACKEND, –backend BACKEND
Selects the backend to use. ‘auto’ chooses the backend automatically (fallback: XDG), ‘config’ tries the config file (which is ‘auto’ by default) and ‘list’ displays a list of the possible backends. Can be configured in ~/.config/kwpolska/trashman/trashman.cfg.
-h, –help
Prints a help message.
-v, –verbose
Turns on verbose mode.
-V, –version
Prints the version in use.

EXAMPLES

trash foo
Trashes the foo directory.
trash foo
Restores the foo directory from trash.
trash -e
Empties the trash.

BUGS

Bugs should be reported at the GitHub page (<https://github.com/Kwpolska/trashman/issues>). You can also send mail to <chris@chriswarrick.com>.

Trashman. A Python trash manager.

Info:This is the README file for Trashman.
Author:Chris Warrick <chris@chriswarrick.com>
Date:2015-03-07
Version:1.5.0

PURPOSE

This is a simple trash manager. It can do various things related to the trash.

INSTALLATION

PyPI or AUR.

Global Functions and Modules List

Author:Chris Warrick <chris@chriswarrick.com>
Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE or Appendix B.)
Date:2015-03-07
Version:1.5.0

This is an auto-generated documentation of the Trashman suite. It is bare-bones, and you’d be better off reading the source code yourself.

__init__.py

trashman

A Python trash manager.

Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE).
exception trashman.__init__.TMError(src, info, msg)[source]

Exceptions raised by the Trashman.

trashman.__init__.size_dir(sdir)[source]

Get the size of a directory. Based on code found online.

tmds.py (TMDS — Trashman Data Storage)

trashman.TMDS

Trashman Data Storage.

Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE).
class trashman.tmds.TMDS[source]

Trashman Data Storage.

critical(msg)[source]

Show a critical error and log it.

error(msg)[source]

Show an error and log it.

info(msg)[source]

Show an information and log it.

warning(msg)[source]

Show a warning and log it.

main.py (main())

Backends

Author:Chris Warrick <chris@chriswarrick.com>
Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE or Appendix B.)
Date:2015-02-28
Version:1.5.0

Trashman uses backends for managing files. All the backends define the same functions and inherit from the Trash class.

Backend requirements:
  • name ending in Trash (eg. XDGTrash, DummyTrash)
  • PEP 8, docstrings
  • inherit from Trash
  • throw exceptions and log activity
  • implement the functions listed below (do not re-implement log unless needed)
  • do actual work (save for the dummy backend)
  • have a self.trashdir variable with the trash location (None if impossible)
  • have a self.logger instance (import logging, logging.getLogger('NAME')

In order to choose a backend, use trashman.backends.select(backend). If backend is auto, a choice will be made basing on the config, and if it also says auto, on the OS used. If it is list, a human-readable list of backends will be printed.

Functions

(this automatically-generated of the Trash class.)

class trashman.backends.trash.Trash[source]

Base Trash class.

empty(verbose)[source]

Empty the trash.

list(human=True)[source]

List the trash contents.

log(msg, lvl='debug')[source]

Log a message.

regenerate()[source]

Regenerate the trash and recreate metadata.

restore(filename, verbose)[source]

Restore a file from trash.

trash(filepath, verbose)[source]

Move specified file to trash.

Existing backends

DummyTrash
Name:DummyTrash
Module:dummytrash
Author:Chris Warrick <chris@chriswarrick.com>
Specification:n/a
OS:any
Description:A dummy backend, printing all the requests it gets.
Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE or Appendix B.)
Date:2015-02-28
Version:1.5.0
trashman.backends.dummytrash

A dummy backend, printing all the requests it gets.

Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE).
class trashman.backends.dummytrash.DummyTrash[source]

A dummy trash, printing and logging actions that would be performed.

empty(verbose)[source]

Empty the trash.

list(human=True)[source]

List the trash contents.

log(msg, lvl='debug')[source]

Log a message.

regenerate()[source]

Regenerate the trash and recreate metadata.

restore(filename, verbose)[source]

Restore a file from trash.

trash(filepath, verbose)[source]

Move specified file to trash.

XDGTrash
Name:XDGTrash
Module:xdgtrash
Author:Chris Warrick <chris@chriswarrick.com>
Specification:XDG/freedesktop <http://freedesktop.org/wiki/Specifications/trash-spec>
OS:Linux (KDE, GNOME, Xfce and others conforming to this spec)
Description:An XDG trash implementation.
Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE or Appendix B.)
Date:2015-02-28
Version:1.5.0
trashman.backends.xdgtrash

An XDG trash implementation.

Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE).
class trashman.backends.xdgtrash.XDGTrash[source]

XDG trash backend.

empty(verbose)[source]

Empty the trash.

list(human=True)[source]

List the trash contents.

regenerate()[source]

Regenerate the trash and recreate metadata.

restore(filename, verbose, tocwd=False)[source]

Restore a file from trash.

trash(filepath, verbose)[source]

Move specified file to trash.

Appendix A. Contribution rules

Info:Those are the contribution rules for Trashman.
Copyright:© 2012-2018, Chris Warrick.
License:3-clause BSD

Do you want to contribute to this project? Great! I’d love to see some help, but you must comply with some rules.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Issue reporting

GitHub Issues are the recommended way to report an issue.

When pasting console sessions, you must paste them fully, prompt-to-prompt, to see all the messages and your input. Trim only stuff that you are 1000% sure that is not related to the project in question.

General preparations, rules and pull process

Prepare

A GitHub account is recommended. Patches by e-mail are accepted, but I’d prefer to work via GitHub.

Rules
  1. Commits must have short, informative and logical messages. Signoffs and long messages are recommended. “Fix #xxx” is required if an issue exists.
  2. The following fancy Unicode characters should be used when needed: . should not appear in console output, but may appear elsewhere.
  3. For Python code, use the PEP 8 coding style and PEP 257 documentation style. For other languages, K&R style applies. Braces are mandatory in all blocks (even one-line blocks). Braces are on the same lines as class names and function signatures. Use 4-space indents.
Request a Pull

Done? Go hit the Pull Request button over on GitHub! Your request should be accepted shortly (assuming there are no major errors).

Appendix A. License for Trashman

Info:This is the license for Trashman.
Author:Chris Warrick <chris@chriswarrick.com>
Date:2015-03-07
Version:1.5.0

Copyright © 2011-2018, Chris Warrick. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the author of this software nor the names of contributors to this software may be used to endorse or promote products derived from this software without specific prior written consent.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

CHANGELOG for Trashman

Author:Chris Warrick <chris@chriswarrick.com>
Copyright:© 2011-2018, Chris Warrick.
License:BSD (see /LICENSE or Appendix B.)
Date:2015-03-07
Version:1.5.0

GitHub holds releases, too

More information can be found on GitHub in the releases section.

Version History

1.5.0
1.5.0
A big modernization of Trashman.
1.0.0
1.0.4
Minor fixes.
1.0.3
I do not like the word “exit”.
1.0.2
Fixes #2, creating config dirs properly. (the app crashed if there was no ~/.config/kwpolska/ dir. This bug wasn’t found due to having PKGBUILDer installed, which was creating that directory.)
1.0.1
Bugfix release.
1.0.0
A complete modification of the approach, now using a concept of “backends”, allowing multiple trash systems to be used.
0.2.0
0.2.4.1 (semi-official)
Locale fix #3, only pypi/aur
0.2.4
Zsh completions.
0.2.3
Locale fix #2
0.2.2
Locale fix #1
0.2.1
Localization support.
0.2.0
Documentation. The project became a bit more mature now.
0.1.0
0.1.3
Fixed some problems with file restoration.
0.1.2
Ommited a character, also added restoration to –help.
0.1.1
Restoration magic.
0.1.0
Initial release.