Metadata-Version: 2.4
Name: countrystatecity-timezones
Version: 1.0.5
Summary: Type-safe offline data for 432 IANA timezones, with country associations, GMT offsets, and conversion utilities.
Author-email: dr5hn <support@countrystatecity.in>
Maintainer-email: dr5hn <support@countrystatecity.in>
License: Open Database License (ODbL) v1.0
        
        This package uses data from the countries-states-cities-database project,
        which is licensed under the Open Database License (ODbL) v1.0.
        
        For the full text of the ODbL license, please visit:
        https://opendatacommons.org/licenses/odbl/1-0/
        
        Summary:
        You are free to:
        - Share: Copy and redistribute the database
        - Create: Produce works from the database
        - Adapt: Modify, transform and build upon the database
        
        Under the following conditions:
        - Attribute: You must attribute any public use of the database
        - Share-Alike: If you publicly use any adapted version, you must also offer 
          that adapted database under the ODbL
        - Keep open: If you redistribute the database, you must keep it open
        
Project-URL: Homepage, https://countrystatecity.in/?utm_source=pypi&utm_medium=project_link&utm_campaign=python_packages&utm_content=timezones
Project-URL: Documentation, https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/timezones
Project-URL: Repository, https://github.com/dr5hn/countrystatecity-pypi
Project-URL: Source, https://github.com/dr5hn/countrystatecity-pypi/tree/main/python/packages/timezones
Project-URL: Issues, https://github.com/dr5hn/countrystatecity-pypi/issues
Project-URL: Changelog, https://github.com/dr5hn/countrystatecity-pypi/blob/main/python/packages/timezones/CHANGELOG.md
Project-URL: Get API Key, https://app.countrystatecity.in/?utm_source=pypi&utm_medium=project_link&utm_campaign=python_packages&utm_content=timezones
Project-URL: Production API, https://docs.countrystatecity.in/api/introduction
Project-URL: Pricing, https://countrystatecity.in/pricing/?utm_source=pypi&utm_medium=project_link&utm_campaign=python_packages&utm_content=timezones
Keywords: timezones,timezone,countries,geography,iana,utc,gmt,time-conversion,lazy-loading,type-hints,pydantic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: backports.zoneinfo; python_version < "3.9"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# countrystatecity-timezones

[![PyPI](https://img.shields.io/pypi/v/countrystatecity-timezones)](https://pypi.org/project/countrystatecity-timezones/)
[![Python Version](https://img.shields.io/pypi/pyversions/countrystatecity-timezones)](https://pypi.org/project/countrystatecity-timezones/)
[![License](https://img.shields.io/badge/License-ODbL--1.0-blue.svg)](LICENSE)
[![Type Checked](https://img.shields.io/badge/type--checked-mypy-blue)](https://mypy.readthedocs.io/)
[![timezones](https://static.pepy.tech/personalized-badge/countrystatecity-timezones?period=month&units=international_system&left_color=grey&right_color=brightgreen&left_text=timezones)](https://pepy.tech/project/countrystatecity-timezones)
[![timezones](https://static.pepy.tech/personalized-badge/countrystatecity-timezones?period=week&units=international_system&left_color=grey&right_color=brightgreen&left_text=timezones)](https://pepy.tech/project/countrystatecity-timezones)

Official Python package for 432 IANA timezones with country associations, GMT offsets, and time conversion utilities. Part of the [countrystatecity](https://github.com/dr5hn/countrystatecity-pypi) ecosystem.

## From offline prototype to production

This package provides a versioned offline snapshot. For regularly updated data,
server-side search and filtering, field-selected responses, or managed availability
and support, use the Country State City API.

[Get a free API key](https://app.countrystatecity.in/?utm_source=pypi&utm_medium=package&utm_campaign=python_packages&utm_content=timezones) ·
[API docs](https://docs.countrystatecity.in/api/introduction) ·
[Pricing](https://countrystatecity.in/pricing/?utm_source=pypi&utm_medium=package&utm_campaign=python_packages&utm_content=timezones) ·
[Migration guide](https://github.com/dr5hn/countrystatecity-pypi/blob/main/docs/MIGRATING_TO_API.md)

Keep API keys in server-side environment variables, never in client-side code or
source control.

## Installation

```bash
pip install countrystatecity-timezones
```

## Quick Start

```python
from countrystatecity_timezones import (
    get_all_timezones,
    get_timezones_by_country,
    get_timezone_by_zone_name,
    get_timezones_by_offset,
    search_timezones,
    convert_time,
)
from datetime import datetime

# Get all timezones
timezones = get_all_timezones()
# [Timezone(zoneName="Africa/Abidjan", gmtOffset=0, ...), ...]

# Get timezones for a country
us_timezones = get_timezones_by_country("US")
# [Timezone(zoneName="America/Adak", countryCode="US", ...), ...]

# Lookup by IANA zone name
tz = get_timezone_by_zone_name("America/New_York")
# Timezone(zoneName="America/New_York", gmtOffset=-18000, gmtOffsetName="UTC-05:00", ...)

# Filter by GMT offset (seconds)
utc_minus_5 = get_timezones_by_offset(-18000)

# Search by name or abbreviation
results = search_timezones("Eastern")

# Convert time between timezones
dt = datetime(2024, 1, 1, 12, 0, 0)
converted = convert_time(dt, "America/New_York", "Asia/Kolkata")
# datetime(2024, 1, 1, 22, 30, tzinfo=ZoneInfo("Asia/Kolkata"))
```

## Data Model

```python
class Timezone(BaseModel):
    zoneName: str        # IANA timezone name (e.g., "America/New_York")
    gmtOffset: int       # GMT offset in seconds (e.g., -18000)
    gmtOffsetName: str   # Human-readable offset (e.g., "UTC-05:00")
    abbreviation: str    # Timezone abbreviation (e.g., "EST")
    tzName: str          # Full timezone name (e.g., "Eastern Standard Time")
    countryCode: str     # ISO2 country code (e.g., "US")
    countryName: str     # Country name (e.g., "United States")
```

## API Reference

| Function | Description |
|---|---|
| `get_all_timezones()` | Get all timezone entries |
| `get_timezones_by_country(code)` | Get timezones for an ISO2 country code |
| `get_timezone_by_zone_name(name)` | Lookup by IANA zone name |
| `get_timezones_by_offset(seconds)` | Filter by GMT offset in seconds |
| `search_timezones(query)` | Search by zone name, full name, or abbreviation |
| `convert_time(dt, from_tz, to_tz)` | Convert datetime between IANA timezones |

## License

ODbL-1.0 — see [LICENSE](LICENSE).

## Other Packages in this Ecosystem

| Package | Description |
|---|---|
| [countrystatecity-countries](https://pypi.org/project/countrystatecity-countries/) | 250 countries, 5,308 states, 171,938 cities |
| [countrystatecity-currencies](https://pypi.org/project/countrystatecity-currencies/) | 249 country/currency associations |
| [countrystatecity-translations](https://pypi.org/project/countrystatecity-translations/) | 4,724 translations in 19 languages |
| [countrystatecity-phonecodes](https://pypi.org/project/countrystatecity-phonecodes/) | International phone/dialing codes for 250 countries |
| [countrystatecity-regions](https://pypi.org/project/countrystatecity-regions/) | Region and subregion associations for 250 countries |
| [countrystatecity-postal-codes](https://pypi.org/project/countrystatecity-postal-codes/) | Postal/ZIP records for 125 countries |

Data sourced from [countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database).

---

Made with ❤️ by [dr5hn](https://github.com/dr5hn)
