[Core-544] Event documentation (#12694)

GitOrigin-RevId: 7304942d62bfeb32da4e63fe375c1e96127fea2c

descarteslabs/core/catalog/__init__.py

@@ -48,13 +48,15 @@
 )
 from .event_api_destination import (
     EventApiDestination,
+    EventApiDestinationCollection,
     EventApiDestinationSearch,
     EventConnectionParameter,
 )
-from .event_rule import EventRule, EventRuleSearch, EventRuleTarget
-from .event_schedule import EventSchedule, EventScheduleSearch
+from .event_rule import EventRule, EventRuleCollection, EventRuleSearch, EventRuleTarget
+from .event_schedule import EventSchedule, EventScheduleCollection, EventScheduleSearch
 from .event_subscription import (
     EventSubscription,
+    EventSubscriptionCollection,
     EventSubscriptionComputeTarget,
     EventSubscriptionSearch,
     EventSubscriptionTarget,
@@ -124,14 +126,18 @@
     "DocumentState",
     "DownloadFileFormat",
     "EventApiDestination",
+    "EventApiDestinationCollection",
     "EventApiDestinationSearch",
     "EventConnectionParameter",
     "EventRule",
+    "EventRuleCollection",
     "EventRuleSearch",
     "EventRuleTarget",
     "EventSchedule",
+    "EventScheduleCollection",
     "EventScheduleSearch",
     "EventSubscription",
+    "EventSubscriptionCollection",
     "EventSubscriptionComputeTarget",
     "EventSubscriptionSearch",
     "EventSubscriptionTarget",

descarteslabs/core/catalog/catalog_base.py

@@ -740,7 +740,6 @@ def search(cls, client=None, request_params=None, headers=None):
         >>> search = Product.search().limit(10) # doctest: +SKIP
         >>> for result in search: # doctest: +SKIP
                 print(result.name) # doctest: +SKIP
-
         """
         return Search(
             cls, client=client, request_params=request_params, headers=headers
@@ -792,38 +791,6 @@ def save(self, request_params=None, headers=None):
         ~descarteslabs.exceptions.ClientError or ~descarteslabs.exceptions.ServerError
             :ref:`Spurious exception <network_exceptions>` that can occur during a
             network request.
-
-        Example
-        -------
-        >>> from descarteslabs.catalog import Product
-        >>> new_product = Product(
-        ...     id="my-product",
-        ...     name="My Product",
-        ...     description="This is a test product"
-        ... )
-        >>> new_product.state
-        <DocumentState.UNSAVED: 'unsaved'>
-        >>> new_product.save() # doctest: +SKIP
-        >>> # ids will be automatically prefixed by the Descartes Labs catalog
-        >>> # with your organization id
-        >>> new_product.id # doctest: +SKIP
-        my_org_id:my-product
-        >>> # Now you can retrieve the product and update it
-        >>> existing_product = Product.get(new_product.id) # doctest: +SKIP
-        >>> existing_product.state # doctest: +SKIP
-        <DocumentState.SAVED: 'saved'>
-        >>> existing_product.name = "My Updated Product" # doctest: +SKIP
-        >>> existing_product.state # doctest: +SKIP
-        <DocumentState.MODIFIED: 'modified'>
-        >>> existing_product.save() # doctest: +SKIP
-        >>> existing_product.state # doctest: +SKIP
-        <DocumentState.SAVED: 'saved'>
-        >>> # After you delete it...
-        >>> existing_product.delete() # doctest: +SKIP
-        True
-        >>> product.state # doctest: +SKIP
-        <DocumentState.DELETED: 'deleted'>
-
         """
         if self.state == DocumentState.SAVED and not request_params:
             # Noop, already saved in the catalog
@@ -872,26 +839,6 @@ def reload(self, request_params=None, headers=None):
         ~descarteslabs.exceptions.ClientError or ~descarteslabs.exceptions.ServerError
             :ref:`Spurious exception <network_exceptions>` that can occur during a
             network request.
-
-        Example
-        -------
-        >>> from descarteslabs.catalog import Product
-        >>> p = Product(id="my_org_id:my_product_id")
-        >>> # Some time elapses and a concurrent change was made
-        >>> p.state # doctest: +SKIP
-        <DocumentState.SAVED: 'saved'>
-        >>> p.reload() # doctest: +SKIP
-        >>> # But once you make changes, you cannot use this method any more
-        >>> p.name = "My name has changed"
-        >>> p.reload() # doctest: +SKIP
-        Traceback (most recent call last):
-          ...
-        ValueError: Product instance with id my_org_id:my_product_id has not been saved
-        >>> # But you can revert
-        >>> p = Product.get(p.id) # doctest: +SKIP
-        >>> p.state # doctest: +SKIP
-        <DocumentState.SAVED: 'saved'>
-
         """
 
         if self.state != DocumentState.SAVED:

descarteslabs/core/catalog/event_api_destination.py

@@ -64,7 +64,7 @@ class EventApiDestinationSearch(Search):
 
 
 class EventApiDestination(CatalogObject):
-    """An EventApiDestination.
+    """An EventBridge API destination.
 
 
     Parameters

descarteslabs/core/catalog/event_rule.py

@@ -135,7 +135,7 @@ class EventRuleSearch(Search):
 
 
 class EventRule(CatalogObject):
-    """An EventRule.
+    """An EventBridge rule to match event subscription targets.
 
 
     Parameters

descarteslabs/core/catalog/event_schedule.py

@@ -37,7 +37,7 @@ class EventScheduleSearch(Search):
 
 
 class EventSchedule(CatalogObject):
-    """An EventSchedule.
+    """A Scheduled Event.
 
 
     Parameters

descarteslabs/core/catalog/event_subscription.py

@@ -116,8 +116,9 @@ def __init__(self, text: str, unquoted=False, raw=False):
         ``{"type": "Polygon", "coordinates": [[[0, 0,], [1, 0], [1, 1], [0, 1], [0, 0]]]}``.
 
         If raw is True, then the text will be rendered by Jinja2 as is, without
-        introducing any additional quotes or substitutions. For example,
-        ``Placeholder('"{{ event.detail.id }}"', raw=True)`` will render as `"some-id"`.
+        introducing any additional quotes or substitutions. Generally this is used
+        when you must explicitly pass through a Jinja2 template expression with
+        substitutions.
 
         In all cases, the final result after all substitions must be a fragment of
         a valid JSON string.
@@ -251,7 +252,7 @@ class EventSubscriptionSearch(GeoSearch):
 
 
 class EventSubscription(CatalogObject):
-    """An EventSubscription.
+    """A Subscription to receive event notifications.
 
 
     Parameters
@@ -633,7 +634,14 @@ class EventSubscriptionCollection(Collection):
 
 
 class ScheduledEventSubscription(EventSubscription):
-    """A convenience class for creating an EventSubscription for a scheduled event."""
+    """A convenience class for creating an EventSubscription for a scheduled event.
+
+    Creates an EventSubscription for a scheduled event. Based on the one or more
+    EventSchedule ids provided to the constructer, the subscription is configured
+    with the correct ``event_source``, ``event_type``, and ``event_namespace``
+    attributes, so that they need not be provided explicitly (indeed if they are
+    explicitly provided, they will be overwritten).
+    """
 
     _derived_type = "scheduled_event_subscription"