Metadata-Version: 2.4
Name: timeweave
Version: 1.9.0
Summary: Timezone detection, conversion, and self-maintaining IANA rule cache.
Author: vxmpingz_
License: MIT
Project-URL: Homepage, https://github.com/vxmpingz/timeweave
Project-URL: Issues, https://github.com/vxmpingz/timeweave/issues
Keywords: timezone,tzdata,zoneinfo,iana,dst,zic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tzdata>=2024.1
Provides-Extra: tzdata
Requires-Dist: tzdata>=2024.1; extra == "tzdata"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# timeweave

Timezone detection, conversion, and a self-maintaining IANA rule cache.
Python 3.9+.

## Install

```bash
pip install timeweave
```

## Layers

| Module | Role |
|---|---|
| `timeweave.tzkit` | Detect, convert, parse, list zones (read path) |
| `timeweave.updater` | Fetch + SHA-256 verify + cache the rules DB |
| `timeweave.compiler` | Fetch + verify + `zic`-compile tz source into a zoneinfo tree |


## Library use

```python
import timeweave

info = timeweave.detect_timezone()
print(info["timezone"], info["utc_offset"], info["dst_active"])

result = timeweave.convert_timezone(
    "2024-03-10 02:30", ["UTC", "Asia/Tokyo"], from_zone="America/New_York"
)
print(result["instant_utc"], result["local_time_kind"])

parsed = timeweave.parse_datetime("Sun, 10 Mar 2024 07:30:00 +0000")
```

## CLI

```bash
tzkit detect --use-ip
tzkit convert '2024-03-10 02:30' --from America/New_York --to UTC --to Asia/Tokyo
tzkit parse 'Sun, 10 Mar 2024 07:30:00 +0000'
tzkit list Europe --transitions --sort offset

tz-update check --json
tz-compile refresh --force
tz-compile status
```

## DST policy

Wall-clock times that fall in a DST gap or fold are classified, never guessed
silently:

* `--ambiguous earliest|latest|raise` — repeated wall times (fold)
* `--nonexistent shift_forward|shift_backward|raise` — skipped wall times (gap)

`raise` exits `6` so CI catches the case.

## Auto-update

`detect_timezone()` and `convert_timezone()` start a non-blocking daemon-thread
update check, at most once per 24h, gated by a marker file. Failures are logged
and swallowed; the caller's result is never affected.

Disable it:

| Variable | Effect |
|---|---|
| `TIMEWEAVE_NO_AUTO_UPDATE=1` | Disable the on-use check only |
| `TIMEWEAVE_OFFLINE=1` | Disable all outbound network from the package |
| `TIMEWEAVE_NO_NETWORK=1` | Same as `OFFLINE` |
| `TIMEWEAVE_AUTO_INTERVAL` | Seconds between checks (default `86400`) |

## Environment

| Variable | Purpose |
|---|---|
| `TIMEWEAVE_SRC_URL` | Source endpoint (compiler) |
| `TIMEWEAVE_CHECKSUM_URL` | Published SHA-256 (default `<url>.sha256`) |
| `TIMEWEAVE_SIGNATURE_URL` + `TIMEWEAVE_GPG_KEYRING` | Authenticity verification |
| `TIMEWEAVE_ZIC_PATH` | Absolute `zic` path (trusted config only) |
| `TIMEWEAVE_CACHE_DIR` | Cache directory |
| `TZDIR` | Compiled zoneinfo tree; prepended to `zoneinfo.TZPATH` on import |
| `SSL_CERT_FILE` / `REQUESTS_CA_BUNDLE` | Custom CA bundle |
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Standard proxy settings |

## Security notes

* **SHA-256 proves integrity, not authenticity.** If the same host serves the
  payload and the checksum, it controls both. Set `TIMEWEAVE_SIGNATURE_URL` and
  `TIMEWEAVE_GPG_KEYRING` against a trusted key for real authenticity.
* **The compiler targets an app-owned directory by default.** Writing into
  `/usr/share/zoneinfo` requires `--system`, needs root, and affects every
  process on the host. Prefer your OS's signed `tzdata` package for the system
  tree; use this module for isolated, air-gapped, or version-pinned caches.
* **Archive members and `Zone`/`Link` names are validated before `zic` runs**,
  and compiler output is re-checked for containment afterwards.
* The `zic` path is a fixed absolute constant, validated executable, and is
  never read from a network response.

## License

MIT
