zip2info 1.0.0__tar.gz

zip2info-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/zip2info
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Publish to PyPI
+        run: uv publish

zip2info-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Source data (not shipped in the package)
+/data/*
+!/data/coordinate_overrides.json
+
+# Internal scripts for data processing
+/scripts/*
+!/scripts/compile_data.py

zip2info-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

zip2info-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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.

zip2info-1.0.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: zip2info
+Version: 1.0.0
+Summary: Fast US ZIP code lookups for timezone and geocoordinates
+Author-email: kylehogate <kyle.holgate@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# zip2info
+
+Fast, zero-dependency US ZIP code lookups for Python.
+
+- **38,000+ zip codes** mapped to IANA timezones
+- **Geocoordinates** for ZIP centroids (latitude/longitude)
+- **Zero dependencies** — pure Python, works everywhere
+- **O(1) lookup** — instant hash table lookups, no database or file I/O
+- **Type-annotated** — full type hints included
+
+## Installation
+
+```bash
+pip install zip2info
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add zip2info
+```
+
+## Usage
+
+```python
+import zip2info
+
+# Timezone lookup
+tz = zip2info.timezone("90210")
+print(tz)  # America/Los_Angeles
+
+# Coordinate lookup (latitude, longitude)
+coords = zip2info.coordinates("90210")
+print(coords)  # (34.0901, -118.4065)
+
+# Rich metadata
+record = zip2info.info("10001")
+print(record.timezone)   # America/New_York
+print(record.latitude)   # 40.7484
+print(record.longitude)  # -73.9967
+
+# Works with integers too
+tz = zip2info.timezone(60601)
+print(tz)  # America/Chicago
+
+# Returns None if zip code not found
+tz = zip2info.timezone("00000")
+print(tz)  # None
+```
+
+## API
+
+### `timezone(zipcode: str | int) -> str | None`
+
+Returns the IANA timezone string for a US ZIP code.
+
+### `coordinates(zipcode: str | int) -> tuple[float, float] | None`
+
+Returns `(latitude, longitude)` for a US ZIP code, or `None` if unavailable.
+
+### `info(zipcode: str | int) -> ZipInfo | None`
+
+Returns a `ZipInfo` dataclass with `zipcode`, `timezone`, `latitude`, and `longitude`.
+Returns `None` when timezone or coordinate data is unavailable.
+
+## Data sources
+
+- **Timezones**: bundled US ZIP-to-timezone dataset (same coverage as the original `zip2tz` project)
+- **Coordinates** (merged in priority order):
+  1. [GeoNames](https://www.geonames.org/) US postal codes ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/))
+  2. U.S. Census ZCTA gazetteer centroids (public domain)
+  3. Manual overrides in `data/coordinate_overrides.json`
+  4. 3-digit ZIP prefix centroid fallback for remaining USPS-only ZIPs (PO boxes, unique entity codes, etc.)
+
+Regenerate packaged data with:
+
+```bash
+python scripts/compile_data.py
+```
+
+## Migration from zip2tz
+
+`zip2info` is a new PyPI package and import path. Existing `zip2tz` installs are unchanged.
+
+```python
+# before
+import zip2tz
+zip2tz.timezone("90210")
+
+# after
+import zip2info
+zip2info.timezone("90210")
+```
+
+## Coverage
+
+Covers all 50 US states plus DC, including Alaska, Hawaii, Indiana county-level boundaries, and other edge cases.
+
+## Data accuracy
+
+Timezone and coordinate mappings are provided on a **best-effort basis**. ZIP codes can span multiple timezones or areas, and coordinate points are centroids/estimates rather than exact address locations.
+
+If you find incorrect data, please open an issue with the ZIP code, expected value, and a source if available.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+Coordinate data includes GeoNames material licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

zip2info-1.0.0/README.md

@@ -0,0 +1,109 @@
+# zip2info
+
+Fast, zero-dependency US ZIP code lookups for Python.
+
+- **38,000+ zip codes** mapped to IANA timezones
+- **Geocoordinates** for ZIP centroids (latitude/longitude)
+- **Zero dependencies** — pure Python, works everywhere
+- **O(1) lookup** — instant hash table lookups, no database or file I/O
+- **Type-annotated** — full type hints included
+
+## Installation
+
+```bash
+pip install zip2info
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add zip2info
+```
+
+## Usage
+
+```python
+import zip2info
+
+# Timezone lookup
+tz = zip2info.timezone("90210")
+print(tz)  # America/Los_Angeles
+
+# Coordinate lookup (latitude, longitude)
+coords = zip2info.coordinates("90210")
+print(coords)  # (34.0901, -118.4065)
+
+# Rich metadata
+record = zip2info.info("10001")
+print(record.timezone)   # America/New_York
+print(record.latitude)   # 40.7484
+print(record.longitude)  # -73.9967
+
+# Works with integers too
+tz = zip2info.timezone(60601)
+print(tz)  # America/Chicago
+
+# Returns None if zip code not found
+tz = zip2info.timezone("00000")
+print(tz)  # None
+```
+
+## API
+
+### `timezone(zipcode: str | int) -> str | None`
+
+Returns the IANA timezone string for a US ZIP code.
+
+### `coordinates(zipcode: str | int) -> tuple[float, float] | None`
+
+Returns `(latitude, longitude)` for a US ZIP code, or `None` if unavailable.
+
+### `info(zipcode: str | int) -> ZipInfo | None`
+
+Returns a `ZipInfo` dataclass with `zipcode`, `timezone`, `latitude`, and `longitude`.
+Returns `None` when timezone or coordinate data is unavailable.
+
+## Data sources
+
+- **Timezones**: bundled US ZIP-to-timezone dataset (same coverage as the original `zip2tz` project)
+- **Coordinates** (merged in priority order):
+  1. [GeoNames](https://www.geonames.org/) US postal codes ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/))
+  2. U.S. Census ZCTA gazetteer centroids (public domain)
+  3. Manual overrides in `data/coordinate_overrides.json`
+  4. 3-digit ZIP prefix centroid fallback for remaining USPS-only ZIPs (PO boxes, unique entity codes, etc.)
+
+Regenerate packaged data with:
+
+```bash
+python scripts/compile_data.py
+```
+
+## Migration from zip2tz
+
+`zip2info` is a new PyPI package and import path. Existing `zip2tz` installs are unchanged.
+
+```python
+# before
+import zip2tz
+zip2tz.timezone("90210")
+
+# after
+import zip2info
+zip2info.timezone("90210")
+```
+
+## Coverage
+
+Covers all 50 US states plus DC, including Alaska, Hawaii, Indiana county-level boundaries, and other edge cases.
+
+## Data accuracy
+
+Timezone and coordinate mappings are provided on a **best-effort basis**. ZIP codes can span multiple timezones or areas, and coordinate points are centroids/estimates rather than exact address locations.
+
+If you find incorrect data, please open an issue with the ZIP code, expected value, and a source if available.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+Coordinate data includes GeoNames material licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

zip2info-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "zip2info"
+version = "1.0.0"
+description = "Fast US ZIP code lookups for timezone and geocoordinates"
+readme = "README.md"
+authors = [
+    { name = "kylehogate", email = "kyle.holgate@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "scripts/**",
+    "data/**",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+]

zip2info-1.0.0/src/zip2info/__init__.py

@@ -0,0 +1,95 @@
+from dataclasses import dataclass
+from typing import Optional
+
+from zip2info._data import TIMEZONES, ZIP_INFO
+
+
+@dataclass(frozen=True, slots=True)
+class ZipInfo:
+    """Metadata for a US ZIP code."""
+
+    zipcode: int
+    timezone: str
+    latitude: float
+    longitude: float
+
+
+def _normalize_zipcode(zipcode: str | int) -> Optional[int]:
+    try:
+        return int(zipcode)
+    except (ValueError, TypeError):
+        return None
+
+
+def timezone(zipcode: str | int) -> Optional[str]:
+    """
+    Return the IANA timezone for a US ZIP code.
+
+    Args:
+        zipcode: ZIP code as a string or integer.
+
+    Returns:
+        Timezone string (for example, ``America/New_York``) or ``None``.
+    """
+    zip_int = _normalize_zipcode(zipcode)
+    if zip_int is None:
+        return None
+
+    record = ZIP_INFO.get(zip_int)
+    if record is None:
+        return None
+    tz_idx, _, _ = record
+    return TIMEZONES[tz_idx]
+
+
+def coordinates(zipcode: str | int) -> Optional[tuple[float, float]]:
+    """
+    Return centroid latitude and longitude for a US ZIP code.
+
+    Coordinates come from the generated ZIP metadata dataset.
+
+    Args:
+        zipcode: ZIP code as a string or integer.
+
+    Returns:
+        ``(latitude, longitude)`` or ``None``.
+    """
+    zip_int = _normalize_zipcode(zipcode)
+    if zip_int is None:
+        return None
+
+    record = ZIP_INFO.get(zip_int)
+    if record is None:
+        return None
+    _, latitude, longitude = record
+    return latitude, longitude
+
+
+def info(zipcode: str | int) -> Optional[ZipInfo]:
+    """
+    Return timezone and coordinate metadata for a US ZIP code.
+
+    Args:
+        zipcode: ZIP code as a string or integer.
+
+    Returns:
+        ``ZipInfo`` when timezone data exists, otherwise ``None``.
+    """
+    zip_int = _normalize_zipcode(zipcode)
+    if zip_int is None:
+        return None
+
+    record = ZIP_INFO.get(zip_int)
+    if record is None:
+        return None
+
+    tz_idx, latitude, longitude = record
+    return ZipInfo(
+        zipcode=zip_int,
+        timezone=TIMEZONES[tz_idx],
+        latitude=latitude,
+        longitude=longitude,
+    )
+
+
+__all__ = ["ZipInfo", "coordinates", "info", "timezone"]