Welcome to hamster_cli’s documentation!

Contents:

hamster_cli

Documentation Status 'Stories in Ready' Requirements Status

A basic CLI for the hamster time tracker.

WARNING This is still pre-alpha software. Altough we are reaching apoint were most things work as intended we make no promisse about your data as well as any commitment. In particular there is no intension to migrate any databases from this version to any future more mature release.

News (2016-04-25)

Version 0.12.0 is out! With this version we feel confident that you may be able to actually play with hamster-cli in a somewhat productive way. Whilst we are still far from being production ready and miss a significant amount of legacy feature this release may give you quite the idea where we are heading. For the first time we were able to give the frontend some love whilst further beefin up our QA toolchain, introducing even more tests and new test environments. The documentation has been vastly improved, digging into the code never was easier.

Happy hacking; Eric.

Features

  • High test coverage.
  • Well documented.
  • Lightweight.
  • Free software: GPL3
  • Uses hamsterlib, which supports a wide array of databases.
  • Few dependencies
  • Active development.

Resources

Credits

Tools used in rendering this package:

Installation

At the command line:

$ easy_install hamster_cli

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv hamster_cli
$ pip install hamster_cli

Usage

To use hamster_cli simply imvoke it:

hamster-cli

Incompabilities

We tries hard to stay compatible with legacy hamster-cli but there are some aspects where we could not do so without make to huge tradeoffs to what we feel is the proper way to do so. For transparency and you to evaluate if those breaking points affect you we list them here:

  • Only one ongoing fact at a time. You will not be able to start more than one fact without providing an endtime. If you do you will be presented with an error and either have to cancel or stop the current ongoing fact.
  • Argument values that contain whitespaces need to be wrapped in quoteation marks. This is established practice and needed to stay POSIX compatible. In particular this affects: * start/end - datetimes; As date and time aspects are seperatetd by a whitespace. * raw_fact arguments; As they contain various whitespaces. * search terms

hamster_cli

hamster_cli package

Submodules

hamster_cli.hamster_cli module

A time tracker for the command line. Utilizing the power of hamsterlib.

class hamster_cli.hamster_cli.Controler[source]

Bases: hamsterlib.lib.HamsterControl

A custom controler that adds config handling on top of its regular functionality.

class hamster_cli.hamster_cli.HamsterAppDirs(*args, **kwargs)[source]

Bases: appdirs.AppDirs

Custom class that ensure appdirs exist.

site_config_dir

Return site_config_dir.

site_data_dir

Return site_data_dir.

user_cache_dir

Return user_cache_dir.

user_config_dir

Return user_config_dir.

user_data_dir

Return user_data_dir.

user_log_dir

Return user_log_dir.

hamster_cli.help_strings module

Module to provide u18n friendly help text strings for our CLI commands.

Module contents

hamster_cli, a command line time tracker utilizing the power of hamsterlib.

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/elbenfreund/hamster_cli/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” is open to whoever wants to implement it.

Implement Features

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

Write Documentation

hamster_cli could always use more documentation, whether as part of the official hamster_cli 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/elbenfreund/hamster_cli/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 hamster_cli for local development.

  1. Fork the hamster_cli repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/hamster_cli.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 hamster_cli
$ cd hamster_cli/
$ make 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:

    $ make test-all

    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 2.6, 2.7, 3.3, and 3.4, and for PyPy. Check https://travis-ci.org/elbenfreund/hamster_cli/pull_requests and make sure that the tests pass for all supported Python versions.

Tips

To run a subset of tests:

$ make test TEST_ARGS="-k NAME_OF_TEST_OR_SUB_MODULE"

or if you just want to run a particular tox environment:

$ tox -e NAMEOVENVORONMENT

If you want to play around with an executeable version of you modified client:

$ cd PATH_TO_CLONED_REPOSITORY
$ mkvirtualenv NAME_OF_SANDBOX_ENV
$ pip install -e .

This will install your WIP hamster-cli in a wroking state into your sandbox. Any changes to the codebase will be applied by that version right away. Please not that any files created by the client will persist even if you uninstall it or delete the virtualenv.

Credits

Development Lead

Contributors

None yet. Why not be the first?

History

0.12.0 (2016-04-25)

  • stop now shows detail on the fact saved.
  • current now shows how much time was accumulated so far.
  • Remove standalone script block. You are expected to utilize pip/setuptools to setup hamster_cli. virtualenvs FTW!
  • Testenvironment now uses linkchecks and doc8 for validating the documentation.
  • Removed ‘GTK window’ related pseudo methods. Until the functionality is actually here.
  • Added manifest validation to testenvironment.
  • Added pep257 validation to testsuite.
  • Vastly improved docstring, docstringcoverage and frontend helptexts.
  • Use hamsterlib 0.10.0 new improved config layout.
  • Add GPL boilerplate and frontend information.
  • release make target now uses twine.
  • Provide new details command to list basic runtime environment details.

0.11.0 (2016-04-16)

  • New, solid config handling.
  • Switch to semantic versioning.
  • Move CI from codeship to Travis-CI.
  • First batch of very basic integration tests.
  • Several fixes to packaging.

0.1.0 (2016-04-09)

  • First release on PyPI.
  • Prove-of-concept release.
  • Most of the basic functionality is there.
  • Provides basic test coverage.

Indices and tables