Timezone Tools

0.1.0.post1 verified Sat May 09 auth: no python

A Python library providing utilities for working with timezone-aware datetimes, including conversion, formatting, and common timezone operations. Current version 0.1.0.post1, requires Python >=3.10. Active development.

pip install timezone-tools

Common errors

error pytz.exceptions.UnknownTimeZoneError: 'US/Eastern' ↓

cause Using an outdated or incorrect timezone string. 'US/Eastern' is deprecated; use 'America/New_York'.

fix

Replace 'US/Eastern' with 'America/New_York' or another valid IANA timezone.

error AttributeError: 'TimezoneConverter' object has no attribute 'convert' ↓

cause The method may be named differently or not exist in the current version.

fix

Check the API documentation. Likely use converter.to_timezone(dt, target_tz) instead of convert.

Warnings

gotcha TimezoneConverter may use pytz timezone objects; ensure you pass a valid IANA timezone string (e.g., 'America/New_York'). Invalid strings may raise a pytz.exceptions.UnknownTimeZoneError. ↓

fix Use only valid IANA timezone identifiers. Check with pytz.all_timezones if unsure.

gotcha The library is in an early release (0.1.0.post1). APIs may change without notice. Pin your dependency to a specific version in production. ↓

fix Pin to timezone-tools==0.1.0.post1 in requirements.txt or setup.py.

deprecated The use of 'pytz' is deprecated in favor of 'zoneinfo' (available in Python 3.9+). This library currently uses pytz, but future versions may migrate to zoneinfo. ↓

fix Prepare to migrate code that relies on pytz behavior; monitor the library's future releases.

Imports

TimezoneConverter

wrong

from timezone_tools.converter import TimezoneConverter

correct

from timezone_tools import TimezoneConverter

Importing from submodule may not be exposed.

format_aware_datetime

wrong

from timezone_tools.utils import format_aware_datetime

correct

from timezone_tools import format_aware_datetime

Utilities are not a public submodule.

utcnow

wrong

from timezone_tools.helpers import utcnow

correct

from timezone_tools import utcnow

Helper functions are accessible directly from package.

Quickstart

Initialize a TimezoneConverter, create an aware datetime in a specific timezone, and format it using a custom pattern.

from timezone_tools import TimezoneConverter, format_aware_datetime
from datetime import datetime
import os

tz = 'America/New_York'
converter = TimezoneConverter()
dt = datetime.now(tz=tz)
formatted = format_aware_datetime(dt, 'YYYY-MM-DD HH:mm:ss')
print(formatted)