Skip to main content

AuthorizationAdapterRegistrationAPI Reference

The AuthorizationAdapterRegistrationAPI is provided to authorization adapter plugins to allow them to register their custom AuthorizationEngineAdapter implementations with Castlecraft Architect.

An instance of this API is passed to the plugin's registration function (the function specified as an entry point in the plugin's pyproject.toml under the architect.authorization_adapters group).

API Overview​

The API is designed to be straightforward, primarily offering a way to add an adapter instance to Architect's central registry.

Class Location​

castlecraft_architect.plugins.authorization_adapter_api.AuthorizationAdapterRegistrationAPI

Initialization​

The AuthorizationAdapterRegistrationAPI is instantiated by Architect's PluginManager and is pre-configured with a reference to the AuthorizationEngineAdapterRegistryService. Plugin developers do not need to instantiate this API themselves; they receive it as an argument to their registration function.

# Example plugin registration function signature
def my_auth_adapter_registration_function(
    api: "AuthorizationAdapterRegistrationAPI",
    container: "punq.Container", # The DI container
    plugin_name: str
):
    # ... use api to register adapter ...
    # ... optionally use container to resolve other services ...
    pass

Methods​

register_adapter​

Registers an instance of an AuthorizationEngineAdapter with Architect.

Signature:

def register_adapter(self, adapter_instance: "AuthorizationEngineAdapter"):

Parameters:

  • adapter_instance (AuthorizationEngineAdapter): An initialized instance of your custom class that inherits from castlecraft_architect.infrastructure.authorization.adapters.auth_engine_adapter.AuthorizationEngineAdapter.

Behavior:

  • The provided adapter_instance is added to an internal registry, keyed by the name returned by its get_engine_name() method.
  • If an adapter with the same engine name is already registered, a ValueError will be raised. Engine names are treated case-insensitively for registration and retrieval.
  • Successful registration is typically logged by Architect.
  • Note on Architecture: The registered adapter is expected to be a pure, synchronous generator. To support persistence commands like sync-policies, the adapter class should also implement the get_persistence_service_class() method to return a class that implements the PolicyPersistenceService interface.

Example Usage (within a plugin's registration function):

from .my_custom_adapter_implementation import MyCustomAuthAdapter # Your adapter class

def register_my_plugin_auth_adapters(api: "AuthorizationAdapterRegistrationAPI", plugin_name: str):
    my_adapter = MyCustomAuthAdapter()
    api.register_adapter(my_adapter)
    # Architect now knows about 'my_adapter' and can use it via its engine name.