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.