Examples
This section provides practical examples and recipes for common timezone tasks.
Basic Examples
Find All DST-Observing Zones
from x_zic import read_zones
zones = read_zones()
dst_zones = [
zone for zone in zones
if zone['rules'] not in ['-', '', None]
]
print(f"Found {len(dst_zones)} DST-observing zones")
Calculate Offset Changes
from x_zic import get_transitions
transitions = get_transitions('Europe/London', 2023, 2024)
for t in transitions:
change = "DST Start" if t['is_dst'] else "DST End"
print(f"{t['timestamp'][:10]}: {change} ({t['abbrev']})")
Geographic Queries
from x_zic.geo import read_zonetab
geo_zones = read_zonetab()
us_zones = [z for z in geo_zones if z['country_code'] == 'US']
for zone in us_zones:
print(f"{zone['zone_id']} - {zone['comments']}")
Advanced Examples
Timezone Statistics
from x_zic import read_zones
from collections import Counter
zones = read_zones()
# Count by region
region_counts = Counter(zone['region'] for zone in zones)
print("Zones by region:")
for region, count in region_counts.most_common():
print(f" {region}: {count}")
# Count DST usage
dst_count = sum(1 for zone in zones if zone['rules'] not in ['-', ''])
print(f"DST zones: {dst_count}/{len(zones)} ({dst_count/len(zones)*100:.1f}%)")
Transition Analysis
from x_zic import get_transitions
from datetime import datetime
def analyze_transitions(zone_name, years=5):
end_year = datetime.now().year
start_year = end_year - years
transitions = get_transitions(zone_name, start_year, end_year)
print(f"Transition analysis for {zone_name} ({start_year}-{end_year}):")
print(f"Total transitions: {len(transitions)}")
dst_starts = [t for t in transitions if t['is_dst']]
dst_ends = [t for t in transitions if not t['is_dst']]
print(f"DST starts: {len(dst_starts)}")
print(f"DST ends: {len(dst_ends)}")
if dst_starts:
avg_start = sum(int(t['timestamp'][5:7]) for t in dst_starts) / len(dst_starts)
print(f"Average DST start month: {avg_start:.1f}")
return transitions
# Usage
transitions = analyze_transitions('America/New_York')
Timezone Conversion Utility
from x_zic import get_transitions
from datetime import datetime, timedelta
class TimezoneConverter:
def __init__(self, zone_name):
self.zone_name = zone_name
self.transitions = get_transitions(zone_name, 1970, 2030)
def utc_to_local(self, utc_dt):
"""Convert UTC datetime to local time"""
# Find applicable transition
for i, transition in enumerate(self.transitions):
trans_dt = datetime.fromisoformat(transition['timestamp'])
if utc_dt < trans_dt:
# Use previous transition's offset
if i > 0:
prev_trans = self.transitions[i-1]
offset = self._parse_offset(prev_trans['offset_after'])
else:
offset = self._parse_offset(transition['offset_before'])
return utc_dt + timedelta(hours=offset)
# Use last transition's offset
if self.transitions:
last_trans = self.transitions[-1]
offset = self._parse_offset(last_trans['offset_after'])
return utc_dt + timedelta(hours=offset)
return utc_dt
def _parse_offset(self, offset_str):
"""Parse offset string to hours"""
# Simplified offset parsing
if offset_str.startswith('-'):
return -int(offset_str[1:3])
else:
return int(offset_str[:2])
# Usage
converter = TimezoneConverter('America/Los_Angeles')
utc_time = datetime(2024, 3, 10, 12, 0, 0)
local_time = converter.utc_to_local(utc_time)
print(f"UTC: {utc_time} -> Local: {local_time}")
Integration Examples
With FastAPI Web Service
from fastapi import FastAPI, HTTPException
from x_zic import read_zones, get_transitions
app = FastAPI(title="Timezone API")
@app.get("/zones")
async def list_zones(region: str = None):
"""List all timezones or filter by region"""
try:
zones = read_zones(region)
return {"zones": zones}
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
@app.get("/zones/{zone_name}/transitions")
async def get_zone_transitions(zone_name: str, start_year: int = 2020, end_year: int = 2030):
"""Get transitions for a specific zone"""
try:
transitions = get_transitions(zone_name, start_year, end_year)
return {
"zone": zone_name,
"transitions": transitions
}
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
@app.get("/health")
async def health_check():
return {"status": "healthy"}
With Pandas Analysis
import pandas as pd
from x_zic import read_zones, get_transitions
# Comprehensive timezone analysis
zones = read_zones()
df_zones = pd.DataFrame(zones)
# Basic statistics
print("Timezone Analysis Report")
print("=" * 50)
print(f"Total zones: {len(df_zones)}")
print(f"Regions: {df_zones['region'].nunique()}")
print(f"DST zones: {len(df_zones[df_zones['rules'] != '-'])}")
# Region analysis
region_stats = df_zones['region'].value_counts()
print("\nZones by region:")
for region, count in region_stats.items():
print(f" {region:15} {count:3} zones")
# Offset analysis
def extract_offset_hours(offset_str):
if offset_str == '-' or not offset_str:
return 0
try:
sign = -1 if offset_str.startswith('-') else 1
parts = offset_str.replace('-', '').replace('+', '').split(':')
hours = int(parts[0])
minutes = int(parts[1]) if len(parts) > 1 else 0
return sign * (hours + minutes/60)
except:
return 0
df_zones['offset_hours'] = df_zones['offset'].apply(extract_offset_hours)
print(f"\nOffset range: {df_zones['offset_hours'].min():.1f} to {df_zones['offset_hours'].max():.1f} hours")
Real-world Use Cases
Scheduling System: Calculate local times for international meetings
Data Analysis: Analyze timezone distribution for global user base
Monitoring: Track DST transitions for system alerts
Migration Tool: Convert historical timestamps between timezones
API Service: Provide timezone information to other applications
Troubleshooting
Common Issues
Problem: Zone not found Solution: Check for typos and use x_zic.read_zones() to see available zones
Problem: Cache issues Solution: Use x_zic.clear_cache() to reset
Problem: Performance problems Solution: Enable caching and load only needed regions
Need more help? Check the API Reference for detailed API documentation.