Package: timewarrior-balance
Contents1Introduction2Install2.1Using the source directly2.2Using pip3Usage3.1Calling the extension3.2Details about interpretation of intervals3.3Configuration file3.3.1Periodic Blocks3.3.2Date entries4License1IntroductionThis is atimewarriorextension for generating a report providing a balance
between hours your worked and hours you have planned to work. This primarily
is intended for users that have a flexible work hours regime and want to keep
track of the balance between allotted time (hours to worked) and time actually
spent (worked hours).Below is an example of a call to the extension:$ timew bal :week
Start: Mon Oct  4 00:00:00 2021
  End: Mon Oct 11 00:00:00 2021

  Tag  Spent  Allotted  Balance
───────────────────────────────
 work  36:57     40:00    -4:03
study  11:00     10:00    +1:00
───────────────────────────────
TOTAL  47:58     50:00    -3:02And below is the content of the configuration file for such example:# Hours for the "work" tag
work {
  # Periodic configuration
  from 2021-10-01 {
    mon  11:00
    tue   9:00
    wed   5:30
    thu   6:30
    fri   8:00
  }

  # Individual entries for adjustment
  2021-10-01  8:00 "Adjustment"
  2021-10-12 -8:00 "National holiday"
}

# Hours for the "study" tag
study {
  from 2021-10-01 {
    mon 2:00
    tue 2:00
    wed 2:00
    thu 2:00
    fri 2:00
  }
}2Install2.1Using the source directlyThere are no extra dependencies besides Python 3 for running this extension.
As such, you can just add a script in your timewarrior extensions directory
(usually~/.timewarrior/extensions/) that just runstimewarrior_balance/balance.py.If you are on a regular Unix machine, we provide a wrapper script
(balance.sh) that can be simply be symlinked:$ ln -s $(realpath balance.sh) ~/.timewarrior/extensions/balance2.2Using pipYou can also install the package withpipand add a script in the
extensions directory to callpython-mtimewarrior_balance:$ pip install --user timewarrior-balance
$ echo "python -m timewarrior_balance" > ~/.timewarrior/extensions/balance
$ chmod a+x ~/.timewarrior/extensions/balance3Usage3.1Calling the extensionConsidering that the extension is installed in timewarrior’s extension
directory as a script namedbalanceand that you have already provided aconfiguration file, it is possible to call the
extension to generate the report by callingtimew balance. It is also
convenient to use the abbreviated formtimew balfor cases when there are
no conflict with other installed extensions:$ timew bal
Start: Tue Jan  2 00:00:00 0001
  End: Mon Oct 12 00:00:00 2021

  Tag  Spent  Allotted  Balance
───────────────────────────────
 work  48:30     56:00    -8:30
study  11:00     12:00    -1:00
───────────────────────────────
TOTAL  59:30     68:00    -9:30Bellow is an example of a report for the current week:$ timew bal :week
Start: Mon Oct 11 00:00:00 2021
  End: Mon Oct 18 00:00:00 2021

  Tag  Spent  Allotted  Balance
───────────────────────────────
 work   4:30     32:00   -27:30
study   1:00     10:00    -9:00
───────────────────────────────
TOTAL   5:30     42:00   -36:30It shows that I still have to spend 27.5 hours and 9 hours on work and
studies, respectively (let’s hope this is the beginning of the week 😛).We can also use dates explicitly. Below is the same report using dates:$ timew bal 2021-10-11 to 2021-10-17
Start: Mon Oct 11 00:00:00 2021
  End: Mon Oct 18 00:00:00 2021

  Tag  Spent  Allotted  Balance
───────────────────────────────
 work   4:30     32:00   -27:30
study   1:00     10:00    -9:00
───────────────────────────────
TOTAL   5:30     42:00   -36:30The interval used by the report is parsed by timewarrior, so
you can use anything that is recognized by timewarrior.3.2Details about interpretation of intervalsThe report will count how much time is allotted and how much has been spent
for each configured tag in the interval of the report. The extension uses the
interval the user provided to thetimewcommand (which is parsed directly
bytimewarrioritself). If none is passed, like in the case above, then it
will default to be from0001-01-02until the date-time for when the report
was called.The interval is closed at the beginning and open (i.e. exclusive) at the end.
The amount ofspenttime is done inside that interval by summing up each
track record filtered by Timewarrior. Note that time that is still being
tracked is also taken into account.By default,timewarrior-balanceuses a rounded interval for calculating theallottedtime: the start date-time is rounded down to midnight of its
previous day and the end date-time is rounded up to midnight of its next day.
If that is not desired, you can setround_interval = noin the
configuration file.3.3Configuration fileIn order to use this extension, you need to create a configuration file namedbalance.confand place it under your timewarrior data directory (usually~/.timewarrior/). This configuration file is were you declare the hours
you need to spend on your activities.The configuration file is composed by a series of blocks or variable
assignments.Each block is a configuration for a tag you want to track. It will be
explained in detail later.A variable assignment is a line in the format<varname> = <value>.
Currently, the only variable interpreted bytimewarrior-balanceisround_interval, but others might be added in the future.The example below shows the content a configuration file with two empty
blocks:# Everything from the "#" to the end of line is considered to be a comment

work {
  # This is an example of a configuration block to tracking hours for the
  # "work" tag
}

"tag with multiple words" {
  # You can use double quotes for tags with multiple words
}A block has the form<tag> { <content> }, that is, it is defined with the
name of the tag you want to track followed by the content embraced by a pair
of opening and closing braces.<tag>can be a single word as the tag name or a string enclosed by
double-quotes, which is useful when the tag name contains spaces or is one
of the reserved keywords of balance’s configuration file. You can also use
the token__untagged__in order to provide configuration for untagged
timewarrior records.<content>contains the configuration for the referred tag and may have
two types of things:Pediodic blocks, where you can define the time allotted for each
day of the week;Individualdate entries, which specify allotted times for a specific
day.3.3.1Periodic BlocksBelow are some examples of periodic blocks:"study music" {
  from 2021-10-02 {
    # I'll dedicate 1 and 2½ hours to study music on Mondays and
    # Wednesdays, respectively
    mon 1:00
    wed 2:30
  }

  # I will dedicate a little more time to the activity in December
  from 2021-12-01 to 2022-01-01 {
    mon 1:00
    wed 2:30
    fri 2:00
  }
}

work {
  # Part-time job
  from 2021-01-01 {
    mon 5:00
    tue 4:00
    wed 6:00
    thu 5:00
  }

  # Got a full-time job in April
  from 2021-04-15 {
    mon 8:00
    tue 8:00
    wed 8:00
    thu 8:00
    fri 8:00
  }
}When calculating the amount of allotted time for each tag, based on the
report’s start and end date, the extension calculates the number of matches
possible for each rule and adds the expected time.Below is a more formal-like description of the format.A periodic block has the formfrom<start-date>[to<end-date>]{ <rules> }.<start-date>and<end-date>define the time interval for which
the rules defined in<rules>have effect. The format of a date isYYYY-MM-DD, defining the year, month and day, respectively.  Note
that the interval is inclusive on<start-date>and exclusive on<end-date>.The end date is optional. If omitted, it defaults to(i)the start date
of the next periodic block or(ii)the end date of the report if this
is the last periodic block of the tag block. You can useend of timein order to explicitly have the effect of the latter (useful when the
periodic block is not the last one).<rules>is a list of pairs in the format<weekday> <hours>,
representing the amount of time allotted for days of the week.<weekday>must be one of:mon,tue,wed,thu,fri,satandsun.<hours>is defined by a number of hours optionally followed by:and a number of minutes. Examples:5,2:15,7:00.3.3.2Date entriesBesides describing periodic rules for allotted time, it is also possible
to specify allotted time for specific date viadate entries. This is
specially useful to make exceptions to the rules (e.g. holidays).A date entry have a very simple format:<date> <hours> [<note>]:<date>is a date in the formatYYYY-MM-DD.<hours>is in the same format as for hours in the rules of periodic
blocks. The value of<hours>does not replace the allotted time for the
day. Instead, it might be a positive or negative value, adding to or
subtracting from the time for the day.<note>is an optional string enclosed by double-quotes that describes
the entry.Below are some examples of uses of date entries:work {
  from 2021-10-01 {
    mon  11:00
    tue   9:00
    wed   5:30
    thu   6:30
    fri   8:00
  }

  2021-10-12 -8:00 "National holiday"
  2021-12-15 +2:00 "Extra hours for this specific day"

  # Note that the plus char is optional
  2021-12-24  2:00
}4LicenseThis extension is released underMozilla Public License 2.0. A copy of the
license is provided inLICENSE.txt.