From e82c9a53045e80972879db96e28b6f378eb9b0cb Mon Sep 17 00:00:00 2001 From: "gcf-owl-bot[bot]" <78513119+gcf-owl-bot[bot]@users.noreply.github.com> Date: Fri, 20 Jan 2023 15:43:02 -0500 Subject: [PATCH] docs: Add documentation for enums (#103) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: Add documentation for enums fix: Add context manager return types chore: Update gapic-generator-python to v1.8.1 PiperOrigin-RevId: 503210727 Source-Link: https://github.com/googleapis/googleapis/commit/a391fd1dac18dfdfa00c18c8404f2c3a6ff8e98e Source-Link: https://github.com/googleapis/googleapis-gen/commit/0080f830dec37c3384157082bce279e37079ea58 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDA4MGY4MzBkZWMzN2MzMzg0MTU3MDgyYmNlMjc5ZTM3MDc5ZWE1OCJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot --- .../services/fleet_routing/client.py | 2 +- .../optimization_v1/types/async_model.py | 27 ++- .../optimization_v1/types/fleet_routing.py | 154 ++++++++++++++++++ ...metadata_google.cloud.optimization.v1.json | 2 +- 4 files changed, 181 insertions(+), 4 deletions(-) diff --git a/packages/google-cloud-optimization/google/cloud/optimization_v1/services/fleet_routing/client.py b/packages/google-cloud-optimization/google/cloud/optimization_v1/services/fleet_routing/client.py index 91b21d3bd078..87f682562f36 100644 --- a/packages/google-cloud-optimization/google/cloud/optimization_v1/services/fleet_routing/client.py +++ b/packages/google-cloud-optimization/google/cloud/optimization_v1/services/fleet_routing/client.py @@ -656,7 +656,7 @@ def sample_batch_optimize_tours(): # Done; return the response. return response - def __enter__(self): + def __enter__(self) -> "FleetRoutingClient": return self def __exit__(self, type, value, traceback): diff --git a/packages/google-cloud-optimization/google/cloud/optimization_v1/types/async_model.py b/packages/google-cloud-optimization/google/cloud/optimization_v1/types/async_model.py index d5a319b4f2d8..cc6a01439a0d 100644 --- a/packages/google-cloud-optimization/google/cloud/optimization_v1/types/async_model.py +++ b/packages/google-cloud-optimization/google/cloud/optimization_v1/types/async_model.py @@ -34,7 +34,16 @@ class DataFormat(proto.Enum): - r"""Data formats for input and output files.""" + r"""Data formats for input and output files. + + Values: + DATA_FORMAT_UNSPECIFIED (0): + Default value. + JSON (1): + Input data in json format. + STRING (2): + Input data in string format. + """ DATA_FORMAT_UNSPECIFIED = 0 JSON = 1 STRING = 2 @@ -148,7 +157,21 @@ class AsyncModelMetadata(proto.Message): """ class State(proto.Enum): - r"""Possible states of the operation.""" + r"""Possible states of the operation. + + Values: + STATE_UNSPECIFIED (0): + The default value. This value is used if the + state is omitted. + RUNNING (1): + Request is being processed. + SUCCEEDED (2): + The operation completed successfully. + CANCELLED (3): + The operation was cancelled. + FAILED (4): + The operation has failed. + """ STATE_UNSPECIFIED = 0 RUNNING = 1 SUCCEEDED = 2 diff --git a/packages/google-cloud-optimization/google/cloud/optimization_v1/types/fleet_routing.py b/packages/google-cloud-optimization/google/cloud/optimization_v1/types/fleet_routing.py index 638d473ca19e..70b1ab3bf6fc 100644 --- a/packages/google-cloud-optimization/google/cloud/optimization_v1/types/fleet_routing.py +++ b/packages/google-cloud-optimization/google/cloud/optimization_v1/types/fleet_routing.py @@ -288,6 +288,24 @@ class SolvingMode(proto.Enum): ``INVALID_REQUEST`` error. See [max_validation_errors][google.cloud.optimization.v1.OptimizeToursRequest.max_validation_errors] to cap the number of errors returned. + + Values: + DEFAULT_SOLVE (0): + Solve the model. + VALIDATE_ONLY (1): + Only validates the model without solving it: populates as + many + [OptimizeToursResponse.validation_errors][google.cloud.optimization.v1.OptimizeToursResponse.validation_errors] + as possible. + DETECT_SOME_INFEASIBLE_SHIPMENTS (2): + Only populates + [OptimizeToursResponse.skipped_shipments][google.cloud.optimization.v1.OptimizeToursResponse.skipped_shipments], + and doesn't actually solve the rest of the request + (``status`` and ``routes`` are unset in the response). + + *IMPORTANT*: not all infeasible shipments are returned here, + but only the ones that are detected as infeasible as a + preprocessing. """ DEFAULT_SOLVE = 0 VALIDATE_ONLY = 1 @@ -297,6 +315,16 @@ class SearchMode(proto.Enum): r"""Mode defining the behavior of the search, trading off latency versus solution quality. In all modes, the global request deadline is enforced. + + Values: + SEARCH_MODE_UNSPECIFIED (0): + Unspecified search mode, equivalent to ``RETURN_FAST``. + RETURN_FAST (1): + Stop the search after finding the first good + solution. + CONSUME_ALL_AVAILABLE_TIME (2): + Spend all the available time to search for + better solutions. """ SEARCH_MODE_UNSPECIFIED = 0 RETURN_FAST = 1 @@ -1540,6 +1568,25 @@ class ShipmentTypeIncompatibility(proto.Message): class IncompatibilityMode(proto.Enum): r"""Modes defining how the appearance of incompatible shipments are restricted on the same route. + + Values: + INCOMPATIBILITY_MODE_UNSPECIFIED (0): + Unspecified incompatibility mode. This value + should never be used. + NOT_PERFORMED_BY_SAME_VEHICLE (1): + In this mode, two shipments with incompatible + types can never share the same vehicle. + NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY (2): + For two shipments with incompatible types with the + ``NOT_IN_SAME_VEHICLE_SIMULTANEOUSLY`` incompatibility mode: + + - If both are pickups only (no deliveries) or deliveries + only (no pickups), they cannot share the same vehicle at + all. + - If one of the shipments has a delivery and the other a + pickup, the two shipments can share the same vehicle iff + the former shipment is delivered before the latter is + picked up. """ INCOMPATIBILITY_MODE_UNSPECIFIED = 0 NOT_PERFORMED_BY_SAME_VEHICLE = 1 @@ -1580,6 +1627,32 @@ class ShipmentTypeRequirement(proto.Message): class RequirementMode(proto.Enum): r"""Modes defining the appearance of dependent shipments on a route. + + Values: + REQUIREMENT_MODE_UNSPECIFIED (0): + Unspecified requirement mode. This value + should never be used. + PERFORMED_BY_SAME_VEHICLE (1): + In this mode, all "dependent" shipments must + share the same vehicle as at least one of their + "required" shipments. + IN_SAME_VEHICLE_AT_PICKUP_TIME (2): + With the ``IN_SAME_VEHICLE_AT_PICKUP_TIME`` mode, all + "dependent" shipments need to have at least one "required" + shipment on their vehicle at the time of their pickup. + + A "dependent" shipment pickup must therefore have either: + + - A delivery-only "required" shipment delivered on the + route after, or + - A "required" shipment picked up on the route before it, + and if the "required" shipment has a delivery, this + delivery must be performed after the "dependent" + shipment's pickup. + IN_SAME_VEHICLE_AT_DELIVERY_TIME (3): + Same as before, except the "dependent" shipments need to + have a "required" shipment on their vehicle at the time of + their *delivery*. """ REQUIREMENT_MODE_UNSPECIFIED = 0 PERFORMED_BY_SAME_VEHICLE = 1 @@ -1821,6 +1894,13 @@ class TravelMode(proto.Enum): These should be a subset of the Google Maps Platform Routes Preferred API travel modes, see: https://developers.google.com/maps/documentation/routes_preferred/reference/rest/Shared.Types/RouteTravelMode. + + Values: + TRAVEL_MODE_UNSPECIFIED (0): + Unspecified travel mode, equivalent to ``DRIVING``. + DRIVING (1): + Travel mode corresponding to driving + directions (car, ...). """ TRAVEL_MODE_UNSPECIFIED = 0 DRIVING = 1 @@ -1831,6 +1911,17 @@ class UnloadingPolicy(proto.Enum): Other shipments are free to occur anywhere on the route independent of ``unloading_policy``. + + Values: + UNLOADING_POLICY_UNSPECIFIED (0): + Unspecified unloading policy; deliveries must + just occur after their corresponding pickups. + LAST_IN_FIRST_OUT (1): + Deliveries must occur in reverse order of + pickups + FIRST_IN_FIRST_OUT (2): + Deliveries must occur in the same order as + pickups """ UNLOADING_POLICY_UNSPECIFIED = 0 LAST_IN_FIRST_OUT = 1 @@ -3410,6 +3501,47 @@ class Code(proto.Enum): meaningless. In particular, it gives no indication of whether a given reason will appear before another in the solution, if both apply. + + Values: + CODE_UNSPECIFIED (0): + This should never be used. If we are unable + to understand why a shipment was skipped, we + simply return an empty set of reasons. + NO_VEHICLE (1): + There is no vehicle in the model making all + shipments infeasible. + DEMAND_EXCEEDS_VEHICLE_CAPACITY (2): + The demand of the shipment exceeds a vehicle's capacity for + some capacity types, one of which is + ``example_exceeded_capacity_type``. + CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DISTANCE_LIMIT (3): + The minimum distance necessary to perform this shipment, + i.e. from the vehicle's ``start_location`` to the shipment's + pickup and/or delivery locations and to the vehicle's end + location exceeds the vehicle's ``route_distance_limit``. + + Note that for this computation we use the geodesic + distances. + CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DURATION_LIMIT (4): + The minimum time necessary to perform this shipment, + including travel time, wait time and service time exceeds + the vehicle's ``route_duration_limit``. + + Note: travel time is computed in the best-case scenario, + namely as geodesic distance x 36 m/s (roughly 130 km/hour). + CANNOT_BE_PERFORMED_WITHIN_VEHICLE_TRAVEL_DURATION_LIMIT (5): + Same as above but we only compare minimum travel time and + the vehicle's ``travel_duration_limit``. + CANNOT_BE_PERFORMED_WITHIN_VEHICLE_TIME_WINDOWS (6): + The vehicle cannot perform this shipment in the best-case + scenario (see + ``CANNOT_BE_PERFORMED_WITHIN_VEHICLE_DURATION_LIMIT`` for + time computation) if it starts at its earliest start time: + the total time would make the vehicle end after its latest + end time. + VEHICLE_NOT_ALLOWED (7): + The ``allowed_vehicle_indices`` field of the shipment is not + empty and this vehicle does not belong to it. """ CODE_UNSPECIFIED = 0 NO_VEHICLE = 1 @@ -3672,6 +3804,28 @@ class Level(proto.Enum): the threshold conditions. The enumeration below is in order of increasing relaxation. + + Values: + LEVEL_UNSPECIFIED (0): + Implicit default relaxation level: no constraints are + relaxed, i.e., all visits are fully constrained. + + This value must not be explicly used in ``level``. + RELAX_VISIT_TIMES_AFTER_THRESHOLD (1): + Visit start times and vehicle start/end times + will be relaxed, but each visit remains bound to + the same vehicle and the visit sequence must be + observed: no visit can be inserted between them + or before them. + RELAX_VISIT_TIMES_AND_SEQUENCE_AFTER_THRESHOLD (2): + Same as ``RELAX_VISIT_TIMES_AFTER_THRESHOLD``, but the visit + sequence is also relaxed: visits remain simply bound to + their vehicle. + RELAX_ALL_AFTER_THRESHOLD (3): + Same as ``RELAX_VISIT_TIMES_AND_SEQUENCE_AFTER_THRESHOLD``, + but the vehicle is also relaxed: visits are completely free + at or after the threshold time and can potentially become + unperformed. """ LEVEL_UNSPECIFIED = 0 RELAX_VISIT_TIMES_AFTER_THRESHOLD = 1 diff --git a/packages/google-cloud-optimization/samples/generated_samples/snippet_metadata_google.cloud.optimization.v1.json b/packages/google-cloud-optimization/samples/generated_samples/snippet_metadata_google.cloud.optimization.v1.json index d57cc00108f2..d38082dbd11f 100644 --- a/packages/google-cloud-optimization/samples/generated_samples/snippet_metadata_google.cloud.optimization.v1.json +++ b/packages/google-cloud-optimization/samples/generated_samples/snippet_metadata_google.cloud.optimization.v1.json @@ -8,7 +8,7 @@ ], "language": "PYTHON", "name": "google-cloud-optimization", - "version": "1.3.0" + "version": "0.1.0" }, "snippets": [ {