API Reference

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

>>> from tracklr import Tracklr
>>> Tracklr.__version__
'0.7'
>>> t = Tracklr()
>>> report = t.get_report(None, None, None, None)
>>> t.total_hours
19.0
>>> for event in report:
...     print("{} | {} | {}".format(event[0], event[2], event[3]))
...
...
2019-02-09 | Worked on initial version of https://gitlab.com/markuz/tracklr | 4.0
2019-02-15 | * fixed timesheet sorting
* fixed possible missing description/summary in ical feeds
* refactored logging
* started on v0.2 ie. multi calendar support | 2.0
2019-02-15 | Testing tracklr v0.1 with Ivan and Tomas | 0.5
2019-02-19 | v0.2 - support of mutliple calendars | 1.0
2019-02-20 | worked on multi-calendar support | 0.5
2019-02-21 | v0.3 - finished off implementation to support multiple calendars | 1.0
2019-02-22 | v0.3 tidy ups | 1.0
2019-02-22 | v0.4 added ``tracklr init {config,template}`` command for easy custom
configuration of tracklr | 2.0
2019-02-23 | v0.5:
* added ``tracklr show`` command that displays configuration
* made configuration simpler
* expanded documentation | 2.0
2019-03-01 |  | 1.0
2019-03-01 | v0.6 | 1.0
2019-03-29 | * refactored the code base so that it is more generic (no more client, project,
tag) include and exclude patterns
* exclude patterns now can be used for filtering
* new internal pdf report
* tracklr pdf --report {ls, tag} can be now used to choose between ls and tag report in pdf
format
* documentation updates | 3.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.

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.