work to integrate with public python SDK. (#1)

Many changes.  Initial refactoring while integrating with the Planet public python SDK

Author: carl-adams-planet

.github/workflows/release-orchestrate.yml

@@ -17,6 +17,15 @@ on:
           - beta
           - rc
           - release
+      publish-to:
+        description: "Where to publish the package to"
+        type: choice
+        default: "none"
+        options:
+          - none
+          - all
+          - pypi-test
+          - pypi-prod
 
 env:
   PYTHON_VERSION: "3.13"
@@ -30,6 +39,10 @@ jobs:
       contents: write
     env:
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    outputs:
+      version: ${{steps.gen-buildnum.outputs.version}}
+      version-with-buildnum: ${{steps.gen-buildnum.outputs.version-with-buildnum}}
+      version-variant-raw: ${{steps.gen-buildnum.outputs.variant-raw}}
     steps:
       - name: "Checkout code"
         uses: actions/checkout@v4
@@ -39,34 +52,87 @@ jobs:
         with:
           build-variant: ${{ inputs.build-variant }}
       - name: "Tag repository"
-        # Tagging is part of the build number generation in part because
-        # tag uniqueness serves as a synchronization mechanism to prevent
-        # multiple releases of the same version.
+        # Tagging is part of the build number generation at the start of the
+        # pipeline because tag uniqueness serves as a synchronization
+        # mechanism to prevent multiple releases of the same version.
         run: |
           set -x
           git config --global user.email "[email protected]"
           git config --global user.name  "CICD for github repository ${GITHUB_REPOSITORY}"
           if [ "${{ steps.gen-buildnum.outputs.variant-raw }}" = "release" ]
           then
-            git tag -a -m "test tag comment for final release" "${{steps.gen-buildnum.outputs.version}}"
-            git push origin                                    "${{steps.gen-buildnum.outputs.version}}"
+            git tag -a -m "Tagging from release orchestration pipeline" "${{steps.gen-buildnum.outputs.version}}"
+            git push origin                                             "${{steps.gen-buildnum.outputs.version}}"
           fi
-          git tag -a -m "test tag comment" "${{steps.gen-buildnum.outputs.version-with-buildnum}}"
-          git push origin                  "${{steps.gen-buildnum.outputs.version-with-buildnum}}"
+          git tag -a -m "Tagging from release orchestration pipeline" "${{steps.gen-buildnum.outputs.version-with-buildnum}}"
+          git push origin                                             "${{steps.gen-buildnum.outputs.version-with-buildnum}}"
   test:
     name: "Prerelease Tests"
     uses: ./.github/workflows/test.yml
-    needs: generate-build-number # Doesn't really need it, but gates the pipeline to not waste time.
+    # We do not really need the build number, but this gates the job so we do not waste
+    # time testing a build that is attempting an illegal clobbering of a released version.
+    needs: generate-build-number
+  generate-release:
+    name: "Create Github Release"
+    runs-on: ubuntu-latest
+    needs: [test, generate-build-number]
+    permissions: write-all
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: "Create Github Release (Version candidate release)"
+        # if:  needs.generate-build-number.outputs.version-variant-raw != 'release'
+        uses: actions/create-release@v1
+        with:
+          tag_name: "${{ needs.generate-build-number.outputs.version-with-buildnum }}"
+          release_name: "${{ needs.generate-build-number.outputs.version-with-buildnum }}"
+          draft: false
+          prerelease: ${{ inputs.version-prerelease }}
+      - name: "Create Github Release (Final version release)"
+        if:  needs.generate-build-number.outputs.version-variant-raw == 'release'
+        uses: actions/create-release@v1
+        with:
+          tag_name: "${{ needs.generate-build-number.outputs.version }}"
+          release_name: "${{ needs.generate-build-number.outputs.version }}"
+          draft: false
+          prerelease: ${{ inputs.version-prerelease }}
   package:
     name: "Build Release Artifacts"
     uses: ./.github/workflows/release-build.yml
     needs: [test, generate-build-number]
   publish:
     name: "Publish Release Artifacts"
     uses: ./.github/workflows/release-publish.yml
-    needs: [package, generate-build-number]
+    needs: [package, generate-release, generate-build-number]
+    with:
+      publish-to: ${{inputs.publish-to}}
     secrets:
       PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
       PYPI_API_TOKEN_TEST: ${{ secrets.PYPI_API_TOKEN_TEST }}
-    # with:
-    #   version-with-buildnumber: ${{needs.generate-build-number.outputs.version-with-buildnum}}
+  publish-2:
+    # Python trusted publishing does not currently support
+    # reusable workflows.  I really would prefer this be part
+    # of "uses: ./.github/workflows/release-publish.yml" for
+    # better encapsulation.
+    # See https://github.com/pypi/warehouse/issues/11096
+    name: "Publish Release Artifacts (Trusted)"
+    needs: [package, generate-release, generate-build-number]
+    if: inputs.publish-to == 'pypi-prod' || inputs.publish-to == 'all'
+    runs-on: ubuntu-latest
+    environment: pypi-prod
+    permissions:
+      # Needed for Trusted Publishing
+      id-token: write
+    steps:
+      - name: "Download Wheel Package"
+        uses: actions/download-artifact@v4
+        with:
+          name: planet-auth-wheel
+          path: dist
+      - name: "Download Source Package"
+        uses: actions/download-artifact@v4
+        with:
+          name: planet-auth-src-targz
+          path: dist
+      - name: "Trusted Publishing - Publish to PyPi (Production)"
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/release-publish.yml

@@ -1,30 +1,29 @@
 name: Publish Release
 
-# TODO: create a github release. This is needed to trigger webhooks.
-
 permissions:
   actions: read
   contents: read
 
 on:
   workflow_call:
-    # inputs:
-    #   version-with-buildnumber:
-    #     required: true
-    #     type: string
-    #     description: "The fully qualified unique version build number."
     secrets:
       PYPI_API_TOKEN:
       PYPI_API_TOKEN_TEST:
+    inputs:
+      publish-to:
+        description: "Where to publish the package to"
+        type: string
+        default: "none"
 
 env:
   PYTHON_VERSION: "3.13"
 
 jobs:
   release-pypi-test:
     name: "Release package to PyPi (Test)"
+    if: inputs.publish-to == 'pypi-test' || inputs.publish-to == 'all'
     runs-on: ubuntu-latest
-    # environment: staging
+    # environment: pypi-test
     steps:
       - name: "Checkout code"
         uses: actions/checkout@v4
@@ -52,14 +51,35 @@ jobs:
         env:
           NOX_PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN_TEST }}
         run: |
-          false
-          # TODO: re-enable. Disabled for pipeline development
-          # nox -s pkg_publish_pypi_test
+          nox -s pkg_publish_pypi_test
+
+  # release-pypi-production:
+  #   name: "Release package to PyPi (Production)"
+  #   if: inputs.publish-to == 'pypi-prod' || inputs.publish-to == 'all'
+  #   runs-on: ubuntu-latest
+  #   # environment: pypi-prod
+  #   permissions:
+  #     # Needed for Trusted Publishing
+  #     id-token: write
+  #   steps:
+  #     - name: "Download Wheel Package"
+  #       uses: actions/download-artifact@v4
+  #       with:
+  #         name: planet-auth-wheel
+  #         path: dist
+  #     - name: "Download Source Package"
+  #       uses: actions/download-artifact@v4
+  #       with:
+  #         name: planet-auth-src-targz
+  #         path: dist
+  #     - name: "Trusted Publishing - Publish to PyPi (Production)"
+  #       uses: pypa/gh-action-pypi-publish@release/v1
 
-  release-pypi-production:
-    name: "Release package to PyPi (Production)"
+  release-none:
+    name: "Release (None)"
+    if: inputs.publish-to == 'none'
     runs-on: ubuntu-latest
-    # environment: staging
+    # environment: none
     steps:
       - name: "Checkout code"
         uses: actions/checkout@v4
@@ -77,13 +97,11 @@ jobs:
         with:
           name: planet-auth-src-targz
           path: dist
-      - name: "Nox: Publish to PyPi (Production)"
-        env:
-          NOX_PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+      - name: "Nox: check package only. (Publishing NoOp / dry-run)"
         run: |
-          false
-          # TODO: re-enable. Disabled for pipeline development
-          # nox -s pkg_publish_pypi_prod
+          echo "Skipping publishing of python package."
+          nox -s pkg_check
+
 
   # Read the docs is published via webhook GitHub webhook
   # release-readthedocs:

CONTRIBUTING.md

@@ -1 +1,4 @@
-TODO: document submitting tickets and PRs.  We will likely lean on the SDK process.
+This project is currently run as a child project of the
+[Planet SDK for Python](https://developers.planet.com/docs/pythonclient/)
+([on github](https://github.com/planetlabs/planet-client-python)).
+Please refer to that project for submitting issues and general discussion.

RELEASE.md

@@ -19,12 +19,15 @@ changes (like documentation).
 The `main` branch is intended to be kept stable with the most up-to-date
 feature set, and should normally be the branch used for new feature releases.
 Patch branches may be necessary when the need to fix older versions arises.
+The release pipelines supports releasing from any branch.
 
 To release a new version, complete the following steps:
 
 1. Create a release branch off of `main` that bumps the version number in
-   [version.txt](./version.txt), and updates the
-   [changelog.md](./docs/changelog.md).
+   branch invariant [version.txt](./version.txt) file, and updates the
+   [changelog.md](./docs/changelog.md).  The [version-with-buildnum.txt](./version-with-buildnum.txt)
+   should also be kept up to date, and is used to assign versions to local
+   builds.
 2. Collect all features targeted for the intended release in the branch, and
    create a PR to merge the release branch into `main`.
 3. Ensure that all tests are passing on `main` branch after all merges.
@@ -35,11 +38,18 @@ To release a new version, complete the following steps:
    * `beta` - A beta release.
    * `alpha` - An alpha release
    * `dev` - A development release.  This is the default.
-5. Initiate a release by activating the [Release Orchestration Workflow](./.github/workflows/release-orchestrate.yml) pipeline:
+5. Determine where to publish the python package to.  This will be passed to the
+   release workflow pipeline as the `publish-to` argument:
+   * `none` - Skip actual publishing to PyPi servers.  This is a dry-run pipeline.
+     This is the default.
+   * `pypi-test` - Publish to the test PyPi server
+   * `pypi-prod` - Publish to the production PyPi server
+   * `all` - Publish to all PyPi servers.
+6. Initiate a release by activating the [Release Orchestration Workflow](./.github/workflows/release-orchestrate.yml) pipeline:
    * The release pipeline may be initiated in the GUI.
    * The release pipeline may be initiated by the `gh` CLI as follows:
      ```bash
-     gh workflow run .github/workflows/release-orchestrate.yml -f build-variant=_selected_release_variation_
+     gh workflow run .github/workflows/release-orchestrate.yml --ref _branch to release_ -f build-variant=_selected_release_variation_ -f publish-to=_selected_publication_target_
      ```
 
 ## Local Publishing

docs/changelog.md

@@ -1,7 +1,9 @@
 # Changelog
 
-## [Unreleased:2.0.0] - YYYY-MM-DD
-- 2.X is the initial public release of Planet auth libraries, targeting integration
-  with our public Python SDK [`planet-client-python`](https://github.com/planetlabs/planet-client-python)/
-- 2.0.X is a development series, not intended for production. When ready,
-  the version will be bumped to 2.1.
+## 2.0.4.X - 2025-03-09
+- Initial Beta release series to shakedown public release pipelines and
+  initial integrations.
+
+## [Unreleased: 2.0.0 - 2.0.3] - YYYY-MM-DD
+- 2.X is the initial public release of Planet auth libraries, targeting
+  integration with our public Python SDK [`planet-client-python`](https://github.com/planetlabs/planet-client-python)

docs/cli-plauth.md

@@ -3,7 +3,7 @@
 {% raw %}
 ::: mkdocs-click
     :module: planet_auth_utils.commands.cli.main
-    :command: plauth_cmd_group
+    :command: cmd_plauth
     :prog_name: plauth
     :depth: 1
 {% endraw %}

docs/examples.md

@@ -51,7 +51,7 @@ For example, to create a custom profile named "my-custom-profile", create the fo
 {% include 'auth-client-config/oauth-auth-code-grant-public-client.json' %}
 ```
 2. Initialize the client library with the specified profile.  Note: if the environment variable
-`PL_AUTH_PROFILE` is set, it will be detected automatically by [planet_auth.Auth.initialize_from_profile][],
+`PL_AUTH_PROFILE` is set, it will be detected automatically by [planet_auth_utils.PlanetAuthFactory][],
 and it will not be necessary to explicitly pass in the profile name:
 ```python linenums="1"
 {% include 'auth-client/oauth/initialize-client-lib-on-disk-profile.py' %}

docs/examples/auth-client/oauth/initialize-client-lib-on-disk-profile.py

@@ -1,8 +1,8 @@
-from planet_auth import Auth
+import planet_auth_utils
 
 
 def main():
-    auth_ctx = Auth.initialize_from_profile(profile="my-custom-profile")
+    auth_ctx = planet_auth_utils.PlanetAuthFactory.initialize_auth_client_context(auth_profile_opt="my-custom-profile")
     print("Auth context initialized from on disk profile {}".format(auth_ctx.profile_name()))
 
 

docs/examples/cli/embed-plauth-click.py

@@ -9,7 +9,7 @@
 
 # TODO: Update (look at current planet SDK)
 @click.group(help="my cli main help message")
-@planet_auth_utils.opt_auth_profile
+@planet_auth_utils.opt_profile
 @planet_auth_utils.opt_token_file
 @click.pass_context
 def my_cli_main(ctx, auth_profile, token_file):
@@ -48,7 +48,7 @@ def do_cmd2(ctx):
     print("Payload:\n{}".format(result.text))
 
 
-my_cli_main.add_command(planet_auth_utils.embedded_plauth_cmd_group)
+my_cli_main.add_command(planet_auth_utils.cmd_plauth_embedded)
 
 if __name__ == "__main__":
     my_cli_main()  # pylint: disable=E1120