diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8aded047..fdba2711 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,10 +19,12 @@ insofar as is practical within the scope of changes targeted to the next major r versioning, major releases do not guarantee backwards compatibility. Stability is not guaranteed during the development cycle. -During the development cycle of a new major release, `RELEASE-PLANNING-X.0.md` should be maintained -with a brief summary of the major and breaking changes underpinning the reason for the upcoming -major release version. Upon release, this content is expected to be folded into package documentation -as appropriate, and this file should be removed. +During the development cycle of a new major release, a GitHub Project and Milestone should be +created to track changes targeted the release. A file such as `RELEASE-PLANNING-X.0.md` in the +root of the source tree may be used for early development prior to the creation of a GitHub +project, but should be retired when a new release becomes more formalized. Upon release, +all content is expected to be folded into package documentation as appropriate (announcements, +company blog posts, changelogs, migration guides, etc.). When a new major release is ready, the development mainline branch will be renamed to `main`, and the old mainline branch will be renamed to `maint-X.0` and will be used as the base for maintenance releases. diff --git a/README.md b/README.md index b223198d..ddb55500 100644 --- a/README.md +++ b/README.md @@ -81,11 +81,11 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#branches) for more information on branches ##### Current Mainline Versions and Branches -| Version | Status | Branch | Documentation | Initial Release | End of Active Development | End of Maintenance | Notes | -|---------|---------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------| -| 3.x | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | TBD | TBD | TBD | TBD | See [RELEASE-PLANNING-X.0.md](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev/RELEASE-PLANNING-3.0.md). | -| 2.x | `active` | [`main`](https://github.com/planetlabs/planet-client-python/tree/main) | [Planet Labs Python Client v2 on Readthedocs.io](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) | April 2023 | TBD | TBD | | -| 1.x | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1) | [Planet Labs Python Client v1 on Github.io](https://planetlabs.github.io/planet-client-python/) | April 2017 | April 2023 | TBD | | +| Version | Status | Branch | Documentation | Initial Release | End of Active Development | End of Maintenance | Notes | +|---------|---------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|-------------------------------------------------------------------------------------------------| +| 3.x | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | [Planet Labs Python Client on ReadTheDocs.io](https://planet-sdk-for-python.readthedocs.io/en/latest/) | TBD | TBD | TBD | See [3.0.0 Release Milestone](https://github.com/planetlabs/planet-client-python/milestone/31). | +| 2.x | `active` | [`main`](https://github.com/planetlabs/planet-client-python/tree/main) | [Planet Labs Python Client v2 on ReadTheDocs.io](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) | April 2023 | TBD | TBD | | +| 1.x | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1) | [Planet Labs Python Client v1 on Github.io](https://planetlabs.github.io/planet-client-python/) | April 2017 | April 2023 | TBD | | ## Installation and Quick Start diff --git a/RELEASE-PLANNING-3.0.md b/RELEASE-PLANNING-3.0.md deleted file mode 100644 index 796a75f1..00000000 --- a/RELEASE-PLANNING-3.0.md +++ /dev/null @@ -1,13 +0,0 @@ -# Planet Python Client 3.0 Release Planning - -* Authentication changes: - * Migrate to OAuth2 based authentication mechanisms, leveraging the - [planet-auth-python](https://github.com/planetlabs/planet-auth-python) - library for implementation. - * Deprecate use of the legacy authentication protocol and handling of the - user's password. - * CLI changes to support changes in authentication practices. - * Support for API keys supplied by the user is maintained, but users should - be aware that there are currently no plans for sentinel-hub.com APIs to - support Planet API keys. The longer term roadmap is for all APIs to work - with OAuth service accounts. diff --git a/docs/get-started/upgrading.md b/docs/get-started/upgrading-v2.md similarity index 100% rename from docs/get-started/upgrading.md rename to docs/get-started/upgrading-v2.md diff --git a/docs/get-started/upgrading-v3.md b/docs/get-started/upgrading-v3.md new file mode 100644 index 00000000..02151a1c --- /dev/null +++ b/docs/get-started/upgrading-v3.md @@ -0,0 +1,95 @@ +# Upgrade from Version 2 to Version 3 + +Version 3 of the Planet SDK for Python is a major update of the SDK offering +new features, not all of which are backwards compatible with version 2. + +## Authentication +Version 3 of the SDK removes support for Planet's legacy authentication network +protocols in favor of OAuth2 based mechanisms. The legacy protocols +were never a [documented Planet API](https://docs.planet.com/develop/apis/), but could +easily be understood by inspection of the SDK code. + +Specifically, what is being deprecated in version 3 are the paths where the SDK +handled a username and password to obtain the user's API key for forward +operations. Users may still operate with an API key by retrieving it from the +Planet user interface under [My Settings](https://www.planet.com/account/#/user-settings) +and providing it to the SDK. While API keys remain supported for machine-to-machine +API use cases using `api.planet.com` APIs, OAuth2 mechanisms should be preferred +where the use case allows for it. + +Users may also continue to initialize SDK and CLI sessions with their username +and password, but rather than being processed by the SDK itself a browser must +be invoked to complete OAuth2 client session initialization. +This new method is intended to offer a number of long term benefits, including: + +* The new method provides the SDK and the CLI with access tokens that may be + used with both `api.planet.com` and `services.sentinel-hub.com` endpoints. The method + used by version 2 of the SDK was specific to `api.planet.com` endpoints, and + will never be supported by `services.sentinel-hub.com` endpoints. +* The new method extends (currently optional) multifactor authentication (MFA) + to SDK and CLI client use cases. +* The new method is compatible with other platform enhancements currently under + development by Planet's software engineering team. + +For complete details on the new mechanisms, see the [Client Authentication Guide](../python/sdk-client-auth.md). + +### CLI Usage +The [`planet auth`](../../cli/cli-reference/#auth) command has been substantially +revised to align to the new authentication mechanisms. For migration from version 2 +of the SDK, the following changes are the most important to note: + +* The `planet auth init` command has been replaced with [`planet auth login`](../../cli/cli-reference/#login). + By default, this command will open a browser window to allow the user to log + in to their Planet account and authorize the SDK or CLI to access their account. + Other options are available to support a variety of use cases, including a + `--no-open-browser` option for remote shells. See `planet auth login --help` + for complete details. +* The `planet auth value` command has been deprecated. Depending on whether the SDK + has been initialized with OAuth2 or API key authentication, + [`planet auth print-access-token`](../../cli/cli-reference/#print-access-token) + or [`planet auth print-api-key`](../../cli/cli-reference/#print-api-key) may + be used. OAuth2 sessions should be preferred where possible. +* The `planet auth store` command has been deprecated. The various options to the + `planet auth login` command should provide suitable alternatives for all use cases. + OAuth2 sessions should be favored for user interactive use cases, such as CLI usage. + `planet auth login --auth-api-key YOUR_API_KEY` may be used to initialize the SDK + with API key based authentication where the use case requires it. + +### Session Persistence +Both version 2 and version 3 of the SDK use the `~/.planet.json` file in the user's +home directory to store user's API key. If this file is present and was configured +by version 2 of the SDK, it should continue to work. + +While the `~/.planet.json` file continues to be used by version 3, and version 3 +understands files written by version 2, version 3 will not write the same information +to this file that version 2 did. Version 3 uses this file in conjunction with the +`~/.planet` directory and subdirectories to store OAuth2 tokens and additional +session information needed for a smooth user experience. + +Version 3 of the SDK provides a [`planet auth reset`](../../cli/cli-reference/#reset) +command to reset all saved state should it become corrupted. When this command is run, +the old files are moved aside rather than deleted. + +### SDK Session Initialization +See the [Client Authentication Guide](../python/sdk-client-auth.md) for a complete +discussion of all options now available. + +Basic SDK use cases should work with no alterations. +User sessions initialized by [`planet auth login`](../../cli/cli-reference/#login) +will be detected by an application using a default Planet client when +run in an environment with access to the user's home directory. For example: + +```python linenums="1" +{% include 'auth-session-management/cli_managed_auth_state__implicit.py' %} +``` + +Applications may also continue to initialize the SDK with a specific API key as follows: +```python linenums="1" +{% include 'auth-session-management/app_managed_auth_state__in_memory__api_key.py' %} +``` + +Users developing new applications should consult the [Client Authentication Guide](../python/sdk-client-auth.md) +for a complete discussion of all OAuth2 based mechanisms. OAuth2 mechanisms +should be preferred to the use of Planet API keys. + +---- diff --git a/docs/python/sdk-client-auth.md b/docs/python/sdk-client-auth.md index bcc3adfa..a0bf32eb 100644 --- a/docs/python/sdk-client-auth.md +++ b/docs/python/sdk-client-auth.md @@ -8,9 +8,11 @@ For general information on how to authenticate to Planet APIs, please see the [Authentication](https://docs.planet.com/develop/authentication) section of Planet's platform documentation. !!! warning - Some statements are forward-looking. OAuth2 M2M tokens are - currently only supported by `services.sentine-hub.com` and not supported - by `api.planet.com`. + Some statements in this guide are forward-looking. + + OAuth2 M2M tokens are currently only supported by `services.sentine-hub.com`, + and are not yet supported by `api.planet.com`. This is planned for a future date + to be announced. All APIs support interactive user OAuth2 access tokens, but a process for developers to register and manage clients has not yet been made public. @@ -18,10 +20,10 @@ the [Authentication](https://docs.planet.com/develop/authentication) section of manage which applications have been authorized to access the platform on their behalf. - If you would like to developed an interactive application that uses - Planet's APIs on behalf of a user (as the `planet` CLI utility does), - please contact Planet and work with engineering to register your - application. + If you would like to develop an interactive application that uses + Planet's APIs on behalf of a logged-in user (as the `planet` CLI utility + does), please contact Planet support and work with engineering to + register your application. ---- ## Authentication Protocols @@ -213,7 +215,7 @@ complete user authentication. This architecture allows for greater security by keeping the user's password from being directly exposed to the application code. This also allows for flexibility in user federation and multifactor authentication procedures without the complexity of these needing to -be exposes to the application developer who is focused on geospatial +be exposed to the application developer who is focused on geospatial operations using the Planet platform, and not the nuances of user authentication and authorization. diff --git a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py index 08ddb0a9..67a88320 100644 --- a/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py +++ b/examples/auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py @@ -75,8 +75,7 @@ def _save_file(file_path: pathlib.Path, data: dict): def example_main(): - # Create an auth context with a client ID that - # is unique to this application. + # Create an auth context with the client ID and secret of the service account. plsdk_auth = planet.Auth.from_oauth_m2m( client_id="__MUST_BE_END_USER_SUPPLIED__", client_secret="__MUST_BE_END_USER_SUPPLIED__", diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py b/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py index 7efb7659..cde34a5a 100644 --- a/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py +++ b/examples/auth-session-management/app_managed_auth_state__in_memory__api_key.py @@ -1,9 +1,6 @@ import json -import logging import planet -logging.basicConfig(level=logging.CRITICAL) - def example_main(): # Create an auth context with the specified API key diff --git a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py index 517e186a..867fdd17 100644 --- a/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py +++ b/examples/auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py @@ -1,13 +1,9 @@ import json -import logging import planet -logging.basicConfig(level=logging.CRITICAL) - def example_main(): - # Create an auth context with a client ID that - # is unique to this application. + # Create an auth context with the client ID and secret of the service account. plsdk_auth = planet.Auth.from_oauth_m2m( client_id="__MUST_BE_END_USER_SUPPLIED__", client_secret="__MUST_BE_END_USER_SUPPLIED__", @@ -17,7 +13,7 @@ def example_main(): # Explicit login is not required for M2M client use. The above is sufficient. # plsdk_auth.user_login() - # Create a Planet SDK object that uses the loaded auth session/ + # Create a Planet SDK object that uses the loaded auth session. sess = planet.Session(plsdk_auth) pl = planet.Planet(sess) diff --git a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py index 61d63198..23b23b11 100644 --- a/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py +++ b/examples/auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py @@ -6,8 +6,7 @@ def example_main(): - # Create an auth context with a client ID that - # is unique to this application. + # Create an auth context with the client ID and secret of the service account. plsdk_auth = planet.Auth.from_oauth_m2m( client_id="__MUST_BE_END_USER_SUPPLIED__", client_secret="__MUST_BE_END_USER_SUPPLIED__", diff --git a/examples/auth-session-management/cli_managed_auth_state__implicit.py b/examples/auth-session-management/cli_managed_auth_state__implicit.py index 19b73f60..bd639780 100644 --- a/examples/auth-session-management/cli_managed_auth_state__implicit.py +++ b/examples/auth-session-management/cli_managed_auth_state__implicit.py @@ -1,18 +1,15 @@ import json -import logging import planet -logging.basicConfig(level=logging.CRITICAL) - def example_main(): # By default, the Planet SDK will be instantiated with the default auth # session configured by `planet auth` and saved to disk. This default - # initialization will also take information from environment variables. + # initialization will also inspect environment variables for configuration. pl = planet.Planet() # Use the SDK to call Planet APIs. - # Refreshing access tokens will be managed automatically by the SDK. + # Refreshing OAuth2 access tokens will be managed automatically by the SDK. for item in pl.data.list_searches(): print(json.dumps(item, indent=2, sort_keys=True)) diff --git a/mkdocs.yml b/mkdocs.yml index a4a1898f..aec8349d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,7 +62,7 @@ plugins: selection: inherited_members: true filters: - - "!^_" # exlude all members starting with _ + - "!^_" # exclude all members starting with _ - "^__init__$" # but always include __init__ modules and methods watch: - planet @@ -76,7 +76,9 @@ nav: - get-started/quick-start-guide.md - get-started/get-your-planet-account.md - get-started/venv-tutorial.md - - get-started/upgrading.md + - "Upgrade Guides": + - get-started/upgrading-v3.md + - get-started/upgrading-v2.md - "No Code CLI": - cli/cli-guide.md - cli/cli-intro.md