parkingstudy 0.1.0__py3-none-any.whl

parkingstudy/occupancy.py

@@ -0,0 +1,318 @@
+"""Occupancy counts by time beat: occupancy rates, peaks, capacity and space-hours.
+
+Terminology follows common parking-study practice:
+
+* **Occupancy rate** at a beat = vehicles counted / legal spaces available at
+  that beat. Illegally parked vehicles may push it above 1.0; this is kept and
+  flagged rather than clipped.
+* **Effective capacity** = spaces x target occupancy. The default target of
+  85 % is the widely used "85 percent rule" (Shoup, *The High Cost of Free
+  Parking*, APA Planners Press, 2005, ch. 12-13): above it drivers start
+  cruising for a vacant space. The target is a policy choice and configurable.
+* **Practical capacity** (also called "effective supply") = spaces x an
+  efficiency factor per facility type, reflecting the cushion needed for
+  turnover, misparking and search. :data:`DEFAULT_PRACTICAL_FACTORS` holds
+  commonly quoted planning values (0.85 on-street, 0.90 off-street); they are
+  rules of thumb, not a standard, and are fully overridable.
+* **Space-hours** of demand = sum over beats of vehicles x beat length. Supply
+  space-hours = sum over beats of available spaces x beat length.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+from ._time import TimeLike, format_beat, minutes_between, parse_beat
+from .errors import DataError
+from .inventory import Inventory, check_grouping
+
+#: Default target occupancy (Shoup's "85 percent rule").
+DEFAULT_TARGET = 0.85
+
+#: Practical-capacity efficiency factors by facility type. Planning rules of
+#: thumb (not taken from a primary standard): override for your study.
+DEFAULT_PRACTICAL_FACTORS: Mapping[str, float] = {"on_street": 0.85, "off_street": 0.90}
+
+
+@dataclass(frozen=True)
+class Count:
+    """Vehicles counted on one block face at one beat.
+
+    ``space_type`` restricts the count to one inventory line; leave it empty when
+    the whole block face was counted.
+    """
+
+    block_face_id: str
+    beat: _dt.datetime
+    occupied: int
+    space_type: str = ""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "beat", parse_beat(self.beat))
+        if int(self.occupied) != self.occupied or self.occupied < 0:
+            raise DataError(f"{self.block_face_id}: occupied must be a non-negative integer")
+        object.__setattr__(self, "occupied", int(self.occupied))
+
+    @classmethod
+    def make(cls, block_face_id: str, beat: TimeLike, occupied: int, space_type: str = "") -> Count:
+        """Build a count, parsing ``beat`` from a string if needed."""
+        return cls(block_face_id, parse_beat(beat), occupied, space_type)
+
+
+@dataclass(frozen=True)
+class OccupancyRow:
+    """Aggregated occupancy at one beat for one key (block face, zone or total)."""
+
+    key: str
+    beat: _dt.datetime
+    occupied: int
+    capacity: int
+
+    @property
+    def rate(self) -> Optional[float]:
+        """Occupied / capacity, or ``None`` when no space is available."""
+        return self.occupied / self.capacity if self.capacity else None
+
+    @property
+    def over_capacity(self) -> bool:
+        """More vehicles than legal spaces (illegal or double parking)."""
+        return self.occupied > self.capacity
+
+
+def occupancy_by_beat(
+    inventory: Inventory, counts: Iterable[Count], by: str = "block_face"
+) -> List[OccupancyRow]:
+    """Occupancy per beat, aggregated to block faces, zones or the whole study area.
+
+    Capacity of each count is the inventory capacity of the counted block face
+    (or of its ``space_type`` line) *at that beat*, so spaces removed by an
+    ``unavailable`` window do not inflate the denominator. When aggregating,
+    only the block faces actually counted at a beat contribute capacity.
+    Rows are sorted by key then beat.
+    """
+    check_grouping(by)
+    seen = set()
+    occ: Dict[Tuple[str, _dt.datetime], List[int]] = OrderedDict()
+    for c in counts:
+        ident = (c.block_face_id, c.space_type, c.beat)
+        if ident in seen:
+            raise DataError(f"duplicate count for {c.block_face_id!r} at {c.beat}")
+        seen.add(ident)
+        cap = inventory.capacity(
+            block_face_id=c.block_face_id, space_type=c.space_type or None, at=c.beat
+        )
+        key = inventory.key_of(c.block_face_id, by)
+        acc = occ.setdefault((key, c.beat), [0, 0])
+        acc[0] += c.occupied
+        acc[1] += cap
+    rows = [OccupancyRow(k, b, v[0], v[1]) for (k, b), v in occ.items()]
+    rows.sort(key=lambda r: (r.key, r.beat))
+    return rows
+
+
+def peak_occupancy(
+    rows: Iterable[OccupancyRow], basis: str = "vehicles"
+) -> Dict[str, OccupancyRow]:
+    """Peak row per key.
+
+    ``basis="vehicles"`` (default) takes the beat with the most parked vehicles,
+    the peak accumulation used for supply/demand comparison; ``basis="rate"``
+    takes the highest occupancy rate (they differ when capacity varies by time).
+    Ties go to the earliest beat.
+    """
+    if basis not in ("vehicles", "rate"):
+        raise ValueError("basis must be 'vehicles' or 'rate'")
+    best: Dict[str, OccupancyRow] = OrderedDict()
+    for row in sorted(rows, key=lambda r: (r.key, r.beat)):
+        cur = best.get(row.key)
+        if cur is None:
+            best[row.key] = row
+            continue
+        if basis == "vehicles":
+            if row.occupied > cur.occupied:
+                best[row.key] = row
+        else:
+            new = -1.0 if row.rate is None else row.rate
+            old = -1.0 if cur.rate is None else cur.rate
+            if new > old:
+                best[row.key] = row
+    return best
+
+
+def effective_capacity(spaces: float, target: float = DEFAULT_TARGET) -> float:
+    """Spaces that can be occupied while meeting the target occupancy (``spaces * target``)."""
+    if not 0 < target <= 1:
+        raise ValueError("target must be in (0, 1]")
+    if spaces < 0:
+        raise ValueError("spaces must not be negative")
+    return spaces * target
+
+
+def practical_capacity(
+    inventory: Inventory,
+    *,
+    factors: Optional[Mapping[str, float]] = None,
+    block_face_id: Optional[str] = None,
+    zone: Optional[str] = None,
+    at: Optional[_dt.datetime] = None,
+) -> float:
+    """Sum of available spaces x facility efficiency factor.
+
+    ``factors`` maps :attr:`InventoryRecord.facility` to a factor in (0, 1];
+    defaults to :data:`DEFAULT_PRACTICAL_FACTORS`.
+    """
+    table = DEFAULT_PRACTICAL_FACTORS if factors is None else factors
+    total = 0.0
+    for rec in inventory.select(block_face_id=block_face_id, zone=zone):
+        if rec.facility not in table:
+            raise DataError(
+                f"no practical-capacity factor for facility {rec.facility!r}; pass factors="
+            )
+        factor = table[rec.facility]
+        if not 0 < factor <= 1:
+            raise ValueError("practical-capacity factors must be in (0, 1]")
+        total += rec.available_at(at) * factor
+    return total
+
+
+@dataclass(frozen=True)
+class CapacityAssessment:
+    """Peak demand against effective and practical capacity for one key."""
+
+    key: str
+    spaces: int
+    peak_beat: _dt.datetime
+    peak_occupied: int
+    peak_rate: Optional[float]
+    target: float
+    effective_capacity: float
+    practical_capacity: float
+
+    @property
+    def surplus(self) -> float:
+        """Effective capacity minus peak vehicles (negative = deficit)."""
+        return self.effective_capacity - self.peak_occupied
+
+    @property
+    def above_target(self) -> bool:
+        """Peak occupancy exceeds the target occupancy."""
+        return self.peak_occupied > self.effective_capacity + 1e-9
+
+    def as_dict(self) -> Dict[str, object]:
+        """Plain-dict form for CSV / JSON output."""
+        return {
+            "key": self.key,
+            "spaces": self.spaces,
+            "peak_beat": format_beat(self.peak_beat),
+            "peak_occupied": self.peak_occupied,
+            "peak_rate": self.peak_rate,
+            "target": self.target,
+            "effective_capacity": self.effective_capacity,
+            "practical_capacity": self.practical_capacity,
+            "surplus": self.surplus,
+            "above_target": self.above_target,
+        }
+
+
+def capacity_assessment(
+    inventory: Inventory,
+    counts: Iterable[Count],
+    *,
+    by: str = "zone",
+    target: float = DEFAULT_TARGET,
+    factors: Optional[Mapping[str, float]] = None,
+) -> List[CapacityAssessment]:
+    """Compare peak accumulation with effective and practical capacity per key.
+
+    Capacity values refer to the spaces available at the peak beat.
+    """
+    rows = occupancy_by_beat(inventory, counts, by=by)
+    out: List[CapacityAssessment] = []
+    for key, peak in peak_occupancy(rows, basis="vehicles").items():
+        if by == "block_face":
+            prac = practical_capacity(inventory, factors=factors, block_face_id=key, at=peak.beat)
+        elif by == "zone":
+            prac = practical_capacity(inventory, factors=factors, zone=key, at=peak.beat)
+        else:
+            prac = practical_capacity(inventory, factors=factors, at=peak.beat)
+        out.append(
+            CapacityAssessment(
+                key=key,
+                spaces=peak.capacity,
+                peak_beat=peak.beat,
+                peak_occupied=peak.occupied,
+                peak_rate=peak.rate,
+                target=target,
+                effective_capacity=effective_capacity(peak.capacity, target),
+                practical_capacity=prac,
+            )
+        )
+    return out
+
+
+def accumulation_curve(
+    inventory: Inventory, counts: Iterable[Count], by: str = "total"
+) -> Dict[str, List[Tuple[_dt.datetime, int]]]:
+    """Parking accumulation (vehicles parked) through the survey, per key."""
+    curve: Dict[str, List[Tuple[_dt.datetime, int]]] = OrderedDict()
+    for row in occupancy_by_beat(inventory, counts, by=by):
+        curve.setdefault(row.key, []).append((row.beat, row.occupied))
+    return curve
+
+
+def infer_beat_minutes(beats: Iterable[_dt.datetime]) -> float:
+    """Survey beat length: the smallest positive gap between distinct beat times."""
+    times = sorted(set(beats))
+    if len(times) < 2:
+        raise DataError("at least two distinct beats are needed to infer the beat length")
+    return min(minutes_between(a, b) for a, b in zip(times, times[1:]))
+
+
+@dataclass(frozen=True)
+class SpaceHours:
+    """Space-hour demand and supply for one key."""
+
+    key: str
+    demand: float
+    supply: float
+
+    @property
+    def utilization(self) -> Optional[float]:
+        """Demand / supply space-hours (time-averaged occupancy)."""
+        return self.demand / self.supply if self.supply else None
+
+    def as_dict(self) -> Dict[str, object]:
+        """Plain-dict form."""
+        return {
+            "key": self.key,
+            "demand_space_hours": self.demand,
+            "supply_space_hours": self.supply,
+            "utilization": self.utilization,
+        }
+
+
+def space_hours(
+    inventory: Inventory,
+    counts: Sequence[Count],
+    *,
+    by: str = "zone",
+    beat_minutes: Optional[float] = None,
+) -> List[SpaceHours]:
+    """Space-hours of demand and supply, each beat representing ``beat_minutes``.
+
+    ``beat_minutes`` defaults to :func:`infer_beat_minutes` over the counts.
+    """
+    if beat_minutes is None:
+        beat_minutes = infer_beat_minutes(c.beat for c in counts)
+    if beat_minutes <= 0:
+        raise ValueError("beat_minutes must be positive")
+    hours = beat_minutes / 60.0
+    acc: Dict[str, List[float]] = OrderedDict()
+    for row in occupancy_by_beat(inventory, counts, by=by):
+        a = acc.setdefault(row.key, [0.0, 0.0])
+        a[0] += row.occupied * hours
+        a[1] += row.capacity * hours
+    return [SpaceHours(k, v[0], v[1]) for k, v in acc.items()]

parkingstudy/pricing.py

@@ -0,0 +1,217 @@
+"""Demand-responsive pricing recommendations from occupancy bands.
+
+Two ready-made policies are provided; every number is a configurable policy
+parameter, so build your own :class:`PricingPolicy` for local currency, steps,
+thresholds and caps.
+
+:data:`SFMTA_POLICY` (default) follows SFMTA, *Demand-responsive parking pricing
+policies: on-street parking meters and off-street lots* (5 December 2017),
+section "On-street metered parking and metered lots":
+
+* occupancy 80 % or above: hourly rate raised by 0.25;
+* 60 % or above but below 80 %: not changed;
+* below 60 %: lowered by 0.25;
+* minimum rate 0.50 per hour, maximum 8.00 per hour (special events excluded),
+  changes no more often than once per four weeks.
+
+:data:`SFPARK_PILOT_POLICY` reproduces the four-band table commonly reported for
+the 2011-2013 SFpark pilot (80-100 %: +0.25, 60-80 %: hold, 30-60 %: -0.25,
+below 30 %: -0.50, cap 6.00 per hour). It was taken from secondary summaries of
+the SFMTA pilot evaluation, not checked against the primary table, and its
+0.25 floor is an assumption.
+
+Band boundaries are lower-inclusive (80 % falls in the "raise" band), as in the
+SFMTA wording "80 percent or above".
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+from .errors import DataError
+from .occupancy import OccupancyRow
+
+
+@dataclass(frozen=True)
+class PriceBand:
+    """Occupancy band ``[lower, upper)`` and the rate change applied in it."""
+
+    lower: float
+    upper: float
+    change: float
+    label: str = ""
+
+    def contains(self, occupancy: float) -> bool:
+        """Whether ``occupancy`` lies in ``[lower, upper)``."""
+        return self.lower <= occupancy < self.upper
+
+
+@dataclass(frozen=True)
+class PricingPolicy:
+    """Band table plus rate floor, cap and rounding increment.
+
+    Bands must be sorted, contiguous and cover ``[0, inf)``; make the last band
+    open-ended (``upper=math.inf``) so occupancies above 100 % (illegal parking)
+    still match.
+    """
+
+    bands: Tuple[PriceBand, ...]
+    min_rate: float = 0.0
+    max_rate: float = math.inf
+    rounding: float = 0.01
+    name: str = "custom"
+
+    def __post_init__(self) -> None:
+        bands = tuple(sorted(self.bands, key=lambda b: b.lower))
+        if not bands:
+            raise ValueError("a pricing policy needs at least one band")
+        if bands[0].lower > 0:
+            raise ValueError("the first band must start at 0")
+        for a, b in zip(bands, bands[1:]):
+            if not math.isclose(a.upper, b.lower):
+                raise ValueError(f"bands must be contiguous ({a.upper} != {b.lower})")
+        if not math.isinf(bands[-1].upper):
+            raise ValueError("the last band must be open-ended (upper=math.inf)")
+        if self.min_rate < 0 or self.max_rate < self.min_rate:
+            raise ValueError("need 0 <= min_rate <= max_rate")
+        if self.rounding <= 0:
+            raise ValueError("rounding must be positive")
+        object.__setattr__(self, "bands", bands)
+
+    def band_for(self, occupancy: float) -> PriceBand:
+        """Band containing an occupancy rate (0-1 scale)."""
+        if occupancy < 0 or math.isnan(occupancy):
+            raise DataError(f"invalid occupancy {occupancy!r}")
+        for band in self.bands:
+            if band.contains(occupancy):
+                return band
+        raise DataError(f"occupancy {occupancy!r} not covered by any band")  # pragma: no cover
+
+
+#: SFMTA on-street meter policy of 5 December 2017 (verified against the SFMTA PDF).
+SFMTA_POLICY = PricingPolicy(
+    bands=(
+        PriceBand(0.0, 0.60, -0.25, "below 60%: lower"),
+        PriceBand(0.60, 0.80, 0.0, "60-80%: hold"),
+        PriceBand(0.80, math.inf, 0.25, "80% or above: raise"),
+    ),
+    min_rate=0.50,
+    max_rate=8.00,
+    rounding=0.01,
+    name="SFMTA demand-responsive meter pricing (2017)",
+)
+
+#: SFpark pilot four-band table (secondary sources; floor assumed, see module docstring).
+SFPARK_PILOT_POLICY = PricingPolicy(
+    bands=(
+        PriceBand(0.0, 0.30, -0.50, "below 30%: lower 0.50"),
+        PriceBand(0.30, 0.60, -0.25, "30-60%: lower 0.25"),
+        PriceBand(0.60, 0.80, 0.0, "60-80%: hold"),
+        PriceBand(0.80, math.inf, 0.25, "80% or above: raise"),
+    ),
+    min_rate=0.25,  # assumption, not verified
+    max_rate=6.00,
+    rounding=0.01,
+    name="SFpark pilot (2011-2013), as reported",
+)
+
+#: Named policies for the CLI.
+POLICIES: Dict[str, PricingPolicy] = {"sfmta": SFMTA_POLICY, "sfpark-pilot": SFPARK_PILOT_POLICY}
+
+
+@dataclass(frozen=True)
+class PriceRecommendation:
+    """Recommended new hourly rate for one key."""
+
+    key: str
+    occupancy: float
+    current_rate: float
+    new_rate: float
+    band: str
+    clamped: bool = field(default=False)
+
+    @property
+    def change(self) -> float:
+        """``new_rate - current_rate``."""
+        return round(self.new_rate - self.current_rate, 10)
+
+    def as_dict(self) -> Dict[str, object]:
+        """Plain-dict form."""
+        return {
+            "key": self.key,
+            "occupancy": self.occupancy,
+            "current_rate": self.current_rate,
+            "new_rate": self.new_rate,
+            "change": self.change,
+            "band": self.band,
+            "clamped": self.clamped,
+        }
+
+
+def _round_to(value: float, step: float) -> float:
+    return round(round(value / step) * step, 10)
+
+
+def recommend_rate(
+    occupancy: float,
+    current_rate: float,
+    policy: PricingPolicy = SFMTA_POLICY,
+    key: str = "",
+) -> PriceRecommendation:
+    """Apply the band rule to one occupancy rate (0-1 scale) and current hourly rate."""
+    if current_rate < 0:
+        raise DataError("current_rate must not be negative")
+    band = policy.band_for(occupancy)
+    raw = current_rate + band.change
+    clamped_value = min(max(raw, policy.min_rate), policy.max_rate)
+    new_rate = _round_to(clamped_value, policy.rounding)
+    new_rate = min(max(new_rate, policy.min_rate), policy.max_rate)
+    return PriceRecommendation(
+        key=key,
+        occupancy=occupancy,
+        current_rate=current_rate,
+        new_rate=new_rate,
+        band=band.label,
+        clamped=not math.isclose(raw, clamped_value),
+    )
+
+
+def recommend_rates(
+    occupancy: Mapping[str, Optional[float]],
+    rates: Mapping[str, Optional[float]],
+    policy: PricingPolicy = SFMTA_POLICY,
+    default_rate: Optional[float] = None,
+) -> List[PriceRecommendation]:
+    """Recommendations for many keys.
+
+    Keys whose occupancy is ``None`` or whose rate is missing (and no
+    ``default_rate``) are skipped.
+    """
+    out: List[PriceRecommendation] = []
+    for key, occ in occupancy.items():
+        rate = rates.get(key)
+        if rate is None:
+            rate = default_rate
+        if occ is None or rate is None:
+            continue
+        out.append(recommend_rate(occ, rate, policy, key=key))
+    return out
+
+
+def mean_occupancy(
+    rows: Iterable[OccupancyRow], keys: Optional[Sequence[str]] = None
+) -> Dict[str, Optional[float]]:
+    """Pooled occupancy (sum of vehicles / sum of spaces) per key from occupancy rows.
+
+    ``rows`` are :class:`~parkingstudy.occupancy.OccupancyRow` objects, typically
+    pre-filtered to the pricing time band (e.g. weekday 09:00-12:00).
+    """
+    acc: Dict[str, List[int]] = {}
+    for r in rows:
+        a = acc.setdefault(r.key, [0, 0])
+        a[0] += r.occupied
+        a[1] += r.capacity
+    order = list(keys) if keys is not None else list(acc)
+    return {k: (acc[k][0] / acc[k][1] if k in acc and acc[k][1] else None) for k in order}

parkingstudy/privacy.py

@@ -0,0 +1,145 @@
+"""Anonymisation of licence plates.
+
+Licence plates are personal data in most jurisdictions (for example under the
+EU GDPR and the Turkish KVKK, Law No. 6698). Turnover analysis only needs to
+know that two sightings belong to the *same* vehicle, so plates are replaced
+on input by a keyed hash (HMAC-SHA256, RFC 2104) computed with a secret salt.
+
+* The same plate and salt always give the same token, so stays can be linked.
+* Without the salt the token cannot be reversed by brute-forcing the small
+  space of valid plates, which an unsalted hash would allow.
+* Use a fresh salt per survey and destroy it afterwards to make tokens
+  unlinkable across surveys.
+
+Nothing in this package stores or writes raw plates: :class:`~parkingstudy.lpr.Sighting`
+holds only the token, and the CSV readers refuse a raw plate column unless a
+:class:`PlateHasher` is supplied.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import unicodedata
+from pathlib import Path
+from typing import Dict, Iterable, Iterator, Mapping, Optional, Union
+
+from .errors import PrivacyError
+
+#: Environment variable read by :meth:`PlateHasher.from_env`.
+SALT_ENV_VAR = "PARKINGSTUDY_SALT"
+
+#: Minimum salt length in bytes (128 bits).
+MIN_SALT_BYTES = 16
+
+
+def generate_salt(nbytes: int = 32) -> str:
+    """Return a new random salt as a hex string (``nbytes`` of entropy)."""
+    if nbytes < MIN_SALT_BYTES:
+        raise ValueError(f"salt must be at least {MIN_SALT_BYTES} bytes")
+    return secrets.token_hex(nbytes)
+
+
+def normalize_plate(raw: str) -> str:
+    """Canonical form of a plate before hashing.
+
+    Unicode NFKC normalisation, upper-casing and removal of every character that
+    is not a letter or digit, so ``"34 abc-123"`` and ``"34ABC123"`` give the same
+    token. Returns an empty string for blank input.
+    """
+    text = unicodedata.normalize("NFKC", str(raw)).upper()
+    return "".join(ch for ch in text if ch.isalnum())
+
+
+class PlateHasher:
+    """Keyed (salted) hashing of licence plates with HMAC-SHA256.
+
+    Parameters
+    ----------
+    salt:
+        Secret key, ``str`` or ``bytes``, at least 16 bytes long. Generate one
+        with :func:`generate_salt` and keep it out of version control.
+    length:
+        Number of hex characters kept from the digest (8-64, default 16 = 64
+        bits, ample to avoid collisions within one survey).
+    prefix:
+        Text prepended to every token, so tokens are recognisable as such.
+
+    The salt is never shown by ``repr`` or ``str``.
+    """
+
+    def __init__(self, salt: Union[str, bytes], *, length: int = 16, prefix: str = "v_") -> None:
+        key = salt.encode("utf-8") if isinstance(salt, str) else bytes(salt)
+        if len(key) < MIN_SALT_BYTES:
+            raise PrivacyError(
+                f"salt is too short ({len(key)} bytes); use at least {MIN_SALT_BYTES} bytes, "
+                "e.g. parkingstudy.generate_salt()"
+            )
+        if not 8 <= length <= 64:
+            raise ValueError("length must be between 8 and 64 hex characters")
+        self._key = key
+        self.length = length
+        self.prefix = prefix
+
+    @classmethod
+    def from_env(cls, var: str = SALT_ENV_VAR, **kwargs: object) -> PlateHasher:
+        """Build a hasher from the salt stored in an environment variable."""
+        value = os.environ.get(var)
+        if not value:
+            raise PrivacyError(f"environment variable {var} is not set or empty")
+        return cls(value, **kwargs)  # type: ignore[arg-type]
+
+    @classmethod
+    def from_file(cls, path: Union[str, Path], **kwargs: object) -> PlateHasher:
+        """Build a hasher from the first line of a salt file."""
+        value = Path(path).read_text(encoding="utf-8").strip()
+        return cls(value, **kwargs)  # type: ignore[arg-type]
+
+    def hash(self, raw_plate: str) -> str:
+        """Return the anonymous token for a plate."""
+        plate = normalize_plate(raw_plate)
+        if not plate:
+            raise PrivacyError("empty licence plate cannot be hashed")
+        digest = hmac.new(self._key, plate.encode("utf-8"), hashlib.sha256).hexdigest()
+        return self.prefix + digest[: self.length]
+
+    __call__ = hash
+
+    def __repr__(self) -> str:
+        return f"PlateHasher(salt=<hidden>, length={self.length}, prefix={self.prefix!r})"
+
+
+def anonymise_rows(
+    rows: Iterable[Mapping[str, str]],
+    hasher: PlateHasher,
+    *,
+    plate_column: str = "plate",
+    token_column: str = "plate_token",
+) -> Iterator[Dict[str, str]]:
+    """Yield copies of ``rows`` with ``plate_column`` replaced by ``token_column``.
+
+    The raw plate column is dropped from every output row.
+    """
+    for row in rows:
+        if plate_column not in row:
+            raise PrivacyError(f"plate column {plate_column!r} not found")
+        out = {k: v for k, v in row.items() if k != plate_column}
+        out[token_column] = hasher.hash(row[plate_column] or "")
+        yield out
+
+
+def resolve_hasher(
+    salt: Optional[str] = None,
+    salt_file: Optional[Union[str, Path]] = None,
+    salt_env: Optional[str] = None,
+) -> Optional[PlateHasher]:
+    """Helper for front ends: build a hasher from whichever salt source is given."""
+    if salt is not None:
+        return PlateHasher(salt)
+    if salt_file is not None:
+        return PlateHasher.from_file(salt_file)
+    if salt_env is not None:
+        return PlateHasher.from_env(salt_env)
+    return None