aiozoneinfo

0.2.3 · active · verified Thu Apr 16

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.

Common errors

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

Install

pip install aiozoneinfo Install aiozoneinfo

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

view raw JSON →