API Reference

Sample code to illustrate Tracklr code functionality using a demo iCalendar feed.

>>> from tracklr import Tracklr
>>> t = Tracklr()
>>> t.__version__
'0.9.0'
>>> report = t.get_report(None, None, None, None)
>>> t.total_hours
25.0
>>> 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

Tracklr

class tracklr.Tracklr

Tracklr loads events recorded in iCalendar feeds and uses them to create reports.

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(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_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, url, username=None, password=None, title=None, subtitle=None)

Loads calendar URL which can use BasicHTTPAuth.

get_logger()

Sets up logger

get_parser(parser)

Returns parser with Tracklr’s arguments:

  • -k --kalendar specify calendar to use. default calendar is used otherwise
  • -d --date date pattern eg. 2019, 2019-01
  • -t --title report title, or title from the config is used
  • -s --subtitle report subtitle, or subtitle from the config is used
  • -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 “#tag”
get_pdf_output_file(file=None)

Return file is one is provided to input, or defaults to self.pdf_output_file = "report.pdf".

get_report(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_tags(calendar, date_pattern, include, exclude)

Generates tags report in format:

tag, hours

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_tags(summary)

Parses given event summary and returns all #hashtags found.

x_wr_timezone(calendar)

Use this for feeds that use non-standard X-WR-TIMEZONE for timezones.

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/

ls

class tracklr.ls.Ls(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()

Generates HTML version

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
  • -r --report {ls, tag} pdf of ls (default) or tag
take_action(parsed_args)

Generates report as a PDF file.

tag

class tracklr.tag.Tag(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.

show

class tracklr.show.Show(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)

Show configuration details.