Typing Stubs for tzlocal

5.1.0.1 · active · verified Sat Apr 11

types-tzlocal provides static type annotations (stubs) for the `tzlocal` library, which is used to obtain the local timezone as a `tzinfo` object. The current version, 5.1.0.1, specifically targets `tzlocal` versions up to 5.1. Note that as of `tzlocal` version 5.2, the core library includes its own type annotations, making `types-tzlocal` redundant for newer versions of `tzlocal`. It is maintained as part of the `typeshed` project and receives updates aligned with `tzlocal` releases.

Warnings

breaking With tzlocal version 5.0, the `pytz_deprecation_shim` was removed. This means `tzlocal.get_localzone()` now exclusively returns `zoneinfo` objects, similar to version 3.0. If your application relies on `pytz` objects, you must remain on `tzlocal` version 4.x or adapt your code to `zoneinfo`'s API.
Fix: Either pin 'tzlocal<5' if `pytz` compatibility is essential, or update your code to work with `zoneinfo.ZoneInfo` objects (standard in Python 3.9+).
gotcha Since `tzlocal` version 5.2, the `tzlocal` library itself bundles its type annotations (stubs). If you are using `tzlocal` 5.2 or newer, `types-tzlocal` becomes redundant and should be uninstalled to avoid potential conflicts or unnecessary package overhead.
Fix: Run `pip uninstall types-tzlocal` if your `tzlocal` version is 5.2 or higher.
gotcha On some Unix-like systems, if the timezone name is not properly configured (e.g., in `/etc/timezone` or via symlinks), `tzlocal.get_localzone_name()` might raise an error, while `tzlocal.get_localzone()` would still successfully return a `tzinfo` object. Unconfigured systems might default to UTC.
Fix: Ensure your operating system's timezone configuration is correctly set up. If only the `tzinfo` object is needed, prefer `get_localzone()` over `get_localzone_name()`.
deprecated The `pytz_deprecation_shim` was introduced in `tzlocal` 4.0 to restore partial `pytz` compatibility after `tzlocal` 3.0 switched to `zoneinfo` objects. This shim was then removed in `tzlocal` 5.0. Relying on it for `pytz` compatibility in `tzlocal` 4.x is a temporary measure and should be migrated away from.
Fix: Migrate to using `zoneinfo.ZoneInfo` objects (native in Python 3.9+) or other modern timezone handling, or explicitly manage `pytz` directly if specific `pytz` features are required.

Install

pip install types-tzlocal Install types-tzlocal

Imports

get_localzone
```
from tzlocal import get_localzone
```
get_localzone_name
```
from tzlocal import get_localzone_name
```
Only use if the timezone name is strictly required; get_localzone() is generally preferred.

Quickstart

Demonstrates how to retrieve the local timezone `tzinfo` object and create a timezone-aware `datetime` object using `tzlocal`. It also shows how to get the timezone name, with a note about potential failures on some systems.

from datetime import datetime
from tzlocal import get_localzone

# Get the local timezone tzinfo object
local_tz = get_localzone()
print(f"Local timezone: {local_tz}")

# Create a timezone-aware datetime object
now_naive = datetime.now()
now_aware = local_tz.localize(now_naive)
print(f"Timezone-aware datetime: {now_aware}")

# Get just the timezone name (may fail on some Unix systems)
try:
    local_tz_name = get_localzone_name()
    print(f"Local timezone name: {local_tz_name}")
except Exception as e:
    print(f"Could not get local timezone name: {e}")

view raw JSON →