Support bulk subs creation in client and add --bulk to CLI to invoke it #1119

goldenberg · 2025-04-09T22:03:53Z

Related Issue(s):

Closes #

Proposed Changes:

For inclusion in changelog (if applicable):

Adds client.bulk_create_subscriptions() which allows creating multiple subscriptions at once by referencing a feature collection
Adds support for planet subscriptions bulk-create to bulk create using the above mechanism

Not intended for changelog:

Diff of User Interface

Old behavior:

New behavior:
❯ planet subscriptions request-catalog --item-types PSScene --asset-types ortho_visual --geometry pl:features/my/adrian-test-new-guinea-10geojson-xqRXaaZ --start-time 2021-01-01 --end-time 2021-01-05 > catalog_fc_sub_source.json
❯ planet subscriptions request --name "bg test bulk sub" --source catalog_fc_sub_source.json > catalog_fc_sub.json
❯ planet subscriptions create --bulk --hosting sentinel_hub catalog_fc_sub.json

PR Checklist:

This PR is as small and focused as possible
If this PR includes proposed changes for inclusion in the changelog, the title of this PR summarizes those changes and is ready for inclusion in the Changelog.
I have updated docstrings for function changes and docs in the 'docs' folder for user interface / behavior changes
This PR does not break any examples or I have updated them

(Optional) @mentions for Notifications:

goldenberg · 2025-04-09T22:49:56Z

I've now tested this via the CLI by running:

❯ planet subscriptions request-catalog --item-types PSScene --asset-types ortho_visual --geometry pl:features/my/adrian-test-new-guinea-10geojson-xqRXaaZ --start-time 2021-01-01 --end-time 2021-01-05 > catalog_fc_sub_source.json
❯ planet subscriptions request --name "bg test bulk sub" --source catalog_fc_sub_source.json > catalog_fc_sub.json
❯ planet subscriptions create --bulk --hosting sentinel_hub catalog_fc_sub.json

And I believe it works. Needs more testing though

Copilot

Pull Request Overview

This PR adds support for bulk subscription creation to the client and CLI, allowing users to create multiple subscriptions at once using a feature collection reference. Key changes include:

Implementation of the bulk_create_subscriptions method in both the synchronous and asynchronous clients.
Addition of integration tests to verify bulk subscription creation.
Update to the CLI to support the --bulk flag for invoking bulk creation.

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
tests/integration/test_subscriptions_api.py	Adds an integration test for bulk subscription creation.
planet/sync/subscriptions.py	Introduces a synchronous bulk_create_subscriptions method.
planet/clients/subscriptions.py	Adds an asynchronous bulk_create_subscriptions method using POST to /bulk.
planet/cli/subscriptions.py	Adds support for the --bulk option in the subscriptions CLI command.

planet/sync/subscriptions.py

asonnenschein · 2025-04-15T11:45:10Z

planet/cli/subscriptions.py

@@ -151,6 +151,11 @@ async def list_subscriptions_cmd(ctx,

 @subscriptions.command(name="create")  # type: ignore
 @click.argument("request", type=types.JSON())
+@click.option(
+    "--bulk",


I'm split on whether or not the CLI bulk create path should be an optional flag on the standard create argument as you have implemented here (e.g. create --bulk), or if it should be it's own argument (e.g. bulk,
bulk create, bulk_create, create_bulk, etc).

Including an optional --bulk flag on the standard create command implies that the --bulk flag modifies the behavior of the create command. This isn't really the case though because bulk create has it's own API endpoint POST /subscriptions/v1/bulk. Thinking forward, it might be difficult to enhance and/or modify the bulk create path in the CLI if tightly couple it with the standard create path.

Defining the bulk create path as a distinct argument implies that this is a distinct path, separate from the standard create path. Keeping the paths separate should make it easier to enhance and/or modify the bulk create CLI UX without getting wires crossed with the standard create path.

One more thing to think about is that the payloads for the two paths are slightly different. The standard create path expects a single object of subscription criteria, and the bulk create path expects an array of objects that define subscription criteria. I can see supporting two different request data structures for the same create command, and driven by the --bulk flag being a confusing UX.

Having typed this out and thought about it some more, I am leaning more towards the bulk create path having it's own distinct argument on account of the different endpoints and request data structures.

That all makes sense to me! Update to break into a bulk-create subcommand. Let me know how it looks.

LGTM! The distinct bulk-create sub-command on the request argument looks great! Could you also remove the --bulk flag option from the create command?

Oops! Thought I grabbed that but apparently not. Fixed.

tests/integration/test_subscriptions_api.py

asonnenschein · 2025-04-16T12:33:10Z

LGTM! I left one more comment about removing the --bulk flag option from the create command. Also the SDK docs will autogenerate from the docstrings, but the CLI docs will need to be updated manually (https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-subscriptions.md) . Otherwise this PR looks great! I'll hit approve now to unblock you so you can merge after these couple of changes are made.

Copilot

Pull Request Overview

This PR adds support for bulk subscription creation in both the client and CLI while updating the test suites accordingly.

Introduces a new client method bulk_create_subscriptions for both async and sync flows.
Adds a new CLI command "bulk-create" for bulk subscription creation.
Updates tests to validate the new bulk creation functionality.

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/integration/test_subscriptions_cli.py	Added tests for the new CLI bulk create command.
tests/integration/test_subscriptions_api.py	Created async and sync tests for bulk create subscriptions.
planet/sync/subscriptions.py	Added the sync bulk_create_subscriptions method.
planet/clients/subscriptions.py	Added async bulk_create_subscriptions method with API error handling.
planet/cli/subscriptions.py	Introduced a new CLI command for bulk create subscriptions.

Comments suppressed due to low confidence (1)

planet/cli/subscriptions.py:234

[nitpick] For consistency with the client method bulk_create_subscriptions, consider renaming the CLI command function to bulk_create_subscriptions_cmd.

async def bulk_create_subscription_cmd(ctx, request, pretty, **kwargs):

Copilot · 2025-04-16T19:53:57Z

tests/integration/test_subscriptions_api.py

+    resp = pl.subscriptions.bulk_create_subscriptions({
+        'name': 'test', 'delivery': 'yes, please', 'source': 'test'
+    })
+    assert '/subscriptions/v1?' in resp['_links']['list']
+


The synchronous bulk_create_subscriptions method expects a list of dictionaries but is being passed a dictionary. Wrap the dictionary in a list to maintain consistency with the client API.

Suggested change

resp = pl.subscriptions.bulk_create_subscriptions({

'name': 'test', 'delivery': 'yes, please', 'source': 'test'

})

assert '/subscriptions/v1?' in resp['_links']['list']

resp = pl.subscriptions.bulk_create_subscriptions([{

'name': 'test', 'delivery': 'yes, please', 'source': 'test'

}])

Good catch, why didn't the test fail then? Hmm.

…k option on create

asonnenschein · 2025-04-23T12:09:21Z

docs/cli/cli-subscriptions.md

@@ -247,6 +247,49 @@ planet subscriptions patch cb817760-1f07-4ee7-bba6-bcac5346343f \
    patched-attributes.json
 ```

+### Bulk Create Subscriptions


Nice! Thanks for adding the CLI documentation for bulk-create!

goldenberg force-pushed the bg/bulk_subs_dnd_1748 branch 3 times, most recently from dd72894 to ddc9ac7 Compare April 9, 2025 22:43

Support bulk subs creation in client and add --bulk to CLI to invoke it

65d5eac

goldenberg force-pushed the bg/bulk_subs_dnd_1748 branch 4 times, most recently from 5c7111a to d962a6b Compare April 14, 2025 21:45

goldenberg changed the title ~~DRAFT: Support bulk subs creation in client and add --bulk to CLI to invoke it~~ Support bulk subs creation in client and add --bulk to CLI to invoke it Apr 14, 2025

goldenberg requested a review from Copilot April 14, 2025 21:49

Copilot AI reviewed Apr 14, 2025

View reviewed changes

planet/sync/subscriptions.py Show resolved Hide resolved

Update to parse referenced list of subs, and add an integration test

607e62e

goldenberg force-pushed the bg/bulk_subs_dnd_1748 branch from d962a6b to 607e62e Compare April 14, 2025 21:51

asonnenschein reviewed Apr 15, 2025

View reviewed changes

tests/integration/test_subscriptions_api.py Show resolved Hide resolved

goldenberg force-pushed the bg/bulk_subs_dnd_1748 branch from 9a09af2 to 3fcc7aa Compare April 15, 2025 22:31

Add test_bulk_create_subscription_success_sync

79e209d

goldenberg force-pushed the bg/bulk_subs_dnd_1748 branch 3 times, most recently from d6b462d to f1d1602 Compare April 15, 2025 22:51

asonnenschein approved these changes Apr 16, 2025

View reviewed changes

goldenberg requested a review from Copilot April 16, 2025 19:53

Copilot AI reviewed Apr 16, 2025

View reviewed changes

goldenberg added 2 commits April 16, 2025 12:54

Define dedicated subscriptions bulk-create command instead of --bul…

7678ace

…k option on create

Add documentation for new bulk cli command

0ed8e82

goldenberg force-pushed the bg/bulk_subs_dnd_1748 branch from f1d1602 to 0ed8e82 Compare April 16, 2025 23:49

fixup! Add test_bulk_create_subscription_success_sync

8c36027

asonnenschein reviewed Apr 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support bulk subs creation in client and add --bulk to CLI to invoke it #1119

Support bulk subs creation in client and add --bulk to CLI to invoke it #1119

goldenberg commented Apr 9, 2025 •

edited

Loading

goldenberg commented Apr 9, 2025

Copilot AI left a comment

asonnenschein Apr 15, 2025

goldenberg Apr 15, 2025

asonnenschein Apr 16, 2025

goldenberg Apr 16, 2025

asonnenschein commented Apr 16, 2025

Copilot AI left a comment

Copilot AI Apr 16, 2025

goldenberg Apr 16, 2025

asonnenschein Apr 23, 2025

Support bulk subs creation in client and add --bulk to CLI to invoke it #1119

Are you sure you want to change the base?

Support bulk subs creation in client and add --bulk to CLI to invoke it #1119

Conversation

goldenberg commented Apr 9, 2025 • edited Loading

goldenberg commented Apr 9, 2025

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

asonnenschein Apr 15, 2025

Choose a reason for hiding this comment

goldenberg Apr 15, 2025

Choose a reason for hiding this comment

asonnenschein Apr 16, 2025

Choose a reason for hiding this comment

goldenberg Apr 16, 2025

Choose a reason for hiding this comment

asonnenschein commented Apr 16, 2025

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Copilot AI Apr 16, 2025

Choose a reason for hiding this comment

goldenberg Apr 16, 2025

Choose a reason for hiding this comment

asonnenschein Apr 23, 2025

Choose a reason for hiding this comment

goldenberg commented Apr 9, 2025 •

edited

Loading