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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anaplan-sdk
-Version: 0.4.3a1
+Version: 0.4.4a1
 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.4a1/anaplan_sdk/__init__.py

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

{anaplan_sdk-0.4.3a1 → anaplan_sdk-0.4.4a1}/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.3a1 → anaplan_sdk-0.4.4a1}/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,26 +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 StaticTokenAuth(httpx.Auth):
+class _StaticTokenAuth(httpx.Auth):
     def __init__(self, token: str):
-        logger.warning("Using static token authentication. Tokens will not be refreshed.")
         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("Your token is invalid or expired.")
+            raise InvalidCredentialsException("Token is invalid or expired.")
 
 
-class AnaplanBasicAuth(_AnaplanAuth):
-    def __init__(self, user_email: str, password: str):
+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()
@@ -77,7 +73,7 @@ class AnaplanBasicAuth(_AnaplanAuth):
         )
 
 
-class AnaplanCertAuth(_AnaplanAuth):
+class _AnaplanCertAuth(_AnaplanAuth):
     requires_request_body = True
 
     def __init__(
@@ -85,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()
@@ -157,168 +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, _ = self._oauth.authorization_url()
+            authorization_response = 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,
-            )
-            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
 
 
+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,
     token: str | None = None,
-    oauth_token: dict[str, str] | None = None,
 ) -> httpx.Auth:
-    if token:
-        # TODO: If other parameters are provided that allow refreshing the token, use them to create
-        #  use them to create one of the other auth classes instead.
-        return StaticTokenAuth(token)
-    if oauth_token:
-        if not isinstance(oauth_token, dict) and all(
-            f in oauth_token for f in ("access_token", "refresh_token", "token_type", "scope")
-        ):
-            raise ValueError(
-                "oauth_token must be a dictionary with at least 'access_token', 'refresh_token', "
-                "'token_type', and 'scope' keys."
-            )
-        # TODO: If client_id, client_secret, and redirect_uri are provided, use them to create an
-        #  AnaplanOauth2AuthCodeAuth (extend to accept existing `access_token` instance. Else, use
-        #  the StaticTokenAuth directly.
-        return StaticTokenAuth(oauth_token["access_token"])
     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()