timeplace 0.1.0__tar.gz

timeplace-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.3
+Name: timeplace
+Version: 0.1.0
+Summary: Add your description here
+Author: Ryan Vandersmith
+Author-email: Ryan Vandersmith <ryanvandersmith@gmail.com>
+Requires-Dist: geopy>=2.5.0
+Requires-Dist: timezonefinder>=9.2.0
+Requires-Dist: tzdata>=2026.5
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# timeplace
+
+Parse and format **timeplace** lines: a single line of text naming a time, a place, and a comment.
+
+```
+2025-05-18 5:30pm Arnett, OK # Several tornadoes
+2022-12-02 05z 40.01499,-105.27055 # Downslope windstorm, 50-80mph
+```
+
+See [SPEC.md](../SPEC.md) for the format. Requires Python 3.12+.
+
+## Install
+
+```sh
+uv add timeplace      # or: pip install timeplace
+```
+
+## Parsing
+
+Every part of a line is optional, but the order is always time, place, comment.
+
+```python
+import datetime as dt
+from timeplace import parse
+
+tp = parse("2021-12-30 2pm Boulder, CO # Marshall Fire downslope wind, 100mph")
+tp.time     # datetime(2021, 12, 30, 14, 0, tzinfo=ZoneInfo('America/Denver'))
+tp.place    # Place(lat=40.01..., lon=-105.27..., name='Boulder, CO')
+tp.comment  # '# Marshall Fire downslope wind, 100mph'
+```
+
+Place names are geocoded with Nominatim (OpenStreetMap). Local clock times (`am`/`pm`) use the
+time zone of the place; `z` times are UTC.
+
+```python
+parse("2022-12-02 05z Boulder, CO")            # UTC time
+parse("2018-05-28 5pm 39.62261,-102.97337")    # coordinates: no geocoding needed
+parse("2026-1-2")                              # date only -> tp.time is a datetime.date
+parse("Show Low, AZ")                          # place only
+parse("#rotorcloud")                           # comment only
+parse("2026-01-12 10am Nowhere")               # geocoding failed: tp.place is None, tp.time is a date
+```
+
+`TimePlace.parse(text)` is equivalent to `parse(text)`.
+
+### Fallback time zone
+
+When the place is missing or unresolved, a local clock time cannot be resolved. Supply `tz`:
+
+```python
+from zoneinfo import ZoneInfo
+
+tp = parse("2026-01-12 10am", tz=ZoneInfo("America/Denver"))
+tp.time  # datetime(2026, 1, 12, 10, 0, tzinfo=ZoneInfo('America/Denver'))
+```
+
+### Invalid values
+
+```python
+parse("2026-13-01")          # ValueError: month must be in 1..12
+parse("2026-01-01 13pm 1,1") # ValueError: invalid 12-hour clock hour
+parse("100,0")               # ValueError: latitude out of range
+```
+
+### Strict mode
+
+`strict=True` accepts only `[date clock(z)] lat,lon [comment]`, never geocodes, and raises
+`ValueError` for anything else. Use it for machine-generated data.
+
+```python
+parse("2022-12-02 05z 40.01499,-105.27055 # hi", strict=True)  # OK
+parse("Boulder, CO", strict=True)                              # ValueError
+parse("2022-12-02 5pm 1,1", strict=True)                       # ValueError (not UTC)
+```
+
+## Tags
+
+Tags are `#word` tokens in the comment, lowercased, as a `frozenset`. `# text` (hash then space)
+is the comment delimiter, and URL fragments are ignored.
+
+```python
+tp = parse("2026-10-21 1,1 #Photogenic #supercell https://x.com/a#frag #a-b")
+tp.tags  # frozenset({'photogenic', 'supercell', 'a-b'})
+```
+
+## Formatting
+
+`str(tp)` / `tp.format()` gives the display form: local time, place name.
+`format(canonical=True)` gives the canonical form: UTC time, `lat,lon` rounded to 5 decimals.
+
+```python
+tp = parse("2022-12-02 5am Boulder, CO # Downslope")
+str(tp)                        # '2022-12-02 5am Boulder, CO # Downslope'
+tp.format(canonical=True)      # '2022-12-02 12z 40.01499,-105.27055 # Downslope'
+```
+
+## Building values directly
+
+`TimePlace` is a frozen dataclass; `time` must be timezone-aware (or a `date`).
+
+```python
+import datetime as dt
+from timeplace import Place, TimePlace
+
+tp = TimePlace(
+    time=dt.datetime(2026, 4, 23, 20, tzinfo=dt.UTC),
+    place=Place(36.3956, -97.8784, "Enid, OK"),
+    comment="#tornado #ef4",
+)
+tp.format(canonical=True)             # '2026-04-23 20z 36.3956,-97.8784 #tornado #ef4'
+tp.replace(comment="# updated")       # new TimePlace with a different comment
+Place(36.3956, -97.8784).timezone()   # ZoneInfo('America/Chicago')
+Place(91, 0)                          # ValueError
+```
+
+## Geocoding
+
+The default geocoder is `NominatimGeocoder`: it sends a `timeplace` User-Agent, caches results
+in memory, and limits requests to 1 per second, as the
+[Nominatim usage policy](https://operations.osmfoundation.org/policies/nominatim/) requires.
+Failures return `None`.
+
+Use your own user agent or settings:
+
+```python
+from timeplace import NominatimGeocoder, parse
+
+geocoder = NominatimGeocoder("my-app/1.0 (me@example.com)", min_interval=1.0, timeout=10)
+tp = parse("2025-05-18 5:30pm Arnett, OK", geocoder=geocoder)
+```
+
+A geocoder is any `Callable[[str], Place | None]`, so offline lookups and test doubles are easy:
+
+```python
+from timeplace import Place, parse
+
+known = {"Boulder, CO": Place(40.01499, -105.27055, "Boulder, CO")}
+tp = parse("2021-12-30 2pm Boulder, CO", geocoder=known.get)
+```
+
+## Development
+
+```sh
+uv sync
+uv run pytest          # offline: Nominatim is mocked
+uv run pytest --live   # also run tests against the real Nominatim service
+uv run ruff check
+uv run mypy src tests
+```
+
+Live tests are marked `live` and skipped by default. In CI they run only via manual
+"Run workflow" with the `live` input enabled.
+

timeplace-0.1.0/README.md

@@ -0,0 +1,153 @@
+# timeplace
+
+Parse and format **timeplace** lines: a single line of text naming a time, a place, and a comment.
+
+```
+2025-05-18 5:30pm Arnett, OK # Several tornadoes
+2022-12-02 05z 40.01499,-105.27055 # Downslope windstorm, 50-80mph
+```
+
+See [SPEC.md](../SPEC.md) for the format. Requires Python 3.12+.
+
+## Install
+
+```sh
+uv add timeplace      # or: pip install timeplace
+```
+
+## Parsing
+
+Every part of a line is optional, but the order is always time, place, comment.
+
+```python
+import datetime as dt
+from timeplace import parse
+
+tp = parse("2021-12-30 2pm Boulder, CO # Marshall Fire downslope wind, 100mph")
+tp.time     # datetime(2021, 12, 30, 14, 0, tzinfo=ZoneInfo('America/Denver'))
+tp.place    # Place(lat=40.01..., lon=-105.27..., name='Boulder, CO')
+tp.comment  # '# Marshall Fire downslope wind, 100mph'
+```
+
+Place names are geocoded with Nominatim (OpenStreetMap). Local clock times (`am`/`pm`) use the
+time zone of the place; `z` times are UTC.
+
+```python
+parse("2022-12-02 05z Boulder, CO")            # UTC time
+parse("2018-05-28 5pm 39.62261,-102.97337")    # coordinates: no geocoding needed
+parse("2026-1-2")                              # date only -> tp.time is a datetime.date
+parse("Show Low, AZ")                          # place only
+parse("#rotorcloud")                           # comment only
+parse("2026-01-12 10am Nowhere")               # geocoding failed: tp.place is None, tp.time is a date
+```
+
+`TimePlace.parse(text)` is equivalent to `parse(text)`.
+
+### Fallback time zone
+
+When the place is missing or unresolved, a local clock time cannot be resolved. Supply `tz`:
+
+```python
+from zoneinfo import ZoneInfo
+
+tp = parse("2026-01-12 10am", tz=ZoneInfo("America/Denver"))
+tp.time  # datetime(2026, 1, 12, 10, 0, tzinfo=ZoneInfo('America/Denver'))
+```
+
+### Invalid values
+
+```python
+parse("2026-13-01")          # ValueError: month must be in 1..12
+parse("2026-01-01 13pm 1,1") # ValueError: invalid 12-hour clock hour
+parse("100,0")               # ValueError: latitude out of range
+```
+
+### Strict mode
+
+`strict=True` accepts only `[date clock(z)] lat,lon [comment]`, never geocodes, and raises
+`ValueError` for anything else. Use it for machine-generated data.
+
+```python
+parse("2022-12-02 05z 40.01499,-105.27055 # hi", strict=True)  # OK
+parse("Boulder, CO", strict=True)                              # ValueError
+parse("2022-12-02 5pm 1,1", strict=True)                       # ValueError (not UTC)
+```
+
+## Tags
+
+Tags are `#word` tokens in the comment, lowercased, as a `frozenset`. `# text` (hash then space)
+is the comment delimiter, and URL fragments are ignored.
+
+```python
+tp = parse("2026-10-21 1,1 #Photogenic #supercell https://x.com/a#frag #a-b")
+tp.tags  # frozenset({'photogenic', 'supercell', 'a-b'})
+```
+
+## Formatting
+
+`str(tp)` / `tp.format()` gives the display form: local time, place name.
+`format(canonical=True)` gives the canonical form: UTC time, `lat,lon` rounded to 5 decimals.
+
+```python
+tp = parse("2022-12-02 5am Boulder, CO # Downslope")
+str(tp)                        # '2022-12-02 5am Boulder, CO # Downslope'
+tp.format(canonical=True)      # '2022-12-02 12z 40.01499,-105.27055 # Downslope'
+```
+
+## Building values directly
+
+`TimePlace` is a frozen dataclass; `time` must be timezone-aware (or a `date`).
+
+```python
+import datetime as dt
+from timeplace import Place, TimePlace
+
+tp = TimePlace(
+    time=dt.datetime(2026, 4, 23, 20, tzinfo=dt.UTC),
+    place=Place(36.3956, -97.8784, "Enid, OK"),
+    comment="#tornado #ef4",
+)
+tp.format(canonical=True)             # '2026-04-23 20z 36.3956,-97.8784 #tornado #ef4'
+tp.replace(comment="# updated")       # new TimePlace with a different comment
+Place(36.3956, -97.8784).timezone()   # ZoneInfo('America/Chicago')
+Place(91, 0)                          # ValueError
+```
+
+## Geocoding
+
+The default geocoder is `NominatimGeocoder`: it sends a `timeplace` User-Agent, caches results
+in memory, and limits requests to 1 per second, as the
+[Nominatim usage policy](https://operations.osmfoundation.org/policies/nominatim/) requires.
+Failures return `None`.
+
+Use your own user agent or settings:
+
+```python
+from timeplace import NominatimGeocoder, parse
+
+geocoder = NominatimGeocoder("my-app/1.0 (me@example.com)", min_interval=1.0, timeout=10)
+tp = parse("2025-05-18 5:30pm Arnett, OK", geocoder=geocoder)
+```
+
+A geocoder is any `Callable[[str], Place | None]`, so offline lookups and test doubles are easy:
+
+```python
+from timeplace import Place, parse
+
+known = {"Boulder, CO": Place(40.01499, -105.27055, "Boulder, CO")}
+tp = parse("2021-12-30 2pm Boulder, CO", geocoder=known.get)
+```
+
+## Development
+
+```sh
+uv sync
+uv run pytest          # offline: Nominatim is mocked
+uv run pytest --live   # also run tests against the real Nominatim service
+uv run ruff check
+uv run mypy src tests
+```
+
+Live tests are marked `live` and skipped by default. In CI they run only via manual
+"Run workflow" with the `live` input enabled.
+

timeplace-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "timeplace"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "geopy>=2.5.0",
+    "timezonefinder>=9.2.0",
+    "tzdata>=2026.5",
+]
+
+[[project.authors]]
+name = "Ryan Vandersmith"
+email = "ryanvandersmith@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.0",
+    "pdoc>=15.0.0",
+    "pytest>=9.1.1",
+    "ruff>=0.17.2",
+]
+
+[tool.mypy]
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["geopy.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+]

timeplace-0.1.0/pyproject.toml.orig

@@ -0,0 +1,42 @@
+[project]
+name = "timeplace"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Ryan Vandersmith", email = "ryanvandersmith@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "geopy>=2.5.0",
+    "timezonefinder>=9.2.0",
+    "tzdata>=2026.5",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.0",
+    "pdoc>=15.0.0",
+    "pytest>=9.1.1",
+    "ruff>=0.17.2",
+]
+
+[tool.mypy]
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["geopy.*"]
+ignore_missing_imports = true
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

timeplace-0.1.0/src/timeplace/__init__.py

@@ -0,0 +1,13 @@
+"""Parse and format timeplace lines: a moment, a place, and a comment."""
+
+from .core import TimePlace, format_timeplace, parse
+from .geo import Geocoder, NominatimGeocoder, Place
+
+__all__ = [
+    "Geocoder",
+    "NominatimGeocoder",
+    "Place",
+    "TimePlace",
+    "format_timeplace",
+    "parse",
+]

timeplace-0.1.0/src/timeplace/core.py

@@ -0,0 +1,161 @@
+"""Parsing and formatting of timeplace lines."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from dataclasses import dataclass, replace
+
+from .geo import Geocoder, NominatimGeocoder, Place
+
+_LINE_RE = re.compile(
+    r"""
+    \s*
+    (?:
+        (?P<year>\d{4})-(?P<month>\d{1,2})-(?P<day>\d{1,2})
+        (?:[ ](?P<hour>\d{1,2})(?::(?P<minute>\d{2}))?(?P<zone>z|am|pm|[ ]am|[ ]pm)(?![a-z]))?
+    )?
+    \s*
+    (?P<place>[^#]*)
+    (?P<comment>\#.*)?
+    """,
+    re.IGNORECASE | re.VERBOSE | re.DOTALL,
+)
+_NUM = r"[+-]?(?:\d+(?:\.\d*)?|\.\d+)"
+_COORDS_RE = re.compile(rf"({_NUM})\s*,\s*({_NUM})")
+_TAG_RE = re.compile(r"(?:^|(?<=\s))#(\w[\w\-]*)")
+
+_default_geocoder: Geocoder | None = None
+
+
+def _get_default_geocoder() -> Geocoder:
+    global _default_geocoder
+    if _default_geocoder is None:
+        _default_geocoder = NominatimGeocoder()
+    return _default_geocoder
+
+
+@dataclass(frozen=True, slots=True)
+class TimePlace:
+    """A moment, a place, and a comment; every part is optional.
+
+    `time` is a timezone-aware `datetime`, a plain `date` (no clock time, or an
+    unresolvable local time), or `None`.
+    """
+
+    time: dt.datetime | dt.date | None = None
+    place: Place | None = None
+    comment: str | None = None
+
+    def __post_init__(self) -> None:
+        if isinstance(self.time, dt.datetime) and self.time.tzinfo is None:
+            raise ValueError("time must be timezone-aware")
+
+    @property
+    def tags(self) -> frozenset[str]:
+        return frozenset(t.lower() for t in _TAG_RE.findall(self.comment or ""))
+
+    def replace(self, **changes: object) -> TimePlace:
+        return replace(self, **changes)  # type: ignore[arg-type]
+
+    @staticmethod
+    def parse(
+        text: str,
+        *,
+        geocoder: Geocoder | None = None,
+        tz: dt.tzinfo | None = None,
+        strict: bool = False,
+    ) -> TimePlace:
+        return parse(text, geocoder=geocoder, tz=tz, strict=strict)
+
+    def format(self, *, canonical: bool = False) -> str:
+        return format_timeplace(self, canonical=canonical)
+
+    def __str__(self) -> str:
+        return self.format()
+
+
+def parse(
+    text: str,
+    *,
+    geocoder: Geocoder | None = None,
+    tz: dt.tzinfo | None = None,
+    strict: bool = False,
+) -> TimePlace:
+    """Parse a timeplace line.
+
+    Names are geocoded with `geocoder` (Nominatim by default); failures leave the
+    place unresolved. Local clock times use the place's time zone, else `tz`.
+    With `strict=True`, no geocoding happens and `ValueError` is raised for
+    anything outside the strict subset.
+    """
+    m = _LINE_RE.fullmatch(text.strip("\r\n"))
+    assert m is not None  # every group is optional and the tail matches anything
+    place_text = m["place"].strip()
+    comment = m["comment"]
+
+    place: Place | None = None
+    if place_text:
+        coords = _COORDS_RE.fullmatch(place_text)
+        if coords:
+            place = Place(float(coords[1]), float(coords[2]))
+        elif strict:
+            raise ValueError(f"strict form requires lat,lon place: {place_text!r}")
+        else:
+            place = (geocoder or _get_default_geocoder())(place_text)
+
+    zone = m["zone"].strip().lower() if m["zone"] else None
+    if strict:
+        if place is None:
+            raise ValueError("strict form requires a place")
+        if m["year"] is not None and zone is None:
+            raise ValueError("strict form requires date and clock together")
+        if zone not in (None, "z"):
+            raise ValueError("strict form requires UTC (z) clock time")
+
+    time: dt.datetime | dt.date | None = None
+    if m["year"] is not None:
+        date = dt.date(int(m["year"]), int(m["month"]), int(m["day"]))
+        time = date
+        if m["hour"] is not None:
+            assert zone is not None
+            hour, minute = int(m["hour"]), int(m["minute"] or 0)
+            if minute > 59:
+                raise ValueError(f"invalid minute: {minute}")
+            if zone == "z":
+                if hour > 23:
+                    raise ValueError(f"invalid hour: {hour}")
+                tzinfo: dt.tzinfo | None = dt.UTC
+            else:
+                if not 1 <= hour <= 12:
+                    raise ValueError(f"invalid 12-hour clock hour: {hour}")
+                hour = hour % 12 + (12 if zone == "pm" else 0)
+                tzinfo = (place.timezone() if place else None) or tz
+            if tzinfo is not None:
+                time = dt.datetime.combine(date, dt.time(hour, minute), tzinfo)
+
+    return TimePlace(time, place, comment)
+
+
+def format_timeplace(tp: TimePlace, *, canonical: bool = False) -> str:
+    parts: list[str] = []
+    time = tp.time
+    if isinstance(time, dt.datetime):
+        if canonical:
+            time = time.astimezone(dt.UTC)
+        minutes = f":{time.minute:02d}" if time.minute else ""
+        if time.tzinfo is dt.UTC:
+            clock = f"{time.hour:02d}{minutes}z"
+        else:
+            clock = f"{(time.hour - 1) % 12 + 1}{minutes}{'pm' if time.hour >= 12 else 'am'}"
+        parts.append(f"{time:%Y-%m-%d} {clock}")
+    elif time is not None:
+        parts.append(f"{time:%Y-%m-%d}")
+    if tp.place is not None:
+        if canonical or tp.place.name is None:
+            parts.append(tp.place.coords)
+        else:
+            parts.append(tp.place.name.replace("#", "_"))
+    if tp.comment is not None:
+        parts.append(tp.comment)
+    return " ".join(parts)

timeplace-0.1.0/src/timeplace/geo.py

@@ -0,0 +1,87 @@
+"""Geocoding and time zone lookup."""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import lru_cache
+from zoneinfo import ZoneInfo
+
+from geopy.exc import GeopyError
+from geopy.geocoders import Nominatim
+from timezonefinder import TimezoneFinder
+
+
+@dataclass(frozen=True, slots=True)
+class Place:
+    lat: float
+    lon: float
+    name: str | None = None
+
+    def __post_init__(self) -> None:
+        if not -90 <= self.lat <= 90:
+            raise ValueError(f"latitude out of range: {self.lat}")
+        if not -180 <= self.lon <= 180:
+            raise ValueError(f"longitude out of range: {self.lon}")
+
+    @property
+    def coords(self) -> str:
+        return f"{_fmt_coord(self.lat)},{_fmt_coord(self.lon)}"
+
+    def timezone(self) -> ZoneInfo | None:
+        return find_timezone(self.lat, self.lon)
+
+
+type Geocoder = Callable[[str], Place | None]
+
+
+def _fmt_coord(value: float) -> str:
+    text = f"{value:.5f}".rstrip("0").rstrip(".")
+    return "0" if text in ("-0", "") else text
+
+
+@lru_cache(maxsize=4096)
+def find_timezone(lat: float, lon: float) -> ZoneInfo | None:
+    key = _tz_finder().timezone_at(lat=lat, lng=lon)
+    return ZoneInfo(key) if key else None
+
+
+@lru_cache(maxsize=1)
+def _tz_finder() -> TimezoneFinder:
+    return TimezoneFinder()
+
+
+class NominatimGeocoder:
+    """Nominatim geocoder that identifies itself, caches, and limits to 1 request/s."""
+
+    def __init__(
+        self,
+        user_agent: str = "timeplace",
+        *,
+        min_interval: float = 1.0,
+        timeout: float = 10.0,
+    ) -> None:
+        self._client = Nominatim(user_agent=user_agent, timeout=timeout)
+        self._min_interval = min_interval
+        self._cache: dict[str, Place | None] = {}
+        self._lock = threading.Lock()
+        self._last_request = float("-inf")
+
+    def __call__(self, query: str) -> Place | None:
+        with self._lock:
+            if query in self._cache:
+                return self._cache[query]
+            wait = self._last_request + self._min_interval - time.monotonic()
+            if wait > 0:
+                time.sleep(wait)
+            try:
+                result = self._client.geocode(query)
+            except GeopyError:  # service errors leave the place unresolved
+                return None
+            finally:
+                self._last_request = time.monotonic()
+            place = Place(result.latitude, result.longitude, query) if result else None
+            self._cache[query] = place
+            return place