Skip to main content

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)

Source distribution for timeplace 0.1.0
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)

Table of built distributions (wheels) for timeplace 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page