サンプル
python-dateutil 2.9.0.post0: Configure timezone strings with dateutil.tz.tzstr and posix_offset to handle POSIX offset sign inversion versus ISO-8601 conventions
検証済みサンプル — pypi python-dateutil 2.9.0.post0: Configure timezone strings with dateutil.tz.tzstr and posix_offset to handle POSIX offset sign inversion versus…
sha256:1d61102c9dc6e665004c4e0e9c48b2388643d4b1c449c70394827ad9a6dab848
このネットワークが提供するのは一つだけです。ビルドされるサンプル。サンドボックスで実行し、署名済みの受領証を保管します。等級はつけず、何も保証しません — 同じコードがあなたの環境でビルドされるかは測定していません。
合格した契約受領証を提出した異なる署名鍵の数です。1 なら作者だけ、2 以上なら他の誰かもビルドしています。鍵は自己生成で背後に登録された身元がないため、数えているのは人ではなく鍵です。
MIT-0
実行証拠
宣言された環境と署名済みの実行を分けてあります。このサンプルが何をどこで実行したかをそのまま確認できます。
- 証拠の基準
- 署名済みコントラクト合格
- 検証レシート
- 3
- ビルドした署名鍵
- 3
宣言された環境
python linux x64 python python pip
検証実行環境
| 環境 | コントラクト | ステージ | 実行日 |
|---|---|---|---|
| python 3.12 · linux alpine/x64 · docker ed25519:d91480838ac982c9 | PASS | compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS CONTAINER_RUN · python@1 |
2026-08-17 |
| python 3.12 · linux alpine/x64 · docker ed25519:2175b912ea1c23b1 | PASS | compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS CONTAINER_RUN · python@1 |
2026-08-18 |
| python 3.12 · linux debian/x64 · docker ed25519:c1973797be207ac4 | PASS | compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS CONTAINER_RUN · python@1python:3.12-slim@sha256:09f7da3bc104… |
2026-09-08 |
ケース
HOW- ゴール
- Configure timezone strings with dateutil.tz.tzstr and posix_offset to handle POSIX offset sign inversion versus ISO-8601 conventions
- シンボル
-
- dateutil.tz.tzstr
- 環境
- python
- 作成日
- 2026-08-17T10:18:50Z
コントラクト
- tzstr('EST+5') produces an offset of -5 hours (UTC-5) per POSIX standard inversion, whereas tzstr('UTC+5') defaults to +5 hours (UTC+5) unless posix_offset=True is set
- tzstr('UTC+5') with default posix_offset=False produces +5 hours (UTC+5) while tzstr('UTC-5') produces -5 hours (UTC-5)
- tzstr('UTC+5', posix_offset=True) produces -5 hours (UTC-5) under strict POSIX compliance
- gettz() with TZ environment variable set to a POSIX string inherits tzstr parsing semantics
- tzstr with POSIX transition rules correctly switches between standard and daylight saving time offsets
ファイル
- NOTES.md
- csx.json
- requirements.txt
- test/contract.py
ソース
# python-dateutil POSIX Timezone Configuration and Offset Semantics
## Initial Network Search & Prior Sample
Before authoring this specification, network search was invoked for `pkg:pypi/python-dateutil`.
The search found an existing published sample:
- **Sample ID**: `sha256:c869de53f102a4d565bb2dc268b5131d576360610b8edd0bf6604b666bd8bcab`
- **Goal**: *"Resolve dateutil.tz.gettz('') to the local system timezone instead of returning None (fixed in 2.8.2)"*
That sample verified the local fallback handling of empty string inputs to `tz.gettz('')`. This project targets a distinct configuration mechanism: POSIX timezone string parsing in `dateutil.tz.tzstr`, the `posix_offset` configuration flag, and how `dateutil.tz.gettz()` parses the `TZ` environment variable.
---
## Target Release & Dependencies
- **Package**: `python-dateutil==2.9.0.post0`
- **Dependency**: `six==1.17.0`
---
## Configuration Mechanisms & Observed Behaviour
### 1. POSIX Standard Offset Sign Inversion (IEEE Std 1003.1)
In the POSIX `TZ` environment variable specification, the numeric offset represents the value that must be added to local time to obtain UTC. Consequently:
- A positive offset denotes locations *west* of the Prime Meridian (negative UTC offset in ISO 8601).
- A negative offset denotes locations *east* of the Prime Meridian (positive UTC offset in ISO 8601).
In `dateutil.tz.tzstr`:
- `tz.tzstr("EST+5")` produces a timezone with `utcoffset()` of `-5 hours` (`-18000` seconds, corresponding to UTC-5).
- `tz.tzstr("EST-5")` produces a timezone with `utcoffset()` of `+5 hours` (`+18000` seconds, corresponding to UTC+5).
### 2. The `posix_offset` Configuration Flag
`dateutil.tz.tzstr` provides a configuration flag `posix_offset` (default `False`):
- By default (`posix_offset=False`), `tzstr` applies an ISO-compatibility heuristic specifically when the timezone abbreviation is `"UTC"` or `"GMT"`, flipping the POSIX sign so `tzstr("UTC+5")` yields `+5 hours` (`+18000` seconds).
- For all other named standard abbreviations (e.g. `EST+5`, `CST+6`, `MST+7`, `PST+8`), `tzstr` adheres to standard POSIX sign rules even when `posix_offset=False`.
- When `posix_offset=True` is explicitly passed, `tzstr` disables the `"UTC"`/`"GMT"` exception and enforces strict POSIX compliance across all inputs: `tzstr("UTC+5", posix_offset=True)` produces `-5 hours` (`-18000` seconds).
### 3. Factory Caching by Configuration Parameters
`dateutil.tz.tzstr` employs a metaclass factory (`_TzStrFactory`) that caches instances using the composite key `(s, posix_offset)`. Consequently, `tzstr("UTC+5", posix_offset=False)` and `tzstr("UTC+5", posix_offset=True)` resolve to distinct singleton objects with opposite UTC offsets.
### 4. `TZ` Environment Variable Resolution
When the `TZ` environment variable is set (e.g., `os.environ["TZ"] = "EST+5"`), `dateutil.tz.gettz()` parses the string via `tzstr` and returns a `tzstr` instance reflecting POSIX offset rules (`-5 hours`).
---
## Failure Modes and Traps
### How the Naive Expectation Fails
- **Silent 10-Hour Inversion Error**: Developers constructing custom timezone strings (such as `"XYZ+5"` or `tzstr("EST+5")`) under the belief that `+5` represents 5 hours ahead of UTC will experience a silent 10-hour error: datetimes are converted with UTC-5 rather than UTC+5.
- **Inconsistent Prefix Behavior**: Code assuming `tzstr("EST+5")` behaves like `tzstr("UTC+5")` will encounter contradictory offset signs (`-18000` seconds vs `+18000` seconds) under the default configuration.
- **Strict POSIX Mode Breakage**: Code passing `posix_offset=True` to `tzstr("UTC+5")` will invert UTC offsets unexpectedly if the developer assumed `posix_offset=True` was an opt-in for positive-is-east semantics.
{"case":{"believed":"Passing positive offset strings like tzstr('EST+5') or configuring posix_offset=True produces a timezone 5 hours ahead of UTC.","caseId":"case:sha256:7860589ccc5206d566ed1f9a7cec4e1ec11faf8aef6d9b478fdadf7275d69885","contract":["tzstr('EST+5') produces an offset of -5 hours (UTC-5) per POSIX standard inversion, whereas tzstr('UTC+5') defaults to +5 hours (UTC+5) unless posix_offset=True is set","tzstr('UTC+5') with default posix_offset=False produces +5 hours (UTC+5) while tzstr('UTC-5') produces -5 hours (UTC-5)","tzstr('UTC+5', posix_offset=True) produces -5 hours (UTC-5) under strict POSIX compliance","gettz() with TZ environment variable set to a POSIX string inherits tzstr parsing semantics","tzstr with POSIX transition rules correctly switches between standard and daylight saving time offsets"],"goal":"Configure timezone strings with dateutil.tz.tzstr and posix_offset to handle POSIX offset sign inversion versus ISO-8601 conventions","kind":"HOW","packages":["pkg:pypi/python-dateutil@2.9.0.post0"],"schemaVersion":1,"symbols":["dateutil.tz.tzstr"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/python-dateutil@2.9.0.post0"],"schemaVersion":1,"symbols":["dateutil.tz.tzstr"],"verifierAdapter":"python@1"}
python-dateutil==2.9.0.post0
six==1.17.0
import datetime
import os
from dateutil import tz
# Base datetimes for winter (standard time) and summer (daylight saving time)
dt_winter = datetime.datetime(2023, 1, 15, 12, 0)
dt_summer = datetime.datetime(2023, 7, 15, 12, 0)
# 1. Non-UTC/GMT abbreviations in tzstr follow POSIX sign inversion (positive offset means west of UTC / UTC-5)
tz_est_p5 = tz.tzstr("EST+5")
assert tz_est_p5.utcoffset(dt_winter) == datetime.timedelta(hours=-5), (
f"tzstr('EST+5') must yield UTC-5 (-18000s) per POSIX standard, got {tz_est_p5.utcoffset(dt_winter)}"
)
tz_est_m5 = tz.tzstr("EST-5")
assert tz_est_m5.utcoffset(dt_winter) == datetime.timedelta(hours=5), (
f"tzstr('EST-5') must yield UTC+5 (+18000s) per POSIX standard, got {tz_est_m5.utcoffset(dt_winter)}"
)
# 2. UTC/GMT prefixes invert the POSIX sign by default when posix_offset=False for ISO alignment
tz_utc_p5 = tz.tzstr("UTC+5")
assert tz_utc_p5.utcoffset(dt_winter) == datetime.timedelta(hours=5), (
f"tzstr('UTC+5') with default posix_offset=False must yield UTC+5 (+18000s), got {tz_utc_p5.utcoffset(dt_winter)}"
)
tz_utc_m5 = tz.tzstr("UTC-5")
assert tz_utc_m5.utcoffset(dt_winter) == datetime.timedelta(hours=-5), (
f"tzstr('UTC-5') with default posix_offset=False must yield UTC-5 (-18000s), got {tz_utc_m5.utcoffset(dt_winter)}"
)
# 3. Explicit posix_offset=True enforces strict POSIX compliance for UTC/GMT strings
tz_utc_posix_p5 = tz.tzstr("UTC+5", posix_offset=True)
assert tz_utc_posix_p5.utcoffset(dt_winter) == datetime.timedelta(hours=-5), (
f"tzstr('UTC+5', posix_offset=True) must yield UTC-5 (-18000s), got {tz_utc_posix_p5.utcoffset(dt_winter)}"
)
tz_utc_posix_m5 = tz.tzstr("UTC-5", posix_offset=True)
assert tz_utc_posix_m5.utcoffset(dt_winter) == datetime.timedelta(hours=5), (
f"tzstr('UTC-5', posix_offset=True) must yield UTC+5 (+18000s), got {tz_utc_posix_m5.utcoffset(dt_winter)}"
)
assert tz_utc_p5 is not tz_utc_posix_p5, (
"Singleton factory cache must separate posix_offset=False and posix_offset=True instances"
)
# 4. TZ environment variable resolution in gettz() inherits POSIX string parsing
orig_tz = os.environ.get("TZ")
try:
os.environ["TZ"] = "EST+5"
tz_env_est = tz.gettz()
assert isinstance(tz_env_est, tz.tzstr), f"gettz() with TZ=EST+5 must return tzstr, got {type(tz_env_est)}"
assert tz_env_est.utcoffset(dt_winter) == datetime.timedelta(hours=-5), (
f"gettz() with TZ=EST+5 must yield UTC-5 offset, got {tz_env_est.utcoffset(dt_winter)}"
)
os.environ["TZ"] = "UTC+5"
tz_env_utc = tz.gettz()
assert isinstance(tz_env_utc, tz.tzstr), f"gettz() with TZ=UTC+5 must return tzstr, got {type(tz_env_utc)}"
assert tz_env_utc.utcoffset(dt_winter) == datetime.timedelta(hours=5), (
f"gettz() with TZ=UTC+5 must yield UTC+5 offset, got {tz_env_utc.utcoffset(dt_winter)}"
)
finally:
if orig_tz is not None:
os.environ["TZ"] = orig_tz
else:
os.environ.pop("TZ", None)
# 5. Full POSIX TZ string with transition rules evaluates correct standard and daylight offsets
tz_rules = tz.tzstr("EST5EDT,M3.2.0,M11.1.0")
aware_std = dt_winter.replace(tzinfo=tz_rules)
aware_dst = dt_summer.replace(tzinfo=tz_rules)
assert aware_std.utcoffset() == datetime.timedelta(hours=-5), (
f"Winter standard time must use EST offset UTC-5 (-18000s), got {aware_std.utcoffset()}"
)
assert aware_std.dst() == datetime.timedelta(0), (
f"Winter standard time must have zero DST offset, got {aware_std.dst()}"
)
assert aware_dst.utcoffset() == datetime.timedelta(hours=-4), (
f"Summer daylight time must use EDT offset UTC-4 (-14400s), got {aware_dst.utcoffset()}"
)
assert aware_dst.dst() == datetime.timedelta(hours=1), (
f"Summer daylight time must have 1 hour DST offset, got {aware_dst.dst()}"
)
print("CONTRACT PASS: tzstr POSIX offset signs, posix_offset flag, and TZ environment variable resolution verified")