OAuth2 support via planet_auth python libraries

.github/workflows/publish-pypi.yml

@@ -24,7 +24,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-pip
 
-      - name: Build, verify, and upload to TestPyPI
+      - name: Build, verify, and upload to PyPI
         run: |
           pip install --upgrade nox
           nox -s build publish_pypi

.gitignore

@@ -23,7 +23,9 @@ coverage.xml
 *.pyc
 
 # Editors
+.idea/
 .vscode/
 # Docs build
 site
 .venv
+venv

CHANGES.txt

@@ -1,5 +1,15 @@
 Changelog moved to https://github.com/planetlabs/planet-client-python/releases
 
+3.0.0 (Unreleased)
+- Overhaul of planet.Auth AP interface to leverage the
+  [Planet Auth Utility Library](https://github.com/planetlabs/planet-auth-python)
+  and move preferred authentication mechanisms to OAuth2 over API keys.
+  See the Client Authentication Guide in the documentation for details and
+  examples.
+- Overhaul of the `planet auth` CLI to support Auth infrastructure overhaul.
+  Of immediate note to uses is that `planet auth login` should be preferred
+  to `planet auth init` to initialize the CLI client for use.
+
 2.13.0 (2024-12-18)
 - Add Planet class (`from planet import Planet`)
   - Planet is a client that uses sync methods. Users do not have

docs/cli/cli-guide.md

@@ -34,13 +34,13 @@ Yes. Even if you’re not writing code—and only using the "no code" CLI part o
 Install the Planet SDK for Python using [pip](https://pip.pypa.io):
 
 ```console
-$ pip install planet
+pip install planet
 ```
 
 ## Step 3: Check the Planet SDK for Python version
 
 ```console
-$ planet --version
+planet --version
 ```
 
 You should be on some version 2 of the Planet SDK for Python.
@@ -55,46 +55,40 @@ To confirm your Planet account, or to get one if you don’t already have one, s
 
 ### Authenticate with the Planet server
 
-Just as you log in when you browse to https://account.planet.com, you’ll want to sign on to your account so you have access to your account and orders.
+Just as you log in when you browse to https://planet.com/account, you’ll want to sign on to your account so you have access to your account and orders.
 
 At a terminal console, type the following Planet command:
 
 ```console
-$ planet auth init
+planet auth login
 ```
 
-You’ll be prompted for the email and password you use to access [your account](https://account.planet.com). When you type in your password, you won’t see any indication that the characters are being accepted. But when you hit enter, you’ll know that you’ve succeeded because you’ll see on the command line:
+A browser window should be opened, and you will be directed to login to your account.  This
+command will wait for the browser login to complete, and should exit shortly afterwards.
+When this process succeeds, you will see the following message on the console:
 
 ```console
-Initialized
+Login succeeded.
 ```
 
-### Get your API key
-
-Now that you’ve logged in, you can easily retrieve your API key that is being used for requests with the following command:
-
+If you are in an environment where the `planet` command line utility cannot open a browser (such 
+as a remote shell on a cloud service provider), use the following command and follow the instructions:
 ```console
-planet auth value
+planet auth login --no-open-browser
 ```
 
-Many `planet` calls you make require an API key. This is a very convenient way to quickly grab your API key.
-
-#### Your API Key as an Environment Variable
+### Get your Access Token
 
-You can also set the value of your API Key as an environment variable in your terminal at the command line:
+Now that you’ve logged in, you can easily retrieve an Access Token that is being used for requests with the following command:
 
 ```console
-export PL_API_KEY=<your api key>
+planet auth print-access-token
 ```
 
-And you can see that the value was stored successfully as an environment variable with the following command:
-
-```console
-echo $PL_API_KEY
-```
+Many `planet` calls you make require an access token. This is a very convenient way to quickly grab the current access token.
 
-!!!note "The API Key environment variable is ignored by the CLI but used by the Python library"
-    If you do create a `PL_API_KEY` environment variable, the CLI will be unaffected but the Planet library will use this as the source for authorization instead of the value stored in `planet auth init`.
+**Note** : As a security measure, access tokens are time limited. They have a relatively short lifespan, and must
+be refreshed.  The `print-access-token` command takes care of this transparently for the user.
 
 ## Step 5: Search for Planet Imagery
 

docs/cli/cli-reference.md

@@ -4,8 +4,10 @@ title: CLI Reference
 
 This page provides documentation for our command line tools.
 
+{% raw %}
 ::: mkdocs-click
     :module: planet.cli.cli
     :command: main 
     :prog_name: planet
     :depth: 1
+{% endraw %}

docs/get-started/quick-start-guide.md

@@ -27,10 +27,12 @@ pip install planet
 
 ### Authentication
 
-Use the `PL_API_KEY` environment variable to authenticate with the Planet API. For other authentication options, see the [SDK guide](../python/sdk-guide.md).
+Use the `planet auth` CLI command to establish a user login session that will
+be saved to the user's home directory.  For other authentication options, see
+the [Client Authentication Guide](../python/sdk-client-auth.md).
 
 ```bash
-export PL_API_KEY=your_api_key
+planet auth login
 ```
 
 ### The Planet client
@@ -39,7 +41,7 @@ The `Planet` class is the main entry point for the Planet SDK. It provides acces
 
 ```python
 from planet import Planet
-pl = Planet()  # automatically detects PL_API_KEY
+pl = Planet()  # automatically detects authentication configured by `planet auth login`
 ```
 
 The Planet client has members `data`, `orders`, and `subscriptions`, which allow you to interact with the Data API, Orders API, and Subscriptions API. Usage examples for searching, ordering and creating subscriptions can be found in the [SDK guide](../python/sdk-guide.md).