refactor common definitions access

* cache the read file in a global dict
* provide filtering overloads for common use cases
* remove duplicated code and unnecessary params

Author: thekaveman

agency/get_vehicle.json

@@ -31,6 +31,13 @@
       ],
       "pattern": "^(.*)$"
     },
+    "timestamp": {
+      "$id": "#/definitions/timestamp",
+      "type": "number",
+      "description": "Integer milliseconds since Unix epoch",
+      "multipleOf": 1.0,
+      "minimum": 0
+    },
     "vehicle_type": {
       "$id": "#/definitions/vehicle_type",
       "type": "string",
@@ -43,13 +50,6 @@
         "other"
       ]
     },
-    "timestamp": {
-      "$id": "#/definitions/timestamp",
-      "type": "number",
-      "description": "Integer milliseconds since Unix epoch",
-      "multipleOf": 1.0,
-      "minimum": 0
-    },
     "uuid": {
       "$id": "#/definitions/uuid",
       "type": "string",

schema/agency.py

@@ -7,33 +7,33 @@
 import common
 
 
-def get_stops_schema(common_definitions):
+def get_stops_schema():
     """
     Create the schema for the Agency GET /stops endpoint.
     """
     # load schema template and insert definitions
     schema = common.load_json("./templates/agency/get_stops.json")
-    stops = common.stop_definitions(common_definitions)
+    stops = common.stop_definitions()
     schema["definitions"].update(stops)
 
     # verify and return
     return common.check_schema(schema)
 
 
-def post_stops_schema(common_definitions):
+def post_stops_schema():
     """
     Create the schema for the Agency POST /stops endpoint.
     """
     # load schema template and insert definitions
     schema = common.load_json("./templates/agency/post_stops.json")
-    stops = common.stop_definitions(common_definitions)
+    stops = common.stop_definitions()
     schema["definitions"].update(stops)
 
     # verify and return
     return common.check_schema(schema)
 
 
-def put_stops_schema(common_definitions):
+def put_stops_schema():
     """
     Create the schema for the Agency POST /stops endpoint.
     """
@@ -42,60 +42,62 @@ def put_stops_schema(common_definitions):
     # the PUT body allows a small subset of fields
     schema = common.load_json("./templates/agency/put_stops.json")
 
-    stop_defs = common.stop_definitions(common_definitions)
+    stops = common.stop_definitions()
     needed_defs = ["stop_status", "uuid", "vehicle_type_counts"]
-    for key in [k for k in stop_defs.keys() if k not in needed_defs]:
-        del stop_defs[key]
+    for key in [k for k in stops.keys() if k not in needed_defs]:
+        del stops[key]
 
-    schema["definitions"].update(stop_defs)
+    schema["definitions"].update(stops)
 
     # verify and return
     return common.check_schema(schema)
 
 
-def get_vehicle_schema(common_definitions):
+def get_vehicle_schema():
     """
     Create the schema for the Agency GET /vehicles endpoint.
     """
     # load schema template and insert definitions
     schema = common.load_json("./templates/agency/get_vehicle.json")
-    schema["definitions"] = {
-        "propulsion_types": common_definitions["propulsion_types"],
-        "string": common_definitions["string"],
-        "vehicle_type": common_definitions["vehicle_type"],
-        "timestamp": common_definitions["timestamp"],
-        "uuid": common_definitions["uuid"]
-    }
+    definitions = common.load_definitions(
+        "propulsion_types",
+        "string",
+        "timestamp",
+        "vehicle_type",
+        "uuid"
+    )
+    schema["definitions"].update(definitions)
 
     # merge the state machine definitions and transition combinations rule
-    state_machine_defs, transitions = common.vehicle_state_machine(common_definitions, "state", "prev_events")
+    state_machine_defs, transitions = common.vehicle_state_machine("state", "prev_events")
     schema["definitions"].update(state_machine_defs)
     schema["allOf"].append(transitions)
 
     # merge common vehicle information, with Agency tweaks
-    vehicle = common.vehicle_definition(common_definitions, provider_name=False)
+    vehicle = common.vehicle_definition(provider_name=False)
     schema["required"] = vehicle["required"] + schema["required"]
     schema["properties"] = { **vehicle["properties"], **schema["properties"] }
 
     # verify and return
     return common.check_schema(schema)
 
 
-def post_vehicle_schema(common_definitions):
+def post_vehicle_schema():
     """
     Create the schema for the Agency POST /vehicles endpoint.
     """
     # load schema template and insert definitions
     schema = common.load_json("./templates/agency/post_vehicle.json")
-    schema["definitions"] = {
-        "propulsion_types": common_definitions["propulsion_types"],
-        "string": common_definitions["string"],
-        "vehicle_type": common_definitions["vehicle_type"],
-        "uuid": common_definitions["uuid"]
-    }
+    definitions = common.load_definitions(
+        "propulsion_types",
+        "string",
+        "vehicle_type",
+        "uuid"
+    )
+    schema["definitions"].update(definitions)
 
     # merge common vehicle information, with Agency tweaks
-    vehicle = common.vehicle_definition(common_definitions, provider_name=False, provider_id=False)
+    vehicle = common.vehicle_definition(provider_name=False, provider_id=False)
 
     schema["required"] = vehicle["required"] + schema["required"]
     schema["properties"] = { **vehicle["properties"], **schema["properties"] }
@@ -104,42 +106,44 @@ def post_vehicle_schema(common_definitions):
     return common.check_schema(schema)
 
 
-def post_vehicle_event_schema(common_definitions):
+def post_vehicle_event_schema():
     """
     Create the schema for the Agency POST /vehicles/:id/event endpoint.
     """
     # load schema template and insert definitions
     schema = common.load_json("./templates/agency/post_vehicle_event.json")
-    schema["definitions"] = {
-        "telemetry": common_definitions["telemetry"],
-        "timestamp": common_definitions["timestamp"],
-        "uuid": common_definitions["uuid"]
-    }
+    definitions = common.load_definitions(
+        "telemetry",
+        "timestamp",
+        "uuid"
+    )
+    schema["definitions"].update(definitions)
 
     # merge the state machine definitions and transition combinations rule
-    state_machine_defs, transitions = common.vehicle_state_machine(common_definitions, "vehicle_state", "event_types")
+    state_machine_defs, transitions = common.vehicle_state_machine("vehicle_state", "event_types")
     schema["definitions"].update(state_machine_defs)
     schema["allOf"].append(transitions)
 
     # add the conditionally-required trip_id rule
-    trip_id_ref = common_definitions["trip_id_reference"]
+    trip_id_ref = common.load_definitions("trip_id_reference")
     schema["allOf"].append(trip_id_ref)
 
     # verify and return
     return common.check_schema(schema)
 
 
-def post_vehicle_telemetry_schema(common_definitions):
+def post_vehicle_telemetry_schema():
     """
     Create the schema for the Agency POST /vehicles/telemetry endpoint.
     """
     # load schema template and insert definitions
     schema = common.load_json("./templates/agency/post_vehicle_telemetry.json")
-    schema["definitions"] = {
-        "telemetry": common_definitions["telemetry"],
-        "timestamp": common_definitions["timestamp"],
-        "uuid": common_definitions["uuid"]
-    }
+    definitions = common.load_definitions(
+        "telemetry",
+        "timestamp",
+        "uuid"
+    )
+    schema["definitions"].update(definitions)
 
     # verify and return
     return common.check_schema(schema)
@@ -164,14 +168,14 @@ def schema_generators():
     }
 
 
-def write_schema_files(common_definitions):
+def write_schema_files():
     """
     Create each of the Agency endpoint schema files in the appropriate directory.
     """
     print("\nStarting to generate Agency JSON Schemas...\n")
 
     for name, generator in schema_generators().items():
-        schema = generator(common_definitions)
+        schema = generator()
         with open(f"../agency/{name}.json", "w") as schemafile:
             schemafile.write(json.dumps(schema, indent=2))
             print(f"Wrote {name}.json")

schema/common.py

@@ -8,6 +8,9 @@
 import requests
 
 
+COMMON_DEFINITIONS = {}
+
+
 def load_json(path):
     """
     Load a JSON file from disk.
@@ -24,11 +27,11 @@ def definition_id(id):
     return f"#/definitions/{id}"
 
 
-def vehicle_definition(common_definitions, provider_name=True, provider_id=True):
+def vehicle_definition(provider_name=True, provider_id=True):
     """
     Extract a deep-copy of the common vehicle model definition to allow for customization.
     """
-    vehicle = copy.deepcopy(common_definitions["vehicle"])
+    vehicle = copy.deepcopy(load_definitions("vehicle"))
 
     if not provider_name:
         vehicle["required"].remove("provider_name")
@@ -41,7 +44,7 @@ def vehicle_definition(common_definitions, provider_name=True, provider_id=True)
     return vehicle
 
 
-def vehicle_state_machine(common_definitions, vehicle_state=None, vehicle_events=None):
+def vehicle_state_machine(vehicle_state=None, vehicle_events=None):
     """
     Return a tuple (definitions, transitions) with the common vehicle state schema.
         * defitions is the common definitions for vehicle state fields
@@ -50,13 +53,8 @@ def vehicle_state_machine(common_definitions, vehicle_state=None, vehicle_events
     Optionally pass field names for the vehicle_state and vehicle_events schemas
     to override those in transitions.
     """
-    state_machine_defs = {
-        "vehicle_state": common_definitions["vehicle_state"],
-        "vehicle_event": common_definitions["vehicle_event"],
-        "vehicle_events": common_definitions["vehicle_events"],
-    }
-
-    transitions = copy.deepcopy(common_definitions["vehicle_state_transitions"])
+    state_machine_defs = load_definitions("vehicle_state", "vehicle_event", "vehicle_events")
+    transitions = copy.deepcopy(load_definitions("vehicle_state_transitions"))
 
     if vehicle_state:
         for option in transitions["oneOf"]:
@@ -73,14 +71,14 @@ def vehicle_state_machine(common_definitions, vehicle_state=None, vehicle_events
     return (state_machine_defs, transitions)
 
 
-def vehicle_type_counts_definition(common_definitions):
+def vehicle_type_counts_definition(definitions=None):
     """
     Generate a definition for a dict of vehicle_type: int.
     """
     vehicle_type_counts = {}
     def_name = "vehicle_type_counts"
     def_id = definition_id(def_name)
-    vehicle_types = common_definitions["vehicle_type"]
+    vehicle_types = definitions["vehicle_type"] if definitions else load_definitions("vehicle_type")
 
     for vehicle_type in vehicle_types["enum"]:
         vehicle_type_counts[vehicle_type] = {
@@ -191,52 +189,67 @@ def mds_feature_point_definition():
     }
 
 
-def stop_definitions(common_definitions):
+def stop_definitions():
     """
     Return a dict of definitions needed for stops.
     """
-    defs = {
-        "stop": common_definitions["stop"],
-        "stop_status": common_definitions["stop_status"],
-        "string": common_definitions["string"],
-        "timestamp": common_definitions["timestamp"],
-        "uuid": common_definitions["uuid"],
-        "vehicle_type_counts": common_definitions["vehicle_type_counts"]
-    }
-    defs.update(mds_feature_point_definition())
+    definitions = load_definitions(
+        "stop",
+        "stop_status",
+        "string",
+        "timestamp",
+        "uuid",
+        "vehicle_type_counts"
+    )
+    definitions.update(mds_feature_point_definition())
 
-    return defs
+    return definitions
 
 
-def property_definition(id, common_definitions, ref=""):
+def property_definition(property_id, ref=""):
     """
     Return a tuple (property, definition) of schema elements for the given id.
     """
     # property ref definition
-    definition = { id: common_definitions.get(id) }
+    definition = { property_id: load_definitions(property_id) }
     # the property
-    ref = ref or definition_id(id)
-    prop = { id: { "$id": f"#/properties/{id}", "$ref": ref } }
+    ref = ref or definition_id(property_id)
+    prop = { property_id: { "$id": f"#/properties/{property_id}", "$ref": ref } }
 
     return prop, definition
 
 
-def load_definitions():
+def load_definitions(*args):
     """
     Load the common.json definitions file, with some generated additions.
+
+    If args are provided, filter to a dictionary of definitions using the args as keys.
+
+    With only a single arg, return just the definition with that key directly.
     """
-    common = load_json("./templates/common.json")
-    common_definitions = common["definitions"]
+    global COMMON_DEFINITIONS
+
+    if COMMON_DEFINITIONS == {}:
+        common = load_json("./templates/common.json")
+        definitions = common["definitions"]
+
+        # MDS specific geography definition
+        mds_feature = mds_feature_point_definition()
+        definitions.update(mds_feature)
 
-    # MDS specific geography definition
-    mds_feature = mds_feature_point_definition()
-    common_definitions.update(mds_feature)
+        # vehicle_type -> count definition
+        veh_type_counts = vehicle_type_counts_definition(definitions)
+        definitions.update(veh_type_counts)
 
-    # vehicle_type -> count definition
-    veh_type_counts = vehicle_type_counts_definition(common_definitions)
-    common_definitions.update(veh_type_counts)
+        COMMON_DEFINITIONS = definitions
 
-    return common_definitions
+    if args and len(args) > 0:
+        if len(args) == 1:
+            return COMMON_DEFINITIONS.get(args[0])
+        else:
+            return { key: COMMON_DEFINITIONS.get(key) for key in args }
+    else:
+        return COMMON_DEFINITIONS
 
 
 def check_schema(schema):