DRAFT: Update docs prior to pushing alpha out (#1140)

carl-adams-planet · web-flow · commit bedbf62dd421 · 2025-05-20T14:34:53.000-07:00
* update CONTRIBUTING and README to account for use of github projects and milestones.

* minor updates to examples.

* minor updates to auth guide.

* 3.0 migration guide.
diff --git 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
@@ -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
diff --git a/docs/get-started/upgrading-v2.md b/docs/get-started/upgrading-v2.md
diff --git a/docs/get-started/upgrading-v3.md 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
@@ -8,20 +8,22 @@ 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.
     We have also not yet release a way for end-users of such applications to
     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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
