django-multisite2 3.0.0__tar.gz → 3.1.0__tar.gz

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-multisite2
-Version: 3.0.0
+Version: 3.1.0
 Summary: Serve multiple sites from a single Django application
 Keywords: django,nginx,edc,clinical trials,research,data management,gunicorn,deployment
 Author: Leonid S Shestera
@@ -303,15 +303,15 @@ Per-site time zones
 thread, so Django renders every datetime in local time for whichever site served the
 request. It is the time zone equivalent of what ``SiteID`` does for ``SITE_ID``.
 
-Map each site to a time zone in settings.py. Values may be an IANA key or a ``ZoneInfo``::
+Map each site to a time zone in settings.py. Values must be an IANA key::
 
     MULTISITE_TIME_ZONES = {
         1: "Africa/Dar_es_Salaam",
         2: "America/New_York",
     }
 
-Then add the middleware, which must come AFTER ``DynamicSiteMiddleware``, since that is
-what resolves ``SITE_ID`` for the request:
+
+Add the middleware after ``DynamicSiteMiddleware``
 
 .. code-block::
 
@@ -329,11 +329,10 @@ The lookup itself is available directly::
 
     from multisite.utils import get_multisite_timezone
 
-``get_multisite_timezone()`` returns the IANA key of the time zone for the current
-``SITE_ID``, always as a ``str``. It falls back to ``settings.TIME_ZONE`` and issues a
-``RuntimeWarning`` if ``MULTISITE_TIME_ZONES`` is unset or has no entry for the current
-site, and returns ``settings.TIME_ZONE`` without warning when ``SITE_ID`` is a plain
-integer rather than a ``SiteID``.
+``get_multisite_timezone(site_id=None)`` returns the time zone for ``site_id``, or for the
+current ``SITE_ID`` if not given. It requires ``DynamicSiteTimezoneMiddleware`` in
+``MIDDLEWARE`` and raises ``MultisiteTimezoneError`` otherwise, or if ``site_id`` has no
+entry in ``MULTISITE_TIME_ZONES``. The current site falls back to ``settings.TIME_ZONE``.
 
 Outside a request, in management commands, signal handlers or queue workers, no time zone
 is activated and Django falls back to ``settings.TIME_ZONE``. Wrap the entry point as you
@@ -347,8 +346,8 @@ would with ``SiteID.override()``::
 Three system checks cover the configuration:
 
 * ``multisite.E001`` if ``DynamicSiteTimezoneMiddleware`` is listed before ``DynamicSiteMiddleware``
-* ``multisite.W001`` if ``DynamicSiteMiddleware`` is missing altogether
-* ``multisite.W002`` (deploy only) if ``MULTISITE_TIME_ZONES`` is set but the middleware is not installed
+* ``multisite.E002`` if the middleware is installed but ``MULTISITE_TIME_ZONES`` is missing or empty
+* ``multisite.E003`` if ``DynamicSiteMiddleware`` is missing altogether
 
 
 Development Environments

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/README.rst

@@ -275,15 +275,15 @@ Per-site time zones
 thread, so Django renders every datetime in local time for whichever site served the
 request. It is the time zone equivalent of what ``SiteID`` does for ``SITE_ID``.
 
-Map each site to a time zone in settings.py. Values may be an IANA key or a ``ZoneInfo``::
+Map each site to a time zone in settings.py. Values must be an IANA key::
 
     MULTISITE_TIME_ZONES = {
         1: "Africa/Dar_es_Salaam",
         2: "America/New_York",
     }
 
-Then add the middleware, which must come AFTER ``DynamicSiteMiddleware``, since that is
-what resolves ``SITE_ID`` for the request:
+
+Add the middleware after ``DynamicSiteMiddleware``
 
 .. code-block::
 
@@ -301,11 +301,10 @@ The lookup itself is available directly::
 
     from multisite.utils import get_multisite_timezone
 
-``get_multisite_timezone()`` returns the IANA key of the time zone for the current
-``SITE_ID``, always as a ``str``. It falls back to ``settings.TIME_ZONE`` and issues a
-``RuntimeWarning`` if ``MULTISITE_TIME_ZONES`` is unset or has no entry for the current
-site, and returns ``settings.TIME_ZONE`` without warning when ``SITE_ID`` is a plain
-integer rather than a ``SiteID``.
+``get_multisite_timezone(site_id=None)`` returns the time zone for ``site_id``, or for the
+current ``SITE_ID`` if not given. It requires ``DynamicSiteTimezoneMiddleware`` in
+``MIDDLEWARE`` and raises ``MultisiteTimezoneError`` otherwise, or if ``site_id`` has no
+entry in ``MULTISITE_TIME_ZONES``. The current site falls back to ``settings.TIME_ZONE``.
 
 Outside a request, in management commands, signal handlers or queue workers, no time zone
 is activated and Django falls back to ``settings.TIME_ZONE``. Wrap the entry point as you
@@ -319,8 +318,8 @@ would with ``SiteID.override()``::
 Three system checks cover the configuration:
 
 * ``multisite.E001`` if ``DynamicSiteTimezoneMiddleware`` is listed before ``DynamicSiteMiddleware``
-* ``multisite.W001`` if ``DynamicSiteMiddleware`` is missing altogether
-* ``multisite.W002`` (deploy only) if ``MULTISITE_TIME_ZONES`` is set but the middleware is not installed
+* ``multisite.E002`` if the middleware is installed but ``MULTISITE_TIME_ZONES`` is missing or empty
+* ``multisite.E003`` if ``DynamicSiteMiddleware`` is missing altogether
 
 
 Development Environments

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "django-multisite2"
-version = "3.0.0"
+version = "3.1.0"
 description = "Serve multiple sites from a single Django application"
 keywords = [
     "django",

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "django-multisite2"
-version = "3.0.0"
+version = "3.1.0"
 description = "Serve multiple sites from a single Django application"
 readme = { file = "README.rst", content-type = "text/x-rst" }
 keywords = ["django", "nginx", "edc", "clinical trials", "research", "data management", "gunicorn", "deployment"]

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/src/multisite/apps.py

@@ -27,7 +27,7 @@ class AppConfig(DjangoAppConfig):
 
     def ready(self):
         register(multisite_middleware_check)
-        register(multisite_timezone_setting_check, deploy=True)
+        register(multisite_timezone_setting_check)
         if not getattr(settings, "MULTISITE_REGISTER_POST_MIGRATE_SYNC_ALIAS", True):
             post_migrate.connect(
                 post_migrate_sync_alias,

django_multisite2-3.1.0/src/multisite/constants.py

@@ -0,0 +1,2 @@
+DYNAMIC_SITE_MIDDLEWARE = "multisite.middleware.DynamicSiteMiddleware"
+DYNAMIC_SITE_TIMEZONE_MIDDLEWARE = "multisite.middleware.DynamicSiteTimezoneMiddleware"

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/src/multisite/exceptions.py

@@ -37,6 +37,10 @@ class MultisiteCookieDomainDepthError(Exception):
     pass
 
 
+class MultisiteTimezoneError(Exception):
+    pass
+
+
 def debug_raise_disallowed_host_exception(e):
     if getattr(settings, "MULTISITE_DEBUG", None):
         raise MultisiteDisallowedHost(

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/src/multisite/middleware/dynamic_site_timezone_middleware.py

@@ -9,6 +9,14 @@ class DynamicSiteTimezoneMiddleware:
     Must be listed AFTER `multisite.middleware.DynamicSiteMiddleware`,
     which resolves `settings.SITE_ID` for this request.
 
+    Requires settings.MULTISITE_TIME_ZONES format {site_id: IANA key}.
+    For example:
+        MULTISITE_TIME_ZONES = {
+            10: "Africa/Gaborone",
+            20: "Africa/Dar_es_Salaam",
+            30: "Africa/Lagos",
+        }
+
     Outside a request (management commands, signals, workers) nothing
     is activated and Django falls back to `settings.TIME_ZONE`. Use
     `timezone.override(get_multisite_timezone())` there, as you would use

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/src/multisite/system_checks.py

@@ -1,10 +1,9 @@
 from __future__ import annotations
 
 from django.conf import settings
-from django.core.checks import CheckMessage, Error, Warning
+from django.core.checks import CheckMessage, Error
 
-DYNAMIC_SITE_MIDDLEWARE = "multisite.middleware.DynamicSiteMiddleware"
-DYNAMIC_SITE_TIMEZONE_MIDDLEWARE = "multisite.middleware.DynamicSiteTimezoneMiddleware"
+from .constants import DYNAMIC_SITE_MIDDLEWARE, DYNAMIC_SITE_TIMEZONE_MIDDLEWARE
 
 
 def multisite_middleware_check(app_configs, **kwargs) -> list[CheckMessage]:  # noqa: ARG001
@@ -22,14 +21,14 @@ def multisite_middleware_check(app_configs, **kwargs) -> list[CheckMessage]:  #
         return errors
     if DYNAMIC_SITE_MIDDLEWARE not in middleware:
         errors.append(
-            Warning(
-                f"Missing MIDDLEWARE. `{DYNAMIC_SITE_TIMEZONE_MIDDLEWARE}` has no effect "
-                f"without `{DYNAMIC_SITE_MIDDLEWARE}`.",
+            Error(
+                f"Missing MIDDLEWARE. `{DYNAMIC_SITE_TIMEZONE_MIDDLEWARE}` "
+                f"requires `{DYNAMIC_SITE_MIDDLEWARE}`.",
                 hint=(
-                    "Without it `settings.SITE_ID` is never resolved for the request, so "
-                    "the default site's timezone is activated every time."
+                    f"Add `{DYNAMIC_SITE_MIDDLEWARE}` to settings "
+                    f"before `{DYNAMIC_SITE_TIMEZONE_MIDDLEWARE}`."
                 ),
-                id="multisite.W001",
+                id="multisite.E003",
             )
         )
     elif middleware.index(DYNAMIC_SITE_TIMEZONE_MIDDLEWARE) < middleware.index(
@@ -50,24 +49,18 @@ def multisite_middleware_check(app_configs, **kwargs) -> list[CheckMessage]:  #
 
 
 def multisite_timezone_setting_check(app_configs, **kwargs) -> list[CheckMessage]:  # noqa: ARG001
-    """Checks that `settings.MULTISITE_TIME_ZONES`, if set, is acted on.
-
-    Registered with `deploy=True`, so it runs under `check --deploy`
-    and not on every test run.
-    """
+    """Checks that `settings.MULTISITE_TIME_ZONES`, if set, is acted on."""
     errors: list[CheckMessage] = []
-    if getattr(settings, "MULTISITE_TIME_ZONES", None) and (
-        DYNAMIC_SITE_TIMEZONE_MIDDLEWARE
-        not in list(getattr(settings, "MIDDLEWARE", None) or [])
+    if not getattr(settings, "MULTISITE_TIME_ZONES", None) and (
+        DYNAMIC_SITE_TIMEZONE_MIDDLEWARE in (list(getattr(settings, "MIDDLEWARE", None) or []))
     ):
         errors.append(
-            Warning(
-                "settings.MULTISITE_TIME_ZONES is set but has no effect.",
-                hint=(
-                    f"Add `{DYNAMIC_SITE_TIMEZONE_MIDDLEWARE}` to MIDDLEWARE, after "
-                    f"`{DYNAMIC_SITE_MIDDLEWARE}`."
-                ),
-                id="multisite.W002",
+            Error(
+                "settings.MULTISITE_TIME_ZONES is missing or not set. "
+                f"MULTISITE_TIME_ZONES is required if {DYNAMIC_SITE_TIMEZONE_MIDDLEWARE} "
+                "is active in middleware.",
+                hint="Add `MULTISITE_TIME_ZONES` to settings.",
+                id="multisite.E002",
             )
         )
     return errors

{django_multisite2-3.0.0 → django_multisite2-3.1.0}/src/multisite/utils.py

@@ -15,6 +15,8 @@ from django.core.exceptions import (
 from django.http import Http404
 from django.urls import get_callable
 
+from .constants import DYNAMIC_SITE_TIMEZONE_MIDDLEWARE
+from .exceptions import MultisiteTimezoneError
 from .threadlocals import SiteID
 
 if TYPE_CHECKING:
@@ -179,35 +181,41 @@ def get_user_sites(request) -> QuerySet[Site]:
     return sites
 
 
-def get_multisite_timezone() -> str:
-    """Returns the IANA key of the time zone for the current site.
+def get_multisite_timezone(site_id: int | None = None) -> str:
+    """Returns the IANA key of the time zone for the given site.
 
-    Values in `settings.MULTISITE_TIME_ZONES` may be given as a str
-    or as a `ZoneInfo`. Either way a str is returned, since callers
-    pass the result straight to `ZoneInfo()`.
+    Requires `DynamicSiteTimezoneMiddleware` and that the given site
+    exist in settings.MULTISITE_TIME_ZONES.
+
+    See also DynamicSiteTimezoneMiddleware and system checks.
     """
-    timezone = settings.TIME_ZONE
-    if isinstance(settings.SITE_ID, SiteID):
-        site_timezones = getattr(settings, "MULTISITE_TIME_ZONES", {})
-        if not site_timezones:
-            warnings.warn(
-                (
-                    "settings.MULTISITE_TIME_ZONES not set for multisite trial. "
-                    f"Defaulting to {settings.TIME_ZONE}"
-                ),
-                RuntimeWarning,
-                stacklevel=2,
-            )
-        elif not site_timezones.get(settings.SITE_ID):
-            warnings.warn(
-                (
-                    "settings.MULTISITE_TIME_ZONES missing timezone for site "
-                    f"{settings.SITE_ID}. Defaulting to {settings.TIME_ZONE}. "
-                    f"Got {settings.MULTISITE_TIME_ZONES}."
-                ),
-                RuntimeWarning,
-                stacklevel=2,
-            )
-        else:
-            timezone = site_timezones.get(settings.SITE_ID)
-    return str(timezone)
+
+    timezone_data: dict[int | str, str] = getattr(settings, "MULTISITE_TIME_ZONES", {})
+    if DYNAMIC_SITE_TIMEZONE_MIDDLEWARE not in (
+        list(getattr(settings, "MIDDLEWARE", None) or [])
+    ):
+        func_name = sys._getframe().f_code.co_name
+        raise MultisiteTimezoneError(
+            "Middleware needed for function. "
+            f"Add `{DYNAMIC_SITE_TIMEZONE_MIDDLEWARE}` to MIDDLEWARE. "
+            f"Got function `{func_name}`."
+        )
+
+    if isinstance(settings.SITE_ID, SiteID) and not timezone_data:
+        warnings.warn(
+            (
+                "settings.MULTISITE_TIME_ZONES not set for multisite deployment. "
+                f"Defaulting to {settings.TIME_ZONE}. Try adding MULTISITE_TIME_ZONES "
+                "to your settings."
+            ),
+            RuntimeWarning,
+            stacklevel=2,
+        )
+    if site_id is not None and not timezone_data.get(site_id):
+        raise MultisiteTimezoneError(
+            "settings.MULTISITE_TIME_ZONES missing timezone for site_id. "
+            f"Expected one of {timezone_data}. Got site_id={site_id}."
+        )
+
+    site_id: str = settings.SITE_ID if site_id is None else site_id
+    return timezone_data.get(site_id) or settings.TIME_ZONE