anaplan-sdk 0.4.3a1__tar.gz → 0.4.4__tar.gz

{anaplan_sdk-0.4.3a1 → anaplan_sdk-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anaplan-sdk
-Version: 0.4.3a1
+Version: 0.4.4
 Summary: Streamlined Python Interface for Anaplan
 Project-URL: Homepage, https://vinzenzklass.github.io/anaplan-sdk/
 Project-URL: Repository, https://github.com/VinzenzKlass/anaplan-sdk
@@ -14,6 +14,8 @@ Requires-Dist: httpx<1.0.0,>=0.27.0
 Requires-Dist: pydantic<3.0.0,>=2.7.2
 Provides-Extra: cert
 Requires-Dist: cryptography<46.0.0,>=42.0.7; extra == 'cert'
+Provides-Extra: keyring
+Requires-Dist: keyring<26.0.0,>=25.6.0; extra == 'keyring'
 Provides-Extra: oauth
 Requires-Dist: oauthlib<4.0.0,>=3.0.0; extra == 'oauth'
 Description-Content-Type: text/markdown
@@ -58,7 +60,8 @@ abstractions over all Anaplan APIs, allowing you to focus on business requiremen
 
 ## Getting Started
 
-Head over to the [Quick Start](quickstart.md) for basic usage instructions and examples.
+Head over to the [Quick Start](https://vinzenzklass.github.io/anaplan-sdk/quickstart/) for basic usage instructions and
+examples.
 
 ## Contributing
 

{anaplan_sdk-0.4.3a1 → anaplan_sdk-0.4.4}/README.md

@@ -38,7 +38,8 @@ abstractions over all Anaplan APIs, allowing you to focus on business requiremen
 
 ## Getting Started
 
-Head over to the [Quick Start](quickstart.md) for basic usage instructions and examples.
+Head over to the [Quick Start](https://vinzenzklass.github.io/anaplan-sdk/quickstart/) for basic usage instructions and
+examples.
 
 ## Contributing
 

anaplan_sdk-0.4.4/anaplan_sdk/__init__.py

@@ -0,0 +1,15 @@
+from ._async_clients import AsyncClient
+from ._auth import AnaplanLocalOAuth, AnaplanRefreshTokenAuth
+from ._clients import Client
+from ._oauth import AsyncOauth, Oauth
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "AnaplanLocalOAuth",
+    "AnaplanRefreshTokenAuth",
+    "AsyncOauth",
+    "Oauth",
+    "models",
+    "exceptions",
+]

{anaplan_sdk-0.4.3a1 → anaplan_sdk-0.4.4}/anaplan_sdk/_async_clients/_bulk.py

@@ -6,7 +6,7 @@ from typing import AsyncIterator, Iterator
 import httpx
 from typing_extensions import Self
 
-from anaplan_sdk._auth import AuthCodeCallback, AuthTokenRefreshCallback, _create_auth
+from anaplan_sdk._auth import _create_auth
 from anaplan_sdk._base import _AsyncBaseClient, action_url
 from anaplan_sdk.exceptions import AnaplanActionError, InvalidIdentifierException
 from anaplan_sdk.models import (
@@ -32,14 +32,8 @@ logger = logging.getLogger("anaplan_sdk")
 
 class AsyncClient(_AsyncBaseClient):
     """
-    An asynchronous Client for pythonic access to the
-    [Anaplan Integration API v2](https://anaplan.docs.apiary.io/). This Client provides high-level
-    abstractions over the API, so you can deal with python objects and simple functions rather than
-    implementation details like http, json, compression, chunking etc.
-
-
-    For more information, quick start guides and detailed instructions refer to:
-    [Anaplan SDK](https://vinzenzklass.github.io/anaplan-sdk).
+    Asynchronous Anaplan Client. For guides and examples
+    refer to https://vinzenzklass.github.io/anaplan-sdk.
     """
 
     def __init__(
@@ -51,15 +45,8 @@ class AsyncClient(_AsyncBaseClient):
         certificate: str | bytes | None = None,
         private_key: str | bytes | None = None,
         private_key_password: str | bytes | None = None,
-        client_id: str | None = None,
-        client_secret: str | None = None,
-        redirect_uri: str | None = None,
-        refresh_token: str | None = None,
-        oauth2_scope: str = "openid profile email offline_access",
-        on_auth_code: AuthCodeCallback = None,
-        on_token_refresh: AuthTokenRefreshCallback = None,
-        oauth_token: dict[str, str] | None = None,
         token: str | None = None,
+        auth: httpx.Auth | None = None,
         timeout: float | httpx.Timeout = 30,
         retry_count: int = 2,
         status_poll_delay: int = 1,
@@ -67,86 +54,55 @@ class AsyncClient(_AsyncBaseClient):
         allow_file_creation: bool = False,
     ) -> None:
         """
-        An asynchronous Client for pythonic access to the Anaplan Integration API v2:
-        https://anaplan.docs.apiary.io/. This Client provides high-level abstractions over the API,
-        so you can deal with python objects and simple functions rather than implementation details
-        like http, json, compression, chunking etc.
-
-
-        For more information, quick start guides and detailed instructions refer to:
-        https://vinzenzklass.github.io/anaplan-sdk.
+        Asynchronous Anaplan Client. For guides and examples
+        refer to https://vinzenzklass.github.io/anaplan-sdk.
 
         :param workspace_id: The Anaplan workspace Id. You can copy this from the browser URL or
-                             find them using an HTTP Client like Postman, Paw, Insomnia etc.
+               find them using an HTTP Client like Postman, Paw, Insomnia etc.
         :param model_id: The identifier of the model.
         :param user_email: A valid email registered with the Anaplan Workspace you are attempting
-                           to access. **The associated user must have Workspace Admin privileges**
-        :param password: Password for the given `user_email`. This is not suitable for production
-                         setups. If you intend to use this in production, acquire a client
-                         certificate as described under: https://help.anaplan.com/procure-ca-certificates-47842267-2cb3-4e38-90bf-13b1632bcd44
-        :param certificate: The absolute path to the client certificate file or the certificate
-                            itself.
-        :param private_key: The absolute path to the private key file or the private key itself.
-        :param private_key_password: The password to access the private key if there is one.
-        :param client_id: The client Id of the Oauth2 Anaplan Client.
-        :param client_secret: The client secret for your Oauth2 Anaplan Client.
-        :param redirect_uri: The redirect URI for your Oauth2 Anaplan Client.
-        :param refresh_token: If you have a valid refresh token, you can pass it to skip the
-                              interactive authentication code step.
-        :param oauth2_scope: The scope of the Oauth2 token, if you want to narrow it.
-        :param on_auth_code: A callback that takes the redirect URI as a single argument and must
-                             return the entire response URI. This will substitute the interactive
-                             authentication code step in the terminal. The callback can be either
-                             a synchronous function or an async coroutine function - both will be
-                             handled appropriately regardless of the execution context (in a thread,
-                             with or without an event loop, etc.).
-                             **Note**: When using asynchronous callbacks in complex applications
-                             with multiple event loops, be aware that callbacks may execute in a
-                             separate event loop context from where they were defined, which can
-                             make debugging challenging.
-        :param on_token_refresh: A callback function that is called whenever the token is refreshed.
-                                 This includes the initial token retrieval and any subsequent calls.
-                                 With this you can for example securely store the token in your
-                                 application or on your server for later reuse. The function
-                                 must accept a single argument, which is the token dictionary
-                                 returned by the Oauth2 token endpoint and does not return anything.
-                                 This can be either a synchronous function or an async coroutine
-                                 function. **Note**: When using asynchronous callbacks in complex
-                                 applications with multiple event loops, be aware that callbacks
-                                 may execute in a separate event loop context from where they were
-                                 defined, which can make debugging challenging.
+               to access.
+        :param password: Password for the given `user_email` for basic Authentication.
+        :param certificate: The certificate content or the absolute path to the certificate file.
+        :param private_key: The private key content or the absolute path to the private key file.
+        :param private_key_password: The password to access the private key file. This is only
+               considered if you provided a private key file and it password-protected.
+        :param token: An Anaplan API Token. This will be used to authenticate the client. If
+               sufficient other authentication parameters are provided, the token will be used
+               until it expires, after which a new one will be created. If you provide only this
+               parameter, the client will raise an error upon first authentication failure. For
+               short-lived instances, such as in web applications where user specific clients are
+               created, this is the recommended way to authenticate, since this has the least
+               overhead.
+        :param auth: You can provide a subclass of `httpx.Auth` to use for authentication. You can
+               provide an instance of one of the classes provided by the SDK, or an instance of
+               your own subclass of `httpx.Auth`. This will give you full control over the
+               authentication process, but you will need to implement the entire authentication
+               logic yourself.
         :param timeout: The timeout in seconds for the HTTP requests. Alternatively, you can pass
-                        an instance of `httpx.Timeout` to set the timeout for the HTTP requests.
+               an instance of `httpx.Timeout` to set the timeout for the HTTP requests.
         :param retry_count: The number of times to retry an HTTP request if it fails. Set this to 0
-                            to never retry. Defaults to 2, meaning each HTTP Operation will be
-                            tried a total number of 2 times.
+               to never retry. Defaults to 2, meaning each HTTP Operation will be tried a total
+               number of 2 times.
         :param status_poll_delay: The delay between polling the status of a task.
         :param upload_chunk_size: The size of the chunks to upload. This is the maximum size of
-                                  each chunk. Defaults to 25MB.
+               each chunk. Defaults to 25MB.
         :param allow_file_creation: Whether to allow the creation of new files. Defaults to False
-                            since this is typically unintentional and may well be unwanted
-                            behaviour in the API altogether. A file that is created this
-                            way will not be referenced by any action in anaplan until
-                            manually assigned so there is typically no value in dynamically
-                            creating new files and uploading content to them.
+               since this is typically unintentional and may well be unwanted behaviour in the API
+               altogether. A file that is created this way will not be referenced by any action in
+               anaplan until manually assigned so there is typically no value in dynamically
+               creating new files and uploading content to them.
         """
         _client = httpx.AsyncClient(
             auth=(
-                _create_auth(
+                auth
+                or _create_auth(
                     token=token,
-                    oauth_token=oauth_token,
                     user_email=user_email,
                     password=password,
                     certificate=certificate,
                     private_key=private_key,
                     private_key_password=private_key_password,
-                    client_id=client_id,
-                    client_secret=client_secret,
-                    redirect_uri=redirect_uri,
-                    refresh_token=refresh_token,
-                    oauth2_scope=oauth2_scope,
-                    on_auth_code=on_auth_code,
-                    on_token_refresh=on_token_refresh,
                 )
             ),
             timeout=timeout,

anaplan_sdk-0.4.4/anaplan_sdk/_auth.py

@@ -0,0 +1,363 @@
+import logging
+import os
+from base64 import b64encode
+from typing import Callable
+
+import httpx
+
+from ._oauth import _OAuthRequestFactory
+from .exceptions import AnaplanException, InvalidCredentialsException, InvalidPrivateKeyException
+
+logger = logging.getLogger("anaplan_sdk")
+
+
+class _AnaplanAuth(httpx.Auth):
+    requires_response_body = True
+
+    def __init__(self, token: str | None = None):
+        self._token: str = token or ""
+        if not token:
+            logger.info("Creating Authentication Token.")
+            with httpx.Client(timeout=15.0) as client:
+                self._parse_auth_response(client.send(self._build_auth_request()))
+
+    def _build_auth_request(self) -> httpx.Request:
+        raise NotImplementedError("Must be implemented in subclass.")
+
+    def auth_flow(self, request):
+        request.headers["Authorization"] = f"AnaplanAuthToken {self._token}"
+        response = yield request
+        if response.status_code == 401:
+            logger.info("Token expired, refreshing.")
+            auth_res = yield self._build_auth_request()
+            self._parse_auth_response(auth_res)
+            request.headers["Authorization"] = f"AnaplanAuthToken {self._token}"
+            yield request
+
+    def _parse_auth_response(self, response: httpx.Response) -> None:
+        if response.status_code == 401:
+            raise InvalidCredentialsException
+        if not response.is_success:
+            raise AnaplanException(f"Authentication failed: {response.status_code} {response.text}")
+        self._token = response.json()["tokenInfo"]["tokenValue"]
+
+
+class _StaticTokenAuth(httpx.Auth):
+    def __init__(self, token: str):
+        self._token = token
+
+    def auth_flow(self, request):
+        request.headers["Authorization"] = f"AnaplanAuthToken {self._token}"
+        response = yield request
+        if response.status_code == 401:
+            raise InvalidCredentialsException("Token is invalid or expired.")
+
+
+class _AnaplanBasicAuth(_AnaplanAuth):
+    def __init__(self, user_email: str, password: str, token: str | None = None):
+        self.user_email = user_email
+        self.password = password
+        super().__init__(token)
+
+    def _build_auth_request(self) -> httpx.Request:
+        cred = b64encode(f"{self.user_email}:{self.password}".encode()).decode()
+        return httpx.Request(
+            method="post",
+            url="https://auth.anaplan.com/token/authenticate",
+            headers={"Authorization": f"Basic {cred}"},
+        )
+
+
+class _AnaplanCertAuth(_AnaplanAuth):
+    requires_request_body = True
+
+    def __init__(
+        self,
+        certificate: str | bytes,
+        private_key: str | bytes,
+        private_key_password: str | bytes | None = None,
+        token: str | None = None,
+    ):
+        self.__set_certificate(certificate)
+        self.__set_private_key(private_key, private_key_password)
+        super().__init__(token)
+
+    def _build_auth_request(self) -> httpx.Request:
+        encoded_cert, encoded_string, encoded_signed_string = self._prep_credentials()
+        return httpx.Request(
+            method="post",
+            url="https://auth.anaplan.com/token/authenticate",
+            headers={
+                "Authorization": f"CACertificate {encoded_cert}",
+                "Content-Type": "application/json",
+            },
+            json={"encodedData": encoded_string, "encodedSignedData": encoded_signed_string},
+        )
+
+    def _prep_credentials(self) -> tuple[str, str, str]:
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.asymmetric.padding import PKCS1v15
+
+        message = os.urandom(150)
+        return (
+            b64encode(self._certificate).decode(),
+            b64encode(message).decode(),
+            b64encode(self._private_key.sign(message, PKCS1v15(), hashes.SHA512())).decode(),
+        )
+
+    def __set_certificate(self, certificate: str | bytes) -> None:
+        if isinstance(certificate, str):
+            if os.path.isfile(certificate):
+                with open(certificate, "rb") as f:
+                    self._certificate = f.read()
+            else:
+                self._certificate = certificate.encode()
+        else:
+            self._certificate = certificate
+
+    def __set_private_key(
+        self, private_key: str | bytes, private_key_password: str | bytes
+    ) -> None:
+        try:
+            from cryptography.exceptions import InvalidKey, UnsupportedAlgorithm
+            from cryptography.hazmat.backends import default_backend
+            from cryptography.hazmat.primitives import serialization
+            from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
+        except ImportError as e:
+            raise AnaplanException(
+                "cryptography is not available. Please install anaplan-sdk with the cert extra "
+                "`pip install anaplan-sdk[cert]` or install cryptography separately."
+            ) from e
+        try:
+            if isinstance(private_key, str):
+                if os.path.isfile(private_key):
+                    with open(private_key, "rb") as f:
+                        data = f.read()
+                else:
+                    data = private_key.encode()
+            else:
+                data = private_key
+            password = (
+                private_key_password.encode()
+                if isinstance(private_key_password, str)
+                else private_key_password
+            )
+            self._private_key: RSAPrivateKey = serialization.load_pem_private_key(
+                data, password, backend=default_backend()
+            )
+        except (IOError, InvalidKey, UnsupportedAlgorithm) as error:
+            raise InvalidPrivateKeyException from error
+
+
+class AnaplanLocalOAuth(_AnaplanAuth):
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: str,
+        token: dict[str, str] | None = None,
+        persist_token: bool = False,
+        authorization_url: str = "https://us1a.app.anaplan.com/auth/prelogin",
+        token_url: str = "https://us1a.app.anaplan.com/oauth/token",
+        validation_url: str = "https://auth.anaplan.com/token/validate",
+        scope: str = "openid profile email offline_access",
+        state_generator: Callable[[], str] | None = None,
+    ):
+        """
+        Initializes the AnaplanLocalOAuth class for OAuth2 authentication using the
+        Authorization Code Flow. This is a utility class for local development and requires user
+        interaction. For Web Applications and other scenarios, refer to `Oauth` or `AsyncOauth`.
+        This class will refresh the access token automatically when it expires.
+        :param client_id: The client ID of your Anaplan Oauth 2.0 application. This Application
+               must be an Authorization Code Grant application.
+        :param client_secret: The client secret of your Anaplan Oauth 2.0 application.
+        :param redirect_uri: The URL to which the user will be redirected after authorizing the
+               application.
+        :param token: The OAuth token dictionary containing at least the `access_token` and
+               `refresh_token`. If not provided, the user will be prompted to interactive
+               authorize the application, if `persist_token` is set to False or no valid refresh
+               token is found in the keyring.
+        :param persist_token: If set to True, the refresh token will be stored in the system's
+               keyring, allowing the application to use the same refresh token across multiple
+               runs. If set to False, the user will be prompted to authorize the application each
+               time. This requires the `keyring` extra to be installed. If a valid refresh token
+               is found in the keyring, it will be used instead of the given `token` parameter.
+        :param authorization_url: The URL to which the user will be redirected to authorize the
+               application. Defaults to the Anaplan Prelogin Page, where the user can select the
+               login method.
+        :param token_url: The URL to post the authorization code to in order to fetch the access
+               token.
+        :param validation_url: The URL to validate the access token.
+        :param scope: The scope of the access request.
+        :param state_generator: A callable that generates a random state string. You can optionally
+               pass this if you need to customize the state generation logic. If not provided,
+               the state will be generated by `oauthlib`.
+        """
+        self._oauth_token = token or {}
+        self._service_name = "anaplan_sdk"
+
+        if persist_token:
+            try:
+                import keyring
+
+                stored = keyring.get_password(self._service_name, self._service_name)
+                if stored:
+                    logger.info("Using persisted OAuth refresh token.")
+                    self._oauth_token = {"refresh_token": stored}
+                    self._token = ""  # Set to blank to trigger the super().__init__ auth request.
+            except ImportError as e:
+                raise AnaplanException(
+                    "keyring is not available. Please install anaplan-sdk with the keyring extra "
+                    "`pip install anaplan-sdk[keyring]` or install keyring separately."
+                ) from e
+        self._persist_token = persist_token
+        self._oauth = _OAuthRequestFactory(
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_uri=redirect_uri,
+            scope=scope,
+            authorization_url=authorization_url,
+            token_url=token_url,
+            validation_url=validation_url,
+            state_generator=state_generator,
+        )
+        if not self._oauth_token:
+            self.__auth_code_flow()
+        super().__init__(self._token)
+
+    @property
+    def token(self) -> dict[str, str]:
+        """
+        Returns the current token dictionary. You can safely use the `access_token`, but if you
+        must not use the `refresh_token` outside of this class, if you expect to use this instance
+        further. If you do use the `refresh_token` outside of this class, this will error on the
+        next attempt to refresh the token, as the `refresh_token` can only be used once.
+        """
+        return self._oauth_token
+
+    def _build_auth_request(self) -> httpx.Request:
+        return self._oauth.refresh_token_request(self._oauth_token["refresh_token"])
+
+    def _parse_auth_response(self, response: httpx.Response) -> None:
+        if response.status_code == 401:
+            raise InvalidCredentialsException
+        if not response.is_success:
+            raise AnaplanException(f"Authentication failed: {response.status_code} {response.text}")
+        self._oauth_token = response.json()
+        if self._persist_token:
+            import keyring
+
+            keyring.set_password(
+                self._service_name, self._service_name, self._oauth_token["refresh_token"]
+            )
+        self._token: str = self._oauth_token["access_token"]
+
+    def __auth_code_flow(self):
+        from oauthlib.oauth2 import OAuth2Error
+
+        try:
+            logger.info("Creating Authentication Token with OAuth2 Authorization Code Flow.")
+            url, _ = self._oauth.authorization_url()
+            authorization_response = input(
+                f"Please go to {url} and authorize the app.\n"
+                "Then paste the entire redirect URL here: "
+            )
+            with httpx.Client() as client:
+                res = client.send(self._oauth.token_request(authorization_response))
+            self._parse_auth_response(res)
+        except (httpx.HTTPError, ValueError, TypeError, OAuth2Error) as error:
+            raise InvalidCredentialsException("Error during OAuth2 authorization flow.") from error
+
+
+class AnaplanRefreshTokenAuth(_AnaplanAuth):
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        redirect_uri: str,
+        token: dict[str, str],
+        token_url: str = "https://us1a.app.anaplan.com/oauth/token",
+    ):
+        """
+        This class is a utility class for long-lived `Client` or `AsyncClient` instances that use
+        OAuth. This class will use the `access_token` until the first request fails with a 401
+        Unauthorized error, at which point it will attempt to refresh the `access_token` using the
+        `refresh_token`. If the refresh fails, it will raise an `InvalidCredentialsException`. The
+        `expires_in` field in the token dictionary is not considered. Manipulating any of the
+        fields in the token dictionary is not recommended and will likely have no effect.
+
+        **For its entire lifetime, you are ceding control of the token to this class.**
+        You must not use the same token simultaneously in multiple instances of this class or
+        outside of it, as this may lead to unexpected behavior when e.g. the refresh token is
+        used, which can only happen once and will lead to errors when attempting to use the same
+        refresh token again elsewhere.
+
+        If you need the token back before this instance is destroyed, you can use the `token`
+        method.
+
+        :param client_id: The client ID of your Anaplan Oauth 2.0 application. This Application
+               must be an Authorization Code Grant application.
+        :param client_secret: The client secret of your Anaplan Oauth 2.0 application.
+        :param redirect_uri: The URL to which the user will be redirected after authorizing the
+               application.
+        :param token: The OAuth token dictionary containing at least the `access_token` and
+               `refresh_token`.
+        :param token_url: The URL to post the refresh token request to in order to fetch the access
+               token.
+        """
+        if not isinstance(token, dict) or not all(
+            key in token for key in ("access_token", "refresh_token")
+        ):
+            raise ValueError(
+                "The token must at least contain 'access_token' and 'refresh_token' keys."
+            )
+        self._oauth_token = token
+        self._oauth = _OAuthRequestFactory(
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_uri=redirect_uri,
+            token_url=token_url,
+        )
+        super().__init__(self._oauth_token["access_token"])
+
+    @property
+    def token(self) -> dict[str, str]:
+        """
+        Returns the current OAuth token. You can safely use the `access_token`, but you
+        must not use the `refresh_token` outside of this class, if you expect to use this instance
+        further. If you do use the `refresh_token` outside of this class, this will error on the
+        next attempt to refresh the token, as the `refresh_token` can only be used once.
+        """
+        return self._oauth_token
+
+    def _build_auth_request(self) -> httpx.Request:
+        return self._oauth.refresh_token_request(self._oauth_token["refresh_token"])
+
+    def _parse_auth_response(self, response: httpx.Response) -> None:
+        if response.status_code == 401:
+            raise InvalidCredentialsException
+        if not response.is_success:
+            raise AnaplanException(f"Authentication failed: {response.status_code} {response.text}")
+        self._oauth_token = response.json()
+        self._token: str = self._oauth_token["access_token"]
+
+
+def _create_auth(
+    user_email: str | None = None,
+    password: str | None = None,
+    certificate: str | bytes | None = None,
+    private_key: str | bytes | None = None,
+    private_key_password: str | bytes | None = None,
+    token: str | None = None,
+) -> httpx.Auth:
+    if certificate and private_key:
+        return _AnaplanCertAuth(certificate, private_key, private_key_password, token)
+    if user_email and password:
+        return _AnaplanBasicAuth(user_email, password, token)
+    if token:
+        return _StaticTokenAuth(token)
+    raise ValueError(
+        "No valid authentication parameters provided. Please provide either:\n"
+        "- `user_email` and `password`, or\n"
+        "- `certificate` and `private_key`\n"
+    )