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 for the format. Requires Python 3.12+.
Install
uv add timeplace # or: pip install timeplace
Parsing
Every part of a line is optional, but the order is always time, place, comment.
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.
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:
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
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.
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.
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.
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).
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 requires.
Failures return None.
Use your own user agent or settings:
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:
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
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.
Metadata
Release files for timeplace 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| timeplace-0.1.0.tar.gz | 6.0 kB | With provenance | Details for timeplace-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| timeplace-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for timeplace-0.1.0-py3-none-any.whl |
Total release size: 12.9 kB
Release files / timeplace-0.1.0.tar.gz
| Download URL | timeplace-0.1.0.tar.gz |
|---|---|
| Size | 6.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c81612b4d9590ade1f84e5ca2b944e1ac7282449e03e3951acd875488df78b8a
|
|
BLAKE2b-256 checksum How to use checksums |
27ee9b37fe63b6a7fc5ca1c8e13a476626f7831e825479ee8f4109ae4b623cb0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logRelease files / timeplace-0.1.0-py3-none-any.whl
| Download URL | timeplace-0.1.0-py3-none-any.whl |
|---|---|
| Size | 6.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8ac9a2e883f029b5d166a01a6a601f40048d666e9e048654ed77ba6e79a9bdca
|
|
BLAKE2b-256 checksum How to use checksums |
c590bbe0cff2ac56b5b29c9400b840f48b5fcb5146fa58a98cd5d57b283aac03
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logSecurity for timeplace 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for timeplace-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.