Welcome to taggo’s documentation!

Contents:

taggo

https://img.shields.io/pypi/v/taggo.svg https://img.shields.io/travis/xeor/taggo.svg https://img.shields.io/coveralls/xeor/taggo.svg Documentation Status Updates

Tag organizer that uses names of files and folders to create symlinks. Tags are defined by using #hashtags in the name. They can also be as many sub levels as you want, like #sub-hash-tag

note This version is a completey different version than the old (https://github.com/xeor/taggo/tree/0.2). The old version works for python 2 (but not 3). It also had config-file instead of parameters. Check out the repo if you want it..

Introduction

This project is in beta stage, please report bugs :)

Any questions, thoughts, bugs are very welcome!

Requirements

  • 3.6+

Docker

Start the container with environment variables like CRON_TAGGO_0 with the format * * * * *|run ….

  • CRON_TAGGO_n where n is a number, start at 0, have as many as you want.
  • We take care automaticly that only 1 of each number is running at a time. Example, if one of your job is running every minute and it takes more than a minute to finish. It wont start the 2nd time.
  • The environment variable is split in 2 by a |. The first param is a cron, the 2nd is the parameters sent to the taggo command.

FAQ

  • Why the name taggo?
    • It’s a tagging tool. It does stuff with tags. What do you suggest? Tagging, taggs, tags, tag2fold… no.. Taggo!
  • Why do you want to create tags with symlinks?
    • Because everyone have underestimated the power of tagging data.
    • Photo filenames are just wasted, what does DCIM1234.jpg tell you?
    • You know you miss one folder that contains all your dog pictures.
    • You sould not depend on a 3rd party program/database to manage your files/photos.

Installation

Stable release

To install taggo, run this command in your terminal:

$ pip install taggo

If you also want to download the required packages to run all metadata-addons, install taggo like this.

$ pip install taggo[all]

This is the preferred method to install taggo, as it will always install the most recent stable release.

If you don’t have pip installed, this Python installation guide can guide you through the process.

From sources

The sources for taggo can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/xeor/taggo

Or download the tarball:

$ curl  -OL https://github.com/xeor/taggo/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

Usage

Taggo is most usefull if you use it on the commandline

Files and folders example layout:

root@4c95ee980234:/# find /data/
/data/
/data/2016
/data/2016/best taco #recipes-dinner.txt
/data/2016/python snippets #projects-programming-python.txt
/data/2017
/data/2017/#traveling-london
/data/2017/#traveling-london/places to visit.txt
/data/2017/#traveling-london/airplane tickets.pdf
/data/2015
/data/2015/chocolate cake #recipes-cake.txt
/data/2015/truffle chicken #recipes-dinner.txt
/data/2015/#important note.txt

Difference between –filter and –filter-query

TLDR: If possible, use –filter for speed :)

The longer story, is that –filter knows what you are filtering on, before it completes all the metadata-addon calculations. This is because the correct filter gets checked after each metadata calculation. Example, when the stat addon is done, the stat filters are checked. If the filter dictates that it should skip the file, no more metadata calculation is done for that file. This is usefull and can save you some time. However, there are some big cons using the –filter:

  • You wont be able to filter on data that is not flat. Example, there are no way to filter on paths[]…
  • It is not that powerfull, and doing logical AND, OR, NOT and such are a pain.

The –filter-query is using jmespath, and it have a very powerfull querylanguage. It can handle more logic, and is much more powerfull than –filter. However.. There are some cons:

  • It depends on a 3rd party lib (pip install jmespath)
  • The filter are checked once per file, after all metadata addons are calculated.

Both filter-types can however be combined.. So you can do a quick check using –filter, then a more advanced check later using –filter-query

Cleanup

Symlinks that are dead can be cleaned up easiely:

root@4c95ee980234:/# rm "/data/2016/best taco #recipes-dinner.txt"

root@4c95ee980234:/# taggo cleanup tags/
Deleting symlink /tags/recipes/dinner/2016 - best taco #recipes-dinner.txt

List tags

To list tags available in a source directory:

root@4c95ee980234:/# taggo info data/
Folder tags:
  traveling-london

File tags:
  important
  projects-programming-python
  recipes-cake
  recipes-dinner

Rename tags

You can also rename tags if you want them nested another way, or just got a typo:

root@4c95ee980234:/# taggo rename data/ traveling-london traveling-uk-london
Renaming: /data/2017/{#traveling-london -> #traveling-uk-london}

root@4c95ee980234:/# taggo cleanup tags/
Deleting symlink /tags/traveling/london/2017_#traveling-london - #traveling-london
Removing empty folder: /tags/traveling/london
Removing empty folder: /tags/traveling

root@4c95ee980234:/# taggo run data tags

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/xeor/taggo/issues.

If you are reporting a bug, please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation

taggo could always use more documentation, whether as part of the official taggo docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/xeor/taggo/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up taggo for local development.

  1. Fork the taggo repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/taggo.git

  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv taggo
$ cd taggo/
$ python setup.py develop

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 taggo tests
$ python setup.py test or pytest
$ tox

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include tests.
  2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
  3. The pull request should work for Python 3.6, and up. Check https://travis-ci.org/xeor/taggo/pull_requests and make sure that the tests pass for all supported Python versions.

Debug travis

Start a custom build (trigger build) and input something like script: DEBUG=true pytest -k test_symlink_creation

Credits

Project owner

Contributors

None yet. Why not be the first?

History

0.13.0 (2018-03-04)

  • Dropping python 2.x support… Some things might end up being problematic to support. Like symlinks for directories in windows. So instead of making a bunch of hacks around functionality. It is now dropped.

0.12.0 (2018-03-03)

  • Making symlink name template configurable
  • Symlink collision handling
  • Logs to stdout/stderr depending on message severety
  • Option to output log as json
  • Option to prompt/wait after each symlink. Usefull for debugging
  • Lots of things around symlink-name-templates, it’s now completly configurable.
  • Possible to have extrainfo (used in symlink-name) from a tag parameter. Like #tag(info)
  • Using powerful filters to not symlink certain files, or only symlink some files.
  • Metadata-addons to use special file-info as in the symlink-name, like md5, stat, exif-data, …
  • Output data as json, if you want a logparser to use it. Single-lines..
  • Configurable collision handling. If symlink already exist and points to a different file.
  • Making pip install taggo[all] to get all metadata-addon required libs
  • –auto-cleanup option in run
  • Log different messages to stdout or stderr

0.11.0 (2018-02-20)

  • Fixing up docker image

0.10.0 (2017-11-04)

  • Basic docker image

0.9.0 (2017-10-21)

  • Python 2.7 support

0.8.0 (2017-10-21)

  • Good test coverage
  • Things are mostly working
  • Rename functionality
  • List/info
  • Much more

0.4.0 (2017-10-08)

  • Started a complete rewrite, mainly focusing on using python 3.6
  • Test on PyPI.. Non working version.

0.2 (2017-10-07)

  • Checkpoint of the old version working only with 2.x. This checkpoint contains code from many years ago.

Indices and tables