[New-bugs-announce] [issue40536] Addition of a "list of available time zones" function to zoneinfo

[Paul Ganssle]

New submission from Paul Ganssle <p.ganssle at gmail.com>:

One thing that I sort of overlooked in PEP 615 that I think will be a common feature request for zoneinfo is the ability to get a list of time zones available on the current TZPATH.

This is more complicated to implement than it sounds like, but luckily I already did it in order to implement the property tests for the zoneinfo module:

https://github.com/pganssle/zoneinfo/blob/ffd21a6d065e04725e04b37bb430c2559fefd5fa/tests/test_zoneinfo_property.py#L23-L70

The biggest complication is that there are files on TZPATH that are not necessarily time zones, and when I looked I couldn't easily find a list of all available time zones, so the only way to tell which ones are time zones and which ones aren't is to open each one and read the first 4 bytes. However, `tzdata` does ship with a list of available time zones, so the way I've got the function working right now is:

1. If `tzdata` is installed – despite the fact that it's technically the end of the search path, convert the list of available zones that ships with `tzdata` to your starting set (since you know these are all valid zones).
2. Walk the `tzpath`, and every time you find something not in the set of valid keys, open it and read the first 4 bytes, then add that to the set.

The common cases will be that `tzdata` is not available (in which case no harm done), or `tzdata` has the same set of keys as the TZPATH, in which case you never have to open any of the TZif files. The fact that the search order is inverted from what it normally is doesn't matter because the output is the union of all the sets anyway.

I don't know that the PEP needs to be amended – if this were a feature request for Python 3.10 I don't think it would need a PEP to go through, but I don't mind amending the PEP to document it.

Design decisions (with my initial answers, loosely held):

1. Should this be a classmethod or a free-standing function?

I'm inclined towards free-standing function because zoneinfo.TZPATH is at the module level and not the class level.

2. What should the return type be?

I think frozenset() or set(); a sorted list is also a reasonable option, but for people who just want to use "in" or show some subset of available zones, that would be wasteful.

We should go with frozenset() if we want there to be some possibility of caching the result in the future.

3. Should we try to cache the result?

I would say no, at least for now. It would not be super easy to get the cache invalidation right in the general case, and not many people are likely to be sensitive to the performance of this operation – the people who are can easily create their own cache.

4. What should it be called?

Naming things is hard. Options:

- zoneinfo.timezones()
- zoneinfo.all_timezones()
- zoneinfo.timezone_{list,set}()
- zoneinfo.valid_timezones()
- zoneinfo.valid_keys()
- zoneinfo.available_timezones()

`pytz` has a similar thing and calls it all_timezones. It also has something called common_timezones, but that is a bit harder to pull off and I'm not confident that we'll get something satisfactory before the feature freeze.

----------
components: Library (Lib)
messages: 368285
nosy: belopolsky, lemburg, p-ganssle
priority: normal
severity: normal
status: open
title: Addition of a "list of available time zones" function to zoneinfo
type: enhancement
versions: Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40536>
_______________________________________