API Reference#
Sample code to illustrate Tracklr
code functionality using a demo iCalendar feed.
>>> from tracklr import Tracklr
>>> t = Tracklr()
>>> t.__version__
'1.5.2'
>>> report = t.get_report(None, None, None, None, None)
>>> t.total_hours
47.0
>>> for event in report:
... print("{} | {} | {}".format(event[0], event[1], event[3]))
...
...
2019-02-09 | @Tracklr #v0.1.0 | 4.0
2019-02-15 | @Tracklr #v0.1.0 | 0.5
2019-02-15 | @Tracklr #v0.2.0 | 2.0
2019-02-19 | @Tracklr #v0.2.0 | 1.0
2019-02-20 | @Tracklr #v0.2.0 | 0.5
2019-02-21 | @Tracklr #v0.3.0 | 1.0
2019-02-22 | @Tracklr #v0.3.0 | 1.0
2019-02-22 | @Tracklr #v0.4.0 | 2.0
2019-02-23 | @Tracklr #v0.5.0 | 2.0
2019-03-01 | @Tracklr #v0.6.0 | 1.0
2019-03-01 | @Tracklr #v0.6.0 | 1.0
2019-03-29 - 2019-03-30 | @Tracklr #v0.7.0 | 6.0
2019-05-03 | @Tracklr #v0.8.0 | 2.0
2019-06-04 | @Tracklr #v0.9.0 | 1.0
2019-06-10 | @Tracklr #v0.9.1 | 0.5
2019-06-10 | @Tracklr #v0.9.2 | 1.0
2019-07-26 | @Tracklr #v0.9.3 | 0.5
2019-08-16 | @Tracklr #v0.9.3 | 2.0
2019-11-20 | @Tracklr #v0.9.4 | 1.0
2019-12-24 | @Tracklr #v0.9.5 | 2.0
2019-12-25 | @Tracklr #v1.0.0 | 2.0
2019-12-26 | @Tracklr #v1.0.0 | 2.0
2019-12-30 | @Tracklr #v1.0.1 | 2.0
2019-12-31 | @Tracklr #v1.1.0 | 2.0
2020-01-01 | @Tracklr #v1.1.1 | 2.0
2020-01-01 | @Tracklr #v1.1.2 | 1.0
2020-01-04 | @Tracklr #v1.1.3 | 2.0
2020-01-04 | @Tracklr #v1.2.0 | 2.0
>>>
Version v0.7.0
event does not look correct, because it spans across two days and it should not, because the event is set to 2019-03-30 in the calendar.
Tracklr Demo is a Google Calendar feed which uses X-WR-TIMEZONE
to store the timezone information so to get a correct report, timezone
needs to be set to True
:
>>> t.calendars['default']['timezone']
Traceback (most recent call last):
File "<input>", line 1, in <module>
t.calendars['default']['timezone']
KeyError: 'timezone'
>>> t.calendars['default']['timezone'] = True
>>> report = t.get_report(None, None, None, None)
>>> for event in report:
... print("{} | {} | {}".format(event[0], event[1], event[3]))
...
...
2019-02-09 | @Tracklr #v0.1.0 | 4.0
2019-02-16 | @Tracklr #v0.1.0 | 0.5
2019-02-16 | @Tracklr #v0.2.0 | 2.0
2019-02-20 | @Tracklr #v0.2.0 | 1.0
2019-02-21 | @Tracklr #v0.2.0 | 0.5
2019-02-22 | @Tracklr #v0.3.0 | 1.0
2019-02-22 | @Tracklr #v0.3.0 | 1.0
2019-02-23 | @Tracklr #v0.4.0 | 2.0
2019-02-24 | @Tracklr #v0.5.0 | 2.0
2019-03-01 | @Tracklr #v0.6.0 | 1.0
2019-03-02 | @Tracklr #v0.6.0 | 1.0
2019-03-30 | @Tracklr #v0.7.0 | 6.0
2019-05-04 | @Tracklr #v0.8.0 | 2.0
2019-06-04 | @Tracklr #v0.9.0 | 1.0
2019-06-10 | @Tracklr #v0.9.1 | 0.5
2019-06-10 | @Tracklr #v0.9.2 | 1.0
2019-07-27 | @Tracklr #v0.9.3 | 0.5
2019-08-17 | @Tracklr #v0.9.3 | 2.0
2019-11-20 | @Tracklr #v0.9.4 | 1.0
2019-12-24 | @Tracklr #v0.9.5 | 2.0
2019-12-25 | @Tracklr #v1.0.0 | 2.0
2019-12-27 | @Tracklr #v1.0.0 | 2.0
2019-12-30 | @Tracklr #v1.0.1 | 2.0
2019-12-31 | @Tracklr #v1.1.0 | 2.0
2020-01-01 | @Tracklr #v1.1.1 | 2.0
2020-01-01 | @Tracklr #v1.1.2 | 1.0
2020-01-04 | @Tracklr #v1.1.3 | 2.0
2020-01-05 | @Tracklr #v1.2.0 | 2.0
>>>
Alternatively, timezone
can be explicitly set as well:
>>> t.calendars['default']['timezone'] = 'Pacific/Auckland'
>>> report = t.get_report(None, None, None, None)
>>> for event in report:
... print("{} | {} | {}".format(event[0], event[1], event[3]))
...
...
2019-02-09 | @Tracklr #v0.1.0 | 4.0
2019-02-16 | @Tracklr #v0.1.0 | 0.5
2019-02-16 | @Tracklr #v0.2.0 | 2.0
2019-02-20 | @Tracklr #v0.2.0 | 1.0
2019-02-21 | @Tracklr #v0.2.0 | 0.5
2019-02-22 | @Tracklr #v0.3.0 | 1.0
2019-02-22 | @Tracklr #v0.3.0 | 1.0
2019-02-23 | @Tracklr #v0.4.0 | 2.0
2019-02-24 | @Tracklr #v0.5.0 | 2.0
2019-03-01 | @Tracklr #v0.6.0 | 1.0
2019-03-02 | @Tracklr #v0.6.0 | 1.0
2019-03-30 | @Tracklr #v0.7.0 | 6.0
2019-05-04 | @Tracklr #v0.8.0 | 2.0
2019-06-04 | @Tracklr #v0.9.0 | 1.0
2019-06-10 | @Tracklr #v0.9.1 | 0.5
2019-06-10 | @Tracklr #v0.9.2 | 1.0
2019-07-27 | @Tracklr #v0.9.3 | 0.5
2019-08-17 | @Tracklr #v0.9.3 | 2.0
2019-11-20 | @Tracklr #v0.9.4 | 1.0
2019-12-24 | @Tracklr #v0.9.5 | 2.0
2019-12-25 | @Tracklr #v1.0.0 | 2.0
2019-12-27 | @Tracklr #v1.0.0 | 2.0
2019-12-30 | @Tracklr #v1.0.1 | 2.0
2019-12-31 | @Tracklr #v1.1.0 | 2.0
2020-01-01 | @Tracklr #v1.1.1 | 2.0
2020-01-01 | @Tracklr #v1.1.2 | 1.0
2020-01-04 | @Tracklr #v1.1.3 | 2.0
2020-01-05 | @Tracklr #v1.2.0 | 2.0
>>>
Tracklr#
- class tracklr.Tracklr#
Tracklr loads events recorded in iCalendar feeds and uses them to create reports.
- add_event(calendar, begin_dt, end_dt, name, description)#
Adds event to given calendars which can use BasicHTTPAuth.
Notes: * vdir calendars are not supported * calendars without username/password are not supported
- banner(kalendar, title=None, subtitle=None, use_figlet=True)#
Displays base information about the Tracklr instance.
- configure()#
Tries to load Tracklr configuration from current working directory then user config directory and if none found it defaults to internal configuration stored in
Tracklr.__config__
.Once config loaded, processes
calendars
list from the config and handles various configuration options.
- filter_event(key, event, date_pattern, include, exclude)#
Decides whether the event should be included or excluded.
- get_auth(username, password)#
Returns
HTTPBasicAuth
for providedusername
andpassword
.
- get_base_parser(parser)#
Returns parser with base Tracklr’s arguments:
-k
--kalendar
specify calendar to use. default calendar is used otherwise-t
--title
report title, or title from the config is used-s
--subtitle
report subtitle, or subtitle from the config is used
- get_calendar(calendar)#
Loads multiple calendars which can use BasicHTTPAuth.
- get_calendar_config(calendar)#
Returns given calendar config or raises exception if none found.
- get_event_date(event, format='%Y-%m-%d')#
Returns dates(s) of given event.
- get_event_length(event)#
Calculates length of an event.
- get_feed(name, location, username=None, password=None, title=None, subtitle=None)#
Loads calendar URL which can use BasicHTTPAuth.
- get_matches(key, calendar, date_pattern, include, exclude)#
Generates matches report in format:
match, hours
- get_parser(parser)#
Returns parser with base Tracklr’s arguments:
-k
--kalendar
specify calendar to use. default calendar is used otherwise-t
--title
report title, or title from the config is used-s
--subtitle
report subtitle, or subtitle from the config is used
And with additional ls/pdf/group arguments:
-d
--date
date pattern eg. 2019, 2019-01-g
--group
extracts groups of keywords from events that match given group identifier eg. -g @ for parsing out targets, -g # for parsing out hastags, -g $ for parsing out monies.-i
--include
include patterns. Tags need to be in quotes. Eg. -i @Tracklr “#v0.7”-x
--exclude
exclude patterns. Tags need to be in quotes. Eg. -x “#hashtag”
- get_report(key, calendar, date_pattern, include, exclude)#
Generates timesheet report in format:
date, summary, description, hours
- get_subtitle(calendar, subtitle)#
Handles title of the provided calendar.
Title is optional in the configuration so default title is “Command-line Productivity Toolset”.
- get_title(calendar, title)#
Handles title of the provided calendar.
Title is optional in the configuration so default title is “Tracklr”.
- get_titles(calendar, title, subtitle)#
Returns “title - subtitle” string.
- parse_summary(key, summary)#
Parses given event summary and returns all strings that begin with given key found.
- set_timezone(name)#
Use this for feeds that use non-standard
X-WR-TIMEZONE
for timezones, or when a feed needs to apply specific timezone.TL;DR
X-WR-TIMEZONE
is NOT part of RFC 5545.For more info see: https://blog.jonudell.net/2011/10/17/x-wr-timezone-considered-harmful/
init#
- class tracklr.init.Init(app, app_args, cmd_name=None)#
- create_file(parsed_args, file_path, file_name, file_content)#
Creates desired file at given path with given content.
- create_file_type(parsed_args, file_name, file_content)#
Handles creation of given file.
- get_description()#
initializes
tracklr.yml
andpdf.html
- get_parser(prog_name)#
Adds two arguments:
action
- inits eitherconfig
ortemplate
--user-config-dir
- use this option to generate file in user config directory instead of current directory
- init_config(parsed_args)#
Creates local or global config.
- init_template(parsed_args)#
Creates local or global template.
- take_action(parsed_args)#
Creates
tracklr.yml
andpdf.html
out of defaults in:user config directory
local directory
info#
- class tracklr.info.Info(app, app_args, cmd_name=None)#
- get_description()#
Return the command description.
The default is to use the first line of the class’ docstring as the description. Set the
_description
class attribute to a one-line description of a command to use a different value. This is useful for enabling translations, for example, with_description
set to a string wrapped with a gettext translation marker.
- get_parser(prog_name)#
Return an
argparse.ArgumentParser
.
- take_action(parsed_args)#
Display information about the current instance.
ls#
group#
- class tracklr.group.Group(app, app_args, cmd_name=None)#
- get_description()#
Return the command description.
The default is to use the first line of the class’ docstring as the description. Set the
_description
class attribute to a one-line description of a command to use a different value. This is useful for enabling translations, for example, with_description
set to a string wrapped with a gettext translation marker.
- get_parser(prog_name)#
Return an
argparse.ArgumentParser
.
- take_action(parsed_args)#
Generates report and logs total number of hours.
pdf#
- class tracklr.pdf.Pdf(app, app_args, cmd_name=None)#
- generate_html(pdf_template_file)#
Generates HTML version of the report using given template.
- generate_pdf(in_html, out_pdf)#
Generates PDF from HTML version
- get_description()#
creates PDF report
- get_parser(prog_name)#
Defines the following input arguments for
pdf
command:-f
--file
destination of the pdf file-e
--template
destination of the html template file-r
--report
{ls, group} pdf ofls
(default) orgroup
- take_action(parsed_args)#
Generates report as a PDF file.