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–2015, 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.

COPYRIGHT¶

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

Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
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.
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.

Global Functions and Modules List¶

Author:	Chris Warrick <chris@chriswarrick.com>
Copyright:	© 2011–2015, 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–2015, 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–2015, 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–2015, 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–2015, 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–2015, 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–2015, 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–2015, 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¶

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

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. If you do not have an account there, get one or mail me.

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 mail are accepted, but working with you through there is a better way.

Fork the repo first. Non-GitHub people, git clone.

Rules¶

Commits must have short, informative and logical messages. Signoffs and long messages are recommended. “fixes #xxx” is required if an issue exists.
The following fancy Unicode characters should be used when needed: — “ ” ‘ ’
The ellipsis (…) character must not be used in program output for humans, but may be used elsewhere.
I’m a Grammar Nazi.

Request a Pull¶

Done? Go hit the Pull Request button over on GitHub! And if you don’t use GitHub, git format-patch. Other formats are not accepted.

Your commit should be pulled up in a (longer) while. If I like it. Because some commits may be bad. So, do your best not to do those bad commits.

Details for specific contribution types¶

Code (Python)¶

PEP 8. pip install pep8 is recommended.
./tests.py.
Localize all the strings (_('string'))
Strings must be quoted using 'str'. Multi-line strings, """str""". Use the latter only if needed. Otherwise, do:

string = ('A very, very, very long string '
          'that’s broken up into multiple lines.')

string = _('A very, very, very log string '
           'that’s broken up into multiple lines '
           'and that is localized through gettext.'))

str.format. Braces should be empty or contain a name that is later passed on to the function. The format function should be inserted after the parenthesis for string localization. For example:

string = _('{} is awesome').format('PKGBUILDer')
string = _('{sth} is awesome').format(sth='PKGBUILDer')

Documentation is important. Please take care of it.

Code (non-Python)¶

Rejected.

Non-code contributions¶

Those are accepted. No specific rules exist. And don’t remove any files without my permission (docs/*.8.gz in particular).

Localization¶

Run mkdir -p locale/[CODE]/LC_MESSAGES in your terminal, replacing [CODE] by your language code, as in /usr/share/locale.
Copy the /messages.pot file to locale/[CODE]/LC_MESSAGES/[PROJECT].po (replace [PROJECT] with the project name, all-lowercase)
Do your work. The comments will inform you where this string is, and the ones starting with ‘TRANSLATORS:’ are for you to read and make use of. Other comments come from my code and you should not care about them. And if it is directed for translators, let me know. The Poedit app may be of help. Please take care of the headers at the top of the file (with a text editor, do not use Poedit for that!) and modify them. The Last-Translator, Language-Team and Language are important, the others are auto-generated anyways. The general Rules apply, please take care of it!
Commit (-s/--signoff is required here).
Your translation will be added in the next release, or, if a release isn’t planned in the near future, a new release will be made. Your addition will be appreciated. Note that I cannot translate new strings, and, as a result, I might ask you for additions in the future.

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

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

Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
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.
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–2015, 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.

Trashman. A Python trash manager.¶

How to use¶

Features¶

Additional documents, indices and tables¶

Trashman¶

SYNOPSIS¶

DESCRIPTION¶

OPERATIONS¶

OPTIONS¶

EXAMPLES¶

BUGS¶

Trashman. A Python trash manager.¶

PURPOSE¶

INSTALLATION¶

COPYRIGHT¶

Global Functions and Modules List¶

__init__.py¶

trashman¶

tmds.py (TMDS — Trashman Data Storage)¶

trashman.TMDS¶

main.py (main())¶

Backends¶

Functions¶

Existing backends¶

DummyTrash¶

trashman.backends.dummytrash¶

XDGTrash¶

trashman.backends.xdgtrash¶

Appendix A. Contribution rules¶

Issue reporting¶

General preparations, rules and pull process¶

Prepare¶

Rules¶

Request a Pull¶

Details for specific contribution types¶

Code (Python)¶

Code (non-Python)¶

Non-code contributions¶

Localization¶

Appendix A. License for Trashman¶

CHANGELOG for Trashman¶

GitHub holds releases, too¶

Version History¶

1.5.0¶

1.0.0¶

0.2.0¶

0.1.0¶

init.py¶