time-change 0.1.0

Convert times between world cities and IANA timezones (offline, no API key).

time_change

A small command-line tool for converting a local time in one city to the corresponding local time in another city — for example, finding what 20:00 in Beijing corresponds to in New York.

Features

• Convert a time in one city to the corresponding time in another city
• 200+ major world cities recognised out of the box (Beijing, NewYork, London, Tokyo, Mumbai, Dubai, Berlin, …)
• Falls back to any IANA timezone identifier (e.g. Asia/Kolkata, America/Argentina/Buenos_Aires)
• Daylight saving time (DST) handled automatically via the IANA tz database
• No API key, no network access — fully offline after install

Why not use a web API?

Several platforms offer time APIs (Google Time Zone API, TimeAPI.io, WorldTimeAPI, etc.), but for city-to-city conversion they are usually the wrong choice:

• They require an API key and a network connection
• They have rate limits and may be unreliable
• They add latency to every conversion

The same IANA timezone database those APIs use is already shipped with Python (via the standard-library zoneinfo module). time_change simply maps a city name to an IANA timezone and does the arithmetic locally — fast, free, and available offline.

Installation

From source (development):

python -m pip install -e .

From a built wheel:

python -m build
python -m pip install dist/time_change-*.whl

Usage

time_change <source_city>_<HH:MM> <target_city>

The source argument combines the city name and the time, separated by an underscore. The target argument is just a city name. Both city names may contain spaces if you quote them.

Examples

$ time_change Beijing_20:00 NewYork
Beijing 20:00 (Asia/Shanghai) -> NewYork 07:00 (America/New_York)

$ time_change London_09:30 Tokyo
London 09:30 (Europe/London) -> Tokyo 18:30 (Asia/Tokyo)

$ time_change "New York_08:00" Berlin
New York 08:00 (America/New_York) -> Berlin 14:00 (Europe/Berlin)

# Use IANA timezone identifiers for cities not in the built-in dictionary
$ time_change Asia/Kolkata_14:00 America/New_York
Asia/Kolkata 14:00 (Asia/Kolkata) -> America/New_York 04:30 (America/New_York)

Input

• source: <city>_<HH:MM> in 24-hour format. Examples: Beijing_20:00, New York_08:30, Asia/Shanghai_20:00.
• target: a city name or IANA timezone. Examples: NewYork, Hong Kong, Europe/Paris.

Output

One line of the form

<source> <HH:MM> (<source_iana>) -> <target> <HH:MM> (<target_iana>)

with the converted local time in HH:MM 24-hour format.

Error handling

The tool prints an error to stderr and exits with a non-zero status when:

• The source string is missing the _HH:MM suffix
• The time is not a valid HH:MM (e.g. 25:99, 20-00)
• The city/timezone is unknown to both the built-in mapping and the IANA database

$ time_change Atlantis_20:00 NewYork
Error: Unknown city or timezone: 'Atlantis'

$ time_change Beijing_99:99 NewYork
Error: Invalid hour 99 in '99:99'. Hour must be 0-23.

$ time_change Beijing2000 NewYork
Error: Invalid source spec 'Beijing2000'. Expected '<City>_<HH:MM>' (e.g. 'Beijing_20:00').

Known limitations

• The built-in city dictionary covers major world cities. For anywhere it does not cover, pass the IANA timezone name directly (e.g. Asia/Kolkata, America/Argentina/Buenos_Aires).
• The conversion uses today's date in the source timezone, so the rare DST transition edge cases around midnight (non-existent or ambiguous local times) are not specifically handled.
• Times close to a DST boundary differ from a naive fixed-offset UTC calculation because the offset changes with the date.
• City names that map to several IANA zones (e.g. "Springfield") resolve to the most common one.
• 24-hour input only — AM/PM is not currently supported.

Development

python -m venv .venv
source .venv/bin/activate
python -m pip install -e . pytest build twine
pytest -q

License

MIT — see LICENSE.