Examples
========

This section provides practical examples and recipes for common timezone tasks.

Basic Examples
--------------

Find All DST-Observing Zones
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    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
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    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
^^^^^^^^^^^^^^^^^^

.. code-block:: python

    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
^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    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
^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    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
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    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
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    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
^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

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

1. **Scheduling System**: Calculate local times for international meetings
2. **Data Analysis**: Analyze timezone distribution for global user base
3. **Monitoring**: Track DST transitions for system alerts
4. **Migration Tool**: Convert historical timestamps between timezones
5. **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 :doc:`api-reference` for detailed API documentation.