docs: Add documentation for enums (#103)

* 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: googleapis/googleapis@a391fd1

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 <gcf-owl-bot[bot]@users.noreply.github.com>

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):

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

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

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": [
     {