aiozoneinfo

0.2.3 verified Thu Apr 16 auth: no python

aiozoneinfo is an asyncio-compatible Python library that provides tools to asynchronously fetch and access zoneinfo timezone data. It integrates seamlessly with asynchronous applications requiring up-to-date timezone information. The current version is 0.2.3, with a release cadence focused on minor fixes and improvements.

pip install aiozoneinfo

Common errors

error ModuleNotFoundError: No module named 'aiozoneinfo' ↓

cause The aiozoneinfo library has not been installed in your current Python environment.

fix

Install the library using pip: pip install aiozoneinfo

error aiozoneinfo.exceptions.ZoneInfoNotFound: Timezone 'Some/Invalid_Zone' not found ↓

cause The specified timezone identifier is not a valid IANA Time Zone Database name or could not be found by the service.

fix

Verify the timezone string is correct (e.g., 'America/New_York', 'Europe/Paris'). Check the IANA Time Zone Database for valid names.

error RuntimeError: An asyncio.Future, a coroutine or an awaitable is required instead of None ↓

cause You likely forgot to `await` a call to an aiozoneinfo async method, leading to a coroutine object being passed where an awaited result was expected.

fix

Ensure all calls to aiozoneinfo methods (like async_get_timezone) are prefixed with await.

Warnings

gotcha aiozoneinfo relies on an active internet connection to fetch timezone data. Operations will fail if there is no network connectivity or if the remote server is unreachable. ↓

fix Ensure stable network connectivity. Implement retry mechanisms or local caching for resilience in production environments.

gotcha Incorrect or misspelled timezone names passed to `async_get_timezone` will result in an `aiozoneinfo.exceptions.ZoneInfoNotFound` exception. ↓

fix Always use valid IANA Time Zone Database names (e.g., 'America/New_York', 'Europe/London'). Consider validating user input against a known list of timezones.

gotcha As an asyncio library, ensure all calls to `aiozoneinfo` methods are `await`ed within an `async` function and executed within an asyncio event loop (e.g., via `asyncio.run()`). ↓

fix Prefix all `aiozoneinfo` method calls with `await`. Wrap your top-level async function with `asyncio.run()` when running from a synchronous context.

Imports

ZoneInfo
```
from aiozoneinfo import ZoneInfo
```

Quickstart

This quickstart demonstrates how to initialize the `ZoneInfo` client and asynchronously fetch timezone data using `async_get_timezone`. It also includes basic error handling for invalid timezone names.

import asyncio
from aiozoneinfo import ZoneInfo

async def get_timezone_data(timezone_name: str):
    """Fetches timezone data asynchronously."""
    zoneinfo_fetcher = ZoneInfo()
    try:
        tz = await zoneinfo_fetcher.async_get_timezone(timezone_name)
        print(f"Fetched timezone for {timezone_name}: {tz}")
        # You can now use 'tz' with datetime objects:
        # import datetime
        # dt_utc = datetime.datetime.now(datetime.timezone.utc)
        # dt_local = dt_utc.astimezone(tz)
        # print(f"Current time in {timezone_name}: {dt_local}")
    except Exception as e:
        print(f"Error fetching timezone {timezone_name}: {e}")

async def main():
    await get_timezone_data("America/New_York")
    await get_timezone_data("Europe/London")
    await get_timezone_data("Invalid/Timezone")

if __name__ == "__main__":
    asyncio.run(main())