time-change-2 0.2.0

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

time_change_2

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.

This is the successor to time_change and adds Chinese city-name support: you can pass 北京, 纽约, 伦敦, 东京, … directly.

Features

• Convert a time in one city to the corresponding time in another city
• Bilingual input: accepts both Chinese (北京, 纽约, 伦敦) and romanised (Beijing, NewYork, London) city names
• 200+ major world cities recognised out of the box, in both languages
• 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_2 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_2-*.whl

Usage

time_change_2 <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 be Chinese, romanised, or raw IANA ids, and may contain spaces if you quote them.

Examples (English)

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

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

$ time_change_2 "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_2 Asia/Kolkata_14:00 America/New_York
Asia/Kolkata 14:00 (Asia/Kolkata) -> America/New_York 04:30 (America/New_York)

Examples (Chinese)

$ time_change_2 北京_20:00 纽约
北京 20:00 (Asia/Shanghai) -> 纽约 07:00 (America/New_York)

$ time_change_2 伦敦_09:30 东京
伦敦 09:30 (Europe/London) -> 东京 18:30 (Asia/Tokyo)

$ time_change_2 上海_08:00 巴黎
上海 08:00 (Asia/Shanghai) -> 巴黎 02:00 (Europe/Paris)

# Chinese source, English target — they can be freely mixed
$ time_change_2 成都_14:30 Sydney
成都 14:30 (Asia/Shanghai) -> Sydney 17:30 (Australia/Sydney)

Input

• source: <city>_<HH:MM> in 24-hour format. Examples: Beijing_20:00, 北京_20:00, New York_08:30, Asia/Shanghai_20:00.
• target: a city name (Chinese or romanised) 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 Chinese mapping, the romanised mapping, and the IANA database

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

$ time_change_2 北京_99:99 纽约
Error: Invalid hour 99 in '99:99'. Hour must be 0-23.

$ time_change_2 北京2000 纽约
Error: Invalid source spec '北京2000'. 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.
• Chinese city-name coverage is a curated subset of the romanised list; less-common cities may need to be entered in English.

Development

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

License

MIT — see LICENSE.