Merge branch 'main' into carl/jwt-validator-commands

Author: carl-adams-planet

.github/workflows/release-build.yml

@@ -57,6 +57,9 @@ jobs:
   #     - name: "Nox: MKDocs Build"
   #       run: |
   #         nox -s mkdocs_build
+  #     - name: "Nox: MKDocs Check Links"
+  #       run: |
+  #         nox -s mkdocs_checklinks
   #     - name: "Save Artifacts - MkDocs"
   #       uses: actions/upload-artifact@v4
   #       with:

.github/workflows/test.yml

@@ -173,3 +173,8 @@ jobs:
       - name: 'Nox: MKDocs Build'
         run: |
           nox -s mkdocs_build
+          # Not checking the links in the pipeline right now.
+          # This is throwing some false positives on intra-md links
+          # that build OK, and would also be caught by our mkdocs
+          # strict mode setting.
+          # nox -s mkdocs_checklinks

README.md

@@ -1,7 +1,8 @@
 # Planet Auth Utility Library
 [![Build Status](https://github.com/planetlabs/planet-auth-python/actions/workflows/test.yml/badge.svg)](https://github.com/planetlabs/planet-auth-python/actions/workflows/test.yml)
-[![PyPI Downloads](https://static.pepy.tech/badge/planet-auth)](https://pepy.tech/projects/planet-auth)
 [![Read The Docs](https://app.readthedocs.org/projects/planet-auth/badge/)](https://planet-auth.readthedocs.io/)
+[![PyPI Downloads (pypistats.org)](https://img.shields.io/pypi/dm/planet-auth)](https://pypistats.org/packages/planet-auth)
+[![PyPI Downloads (peppy.tech)](https://static.pepy.tech/badge/planet-auth)](https://pepy.tech/projects/planet-auth)
 
 The Planet Auth Library provides generic authentication utilities for clients
 and for services.  For clients, it provides means to obtain access tokens that

docs/api-planet-auth-config-injection.md

@@ -0,0 +1,6 @@
+# ::: planet_auth_config_injection
+    options:
+      show_root_full_path: true
+      inherited_members: true
+      show_submodules: true
+      show_if_no_docstring: false

docs/api-planet-auth-utils.md

@@ -0,0 +1,6 @@
+# ::: planet_auth_utils
+    options:
+      show_root_full_path: true
+      inherited_members: true
+      show_submodules: true
+      show_if_no_docstring: false

docs/api-planet-auth.md

@@ -0,0 +1,6 @@
+# ::: planet_auth
+    options:
+      show_root_full_path: true
+      inherited_members: true
+      show_submodules: true
+      show_if_no_docstring: false

docs/api.md

@@ -0,0 +1,4 @@
+# Built-in Auth Client Profile Injection
+
+TODO: Document how applications may inject built-in auth client profiles for
+a smoother application user and developer experience.

docs/built-ins.md

@@ -1,9 +1,9 @@
 # Changelog
 
-## 2.1.0 - 2025 TBD
+## 2.1.0 - 2025-??-??
 - Initial public release targeting integration with the
   [Planet Client for Python](https://github.com/planetlabs/planet-client-python).
 
-## [Unreleased: 2.0.*] - YYYY-MM-DD
+## [Unreleased: 2.0.*]
 - All releases in the 2.0.X series are development releases, even if not
   tagged as such. This work included some shakedowns of the release pipelines.

docs/changelog.md

@@ -9,40 +9,13 @@ AuthClient Configuration dictionaries may either be provided directly, or loaded
 from disk when saved in a `Profile` (See below).
 
 While it is possible to work directly with the lower level implementation
-classes, it is generally simpler to use the higher level management code in
-[planet_auth.Auth][], or the factory methods in [planet_auth.AuthClient][] 
-and [planet_auth.AuthClientConfig][] to configure and instantiate instances.
-Directly using the lower level implementations should not be necessary in
-most cases.
+classes, it is generally simpler to organize the working set of objects
+with an [Auth Context][planet_auth.Auth] instance created from one of the
+factory methods in [planet_auth_utils.PlanetAuthFactory][]
 
 A number of auth client implementations are provided.  Clients should
 select the one most appropriate for their use case.
 
-### Planet Legacy Client
-Implemented by [planet_auth.PlanetLegacyAuthClient][] and [planet_auth.PlanetLegacyAuthClientConfig][]
-
-Configuration:
-```json linenums="1" title="~/.planet/_profile_name_/auth_client.json"
-{% include 'auth-client-config/planet-legacy.json' %}
-```
-
-Profile Usage:
-```python linenums="1"
-from planet_auth import Auth
-
-auth_ctx = Auth.initialize_from_profile(profile="_profile_name_")
-```
-
-
-Direct Usage:
-```python linenums="1"
-from planet_auth import Auth
-auth_ctx = Auth.initialize_from_config_dict(
-    client_config={ ... content of auth_client.json ... },
-    token_file="/my_token_file.json"
-)
-```
-
 ### OAuth Clients
 #### Auth Code with PKCE
 Implemented by [planet_auth.AuthCodeAuthClient][] and [planet_auth.AuthCodeClientConfig][]
@@ -54,18 +27,12 @@ Configuration:
 
 Profile Usage:
 ```python linenums="1"
-from planet_auth import Auth
-
-auth_ctx = Auth.initialize_from_profile(profile="_profile_name_")
+{% include 'snippets/auth-client-context-from-saved-profile.py' %}
 ```
 
 Direct Usage:
 ```python linenums="1"
-from planet_auth import Auth
-auth_ctx = Auth.initialize_from_config_dict(
-    client_config={ ... content of auth_client.json ... },
-    token_file="/my_token_file.json"
-)
+{% include 'snippets/auth-client-context-oauth-direct.py' %}
 ```
 
 #### Auth Code with PKCE and Client Public Key
@@ -164,6 +131,25 @@ outbound calls, which is one of the primary aims of most auth client types.
 Instead, this client configuration can only be used to validate incoming
 tokens.
 
+### Planet Legacy Client
+Implemented by [planet_auth.PlanetLegacyAuthClient][] and [planet_auth.PlanetLegacyAuthClientConfig][]
+
+Configuration:
+```json linenums="1" title="~/.planet/_profile_name_/auth_client.json"
+{% include 'auth-client-config/planet-legacy.json' %}
+```
+
+Profile Usage:
+```python linenums="1"
+{% include 'snippets/auth-client-context-from-saved-profile.py' %}
+```
+
+
+Direct Usage:
+```python linenums="1"
+{% include 'snippets/auth-client-context-pl-legacy-direct.py' %}
+```
+
 ## Environment Variables
 See [planet_auth_utils.EnvironmentVariables][] for a list of environment variables.