Getting Started

Installation

Basic Installation

pip install x-zic

With Optional Dependencies

# For pandas integration
pip install x-zic[pandas]

# For analysis features
pip install x-zic[analysis]

# For development
pip install x-zic[dev]

Basic Usage

Reading Timezone Data

import x_zic

# Read all zones
all_zones = x_zic.read_zones()
print(f"Found {len(all_zones)} timezones")

# Read by region
european_zones = x_zic.read_zones('europe')
asian_zones = x_zic.read_zones('asia')

Working with Transitions

# Get DST transitions
transitions = x_zic.get_transitions(
    'America/Los_Angeles',
    start_year=2020,
    end_year=2025
)

# Analyze transition patterns
for t in transitions:
    print(f"{t['timestamp']} | {t['abbrev']:>4} | "
          f"{t['offset_before']} → {t['offset_after']}")

Geographic Data

from x_zic.geo import read_zonetab

# Get timezones with coordinates
geo_zones = read_zonetab()
for zone in geo_zones[:5]:
    print(f"{zone['zone_id']} | {zone['country_code']} | "
          f"({zone['latitude']}, {zone['longitude']})")

Core Concepts

Time Zone Database

The IANA Time Zone Database (TZDB) is the authoritative source for timezone information worldwide. It contains:

  • Zone definitions: Timezone rules and offsets

  • Rule sets: DST transition rules

  • Links: Aliases and deprecated names

  • Geographic data: Coordinates and country codes

x-zic provides a complete parser for all TZDB components.

Caching System

x-zic automatically caches parsed data for optimal performance:

  • First run: Parses TZDB files and creates cache

  • Subsequent runs: Loads from cache instantly

  • Cache validation: Automatically detects source changes

  • Manual control: Clear cache when needed

# Clear cache manually
x_zic.clear_cache()

Data Models

The library uses simple, serializable data models:

# Zone example
{
    'name': 'America/New_York',
    'offset': '-5:00',
    'rules': 'US',
    'format': 'E%sT',
    'region': 'northamerica'
}

# Transition example
{
    'zone': 'America/New_York',
    'timestamp': '2024-03-10T07:00:00',
    'offset_before': '-05:00',
    'offset_after': '-04:00',
    'is_dst': True,
    'abbrev': 'EDT'
}

Next Steps

Ready for more? Check out: