Skip to content

Commit 27591b4

Browse files
committed
Adding descriptions and standardizing docstring comments
1 parent e8dcde5 commit 27591b4

16 files changed

+587
-133
lines changed

wzdx/models/feed_info/feed_data_source.py

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,39 @@
22
from datetime import datetime
33
from pydantic import BaseModel, Field
44

5+
56
class FeedDataSource(BaseModel):
6-
"""WZDx feed data source"""
7-
data_source_id: str = Field(alias="data_source_id")
8-
organization_name: str = Field(None, alias="organization_name")
9-
update_date: Optional[datetime] = Field(None, alias="update_date")
10-
update_frequency: Optional[int] = Field(None, alias="update_frequency")
11-
contact_name: Optional[str] = Field(None, alias="contact_name")
12-
contact_email: Optional[str] = Field(None, alias="contact_email")
7+
"""
8+
The FeedDataSource object describes information about a specific data source used to build a data feed. A WZDx feed must contain at least one FeedDataSource, included as an entry in the data_sources array of the FeedInfo object.
9+
10+
Documentation: https://github.com/usdot-jpo-ode/wzdx/blob/develop/spec-content/objects/FeedDataSource.md
11+
"""
12+
13+
data_source_id: str = Field(
14+
alias="data_source_id",
15+
description="A unique identifier for the data source organization providing work zone data. It is recommended that this identifier is a Universally Unique IDentifier (UUID) as defined in RFC 4122 to guarantee uniqueness between feeds and over time.",
16+
)
17+
organization_name: str = Field(
18+
alias="organization_name",
19+
description="The name of the organization for the authoritative source of the work zone data.",
20+
)
21+
update_date: Optional[datetime] = Field(
22+
default=None,
23+
alias="update_date",
24+
description="The UTC date and time when the data source was last updated.",
25+
)
26+
update_frequency: Optional[int] = Field(
27+
default=None,
28+
alias="update_frequency",
29+
description="The frequency in seconds at which the data source is updated.",
30+
)
31+
contact_name: Optional[str] = Field(
32+
default=None,
33+
alias="contact_name",
34+
description="The name of the individual or group responsible for the data source.",
35+
)
36+
contact_email: Optional[str] = Field(
37+
default=None,
38+
alias="contact_email",
39+
description="The email address of the individual or group responsible for the data source.",
40+
)

wzdx/models/feed_info/feed_info.py

Lines changed: 40 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,44 @@
66

77
class FeedInfo(BaseModel):
88
"""
9-
WZDx feed info metadata.
10-
11-
See: https://github.com/usdot-jpo-ode/wzdx/blob/develop/spec-content/objects/FeedInfo.md
9+
The FeedInfo object describes WZDx feed header information such as metadata, contact information, and data sources. There is one FeedInfo per WZDx GeoJSON document.
10+
11+
Documentation: https://github.com/usdot-jpo-ode/wzdx/blob/develop/spec-content/objects/FeedInfo.md
1212
"""
13-
publisher: str = None
14-
version: str = None
15-
license: Optional[str] = None
16-
data_sources: list[FeedDataSource] = Field(None, alias="data_sources")
17-
update_date: datetime = Field(None, alias="update_date")
18-
update_frequency: Optional[int] = Field(None, alias="update_frequency")
19-
contact_name: Optional[str] = Field(None, alias="contact_name")
20-
contact_email: Optional[EmailStr] = Field(None, alias="contact_email")
13+
14+
publisher: str = Field(
15+
alias="publisher",
16+
description="The organization responsible for publishing the feed.",
17+
)
18+
version: str = Field(
19+
alias="version",
20+
description="The WZDx specification version used to create the data feed in major.minor format. Note this mandates that all data in a WZDx feed complies to a single version of WZDx.",
21+
)
22+
license: Optional[str] = Field(
23+
default=None,
24+
alias="license",
25+
description='The URL of the license that applies to the data in the WZDx feed. This must be the string "https://creativecommons.org/publicdomain/zero/1.0/"',
26+
)
27+
data_sources: list[FeedDataSource] = Field(
28+
alias="data_sources",
29+
description="A list of specific data sources for the road event data in the feed.",
30+
)
31+
update_date: datetime = Field(
32+
alias="update_date",
33+
description="The UTC date and time when the GeoJSON file (representing the instance of the feed) was generated.",
34+
)
35+
update_frequency: Optional[int] = Field(
36+
default=None,
37+
alias="update_frequency",
38+
description="The frequency in seconds at which the data feed is updated.",
39+
)
40+
contact_name: Optional[str] = Field(
41+
default=None,
42+
alias="contact_name",
43+
description="The name of the individual or group responsible for the data feed.",
44+
)
45+
contact_email: Optional[EmailStr] = Field(
46+
default=None,
47+
alias="contact_email",
48+
description="The email address of the individual or group responsible for the data feed.",
49+
)

wzdx/models/field_device_feed/device_feed.py

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,26 @@
77

88

99
class DeviceFeed(BaseModel):
10-
feed_info: FeedInfo = Field(alias="feed_info")
11-
type: str
12-
features: list[FieldDeviceFeature]
13-
bbox: Optional[list[float]] = None
10+
"""
11+
The DeviceFeed object is the root (highest level) object of a WZDx Device Feed. There is one DeviceFeed object per feed GeoJSON document. The DeviceFeed is a [GeoJSON FeatureCollection](https://datatracker.ietf.org/doc/html/rfc7946#section-3.3) object.
12+
13+
The DeviceFeed contains information (location, status, live data) about field devices deployed on the roadway in work zones.
14+
15+
Documentation: https://github.com/usdot-jpo-ode/wzdx/blob/develop/spec-content/objects/DeviceFeed.md
16+
"""
17+
18+
feed_info: FeedInfo = Field(
19+
alias="feed_info", description="Information about the data feed."
20+
)
21+
type: str = Field(
22+
alias="type",
23+
description="The GeoJSON object type. For WZDx, this must be the string FeatureCollection.",
24+
)
25+
features: list[FieldDeviceFeature] = Field(
26+
alias="features",
27+
description="An array of GeoJSON [Feature](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2) objects which each represent a field device deployed in a work zone.",
28+
)
29+
bbox: Optional[list[float]] = Field(
30+
default=None,
31+
description="Information on the coordinate range for all FieldDeviceFeatures in the feed. The value must be an array of length 2n where n is the number of dimensions represented in the contained geometries, with all axes of the most southwesterly point followed by all axes of the more northeasterly point. The axes order of a bbox follows the axes order of geometries.",
32+
)

wzdx/models/field_device_feed/field_device_core_details.py

Lines changed: 82 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,85 @@
88

99

1010
class FieldDeviceCoreDetails(BaseModel):
11-
device_type: FieldDeviceType = Field(alias="device_type")
12-
data_source_id: str = Field(alias="data_source_id")
13-
device_status: FieldDeviceStatus = Field(alias="device_status")
14-
update_date: datetime = Field(alias="update_date")
15-
has_automatic_location: bool = Field(alias="has_automatic_location")
16-
road_direction: Optional[Direction] = Field(None, alias="road_direction")
17-
road_names: Optional[list[str]] = Field(None, alias="road_names")
18-
name: Optional[str] = Field(None, alias="name")
19-
description: Optional[str] = Field(None, alias="description")
20-
status_messages: Optional[list[str]] = Field(None, alias="status_messages")
21-
is_moving: Optional[bool] = Field(None, alias="is_moving")
22-
road_event_ids: Optional[list[str]] = Field(None, alias="road_event_ids")
23-
milepost: Optional[float] = Field(None, alias="milepost")
24-
make: Optional[str] = Field(None, alias="make")
25-
model: Optional[str] = Field(None, alias="model")
26-
serial_number: Optional[str] = Field(None, alias="serial_number")
27-
firmware_version: Optional[str] = Field(None, alias="firmware_version")
28-
velocity_kph: Optional[float] = Field(None, alias="velocity_kph")
11+
"""
12+
The FieldDeviceCoreDetails object represents the core details—both configuration and current state—of a field device that are shared by all types of field devices.
13+
The FieldDeviceCoreDetails object cannot occur directly in a data feed and does not represent a field device on its own. It is used as the value of the core_details
14+
property on every specific type of field device, each represented by its own object.
15+
16+
Documentation: https://github.com/usdot-jpo-ode/wzdx/blob/develop/spec-content/objects/FieldDeviceCoreDetails.md
17+
"""
18+
19+
device_type: FieldDeviceType = Field(
20+
alias="device_type", description="The type of field device."
21+
)
22+
data_source_id: str = Field(
23+
alias="data_source_id",
24+
description="Identifies the data source from which the field device data originates.",
25+
)
26+
device_status: FieldDeviceStatus = Field(
27+
alias="device_status",
28+
description="The operational status of the field device. The value of this property indicates if the device is ok or in an error or warning state.",
29+
)
30+
update_date: datetime = Field(
31+
alias="update_date",
32+
description="The UTC time and date when the field device information was updated.",
33+
)
34+
has_automatic_location: bool = Field(
35+
alias="has_automatic_location",
36+
description="A yes/no value indicating if the field device location (parent FieldDeviceFeature's geometry) is determined automatically from an onboard GPS (true) or manually set/overridden (false).",
37+
)
38+
road_direction: Optional[Direction] = Field(
39+
None,
40+
alias="road_direction",
41+
description="The direction of the road that the field device is on. This value indicates the direction of the traffic flow of the road, not a real heading angle.",
42+
)
43+
road_names: Optional[list[str]] = Field(
44+
None,
45+
alias="road_names",
46+
description="A list of publicly known names of the road on which the device is located. This may include the road number designated by a jurisdiction such as a county, state or interstate (e.g. I-5, VT 133).",
47+
)
48+
name: Optional[str] = Field(
49+
None, alias="name", description="A human-readable name for the field device."
50+
)
51+
description: Optional[str] = Field(
52+
None, alias="description", description="A description of the field device."
53+
)
54+
status_messages: Optional[list[str]] = Field(
55+
None,
56+
alias="status_messages",
57+
description="A list of messages associated with the device's status, if applicable. Used to provide additional information about the status such as specific warning or error messages.",
58+
)
59+
is_moving: Optional[bool] = Field(
60+
None,
61+
alias="is_moving",
62+
description="A yes/no value indicating if the device is actively moving (not statically placed) as part of a mobile work zone operation.",
63+
)
64+
road_event_ids: Optional[list[str]] = Field(
65+
None,
66+
alias="road_event_ids",
67+
description="A list of one or more IDs of a RoadEventFeature that the device is associated with.",
68+
)
69+
milepost: Optional[float] = Field(
70+
None,
71+
alias="milepost",
72+
description="The linear distance measured against a milepost marker along a roadway where the device is located.",
73+
)
74+
make: Optional[str] = Field(
75+
None, alias="make", description="The make or manufacturer of the device."
76+
)
77+
model: Optional[str] = Field(
78+
None, alias="model", description="The model of the device."
79+
)
80+
serial_number: Optional[str] = Field(
81+
None, alias="serial_number", description="The serial number of the device."
82+
)
83+
firmware_version: Optional[str] = Field(
84+
None,
85+
alias="firmware_version",
86+
description="The version of firmware the device is using to operate.",
87+
)
88+
velocity_kph: Optional[float] = Field(
89+
None,
90+
alias="velocity_kph",
91+
description="The velocity of the device in kilometers per hour.",
92+
)
Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,37 @@
11
from typing import Optional
2-
from pydantic import BaseModel
2+
from pydantic import BaseModel, Field
33

44
from ..geometry.geojson_geometry import GeoJsonGeometry
55
from .properties.field_device_properties import FieldDeviceProperties
66

77

88
class FieldDeviceFeature(BaseModel):
9-
id: str
10-
type: str
11-
properties: FieldDeviceProperties
12-
geometry: GeoJsonGeometry
13-
bbox: Optional[list[float]] = None
9+
"""
10+
The FieldDeviceFeature object is a GeoJSON Feature representing a deployed field device. This object contains the specific details of the field device, similar to how the RoadEventFeature object in a WZDx Feed contains the road event object (WorkZoneRoadEvent or DetourRoadEvent.
11+
12+
Currently, only point devices are supported.
13+
14+
Documentation: https://github.com/usdot-jpo-ode/wzdx/blob/develop/spec-content/objects/FieldDeviceFeature.md
15+
"""
16+
17+
id: str = Field(
18+
alias="id",
19+
description="A unique identifier issued by the data feed provider to identify the field device. It is recommended that this identifier is a Universally Unique IDentifier (UUID) as defined in RFC 4122 to guarantee uniqueness between feeds and over time.",
20+
)
21+
type: str = Field(
22+
alias="type",
23+
description="The GeoJSON object type. This MUST be the string Feature.",
24+
)
25+
properties: FieldDeviceProperties = Field(
26+
alias="properties",
27+
description="The specific details of the field device.",
28+
)
29+
geometry: GeoJsonGeometry = Field(
30+
alias="geometry",
31+
description="The geometry of the field device, indicating its location. The Geometry object's type property MUST be Point.",
32+
)
33+
bbox: Optional[list[float]] = Field(
34+
default=None,
35+
alias="bbox",
36+
description="Information on the coordinate range for this field device. Must be an array of length 2n where n is the number of dimensions represented in the geometry property, with all axes of the most southwesterly point followed by all axes of the more northeasterly point. The axes order of a bbox follows the axes order of the geometry.",
37+
)
Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
11
from enum import Enum
22

3+
34
class FieldDeviceStatus(str, Enum):
4-
ERROR = "error"
5-
OK = "ok"
6-
UNKNOWN = "unknown"
7-
WARNING = "warning"
5+
"""
6+
The FieldDeviceStatus enumerated type describes the operational status of a field device. The status indicates the health of the device.
7+
8+
Documentation: https://github.com/usdot-jpo-ode/wzdx/blob/develop/spec-content/enumerated-types/FieldDeviceStatus.md
9+
"""
10+
11+
OK = "ok" # The device is turned on and working without issue.
12+
WARNING = "warning" # The device is functional but is impaired or impacted in a way that is not critical to operation.
13+
ERROR = "error" # The device is impaired such that it is not able to perform one or more necessary functions.
14+
UNKNOWN = "unknown" # The device's operational status is not known.

wzdx/models/field_device_feed/field_device_type.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
from typing_extensions import Literal
22

3+
"""
4+
The FieldDeviceType enumerated type enumerates all types of field devices described by the specification.
5+
6+
Documentation: https://github.com/usdot-jpo-ode/wzdx/blob/develop/spec-content/enumerated-types/FieldDeviceType.md
7+
"""
38
FieldDeviceType = Literal[
49
"arrow-board",
510
"camera",

0 commit comments

Comments
 (0)