source: stamper/docs/about.rst@ 42:cff2c17bc1d4

Last change on this file since 42:cff2c17bc1d4 was 42:cff2c17bc1d4, checked in by Borja Lopez <borja@…>, 10 years ago

Added initial version of the docs, covering:

  • About stamper
  • Basic installation instructions (missing install from repo or dev env setup, for example)
  • Basic usage instructions (total times, per-day details, timeline, date-based filters and more)
File size: 2.7 KB

About Stamper

From where does it come from?

Stamper was born strongly inspired by the original stamp tool written by Sascha Welter (aka betabug).

The idea is quite simple:

  1. You stamp a time in a text file, recording that time as the time when you started working on something:

    2014-08-13 09:45 start
  2. You stamp again once you have finished, providing something like an id (to identify a customer, project, whatever) and a description of what you did:

    2014-08-13 10:45 stamper writing documentation

Those times are saved into a text file and afterwards, with a little bit of python magic, you get some reports about the amount of time dedicated per day or id (for example).

Enter the JSON

Betabug's stamp tool records those times as lines in a text file. This is quite convenient because you can look into the file with traditional tools like cat, head or tail, or even open it with your favourite editor, and get information about the times you've spent working on something.

But this comes at a cost, it needs some ugly parsing of the .txt file in the python code that calculates the statistics and reports, making it difficult/slow to perform certain tasks.

And here it comes JSON:

JSON (JavaScript Object Notation) is a lightweight data-interchange format.
It is easy for humans to read and write. It is easy for machines to parse
and generate. It is based on a subset of the JavaScript Programming Language,
Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is
completely language independent but uses conventions that are familiar to
programmers of the C-family of languages, including C, C++, C#, Java,
JavaScript, Perl, Python, and many others. These properties make JSON an
ideal data-interchange language.

(extracted from

Using a .json file instead of a txt file, we can export/import python data structures (like lists or dicts) easily into a text-like file. This means that we can still edit the file using a text editor, or check its contents using cat, head or tail, but we can forget about the parsing of the entries.

The tools

Stamper comes with a variety of tools, but the most used ones are:

  • stamp: Use this to stamp times into the json file.
  • stamps: USe this to query the json file and obtain information about your stamped times.
.. seealso::


Note: See TracBrowser for help on using the repository browser.