Move BuiltinConfigurationProviderInterface to a separate top level package that does not have any dependencies. Having it be part of the package makes it very difficult to avoid circular dependencies.

Author: carl-adams-planet

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

mkdocs.yml

@@ -80,6 +80,7 @@ nav:
   - API Reference:
     - Planet Auth: 'api-planet-auth.md'
     - Planet Auth Utils: 'api-planet-auth-utils.md'
+    - Planet Auth Config Injection: 'api-planet-auth-config-injection.md'
   - Examples:
     - Installation: 'examples-installation.md'
     - CLI: 'examples-cli.md'

src/planet_auth_config_injection/__init__.py

@@ -0,0 +1,32 @@
+# Copyright 2025 Planet Labs PBC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+# The Planet Authentication Library Configration Injection Package: `planet_auth_config_injection`
+
+This package provides interfaces and utilities for higher-level applications
+to inject configuration into the Planet Authentication Library.
+"""
+
+from .builtins_provider import (
+    AUTH_BUILTIN_PROVIDER,
+    BuiltinConfigurationProviderInterface,
+    EmptyBuiltinProfileConstants,
+)
+
+__all__ = [
+    "AUTH_BUILTIN_PROVIDER",
+    "BuiltinConfigurationProviderInterface",
+    "EmptyBuiltinProfileConstants",
+]

src/planet_auth_utils/builtins_provider.py renamed to src/planet_auth_config_injection/builtins_provider.py

@@ -22,8 +22,9 @@
 # users.
 AUTH_BUILTIN_PROVIDER = "PL_AUTH_BUILTIN_CONFIG_PROVIDER"
 """
-Specify a python module and class that implement the BuiltinConfigurationProviderInterface abstract
-interface to provide the library and utility commands with some built-in configurations.
+Environment variable to specify a python module and class that implement the
+BuiltinConfigurationProviderInterface abstract interface to provide the library
+and utility commands with some built-in configurations.
 """
 
 _NOOP_AUTH_CLIENT_CONFIG = {

src/planet_auth_utils/__init__.py

@@ -99,11 +99,7 @@
 from .commands.cli.util import recast_exceptions_to_click
 from planet_auth_utils.constants import EnvironmentVariables
 from planet_auth_utils.plauth_factory import PlanetAuthFactory
-from planet_auth_utils.builtins import (
-    Builtins,
-    # Easily causes circular dependencies. Intentionally not part of the main package interface for now.
-    # BuiltinConfigurationProviderInterface,
-)
+from planet_auth_utils.builtins import Builtins
 from planet_auth_utils.profile import Profile
 from planet_auth_utils.plauth_user_config import PlanetAuthUserConfig
 
@@ -165,7 +161,6 @@
     "recast_exceptions_to_click",
     #
     "Builtins",
-    # "BuiltinConfigurationProviderInterface",
     "EnvironmentVariables",
     "PlanetAuthFactory",
     "Profile",

src/planet_auth_utils/builtins.py

@@ -18,7 +18,7 @@
 from planet_auth import AuthClientConfig
 from planet_auth_utils.profile import ProfileException
 from planet_auth.logging.auth_logger import getAuthLogger
-from .builtins_provider import (
+from planet_auth_config_injection import (
     BuiltinConfigurationProviderInterface,
     EmptyBuiltinProfileConstants,
     AUTH_BUILTIN_PROVIDER,
@@ -36,6 +36,7 @@ def _load_builtins_worker(builtin_provider_fq_class_name, log_warning=False):
         return
 
     module_name, _, class_name = builtin_provider_fq_class_name.rpartition(".")
+    auth_logger.debug(msg=f'Loading built-in provider:"{builtin_provider_fq_class_name}".')
     if module_name and class_name:
         try:
             builtin_provider_module = importlib.import_module(module_name)  # nosemgrep - WARNING - See below
@@ -89,6 +90,7 @@ class Builtins:
     def _load_builtin_jit():
         if not Builtins._builtin:
             Builtins._builtin = _load_builtins()
+            auth_logger.debug(msg=f"Successfully loaded built-in provider: {Builtins._builtin.__class__.__name__}")
 
     @staticmethod
     def is_builtin_profile(profile: str) -> bool:

tests/test_planet_auth_utils/unit/auth_utils/builtins_test_impl.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 from typing import Dict, List, Optional
-from planet_auth_utils.builtins_provider import BuiltinConfigurationProviderInterface
+from planet_auth_config_injection import BuiltinConfigurationProviderInterface
 
 
 class MockStagingEnv:

tests/test_planet_auth_utils/unit/auth_utils/test_builtins.py

@@ -16,7 +16,7 @@
 import pytest
 import unittest
 
-from planet_auth_utils.builtins_provider import AUTH_BUILTIN_PROVIDER
+from planet_auth_config_injection import AUTH_BUILTIN_PROVIDER
 from planet_auth_utils.builtins import Builtins, BuiltinsException
 
 from tests.test_planet_auth_utils.util import TestWithHomeDirProfiles

tests/test_planet_auth_utils/unit/auth_utils/test_plauth_factory.py

@@ -20,7 +20,7 @@
 import planet_auth.storage_utils
 from planet_auth.constants import AUTH_CONFIG_FILE_PLAIN
 
-from planet_auth_utils.builtins_provider import AUTH_BUILTIN_PROVIDER
+from planet_auth_config_injection import AUTH_BUILTIN_PROVIDER
 from planet_auth_utils.builtins import Builtins
 from planet_auth_utils.constants import EnvironmentVariables
 from planet_auth_utils.plauth_factory import PlanetAuthFactory, MissingArgumentException