| 1 | About Stamper
|
|---|
| 2 | =============
|
|---|
| 3 |
|
|---|
| 4 | .. contents::
|
|---|
| 5 |
|
|---|
| 6 |
|
|---|
| 7 | From where does it come from?
|
|---|
| 8 | -----------------------------
|
|---|
| 9 |
|
|---|
| 10 | Stamper_ was born strongly inspired by the original stamp_ tool written by
|
|---|
| 11 | `Sascha Welter`_ (aka betabug_).
|
|---|
| 12 |
|
|---|
| 13 | The idea is quite simple:
|
|---|
| 14 |
|
|---|
| 15 | 1. You **stamp** a time in a text file, recording that time as the time when
|
|---|
| 16 | you started working on something::
|
|---|
| 17 |
|
|---|
| 18 | 2014-08-13 09:45 start
|
|---|
| 19 |
|
|---|
| 20 | 2. You **stamp** again once you have finished, providing something like an id
|
|---|
| 21 | (to identify a customer, project, whatever) and a description of what you
|
|---|
| 22 | did::
|
|---|
| 23 |
|
|---|
| 24 | 2014-08-13 10:45 stamper writing documentation
|
|---|
| 25 |
|
|---|
| 26 | Those times are saved into a text file and afterwards, with a little bit of
|
|---|
| 27 | python_ magic, you get some reports about the amount of time dedicated per
|
|---|
| 28 | day or id (for example).
|
|---|
| 29 |
|
|---|
| 30 |
|
|---|
| 31 | Enter the JSON
|
|---|
| 32 | --------------
|
|---|
| 33 |
|
|---|
| 34 | Betabug's stamp tool records those times as lines in a text file. This is quite
|
|---|
| 35 | convenient because you can look into the file with traditional tools like *cat*,
|
|---|
| 36 | *head* or *tail*, or even open it with your favourite editor, and get
|
|---|
| 37 | information about the times you've spent working on something.
|
|---|
| 38 |
|
|---|
| 39 | But this comes *at a cost*, it needs some *ugly* parsing of the .txt file in the
|
|---|
| 40 | python code that calculates the statistics and reports, making it difficult/slow
|
|---|
| 41 | to perform certain tasks.
|
|---|
| 42 |
|
|---|
| 43 | **And here it comes JSON:**
|
|---|
| 44 |
|
|---|
| 45 | ::
|
|---|
| 46 |
|
|---|
| 47 | JSON (JavaScript Object Notation) is a lightweight data-interchange format.
|
|---|
| 48 | It is easy for humans to read and write. It is easy for machines to parse
|
|---|
| 49 | and generate. It is based on a subset of the JavaScript Programming Language,
|
|---|
| 50 | Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is
|
|---|
| 51 | completely language independent but uses conventions that are familiar to
|
|---|
| 52 | programmers of the C-family of languages, including C, C++, C#, Java,
|
|---|
| 53 | JavaScript, Perl, Python, and many others. These properties make JSON an
|
|---|
| 54 | ideal data-interchange language.
|
|---|
| 55 |
|
|---|
| 56 | (extracted from http://json.org)
|
|---|
| 57 |
|
|---|
| 58 | Using a .json file instead of a txt file, we can export/import python data
|
|---|
| 59 | structures (like lists or dicts) easily into a text-like file. This means that
|
|---|
| 60 | we can still edit the file using a text editor, or check its contents using
|
|---|
| 61 | *cat*, *head* or *tail*, but we can forget about the parsing of the entries.
|
|---|
| 62 |
|
|---|
| 63 |
|
|---|
| 64 | The tools
|
|---|
| 65 | ---------
|
|---|
| 66 |
|
|---|
| 67 | Stamper_ comes with a variety of tools, but the most used ones are:
|
|---|
| 68 |
|
|---|
| 69 | - **stamp:** Use this to *stamp* times into the json file.
|
|---|
| 70 |
|
|---|
| 71 | - **stamps:** USe this to query the json file and obtain information about your
|
|---|
| 72 | stamped times.
|
|---|
| 73 |
|
|---|
| 74 | .. seealso::
|
|---|
| 75 |
|
|---|
| 76 | :doc:using
|
|---|
| 77 |
|
|---|
| 78 |
|
|---|
| 79 |
|
|---|
| 80 | .. _Stamper: https://bitbucket.org/codigo23/stamper
|
|---|
| 81 | .. _stamp: http://repos.betabug.ch/stamp
|
|---|
| 82 | .. _`Sascha Welter`: http://betabug.ch
|
|---|
| 83 | .. _`betabug`: http://betabug.ch
|
|---|
| 84 | .. _python: http://python.org
|
|---|
| 85 | .. _JSON:
|
|---|
