busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

semantics

Browse Source
This commit is contained in:
busya
2026-05-26 09:30:41 +03:00
parent 1e7bcecaea
commit 9ffa8af1dc
623 changed files with 28045 additions and 26557 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
backend/src/core/timezone.py
View File

@@ -2,7 +2,7 @@
# @BRIEF Application-level timezone utilities. Reads APP_TIMEZONE from env (default Europe/Moscow)
# and provides helpers for converting UTC datetimes to the configured timezone.
# @RELATION CALLED_BY -> [ConfigManager]
# @RELATION DEPENDS_ON -> [GlobalSettings.app_timezone]
# @RELATION DEPENDS_ON -> [EXT:method:GlobalSettings.app_timezone]
# @RATIONALE Centralised timezone resolution avoids scattering ZoneInfo() calls across the codebase.
# All API responses should emit localised timestamps; internal storage remains UTC.
# @REJECTED Storing non-UTC in the database rejected — UTC is the canonical best practice for
@@ -14,8 +14,8 @@ from zoneinfo import ZoneInfo
# #region _get_default_tz_name [C:1] [TYPE Function]
# @BRIEF Read APP_TIMEZONE from env, fall back to Europe/Moscow.
# @PRE: Environment is loaded (dotenv or os.environ).
# @POST: Returns a valid IANA timezone string.
# @PRE Environment is loaded (dotenv or os.environ).
# @POST Returns a valid IANA timezone string.
def _get_default_tz_name() -> str:
return os.getenv("APP_TIMEZONE", "Europe/Moscow")
# #endregion _get_default_tz_name
@@ -23,8 +23,8 @@ def _get_default_tz_name() -> str:
# #region get_app_timezone [C:1] [TYPE Function]
# @BRIEF Return cached ZoneInfo for the configured application timezone.
# @SIDE_EFFECT: Reads os.environ on first call; result is cached.
# @POST: Returns a ZoneInfo instance matching APP_TIMEZONE env var.
# @SIDE_EFFECT Reads os.environ on first call; result is cached.
# @POST Returns a ZoneInfo instance matching APP_TIMEZONE env var.
_APP_TZ_CACHE: ZoneInfo | None = None
def get_app_timezone() -> ZoneInfo:
@@ -37,8 +37,8 @@ def get_app_timezone() -> ZoneInfo:
# #region invalidate_timezone_cache [C:1] [TYPE Function]
# @BRIEF Reset the cached ZoneInfo so the next get_app_timezone() call re-reads from env/DB.
# @POST: _APP_TZ_CACHE is set to None; subsequent get_app_timezone() will re-resolve.
# @RATIONALE: Called after PATCH /settings/consolidated updates app_timezone.
# @POST _APP_TZ_CACHE is set to None; subsequent get_app_timezone() will re-resolve.
# @RATIONALE Called after PATCH /settings/consolidated updates app_timezone.
def invalidate_timezone_cache() -> None:
global _APP_TZ_CACHE
_APP_TZ_CACHE = None
@@ -47,8 +47,8 @@ def invalidate_timezone_cache() -> None:
# #region validate_timezone [C:1] [TYPE Function]
# @BRIEF Validate that a timezone string is a known IANA timezone.
# @PRE: tz_name is a string.
# @POST: Returns True if ZoneInfo accepts the name, False otherwise.
# @PRE tz_name is a string.
# @POST Returns True if ZoneInfo accepts the name, False otherwise.
def validate_timezone(tz_name: str) -> bool:
try:
ZoneInfo(tz_name)
@@ -60,8 +60,8 @@ def validate_timezone(tz_name: str) -> bool:
# #region localize [C:1] [TYPE Function]
# @BRIEF Convert a timezone-aware or naive UTC datetime to the configured app timezone.
# @PRE: If dt is timezone-naive, it is assumed to be UTC.
# @POST: Returns a datetime with the app timezone attached (astimezone).
# @PRE If dt is timezone-naive, it is assumed to be UTC.
# @POST Returns a datetime with the app timezone attached (astimezone).
def localize(dt: datetime | None) -> datetime | None:
if dt is None:
return None
@@ -73,7 +73,7 @@ def localize(dt: datetime | None) -> datetime | None:
# #region now [C:1] [TYPE Function]
# @BRIEF Get current time in the configured application timezone.
# @POST: Returns timezone-aware datetime in the app timezone.
# @POST Returns timezone-aware datetime in the app timezone.
def now() -> datetime:
return datetime.now(get_app_timezone())
# #endregion now
@@ -81,7 +81,7 @@ def now() -> datetime:
# #region format_timezone_offset [C:1] [TYPE Function]
# @BRIEF Return the UTC offset string for the configured timezone (e.g. "+03:00").
# @POST: Returns string like "+03:00" or "+00:00".
# @POST Returns string like "+03:00" or "+00:00".
def format_timezone_offset() -> str:
offset = now().strftime("%z")
if offset: