Time & Date Utilities

class ConstantTZInfo(tzinfo):
    """Timezone info for fixed UTC offsets."""
    def __init__(self, name=None, offset=None): ...
    def utcoffset(self, dt): ...
    def tzname(self, dt): ...
    def dst(self, dt): ...

class LocalTZInfo(tzinfo):
    """Timezone info for local timezone with DST support."""
    def utcoffset(self, dt): ...
    def tzname(self, dt): ...
    def dst(self, dt): ...

class USTimeZone(tzinfo):
    """US timezone implementation with historical DST rules."""
    def __init__(self, name, offset, dst_name, dst_offset, dst_start, dst_end): ...
    def utcoffset(self, dt): ...
    def tzname(self, dt): ...
    def dst(self, dt): ...

def dt_to_timestamp(dt):
    """
    Convert datetime to Unix timestamp.
    
    Parameters:
    - dt (datetime): Datetime object to convert
    
    Returns:
    float: Unix timestamp
    """

def isoparse(iso_str):
    """
    Parse ISO 8601 datetime strings.
    
    Parameters:
    - iso_str (str): ISO 8601 formatted datetime string
    
    Returns:
    datetime: Parsed datetime object with timezone info
    """

def strpdate(string, format):
    """
    Parse date string with timezone awareness.
    
    Parameters:
    - string (str): Date string to parse
    - format (str): strptime format string
    
    Returns:
    datetime: Parsed datetime object
    """

def parse_timedelta(text):
    """
    Parse human-readable timedelta strings.
    
    Parameters:
    - text (str): Human-readable time duration (e.g., '1h 30m', '2 days')
    
    Returns:
    timedelta: Parsed time duration
    """

def decimal_relative_time(d, other=None, **kwargs):
    """
    Decimal relative time description.
    
    Parameters:
    - d (datetime): Target datetime
    - other (datetime, optional): Reference datetime (default: now)
    
    Returns:
    str: Decimal relative time string
    """

def relative_time(d, other=None, ndigits=0):
    """
    Human-readable relative time.
    
    Parameters:
    - d (datetime): Target datetime
    - other (datetime, optional): Reference datetime (default: now)
    - ndigits (int): Number of decimal places for precision
    
    Returns:
    str: Human-readable relative time (e.g., '2 hours ago', 'in 3 days')
    """

def daterange(start, stop, step=1, inclusive=False):
    """
    Generate date ranges.
    
    Parameters:
    - start (date): Start date
    - stop (date): End date
    - step (int): Step size in days
    - inclusive (bool): Include end date
    
    Yields:
    date: Each date in the range
    """

from boltons.timeutils import (
    isoparse, relative_time, parse_timedelta, daterange,
    dt_to_timestamp, LocalTZInfo, UTC
)
from datetime import datetime, date, timedelta

# Parse ISO 8601 strings
iso_string = "2023-12-25T15:30:00Z"
dt = isoparse(iso_string)
print(dt)  # 2023-12-25 15:30:00+00:00

# Convert to timestamp
timestamp = dt_to_timestamp(dt)
print(timestamp)  # Unix timestamp

# Human-readable relative time
now = datetime.now(UTC)
past = now - timedelta(hours=2, minutes=30)
relative = relative_time(past, now)
print(relative)  # "2 hours ago"

future = now + timedelta(days=3)
relative_future = relative_time(future, now)
print(relative_future)  # "in 3 days"

# Parse time durations
duration_str = "1h 30m 45s"
duration = parse_timedelta(duration_str)
print(duration)  # timedelta(hours=1, minutes=30, seconds=45)

# Generate date ranges
start_date = date(2023, 1, 1)
end_date = date(2023, 1, 7)
for day in daterange(start_date, end_date):
    print(day)  # 2023-01-01, 2023-01-02, ..., 2023-01-06

# Timezone-aware operations
local_tz = LocalTZInfo()
local_time = datetime.now(local_tz)
utc_time = local_time.astimezone(UTC)
print(f"Local: {local_time}")
print(f"UTC: {utc_time}")

from boltons.timeutils import USTimeZone, ConstantTZInfo
from datetime import datetime

# US timezone with DST
eastern = USTimeZone(
    'EST', timedelta(hours=-5),
    'EDT', timedelta(hours=-4),
    dst_start=(3, 2, 0),  # Second Sunday in March
    dst_end=(11, 1, 0)    # First Sunday in November
)

# Create timezone-aware datetime
dt_eastern = datetime(2023, 7, 4, 12, 0, 0, tzinfo=eastern)
print(dt_eastern)  # 2023-07-04 12:00:00-04:00 (EDT in summer)

# Fixed offset timezone
pst = ConstantTZInfo('PST', timedelta(hours=-8))
dt_pst = datetime(2023, 12, 25, 10, 0, 0, tzinfo=pst)
print(dt_pst)  # 2023-12-25 10:00:00-08:00

# Complex relative time formatting
start = datetime(2023, 1, 1, 12, 0, 0, tzinfo=UTC)
end = datetime(2023, 1, 15, 18, 30, 45, tzinfo=UTC)

relative_precise = relative_time(end, start, ndigits=2)
print(relative_precise)  # Precise relative time with decimals

# Timezone constants
ZERO = timedelta(0)                    # Zero timedelta constant
HOUR = timedelta(hours=1)              # One hour timedelta constant
UTC = ConstantTZInfo('UTC', ZERO)      # UTC timezone instance

# Epoch reference
EPOCH_AWARE = datetime(1970, 1, 1, tzinfo=UTC)  # Timezone-aware Unix epoch