osm-lts 0.2.0__tar.gz

osm_lts-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Trusted Publishing OIDC exchange
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install -e '.[test]' build
+      - run: pytest
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # No-op when pyproject's version is already on PyPI, so a
+          # routine commit that doesn't bump the version is silently
+          # skipped instead of failing the workflow.
+          skip-existing: true

osm_lts-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e '.[test]'
+      - run: pytest

osm_lts-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+build/
+dist/
+*.egg-info/
+*.egg
+
+.venv/
+venv/
+env/
+
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+.DS_Store
+.vscode/
+.idea/
+uv.lock

osm_lts-0.2.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.2.0 — 2026-05-15
+
+- New `Classifier` class — frozen dataclass exposing the previously-
+  hardcoded defaults (excluded highways, per-highway speed/lane
+  defaults, fallback speed/lane counts, cycleway sub-tag priority)
+  as overridable fields. `classify(tags)` is a convenience wrapper
+  around the default-configured singleton; `Classifier(...)` is the
+  way to model regions whose conventions differ from the US-centric
+  defaults.
+- Instances are callable: `Classifier()(tags)` works alongside
+  `.classify(tags)`.
+- Tests pin every override surface (excluded highways add/drop,
+  speed fallback flipping the LTS 4 threshold, lane-count fallback
+  promoting to LTS 4, cycleway sub-tag priority reordering) plus
+  frozen-instance enforcement and per-instance dict isolation.
+
+## 0.1.0 — 2026-05-15
+
+Initial release. Pure-Python Furth Level of Traffic Stress classifier
+extracted from the Bike Streets routing platform.
+
+- `osm_lts.classify(tags)` — returns `LTS` 1–4 (or `None` for excluded
+  highways) given an OSM tag mapping. Tolerates units in `maxspeed`
+  and `lanes`, walks `cycleway` and per-side variants.
+- `osm-lts classify` CLI for batch JSON / JSONL / array input.
+- Tests pin every Furth rule branch plus edge cases (unit strings,
+  cycleway sub-tags, separation overriding speed, multi-lane bumps).

osm_lts-0.2.0/LICENSE

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

osm_lts-0.2.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: osm-lts
+Version: 0.2.0
+Summary: Classify OpenStreetMap ways by Level of Traffic Stress (LTS) using the Furth methodology.
+Project-URL: Homepage, https://github.com/bikestreets/osm-lts
+Project-URL: Source, https://github.com/bikestreets/osm-lts
+Project-URL: Issues, https://github.com/bikestreets/osm-lts/issues
+Project-URL: Changelog, https://github.com/bikestreets/osm-lts/blob/main/CHANGELOG.md
+Author: Bike Streets
+License-Expression: MIT
+License-File: LICENSE
+Keywords: advocacy,bicycle,cycling,level-of-traffic-stress,lts,openstreetmap,osm,transportation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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 :: Scientific/Engineering :: GIS
+Classifier: Topic :: Sociology
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# osm-lts
+
+[![PyPI version](https://img.shields.io/pypi/v/osm-lts.svg)](https://pypi.org/project/osm-lts/)
+[![Python versions](https://img.shields.io/pypi/pyversions/osm-lts.svg)](https://pypi.org/project/osm-lts/)
+[![CI](https://github.com/bikestreets/osm-lts/actions/workflows/test.yml/badge.svg)](https://github.com/bikestreets/osm-lts/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/pypi/l/osm-lts.svg)](https://github.com/bikestreets/osm-lts/blob/main/LICENSE)
+
+Classify OpenStreetMap ways by **Level of Traffic Stress (LTS)** using the
+[Furth methodology](https://peterfurth.sites.northeastern.edu/level-of-traffic-stress/).
+
+LTS is a 1–4 scale from "kid-comfortable" (1) to "strong-and-fearless only"
+(4). It's the standard advocacy and planning input for "where is the bike
+network actually rideable for a typical adult" — far more honest than miles
+of "bike infrastructure" because it captures whether that infrastructure is
+on a calm street or a six-lane arterial.
+
+## Install
+
+```bash
+pip install osm-lts
+```
+
+Pure Python, no dependencies, Python 3.9+.
+
+## Use
+
+```python
+from osm_lts import classify
+
+classify({"highway": "residential", "maxspeed": "25 mph"})
+# <LTS.MOST_ADULTS: 2>
+
+classify({"highway": "primary"})
+# <LTS.STRONG_AND_FEARLESS: 4>
+
+classify({"highway": "cycleway"})
+# <LTS.KID_COMFORTABLE: 1>
+
+classify({"highway": "footway"})
+# None — outside scope (not relevant to cyclist stress)
+```
+
+The function takes any `Mapping[str, str]` of OSM tags. Numeric tags
+(`maxspeed`, `lanes`) tolerate units (`"25 mph"`, `"50 km/h"`, `"4;3"`) —
+only the leading digits are read. The result is an `IntEnum`, so
+`int(classify(tags))` gives you the bare LTS value for serialization.
+
+### CLI
+
+The package ships with an `osm-lts` command for batch jobs:
+
+```bash
+echo '{"highway": "residential", "maxspeed": "25 mph"}' | osm-lts classify
+# {"tags": {"highway": "residential", "maxspeed": "25 mph"}, "lts": 2}
+
+osm-lts classify --in ways.jsonl --out lts.jsonl
+```
+
+Input is JSON, JSONL, or a single JSON array — auto-detected.
+
+## How it works
+
+The classifier mirrors Furth's published rules:
+
+| Tier  | Description                  | Example triggers                                                |
+| :---: | ---------------------------- | --------------------------------------------------------------- |
+| LTS 1 | Suitable for children        | `highway=cycleway`, `living_street`, `cycleway=track`           |
+| LTS 2 | Most adults will tolerate    | `residential` ≤25 mph, bike lane on a slow street               |
+| LTS 3 | Experienced cyclists only    | `tertiary`, fast residential, bike lane on a faster street      |
+| LTS 4 | Strong-and-fearless only     | `primary` / `trunk`, `>35 mph`, `≥3 lanes` and `>30 mph`        |
+
+The branches evaluate top-to-bottom and short-circuit on the first match.
+Order matters — a `cycleway=track` on a 40 mph arterial returns LTS 1
+because separation wins over speed. Highways outside scope (`motorway`,
+`footway`, `sidewalk`, `steps`, `pedestrian`) return `None`.
+
+When `maxspeed` or `lanes` are missing, highway-typical defaults fill in:
+
+```python
+from osm_lts import (
+    DEFAULT_SPEED_MPH_BY_HIGHWAY,
+    DEFAULT_LANE_COUNT_BY_HIGHWAY,
+    EXCLUDED_HIGHWAYS,
+)
+```
+
+These are public so callers can read them in their own UIs (e.g. "we
+assumed 25 mph because the way was untagged").
+
+### Customizing the rules
+
+Wrap a `Classifier` instance to override any of the defaults. Useful for
+modeling a city or country whose posted-speed conventions or in-scope
+highway set differ from the US-centric defaults the package ships with.
+
+```python
+from osm_lts import Classifier, EXCLUDED_HIGHWAYS
+
+# Stricter unknown-speed default:
+strict = Classifier(speed_mph_fallback=20)
+strict({"highway": "residential"})  # <LTS.MOST_ADULTS: 2>
+
+# Drop pedestrian-priority paths out of scope entirely:
+narrower = Classifier(excluded_highways=EXCLUDED_HIGHWAYS | {"path"})
+narrower({"highway": "path", "bicycle": "designated"})  # None
+
+# Per-highway speed overrides:
+slower_residential = Classifier(speed_mph_by_highway={"residential": 20})
+```
+
+`Classifier` is a frozen dataclass — instances are hashable and
+thread-safe to share. Use `dataclasses.replace(clf, ...)` for tweaked
+copies.
+
+## Origin
+
+Extracted from the [Bike Streets](https://bikestreets.com/) city-mapping
+platform.
+
+## Development
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

osm_lts-0.2.0/README.md

@@ -0,0 +1,129 @@
+# osm-lts
+
+[![PyPI version](https://img.shields.io/pypi/v/osm-lts.svg)](https://pypi.org/project/osm-lts/)
+[![Python versions](https://img.shields.io/pypi/pyversions/osm-lts.svg)](https://pypi.org/project/osm-lts/)
+[![CI](https://github.com/bikestreets/osm-lts/actions/workflows/test.yml/badge.svg)](https://github.com/bikestreets/osm-lts/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/pypi/l/osm-lts.svg)](https://github.com/bikestreets/osm-lts/blob/main/LICENSE)
+
+Classify OpenStreetMap ways by **Level of Traffic Stress (LTS)** using the
+[Furth methodology](https://peterfurth.sites.northeastern.edu/level-of-traffic-stress/).
+
+LTS is a 1–4 scale from "kid-comfortable" (1) to "strong-and-fearless only"
+(4). It's the standard advocacy and planning input for "where is the bike
+network actually rideable for a typical adult" — far more honest than miles
+of "bike infrastructure" because it captures whether that infrastructure is
+on a calm street or a six-lane arterial.
+
+## Install
+
+```bash
+pip install osm-lts
+```
+
+Pure Python, no dependencies, Python 3.9+.
+
+## Use
+
+```python
+from osm_lts import classify
+
+classify({"highway": "residential", "maxspeed": "25 mph"})
+# <LTS.MOST_ADULTS: 2>
+
+classify({"highway": "primary"})
+# <LTS.STRONG_AND_FEARLESS: 4>
+
+classify({"highway": "cycleway"})
+# <LTS.KID_COMFORTABLE: 1>
+
+classify({"highway": "footway"})
+# None — outside scope (not relevant to cyclist stress)
+```
+
+The function takes any `Mapping[str, str]` of OSM tags. Numeric tags
+(`maxspeed`, `lanes`) tolerate units (`"25 mph"`, `"50 km/h"`, `"4;3"`) —
+only the leading digits are read. The result is an `IntEnum`, so
+`int(classify(tags))` gives you the bare LTS value for serialization.
+
+### CLI
+
+The package ships with an `osm-lts` command for batch jobs:
+
+```bash
+echo '{"highway": "residential", "maxspeed": "25 mph"}' | osm-lts classify
+# {"tags": {"highway": "residential", "maxspeed": "25 mph"}, "lts": 2}
+
+osm-lts classify --in ways.jsonl --out lts.jsonl
+```
+
+Input is JSON, JSONL, or a single JSON array — auto-detected.
+
+## How it works
+
+The classifier mirrors Furth's published rules:
+
+| Tier  | Description                  | Example triggers                                                |
+| :---: | ---------------------------- | --------------------------------------------------------------- |
+| LTS 1 | Suitable for children        | `highway=cycleway`, `living_street`, `cycleway=track`           |
+| LTS 2 | Most adults will tolerate    | `residential` ≤25 mph, bike lane on a slow street               |
+| LTS 3 | Experienced cyclists only    | `tertiary`, fast residential, bike lane on a faster street      |
+| LTS 4 | Strong-and-fearless only     | `primary` / `trunk`, `>35 mph`, `≥3 lanes` and `>30 mph`        |
+
+The branches evaluate top-to-bottom and short-circuit on the first match.
+Order matters — a `cycleway=track` on a 40 mph arterial returns LTS 1
+because separation wins over speed. Highways outside scope (`motorway`,
+`footway`, `sidewalk`, `steps`, `pedestrian`) return `None`.
+
+When `maxspeed` or `lanes` are missing, highway-typical defaults fill in:
+
+```python
+from osm_lts import (
+    DEFAULT_SPEED_MPH_BY_HIGHWAY,
+    DEFAULT_LANE_COUNT_BY_HIGHWAY,
+    EXCLUDED_HIGHWAYS,
+)
+```
+
+These are public so callers can read them in their own UIs (e.g. "we
+assumed 25 mph because the way was untagged").
+
+### Customizing the rules
+
+Wrap a `Classifier` instance to override any of the defaults. Useful for
+modeling a city or country whose posted-speed conventions or in-scope
+highway set differ from the US-centric defaults the package ships with.
+
+```python
+from osm_lts import Classifier, EXCLUDED_HIGHWAYS
+
+# Stricter unknown-speed default:
+strict = Classifier(speed_mph_fallback=20)
+strict({"highway": "residential"})  # <LTS.MOST_ADULTS: 2>
+
+# Drop pedestrian-priority paths out of scope entirely:
+narrower = Classifier(excluded_highways=EXCLUDED_HIGHWAYS | {"path"})
+narrower({"highway": "path", "bicycle": "designated"})  # None
+
+# Per-highway speed overrides:
+slower_residential = Classifier(speed_mph_by_highway={"residential": 20})
+```
+
+`Classifier` is a frozen dataclass — instances are hashable and
+thread-safe to share. Use `dataclasses.replace(clf, ...)` for tweaked
+copies.
+
+## Origin
+
+Extracted from the [Bike Streets](https://bikestreets.com/) city-mapping
+platform.
+
+## Development
+
+```bash
+pip install -e '.[test]'
+pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

osm_lts-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "osm-lts"
+version = "0.2.0"
+description = "Classify OpenStreetMap ways by Level of Traffic Stress (LTS) using the Furth methodology."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Bike Streets" }]
+keywords = [
+  "osm",
+  "openstreetmap",
+  "lts",
+  "level-of-traffic-stress",
+  "cycling",
+  "bicycle",
+  "advocacy",
+  "transportation",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: GIS",
+  "Topic :: Sociology",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+osm-lts = "osm_lts.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/bikestreets/osm-lts"
+Source = "https://github.com/bikestreets/osm-lts"
+Issues = "https://github.com/bikestreets/osm-lts/issues"
+Changelog = "https://github.com/bikestreets/osm-lts/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/osm_lts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+addopts = "-ra --doctest-modules"

osm_lts-0.2.0/src/osm_lts/__init__.py

@@ -0,0 +1,32 @@
+"""osm-lts — classify OpenStreetMap ways by Level of Traffic Stress.
+
+Implements the Furth methodology
+(peterfurth.sites.northeastern.edu/level-of-traffic-stress/) as a pure
+Python function operating on OSM tag dicts. No PostGIS, no Django, no
+network I/O — just OSM tags in, LTS 1-4 (or ``None``) out.
+"""
+
+from ._classify import LTS, Classifier, classify
+from ._constants import (
+    CYCLEWAY_TAG_KEYS,
+    DEFAULT_LANE_COUNT_BY_HIGHWAY,
+    DEFAULT_LANE_COUNT_FALLBACK,
+    DEFAULT_SPEED_MPH_BY_HIGHWAY,
+    DEFAULT_SPEED_MPH_FALLBACK,
+    EXCLUDED_HIGHWAYS,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "LTS",
+    "Classifier",
+    "classify",
+    "EXCLUDED_HIGHWAYS",
+    "DEFAULT_SPEED_MPH_BY_HIGHWAY",
+    "DEFAULT_SPEED_MPH_FALLBACK",
+    "DEFAULT_LANE_COUNT_BY_HIGHWAY",
+    "DEFAULT_LANE_COUNT_FALLBACK",
+    "CYCLEWAY_TAG_KEYS",
+    "__version__",
+]

osm_lts-0.2.0/src/osm_lts/_classify.py

@@ -0,0 +1,255 @@
+"""Furth Level of Traffic Stress classifier.
+
+Reference: peterfurth.sites.northeastern.edu/level-of-traffic-stress/
+
+The classification is a four-tier scale from "kid-comfortable" (1) to
+"strong-and-fearless only" (4). The branches below evaluate top-to-
+bottom; the first match wins. Order matters — separation (a
+``cycleway=track``) short-circuits before any speed/lane bump can
+push the way up to LTS 4.
+
+Two entry points:
+
+* :func:`classify` — module-level function using the default rules.
+  Equivalent to ``Classifier().classify(tags)``.
+* :class:`Classifier` — frozen dataclass with overridable defaults
+  (excluded highways, speed/lane fallbacks, cycleway sub-tag order).
+  Construct one when you need to model a city or country whose
+  posted-speed conventions or in-scope highway set differ from the
+  US-centric defaults.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Mapping, Optional
+
+from . import _constants as C
+
+
+class LTS(IntEnum):
+    """Furth's Level of Traffic Stress, 1 (calmest) to 4 (most hostile)."""
+
+    KID_COMFORTABLE = 1
+    MOST_ADULTS = 2
+    EXPERIENCED_ONLY = 3
+    STRONG_AND_FEARLESS = 4
+
+
+_NON_DIGIT_RE = re.compile(r"[^0-9]")
+_BIKE_LANE_KINDS = frozenset({"lane", "opposite_lane", "shared_lane"})
+_LTS4_HIGHWAYS = frozenset({"primary", "primary_link", "trunk", "trunk_link"})
+_LTS3_HIGHWAYS = frozenset(
+    {
+        "tertiary",
+        "tertiary_link",
+        "secondary",
+        "secondary_link",
+        "residential",
+        "unclassified",
+    }
+)
+
+
+def _coerce_int(value: Optional[str]) -> Optional[int]:
+    """Strip non-digits from an OSM tag value and return ``int``, else ``None``.
+
+    OSM ``maxspeed`` and ``lanes`` are free-form strings: ``"25 mph"``,
+    ``"50 km/h"``, ``"4"``, ``"4;3"``. We only consume the leading
+    digits — anything that doesn't yield digits returns ``None`` and
+    the caller falls back to a highway-typical default.
+    """
+    if value is None:
+        return None
+    digits = _NON_DIGIT_RE.sub("", str(value))
+    return int(digits) if digits else None
+
+
+@dataclass(frozen=True)
+class Classifier:
+    """Configurable Furth LTS classifier.
+
+    All fields default to the public module-level constants, so a
+    bare ``Classifier()`` is equivalent to calling :func:`classify`.
+    Override fields to model a region whose conventions differ from
+    the US-centric defaults: a city with stricter posted-speed
+    fallbacks, a country whose ``footway``-tagged ways are commonly
+    rideable, etc.
+
+    The dataclass is frozen so an instance is hashable and safe to
+    share across threads. To "modify" a classifier, use
+    :meth:`dataclasses.replace`.
+
+    Examples:
+        Default behavior::
+
+            >>> Classifier()({"highway": "residential"})
+            <LTS.MOST_ADULTS: 2>
+
+        Stricter unknown-speed default (treat unknowns as 20 mph)::
+
+            >>> clf = Classifier(speed_mph_fallback=20)
+            >>> clf({"highway": "residential"})
+            <LTS.MOST_ADULTS: 2>
+
+        Also exclude pedestrian-priority paths from scope::
+
+            >>> from osm_lts import EXCLUDED_HIGHWAYS
+            >>> clf = Classifier(
+            ...     excluded_highways=EXCLUDED_HIGHWAYS | {"path"}
+            ... )
+            >>> clf({"highway": "path", "bicycle": "designated"}) is None
+            True
+    """
+
+    # frozenset is itself immutable, so a shared module-level default
+    # is safe — the dataclass machinery doesn't raise on it the way
+    # it would on dict/list/set defaults.
+    excluded_highways: frozenset = C.EXCLUDED_HIGHWAYS
+
+    # ``Mapping`` defaults need a factory: dict is mutable so Python
+    # would otherwise share one dict across every Classifier instance,
+    # which would be both surprising and a source of mutation bugs.
+    speed_mph_by_highway: Mapping[str, int] = field(
+        default_factory=lambda: dict(C.DEFAULT_SPEED_MPH_BY_HIGHWAY)
+    )
+    speed_mph_fallback: int = C.DEFAULT_SPEED_MPH_FALLBACK
+
+    lane_count_by_highway: Mapping[str, int] = field(
+        default_factory=lambda: dict(C.DEFAULT_LANE_COUNT_BY_HIGHWAY)
+    )
+    lane_count_fallback: int = C.DEFAULT_LANE_COUNT_FALLBACK
+
+    # Tuples are immutable; safe as a direct default.
+    cycleway_tag_keys: tuple = C.CYCLEWAY_TAG_KEYS
+
+    def _resolve_speed_mph(self, highway: str, maxspeed: Optional[str]) -> int:
+        explicit = _coerce_int(maxspeed)
+        if explicit is not None:
+            return explicit
+        return self.speed_mph_by_highway.get(highway, self.speed_mph_fallback)
+
+    def _resolve_lane_count(self, highway: str, lanes: Optional[str]) -> int:
+        explicit = _coerce_int(lanes)
+        if explicit is not None:
+            return explicit
+        return self.lane_count_by_highway.get(highway, self.lane_count_fallback)
+
+    def _resolve_cycleway_kind(
+        self, tags: Mapping[str, str]
+    ) -> Optional[str]:
+        """First non-empty cycleway* value, in :attr:`cycleway_tag_keys` order."""
+        for key in self.cycleway_tag_keys:
+            value = tags.get(key)
+            if value:
+                return value
+        return None
+
+    def classify(self, tags: Mapping[str, str]) -> Optional[LTS]:
+        """Return the Furth LTS classification for an OSM way's tags.
+
+        See :func:`classify` for the full docstring; this method is
+        the same logic with this instance's overridable defaults.
+        """
+        highway = tags.get("highway")
+        if not highway or highway in self.excluded_highways:
+            return None
+
+        bicycle = tags.get("bicycle")
+        cycleway_kind = self._resolve_cycleway_kind(tags)
+        speed_mph = self._resolve_speed_mph(highway, tags.get("maxspeed"))
+        lane_count = self._resolve_lane_count(highway, tags.get("lanes"))
+
+        # LTS 1 — separated paths, designated bike infrastructure,
+        # slow-by-design streets. Short-circuits before any speed/
+        # lane bump: a `cycleway=track` on a 40 mph arterial still
+        # returns 1 because the rider is physically separated from
+        # traffic.
+        if highway == "cycleway":
+            return LTS.KID_COMFORTABLE
+        if highway == "path" and bicycle == "designated":
+            return LTS.KID_COMFORTABLE
+        if highway == "living_street":
+            return LTS.KID_COMFORTABLE
+        if cycleway_kind == "track":
+            return LTS.KID_COMFORTABLE
+
+        # LTS 4 — high-speed, multi-lane arterial, or trunk/primary
+        # by tag class. A painted bike lane on a >35 mph 6-lane road
+        # is still LTS 4; paint doesn't reduce stress on a hostile
+        # street.
+        if speed_mph > 35:
+            return LTS.STRONG_AND_FEARLESS
+        if highway in _LTS4_HIGHWAYS:
+            return LTS.STRONG_AND_FEARLESS
+        if lane_count >= 3 and speed_mph > 30:
+            return LTS.STRONG_AND_FEARLESS
+
+        # LTS 2 — calm residential or a bike lane on a slow street.
+        if cycleway_kind in _BIKE_LANE_KINDS and speed_mph <= 25:
+            return LTS.MOST_ADULTS
+        if highway in {"residential", "unclassified"} and speed_mph <= 25:
+            return LTS.MOST_ADULTS
+
+        # LTS 3 — moderate-speed mixed traffic, bike lane on a
+        # faster street, tertiary collectors, or any residential/
+        # unclassified not already absorbed by the LTS 2 branch.
+        if cycleway_kind in _BIKE_LANE_KINDS:
+            return LTS.EXPERIENCED_ONLY
+        if highway in _LTS3_HIGHWAYS:
+            return LTS.EXPERIENCED_ONLY
+
+        # Service ways (alleys, driveways, parking aisles) — assume
+        # low traffic. Real OSM data tags these heavily, so absent
+        # any explicit speed signal we treat them as comfortable.
+        if highway == "service":
+            return LTS.KID_COMFORTABLE
+
+        return LTS.EXPERIENCED_ONLY
+
+    # Calling a classifier directly is the ergonomic API:
+    #     clf = Classifier(...)
+    #     clf(tags)
+    def __call__(self, tags: Mapping[str, str]) -> Optional[LTS]:
+        return self.classify(tags)
+
+
+# Singleton used by the module-level :func:`classify` shortcut. Frozen
+# dataclass + immutable defaults make this safe to share across calls
+# and threads.
+_DEFAULT_CLASSIFIER = Classifier()
+
+
+def classify(tags: Mapping[str, str]) -> Optional[LTS]:
+    """Return the Furth LTS classification for an OSM way's tags.
+
+    Convenience wrapper around a default-configured
+    :class:`Classifier`. For custom defaults or a different in-scope
+    highway set, instantiate a :class:`Classifier` directly.
+
+    Args:
+        tags: Mapping of OSM key to value, e.g. ``{"highway":
+            "residential", "maxspeed": "25 mph"}``. Numeric tag values
+            (``maxspeed``, ``lanes``) tolerate units — only the
+            leading digits are read.
+
+    Returns:
+        :class:`LTS` 1-4, or ``None`` for ways outside scope:
+
+        * No ``highway`` tag.
+        * ``highway`` in :data:`EXCLUDED_HIGHWAYS` (motorways,
+          footways, sidewalks, steps, pedestrian).
+
+    Examples:
+        >>> classify({"highway": "cycleway"})
+        <LTS.KID_COMFORTABLE: 1>
+        >>> classify({"highway": "residential", "maxspeed": "25 mph"})
+        <LTS.MOST_ADULTS: 2>
+        >>> classify({"highway": "primary"})
+        <LTS.STRONG_AND_FEARLESS: 4>
+        >>> classify({"highway": "footway"}) is None
+        True
+    """
+    return _DEFAULT_CLASSIFIER.classify(tags)

osm_lts-0.2.0/src/osm_lts/_constants.py

@@ -0,0 +1,66 @@
+"""Tunable defaults for the LTS classifier.
+
+These mirror the SQL CASE branches in the original Bike Streets
+implementation. Surfaced as module-level constants so callers can
+inspect them and (in a future minor release) override them via a
+``Classifier`` instance.
+"""
+
+from __future__ import annotations
+
+# Highways the classifier returns ``None`` for. Bikes are prohibited
+# (``motorway``), the way isn't relevant to cyclist stress
+# (``footway``, ``sidewalk``, ``steps``), or the way is pedestrian-
+# only by convention.
+EXCLUDED_HIGHWAYS: frozenset[str] = frozenset(
+    {
+        "motorway",
+        "motorway_link",
+        "footway",
+        "sidewalk",
+        "steps",
+        "pedestrian",
+    }
+)
+
+# Speed defaults in mph when the way has no explicit ``maxspeed`` tag.
+# Most US residential streets don't carry a maxspeed; the planning
+# default is the posted limit for the highway class.
+DEFAULT_SPEED_MPH_BY_HIGHWAY: dict[str, int] = {
+    "living_street": 15,
+    "residential": 25,
+    "unclassified": 25,
+    "service": 25,
+    "tertiary": 30,
+    "tertiary_link": 30,
+    "secondary": 35,
+    "secondary_link": 35,
+    "primary": 40,
+    "primary_link": 40,
+    "trunk": 40,
+    "trunk_link": 40,
+}
+DEFAULT_SPEED_MPH_FALLBACK: int = 25
+
+# Lane-count defaults when ``lanes`` is missing.
+DEFAULT_LANE_COUNT_BY_HIGHWAY: dict[str, int] = {
+    "residential": 2,
+    "service": 2,
+    "primary": 4,
+    "primary_link": 4,
+    "secondary": 4,
+    "secondary_link": 4,
+}
+DEFAULT_LANE_COUNT_FALLBACK: int = 2
+
+# OSM cycleway sub-tags consulted in priority order. ``cycleway`` (the
+# unprefixed key) wins when present, then per-side variants. A way
+# tagged with conflicting sides (e.g. lane right, track left) returns
+# the first one set — callers wanting per-direction precision should
+# preprocess the tags themselves.
+CYCLEWAY_TAG_KEYS: tuple[str, ...] = (
+    "cycleway",
+    "cycleway:right",
+    "cycleway:left",
+    "cycleway:both",
+)

osm_lts-0.2.0/src/osm_lts/cli.py

@@ -0,0 +1,100 @@
+"""Command-line interface for ``osm-lts``.
+
+Reads a JSON object, JSON array, or one JSON object per line from
+stdin (or ``--in <file>``) and writes the LTS classification to
+stdout (or ``--out <file>``) as JSONL.
+
+Examples::
+
+    echo '{"highway": "residential", "maxspeed": "25 mph"}' \\
+        | osm-lts classify
+    osm-lts classify --in ways.jsonl --out lts.jsonl
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import IO, Iterable, Iterator
+
+from . import __version__
+from ._classify import classify
+
+
+def _iter_json_objects(stream: IO[str]) -> Iterator[dict]:
+    """Yield one tag dict per JSON object found in ``stream``.
+
+    Accepts either a single JSON value (object or array) or one
+    JSON object per line — whichever the file looks like at first
+    non-whitespace character.
+    """
+    text = stream.read().strip()
+    if not text:
+        return
+    if text.startswith("["):
+        for obj in json.loads(text):
+            yield obj
+    elif text.startswith("{") and "\n{" not in text and "}\n{" not in text:
+        # Single object, no embedded newlines between objects.
+        yield json.loads(text)
+    else:
+        for line in text.splitlines():
+            line = line.strip()
+            if line:
+                yield json.loads(line)
+
+
+def _classify_command(args: argparse.Namespace) -> int:
+    for tags in _iter_json_objects(args.infile):
+        result = classify(tags)
+        out_obj = {"tags": tags, "lts": int(result) if result is not None else None}
+        args.outfile.write(json.dumps(out_obj))
+        args.outfile.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="osm-lts",
+        description="Classify OSM ways by Furth Level of Traffic Stress.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"osm-lts {__version__}"
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    classify_parser = sub.add_parser(
+        "classify",
+        help="Classify one or more OSM tag dicts.",
+        description=(
+            "Read JSON tag dicts from stdin (or --in) and write a "
+            "JSONL stream of {tags, lts} objects to stdout (or --out)."
+        ),
+    )
+    classify_parser.add_argument(
+        "--in",
+        dest="infile",
+        type=argparse.FileType("r"),
+        default=sys.stdin,
+        help="Input file (default: stdin).",
+    )
+    classify_parser.add_argument(
+        "--out",
+        dest="outfile",
+        type=argparse.FileType("w"),
+        default=sys.stdout,
+        help="Output file (default: stdout).",
+    )
+    classify_parser.set_defaults(func=_classify_command)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

osm_lts-0.2.0/tests/test_classifier.py

@@ -0,0 +1,145 @@
+"""Behavior tests for :class:`osm_lts.Classifier` overrides.
+
+The function-level rules are covered in ``test_classify.py``. These
+tests exercise the override surface — confirming each constructor
+field actually changes behavior in the expected direction, and that
+defaulted instances stay in lockstep with the module-level
+:func:`osm_lts.classify` shortcut.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from osm_lts import (
+    EXCLUDED_HIGHWAYS,
+    LTS,
+    Classifier,
+    classify,
+)
+
+
+def test_default_classifier_matches_module_function() -> None:
+    """``Classifier()`` and the module-level ``classify`` agree."""
+    clf = Classifier()
+    for tags in [
+        {"highway": "residential"},
+        {"highway": "primary"},
+        {"highway": "cycleway"},
+        {"highway": "footway"},
+        {"highway": "tertiary", "cycleway:right": "lane"},
+        {},
+    ]:
+        assert clf.classify(tags) == classify(tags)
+
+
+def test_callable_alias_matches_classify() -> None:
+    clf = Classifier()
+    tags = {"highway": "residential", "maxspeed": "25 mph"}
+    assert clf(tags) == clf.classify(tags) == LTS.MOST_ADULTS
+
+
+def test_override_excluded_highways_excludes_more() -> None:
+    """Adding ``path`` to the exclusion set drops it out of scope."""
+    clf = Classifier(excluded_highways=EXCLUDED_HIGHWAYS | {"path"})
+    assert clf({"highway": "path", "bicycle": "designated"}) is None
+    # Other excluded highways still excluded.
+    assert clf({"highway": "footway"}) is None
+    # Non-excluded paths unchanged.
+    assert clf({"highway": "residential"}) == LTS.MOST_ADULTS
+
+
+def test_override_excluded_highways_excludes_fewer() -> None:
+    """Removing ``footway`` from the exclusion set lets it classify."""
+    looser = EXCLUDED_HIGHWAYS - {"footway"}
+    clf = Classifier(excluded_highways=looser)
+    # footway has no LTS-specific rule → falls through to the LTS 3
+    # default. Just confirm it's no longer excluded (returns a value
+    # rather than None).
+    assert clf({"highway": "footway"}) is not None
+
+
+def test_override_speed_mph_fallback() -> None:
+    """A 20 mph fallback pushes unknown highways into the LTS 2 branch."""
+    clf = Classifier(speed_mph_fallback=20)
+    # `highway=byway` isn't in the per-highway speed map → falls back
+    # to ``speed_mph_fallback``. With 20 mph it would fall through to
+    # the catch-all LTS 3 (only LTS 4 cares about 35+, only LTS 2's
+    # residential/lane branches care about ≤25), which is the same as
+    # the default — but a different fallback that crosses the 35 mph
+    # threshold flips the result.
+    high = Classifier(speed_mph_fallback=40)
+    assert high({"highway": "byway"}) == LTS.STRONG_AND_FEARLESS
+    assert clf({"highway": "byway"}) == LTS.EXPERIENCED_ONLY
+
+
+def test_override_speed_mph_by_highway() -> None:
+    """City posts residential at 20 mph by default → still LTS 2 but cleaner."""
+    clf = Classifier(speed_mph_by_highway={"residential": 20})
+    assert clf({"highway": "residential"}) == LTS.MOST_ADULTS
+    # Residential without an override would also be LTS 2 at 25 mph,
+    # so test the cross-threshold case: bump tertiary's default to 25
+    # and a tertiary with no maxspeed turns into LTS 2.
+    clf = Classifier(
+        speed_mph_by_highway={"tertiary": 25},
+        # tertiary needs a bike lane to qualify for LTS 2. (Without
+        # one the LTS 2 branch is residential/unclassified-only.)
+    )
+    assert clf({"highway": "tertiary", "cycleway": "lane"}) == LTS.MOST_ADULTS
+
+
+def test_override_lane_count_fallback_can_promote_to_lts4() -> None:
+    """Bumping the lane-count fallback flips a moderate-speed road to LTS 4."""
+    # `highway=byway` has no per-highway lane default and no per-
+    # highway speed default. With speed override 32 (>30) and lanes
+    # override 4 (≥3), the LTS 4 multi-lane branch should fire.
+    clf = Classifier(speed_mph_fallback=32, lane_count_fallback=4)
+    assert clf({"highway": "byway"}) == LTS.STRONG_AND_FEARLESS
+
+
+def test_override_cycleway_tag_keys_changes_priority() -> None:
+    """Re-ordering the cycleway sub-tag list changes which value wins."""
+    tags = {
+        "highway": "tertiary",
+        "maxspeed": "25 mph",
+        "cycleway:left": "track",
+        "cycleway:right": "lane",
+    }
+    # Default order picks ``cycleway:right`` (priority 2) before
+    # ``cycleway:left`` (priority 3): ``lane`` on a 25 mph street →
+    # LTS 2.
+    assert classify(tags) == LTS.MOST_ADULTS
+
+    # Override prioritizes ``cycleway:left`` first: ``track`` →
+    # short-circuits to LTS 1.
+    clf = Classifier(
+        cycleway_tag_keys=("cycleway", "cycleway:left", "cycleway:right")
+    )
+    assert clf(tags) == LTS.KID_COMFORTABLE
+
+
+def test_classifier_is_frozen() -> None:
+    """Field assignment raises — use ``dataclasses.replace`` instead."""
+    clf = Classifier()
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        clf.speed_mph_fallback = 30  # type: ignore[misc]
+
+
+def test_dataclasses_replace_returns_modified_copy() -> None:
+    """The standard ``replace`` helper produces a tweaked copy."""
+    base = Classifier()
+    stricter = dataclasses.replace(base, speed_mph_fallback=20)
+    assert stricter.speed_mph_fallback == 20
+    assert base.speed_mph_fallback != 20  # original untouched
+
+
+def test_default_classifier_independent_dicts() -> None:
+    """Each ``Classifier()`` gets its own dict — no shared mutation risk."""
+    a = Classifier()
+    b = Classifier()
+    # The dataclass uses default_factory, so ``speed_mph_by_highway``
+    # is a fresh dict per instance — mutating one wouldn't bleed into
+    # the other.
+    assert a.speed_mph_by_highway is not b.speed_mph_by_highway

osm_lts-0.2.0/tests/test_classify.py

@@ -0,0 +1,140 @@
+"""Behavior tests for :func:`osm_lts.classify`.
+
+Each parametrize case asserts a specific Furth-rule outcome with the
+smallest tag bag that exercises it. Edge cases (missing tags, mph
+strings with units, multi-arterial bumps, separation overriding
+speed) are kept as named tests so a regression points right at the
+rule that broke.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from osm_lts import LTS, classify
+
+
+@pytest.mark.parametrize(
+    "tags, expected",
+    [
+        # LTS 1 — separated, designated, slow-by-design
+        ({"highway": "cycleway"}, LTS.KID_COMFORTABLE),
+        ({"highway": "path", "bicycle": "designated"}, LTS.KID_COMFORTABLE),
+        ({"highway": "living_street"}, LTS.KID_COMFORTABLE),
+        (
+            {"highway": "residential", "cycleway": "track"},
+            LTS.KID_COMFORTABLE,
+        ),
+        ({"highway": "service"}, LTS.KID_COMFORTABLE),
+        # LTS 2 — calm residential or bike lane on slow street
+        ({"highway": "residential"}, LTS.MOST_ADULTS),
+        ({"highway": "residential", "maxspeed": "25 mph"}, LTS.MOST_ADULTS),
+        ({"highway": "unclassified", "maxspeed": "20 mph"}, LTS.MOST_ADULTS),
+        (
+            {"highway": "tertiary", "maxspeed": "25 mph", "cycleway": "lane"},
+            LTS.MOST_ADULTS,
+        ),
+        # LTS 3 — collectors / fast residential / bike lane on faster street
+        (
+            {"highway": "residential", "maxspeed": "30 mph"},
+            LTS.EXPERIENCED_ONLY,
+        ),
+        ({"highway": "tertiary"}, LTS.EXPERIENCED_ONLY),
+        (
+            {"highway": "secondary", "maxspeed": "30 mph"},
+            LTS.EXPERIENCED_ONLY,
+        ),
+        (
+            {"highway": "tertiary", "cycleway": "lane"},
+            LTS.EXPERIENCED_ONLY,
+        ),
+        # LTS 4 — high-speed / arterial / multi-lane
+        ({"highway": "primary"}, LTS.STRONG_AND_FEARLESS),
+        ({"highway": "trunk"}, LTS.STRONG_AND_FEARLESS),
+        (
+            {"highway": "secondary", "maxspeed": "40 mph"},
+            LTS.STRONG_AND_FEARLESS,
+        ),
+        (
+            {
+                "highway": "secondary",
+                "lanes": "4",
+                "maxspeed": "35 mph",
+            },
+            LTS.STRONG_AND_FEARLESS,
+        ),
+    ],
+)
+def test_classify(tags: dict, expected: LTS) -> None:
+    assert classify(tags) == expected
+
+
+@pytest.mark.parametrize(
+    "highway",
+    [
+        "motorway",
+        "motorway_link",
+        "footway",
+        "sidewalk",
+        "steps",
+        "pedestrian",
+    ],
+)
+def test_excluded_highways_return_none(highway: str) -> None:
+    assert classify({"highway": highway}) is None
+
+
+def test_no_highway_tag_returns_none() -> None:
+    assert classify({}) is None
+    assert classify({"name": "Anywhere St"}) is None
+
+
+def test_maxspeed_strips_unit_string() -> None:
+    """``maxspeed: '25 mph'`` should be parsed as ``25``, not raise."""
+    assert (
+        classify({"highway": "residential", "maxspeed": "25 mph"})
+        == LTS.MOST_ADULTS
+    )
+
+
+def test_lanes_strips_units_too() -> None:
+    """``lanes`` is rare-but-real with weird values like ``'4;3'``."""
+    assert (
+        classify(
+            {
+                "highway": "secondary",
+                "maxspeed": "35 mph",
+                "lanes": "4;3",
+            }
+        )
+        == LTS.STRONG_AND_FEARLESS
+    )
+
+
+def test_cycleway_subkey_priority() -> None:
+    """``cycleway:right`` is read when the unprefixed ``cycleway`` is absent."""
+    tags = {
+        "highway": "tertiary",
+        "maxspeed": "25 mph",
+        "cycleway:right": "lane",
+    }
+    assert classify(tags) == LTS.MOST_ADULTS
+
+
+def test_protected_track_beats_arterial_speed() -> None:
+    """A ``cycleway=track`` overrides a 40 mph arterial — separation wins."""
+    assert (
+        classify({"highway": "primary", "cycleway": "track"})
+        == LTS.KID_COMFORTABLE
+    )
+
+
+def test_returned_int_is_useable_as_lts_value() -> None:
+    """``LTS`` is an ``IntEnum`` so JSON / CSV serialization is trivial."""
+    result = classify({"highway": "residential"})
+    assert int(result) == 2
+
+
+def test_returns_lts_enum_not_bare_int() -> None:
+    """Caller can pattern-match on the named values."""
+    assert isinstance(classify({"highway": "primary"}), LTS)

osm_lts-0.2.0/tests/test_cli.py

@@ -0,0 +1,42 @@
+"""Smoke tests for the ``osm-lts`` CLI."""
+
+from __future__ import annotations
+
+import io
+import json
+
+from osm_lts.cli import main
+
+
+def _run(stdin_text: str, capsys) -> list[dict]:
+    # argparse.FileType('r') with default=sys.stdin would normally
+    # bind to the real stdin; pytest's capsys swap covers it.
+    import sys
+
+    sys.stdin = io.StringIO(stdin_text)
+    rc = main(["classify"])
+    assert rc == 0
+    out = capsys.readouterr().out
+    return [json.loads(line) for line in out.splitlines() if line.strip()]
+
+
+def test_cli_single_object(capsys) -> None:
+    rows = _run('{"highway": "residential", "maxspeed": "25 mph"}', capsys)
+    assert rows == [
+        {"tags": {"highway": "residential", "maxspeed": "25 mph"}, "lts": 2}
+    ]
+
+
+def test_cli_jsonl_input(capsys) -> None:
+    payload = '{"highway": "primary"}\n{"highway": "footway"}\n'
+    rows = _run(payload, capsys)
+    assert rows == [
+        {"tags": {"highway": "primary"}, "lts": 4},
+        {"tags": {"highway": "footway"}, "lts": None},
+    ]
+
+
+def test_cli_array_input(capsys) -> None:
+    payload = '[{"highway": "cycleway"}, {"highway": "residential"}]'
+    rows = _run(payload, capsys)
+    assert [r["lts"] for r in rows] == [1, 2]