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 provided username and password.

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 and pdf.html

get_parser(prog_name)

Adds two arguments:

• action - inits either config or template

• --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 and pdf.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

class tracklr.ls.Ls(app, app_args, cmd_name=None)

get_description()

Returns command description

get_parser(prog_name)

Gets default parser ie. this command does not add any new args

take_action(parsed_args)

Generates report and logs total number of hours.

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 of ls (default) or group

take_action(parsed_args)

Generates report as a PDF file.