Package: miteclock
miteclockA command-line formitethat gets out of your way!Do you track time in mite, but wish you could control the clock with a few keystrokes
from the nearest terminal window? Then give miteclock a try!MotivationThe goal of this program is to address aspects of using mite that I, as a terminal and
keyboard user, have found inconvenient in daily use:Having to search for the mite browser tab or opening a new one when I always have
terminal windows handy.Having to switch between mouse (for projects/services) and keyboard (for notes) to
create an new entry.Surprising narrow-by-typing behavior in the projects/services menus.Inflexible support for templates, no ability to compose an entry from pre-defined
parts.Seeherefor more context.Installation and SetupThis program is tested with Python versions 3.7-3.11. To minimize "works on my machine"
problems, the dependencies have been pinned to specific versions. Therefore it'sstrongly recommendedto install it in a dedicated virtualenv and then add a symbolic
link to the executable somewhere in yourPATH. An even better option is to use thepipxwrapper which automatically takes care of
these two steps.Install with a standard pip command:pipinstallmiteclockNow you should be able to run the following in your terminal:mThe first time you run it, it will prompt you for your account information and create aTOMLconfiguration file in your home directory
named~/.config/miteclock/config.toml. Then it will show you the help message for the
program. This message and the help for sub-commands should provide enough general
documentation, so the rest of this README is a tutorial to get you started.TutorialControlling the ClockThere are only two commands to interact with the timer:m startstarts a clock,m stopstops it. That's it,that simple.m stopis self-explanatory (run it with--help), so here we focus onm start.Tracking a New EntryLet's say your mite account has the following projects:ACME – Self-healing container deploymentsOCP: ED-209CHAZ 2020In these projects you perform the following services (Dienstleistungen):DevelopmentRegular MaintenanceIrregular MaintenanceQABackend QAFrom your experience with the mite webapp, you know that a time entry has the following
three fields:projectservicenoteWhat if instead of selecting the project and the service from a drop-down you did so by
pressing just one key? This is much faster, especially if you have more realistic (i.e.
larger) sets of projects and services that you'd have to sift through with the
drop-down.These keys are known as shortcuts and you can define them in your configuration file.
For our example here, let's create a few mappings from keys to project/service names. We
open our~/.config/miteclock/config.tomlin a text editor and add the following in the[shortcuts]table:[shortcuts]# Shortcuts for projects.a="ACME -- Self-healing container deployments"o="OCP: ED-209"h="CHAZ 2020"t="Team-Internal"#  Shortcuts for services.d="Development"r="Regular Maintenance"i="Irregular Maintenance"c="Communication/Coordination"Now we can add an activity and start the clock for it with this one command:mstartad'writing some code'The first two arguments tostartare expanded into "ACME – Self-healing
container deployments" and "Development" respectively. The last argument is the note. We
put it in quotes so that it is treated as a single argument.Note thatorder mattersfor the expanded items. Itmustbe like in the webapp:projectservicenoteIf you want to leave any field unspecified, enter an empty string for it. For example if
you're working for "ACME" but haven't narrowed your work down to an exact service or
task, run this:mstarta''''Leaving notes empty and filling them out later is so common, that an empty note can be
completely omitted. We can shorten the command above to:mstarta''Another way to avoid writing out a note is to put it into a shortcut definition. This
works well for recurring meetings or tasks where the note stays the same. Let's add some
shortcuts that describe recurring activities for many programmers:daily=["t","c","daily stand-up"]retro=["t","c","retrospective"]server=['a','r',"regular server maintenance"]Notice how we used the shortcuts we had already defined to create new shortcuts?It's
shortcuts all the way down!These nested shortcuts can span anyconsecutivepart of an activity definition. This
is valid…kickoff=["c","kickoff meeting for project"]… and can be used with all your projects, for example:mstarthkickoff# Tracks kickoff meeting for CHAZ 2020mstartokickoff# Tracks kickoff meeting for OCP: ED-209This is also valid:acmedev=["a","d"]This, however, is invalid:invalid=["a","some ACME-related note"]Resume Tracking an Existing EntryOften you might have to stop the clock for some activity and then start it back up
later.If you have clocked in some entries for the day and runm startwithout any arguments,
you will be presented with a list of the activities you recorded for the day paired with
keys you can press to select one of the entries. Note that unlike in the mite webapp,
time entries are sorted by the time they were updated last not by the time when they
were created.You can skip this menu by passing the-lflag (or--lastif you like typing) which
automatically starts the last entry for which you had a clock running.You can even run the same exact command a second time, e.g.mstartad'writing some code'# ... some other commands...mstartad'writing some code'There is alsom resumewhich is just an alias form start -l.Reporting Commandsm statuswill report the current status of the tracker: whether or not the clock is
running and for which entry, which entries have been created today.m showshows you a list of shortcuts.m show projectsshows the projects your
account has access to.m show servicesdoes the same for services. Note that the list
of projects can be long enough that you may want to save it to a file or filter it withgrep.Advanced Activity DefinitionsSo far we have not discussed how we match shortcuts for projects and services to the
right entries in your mite account. Let's say we expand the shortcutd = "Development". Based on its position we know it is a service, so we search all
services associated with your mite account. We collect those servicesthat containthe"Development"in them. If we collect exactly one service, we specify it in the
time entry. Otherwise we have to change the shortcut definition to address one of two
issues: either the shortcut matched multiple entries or it did not match any entries at
all.This works fine for most cases, especially if we use the complete name of a service. It
fails, however, for the following service from our example:"QA". This is because its
full name is contained in another service"Backend QA", so we will always match both
with a definition likeq = "QA".What we would like is a way to say that service names muststrictly matchthe
shortcut definition. Exactly for these cases there is another way to specify shortcut
expansions. The form we have been using so far is actually a shorthand for the
following:q={pattern="QA",match="substring"}To switch to strict matching, we change the value ofmatch:q={pattern="QA",match="strict"}The process of matching projects is the same with one addition. In mite it is possible
for projects to have the same names and differentcustomers. For instance, you may be
building a prototype for two companies, so your projects would be:Prototype (ACME Inc.)Prototype (King Inc.)In this case you could define the following shortcuts:pa={project="Prototype",customer="ACME"}pk={project="Prototype",customer="King"}If you need support for strict matches for either the project name or the customer name,
you can use all that was mentioned above, just place it in theprojectandcustomerkeys:pa={project={pattern="Prototype",match="strict"},customer={pattern="ACME",match="strict"}}Expanding the contents of theprojectandcustomerkeys is currently not supported.
In other words, this won't work:a="ACME"pa={project="Prototype",customer="a"}ContributingIf you find a problem with the program, please open an issuehere.If you want to submit changes, fork this repo, create a branch in your fork that
contains your work, open a pull request against themasterbranch in this repo.For local development, install the dependencies usingpoetry.poetryinstall
poetryrunpre-commitinstallPlease make sure to add tests for any code changes. Assuming the commands above
succeeded, run this:poetryrunpytestYou can also usetoxto test your changes against all supported Python versions:poetryruntoxWhy yet another mite CLI?There already are almost half a dozen command-line interfaces in several languages
(Ruby,JavaScript,Go,Python). There's even aPHP wrapper library. What is the need for yet
another cli?I find that all the existing interfaces provide both too much functionality and too
little. They try to cover allpossibletasks, exposing all the gory details of the
underlying data along the way. If you regularly import and export time records or manage
projects and services for an account, these tools can be very helpful.The way most of us use mite though is to start and stop the clock for activities "on the
go" throughout the day. This takes advantage of mite's built-in tracking capabilities. A
lot of the activities are recurring, like check-in meetings with clients or team
members. Moreover, most activities on a given day revolve around a handful of projects
and services.This program aims to reduce the book-keeping cost of specifying activities. It lets the
user focus on their work while instructing mite to do what it does best: track time. We
deliberately expose a simple interface and deal only in relevant concepts.AcknowledgementsThis project would not have been possible at all without the folkswho run mitemaking their API accessible. Many thanks to them for
that. I am also grateful to the people who wrote client libraries and cli tools based on
the API. This provided context to my efforts and thus helped me define what I wanted to
focus on.LicenceMIT