Merge pull request #983 from planetlabs/issue933

Add more doc help

Author: sgillies

planet/cli/subscriptions.py

@@ -168,7 +168,7 @@ async def get_subscription_cmd(ctx, subscription_id, pretty):
               'csv_flag',
               is_flag=True,
               default=False,
-              help="Get subscription results as an unpaged CSV file.")
+              help="Get subscription results as comma-separated fields.")
 @limit
 # TODO: the following 3 options.
 # –created: timestamp instant or range.
@@ -183,7 +183,26 @@ async def list_subscription_results_cmd(ctx,
                                         status,
                                         csv_flag,
                                         limit):
-    """Gets results of a subscription and prints the API response."""
+    """Print the results of a subscription to stdout.
+
+    The output of this command is a sequence of JSON objects (the
+    default) or a sequence of comma-separated fields (when the --csv
+    option is used), one result per line.
+
+    Examples:
+
+    \b
+        planet subscriptions results SUBSCRIPTION_ID --status=success --limit 10
+
+    Where SUBSCRIPTION_ID is the unique identifier for a subscription,
+    this prints the last 10 successfully delivered results for that
+    subscription as JSON objects.
+
+    \b
+        planet subscriptions results SUBSCRIPTION_ID --limit 0 --csv > results.csv
+
+    Prints all results for a subscription and saves them to a CSV file.
+    """
     async with subscriptions_client(ctx) as client:
         if csv_flag:
             async for result in client.get_results_csv(subscription_id,

planet/clients/subscriptions.py

@@ -268,22 +268,18 @@ class _ResultsPager(Paged):
         except ClientError:  # pragma: no cover
             raise
 
-    async def get_results_csv(self,
-                              subscription_id: str,
-                              status: Optional[Sequence[Literal[
-                                  "created",
-                                  "queued",
-                                  "processing",
-                                  "failed",
-                                  "success"]]] = None,
-                              **kwargs) -> AsyncIterator[str]:
+    async def get_results_csv(
+        self,
+        subscription_id: str,
+        status: Optional[Sequence[Literal["created",
+                                          "queued",
+                                          "processing",
+                                          "failed",
+                                          "success"]]] = None,
+        limit: int = 100,
+    ) -> AsyncIterator[str]:
         """Iterate over rows of results CSV for a Subscription.
 
-        Notes:
-            The name of this method is based on the API's method name. This
-            method provides iteration over results, it does not get a
-            single result description or return a list of descriptions.
-
         Parameters:
             subscription_id (str): id of a subscription.
             status (Set[str]): pass result with status in this set,