About Stamper ============= .. contents:: 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 http://json.org) 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:: :doc:using .. _Stamper: https://bitbucket.org/codigo23/stamper .. _stamp: http://repos.betabug.ch/stamp .. _`Sascha Welter`: http://betabug.ch .. _`betabug`: http://betabug.ch .. _python: http://python.org .. _JSON: