hamsterlib 0.1.0

A library for common timetracking functionality.

===============================
hamsterlib
===============================

.. image:: https://img.shields.io/pypi/v/hamsterlib.svg
:target: https://pypi.python.org/pypi/hamsterlib

.. image:: https://img.shields.io/travis/elbenfreund/hamsterlib/master.svg
:target: https://travis-ci.org/elbenfreund/hamsterlib

.. image:: https://img.shields.io/codecov/c/github/elbenfreund/hamsterlib/master.svg
:target: https://codecov.io/github/elbenfreund/hamsterlib

.. image:: https://badge.waffle.io/elbenfreund/hamsterlib.svg?label=ready&title=Ready
:target: https://waffle.io/elbenfreund/hamsterlib
:alt: 'Stories in Ready'

.. image:: https://readthedocs.org/projects/hamsterlib/badge/?version=master
:target: https://readthedocs.org/projects/hamsterlib/?badge=master
:alt: Documentation Status

.. image:: https://requires.io/github/elbenfreund/hamsterlib/requirements.svg?branch=master
:target: https://requires.io/github/elbenfreund/hamsterlib/requirements/?branch=master
:alt: Requirements Status

(A badges refer to ``master``)

A library for common timetracking functionality.

``hamsterlib`` aims to be a replacement for ``projecthamster`` backend
library. While we are not able to function as a straight forward drop-in
replacement we try very hard to stay as compatible as possible. As a consequence
clients are able to switch to ``hamsterlib`` merely by changing some basic
calls. Most of the semantics and return values will be as before.

This itself points to a major architectural shift in the way ``hamsterlib`` approaches
timetracking. We are firm believers in *do one thing, and do it well*. The tried and
tested unix toolbox principle. As such we focus on providing useful backend
functionality and helper methods so clients (dbus interfaces, CLIs or graphical UIs)
can build upon a solid and consistent base and focus on their specific requirements.

Features
--------
* Full python >=2.7 and >=3.4 compatibility
* Full unicode support
* >= 95% test coverage
* Extensive documentation
* Focus on clean, maintainable code.
* Free software: GPL3
* All you need for production, test or dev environments comes out of the box
with regular python tools.

First Steps
-----------
* Build dev environment: ``make develop``
* Build the documentation locally: ``make docs``
* Run just the tests: ``make test``
* Run entire test suite including linters and coverage: ``make test-all``

Additional Resources
--------------------
* `Documentation by 'read the docs' <https://hamsterlib.readthedocs.org>`_
* `Project management with 'waffles' <https://waffle.io/elbenfreund/hamsterlib>`_
* `CI thanks to Travis-CI <https://travis-ci.org/elbenfreund/hamsterlib>`_
* `Coverage reports by 'codecov' <https://codecov.io/elbenfreund/hamsterlib>`_
* `Dependency monitoring by 'requires.io' <https://requires.io/github/elbenfreund/hamsterlib/requirements/?branch=master>`_

News: Version 0.10.0
---------------------
This new release marks our switch to semantic versioning and brings a few stability improvements
as well as ``ìcal`` and ``xml`` export. We improved documentation, internal code and
project handling a bit but for a full list of changes please refer to the changelog.

Todo
----
This early release is mainly meant as a rough proof-of-concept at this stage. It
showcases our API as well as our general design decisions.
As such there are a few functionalities/details of the original ``projecthamster``
backend that we wish to allow for, but are not provided so far.
These are:

* Tags (We accept them but they are not stored in the backend.)
* Autocomplete related methods
* Trophies (The jury is still out on if and how we want to support those.)
* Migrations from old databases.

Incompatibilities
------------------
Despite our efforts to stay backwards compatible we did deliberately break the way
``Facts`` without end dates are handled. We think allowing for them in any persistent
backend creates a data consistency nightmare and so far there seems no conceivable
use case for it, let alone an obvious semantic.
What we do allow for is *one* ``ongoing fact``. That is a fact that has a start,
but no end date. For details, please refer to the documentation.

Credits
---------
Tools used in rendering this package:

* Cookiecutter_
* `cookiecutter-pypackage`_
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage




History
=======

0.10.0
------
* Add ``ical`` export facilities. Brand new writer using the ``icalendar`` library.
* Add ``xml`` export facilities.
* Switch to `semantic versioning <http://semver.org>`_
* Added GPL3 boilerplate
* Provide documentation on packaging and ``requirements.txt``.
* Add support for `editorconfig <http://editorconfig.org>`_
* Introduce fine grained, storage backend dependent config options.
*

0.0.3 (2016-04-08)
-------------------
* fact managers ``save`` method now enforces new ``fact_min_delta`` setting.
* Fixed broken packing in ``setup.py``.
* Storage manager methods now use extensive logging.
* Documentation moved to 'alabaster' theme and content extended.
* Remove usage of ``future.builtins.str``.
* Adjusted ``release`` make target.

0.0.2 (2016-04-07)
------------------
* First release on PyPi
* Improved documentation
* Support for *ongoing facts*.
* Updated requirements

0.0.1 (2016-04-03)
---------------------
* First release on github