From 82e5dd1fa39954f14813891060021d66a768691f Mon Sep 17 00:00:00 2001 From: Roel <75250264+RoelBollens-TomTom@users.noreply.github.com> Date: Wed, 15 Jul 2026 16:23:36 +0200 Subject: [PATCH] feature: Refactor enums to use DocumentedEnum for enhanced documentation Signed-off-by: Roel <75250264+RoelBollens-TomTom@users.noreply.github.com> --- .../schema/common/scoping/travel_mode.py | 6 +- .../overture/schema/transportation/enums.py | 82 ++++++++++++------- 2 files changed, 56 insertions(+), 32 deletions(-) diff --git a/packages/overture-schema-common/src/overture/schema/common/scoping/travel_mode.py b/packages/overture-schema-common/src/overture/schema/common/scoping/travel_mode.py index 20c068506..54bcfe025 100644 --- a/packages/overture-schema-common/src/overture/schema/common/scoping/travel_mode.py +++ b/packages/overture-schema-common/src/overture/schema/common/scoping/travel_mode.py @@ -2,17 +2,17 @@ Types supporting the trravel mode scope. """ -from enum import Enum +from overture.schema.system.doc import DocumentedEnum -class TravelMode(str, Enum): +class TravelMode(str, DocumentedEnum): """Enumerates possible travel modes. Some modes represent groups of modes. """ VEHICLE = "vehicle" - MOTOR_VEHICLE = "motor_vehicle" # includes car, truck and motorcycle + MOTOR_VEHICLE = ("motor_vehicle", "Includes car, truck and motorcycle") CAR = "car" TRUCK = "truck" MOTORCYCLE = "motorcycle" diff --git a/packages/overture-schema-transportation-theme/src/overture/schema/transportation/enums.py b/packages/overture-schema-transportation-theme/src/overture/schema/transportation/enums.py index c5cf91720..98c797ff6 100644 --- a/packages/overture-schema-transportation-theme/src/overture/schema/transportation/enums.py +++ b/packages/overture-schema-transportation-theme/src/overture/schema/transportation/enums.py @@ -2,6 +2,8 @@ from enum import Enum +from overture.schema.system.doc import DocumentedEnum + class Subtype(str, Enum): """Transportation segment subtype classification.""" @@ -24,7 +26,7 @@ class DestinationLabelType(str, Enum): UNKNOWN = "unknown" -class RoadClass(str, Enum): +class RoadClass(str, DocumentedEnum): """Captures the kind of road and its position in the road network hierarchy.""" MOTORWAY = "motorway" @@ -32,39 +34,52 @@ class RoadClass(str, Enum): SECONDARY = "secondary" TERTIARY = "tertiary" RESIDENTIAL = "residential" - LIVING_STREET = "living_street" # Similar to residential but has implied legal restriction for motor vehicles (which can vary country by country) + LIVING_STREET = ( + "living_street", + "Similar to residential but has implied legal restriction for motor vehicles (which can vary country by country)", + ) TRUNK = "trunk" - UNCLASSIFIED = "unclassified" # Known roads, paved, but subordinate to all of: motorway, trunk, primary, secondary, tertiary - SERVICE = "service" # Provides vehicle access to a feature (such as a building), typically not part of the public street network + UNCLASSIFIED = ( + "unclassified", + "Known roads, paved, but subordinate to all of: motorway, trunk, primary, secondary, tertiary", + ) + SERVICE = ( + "service", + "Provides vehicle access to a feature (such as a building), typically not part of the public street network", + ) PEDESTRIAN = "pedestrian" - FOOTWAY = "footway" # Minor segments mainly used by pedestrians + FOOTWAY = ("footway", "Minor segments mainly used by pedestrians") STEPS = "steps" PATH = "path" TRACK = "track" CYCLEWAY = "cycleway" - BRIDLEWAY = "bridleway" # Similar to track but has implied access only for horses + BRIDLEWAY = ("bridleway", "Similar to track but has implied access only for horses") UNKNOWN = "unknown" -class RailClass(str, Enum): +class RailClass(str, DocumentedEnum): """Captures the kind of rail segment.""" - FUNICULAR = "funicular" # Inclined plane / cliff railway + FUNICULAR = ("funicular", "Inclined plane / cliff railway") LIGHT_RAIL = ( - "light_rail" # Higher-standard tram system, falls between 'tram' and 'rail' + "light_rail", + "Higher-standard tram system, falls between 'tram' and 'rail'", ) MONORAIL = "monorail" NARROW_GAUGE = "narrow_gauge" STANDARD_GAUGE = ( - "standard_gauge" # Standard-gauge rail, equivalent to OSM's railway=rail tag + "standard_gauge", + "Standard-gauge rail, equivalent to OSM's railway=rail tag", + ) + SUBWAY = ("subway", "City passenger rail, often underground") + TRAM = ( + "tram", + "1-2 carriage rail vehicle tracks, often sharing road with vehicles", ) - SUBWAY = "subway" # City passenger rail, often underground - - TRAM = "tram" # 1-2 carriage rail vehicle tracks, often sharing road with vehicles UNKNOWN = "unknown" -class DestinationSignSymbol(str, Enum): +class DestinationSignSymbol(str, DocumentedEnum): """ Indicates what special symbol/icon is present on a signpost, visible as road marking or similar. @@ -73,7 +88,10 @@ class DestinationSignSymbol(str, Enum): MOTORWAY = "motorway" AIRPORT = "airport" HOSPITAL = "hospital" - CENTER = "center" # center of a locality, city center or downtown, from centre in raw OSM value + CENTER = ( + "center", + "Center of a locality, city center or downtown, from centre in raw OSM value", + ) INDUSTRIAL = "industrial" PARKING = "parking" BUS = "bus" @@ -84,22 +102,25 @@ class DestinationSignSymbol(str, Enum): FUEL = "fuel" VIEWPOINT = "viewpoint" FUEL_DIESEL = "fuel_diesel" - FOOD = "food" # 'food', 'restaurant' in OSM + FOOD = ("food", "'food', 'restaurant' in OSM") LODGING = "lodging" INFO = "info" CAMP_SITE = "camp_site" INTERCHANGE = "interchange" - RESTROOMS = "restrooms" # 'toilets' in OSM + RESTROOMS = ("restrooms", "'toilets' in OSM") -class RoadFlag(str, Enum): +class RoadFlag(str, DocumentedEnum): """Simple flags that can be on or off for a road segment. Specifies physical characteristics and can overlap. """ IS_BRIDGE = "is_bridge" - IS_LINK = "is_link" # Note: `is_link` is deprecated and will be removed in a future release in favor of the link subclass + IS_LINK = ( + "is_link", + "Deprecated: will be removed in a future release in favor of the `link` subclass", + ) IS_TUNNEL = "is_tunnel" IS_UNDER_CONSTRUCTION = "is_under_construction" IS_ABANDONED = "is_abandoned" @@ -107,14 +128,17 @@ class RoadFlag(str, Enum): IS_INDOOR = "is_indoor" -class RailFlag(str, Enum): +class RailFlag(str, DocumentedEnum): """Simple flags that can be on or off for a railway segment. Specifies physical characteristics and can overlap. """ IS_BRIDGE = "is_bridge" - IS_TUNNEL = "is_tunnel" # You may also be looking for the 'subway' class (though subways are occasionally above-ground) + IS_TUNNEL = ( + "is_tunnel", + "Note: You may also be looking for the 'subway' class (though subways are occasionally above-ground)", + ) IS_UNDER_CONSTRUCTION = "is_under_construction" IS_ABANDONED = "is_abandoned" IS_COVERED = "is_covered" @@ -135,16 +159,16 @@ class RoadSurface(str, Enum): METAL = "metal" -class Subclass(str, Enum): +class Subclass(str, DocumentedEnum): """Refines expected usage of the segment, must not overlap.""" - LINK = "link" # Connecting stretch (sliproad or ramp) between two road types - SIDEWALK = "sidewalk" # Footway that lies along a road - CROSSWALK = "crosswalk" # Footway that intersects other roads - PARKING_AISLE = "parking_aisle" # Service road intended for parking - DRIVEWAY = "driveway" # Service road intended for deliveries - ALLEY = "alley" # Service road intended for rear entrances, fire exits - CYCLE_CROSSING = "cycle_crossing" # Cycleway that intersects with other roads + LINK = ("link", "Connecting stretch (sliproad or ramp) between two road types") + SIDEWALK = ("sidewalk", "Footway that lies along a road") + CROSSWALK = ("crosswalk", "Footway that intersects other roads") + PARKING_AISLE = ("parking_aisle", "Service road intended for parking") + DRIVEWAY = ("driveway", "Service road intended for deliveries") + ALLEY = ("alley", "Service road intended for rear entrances, fire exits") + CYCLE_CROSSING = ("cycle_crossing", "Cycleway that intersects with other roads") class AccessType(str, Enum):