custom-timezone-fdg 0.1.0__py3-none-any.whl

custom_timezone/__init__.py

@@ -0,0 +1,40 @@
+"""One configurable business time zone for any Python project.
+
+Plain Python, no framework required::
+
+    import custom_timezone as ct
+
+    ct.configure("America/Toronto")                 # or set CUSTOM_TIME_ZONE in the environment
+    start = ct.parse_local_datetime("2026-09-26T14:30")   # aware, America/Toronto
+    ct.format_datetime(start)                        # '2026-09-26 14:30:00 EDT'
+
+Django users additionally get an app config and a middleware (see the README); those live in
+``custom_timezone.apps`` and ``custom_timezone.middleware`` and are only imported by Django.
+"""
+from .config import DEFAULT_TIMEZONE, ENV_VAR, SETTING_NAME, configure, get_timezone, override
+from .core import (
+    format_datetime,
+    format_datetime_local,
+    localize_datetime,
+    now,
+    parse_local_datetime,
+    to_custom_timezone,
+)
+from .exceptions import (
+    AmbiguousTimeError,
+    CustomTimezoneError,
+    NonExistentTimeError,
+    TimezoneConfigurationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "configure", "get_timezone", "override",
+    "localize_datetime", "parse_local_datetime", "to_custom_timezone",
+    "format_datetime", "format_datetime_local", "now",
+    "CustomTimezoneError", "TimezoneConfigurationError",
+    "NonExistentTimeError", "AmbiguousTimeError",
+    "DEFAULT_TIMEZONE", "ENV_VAR", "SETTING_NAME",
+]

custom_timezone/apps.py

@@ -0,0 +1,45 @@
+"""Django app configuration (optional; only needed for the system checks)."""
+from __future__ import annotations
+
+from typing import Any, List
+
+from django.apps import AppConfig
+from django.core import checks
+
+from .config import get_timezone
+from .exceptions import TimezoneConfigurationError
+
+
+def check_custom_timezone(app_configs: Any = None, **kwargs: Any) -> List[checks.CheckMessage]:
+    """``manage.py check`` support: report a bad CUSTOM_TIME_ZONE instead of failing later."""
+    from django.conf import settings
+
+    problems: List[checks.CheckMessage] = []
+    try:
+        get_timezone()
+    except TimezoneConfigurationError as exc:
+        problems.append(
+            checks.Error(
+                str(exc),
+                hint="Set CUSTOM_TIME_ZONE to an IANA name such as 'America/Toronto'.",
+                id="custom_timezone.E001",
+            )
+        )
+    if not settings.USE_TZ:
+        problems.append(
+            checks.Warning(
+                "USE_TZ is False, so datetimes are stored without a time zone.",
+                hint="Set USE_TZ = True; custom_timezone is designed for aware datetimes.",
+                id="custom_timezone.W001",
+            )
+        )
+    return problems
+
+
+class CustomTimezoneConfig(AppConfig):
+    name = "custom_timezone"
+    label = "custom_timezone"
+    verbose_name = "Custom Time Zone"
+
+    def ready(self) -> None:
+        checks.register(check_custom_timezone)

custom_timezone/config.py

@@ -0,0 +1,120 @@
+"""Which time zone is "the custom time zone"?
+
+Resolution order (first match wins):
+
+1. ``with override("Asia/Shanghai"):``       - scoped to the current thread / asyncio task
+2. ``configure("America/Toronto")``       - process-wide, set explicitly in code
+3. Django's ``settings.CUSTOM_TIME_ZONE`` - only if Django is already loaded in this process
+4. the ``CUSTOM_TIME_ZONE`` environment variable
+5. ``"UTC"``
+
+Nothing here imports Django. Step 3 only looks at Django if *your program has already
+imported it*, so plain Python projects never pay for it (or need it installed).
+"""
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import os
+import sys
+from typing import Iterator, Optional, Union
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from .exceptions import TimezoneConfigurationError
+
+SETTING_NAME = "CUSTOM_TIME_ZONE"
+ENV_VAR = "CUSTOM_TIME_ZONE"
+DEFAULT_TIMEZONE = "UTC"
+
+TimezoneLike = Union[str, ZoneInfo]
+
+_configured: Optional[ZoneInfo] = None
+_override: "contextvars.ContextVar[Optional[ZoneInfo]]" = contextvars.ContextVar(
+    "custom_timezone_override", default=None
+)
+
+
+def _is_blank(value: object) -> bool:
+    return value is None or (isinstance(value, str) and not value.strip())
+
+
+def _load(value: object, source: str) -> ZoneInfo:
+    """Turn an IANA name (or an existing ZoneInfo) into a ZoneInfo, or raise a clear error."""
+    if isinstance(value, ZoneInfo):
+        return value
+    if not isinstance(value, str):
+        raise TimezoneConfigurationError(
+            f"{source} must be an IANA time zone name such as 'America/Toronto' "
+            f"(or a zoneinfo.ZoneInfo), not {type(value).__name__}."
+        )
+    name = value.strip()
+    try:
+        return ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError, OSError) as exc:
+        raise TimezoneConfigurationError(
+            f"{source} {name!r} is not a valid IANA time zone name "
+            "(for example 'America/Toronto')."
+        ) from exc
+
+
+def resolve_timezone(tz: Optional[TimezoneLike] = None) -> ZoneInfo:
+    """Return ``tz`` as a ZoneInfo, or the configured time zone when ``tz`` is None."""
+    if tz is None:
+        return get_timezone()
+    return _load(tz, "time zone")
+
+
+def _django_setting() -> object:
+    """Read ``settings.CUSTOM_TIME_ZONE`` if (and only if) Django is already loaded."""
+    conf = sys.modules.get("django.conf")
+    if conf is None:  # Django not imported (or not installed): never import it ourselves.
+        return None
+    from django.core.exceptions import ImproperlyConfigured  # safe: django.conf is loaded
+
+    try:
+        return getattr(conf.settings, SETTING_NAME)
+    except (ImproperlyConfigured, AttributeError):
+        return None  # settings not configured yet, or the project doesn't define the setting
+
+
+def get_timezone() -> ZoneInfo:
+    """Return the custom time zone as a :class:`zoneinfo.ZoneInfo` (see module docstring)."""
+    active = _override.get()
+    if active is not None:
+        return active
+    if _configured is not None:
+        return _configured
+
+    value = _django_setting()
+    source = f"Django setting {SETTING_NAME}"
+    if _is_blank(value):
+        value = os.environ.get(ENV_VAR)
+        source = f"Environment variable {ENV_VAR}"
+    if _is_blank(value):
+        return _load(DEFAULT_TIMEZONE, "default time zone")
+    return _load(value, source)
+
+
+def configure(tz: Optional[TimezoneLike]) -> None:
+    """Set the process-wide custom time zone. ``configure(None)`` clears it again.
+
+    The name is validated immediately, so a typo fails at start-up instead of on the first
+    request. Raises :class:`~custom_timezone.TimezoneConfigurationError` if it is invalid.
+    """
+    global _configured
+    _configured = None if tz is None else _load(tz, "configure() argument")
+
+
+@contextlib.contextmanager
+def override(tz: TimezoneLike) -> Iterator[ZoneInfo]:
+    """Temporarily use another custom time zone in the current thread / asyncio task.
+
+    Other threads and tasks are not affected, which makes it safe for per-request or
+    per-user time zones in web servers.
+    """
+    zone = _load(tz, "override() argument")
+    token = _override.set(zone)
+    try:
+        yield zone
+    finally:
+        _override.reset(token)

custom_timezone/core.py

@@ -0,0 +1,224 @@
+"""Date-time helpers built on the standard library only (``datetime`` + ``zoneinfo``)."""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any, Literal, Optional, Tuple
+
+from .config import TimezoneLike, resolve_timezone
+from .exceptions import AmbiguousTimeError, CustomTimezoneError, NonExistentTimeError
+
+# How to treat a wall-clock time that happens twice (clocks go back) ...
+Ambiguous = Literal["earliest", "latest", "raise"]
+# ... or that never happens (clocks jump forward) ...
+NonExistent = Literal["raise", "shift_forward", "shift_backward"]
+# ... and how to treat naive datetimes that are passed in for conversion.
+NaiveMode = Literal["local", "utc", "raise"]
+
+_UTC = timezone.utc
+DEFAULT_FORMAT = "%Y-%m-%d %H:%M:%S %Z"
+DATETIME_LOCAL_FORMAT = "%Y-%m-%dT%H:%M"
+
+_INVALID = "Enter a valid ISO 8601 date and time, for example 2026-09-26T14:30."
+_DATE_ONLY = "Enter a date and a time (for example 2026-09-26T14:30), not just a date."
+
+# Parsing is done with an explicit grammar rather than datetime.fromisoformat() so the
+# accepted input is identical on every supported Python version (3.9 .. 3.13).
+_DATETIME_RE = re.compile(
+    r"(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})"
+    r"[T ](?P<hour>\d{2}):(?P<minute>\d{2})"
+    r"(?::(?P<second>\d{2})(?:[.,](?P<fraction>\d{1,9}))?)?"
+    r"\s*(?P<offset>[Zz]|[+-]\d{2}(?::?\d{2})?)?",
+    re.ASCII,
+)
+_DATE_RE = re.compile(r"\d{4}-\d{2}-\d{2}", re.ASCII)
+
+
+def _check_choice(name: str, value: str, allowed: Tuple[str, ...]) -> None:
+    if value not in allowed:
+        raise ValueError(f"{name} must be one of {', '.join(map(repr, allowed))}; got {value!r}.")
+
+
+def _is_naive(value: datetime) -> bool:
+    return value.tzinfo is None or value.utcoffset() is None
+
+
+def _attach_zone(wall: datetime, tz: Any, ambiguous: str, nonexistent: str) -> datetime:
+    """Give a naive wall-clock time the zone ``tz``, applying the DST policies."""
+    wall = wall.replace(tzinfo=None, fold=0)
+    first = wall.replace(tzinfo=tz, fold=0)
+    second = wall.replace(tzinfo=tz, fold=1)
+    if first.utcoffset() == second.utcoffset():
+        return first  # the normal case: exists exactly once
+
+    # Offsets differ, so the time is either repeated (clocks go back) or skipped (clocks
+    # jump forward). A repeated time survives a round trip through UTC; a skipped one doesn't.
+    if first.astimezone(_UTC).astimezone(tz).replace(tzinfo=None) == wall:
+        if ambiguous == "raise":
+            raise AmbiguousTimeError(
+                f"{wall:%Y-%m-%d %H:%M} happens twice in {tz} (clocks go back); "
+                "choose ambiguous='earliest' or 'latest'."
+            )
+        return first if ambiguous == "earliest" else second
+
+    if nonexistent == "raise":
+        raise NonExistentTimeError(
+            f"{wall:%Y-%m-%d %H:%M} does not exist in {tz} (clocks jump forward)."
+        )
+    skipped = first if nonexistent == "shift_forward" else second
+    return skipped.astimezone(_UTC).astimezone(tz)
+
+
+def localize_datetime(
+    value: Optional[datetime],
+    *,
+    tz: Optional[TimezoneLike] = None,
+    ambiguous: Ambiguous = "earliest",
+    nonexistent: NonExistent = "raise",
+) -> Optional[datetime]:
+    """Make a naive datetime aware in the custom time zone; aware values are returned as-is.
+
+    ``ambiguous`` / ``nonexistent`` control what happens around daylight-saving changes
+    (see the README). By default the first occurrence of a repeated time is used and a
+    skipped time raises :class:`~custom_timezone.NonExistentTimeError`.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, datetime):
+        raise TypeError(f"Expected a datetime, got {type(value).__name__}.")
+    _check_choice("ambiguous", ambiguous, ("earliest", "latest", "raise"))
+    _check_choice("nonexistent", nonexistent, ("raise", "shift_forward", "shift_backward"))
+    if not _is_naive(value):
+        return value
+    return _attach_zone(value, resolve_timezone(tz), ambiguous, nonexistent)
+
+
+def _parse_offset(text: str) -> timezone:
+    if text in ("Z", "z"):
+        return _UTC
+    sign = -1 if text[0] == "-" else 1
+    digits = text[1:].replace(":", "")
+    hours = int(digits[:2])
+    minutes = int(digits[2:4]) if len(digits) > 2 else 0
+    if minutes > 59:
+        raise ValueError("minute offset out of range")
+    return timezone(sign * timedelta(hours=hours, minutes=minutes))  # ValueError if >= 24h
+
+
+def parse_local_datetime(
+    value: Any,
+    *,
+    tz: Optional[TimezoneLike] = None,
+    ambiguous: Ambiguous = "earliest",
+    nonexistent: NonExistent = "raise",
+    allow_date_only: bool = False,
+) -> Optional[datetime]:
+    """Parse an ISO 8601 date-time string; apply the custom time zone if it has no offset.
+
+    * ``None`` and blank strings return ``None``.
+    * ``"2026-09-26T14:30"`` (HTML ``datetime-local``), with optional seconds, fraction,
+      ``T`` or space separator, and an optional ``Z`` / ``+05:30`` / ``-0400`` offset.
+      An explicit offset is kept; otherwise the custom time zone is applied.
+    * Date-only strings (``"2026-09-26"``) are rejected unless ``allow_date_only=True``
+      (then they mean local midnight).
+    * Anything else - including non-string values such as numbers or dicts - raises
+      :class:`ValueError` (never ``TypeError``), so one ``except ValueError`` is enough.
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return localize_datetime(value, tz=tz, ambiguous=ambiguous, nonexistent=nonexistent)
+    if not isinstance(value, str):
+        raise ValueError(_INVALID)
+
+    text = value.strip()
+    if not text:
+        return None
+
+    match = _DATETIME_RE.fullmatch(text)
+    try:
+        if match is None:
+            if _DATE_RE.fullmatch(text):
+                if not allow_date_only:
+                    raise ValueError(_DATE_ONLY)
+                wall = datetime(int(text[0:4]), int(text[5:7]), int(text[8:10]))
+                return localize_datetime(wall, tz=tz, ambiguous=ambiguous, nonexistent=nonexistent)
+            raise ValueError(_INVALID)
+
+        parts = match.groupdict()
+        wall = datetime(
+            int(parts["year"]), int(parts["month"]), int(parts["day"]),
+            int(parts["hour"]), int(parts["minute"]), int(parts["second"] or 0),
+            int((parts["fraction"] or "").ljust(6, "0")[:6] or 0),
+        )
+        if parts["offset"]:
+            return wall.replace(tzinfo=_parse_offset(parts["offset"]))
+    except CustomTimezoneError:
+        raise  # daylight-saving errors keep their own, more specific message
+    except ValueError as exc:
+        if str(exc) in (_INVALID, _DATE_ONLY):
+            raise
+        raise ValueError(_INVALID) from exc  # e.g. month 13, Feb 30, hour 24, offset +25:00
+
+    return localize_datetime(wall, tz=tz, ambiguous=ambiguous, nonexistent=nonexistent)
+
+
+def to_custom_timezone(
+    value: Optional[datetime],
+    *,
+    tz: Optional[TimezoneLike] = None,
+    naive: NaiveMode = "local",
+) -> Optional[datetime]:
+    """Convert a datetime to the custom time zone (same instant, local wall-clock time).
+
+    Naive input is ambiguous by nature, so ``naive`` says what it means:
+    ``"local"`` (default) = already in the custom time zone, ``"utc"`` = it is UTC,
+    ``"raise"`` = refuse with :class:`ValueError`.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, datetime):
+        raise TypeError(f"Expected a datetime, got {type(value).__name__}.")
+    _check_choice("naive", naive, ("local", "utc", "raise"))
+    target = resolve_timezone(tz)
+    if _is_naive(value):
+        if naive == "raise":
+            raise ValueError("Refusing to convert a naive datetime (naive='raise').")
+        if naive == "utc":
+            value = value.replace(tzinfo=_UTC)
+        else:
+            value = _attach_zone(value, target, "earliest", "raise")
+    return value.astimezone(target)
+
+
+def format_datetime(
+    value: Optional[datetime],
+    fmt: str = DEFAULT_FORMAT,
+    *,
+    tz: Optional[TimezoneLike] = None,
+    naive: NaiveMode = "local",
+) -> str:
+    """Format a datetime after converting it to the custom time zone ('' for None)."""
+    local = to_custom_timezone(value, tz=tz, naive=naive)
+    return local.strftime(fmt) if local is not None else ""
+
+
+def format_datetime_local(
+    value: Optional[datetime],
+    *,
+    tz: Optional[TimezoneLike] = None,
+    naive: NaiveMode = "local",
+) -> str:
+    """Format for an HTML ``<input type="datetime-local">`` value ('' for None)."""
+    return format_datetime(value, DATETIME_LOCAL_FORMAT, tz=tz, naive=naive)
+
+
+def now(*, tz: Optional[TimezoneLike] = None) -> datetime:
+    """The current moment as an aware datetime in the custom time zone."""
+    return datetime.now(resolve_timezone(tz))
+
+
+__all__ = [
+    "localize_datetime", "parse_local_datetime", "to_custom_timezone",
+    "format_datetime", "format_datetime_local", "now",
+]

custom_timezone/exceptions.py

@@ -0,0 +1,22 @@
+"""Exceptions raised by custom_timezone.
+
+All of them subclass :class:`ValueError`, so existing ``except ValueError`` blocks (for
+example around user-supplied date-time strings) keep working.
+"""
+from __future__ import annotations
+
+
+class CustomTimezoneError(ValueError):
+    """Base class for every error raised by this package."""
+
+
+class TimezoneConfigurationError(CustomTimezoneError):
+    """The configured time zone name is missing from the IANA database or malformed."""
+
+
+class NonExistentTimeError(CustomTimezoneError):
+    """A wall-clock time that was skipped by a daylight-saving 'spring forward'."""
+
+
+class AmbiguousTimeError(CustomTimezoneError):
+    """A wall-clock time that happens twice because of a daylight-saving 'fall back'."""

custom_timezone/middleware.py

@@ -0,0 +1,43 @@
+"""Django middleware: activate the custom time zone for every request.
+
+Only imported by Django (via ``MIDDLEWARE``); the rest of the package never imports it.
+"""
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Union
+
+from asgiref.sync import iscoroutinefunction, markcoroutinefunction
+from django.http import HttpRequest, HttpResponse
+from django.utils import timezone
+
+from .config import get_timezone
+
+
+class CustomTimezoneMiddleware:
+    """Activate the custom time zone for forms, admin and template rendering.
+
+    Datetimes are still stored in UTC when ``USE_TZ=True``; activation only controls how naive
+    form input is interpreted and how aware values are displayed. Works under both WSGI and
+    ASGI, and restores whatever time zone was active before the request.
+    """
+
+    sync_capable = True
+    async_capable = True
+
+    def __init__(self, get_response: Callable[[HttpRequest], Any]) -> None:
+        self.get_response = get_response
+        self._async_mode = iscoroutinefunction(get_response)
+        if self._async_mode:
+            markcoroutinefunction(self)  # tells Django to await this instance
+
+    def __call__(self, request: HttpRequest) -> Union[HttpResponse, Awaitable[HttpResponse]]:
+        if self._async_mode:
+            return self.__acall__(request)
+        with timezone.override(get_timezone()):
+            response: HttpResponse = self.get_response(request)
+            return response
+
+    async def __acall__(self, request: HttpRequest) -> HttpResponse:
+        with timezone.override(get_timezone()):
+            response: HttpResponse = await self.get_response(request)
+            return response

custom_timezone/timezone_utils.py

@@ -0,0 +1,20 @@
+"""Backward-compatible import path.
+
+Older code imported the helpers from ``custom_timezone.timezone_utils``. That still works;
+new code can simply ``from custom_timezone import ...``.
+"""
+from __future__ import annotations
+
+from .config import get_timezone
+from .core import (
+    format_datetime,
+    format_datetime_local,
+    localize_datetime,
+    parse_local_datetime,
+    to_custom_timezone,
+)
+
+__all__ = [
+    "get_timezone", "localize_datetime", "parse_local_datetime",
+    "to_custom_timezone", "format_datetime", "format_datetime_local",
+]

custom_timezone_fdg-0.1.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: custom_timezone_fdg
+Version: 0.1.0
+Summary: Configurable business time zones and DST-aware datetime utilities, with optional Django integration
+Author: Hua Chen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/huachenlihx/custom_timezone_fdg
+Project-URL: Repository, https://github.com/huachenlihx/custom_timezone_fdg
+Project-URL: Issues, https://github.com/huachenlihx/custom_timezone_fdg/issues
+Keywords: timezone,zoneinfo,datetime,dst,django
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: Django
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tzdata
+Provides-Extra: django
+Requires-Dist: Django<7.0,>=4.2; extra == "django"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# Custom Timezone FDG
+
+A reusable Python package for working with a **configurable business time zone**, including daylight-saving-time (DST) edge cases. It can be used in regular Python programs, background workers and web applications, with **optional Django app and middleware integration**.
+
+- **Distribution:** `custom_timezone_fdg`
+- **Python import:** `custom_timezone`
+- **Initial package version:** `0.1.0` (as defined in `src/custom_timezone/__init__.py`)
+- **License:** MIT
+
+The core uses Python's `datetime` and `zoneinfo`; **Django is not required** to use the core helpers. The distribution also depends on `tzdata`, which supplies IANA time-zone data on platforms that do not provide it themselves.
+
+## Features
+
+- Configurable business time zone using an explicit override, process configuration, Django setting or environment variable.
+- Parsing and formatting datetimes with IANA time-zone names, including `America/Toronto`.
+- Explicit handling of **nonexistent** and **ambiguous** local times around DST transitions.
+- Thread- and asyncio-task-local temporary time-zone overrides.
+- Optional Django middleware that activates the configured time zone per request and restores the previous one afterward.
+- Django system checks for invalid time-zone settings and disabled timezone awareness.
+- Type information via `py.typed` and compatibility imports through `custom_timezone.timezone_utils`.
+
+## Requirements and installation
+
+The package declares **Python 3.9+**. Optional Django support declares **Django 4.2 through 6.x**, subject to the Python versions supported by each Django release. Test your particular Python/Django combination; the declared ranges do not mean that every combination has been independently verified.
+
+Install the core utilities:
+
+```bash
+python -m pip install custom_timezone_fdg
+```
+
+Install with Django integration dependencies:
+
+```bash
+python -m pip install "custom_timezone_fdg[django]"
+```
+
+The **distribution name** contains `_fdg`, but imports use `custom_timezone`:
+
+```python
+import custom_timezone as ct
+```
+
+If you're contributing from this repository, install it in editable mode:
+
+```bash
+python -m pip install -e ".[test,django]"
+```
+
+## Quick start (without Django)
+
+```python
+import custom_timezone as ct
+
+# Set the business time zone for this Python process.
+ct.configure("America/Toronto")
+
+# Interpret a wall-clock time entered without an offset.
+appointment = ct.parse_local_datetime("2026-09-26T14:30")
+print(appointment)                    # 2026-09-26 14:30:00-04:00
+print(ct.format_datetime(appointment))  # 2026-09-26 14:30:00 EDT
+
+# Convert a UTC instant to the configured business time zone.
+from datetime import datetime, timezone
+stored_utc = datetime(2026, 1, 1, 17, 0, tzinfo=timezone.utc)
+print(ct.to_custom_timezone(stored_utc))    # 2026-01-01 12:00:00-05:00
+print(ct.format_datetime_local(stored_utc)) # 2026-01-01T12:00
+
+# Use another zone temporarily (also works in async tasks).
+with ct.override("Asia/Shanghai"):
+    print(ct.now())
+```
+
+### Choose the business time zone
+
+The first available value is used:
+
+| Priority | Configuration | Scope |
+| --- | --- | --- |
+| 1 | `with ct.override("Asia/Shanghai")` | Current thread/asyncio task |
+| 2 | `ct.configure("America/Toronto")` | Python process |
+| 3 | Django `CUSTOM_TIME_ZONE` | If Django settings are already loaded |
+| 4 | `CUSTOM_TIME_ZONE` environment variable | Python process |
+| 5 | `UTC` | Default fallback |
+
+Configure a non-Django application using an environment variable:
+
+```bash
+export CUSTOM_TIME_ZONE=America/Toronto
+```
+
+Or in Python:
+
+```python
+ct.configure("America/Toronto")
+ct.configure(None)  # Clear the process override; use other configuration sources.
+```
+
+An invalid time-zone name raises `TimezoneConfigurationError`, which subclasses `ValueError`.
+
+## Core API
+
+| Function | Purpose |
+| --- | --- |
+| `get_timezone()` | Return the active `zoneinfo.ZoneInfo` |
+| `configure(tz)` | Set or clear the process-wide time zone |
+| `override(tz)` | Temporarily use another time zone |
+| `parse_local_datetime(text, ...)` | Parse ISO 8601 datetime text into an aware datetime |
+| `localize_datetime(dt, ...)` | Attach the selected time zone to a naive datetime |
+| `to_custom_timezone(dt, ...)` | Convert a datetime to the configured time zone |
+| `format_datetime(dt, ...)` | Format a datetime in the configured time zone |
+| `format_datetime_local(dt, ...)` | Format for HTML `datetime-local` input (`YYYY-MM-DDTHH:MM`) |
+| `now()` | Return the current time in the configured time zone |
+
+Most helpers also accept `tz="Europe/Paris"` to select a zone for a single call.
+
+### Parsing rules
+
+`parse_local_datetime()` accepts ISO-style date and time strings with a `T` or space separator, optionally including an offset. An explicit offset is retained. `None` or blank text returns `None`; invalid input raises `ValueError`.
+
+A date without a time is intentionally rejected by default:
+
+```python
+ct.parse_local_datetime("2026-09-26")  # ValueError
+ct.parse_local_datetime("2026-09-26", allow_date_only=True)  # Local midnight
+```
+
+### Daylight-saving transitions
+
+For `America/Toronto` in 2026, **March 8 at 02:30** does not exist because clocks move forward. **November 1 at 01:30** occurs twice when clocks move back.
+
+```python
+from datetime import datetime
+
+missing = datetime(2026, 3, 8, 2, 30)
+ct.localize_datetime(missing, nonexistent="raise")          # Default: NonExistentTimeError
+ct.localize_datetime(missing, nonexistent="shift_forward") # 03:30 EDT
+ct.localize_datetime(missing, nonexistent="shift_backward")# 01:30 EST
+
+repeated = datetime(2026, 11, 1, 1, 30)
+ct.localize_datetime(repeated, ambiguous="earliest")  # First occurrence (EDT)
+ct.localize_datetime(repeated, ambiguous="latest")    # Second occurrence (EST)
+ct.localize_datetime(repeated, ambiguous="raise")     # AmbiguousTimeError
+```
+
+Both exceptions subclass `ValueError`; the same options are available in `parse_local_datetime()`.
+
+### Naive datetimes
+
+With `to_custom_timezone()`, use the `naive=` parameter to specify how an unaware datetime should be interpreted: `"local"` (default), `"utc"`, or `"raise"`.
+
+## Optional Django integration
+
+Install with the `django` extra and configure your new or existing Django project:
+
+```python
+# settings.py
+import os
+
+INSTALLED_APPS = [
+    # Django's standard and project apps...
+    "custom_timezone.apps.CustomTimezoneConfig",
+]
+
+MIDDLEWARE = [
+    # Normal Django middleware...
+    "custom_timezone.middleware.CustomTimezoneMiddleware",
+]
+
+TIME_ZONE = "UTC"
+USE_TZ = True
+CUSTOM_TIME_ZONE = os.getenv("CUSTOM_TIME_ZONE", "America/Toronto")
+```
+
+**Add** these entries to your existing `INSTALLED_APPS` and `MIDDLEWARE` lists; do not replace the other middleware that Django requires. The shorter app entry `"custom_timezone"` is also supported.
+
+- The middleware activates the selected business time zone for each request, including Django templates, forms and Admin; the previous active zone is restored afterward.
+- Django can keep storing timestamps in UTC when `USE_TZ=True`.
+- `python manage.py check` reports `custom_timezone.E001` for an invalid configured zone and `custom_timezone.W001` if `USE_TZ=False`.
+- This Django app has no models or migrations.
+
+Verify with:
+
+```bash
+python manage.py check
+python manage.py test
+```
+
+### Using in other frameworks
+
+No framework-specific integration is required for regular scripts, FastAPI, Flask or task workers. To select a time zone for a single request or task, use `with ct.override("Area/City")` and ensure the context spans only the intended operation.
+
+## Replacing an existing in-project `custom_timezone` app
+
+The import paths `custom_timezone` and `custom_timezone.timezone_utils` are retained for common usage. However, the standalone package intentionally changes certain behaviours, so **test before replacing an existing application-specific implementation**.
+
+1. Remove or rename the old in-project `custom_timezone/` module so it cannot shadow the installed distribution.
+2. Install `custom_timezone_fdg[django]` in your project's environment.
+3. Retain or adapt your existing `INSTALLED_APPS`, middleware, imports and `CUSTOM_TIME_ZONE` setting.
+4. Run tests for datetime parsing, API validation and DST transitions before deploying.
+
+| Input/behaviour | Older in-project app | Package behaviour |
+| --- | --- | --- |
+| Nonexistent local time | Could silently shift forward | Raises `NonExistentTimeError` by default |
+| Date-only string | Could be treated as midnight | Rejected unless `allow_date_only=True` |
+| Invalid non-string input | Could raise `TypeError` or act as empty | Raises `ValueError` |
+| Invalid business time zone | Could raise `ImproperlyConfigured` | Raises `TimezoneConfigurationError` |
+| Middleware cleanup | Could reset to Django default | Restores previously active time zone |
+
+## Development, testing and publishing
+
+This repository uses the **`src/` layout**: distributable code lives in `src/custom_timezone/`, while tests and packaging files are at the repository root. Consumers still import `custom_timezone`—never `src.custom_timezone`.
+
+```bash
+python3.13 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[test,django]"
+python -m pytest
+```
+
+The `0.1.0` version is defined in `src/custom_timezone/__init__.py` through `__version__`. Update that value before creating a future release. The repository's `CHANGELOG.md` records release details.
+
+Build and inspect the distributions:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+unzip -l dist/*.whl
+```
+
+Before publishing, install the **built wheel** in a separate clean virtual environment and run its import and (if relevant) Django integration checks. Test on TestPyPI before publishing to PyPI; new uploads cannot overwrite an existing version's distribution filename.
+
+## Project links
+
+- Source repository: [GitHub](https://github.com/huachenlihx/custom_timezone_fdg)
+- Issues and feature requests: [GitHub Issues](https://github.com/huachenlihx/custom_timezone_fdg/issues)
+
+These links assume the repository is published under the shown name; update them if you choose a different repository name.
+
+## Contact
+
+**Email:** `huachenlihx@gmail.com`
+
+## License
+
+This project is licensed under the **MIT License**. See the [LICENSE](https://github.com/huachenlihx/custom_timezone_fdg/blob/main/LICENSE) file for the full license text.

custom_timezone_fdg-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+custom_timezone/__init__.py,sha256=sxR2WjdHIjy8_5xTGxZtBa1pxD10xzgL1EgZE9JeGq4,1357
+custom_timezone/apps.py,sha256=wnEzQNoSKE8whqCaCKguniBs3cV33YGbvZzCXmEAngc,1436
+custom_timezone/config.py,sha256=HkScb41JYjylhDbJYF_I8IVZpOcth4HCb6z6uUjGvkk,4253
+custom_timezone/core.py,sha256=nfG76yosmDy9zxwP-yZ7TnvwN5MNz1aeKC5TQGkfiO8,8969
+custom_timezone/exceptions.py,sha256=bBWamIuouGDz48bEXmAuFQ2uHNugztS0B4t0pGRdmMY,751
+custom_timezone/middleware.py,sha256=2AaanxWgzRXRb04LlTe1Q0jtM-4Jv_KfYZO49oqsLFA,1679
+custom_timezone/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+custom_timezone/timezone_utils.py,sha256=SxD4h2fa7ekfAZfhdgH9uAUO6qpuxVxW9lkwYHfVn0A,551
+custom_timezone_fdg-0.1.0.dist-info/licenses/LICENSE,sha256=kDt3b_PpMAh3dKRCk_KDvjSpg5YeBqqq1CjogpvwBiY,1065
+custom_timezone_fdg-0.1.0.dist-info/METADATA,sha256=0YlAiIEKJcDvT1fs5A96zckBU9mPkFkriaKCmx4Pmj4,11815
+custom_timezone_fdg-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+custom_timezone_fdg-0.1.0.dist-info/top_level.txt,sha256=IfjzA2LaHCHGeuoTeTU18vxLgGw0f5oTXLOa70As5W0,16
+custom_timezone_fdg-0.1.0.dist-info/RECORD,,

custom_timezone_fdg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

custom_timezone_fdg-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hua Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

custom_timezone_fdg-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+custom_timezone