gtfslint-cli 0.1.0__py3-none-any.whl

gtfslint/__init__.py

@@ -0,0 +1,32 @@
+"""gtfslint: a fast, pure-Python GTFS Schedule validator and quality report for CI.
+
+>>> import gtfslint
+>>> report = gtfslint.validate("feed.zip")          # doctest: +SKIP
+>>> report.errors, report.warnings                  # doctest: +SKIP
+>>> gtfslint.stats("feed.zip").trips_per_day        # doctest: +SKIP
+"""
+
+from .api import stats, validate
+from .config import Config, load_config
+from .notices import RULES, Notice, Rule, Severity
+from .reader import FeedError
+from .report import Report
+from .stats import FeedStats, RouteHeadway
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RULES",
+    "Config",
+    "FeedError",
+    "FeedStats",
+    "Notice",
+    "Report",
+    "RouteHeadway",
+    "Rule",
+    "Severity",
+    "__version__",
+    "load_config",
+    "stats",
+    "validate",
+]

gtfslint/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m gtfslint``."""
+
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

gtfslint/api.py

@@ -0,0 +1,71 @@
+"""Public entry points: :func:`validate` and :func:`stats`."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os
+import time
+from pathlib import Path
+from typing import Iterable, Optional, Union
+
+from .config import Config, parse_reference_date
+from .reader import FeedSource
+from .report import Report
+from .stats import FeedStats, compute_stats
+from .validator import Engine
+
+__all__ = ["stats", "validate"]
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+
+def validate(
+    path: PathLike,
+    *,
+    config: Optional[Config] = None,
+    select: Optional[Iterable[str]] = None,
+    ignore: Optional[Iterable[str]] = None,
+    reference_date: Union[str, _dt.date, None] = None,
+    with_stats: bool = False,
+) -> Report:
+    """Validate a GTFS Schedule feed (``.zip`` or folder) and return a :class:`Report`.
+
+    ``select``/``ignore`` take rule codes, code prefixes or rule names and override the
+    corresponding ``config`` settings. ``reference_date`` (default: today) anchors the
+    expiration rules. Raises :class:`gtfslint.FeedError` when the path cannot be read.
+    """
+    cfg = (config or Config()).replace(
+        select=list(select) if select is not None else None,
+        ignore=list(ignore) if ignore is not None else None,
+        reference_date=parse_reference_date(reference_date),
+    )
+    from . import __version__
+
+    t0 = time.perf_counter()
+    with FeedSource(path) as src:
+        engine = Engine(src, cfg).run()
+    report = Report(
+        feed=Path(path).as_posix(),
+        notices=engine.out.notices,
+        counts=dict(engine.out.counts),
+        feed_kind=src.kind,
+        files=engine.ctx.files,
+        row_counts=engine.ctx.row_counts,
+        reference_date=engine.ref_date.isoformat(),
+        version=__version__,
+    )
+    if with_stats:
+        report.stats = compute_stats(engine.ctx, report.feed)
+    report.duration_s = time.perf_counter() - t0
+    return report
+
+
+def stats(path: PathLike, *, date: Union[str, _dt.date, None] = None) -> FeedStats:
+    """Compute quality metrics for a feed without collecting notices.
+
+    ``date`` (``YYYY-MM-DD``) selects the day used for headways and vehicle hours; by
+    default the busiest service date is used.
+    """
+    with FeedSource(path) as src:
+        engine = Engine(src, Config(), collect=False).run()
+    return compute_stats(engine.ctx, Path(path).as_posix(), parse_reference_date(date))

gtfslint/cli.py

@@ -0,0 +1,177 @@
+"""Command line interface: ``gtfslint check``, ``gtfslint stats`` and ``gtfslint rules``.
+
+Exit codes: 0 = no notice at or above ``--fail-on``; 1 = at least one such notice;
+2 = usage error, invalid configuration or unreadable feed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from . import __version__
+from .api import stats as compute_feed_stats
+from .api import validate
+from .config import FAIL_ON_CHOICES, Config, load_config
+from .notices import RULES
+from .reader import FeedError
+from .report import FORMATS, stats_to_html, stats_to_markdown, stats_to_text
+
+EXIT_OK, EXIT_FAIL, EXIT_USAGE = 0, 1, 2
+
+
+def _csv_list(value: str) -> List[str]:
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gtfslint",
+        description="Fast GTFS Schedule validator and quality report.",
+    )
+    parser.add_argument("--version", action="version", version=f"gtfslint {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser("check", help="validate one or more feeds (.zip or folder)")
+    check.add_argument("feeds", nargs="+", help="GTFS .zip archive(s) or folder(s)")
+    check.add_argument("-f", "--format", choices=FORMATS, default="text", help="stdout format")
+    check.add_argument("-o", "--output", help="write the --format output to this file")
+    check.add_argument("--json", dest="json_out", metavar="FILE", help="also write a JSON report")
+    check.add_argument("--markdown", metavar="FILE", help="also write a Markdown report")
+    check.add_argument("--html", metavar="FILE", help="also write a self-contained HTML report")
+    check.add_argument("--select", type=_csv_list, help="rules to enable (codes, prefixes, names)")
+    check.add_argument("--ignore", type=_csv_list, help="rules to disable (codes, prefixes, names)")
+    check.add_argument("--fail-on", choices=FAIL_ON_CHOICES, help="lowest severity that fails")
+    check.add_argument("--reference-date", help="date for expiration rules (default: today)")
+    check.add_argument("--max-notices-per-rule", type=int, help="notices kept per rule")
+    check.add_argument("--stats", action="store_true", help="include feed statistics")
+    check.add_argument("-q", "--quiet", action="store_true", help="print only the summary line")
+    _config_args(check)
+
+    st = sub.add_parser("stats", help="print quality metrics of a feed")
+    st.add_argument("feed", help="GTFS .zip archive or folder")
+    st.add_argument("-f", "--format", choices=("text", "json", "markdown", "html"), default="text")
+    st.add_argument("-o", "--output", help="write the --format output to this file")
+    st.add_argument("--json", dest="json_out", metavar="FILE", help="also write JSON")
+    st.add_argument("--markdown", metavar="FILE", help="also write Markdown")
+    st.add_argument("--html", metavar="FILE", help="also write a self-contained HTML page")
+    st.add_argument("--date", help="analysis date YYYY-MM-DD (default: busiest date)")
+
+    rules = sub.add_parser("rules", help="list every rule")
+    rules.add_argument("-f", "--format", choices=("text", "json", "markdown"), default="text")
+    return parser
+
+
+def _config_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--config", help="pyproject.toml to read [tool.gtfslint] from")
+    p.add_argument("--no-config", action="store_true", help="ignore pyproject.toml")
+
+
+def _write(path: Optional[str], text: str) -> None:
+    if path:
+        Path(path).write_text(text, encoding="utf-8")
+
+
+def _emit(text: str) -> None:
+    text = text if text.endswith("\n") else text + "\n"
+    try:
+        sys.stdout.write(text)
+    except UnicodeEncodeError:  # legacy console code pages
+        encoding = sys.stdout.encoding or "utf-8"
+        sys.stdout.write(text.encode(encoding, "replace").decode(encoding))
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    cfg = Config() if args.no_config else load_config(args.config)
+    cfg = cfg.replace(
+        select=args.select,
+        ignore=args.ignore,
+        fail_on=args.fail_on,
+        reference_date=args.reference_date,
+        max_notices_per_rule=args.max_notices_per_rule,
+    )
+    files = [args.output, args.json_out, args.markdown, args.html]
+    if len(args.feeds) > 1 and any(files):
+        print("gtfslint: file outputs require a single feed", file=sys.stderr)
+        return EXIT_USAGE
+    worst = EXIT_OK
+    for feed in args.feeds:
+        try:
+            report = validate(feed, config=cfg, with_stats=args.stats)
+        except FeedError as exc:
+            print(f"gtfslint: {exc}", file=sys.stderr)
+            return EXIT_USAGE
+        text = report.render(args.format)
+        if args.output:
+            _write(args.output, text)
+        elif args.quiet:
+            _emit(f"{'FAILED' if not report.ok else 'OK'}: {report.summary()}")
+        else:
+            _emit(text)
+        _write(args.json_out, report.to_json())
+        _write(args.markdown, report.to_markdown())
+        _write(args.html, report.to_html())
+        worst = max(worst, report.exit_code(cfg.fail_on))
+    return worst
+
+
+def _cmd_stats(args: argparse.Namespace) -> int:
+    try:
+        st = compute_feed_stats(args.feed, date=args.date)
+    except FeedError as exc:
+        print(f"gtfslint: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    renderers = {
+        "text": lambda: stats_to_text(st),
+        "json": lambda: json.dumps(st.to_dict(), indent=2, ensure_ascii=False),
+        "markdown": lambda: stats_to_markdown(st),
+        "html": lambda: stats_to_html(st),
+    }
+    text = renderers[args.format]()
+    if args.output:
+        _write(args.output, text)
+    else:
+        _emit(text)
+    if args.json_out:
+        _write(args.json_out, renderers["json"]())
+    if args.markdown:
+        _write(args.markdown, renderers["markdown"]())
+    if args.html:
+        _write(args.html, renderers["html"]())
+    return EXIT_OK
+
+
+def _cmd_rules(args: argparse.Namespace) -> int:
+    if args.format == "json":
+        _emit(json.dumps([r.to_dict() for r in RULES.values()], indent=2))
+    elif args.format == "markdown":
+        lines = ["| Code | Name | Severity | Description |", "|---|---|---|---|"]
+        lines += [
+            f"| [{r.code}]({r.reference}) | `{r.name}` | {r.severity.label} | {r.description} |"
+            for r in RULES.values()
+        ]
+        _emit("\n".join(lines))
+    else:
+        _emit("\n".join(f"{r.code}  {r.severity.label:<7}  {r.name}" for r in RULES.values()))
+    return EXIT_OK
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Run the CLI and return its exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "check":
+            return _cmd_check(args)
+        if args.command == "stats":
+            return _cmd_stats(args)
+        return _cmd_rules(args)
+    except ValueError as exc:
+        print(f"gtfslint: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    except OSError as exc:
+        print(f"gtfslint: {exc}", file=sys.stderr)
+        return EXIT_USAGE

gtfslint/config.py

@@ -0,0 +1,112 @@
+"""Configuration: defaults, ``[tool.gtfslint]`` in ``pyproject.toml`` and overrides."""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+from .notices import Severity, resolve_selection
+
+if sys.version_info >= (3, 11):  # pragma: no cover - version dependent
+    import tomllib as _toml
+else:  # pragma: no cover - version dependent
+    import tomli as _toml
+
+__all__ = ["Config", "find_pyproject", "load_config", "parse_reference_date"]
+
+FAIL_ON_CHOICES = ("error", "warning", "info", "never")
+
+
+def parse_reference_date(value: Union[str, _dt.date, None]) -> Optional[_dt.date]:
+    """Accept ``YYYY-MM-DD``, ``YYYYMMDD`` or a :class:`datetime.date`."""
+    if value is None or isinstance(value, _dt.date):
+        return value
+    text = str(value).strip()
+    for fmt in ("%Y-%m-%d", "%Y%m%d"):
+        try:
+            return _dt.datetime.strptime(text, fmt).date()
+        except ValueError:
+            continue
+    raise ValueError(f"invalid date {value!r}; expected YYYY-MM-DD")
+
+
+@dataclass
+class Config:
+    """Validator settings. Every field can be set in ``[tool.gtfslint]``.
+
+    TOML keys use dashes (``fail-on``); underscores are accepted too.
+    """
+
+    select: Optional[List[str]] = None
+    ignore: List[str] = field(default_factory=list)
+    fail_on: str = "error"
+    max_notices_per_rule: int = 1000
+    reference_date: Optional[_dt.date] = None
+    min_stop_distance_m: float = 2.0
+    max_parent_distance_m: float = 1000.0
+    max_stop_distance_km: Optional[float] = None
+    speed_limits_kmh: Dict[int, float] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if isinstance(self.select, str):
+            self.select = [s for s in self.select.split(",") if s.strip()]
+        if isinstance(self.ignore, str):
+            self.ignore = [s for s in self.ignore.split(",") if s.strip()]
+        if self.fail_on not in FAIL_ON_CHOICES:
+            raise ValueError(f"fail-on must be one of {', '.join(FAIL_ON_CHOICES)}")
+        self.reference_date = parse_reference_date(self.reference_date)
+        self.speed_limits_kmh = {int(k): float(v) for k, v in self.speed_limits_kmh.items()}
+        resolve_selection(self.select, self.ignore)  # validates selectors early
+
+    @property
+    def enabled_rules(self) -> frozenset:
+        return resolve_selection(self.select, self.ignore)
+
+    @property
+    def fail_threshold(self) -> Optional[Severity]:
+        return None if self.fail_on == "never" else Severity.parse(self.fail_on)
+
+    def replace(self, **changes: Any) -> Config:
+        """Return a copy with the non-``None`` ``changes`` applied."""
+        clean = {k: v for k, v in changes.items() if v is not None}
+        return dataclasses.replace(self, **clean)
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any]) -> Config:
+        """Build a config from a ``[tool.gtfslint]`` table; unknown keys raise."""
+        names = {f.name for f in dataclasses.fields(cls)}
+        kwargs: Dict[str, Any] = {}
+        for key, value in data.items():
+            attr = key.replace("-", "_")
+            if attr not in names:
+                raise ValueError(f"unknown [tool.gtfslint] option {key!r}")
+            kwargs[attr] = value
+        return cls(**kwargs)
+
+
+def find_pyproject(start: Union[str, Path, None] = None) -> Optional[Path]:
+    """Return the nearest ``pyproject.toml`` at or above ``start`` (default: cwd)."""
+    here = Path(start or Path.cwd()).resolve()
+    for folder in (here, *here.parents):
+        candidate = folder / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_config(path: Union[str, Path, None] = None) -> Config:
+    """Load ``[tool.gtfslint]`` from ``path`` (or the nearest ``pyproject.toml``).
+
+    Returns default settings when there is no file or no ``[tool.gtfslint]`` table.
+    """
+    target = Path(path) if path is not None else find_pyproject()
+    if target is None:
+        return Config()
+    with open(target, "rb") as fh:
+        data = _toml.load(fh)
+    table = data.get("tool", {}).get("gtfslint", {})
+    return Config.from_mapping(table)

gtfslint/fieldtypes.py

@@ -0,0 +1,165 @@
+"""Parsers and validators for GTFS field types (colors, URLs, dates, times, ...)."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import math
+import re
+from functools import lru_cache
+from typing import FrozenSet, Optional
+from urllib.parse import urlsplit
+
+__all__ = [
+    "contrast_ratio",
+    "is_color",
+    "is_currency",
+    "is_email",
+    "is_language",
+    "is_timezone",
+    "is_url",
+    "parse_date",
+    "parse_float",
+    "parse_int",
+    "parse_time",
+    "format_time",
+]
+
+_COLOR_RE = re.compile(r"[0-9A-Fa-f]{6}\Z")
+_TIME_RE = re.compile(r"(\d{1,3}):([0-5]\d):([0-5]\d)\Z")
+_INT_RE = re.compile(r"[+-]?\d+\Z")
+_EMAIL_RE = re.compile(r"[^@\s]+@[^@\s]+\.[^@\s]+\Z")
+_LANG_RE = re.compile(r"(?:[A-Za-z]{2,3}|[A-Za-z]{5,8})(?:-[A-Za-z0-9]{1,8})*\Z")
+_TZ_RE = re.compile(r"(?:UTC|GMT|[A-Z][A-Za-z_\-]+(?:/[A-Za-z0-9_+\-]+){1,2})\Z")
+
+# ISO 4217 alphabetic codes (active codes plus funds and precious metals).
+CURRENCIES: FrozenSet[str] = frozenset(
+    """
+    AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BOV BRL
+    BSD BTN BWP BYN BZD CAD CDF CHE CHF CHW CLF CLP CNY COP COU CRC CUC CUP CVE CZK DJF
+    DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG
+    HUF IDR ILS INR IQD IRR ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP
+    LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN MXV MYR MZN NAD NGN
+    NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG
+    SEK SGD SHP SLE SLL SOS SRD SSP STN SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS
+    UAH UGX USD USN UYI UYU UYW UZS VED VES VND VUV WST XAF XAG XAU XBA XBB XBC XBD XCD
+    XCG XDR XOF XPD XPF XPT XSU XTS XUA XXX YER ZAR ZMW ZWG ZWL
+    """.split()
+)
+
+
+def parse_int(value: str) -> Optional[int]:
+    """Parse a GTFS integer; return ``None`` when malformed."""
+    if _INT_RE.match(value):
+        return int(value)
+    return None
+
+
+def parse_float(value: str) -> Optional[float]:
+    """Parse a finite GTFS float; return ``None`` when malformed, NaN or infinite."""
+    try:
+        out = float(value)
+    except ValueError:
+        return None
+    if math.isnan(out) or math.isinf(out) or "_" in value:
+        return None
+    return out
+
+
+def parse_date(value: str) -> Optional[_dt.date]:
+    """Parse ``YYYYMMDD``; return ``None`` when malformed or not a real date."""
+    if len(value) != 8 or not value.isdigit():
+        return None
+    try:
+        return _dt.date(int(value[:4]), int(value[4:6]), int(value[6:]))
+    except ValueError:
+        return None
+
+
+@lru_cache(maxsize=200_000)
+def parse_time(value: str) -> Optional[int]:
+    """Parse ``H:MM:SS``/``HH:MM:SS`` into seconds since midnight of the service day.
+
+    Hours above 23 are valid (trips running past midnight). Returns ``None`` when the
+    value is malformed.
+    """
+    m = _TIME_RE.match(value)
+    if m is None:
+        return None
+    return int(m.group(1)) * 3600 + int(m.group(2)) * 60 + int(m.group(3))
+
+
+def format_time(seconds: int) -> str:
+    """Format seconds since midnight as ``HH:MM:SS`` (hours may exceed 23)."""
+    h, rem = divmod(int(seconds), 3600)
+    m, s = divmod(rem, 60)
+    return f"{h:02d}:{m:02d}:{s:02d}"
+
+
+def is_color(value: str) -> bool:
+    return _COLOR_RE.match(value) is not None
+
+
+def is_url(value: str) -> bool:
+    """True for a fully qualified http(s) URL with a host and no whitespace."""
+    if not value or any(c.isspace() for c in value):
+        return False
+    try:
+        parts = urlsplit(value)
+        host = parts.hostname
+    except ValueError:
+        return False
+    if parts.scheme.lower() not in ("http", "https") or not host:
+        return False
+    return "." in host or host == "localhost" or ":" in host
+
+
+def is_email(value: str) -> bool:
+    return _EMAIL_RE.match(value) is not None
+
+
+def is_language(value: str) -> bool:
+    """Well-formedness check for an IETF BCP 47 language tag."""
+    return _LANG_RE.match(value) is not None
+
+
+def is_currency(value: str) -> bool:
+    return value in CURRENCIES
+
+
+@lru_cache(maxsize=1)
+def _timezones() -> FrozenSet[str]:
+    try:
+        import zoneinfo
+
+        return frozenset(zoneinfo.available_timezones())
+    except Exception:  # pragma: no cover - Python without zoneinfo data
+        return frozenset()
+
+
+@lru_cache(maxsize=4096)
+def is_timezone(value: str) -> bool:
+    """True for an IANA TZ database name.
+
+    Uses the system/``tzdata`` database when available and falls back to a syntactic
+    check (``Area/Location``) otherwise.
+    """
+    zones = _timezones()
+    if zones:
+        return value in zones
+    return _TZ_RE.match(value) is not None  # pragma: no cover
+
+
+def _luminance(color: str) -> float:
+    def channel(c: int) -> float:
+        x = c / 255.0
+        return x / 12.92 if x <= 0.03928 else ((x + 0.055) / 1.055) ** 2.4
+
+    r, g, b = (int(color[i : i + 2], 16) for i in (0, 2, 4))
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)
+
+
+def contrast_ratio(color_a: str, color_b: str) -> float:
+    """WCAG 2 contrast ratio between two six-digit hex colors (1.0 to 21.0)."""
+    la, lb = _luminance(color_a), _luminance(color_b)
+    hi, lo = max(la, lb), min(la, lb)
+    return (hi + 0.05) / (lo + 0.05)