Package: haunts
Table of ContentsWhat it doesHow to installPrerequisitesHow to useUsage by examplesHow it worksSheet definitionConfiguring projectsHow events will be filledActionsReporting featureTODO and known issuesWhy?!OK, but why “haunts”?!RoadmapCreditsHistory0.6.0 (2023-03-31)0.5.0 (2022-12-04)0.4.0 (2022-12-01)0.3.1 (2022-11-21)0.3.0 (2022-05-02)0.2.1 (2022-02-10)0.2.0 (2021-07-29)0.1.0 (2021-07-10)What it doesFill Google Calendars with events taken from a Google Spreadsheet.How to installpipinstallhauntsPrerequisitesTo use Google Calendar and Google Spreasheet APIs you must generate a Google API application and download acredentials.json:Runhaunts--config. It will create the~/.hauntsfolder and anhaunts.inifile inside it.Edit thehaunts.inifile by setting theCONTROLLER_SHEET_DOCUMENT_IDGo tohttps://console.cloud.google.com/home/dashboardand create a Project calledhaunts.In the search bar, searchCredentials APIs and servicesand enable it.Click onCreate Credentials, setDesktopas thetypeand save the json file as~/.haunts/credentials.json.In the search bar, searchGoogle Sheets APIandGoogle Calendar APIand activate them.Runhauntsnormally.
It will ask you to authenticate to both the Google Sheets and the Google Calendar APIs (a browser should be automatically opened for you).
This action will create the following files:~/.haunts/calendars-token.jsonand~/.haunts/sheets-token.jsonHow to useCommand line help is accessible using:haunts--helpUsage by examplesTo sync every available entry in a sheet named “May”:hauntsMayTo limits sync to events on a limited set of days:haunts--day=2021-05-24--day=2021-05-25--day=2021-05-28MayTo also limits sync to some projects (calendars):haunts--day=2021-05-24--day=2021-05-25--day=2021-05-28--project="Project X"MayTo execute only on rows where a “delete” action is defined (see “Actions” below):haunts--day=2021-05-24--day=2021-05-25--day=2021-05-28--project="Project X"-aDMayTo get the report instead of running calendar sync:haunts--executereport--day=2021-05-24--day=2021-05-25--day=2021-05-28--project="Project X"MayTo just report overtime entries in the set:haunts--executereport--day=2021-05-24--day=2021-05-25--day=2021-05-28--project="Project X"--overtimeMayHow it worksWhat haunts does depends on the--executeparameter.In its default configuration (if--executeis omitted, or equal tosync), the command will try to access a Google Spreatsheet you must have access to (write access required), specifically: it will read a single sheet at time inside that spreadsheet.
Every row inside this sheet is an event that will be also created on a Google Calendar.Alternatively you can provide--executereport.
In this case it just access the Google Spreadsheet to collect data.Sheet definitionThe referenced sheet must contains a set of columns. Headers names are important but orders matters not.
Any additional columns will be ignored.Anexample sheetis provided.The partition in multiple sheets is designed to keep every month in a separate sheet, but this is not strictly checked.Every sheet should contains following headers:Date(date)The day where the event will be created. If the date is not found, the line will be treated as an empty line (so: skipped)Start time(time string in formatHH:MMor empty) -optional columnIf provided, the current event will start at given time. This will influence also events defined after this rowSpent(number or empty)How long the event will last. Leave empty to create a full-day event.When executiing the report, full day event length is influences byOVERTIME_FROMconfiguration optionProject(string)Project name as it’s named in theconfigsheet (see below)Activity(string)Summary of the eventDetails(string, optional)Additional text for the event descriptionEvent id(string)Leave this empty. It will be filled with the id of the generated eventLink(text)Leave this empty. It will be filled with a link to the event inside Google CalendarAction(chars)See below. If empty: it will be filled with anIwhen an event is created from this rowConfiguring projectsThe spreadsheet must also contains aconfiguration sheet(default name isconfig, can be changed in the .ini) where you must put two columns (with headers):idThe id of a Google Calendar associated to this project.
You must have write access to this calendar.nameThe name of the project, like an alias to the calendarA project name can be associated to the same calendar id multiple times.Values in thenamecolumn are the only valid values for theProjectcolumn introduced aboveHow events will be filledLet says you run something like this:haunts--day=2021-07-08Julyhauntswill access the sheet namedJulyin the spreadsheet configured in the .ini file.
Only rows where theDatefiled will match the--dayparameter will be considered (if this param is not provided: the full sheet content is analyzed).For every rows that match,hauntswill:Generate a new event, starting from a default time (this can be configured in the .ini).
The event will last forSpenthoursThe next event will start where the previous endedIf the event will be successfully created, an “I” will be placed in theActioncolumn.
This will make future executions to ignore the line.Other columns will be read or filled as described above.ActionsPossible values you can find (or type yourself) in theActioncolumn:Iignore: execution will just ignore this line. This is commonly automatically filled by haunts itself, but you can add this value manually to ignore the line. Example: for events you already have on calendar but you want to track on the spreadsheet too.IIignore all: same asI, but also ignore rows in the--execute=reportmodeDdelete: execution will clearAction,Event idandLinkcells for this row, and delete the related event on the Google Calendar.
As alsoActionis cleared, next execution will likely fill this line again. Use this as a poor-man-edit, to change something on the event.When syncing a calendar (--execute=sync) you can use this column to filter on which rows execute sync by providing the--actionoption. For example:haunts--actionDJulyThis will sync only rows where the “Action” column contains the delete (D) value.Reporting featureUsinghaunts-ereport <SHEET_NAME>will read the source Spreadsheet to collect statistical data.Both-pand-dparameters are allowed.The resulting table can be something like the following:Date        Project      Total
----------  ---------  -------
2022-11-20  Calendar1        2
2022-11-20  Calendar2        1
2022-11-21  Calendar2        5
2022-11-21  Calendar3        3
2022-11-23  Calendar1       10
2022-11-24  Calendar1        8
2022-11-26  Calendar4        9
2022-11-27  Calendar4        8
2022-11-27  Calendar5        1
----------  ---------  -------
                            47For every calendar and day found in the sheet, it report a total of hours spent.Full day events are taken into account, and the overwork is also supported by configuring bothOVERTIME_FROM(default is: no overwork support) andWORKING_HOURS(default is: 8).If you want to report overtime, you can use the--overtimeflag, and only overtime rows will counted.TODO and known issuesrows in the sheet must be sorted ascendinghauntswill not check for already filled time slots (yet?), so overlapping of events may happens-ereportis calculating values on Python side, you know… we have a more reliable spreadsheet there-ereportis counting overtime based on “Start time” column, while it’s probably better to read start dates from eventsWhy?!InB-Openthis is how we register our worklogs, participation to projects in multiple Google Calendars.OK, but why “haunts”?!An haunt is a monster fromDungeons&Dragons, which is translated in the italian version of the game as “Presenza”.But “presenza” is the same term used in italian for “participation”, so how we call our worklogs.And filling worklogs haunt us.RoadmapThe following (ambitious) roadmap is based on the maturtiy level of the software, no timeline available yet.AlphaFill worklogs in my placeBetaIntegration with GitHib Copilot, to write code for meProduction/StableIntegration with GTP-4, to reply to collegues on Slack in my placeMatureProfitInactive(I mean me… not the software)CreditsDevelopers and contributors.keul (main-worklogs-hater)francesconazzaro (how-to-use-google-api-evangelist)gcammarota (reporting-tool-guy)History0.6.0 (2023-03-31)AddedIIaction0.5.0 (2022-12-04)Renamed--actionto--executenew option:--actionto filter by values on “Action” columnnew option:--overtimeto just report overtime amount0.4.0 (2022-12-01)Added-pparameter, to just act on specific project(s)Added--action, and implementedreportaction (credits to @gcammarota)More detailed logging when deleting events with actionD0.3.1 (2022-11-21)bugfix: if a row uses anIaction, everything there is ignoredWhen a project is not found: do not stop haunts but skip the line and report that when execution ends.
Closes #14Empty lines now supported.
Closes #12Human readable error message when the sheet is not found.
Closes #110.3.0 (2022-05-02)Fixed:START_TIMEdefault was not used.
Closes #4New: new action:DNew: added “Start time” feature.
Closes #7Fix: reduces number of writes.
Closes #6Fix: do not fail badly when max number of requests per minutes is reached.
See #1New: added “–config” for initial env configuration, improved documentation0.2.1 (2022-02-10)Fixed full day criteria0.2.0 (2021-07-29)Added support for full-day event0.1.0 (2021-07-10)Initial release