anaplan-sdk 0.4.2__py3-none-any.whl → 0.4.3a2__py3-none-any.whl

anaplan_sdk/__init__.py

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

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,13 +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,
+        token: str | None = None,
+        auth: httpx.Auth | None = None,
         timeout: float | httpx.Timeout = 30,
         retry_count: int = 2,
         status_poll_delay: int = 1,
@@ -65,84 +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,
                     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/_auth.py

@@ -1,14 +1,11 @@
-import asyncio
-import inspect
 import logging
 import os
-import threading
 from base64 import b64encode
-from concurrent.futures import ThreadPoolExecutor
-from typing import Any, Awaitable, Callable, Coroutine
+from typing import Awaitable, Callable
 
 import httpx
 
+from ._oauth import _OAuthRequestFactory
 from .exceptions import AnaplanException, InvalidCredentialsException, InvalidPrivateKeyException
 
 logger = logging.getLogger("anaplan_sdk")
@@ -22,12 +19,12 @@ AuthTokenRefreshCallback = (
 class _AnaplanAuth(httpx.Auth):
     requires_response_body = True
 
-    def __init__(self, pre_authed: bool = False):
-        if not pre_authed:
+    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:
-                res = client.send(self._build_auth_request())
-                self._parse_auth_response(res)
+                self._parse_auth_response(client.send(self._build_auth_request()))
 
     def _build_auth_request(self) -> httpx.Request:
         raise NotImplementedError("Must be implemented in subclass.")
@@ -47,14 +44,25 @@ class _AnaplanAuth(httpx.Auth):
             raise InvalidCredentialsException
         if not response.is_success:
             raise AnaplanException(f"Authentication failed: {response.status_code} {response.text}")
-        self._token: str = response.json()["tokenInfo"]["tokenValue"]
+        self._token = response.json()["tokenInfo"]["tokenValue"]
 
 
-class AnaplanBasicAuth(_AnaplanAuth):
-    def __init__(self, user_email: str, password: str):
+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__()
+        super().__init__(token)
 
     def _build_auth_request(self) -> httpx.Request:
         cred = b64encode(f"{self.user_email}:{self.password}".encode()).decode()
@@ -65,7 +73,7 @@ class AnaplanBasicAuth(_AnaplanAuth):
         )
 
 
-class AnaplanCertAuth(_AnaplanAuth):
+class _AnaplanCertAuth(_AnaplanAuth):
     requires_request_body = True
 
     def __init__(
@@ -73,10 +81,11 @@ class AnaplanCertAuth(_AnaplanAuth):
         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__()
+        super().__init__(token)
 
     def _build_auth_request(self) -> httpx.Request:
         encoded_cert, encoded_string, encoded_signed_string = self._prep_credentials()
@@ -145,150 +154,142 @@ class AnaplanCertAuth(_AnaplanAuth):
             raise InvalidPrivateKeyException from error
 
 
-class AnaplanOauth2AuthCodeAuth(_AnaplanAuth):
+class AnaplanOAuthCodeAuth(_AnaplanAuth):
     def __init__(
         self,
         client_id: str,
         client_secret: str,
-        redirect_uri: str,
-        refresh_token: str | None = None,
+        redirect_url: str,
+        token: dict[str, str] | None = None,
+        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",
-        on_auth_code: AuthCodeCallback = None,
-        on_token_refresh: AuthTokenRefreshCallback = None,
+        state_generator: Callable[[], str] | None = None,
     ):
-        try:
-            from oauthlib.oauth2 import WebApplicationClient
-        except ImportError as e:
-            raise AnaplanException(
-                "oauthlib is not available. Please install anaplan-sdk with the oauth extra "
-                "`pip install anaplan-sdk[oauth]` or install oauthlib separately."
-            ) from e
-        self._oauth = WebApplicationClient(
-            client_id=client_id, client_secret=client_secret, refresh_token=refresh_token
+        """
+        Initializes the AnaplanOAuthCodeAuth 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_url: The URL to which the user will be redirected after authorizing the
+               application.
+        :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._oauth = _OAuthRequestFactory(
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_url=redirect_url,
+            scope=scope,
+            authorization_url=authorization_url,
+            token_url=token_url,
+            validation_url=validation_url,
+            state_generator=state_generator,
         )
-        self._token_url = "https://us1a.app.anaplan.com/oauth/token"
-        self._client_id = client_id
-        self._client_secret = client_secret
-        self._redirect_uri = redirect_uri
-        self._refresh_token = refresh_token
-        self._scope = scope
-        self._id_token = None
-        self._on_auth_code = on_auth_code
-        self._on_token_refresh = on_token_refresh
-        if not refresh_token:
+        if not token:
             self.__auth_code_flow()
-        super().__init__(pre_authed=not refresh_token)
+        super().__init__(self._token)
 
     def _build_auth_request(self) -> httpx.Request:
-        url, headers, body = self._oauth.prepare_refresh_token_request(
-            token_url=self._token_url,
-            refresh_token=self._refresh_token,
-            client_secret=self._client_secret,
-            client_id=self._client_id,
-        )
-        return httpx.Request(method="post", url=url, headers=headers, content=body)
+        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}")
-        token = response.json()
-        self._token = token["access_token"]
-        self._refresh_token = token["refresh_token"]
-        if self._on_token_refresh:
-            _run_callback(self._on_token_refresh, token)
-        self._id_token = token.get("id_token")
+        self._oauth_token = response.json()
+        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.prepare_authorization_request(
-                "https://us1a.app.anaplan.com/auth/prelogin",
-                redirect_url=self._redirect_uri,
-                scope=self._scope,
-            )
-            authorization_response = (
-                _run_callback(self._on_auth_code, url)
-                if self._on_auth_code
-                else input(
-                    f"Please go to {url} and authorize the app.\n"
-                    "Then paste the entire redirect URL here: "
-                )
-            )
-            url, headers, body = self._oauth.prepare_token_request(
-                token_url=self._token_url,
-                redirect_url=self._redirect_uri,
-                authorization_response=authorization_response,
-                client_secret=self._client_secret,
+            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: "
             )
-            self._parse_auth_response(httpx.post(url=url, headers=headers, content=body))
+            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
 
 
-def create_auth(
+class AnaplanRefreshTokenAuth(_AnaplanAuth):
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        redirect_url: 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. It expects that you have a valid OAuth token with a refresh token, which will be used
+        to refresh the access token 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_url: The URL to which the user will be redirected after authorizing the
+               application.
+        :param token_url: The URL to post the refresh token request to in order to fetch the access
+               token.
+        """
+        self._oauth_token = token
+        self._oauth = _OAuthRequestFactory(
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_url=redirect_url,
+            token_url=token_url,
+        )
+        super().__init__(self._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,
-    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,
-) -> _AnaplanAuth:
+    token: str | None = None,
+) -> httpx.Auth:
     if certificate and private_key:
-        return AnaplanCertAuth(certificate, private_key, private_key_password)
+        return _AnaplanCertAuth(certificate, private_key, private_key_password, token)
     if user_email and password:
-        return AnaplanBasicAuth(user_email=user_email, password=password)
-    if client_id and client_secret and redirect_uri:
-        return AnaplanOauth2AuthCodeAuth(
-            client_id=client_id,
-            client_secret=client_secret,
-            redirect_uri=redirect_uri,
-            refresh_token=refresh_token,
-            scope=oauth2_scope,
-            on_auth_code=on_auth_code,
-            on_token_refresh=on_token_refresh,
-        )
+        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, or\n"
-        "- client_id, client_secret, and redirect_uri"
+        "- `user_email` and `password`, or\n"
+        "- `certificate` and `private_key`\n"
     )
-
-
-def _run_callback(func, *arg, **kwargs):
-    if not inspect.iscoroutinefunction(func):
-        return func(*arg, **kwargs)
-    coro = func(*arg, **kwargs)
-    try:
-        loop = asyncio.get_running_loop()
-    except RuntimeError:
-        return asyncio.run(coro)
-
-    if threading.current_thread() is threading.main_thread():
-        if not loop.is_running():
-            return loop.run_until_complete(coro)
-        else:
-            with ThreadPoolExecutor() as pool:
-                future = pool.submit(__run_in_new_loop, coro)
-                return future.result(timeout=30)
-    else:
-        return asyncio.run_coroutine_threadsafe(coro, loop).result()
-
-
-def __run_in_new_loop(coroutine: Coroutine[Any, Any, Any]):
-    new_loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(new_loop)
-    try:
-        return new_loop.run_until_complete(coroutine)
-    finally:
-        new_loop.close()

anaplan_sdk/_clients/_bulk.py

@@ -3,12 +3,12 @@ import multiprocessing
 import time
 from concurrent.futures import ThreadPoolExecutor
 from copy import copy
-from typing import Callable, Iterator
+from typing import Iterator
 
 import httpx
 from typing_extensions import Self
 
-from anaplan_sdk._auth import create_auth
+from anaplan_sdk._auth import _create_auth
 from anaplan_sdk._base import _BaseClient, action_url
 from anaplan_sdk.exceptions import AnaplanActionError, InvalidIdentifierException
 from anaplan_sdk.models import (
@@ -34,14 +34,8 @@ logger = logging.getLogger("anaplan_sdk")
 
 class Client(_BaseClient):
     """
-    A synchronous 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).
+    Synchronous Anaplan Client. For guides and examples
+    refer to https://vinzenzklass.github.io/anaplan-sdk.
     """
 
     def __init__(
@@ -53,13 +47,8 @@ class Client(_BaseClient):
         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: Callable[[str], str] | None = None,
-        on_token_refresh: Callable[[dict[str, str]], None] | 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,
@@ -68,75 +57,56 @@ class Client(_BaseClient):
         allow_file_creation: bool = False,
     ) -> None:
         """
-        A synchronous 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).
+        Synchronous 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.
-        :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.
+               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_parallel: Whether to upload the chunks in parallel. Defaults to True. **If
-                                you are heavily network bound or are experiencing rate limiting
-                                issues, set this to False.**
+        :param upload_parallel: Whether to upload chunks in parallel when uploading files.
         :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.Client(
             auth=(
-                create_auth(
+                auth
+                or _create_auth(
+                    token=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/_oauth.py

@@ -0,0 +1,257 @@
+import logging
+from typing import Callable
+
+import httpx
+
+from .exceptions import AnaplanException, InvalidCredentialsException
+
+logger = logging.getLogger("anaplan_sdk")
+
+
+class _BaseOauth:
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        redirect_url: str,
+        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 OAuth Client. This class provides the two utilities needed to implement
+        the OAuth 2.0 authorization code flow for user-facing Web Applications. It differs from the
+        other Authentication Strategies in this SDK in two main ways:
+
+        1. You must implement the actual authentication flow in your application. You cannot pass
+        the credentials directly to the `Client` or `AsyncClient`, and this class does not
+        implement the SDK internal authentication flow, i.e. it does not subclass `httpx.Auth`.
+
+        2. You then simply pass the resulting token to the `Client` or `AsyncClient`, rather than
+        passing the credentials directly, which will internally construct an `httpx.Auth` instance
+
+        Note that this class exist for convenience only, and you can implement the OAuth 2.0 Flow
+        yourself in your preferred library, or bring an existing implementation. For details on the
+        Anaplan OAuth 2.0 Flow, see the [the Docs](https://anaplanoauth2service.docs.apiary.io/#reference/overview-of-the-authorization-code-grant).
+        :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_url: The URL to which the user will be redirected after authorizing the
+               application.
+        :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._client_id = client_id
+        self._client_secret = client_secret
+        self._redirect_url = redirect_url
+        self._authorization_url = authorization_url
+        self._token_url = token_url
+        self._validation_url = validation_url
+        self._scope = scope
+
+        try:
+            from oauthlib.oauth2 import WebApplicationClient
+        except ImportError as e:
+            raise AnaplanException(
+                "oauthlib is not available. Please install anaplan-sdk with the oauth extra "
+                "`pip install anaplan-sdk[oauth]` or install oauthlib separately."
+            ) from e
+        self._oauth = WebApplicationClient(client_id=client_id, client_secret=client_secret)
+        self._state_generator = state_generator if state_generator else self._oauth.state_generator
+
+    def authorization_url(
+        self, authorization_url: str | None = None, state: str | None = None
+    ) -> tuple[str, str]:
+        """
+        Generates the authorization URL for the OAuth 2.0 flow.
+        :param authorization_url: You can optionally pass a custom authorization URL. This is
+               useful if you want to redirect i.e. redirect the user directly to the Anaplan login
+               page rather than the Prelogin page in only one scenario, while still reusing the
+               Client.
+        :param state: You can optionally pass a custom state string. If not provided, a random
+                state string will be generated by the `oauthlib` library, or by the
+                `state_generator` callable if provided.
+        :return: A tuple containing the authorization URL and the state string.
+        """
+        auth_url = authorization_url or self._authorization_url
+        state = state or self._state_generator()
+        url, _, _ = self._oauth.prepare_authorization_request(
+            auth_url, state, self._redirect_url, self._scope
+        )
+        return url, state
+
+    def _token_request(self, authorization_response: str) -> httpx.Request:
+        url, headers, body = self._oauth.prepare_token_request(
+            authorization_response=authorization_response,
+            token_url=self._token_url,
+            redirect_url=self._redirect_url,
+            client_secret=self._client_secret,
+        )
+        return httpx.Request(method="POST", url=url, headers=headers, content=body)
+
+    def _refresh_token_request(self, refresh_token: str) -> httpx.Request:
+        url, headers, body = self._oauth.prepare_refresh_token_request(
+            self._token_url,
+            refresh_token=refresh_token,
+            client_id=self._client_id,
+            client_secret=self._client_secret,
+        )
+        return httpx.Request(method="POST", url=url, headers=headers, content=body)
+
+    def _parse_response(self, response: httpx.Response) -> dict[str, str]:
+        if response.status_code == 401:
+            raise InvalidCredentialsException
+        if not response.is_success:
+            raise AnaplanException(
+                f"Token request for Client {self._client_id} failed: "
+                f"{response.status_code} {response.text}"
+            )
+        return response.json()
+
+
+class _OAuthRequestFactory(_BaseOauth):
+    def token_request(self, authorization_response: str) -> httpx.Request:
+        return self._token_request(authorization_response)
+
+    def refresh_token_request(self, refresh_token: str) -> httpx.Request:
+        return self._refresh_token_request(refresh_token)
+
+
+class AsyncOauth(_BaseOauth):
+    """
+    Asynchronous Variant of the Anaplan OAuth client for interactive OAuth Flows in Web
+    Applications.
+    """
+
+    async def fetch_token(self, authorization_response: str) -> dict[str, str]:
+        """
+        Fetches the token using the authorization response from the OAuth 2.0 flow.
+        :param authorization_response: The full URL that the user was redirected to after
+               authorizing the application. This URL will contain the authorization code and state.
+        :return: The token as a dictionary containing the access token, refresh token, scope,
+                 expires_in, and type.
+        """
+        from oauthlib.oauth2 import OAuth2Error
+
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.send(self._token_request(authorization_response))
+            return self._parse_response(response)
+        except (httpx.HTTPError, ValueError, TypeError, OAuth2Error) as error:
+            logger.error(error)
+            raise AnaplanException("Error during token creation.") from error
+
+    async def validate_token(self, token: str) -> dict[str, str | dict[str, str]]:
+        """
+        Validates the provided token by checking its validity with the Anaplan Authentication API.
+        If the token is not valid, an `InvalidCredentialsException` is raised.
+        :param token: The access token to validate.
+        :return: The Token information as a dictionary containing the token's details.
+        """
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(
+                    url=self._validation_url, headers={"Authorization": f"AnaplanAuthToken {token}"}
+                )
+            return self._parse_response(response)
+        except httpx.HTTPError as error:
+            logger.error(error)
+            raise AnaplanException("Error during token validation.") from error
+
+    async def refresh_token(self, refresh_token: str) -> dict[str, str]:
+        """
+        Refreshes the token using a refresh token.
+        :param refresh_token: The refresh token to use for refreshing the access token.
+        :return: The new token as a dictionary containing the access token, refresh token, scope,
+                 expires_in, and type.
+        """
+        from oauthlib.oauth2 import OAuth2Error
+
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.send(self._refresh_token_request(refresh_token))
+            return self._parse_response(response)
+        except (httpx.HTTPError, ValueError, TypeError, OAuth2Error) as error:
+            logger.error(error)
+            raise AnaplanException("Error during token refresh.") from error
+
+
+class Oauth(_BaseOauth):
+    """
+    Synchronous Variant of the Anaplan OAuth client for interactive OAuth Flows in Web
+    Applications.
+    """
+
+    def fetch_token(self, authorization_response: str) -> dict[str, str]:
+        """
+        Fetches the token using the authorization response from the OAuth 2.0 flow.
+        :param authorization_response: The full URL that the user was redirected to after
+               authorizing the application. This URL will contain the authorization code and state.
+        :return: The token as a dictionary containing the access token, refresh token, scope,
+                 expires_in, and type.
+        """
+        from oauthlib.oauth2 import OAuth2Error
+
+        try:
+            url, headers, body = self._oauth.prepare_token_request(
+                authorization_response=authorization_response,
+                token_url=self._token_url,
+                redirect_url=self._redirect_url,
+                client_secret=self._client_secret,
+            )
+            with httpx.Client() as client:
+                response = client.post(url=url, headers=headers, content=body)
+            return self._parse_response(response)
+        except (httpx.HTTPError, ValueError, TypeError, OAuth2Error) as error:
+            logger.error(error)
+            raise AnaplanException("Error during token creation.") from error
+
+    def validate_token(self, token: str) -> dict[str, str | dict[str, str]]:
+        """
+        Validates the provided token by checking its validity with the Anaplan Authentication API.
+        If the token is not valid, an `InvalidCredentialsException` is raised.
+        :param token: The access token to validate.
+        :return: The Token information as a dictionary containing the token's details.
+        """
+        try:
+            with httpx.Client() as client:
+                response = client.get(
+                    url=self._validation_url, headers={"Authorization": f"AnaplanAuthToken {token}"}
+                )
+            return self._parse_response(response)
+        except httpx.HTTPError as error:
+            logger.error(error)
+            raise AnaplanException("Error during token validation.") from error
+
+    def refresh_token(self, refresh_token: str) -> dict[str, str]:
+        """
+        Refreshes the token using a refresh token.
+        :param refresh_token: The refresh token to use for refreshing the access token.
+        :return: The new token as a dictionary containing the access token, refresh token, scope,
+                 expires_in, and type.
+        """
+        from oauthlib.oauth2 import OAuth2Error
+
+        try:
+            url, headers, body = self._oauth.prepare_refresh_token_request(
+                self._token_url,
+                refresh_token=refresh_token,
+                client_id=self._client_id,
+                client_secret=self._client_secret,
+            )
+            with httpx.Client() as client:
+                response = client.post(url=url, headers=headers, content=body)
+            return self._parse_response(response)
+        except (httpx.HTTPError, ValueError, TypeError, OAuth2Error) as error:
+            logger.error(error)
+            raise AnaplanException("Error during token refresh.") from error

{anaplan_sdk-0.4.2.dist-info → anaplan_sdk-0.4.3a2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anaplan-sdk
-Version: 0.4.2
+Version: 0.4.3a2
 Summary: Streamlined Python Interface for Anaplan
 Project-URL: Homepage, https://vinzenzklass.github.io/anaplan-sdk/
 Project-URL: Repository, https://github.com/VinzenzKlass/anaplan-sdk

{anaplan_sdk-0.4.2.dist-info → anaplan_sdk-0.4.3a2.dist-info}/RECORD

@@ -1,18 +1,19 @@
-anaplan_sdk/__init__.py,sha256=5fr-SZSsH6f3vkRUTDoK6xdAN31cCpe9Mwz2VNu47Uw,134
-anaplan_sdk/_auth.py,sha256=0htPrOYXDb2CCm4ZkwKQ4Zi26fsK6D0OIBiQdR6ESm8,11817
+anaplan_sdk/__init__.py,sha256=lDFhs0IobOH7a34jqtAgcj9X1bR5hnFRkkkCl_vPHpo,357
+anaplan_sdk/_auth.py,sha256=u7AHeTAWJnOQo7LtdgCmRY1CeITizX_Hqg1aKoZs9EE,12684
 anaplan_sdk/_base.py,sha256=9CdLshORWsLixOyoFa3A0Bka5lhLwlZrQI5sEdBcGFI,12298
+anaplan_sdk/_oauth.py,sha256=FGOStYTtlTruQQDcDjN8JEEKEiEpdPwJM-chCrG1oao,12636
 anaplan_sdk/exceptions.py,sha256=ALkA9fBF0NQ7dufFxV6AivjmHyuJk9DOQ9jtJV2n7f0,1809
 anaplan_sdk/_async_clients/__init__.py,sha256=pZXgMMg4S9Aj_pxQCaSiPuNG-sePVGBtNJ0133VjqW4,364
 anaplan_sdk/_async_clients/_alm.py,sha256=O1_r-O1tNDq7vXRwE2UEFE5S2bPmPh4IAQPQ8bmZfQE,3297
 anaplan_sdk/_async_clients/_audit.py,sha256=a92RY0B3bWxp2CCAWjzqKfvBjG1LJGlai0Hn5qmwgF8,2312
-anaplan_sdk/_async_clients/_bulk.py,sha256=APhgKE4Deh90lm8rcCJMyQTJNMHAXFCKkqnGV_lAtgY,26908
+anaplan_sdk/_async_clients/_bulk.py,sha256=j0yMoM8NWQH9BsSQ4LRYt8djfd1d11vkjNfU8pUeGLU,23737
 anaplan_sdk/_async_clients/_cloud_works.py,sha256=KPX9W55SF6h8fJd4Rx-HLq6eaRA-Vo3rFu343UiiaGQ,16642
 anaplan_sdk/_async_clients/_cw_flow.py,sha256=ZTNAbKDwb59Wg3u68hbtt1kpd-LNz9K0sftT-gvYzJQ,3651
 anaplan_sdk/_async_clients/_transactional.py,sha256=Mvr7OyBPjQRpBtzkJNfRzV4aNCzUiaYmm0zQubo62Wo,8035
 anaplan_sdk/_clients/__init__.py,sha256=FsbwvZC1FHrxuRXwbPxUzbhz_lO1DpXIxEOjx6-3QuA,219
 anaplan_sdk/_clients/_alm.py,sha256=UAdQxgHfax-VquC0YtbqrRBku2Rn35tVgwJdxYFScps,3202
 anaplan_sdk/_clients/_audit.py,sha256=xQQiwWIb4QQefolPvxNwBFE-pkRzzi8fYPyewjF63lc,2181
-anaplan_sdk/_clients/_bulk.py,sha256=4JkuutqCo7yt3Ik2f90ixkfPw1r-7TOq9xg1MUZ5es8,25568
+anaplan_sdk/_clients/_bulk.py,sha256=nlsZHK8vjhvyC0auRuqyvJVvTISPqj9EIHBYLoqSpOc,23354
 anaplan_sdk/_clients/_cloud_works.py,sha256=KAMnLoeMJ2iwMXlDSbKynCE57BtkCfOgM5O8wT1kkSs,16291
 anaplan_sdk/_clients/_cw_flow.py,sha256=5IFWFT-qbyGvaSOOtaFOjHnOlyYbj4Rj3xiavfTlm8c,3527
 anaplan_sdk/_clients/_transactional.py,sha256=YUVbA54uhMloQcahwMtmZO3YooO6qQzwZN3ZRSu_z_c,7976
@@ -23,7 +24,7 @@ anaplan_sdk/models/_bulk.py,sha256=dHP3kMvsKONCZS6mHB271-wp2S4P3rM874Ita8TzABU,8
 anaplan_sdk/models/_transactional.py,sha256=_0UbVR9D5QABI29yloYrJTSgL-K0EU7PzPeJu5LdhnY,4854
 anaplan_sdk/models/cloud_works.py,sha256=nfn_LHPR-KmW7Tpvz-5qNCzmR8SYgvsVV-lx5iDlyqI,19425
 anaplan_sdk/models/flows.py,sha256=SuLgNj5-2SeE3U1i8iY8cq2IkjuUgd_3M1n2ENructk,3625
-anaplan_sdk-0.4.2.dist-info/METADATA,sha256=oyd3terF5C2LV55DARCix6LSpCJ6ch7jlub7nKE6wDo,3543
-anaplan_sdk-0.4.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-anaplan_sdk-0.4.2.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
-anaplan_sdk-0.4.2.dist-info/RECORD,,
+anaplan_sdk-0.4.3a2.dist-info/METADATA,sha256=OcYO34dO9jwqeirqm1BuB-UBB9LwjkdYP7IL4XdHzsg,3545
+anaplan_sdk-0.4.3a2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+anaplan_sdk-0.4.3a2.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+anaplan_sdk-0.4.3a2.dist-info/RECORD,,