diff --git a/docs/conf.py b/docs/conf.py index 30548e4e..226a6ac3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,7 +33,13 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx_rtd_theme", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.autosectionlabel"] +extensions = [ + "sphinx_rtd_theme", + "sphinx.ext.autodoc", + "sphinx.ext.napoleon", + "sphinx.ext.autosectionlabel", + "sphinx.ext.intersphinx", +] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -58,3 +64,8 @@ version = "3.0.4" master_doc = "index" + +# Looks for objects in external projects +intersphinx_mapping = { + "grpc": ("https://grpc.github.io/grpc/python/", None), +} diff --git a/docs/errors.rst b/docs/errors.rst index 8fea5223..901963e7 100644 --- a/docs/errors.rst +++ b/docs/errors.rst @@ -44,6 +44,8 @@ All ``pyzeebe`` errors inherit from :py:class:`PyZeebeError` .. autoexception:: pyzeebe.errors.InvalidCamundaCloudCredentialsError +.. autoexception:: pyzeebe.errors.UnkownGrpcStatusCodeError + ================= Exception Handler diff --git a/pyzeebe/credentials/base.py b/pyzeebe/credentials/base.py index d75d4c1b..2aac4a4e 100644 --- a/pyzeebe/credentials/base.py +++ b/pyzeebe/credentials/base.py @@ -4,7 +4,7 @@ class CredentialsABC(abc.ABC): - """TODO.""" + """A specification for credentials manager. Passed to :py:class:`AuthMetadataPlugin`.""" @abc.abstractmethod def get_auth_metadata(self, context: CallContext) -> AuthMetadata: @@ -13,6 +13,6 @@ def get_auth_metadata(self, context: CallContext) -> AuthMetadata: context (grpc.AuthMetadataContext): Provides information to call credentials metadata plugins. Returns: - Tuple[Tuple[str, Union[str, bytes]], ...]: The `metadata` used to construct the grpc.CallCredentials. + Tuple[Tuple[str, Union[str, bytes]], ...]: The `metadata` used to construct the :py:class:`grpc.CallCredentials`. """ raise NotImplementedError diff --git a/pyzeebe/credentials/camunda_identity.py b/pyzeebe/credentials/camunda_identity.py index 3e3614bd..44fc1e9c 100644 --- a/pyzeebe/credentials/camunda_identity.py +++ b/pyzeebe/credentials/camunda_identity.py @@ -16,8 +16,8 @@ class CamundaIdentityCredentials(CredentialsABC): oauth_url (str): The Keycloak auth endpoint url. client_id (str): The client id provided by Camunda Platform client_secret (str): The client secret provided by Camunda Platform - audience (str): - refresh_threshold_seconds (int): + audience (str): Audience for Zeebe. Default: zeebe-api + refresh_threshold_seconds (int): Will try to refresh token if it expires in this number of seconds or less. Default: 20 """ def __init__( @@ -75,7 +75,7 @@ def get_auth_metadata(self, context: CallContext) -> AuthMetadata: context (grpc.AuthMetadataContext): Provides information to call credentials metadata plugins. Returns: - Tuple[Tuple[str, Union[str, bytes]], ...]: The `metadata` used to construct the grpc.CallCredentials. + Tuple[Tuple[str, Union[str, bytes]], ...]: The `metadata` used to construct the :py:class:`grpc.CallCredentials`. Raises: InvalidOAuthCredentialsError: One of the provided camunda credentials is not correct diff --git a/pyzeebe/credentials/plugins.py b/pyzeebe/credentials/plugins.py index 9aa65641..0ac2026d 100644 --- a/pyzeebe/credentials/plugins.py +++ b/pyzeebe/credentials/plugins.py @@ -7,10 +7,10 @@ class AuthMetadataPlugin(grpc.AuthMetadataPlugin): - """TODO. + """Custom authentication plugin with exception catching. Args: - credentials (CredentialsABC): TODO + credentials (CredentialsABC): A credentials manager. """ def __init__(self, *, credentials: CredentialsABC) -> None: @@ -30,11 +30,6 @@ def __call__(self, context: grpc.AuthMetadataContext, callback: grpc.AuthMetadat try: metadata = self._credentials.get_auth_metadata(context) except Exception as e: - self._sign_request(callback, (), e) + callback((), e) else: - self._sign_request(callback, metadata, None) - - def _sign_request( - self, callback: grpc.AuthMetadataPluginCallback, metadata: AuthMetadata, error: Optional[Exception] - ) -> None: - callback(metadata, error) + callback(metadata, None)