python: use imperative style for railjson_generator docstrings (PEP257)

python/railjson_generator/railjson_generator/external_generated_inputs.py

@@ -15,11 +15,11 @@ class ElectricalProfile:
     track_ranges: List[TrackRange] = field(default_factory=list)
 
     def add_track_range(self, track: TrackSection, begin: float, end: float):
-        """Builds a track range and adds it to the profile."""
+        """Build a track range and add it to the profile."""
         self.track_ranges.append(TrackRange(track=track, begin=begin, end=end))
 
     def to_rjs(self):
-        """Returns the corresponding railjson object."""
+        """Return the corresponding railjson object."""
         return external_generated_inputs.ElectricalProfile(
             value=self.value,
             power_class=self.power_class,
@@ -32,17 +32,17 @@ class ExternalGeneratedInputs:
     electrical_profiles: List[ElectricalProfile] = field(default_factory=list)
 
     def add_electrical_profile(self, *args, **kwargs) -> ElectricalProfile:
-        """Builds an electrical profile, adds it to the inputs, and returns it."""
+        """Build an electrical profile, add it to the inputs, and return it."""
         self.electrical_profiles.append(ElectricalProfile(*args, **kwargs))
         return self.electrical_profiles[-1]
 
     def save(self, path: PathLike):
-        """Writes to the path as railjson."""
+        """Write to the path as railjson."""
         with open(path, "w") as f:
             f.write(self.to_rjs().model_dump_json(indent=2))
 
     def to_rjs(self):
-        """Returns the corresponding railjson `ElectricalProfileSet`."""
+        """Return the corresponding railjson `ElectricalProfileSet`."""
         return external_generated_inputs.ElectricalProfileSet(
             levels=[profile.to_rjs() for profile in self.electrical_profiles],
             level_order={

python/railjson_generator/railjson_generator/infra_builder.py

@@ -39,7 +39,7 @@ def _check_connections(endpoint: TrackEndpoint, connections: Iterable[Tuple[Trac
 
 
 def _register_connection(endpoint_a: TrackEndpoint, endpoint_b: TrackEndpoint, switch_group: SwitchGroup):
-    """Connect two track endpoints together"""
+    """Connect two track endpoints together."""
     a_neighbors = endpoint_a.get_neighbors()
     b_neighbors = endpoint_b.get_neighbors()
     a_neighbors.append((endpoint_b, switch_group))
@@ -57,13 +57,13 @@ class InfraBuilder:
     infra: Infra = field(default_factory=Infra)
 
     def add_track_section(self, *args, **kwargs) -> TrackSection:
-        """Builds a track section, adds it to the infra, and returns it."""
+        """Build a track section, add it to the infra, and return it."""
         track = TrackSection(index=len(self.infra.track_sections), *args, **kwargs)
         self.infra.track_sections.append(track)
         return track
 
     def add_point_switch(self, base: TrackEndpoint, left: TrackEndpoint, right: TrackEndpoint, **kwargs) -> PointSwitch:
-        """Builds a point switch, adds it to the infra, and returns it."""
+        """Build a point switch, add it to the infra, and return it."""
         switch = PointSwitch(A=base, B1=left, B2=right, **kwargs)
         _register_connection(base, left, switch.group("A_B1"))
         _register_connection(base, right, switch.group("A_B2"))
@@ -73,7 +73,7 @@ def add_point_switch(self, base: TrackEndpoint, left: TrackEndpoint, right: Trac
     def add_crossing(
         self, north: TrackEndpoint, south: TrackEndpoint, east: TrackEndpoint, west: TrackEndpoint, **kwargs
     ) -> Crossing:
-        """Builds a crossing, adds it to the infra, and returns it."""
+        """Build a crossing, add it to the infra, and return it."""
         switch = Crossing(A1=north, B1=south, B2=east, A2=west, **kwargs)
         _register_connection(north, south, switch.group("STATIC"))
         _register_connection(east, west, switch.group("STATIC"))
@@ -83,7 +83,7 @@ def add_crossing(
     def add_double_slip_switch(
         self, north_1: TrackEndpoint, north_2: TrackEndpoint, south_1: TrackEndpoint, south_2: TrackEndpoint, **kwargs
     ) -> DoubleSlipSwitch:
-        """Builds a double slip switch, adds it to the infra, and returns it."""
+        """Build a double slip switch, add it to the infra, and return it."""
         switch = DoubleSlipSwitch(A1=north_1, A2=north_2, B1=south_1, B2=south_2, **kwargs)
         for (src, dst), group_name in [
             ((north_1, south_1), "A1_B1"),
@@ -96,24 +96,24 @@ def add_double_slip_switch(
         return switch
 
     def add_link(self, source: TrackEndpoint, destination: TrackEndpoint, **kwargs) -> Link:
-        """Builds a link, adds it to the infra, and returns it."""
+        """Build a link, add it to the infra, and return it."""
         switch = Link(A=source, B=destination, **kwargs)
         self.infra.switches.append(switch)
         _register_connection(source, destination, switch.group("STATIC"))
         return switch
 
     def add_operational_point(self, *args, **kwargs) -> OperationalPoint:
-        """Builds an operational point, adds it to the infra, and returns it."""
+        """Build an operational point, add it to the infra, and return it."""
         self.infra.operational_points.append(OperationalPoint(*args, **kwargs))
         return self.infra.operational_points[-1]
 
     def add_speed_section(self, *args, **kwargs) -> SpeedSection:
-        """Builds a speed section, adds it to the infra, and returns it."""
+        """Build a speed section, add it to the infra, and return it."""
         self.infra.speed_sections.append(SpeedSection(*args, **kwargs))
         return self.infra.speed_sections[-1]
 
     def add_neutral_section(self, *args, **kwargs) -> NeutralSection:
-        """Builds a neutral section, adds it to the infra, and returns it."""
+        """Build a neutral section, add it to the infra, and return it."""
         self.infra.neutral_sections.append(NeutralSection(*args, **kwargs))
         return self.infra.neutral_sections[-1]
 
@@ -127,7 +127,7 @@ def _auto_gen_buffer_stops(self):
                 track.add_buffer_stop(position=track.length)
 
     def register_route(self, route: Route):
-        """Adds a route to the infrastructure"""
+        """Add a route to the infrastructure."""
         self.infra.routes.append(route)
 
     def _prepare_infra(self):
@@ -142,7 +142,7 @@ def _prepare_infra(self):
     def generate_routes(self, progressive_release: bool = True) -> Iterable[Route]:
         """
         Generate routes using signaling and detectors.
-        Route need to be manually registered using register_route.
+        Routes need to be manually registered using register_route.
         Buffer stops will be added where missing.
 
         Keyword arguments:

python/railjson_generator/railjson_generator/schema/location.py

@@ -11,7 +11,7 @@ class Location:
     offset: float
 
     def format(self) -> Dict[str, Any]:
-        """Returns a summary of the location as a dictionary."""
+        """Return a summary of the location as a dictionary."""
         return {
             "track_section": self.track_section.label,
             "offset": self.offset,
@@ -23,13 +23,13 @@ class DirectedLocation(Location):
     direction: Direction
 
     def format(self) -> Dict[str, Any]:
-        """Returns a summary of the directed location as a dictionary."""
+        """Return a summary of the directed location as a dictionary."""
         return {
             **super().format(),
             "direction": self.direction.name,
         }
 
     @staticmethod
     def from_location(location: Location, direction: Direction) -> "DirectedLocation":
-        """Returns a directed location with the given direction."""
+        """Return a directed location with the given direction."""
         return DirectedLocation(location.track_section, location.offset, direction)

python/railjson_generator/railjson_generator/simulation_builder.py

@@ -15,15 +15,15 @@ class SimulationBuilder:
     simulation: Simulation = field(default_factory=Simulation)
 
     def add_train_schedule(self, *locations: Location, **kwargs) -> TrainSchedule:
-        """Creates a train schedule group containing only this train schedule."""
+        """Create a train schedule group containing only this train schedule."""
         train_schedule = TrainSchedule(**kwargs)
         self.add_train_schedule_group(locations, train_schedule)
         return train_schedule
 
     def add_train_schedule_group(
         self, locations: Sequence[Union[Location, DirectedLocation]], *train_schedules: TrainSchedule
     ) -> TrainScheduleGroup:
-        """Creates a train schedule group containing the given train schedules.
+        """Create a train schedule group containing the given train schedules.
 
         Simple locations are expanded to directed locations in all directions."""
         if len(locations) < 2:
@@ -39,5 +39,5 @@ def add_train_schedule_group(
         return train_schedule_group
 
     def build(self) -> Simulation:
-        """Returns the simulation object."""
+        """Return the simulation object."""
         return self.simulation

python/railjson_generator/railjson_generator/utils/routes_generator.py

@@ -16,7 +16,7 @@
 
 
 def follow_track_link(connections: List[Tuple[TrackEndpoint, Optional[SwitchGroup]]]) -> Optional[TrackEndpoint]:
-    """Follow a track link. If there is no track link on this endpoint, returns None"""
+    """Follow a track link. If there is no track link on this endpoint, return None."""
     if not connections:
         return None
     (endpoint, switch_group) = connections[0]
@@ -28,7 +28,7 @@ def follow_track_link(connections: List[Tuple[TrackEndpoint, Optional[SwitchGrou
 def _explore_signals(
     track: TrackSection, det_i: Optional[int], signal_direction: Direction
 ) -> Iterable[Tuple[TrackSection, Signal]]:
-    """Find signals which are associated with a given detector"""
+    """Find signals which are associated with a given detector."""
     signal_iterator = reversed(track.signals) if signal_direction == Direction.START_TO_STOP else iter(track.signals)
 
     pos_filter: Callable[[float], bool]
@@ -155,7 +155,7 @@ def build(self, entry_det: Waypoint, entry_dir: Direction, exit_det: Waypoint, e
 
 
 def search_zone_paths(infra: Infra) -> List[ZonePath]:
-    """Enumerate all possible paths inside zones"""
+    """Enumerate all possible paths inside zones."""
 
     res = []
     for track in infra.track_sections: