API Reference

This section provides complete documentation for all public classes and functions.

Core API

x-zic - TZDB Parser Copyright (C) 2024 Your Name

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

x_zic.read_zones(region=None)[source]

Read all zones or zones from specific region.

x_zic.parse_zone(filename, loader)[source]

Parse zone file.

Parameters:

  • filename (str) – File to parse

  • loader – File loader instance

Returns:

List of Zone objects

Return type:

List[Zone]

x_zic.get_transitions(zone_name, start_year=1970, end_year=2030)[source]

Get timezone transitions for a zone.

x_zic.clear_cache()[source]

Clear all cached data

class x_zic.FileLoader(config)[source]

Bases: object

Smart file loader with caching

Parameters:

config (TZDBConfig) –

__init__(config)[source]
Parameters:

config (TZDBConfig) –

load_file(filename, use_cache=True)[source]

Load file with optional caching.

Parameters:

  • filename (str) – File to load

  • use_cache (bool) – Use cache if available

Returns:

List of file lines

Return type:

List[str]

file_exists(filename)[source]

Check if file exists in source directory

Parameters:

filename (str) –

Return type:

bool

clear_cache()[source]

Clear all cached data

class x_zic.TZDBConfig(tzdb_source_path='tzdb-2025b', cache_dir='.tzdb_cache', cache_enabled=True, cache_version='1.0', max_transition_years=100, region_files=None, legacy_files=None, geo_files=None)[source]

Bases: object

Configuration for TZDB parser

Parameters:

  • tzdb_source_path (str) –

  • cache_dir (str) –

  • cache_enabled (bool) –

  • cache_version (str) –

  • max_transition_years (int) –

  • region_files (List[str]) –

  • legacy_files (List[str]) –

  • geo_files (List[str]) –

tzdb_source_path: str = 'tzdb-2025b'
cache_dir: str = '.tzdb_cache'
cache_enabled: bool = True
cache_version: str = '1.0'
max_transition_years: int = 100
region_files: List[str] = None
legacy_files: List[str] = None
geo_files: List[str] = None
__init__(tzdb_source_path='tzdb-2025b', cache_dir='.tzdb_cache', cache_enabled=True, cache_version='1.0', max_transition_years=100, region_files=None, legacy_files=None, geo_files=None)
Parameters:

  • tzdb_source_path (str) –

  • cache_dir (str) –

  • cache_enabled (bool) –

  • cache_version (str) –

  • max_transition_years (int) –

  • region_files (List[str] | None) –

  • legacy_files (List[str] | None) –

  • geo_files (List[str] | None) –

Return type:

None

Core Module

Configuration

Configuration and constants Copyright (C) 2024 Your Name

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

class x_zic.core.config.TZDBConfig(tzdb_source_path='tzdb-2025b', cache_dir='.tzdb_cache', cache_enabled=True, cache_version='1.0', max_transition_years=100, region_files=None, legacy_files=None, geo_files=None)[source]

Configuration for TZDB parser

Parameters:

  • tzdb_source_path (str) –

  • cache_dir (str) –

  • cache_enabled (bool) –

  • cache_version (str) –

  • max_transition_years (int) –

  • region_files (List[str]) –

  • legacy_files (List[str]) –

  • geo_files (List[str]) –

tzdb_source_path: str = 'tzdb-2025b'
cache_dir: str = '.tzdb_cache'
cache_enabled: bool = True
cache_version: str = '1.0'
max_transition_years: int = 100
region_files: List[str] = None
legacy_files: List[str] = None
geo_files: List[str] = None
__init__(tzdb_source_path='tzdb-2025b', cache_dir='.tzdb_cache', cache_enabled=True, cache_version='1.0', max_transition_years=100, region_files=None, legacy_files=None, geo_files=None)
Parameters:

  • tzdb_source_path (str) –

  • cache_dir (str) –

  • cache_enabled (bool) –

  • cache_version (str) –

  • max_transition_years (int) –

  • region_files (List[str] | None) –

  • legacy_files (List[str] | None) –

  • geo_files (List[str] | None) –

Return type:

None

Models

Data models for TZDB entities Copyright (C) 2024 Your Name

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

class x_zic.core.models.Zone(name, offset, rules, format, until=None, region=None, line_number=None)[source]

Timezone zone definition

Parameters:

  • name (str) –

  • offset (str) –

  • rules (str) –

  • format (str) –

  • until (str | None) –

  • region (str | None) –

  • line_number (int | None) –

name: str
offset: str
rules: str
format: str
until: str | None = None
region: str | None = None
line_number: int | None = None
to_dict()[source]
Return type:

Dict[str, Any]

__init__(name, offset, rules, format, until=None, region=None, line_number=None)
Parameters:

  • name (str) –

  • offset (str) –

  • rules (str) –

  • format (str) –

  • until (str | None) –

  • region (str | None) –

  • line_number (int | None) –

Return type:

None

class x_zic.core.models.Rule(name, from_year, to_year, type, month, day, time, save, letter, region=None, line_number=None)[source]

DST rule definition

Parameters:

  • name (str) –

  • from_year (int) –

  • to_year (str) –

  • type (str) –

  • month (str) –

  • day (str) –

  • time (str) –

  • save (str) –

  • letter (str) –

  • region (str | None) –

  • line_number (int | None) –

name: str
from_year: int
to_year: str
type: str
month: str
day: str
time: str
save: str
letter: str
region: str | None = None
line_number: int | None = None
to_dict()[source]
Return type:

Dict[str, Any]

__init__(name, from_year, to_year, type, month, day, time, save, letter, region=None, line_number=None)
Parameters:

  • name (str) –

  • from_year (int) –

  • to_year (str) –

  • type (str) –

  • month (str) –

  • day (str) –

  • time (str) –

  • save (str) –

  • letter (str) –

  • region (str | None) –

  • line_number (int | None) –

Return type:

None

Timezone link/alias

Parameters:

  • target (str) –

  • alias (str) –

  • region (str | None) –

target: str
alias: str
region: str | None = None
to_dict()[source]
Return type:

Dict[str, Any]

__init__(target, alias, region=None)
Parameters:

  • target (str) –

  • alias (str) –

  • region (str | None) –

Return type:

None

class x_zic.core.models.Transition(zone, timestamp, offset_before, offset_after, is_dst, abbrev)[source]

Timezone transition

Parameters:

  • zone (str) –

  • timestamp (datetime) –

  • offset_before (str) –

  • offset_after (str) –

  • is_dst (bool) –

  • abbrev (str) –

zone: str
timestamp: datetime
offset_before: str
offset_after: str
is_dst: bool
abbrev: str
to_dict()[source]
Return type:

Dict[str, Any]

__init__(zone, timestamp, offset_before, offset_after, is_dst, abbrev)
Parameters:

  • zone (str) –

  • timestamp (datetime) –

  • offset_before (str) –

  • offset_after (str) –

  • is_dst (bool) –

  • abbrev (str) –

Return type:

None

class x_zic.core.models.LeapSecond(timestamp, total_offset, date)[source]

Leap second definition

Parameters:

  • timestamp (int) –

  • total_offset (int) –

  • date (str) –

timestamp: int
total_offset: int
date: str
to_dict()[source]
Return type:

Dict[str, Any]

__init__(timestamp, total_offset, date)
Parameters:

  • timestamp (int) –

  • total_offset (int) –

  • date (str) –

Return type:

None

Loader

File loading with caching Copyright (C) 2024 Your Name

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

class x_zic.core.loader.FileLoader(config)[source]

Smart file loader with caching

Parameters:

config (TZDBConfig) –

__init__(config)[source]
Parameters:

config (TZDBConfig) –

load_file(filename, use_cache=True)[source]

Load file with optional caching.

Parameters:

  • filename (str) – File to load

  • use_cache (bool) – Use cache if available

Returns:

List of file lines

Return type:

List[str]

file_exists(filename)[source]

Check if file exists in source directory

Parameters:

filename (str) –

Return type:

bool

clear_cache()[source]

Clear all cached data

Parser Module

Base Parser

Base parser with common utilities Copyright (C) 2024 Your Name

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

class x_zic.parser.base.BaseParser[source]

Base parser with common functionality

static split_line(line)[source]

Split line while handling comments and preserving structure.

Parameters:

line (str) – Input line

Returns:

List of parts

Return type:

List[str]

static parse_offset(offset_str)[source]

Parse timezone offset string to hours.

Parameters:

offset_str (str) – Offset string (e.g., “-5:00”, “1:30”)

Returns:

Offset in hours or None if invalid

Return type:

float | None

static parse_time(time_str)[source]

Parse time string to hours since midnight.

Parameters:

time_str (str) – Time string (e.g., “2:00”, “14:30:45”)

Returns:

Hours since midnight or None if invalid

Return type:

float | None

Zone Parser

Zone parser Copyright (C) 2024 Your Name

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

x_zic.parser.zone.parse_zone(filename, loader)[source]

Parse zone file.

Parameters:

  • filename (str) – File to parse

  • loader – File loader instance

Returns:

List of Zone objects

Return type:

List[Zone]

x_zic.parser.zone.parse_zone_line(line, region=None, line_number=None)[source]

Parse single zone line.

Parameters:

  • line (str) – Line to parse

  • region (str | None) – Region name

  • line_number (int | None) – Line number in file

Returns:

Zone object or None if not a zone line

Return type:

Zone | None

Rule Parser

Rule parser Copyright (C) 2024 Your Name

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

x_zic.parser.rule.parse_rule(filename, loader)[source]

Parse rule file.

Parameters:

  • filename (str) – File to parse

  • loader – File loader instance

Returns:

List of Rule objects

Return type:

List[Rule]

x_zic.parser.rule.parse_rule_line(line, region=None, line_number=None)[source]

Parse single rule line.

Parameters:

  • line (str) – Line to parse

  • region (str | None) – Region name

  • line_number (int | None) – Line number in file

Returns:

Rule object or None if not a rule line

Return type:

Rule | None

Regions Module

Region file management Copyright (C) 2024 Your Name

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

x_zic.regions.get_zones_by_region(region, loader)[source]

Get all zones from a region.

Parameters:

  • region (str) – Region name

  • loader – File loader

Returns:

List of zone dictionaries

Return type:

List[Dict[str, Any]]

x_zic.regions.get_rules_by_region(region, loader)[source]

Get all rules from a region.

Parameters:

  • region (str) – Region name

  • loader – File loader

Returns:

List of rule dictionaries

Return type:

List[Dict[str, Any]]

x_zic.regions.list_regions()[source]

Get list of all region names

Return type:

List[str]

Transitions Module

Transition calculations

x_zic.transitions.get_transitions(zone_name, start_year=1970, end_year=2030, loader=None)[source]

Calculate transitions for a zone.

Parameters:

  • zone_name (str) – Zone identifier

  • start_year (int) – Start year

  • end_year (int) – End year

  • loader – File loader

Returns:

List of transition dictionaries

Return type:

List[Dict[str, Any]]

Calculator

Transition calculator - core DST logic

x_zic.transitions.calculator.get_transitions(zone_name, start_year=1970, end_year=2030, loader=None)[source]

Calculate transitions for a zone.

Parameters:

  • zone_name (str) – Zone identifier

  • start_year (int) – Start year

  • end_year (int) – End year

  • loader – File loader

Returns:

List of transition dictionaries

Return type:

List[Dict[str, Any]]

x_zic.transitions.calculator.calculate_dst_transitions(zone, rules, year)[source]

Calculate DST transitions for a zone in a specific year.

Parameters:

  • zone (Zone) – Zone definition

  • rules (List[Rule]) – Applicable rules

  • year (int) – Year to calculate

Returns:

List of transition dictionaries

Return type:

List[Dict[str, Any]]

Geo Module

Analysis Module

Export Module

Data Types

Zone

class x_zic.core.models.Zone(name, offset, rules, format, until=None, region=None, line_number=None)[source]

Timezone zone definition

Parameters:

  • name (str) –

  • offset (str) –

  • rules (str) –

  • format (str) –

  • until (str | None) –

  • region (str | None) –

  • line_number (int | None) –

name: str
offset: str
rules: str
format: str
until: str | None = None
region: str | None = None
line_number: int | None = None
to_dict()[source]
Return type:

Dict[str, Any]

__init__(name, offset, rules, format, until=None, region=None, line_number=None)
Parameters:

  • name (str) –

  • offset (str) –

  • rules (str) –

  • format (str) –

  • until (str | None) –

  • region (str | None) –

  • line_number (int | None) –

Return type:

None

Rule

class x_zic.core.models.Rule(name, from_year, to_year, type, month, day, time, save, letter, region=None, line_number=None)[source]

DST rule definition

Parameters:

  • name (str) –

  • from_year (int) –

  • to_year (str) –

  • type (str) –

  • month (str) –

  • day (str) –

  • time (str) –

  • save (str) –

  • letter (str) –

  • region (str | None) –

  • line_number (int | None) –

name: str
from_year: int
to_year: str
type: str
month: str
day: str
time: str
save: str
letter: str
region: str | None = None
line_number: int | None = None
to_dict()[source]
Return type:

Dict[str, Any]

__init__(name, from_year, to_year, type, month, day, time, save, letter, region=None, line_number=None)
Parameters:

  • name (str) –

  • from_year (int) –

  • to_year (str) –

  • type (str) –

  • month (str) –

  • day (str) –

  • time (str) –

  • save (str) –

  • letter (str) –

  • region (str | None) –

  • line_number (int | None) –

Return type:

None

Transition

class x_zic.core.models.Transition(zone, timestamp, offset_before, offset_after, is_dst, abbrev)[source]

Timezone transition

Parameters:

  • zone (str) –

  • timestamp (datetime) –

  • offset_before (str) –

  • offset_after (str) –

  • is_dst (bool) –

  • abbrev (str) –

zone: str
timestamp: datetime
offset_before: str
offset_after: str
is_dst: bool
abbrev: str
to_dict()[source]
Return type:

Dict[str, Any]

__init__(zone, timestamp, offset_before, offset_after, is_dst, abbrev)
Parameters:

  • zone (str) –

  • timestamp (datetime) –

  • offset_before (str) –

  • offset_after (str) –

  • is_dst (bool) –

  • abbrev (str) –

Return type:

None

LeapSecond

class x_zic.core.models.LeapSecond(timestamp, total_offset, date)[source]

Leap second definition

Parameters:

  • timestamp (int) –

  • total_offset (int) –

  • date (str) –

timestamp: int
total_offset: int
date: str
to_dict()[source]
Return type:

Dict[str, Any]

__init__(timestamp, total_offset, date)
Parameters:

  • timestamp (int) –

  • total_offset (int) –

  • date (str) –

Return type:

None

Exceptions