Extension API: add used range / hints to temp

[skwde]

When using the extension API (https://timewarrior.net/docs/api/), the config currently contains

                     'temp.config': '...',                                                                                                                                                   
                     'temp.db': '...',                                                                                                                                                                       
                     'temp.extensions': '...',                                                                                                                                                    
                     'temp.report.end': '...',                                                                                                                                                                                   
                     'temp.report.start': '...',                                                                                                                                                                                 
                     'temp.report.tags': '...',                                                                                                                                                                                                  
                     'temp.version': '1.9.1', 

when accessed via `TimeWarriorParser(sys.stdin).get_config().get_dict()

it would be helpful to also have

• temp.report.hints
• temp.report.range

[lauft]

temp.report.range should already be covered by temp.report.start and temp.report.end.

temp.report.hints seems to have overlap with request to pass arguments/options to reports (e.g. #640 , #230)

[skwde]

temp.report.range should already be covered by temp.report.start and temp.report.end.

Ahh you are right, I got confused by the following:

If I do

timew report abc :month

I get

'temp.report.end': '20260228T230000Z',                                                                                                                                                                                   
'temp.report.start': '20260131T230000Z',

though Z indicates UTC (https://timewarrior.net/docs/dates/).

Note, I am currently in UTC+1.

[lauft]

Timewarrior stores datetime in UTC. It is converted to local time when printed to the console. When using reports, this task has to be done by the extension.

[skwde]

Exactly, start / end of month is midnight in UTC, not one hour before?!

This one hour comes exactly from the timezone I am in.
I would expect everything I get from timeworrior being independent of the timezone I am in.
But there is also the Z indicating UTC according to ISO8601 (https://www.iso8601.com/#timezone)

Note when I do

TZ=UTC timew report balance.py :month

I get

'temp.report.end': '20260301T000000Z',                                                                                                                                                                                   
'temp.report.start': '20260201T000000Z',

weirdly I also get this from

TZ=CET timew report balance.py :month

So the ouptut of

timew report abc :month

i.e.

'temp.report.end': '20260228T230000Z',                                                                                                                                                                                   
'temp.report.start': '20260131T230000Z',

seems odd.

I think from ISO8601 perspective, only the output of

TZ=UTC timew report balance.py :month

is correct, because the output of the other commands do not remove the Z by the correct timezone.

Both

TZ=CET timew report balance.py :month
timew report balance.py :month

return a date with local time and not UTC as indicated by Z.

[smemsh]

Even in different timezones, a timestamp that keeps the Z (for Zulu) is still correct, since it specifies an absolute point in time, it would not change with time zone. Only a "localized" version (which would need to drop the Z) would be different. The stamps are output in Zulu time, so your script would have to localize them if you wanted to do your own calculations.

Note that the cutoffs should still be correct for what data you get, where those starts start and ends stop, depending on your timezone, so for example:

 $ TZ=US/Eastern timew export :month | jq length
196

 $ TZ=Asia/Manila timew export :month | jq length
217

However all those exports will be correctly aligned within the desired range:

 $ for tz in US/Eastern Asia/Manila; do
   TZ=$tz timew export :month \
   | jq -r 'length, first.start, last.start'
   done
196
20260201T130049Z
20260220T145853Z
217
20260131T165021Z
20260220T145853Z

[skwde]

@smemsh, thanks for your response!

It seems my last reply was not really clear. I hope to better demonstrate in the following.

Even in your output you see already the bug, you say the times are in Zulu (UTC / +00:00) but depending on the setting of TZ they are different!

But coming to your specific points:

it specifies an absolute point in time, it would not change with time zone.

Yes absolutely! But it does change with TZ setting!

Only a "localized" version (which would need to drop the Z) would be different.

Yes, I fully agree. But timew sometimes gives "localized" timestamps. (see below)

Z specifies UTC (as mentioned in the "Syntax: Dates" docs but also in ISO8601 and RF3339), and thus +00:00.

My point is, that the Z needs to be dropped as soon as TZ is not UTC or even as soon as TZ is set, to make it clear.

So the correct stamp is

# UTC is +00:00 as indicated by Z for Zulu
TZ=UTC timew report balance.py :month | grep -E 'temp\.report\.(start|end)'
                     'temp.report.end': '20260301T000000Z',                                                                                                                                                                                   
                     'temp.report.start': '20260201T000000Z',
# similar, no timezone
TZ= timew report balance.py :month | grep -E 'temp\.report\.(start|end)'
                     'temp.report.end': '20260301T000000Z',                                                                                                                                        
                     'temp.report.start': '20260201T000000Z', 

The actual displayed timestamp changes with TZ setting. This shouldn't be the case, because the stamp is modified while losing the information, how it was modified. Thus the offset should be added.

# Asia/Manila is +08:00
TZ=Asia/Manila timew report balance.py :month | grep -E 'temp\.report\.(start|end)'
                     'temp.report.end': '20260228T160000Z',                                                                                                                                                                                   
                     'temp.report.start': '20260131T160000Z', 

# Europe/Zurich is currently +01:00
TZ=Europe/Zurich timew report balance.py :month | grep -E 'temp\.report\.(start|end)'
                     'temp.report.end': '20260228T230000Z',                                                                                                                                                                                   
                     'temp.report.start': '20260131T230000Z', 

# I am in Europe/Zurich
timew report balance.py :month | grep -E 'temp\.report\.(start|end)'
                     'temp.report.end': '20260228T230000Z',                                                                                                                                        
                     'temp.report.start': '20260131T230000Z', 

# US/Eastern is currently -05:00
TZ=US/Eastern timew report balance.py :month | grep -E 'temp\.report\.(start|end)'
                     'temp.report.end': '20260301T000000Z',                                                                                                                                                                                   
                     'temp.report.start': '20260201T000000Z',  

So in all cases, as soon as TZ is set (even if not explicitly by the user), the Z should be dropped and replaced by the used offset. Instead the offset is sometimes applied and sometimes it isn't.

The stamps are output in Zulu time,

No, this is not true, see demonstration I just gave. The output is sometimes in UTC (it seems when a timezone corresponds to <00:00) while it is sometimes incorrect (timezone offset taken into account, but still using the Z, though no longer in Zulu).
Bug?

so your script would have to localize them if you wanted to do your own calculations.

Yes, but how should I do that with no information about the used TZ. Even if I completely ignore the Z I cannot be sure when the offset was applied or when the timestamp is really in UTC.

Maybe to comment also again on @lauft message above

Timewarrior stores datetime in UTC. It is converted to local time when printed to the console. When using reports, this task has to be done by the extension.

Yes it is good that it is stored in UTC. As I demonstrated above, conversion to local time is sometimes done depending on the setting of TZ. In any case, as soon as conversion is done, the Z should be dropped because the timestamp is localized and the Z is no longer true and actually indicates wrong information.

Note especially it seems that the timestamp is only localized for offset>00:00 while nothing happens when offset<00:00.
Bug?

[smemsh]

I'll try once more: The time zone you are in is not relevant for a UTC time stamp. The time described by it is an absolute point in time.

You're trying to say the time stamp should be localized already on output just because you set TZ, but it's NOT a localized time. An exported timestamp (ie not "summary" but "export") is in UTC. The output includes the Z and is not localized.

It doesn't matter what time zone you are in, a UTC time stamp always represent the same point in time. Any given UTC timestamp represents the exact same point in time anywhere on the globe.

The cutoffs change for ranges like :month because that's a TZ-relative concept, you will get different time stamps because the endpoints of the relative range that gets output will differ depending on TZ. The stamps themselves however are always going to be absolute points in time, are in UTC, and have the trailing Z. You must localize them yourself if you want to know the localized time corresponding to each of those exported UTC time stamps.

[skwde]

@smemsh Ok, so the cutoffs probably explain the assumed "bug" for TZ=US/Eastern

Though the rest remains unclear...

Just consider the start of the month, which is 2026-02-01 00:00:00 and optional timezone specification adding just +<...> or -<...> but changing nothing in the actual datetime.

So why does the output change based on the TZ setting. Above we got as start times

# Asia/Manila
20260131T160000Z',
# Europe/Zurich
'20260131T230000Z',

Both claim to be start of month in UTC. Why?

I fail to understand how those should be localized to describe the start of the month in my timezone without knowing the TZ setting.

---

The time zone you are in is not relevant for a UTC time stamp

Ok, but why does the timestamp change when setting TZ while still indicating to be UTC?

You're trying to say the time stamp should be localized already on output just because you set TZ, but it's NOT a localized time. An exported timestamp (ie not "summary" but "export") is in UTC. The output includes the Z and is not localized.

I am trying to say that when the timestamp is affected by a TZ setting it should either be indicated by replacing Z with the corresponding offset, or the timestamp should not be affected by the TZ setting.

It doesn't matter what time zone you are in, a UTC time stamp always represent the same point in time. Any given UTC timestamp represents the exact same point in time anywhere on the globe.

Obviously not, how do both

'20260131T160000Z',
'20260131T230000Z',

represent the start of the month?

[lauft]

... start / end of month is midnight in UTC, not one hour before?!

For Timewarrior, the hint :month represents the range of a month, which starts/ends at midnight in local time.

As @smemsh pointed out:

The cutoffs change for ranges like :month because that's a TZ-relative concept, ...

So for February, the local start and end datetimes are 2026-02-01T00:00 and 2026-03-01T00:00. Which depending on the timezone used when calling timew report balance.py :month translates to the following values in UTC:

Timezone	Offset	start	end
Asia/Manila	+8	2026-01-31T16:00Z	2026-02-28T16:00Z
Europe/Zurich	+1	2026-01-31T23:00Z	2026-02-28T23:00Z
US/Eastern	-5	2026-02-01T05:00Z	2026-03-01T05:00Z

how do both

'20260131T160000Z',
'20260131T230000Z',

represent the start of the month?

If you compare those values with the table above:

• 20260131T160000Z represents the start of February in UTC for timezone Asia/Manila,
• 20260131T230000Z represents the start of February in UTC for timezone Europe/Zurich,

and, in the same way,

• 20260201T050000Z represents the start of February in UTC for timezone US/Eastern

---

I think saying "a day/month/year starts on " does not make much sense in UTC.

I would rather think of UTC as a way to uniformly record timestamps. What this timestamp actually means depends on you, or more precisely, on your location.

Thus day, month, year are more local concepts: A day starts when your local time passes your local midnight. Therefore, Australians celebrate New Years Eve earlier than us in Europe...

[smemsh]

The time zone you are in is not relevant for a UTC time stamp

Ok, but why does the timestamp change when setting TZ while still indicating to be UTC?

because you requested :month which is TZ relative so the range of time to give you records for begins and ends at different time points depending on what time zone you are in.

You asked for :month, which starts at day 1, second 0 of your local month. This will be a different point in time, depending on your time zone. The export doesn't contain time zone information, only points in time. Think of the timestamps as an amount of time since the universe began. The fact that they happen to be encoded in UTC is an implementation detail only.

[skwde]

@lauft @smemsh

Thanks for your replies and effort.

I do see the point / reasoning now. Whenever you print data you "localize" it to TZ to have data appear as if recorded there.

I however still think that as soon as one localizes the data one should at the offset. I never heard of a timestamp local to a timezone but in UTC. The information of what TZ was lost to alter your UTC stamp is lost.
While for timw summary :month this is not a big problem (even though it should be printed) for the timew report this can be a problem. Because in the report, I can only assume that the env variable TZ was used, otherwise there isno way to find out "in what timezone the UTC stamp is in" (it really feels weird writing / saying that).
Imagine the case where TZ is set to one timezone but a report hardcodes another or requests another (once #230 is ready) .

There is only (and should only be) one UTC independent of timezone.
UTC is well defined for a reason.

Even though I think you are aware of that: There is a standard, ISO8601 e.g. see https://en.wikipedia.org/wiki/ISO_8601, for "covering the worldwide exchange and communication of date and time-related data".

But ultimately it is not up to me to decide how it should be done. I merely have to work with what I get.

[smemsh]

The information of what TZ was lost to alter your UTC stamp is lost.

That point in time differs in each possible time zone. Thankfully since it was encoded in a known, fixed time zone (UTC), we know the absolute time it represents, and can localize it to any time zone. Like this:

 $ now="$(date --utc)"

 $ for tz in US/{Eastern,Pacific}; do TZ=$tz date -d "$now"; done
Wed Mar  4 14:11:49 EST 2026
Wed Mar  4 11:11:49 PST 2026

You can see that the UTC timestamp $now was localized according to $TZ at the point of display. These apparently different values nonetheless represent the identical point in time.

Timewarrior stores points in time. I fail to see what information is "lost," or how it violates ISO-8601, or how there are multiple meanings of UTC in play here.

"in what timezone the UTC stamp is in"

There is no information stored about "what time zone the user was in at the time of recording." There is only a point in time stored. That point in time is the same in any time zone, but the localized value will differ according to its offset from UTC.

[skwde]

Well, on timew report :month you alter

20260201T000000Z

to

20260131T160000Z

based on the environment variable TZ.

Simply looking at the two timestamps

20260201T000000Z
20260131T160000Z

I only see two different points in time.

From this I know nothing about the second one representing the start of month in the TZ used, because when parsing timew report :month output in the report script I don't get this information. I can only access it by using the OS variable TZ from the OS.

---

You can see that the UTC timestamp $now was localized according to $TZ at the point of display. These apparently different values nonetheless represent the identical point in time.

Yes, because one is in UTC and the localized one (where TZ was used) carries the offset / timezone.
This is perfectly clear.

[smemsh]

Well, on timew report :month you alter 20260201T000000Z to 20260131T160000Z

where? it doesn't happen for me:

 $ echo -e '#!/bin/bash\nwhile read; do echo $REPLY; done' > testing
 $ chmod 0755 testing

 $ timew report testing @1 | grep -A99 ^$ | jq -r '.[].start'
20260305T131017Z

 $ timew export @1 | jq -r '.[].start'
20260305T131017Z

This is the same timestamp returned both to the report script and present in the database. No localization has occurred. Again, that is up to the script to localize if it wants to. What the database stores are UTC timestamps.

I can only access it by using the OS variable TZ from the OS

Access what? The timezone you're in when you invoke timewarrior? TZ is an environment variable that the timew process would export to all child processes (including report scripts) if it were in the exported environment when timewarrior was executed. Like for all other UNIX processes. So this is just normal behavior, no?

I'm really trying here, but do not see the issue. If you're just saying you want access to the cli args that timew got, so your report gets to see that you gave :month and do something special, then #230 is debating that currently (as you point out) and one of the solutions mentioned is to pass all args timewarrior got to the report script. Would that solve your issue?

[skwde]

As mentioned, it depends on the setting of TZ variable. You stick with whatever is set on your system.

Here is a MWE, use extensions/test.py

#!/usr/bin/env python3

import sys
from timewreport.parser import TimeWarriorParser

parser = TimeWarriorParser(sys.stdin)
tw_config = parser.get_config().get_dict()
print(tw_config["temp.report.start"])

and run

TZ=UTC timew report :month test.py
TZ=Asia/Manila timew report :month test.py

you get

20260301T000000Z
20260228T160000Z

So based on the setting of TZ you get two different timestamps, though both indicating to be in UTC (because they use Z) while only the former actually used UTC. Without accessing the environment variable TZ in test.py I have now way to know the value of TZ because

1. It is not recorded in tw_config.
2. Both timestamps indicate they are in UTC by using the Z.