Metadata-Version: 2.4
Name: time_change
Version: 0.1.0
Summary: Convert times between world cities and IANA timezones (offline, no API key).
Author: Time Change Contributors
License: MIT
Project-URL: Homepage, https://example.com/time_change
Project-URL: Issues, https://example.com/time_change/issues
Keywords: time,timezone,converter,cities,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tzdata>=2024.1; sys_platform == "win32"
Dynamic: license-file

# 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):

```bash
python -m pip install -e .
```

From a built wheel:

```bash
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

```bash
$ 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

```bash
$ 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

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

## License

MIT — see [LICENSE](LICENSE).
