Package: toggl-fetch
toggl-fetchmakes it easy to periodically retrieve summary reports for aTogglworkspace.Doing that manually is tedious: Each time you need to generate a new report, you need to remember on what date
the previous report ends – so that you can let the new report start on the correct date.toggl-fetchtakes
care of remembering that piece of information and downloading the report for you.ContentsOperation overviewInstallationA short how-toObtaining a Toggl API tokenGenerating the first reportGenerating subsequent reportsDetailed usageSpecifying an output file templateUsing a configuration fileVersion historyVersion 1.0.1Version 1.0.0Operation overviewThe first time you fetch a report for a workspace usingtoggl-fetch, you need to tell it on what date the report
should start. If you don’t specify a start date, thentoggl-fetchlets the report start four weeks ago.Optionally, you can specify the date the report should end (herafter simply called the “end date”). If you don’t
specify an end date,toggl-fetchuses today’s date.Being given this information,toggl-fetchdownloads the report as a PDF file and stores it on your computer.
It also remembers the “end date” for the report; it does that separately for each workspace, so you can use it for
multiple workspaces.Now, the next time you usetoggl-fetchto fetch a report for the workspace, you can omit the start date.toggl-fetchthen adds one day to the saved “end date” (which it stored the last time you fetched a report)
and uses the result as the new start date for the report. It then remembers the “end date” for the current report so
that it can use that information the next time you usetoggl-fetch.NoteBoth the “start date” and the “end date” are treated asinclusivedates; that is, the generated reports willincludedata for the specified dates.InstallationYou can installtoggl-fetchusingpip:pip install toggl-fetchA short how-toObtaining a Toggl API tokentoggl-fetchneeds a Toggl API token in order to log in to your Toggl account. You can obtain the API token
for your account at the end of yourprofile page.For the following examples, let’s assume that you API token is9fc1632af9abac871694d49727685b90.Generating the first reportHaving obtained an API token, you can now generate your first report. To do that, you need to know the name of the
workspace you want to generate a report for; let’s assume it to be “John Doe’s workspace”. Also, the report should
begin on 2016-01-01 and end on today’s date (since the latter is the default, you don’t need to specify an
end date).To download the report as a PDF file into your current working directory, execute the
following command:toggl-fetch --api-token 9fc1632af9abac871694d49727685b90 --workspace "John Doe's workspace" --start-date 2016-01-01That’s it. Provided that the API token is valid and a workspace with the specified name exists, you should now
find the report as a PDF file namedsummary_<end_year>-<end_month>.pdfin the current working directory
(seeSpecifying an output file templateto learn how to change that filename).Generating subsequent reportsNow that you have generated your first report, generating subsequent reports is as easy as running the following
command:toggl-fetch --api-token 9fc1632af9abac871694d49727685b90 --workspace "John Doe's workspace"Note that we omitted the start date – this makestoggl-fetchcalculate it from the “end date” it stored when you
generated the last report (which in this case, was the first report ever generated).This again will download the report to a file namedsummary_<end_year>-<end_month>.pdfin your current
working directory (see alsoSpecifying an output file template).Detailed usageTo view all the command line arguments accepted bytoggl-fetch, simply do:toggl-fetch --helpSpecifying an output file templateBy default, the report is downloaded into the current working directory as a file namedsummary_<end_year>-<end_month>.pdf, whereend_yearandend_monthare taken from
the end date of the report.This filename template can be changed using the--outputoption. It takes a relative or absolute filename
as an argument; the special placeholders{start_date}and{end_date}are replaced to produce the name of
the output file.The default template issummary_{end_date:%Y}-{end_date:%m}.pdf. Here,{end_date}is used twice, but
each of the two placeholders contains a different string after the colon: This is a date format specification
specifying how to format the end date. In this case, the placeholder{end_date:%Y}is replaced by the
year of the end date and the placeholder{end_date:%m}is replaced by the month of the end date.The Python documentation contains alist of valid date format codeswhich can be used in the date format
specification. For example, the two{end_date}placeholders above could be replaced with a single placeholder{end_date:%Y-%m}to produce the same result.Using a configuration fileSpecifying the workspace name, your API token and maybe even an output file template each time you usetoggl-fetchis annoying. You can avoid having to specify options on the command line by placing them in a configuration file
instead.toggl-fetchfollows theXDG Base Directory Specification. In most cases, this means you can place a configuration
file in~/.config/toggl-fetch/config.iniandtoggl-fetchwill find it.Taking the command line parameters used inA short how-toas an example, a valid configuration file would look like
this:[options]api_token=9fc1632af9abac871694d49727685b90workspace=John Doe's workspaceSpecifying these two options in the configuration file is enough to be able to runtoggl-fetchwithout having to
specify any command line options.All command line options can be used in the[options]section. Command line parameters without a value
(like--force) can be set by simply using the option name without a value, like this:[options]forceWarningThis is only an example. Placing theforceoption in the configuration file isdiscouragedfor obvious
reasons.Lines starting with optional whitespace followed by either#or;are treated as comments and are ignored.NoteInline comments (comments at the end of non-empty lines) arenotsupported.Version historyVersion 1.0.1Fix: Add forgotten short option-Vas a counterpart to--version.Fix: Document return codes for themain()function.Fix:User-Agentheader: Add our version number and correctly format our URL.Version 1.0.0Initial release.