gbfs-validator 0.1.0__py3-none-any.whl

gbfs_validator/__init__.py

@@ -0,0 +1,12 @@
+from typing import Any
+
+from gbfs_validator.feed import GBFS
+from gbfs_validator.version import __version__
+
+
+def validate_feed(url: str, **kwargs: Any) -> dict[str, Any]:
+    """Validate a GBFS feed and return the report."""
+    return GBFS(url, **kwargs).validation()
+
+
+__all__ = ["GBFS", "__version__", "validate_feed"]

gbfs_validator/cli.py

@@ -0,0 +1,168 @@
+"""Command line entry point: validate a feed, print and/or save the JSON report."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import sys
+from typing import Any
+
+from gbfs_validator.constants.error_ids import ErrorIds
+from gbfs_validator.feed import GBFS
+from gbfs_validator.version import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gbfs-validator",
+        usage="%(prog)s [OPTIONS]...",
+        description="Validate a GBFS feed and report on every file it declares.",
+    )
+    parser.add_argument("-v", "--version", action="version", version=__version__)
+    parser.add_argument(
+        "-u",
+        "--url",
+        metavar="FEED_URL",
+        required=True,
+        help="URL of the GBFS feed, or a local path to a directory or a gbfs.json file",
+    )
+    parser.add_argument(
+        "-vb", "--verbose", action="store_true", help="print progress logs to stderr"
+    )
+    parser.add_argument(
+        "-s", "--save-report", metavar="REPORT_PATH", help="local path to write the report to"
+    )
+    parser.add_argument(
+        "-pr",
+        "--print-report",
+        choices=["yes", "no"],
+        default="yes",
+        help="print the report as JSON to standard output (default: yes)",
+    )
+    parser.add_argument("--docked", action="store_true", help="feed serves a docked system")
+    parser.add_argument(
+        "--free-floating", action="store_true", help="feed serves a free floating system"
+    )
+    parser.add_argument(
+        "--feed-version",
+        metavar="VERSION",
+        help="validate against this GBFS version instead of the detected one",
+    )
+    parser.add_argument(
+        "--include-schema", action="store_true", help="keep the compiled schema in the report"
+    )
+    parser.add_argument(
+        "--fail-on-error", action="store_true", help="exit 1 when the feed has validation errors"
+    )
+    return parser
+
+
+def resolve_url(url: str) -> str:
+    """An existing local path becomes a file:// URL; a directory keeps a trailing slash."""
+    path = pathlib.Path(url)
+    if not path.exists():
+        return url
+    resolved = path.resolve()
+    # Without the trailing slash, urljoin drops the directory when it appends
+    # gbfs.json (feed.py:69).
+    return f"{resolved.as_uri()}/" if resolved.is_dir() else resolved.as_uri()
+
+
+def strip_report(report: dict[str, Any], include_schema: bool) -> dict[str, Any]:
+    """The CLI never echoes fetched bodies, and drops schemas unless asked for them."""
+    if "files" not in report:
+        return report
+    drop = {"body"} if include_schema else {"body", "schema"}
+    return {**report, "files": [_strip_entry(entry, drop) for entry in report["files"]]}
+
+
+def _strip_entry(entry: dict[str, Any], drop: set[str]) -> dict[str, Any]:
+    out = {key: value for key, value in entry.items() if key not in drop}
+    languages = out.get("languages")
+    if isinstance(languages, list):
+        out["languages"] = [
+            {key: value for key, value in lang.items() if key not in drop} for lang in languages
+        ]
+    return out
+
+
+def _save(report_json: str, destination: str) -> None:
+    path = pathlib.Path(destination)
+    if path.parent != path:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(report_json)
+
+
+def _discard_stdout() -> None:
+    """Point fd 1 at /dev/null so the interpreter's shutdown flush cannot fail too."""
+    try:
+        fd = sys.stdout.fileno()
+    except (AttributeError, ValueError, OSError):
+        return
+    devnull = os.open(os.devnull, os.O_WRONLY)
+    try:
+        os.dup2(devnull, fd)
+    finally:
+        os.close(devnull)
+
+
+def _critical(err: Exception) -> int:
+    """Upstream's catch-all critical path (cli.js:93)."""
+    if isinstance(err, BrokenPipeError):
+        _discard_stdout()
+    print(f"Critical error while validating GBFS feed => {err}", file=sys.stderr)
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exit_request:
+        if exit_request.code:
+            raise
+        return 0
+
+    if not args.save_report and args.print_report == "no":
+        print(
+            f"[{ErrorIds.CLI_NO_OUTPUT_REQUESTED}] Please set at least one of the following "
+            f"options: --save-report or --print-report",
+            file=sys.stderr,
+        )
+        parser.print_help(sys.stderr)
+        return 1
+
+    url = resolve_url(args.url)
+    if args.verbose:
+        print(f"Started GBFS validation of {url} with options: {vars(args)}", file=sys.stderr)
+
+    # Printing and saving stay inside the catch, as upstream does (cli.js:85).
+    try:
+        report = GBFS(
+            url,
+            docked=args.docked,
+            freefloating=args.free_floating,
+            version=args.feed_version,
+        ).validation()
+        report_json = json.dumps(strip_report(report, args.include_schema))
+        if args.print_report == "yes":
+            print(report_json)
+            # Without this, a closed stdout only fails at shutdown, past the catch.
+            sys.stdout.flush()
+        if args.save_report:
+            _save(report_json, args.save_report)
+    except Exception as err:  # noqa: BLE001 - upstream's catch-all critical path (cli.js:93)
+        return _critical(err)
+
+    if args.verbose:
+        print("Validation completed", file=sys.stderr)
+
+    if args.fail_on_error and report["summary"].get("hasErrors"):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gbfs_validator/conditionals.py

@@ -0,0 +1,162 @@
+"""The cross-file conditional rules, ported from the switch in gbfs.js:730.
+
+Every test here is JavaScript truthiness on unvalidated feed data, so an empty
+string id or a zero price triggers nothing while an empty array or object
+triggers everything. That is upstream's behavior and the differential depends
+on it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from gbfs_validator.feedhelpers import (
+    file_exist,
+    get_pricing_plans,
+    get_vehicle_types,
+    had_vehicle_type_id,
+    has_pricing_plan_id,
+    has_rental_uris,
+    prop,
+)
+from gbfs_validator.jstruth import truthy
+from gbfs_validator.partials import get_partial_schema
+
+Context = dict[str, Any]
+
+
+def _has_length(value: Any) -> bool:
+    """`value && value.length`: only arrays and strings carry a length in JS."""
+    return isinstance(value, (list, str)) and len(value) > 0
+
+
+def find_type(files: list[dict[str, Any]], file_type: str) -> dict[str, Any] | None:
+    return next((f for f in files if f.get("type") == file_type), None)
+
+
+def conditional_context(files: list[dict[str, Any]]) -> Context:
+    vehicle_types_file = find_type(files, "vehicle_types")
+    free_bike_status_file = find_type(files, "free_bike_status")
+    station_information_file = find_type(files, "station_information")
+    pricing_plans_file = find_type(files, "system_pricing_plans")
+
+    context: Context = {
+        "vehicleTypes": None,
+        "pricingPlans": None,
+        "freeBikeStatusHasVehicleTypeId": None,
+        "hasIosRentalUris": None,
+        "hasAndroidRentalUris": None,
+        "hasBikesPricingPlanId": None,
+    }
+
+    if vehicle_types_file is not None and file_exist(vehicle_types_file):
+        context["vehicleTypes"] = get_vehicle_types(vehicle_types_file)
+
+    if free_bike_status_file is not None and file_exist(free_bike_status_file):
+        context["freeBikeStatusHasVehicleTypeId"] = had_vehicle_type_id(free_bike_status_file)
+        context["hasIosRentalUris"] = has_rental_uris(free_bike_status_file, "bikes", "ios")
+        context["hasAndroidRentalUris"] = has_rental_uris(free_bike_status_file, "bikes", "android")
+        context["hasBikesPricingPlanId"] = has_pricing_plan_id(free_bike_status_file)
+
+    if station_information_file is not None and file_exist(station_information_file):
+        context["hasIosRentalUris"] = context["hasIosRentalUris"] or has_rental_uris(
+            station_information_file, "stations", "ios"
+        )
+        context["hasAndroidRentalUris"] = context["hasAndroidRentalUris"] or has_rental_uris(
+            station_information_file, "stations", "android"
+        )
+
+    if pricing_plans_file is not None and file_exist(pricing_plans_file):
+        context["pricingPlans"] = get_pricing_plans(pricing_plans_file)
+
+    return context
+
+
+def partials_for(
+    version: str, file: dict[str, Any], context: Context
+) -> tuple[list[dict[str, Any]], Any]:
+    """Schema patches for one file, plus its possibly promoted `required`."""
+    add_schema: list[dict[str, Any]] = []
+    required = file.get("required")
+    file_type = file.get("type")
+    vehicle_types = context["vehicleTypes"]
+    has_vehicle_types = _has_length(vehicle_types)
+
+    if file_type == "station_status" and has_vehicle_types:
+        _add(
+            add_schema,
+            version,
+            "station_status/required_vehicle_types_available",
+            {"vehicleTypes": vehicle_types},
+        )
+    elif file_type == "free_bike_status" and has_vehicle_types:
+        _add(
+            add_schema,
+            version,
+            "free_bike_status/required_vehicle_type_id",
+            {"vehicleTypes": vehicle_types},
+        )
+    elif file_type == "vehicle_status" and has_vehicle_types:
+        _add(
+            add_schema,
+            version,
+            "vehicle_status/required_vehicle_type_id",
+            {"vehicleTypes": vehicle_types},
+        )
+    elif file_type == "vehicle_types":
+        required = _vehicle_types_rules(add_schema, version, context, required)
+    elif file_type == "system_pricing_plans":
+        if context["hasBikesPricingPlanId"]:
+            required = True
+    elif file_type == "system_information":
+        _system_information_rules(add_schema, version, context)
+
+    return add_schema, required
+
+
+def _vehicle_types_rules(
+    add_schema: list[dict[str, Any]], version: str, context: Context, required: Any
+) -> Any:
+    if context["freeBikeStatusHasVehicleTypeId"]:
+        required = True
+    plans = context["pricingPlans"]
+    if not _has_length(plans):
+        return required
+
+    _add(add_schema, version, "vehicle_types/pricing_plan_id", {"pricingPlans": plans})
+    # Truthiness, so a zero price does not count as a reservation price while an
+    # empty object does.
+    reserved = [
+        prop(plan, "plan_id", "pricing plan")
+        for plan in plans
+        if truthy(prop(plan, "reservation_price_flat_rate", "pricing plan"))
+        or truthy(prop(plan, "reservation_price_per_min", "pricing plan"))
+    ]
+    if reserved:
+        _add(
+            add_schema,
+            version,
+            "vehicle_types/default_reserve_time_require",
+            {"pricingPlansIdsWithReservationPrice": reserved},
+        )
+    return required
+
+
+def _system_information_rules(
+    add_schema: list[dict[str, Any]], version: str, context: Context
+) -> None:
+    ios = context["hasIosRentalUris"]
+    android = context["hasAndroidRentalUris"]
+    if android or ios:
+        _add(
+            add_schema,
+            version,
+            "system_information/required_store_uri",
+            {"ios": bool(ios), "android": bool(android)},
+        )
+
+
+def _add(add_schema: list[dict[str, Any]], version: str, name: str, params: dict[str, Any]) -> None:
+    partial = get_partial_schema(version, name, params)
+    if partial:
+        add_schema.append(partial)

gbfs_validator/constants/error_ids.py

@@ -0,0 +1,56 @@
+"""Central error ID registry. See guides/error-id-registry.md in agent-starter.
+
+Rules:
+  1. Never reuse a retired ID: mark it `# retired` and leave it in place.
+  2. One ID per distinct cause, not per raise site.
+  3. Numbers are stable; append, never renumber.
+
+Raise via AppError(ErrorIds.X, "...", {...}). Log lines include the ID so
+grep, telemetry, and agents can all find every occurrence with one search.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from typing import Any
+
+
+class ErrorIds(StrEnum):
+    # Fetching a feed file (network, status, decode)
+    FETCH_UNREACHABLE = "E_FETCH_001"
+    FETCH_BAD_STATUS = "E_FETCH_002"
+    FETCH_BAD_JSON = "E_FETCH_003"
+    FETCH_AUTH_FAILED = "E_FETCH_004"
+
+    # Schema handling
+    SCHEMA_UNKNOWN_VERSION = "E_SCHEMA_001"
+    SCHEMA_MISSING_FILE = "E_SCHEMA_002"
+    SCHEMA_PATCH_SOURCE_MISMATCH = "E_SCHEMA_003"
+    SCHEMA_UNSUPPORTED_PATCH_OP = "E_SCHEMA_004"
+
+    # Feed structure encountered before validation could report on it. These
+    # mirror upstream crashes on purpose; see the spec's parity contract.
+    FEED_MISSING_URL = "E_FEED_001"
+    FEED_MALFORMED_CONTAINER = "E_FEED_002"
+
+    # CLI usage
+    CLI_NO_OUTPUT_REQUESTED = "E_CLI_001"
+
+
+class AppError(Exception):
+    """Base error: every raise carries a stable ID plus structured context."""
+
+    def __init__(
+        self,
+        error_id: ErrorIds,
+        message: str,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.id = error_id
+        self.context = context or {}
+
+    def to_log_line(self) -> str:
+        ctx = " ".join(f"{k}={json.dumps(v, default=str)}" for k, v in self.context.items())
+        return f"[{self.id}] {self}{' ' + ctx if ctx else ''}"

gbfs_validator/data/PIN

@@ -0,0 +1,2 @@
+b734086ccdf93b5acd72bb349c6fda0c9f64fd39
+916327fe43ea79683f57c87bc54fdfc24797862f

gbfs_validator/data/schemas/v1.0/free_bike_status.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "https://github.com/MobilityData/gbfs/blob/v1.0/gbfs.md#free_bike_statusjson",
+  "description": "Describes the vehicles that are available for rent (as of v2.1-RC2).",
+  "type": "object",
+  "properties": {
+    "last_updated": {
+      "description": "Last time the data in the feed was updated in POSIX time.",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1924988399
+    },
+    "ttl": {
+      "description": "Number of seconds before the data in the feed will be updated again (0 if the data should always be refreshed).",
+      "type": "integer",
+      "minimum": 0
+    },
+    "data": {
+      "description": "Array that contains one object per bike as defined below.",
+      "type": "object",
+      "properties": {
+        "bikes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "bike_id": {
+                "description": "Rotating (as of v2.0) identifier of a vehicle.",
+                "type": "string"
+              },
+              "lat": {
+                "description": "The latitude of the vehicle.",
+                "type": "number",
+                "minimum": -90,
+                "maximum": 90
+              },
+              "lon": {
+                "description": 	"The longitude of the vehicle.",
+                "type": "number",
+                "minimum": -180,
+                "maximum": 180
+              },
+              "is_reserved": {
+                "description": "Is the vehicle currently reserved?",
+                "oneOf": [{ "type": "boolean" }, { "type": "number" }]
+              },
+              "is_disabled": {
+                "description": "Is the vehicle currently disabled (broken)?",
+                "oneOf": [{ "type": "boolean" }, { "type": "number" }]
+              }
+            },
+            "required": ["bike_id", "lat", "lon", "is_reserved", "is_disabled"]
+          }
+        }
+      },
+      "required": ["bikes"]
+    }
+  },
+  "required": ["last_updated", "ttl", "data"]
+}

gbfs_validator/data/schemas/v1.0/gbfs.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "https://github.com/MobilityData/gbfs/blob/v1.0/gbfs.md#gbfsjson",
+  "description": "Auto-discovery file that links to all of the other files published by the system.",
+  "type": "object",
+  "properties": {
+    "last_updated": {
+      "description": "Last time the data in the feed was updated in POSIX time.",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1924988399
+    },
+    "ttl": {
+      "description": "Number of seconds before the data in the feed will be updated again (0 if the data should always be refreshed).",
+      "type": "integer",
+      "minimum": 0
+    },
+    "data": {
+      "description": "Response data in the form of name:value pairs.",
+      "type": "object",
+      "patternProperties": {
+        "^[a-zA-Z]{2}$": {
+          "type": "object",
+          "properties": {
+            "feeds": {
+              "description": "An array of all of the feeds that are published by the auto-discovery file. Each element in the array is an object with the keys below.",
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "url": {
+                    "type": "string"
+                  }
+                },
+                "required": ["name", "url"]
+              },
+              "minItems": 1,
+              "contains": {
+                "properties": {
+                  "name": { "const": "system_information" }
+                }
+              }
+            }
+          },
+          "required": ["feeds"]
+        }
+      },
+      "minProperties": 1,
+      "additionalProperties": false
+    }
+  },
+  "required": ["last_updated", "ttl", "data"]
+}

gbfs_validator/data/schemas/v1.0/station_information.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "https://github.com/MobilityData/gbfs/blob/v1.0/gbfs.md#station_informationjson",
+  "description": "List of all stations, their capacities and locations. REQUIRED of systems utilizing docks.",
+  "type": "object",
+  "properties": {
+    "last_updated": {
+      "description": 	"Last time the data in the feed was updated in POSIX time.",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1924988399
+    },
+    "ttl": {
+      "description": "Number of seconds before the data in the feed will be updated again (0 if the data should always be refreshed).",
+      "type": "integer",
+      "minimum": 0
+    },
+    "data": {
+      "description": "Array that contains one object per station as defined below.",
+      "type": "object",
+      "properties": {
+        "stations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "station_id": {
+                "description": 	"Identifier of a station.",
+                "type": "string"
+              },
+              "name": {
+                "description": "Public name of the station.",
+                "type": "string"
+              },
+              "short_name": {
+                "description": "Short name or other type of identifier.",
+                "type": "string"
+              },
+              "lat": {
+                "description": 	"The latitude of the station.",
+                "type": "number",
+                "minimum": -90,
+                "maximum": 90
+              },
+              "lon": {
+                "description": 	"The longitude fo the station.",
+                "type": "number",
+                "minimum": -180,
+                "maximum": 180
+              },
+              "address": {
+                "description": 	"Address where station is located.",
+                "type": "string"
+              },
+              "cross_street": {
+                "description": 	"Cross street or landmark…the station is located.",
+                "type": "string"
+              },
+              "region_id": {
+                "description": "Identifier of the region…the station is located.",
+                "type": "string"
+              },
+              "post_code": {
+                "description": "Postal code where station is located.",
+                "type": "string"
+              },
+              "rental_methods": {
+                "description": "Payment methods accepted at this station.",
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "KEY",
+                    "CREDITCARD",
+                    "PAYPASS",
+                    "APPLEPAY",
+                    "ANDROIDPAY",
+                    "TRANSITCARD",
+                    "ACCOUNTNUMBER",
+                    "PHONE"
+                  ]
+                }
+              },
+              "capacity": {
+                "description": "Number of total docking …ilable and unavailable.",
+                "type": "integer",
+                "minimum": 0
+              }
+            },
+            "required": ["station_id", "name", "lat", "lon"]
+          }
+        }
+      },
+      "required": ["stations"]
+    }
+  },
+  "required": ["last_updated", "ttl", "data"]
+}