anaplan-sdk 0.4.4a2__tar.gz → 0.4.4a4__tar.gz

{anaplan_sdk-0.4.4a2 → anaplan_sdk-0.4.4a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anaplan-sdk
-Version: 0.4.4a2
+Version: 0.4.4a4
 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

{anaplan_sdk-0.4.4a2 → anaplan_sdk-0.4.4a4}/anaplan_sdk/__init__.py

@@ -1,12 +1,12 @@
 from ._async_clients import AsyncClient
-from ._auth import AnaplanOAuthCodeAuth, AnaplanRefreshTokenAuth
+from ._auth import AnaplanLocalOAuth, AnaplanRefreshTokenAuth
 from ._clients import Client
 from ._oauth import AsyncOauth, Oauth
 
 __all__ = [
     "AsyncClient",
     "Client",
-    "AnaplanOAuthCodeAuth",
+    "AnaplanLocalOAuth",
     "AnaplanRefreshTokenAuth",
     "AsyncOauth",
     "Oauth",

{anaplan_sdk-0.4.4a2 → anaplan_sdk-0.4.4a4}/anaplan_sdk/_auth.py

@@ -1,20 +1,16 @@
 import logging
 import os
 from base64 import b64encode
-from typing import Awaitable, Callable
+from typing import Callable
 
 import httpx
+import keyring
 
 from ._oauth import _OAuthRequestFactory
 from .exceptions import AnaplanException, InvalidCredentialsException, InvalidPrivateKeyException
 
 logger = logging.getLogger("anaplan_sdk")
 
-AuthCodeCallback = (Callable[[str], str] | Callable[[str], Awaitable[str]]) | None
-AuthTokenRefreshCallback = (
-    Callable[[dict[str, str]], None] | Callable[[dict[str, str]], Awaitable[None]]
-) | None
-
 
 class _AnaplanAuth(httpx.Auth):
     requires_response_body = True
@@ -154,13 +150,14 @@ class _AnaplanCertAuth(_AnaplanAuth):
             raise InvalidPrivateKeyException from error
 
 
-class AnaplanOAuthCodeAuth(_AnaplanAuth):
+class AnaplanLocalOAuth(_AnaplanAuth):
     def __init__(
         self,
         client_id: str,
         client_secret: str,
-        redirect_url: 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",
@@ -168,15 +165,24 @@ class AnaplanOAuthCodeAuth(_AnaplanAuth):
         state_generator: Callable[[], str] | None = None,
     ):
         """
-        Initializes the AnaplanOAuthCodeAuth class for OAuth2 authentication using the
+        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_url: The URL to which the user will be redirected after authorizing the
+        :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.
@@ -185,25 +191,51 @@ class AnaplanOAuthCodeAuth(_AnaplanAuth):
         :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`.
+               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 = None  # Set to None 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_url=redirect_url,
+            redirect_uri=redirect_uri,
             scope=scope,
             authorization_url=authorization_url,
             token_url=token_url,
             validation_url=validation_url,
             state_generator=state_generator,
         )
-        if not token:
+        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"])
 
@@ -213,6 +245,10 @@ class AnaplanOAuthCodeAuth(_AnaplanAuth):
         if not response.is_success:
             raise AnaplanException(f"Authentication failed: {response.status_code} {response.text}")
         self._oauth_token = response.json()
+        if self._persist_token:
+            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):
@@ -237,34 +273,62 @@ class AnaplanRefreshTokenAuth(_AnaplanAuth):
         self,
         client_id: str,
         client_secret: str,
-        redirect_url: 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. 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.
+        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_url: The URL to which the user will be redirected after authorizing the
+        :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) and 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_url=redirect_url,
+            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 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"])
 

{anaplan_sdk-0.4.4a2 → anaplan_sdk-0.4.4a4}/anaplan_sdk/_oauth.py

@@ -13,7 +13,7 @@ class _BaseOauth:
         self,
         client_id: str,
         client_secret: str,
-        redirect_url: str,
+        redirect_uri: 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",
@@ -38,7 +38,7 @@ class _BaseOauth:
         :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
+        :param redirect_uri: 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
@@ -53,7 +53,7 @@ class _BaseOauth:
         """
         self._client_id = client_id
         self._client_secret = client_secret
-        self._redirect_url = redirect_url
+        self._redirect_uri = redirect_uri
         self._authorization_url = authorization_url
         self._token_url = token_url
         self._validation_url = validation_url
@@ -86,7 +86,7 @@ class _BaseOauth:
         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
+            auth_url, state, self._redirect_uri, self._scope
         )
         return url, state
 
@@ -94,7 +94,7 @@ class _BaseOauth:
         url, headers, body = self._oauth.prepare_token_request(
             authorization_response=authorization_response,
             token_url=self._token_url,
-            redirect_url=self._redirect_url,
+            redirect_url=self._redirect_uri,
             client_secret=self._client_secret,
         )
         return httpx.Request(method="POST", url=url, headers=headers, content=body)
@@ -206,7 +206,7 @@ class Oauth(_BaseOauth):
             url, headers, body = self._oauth.prepare_token_request(
                 authorization_response=authorization_response,
                 token_url=self._token_url,
-                redirect_url=self._redirect_url,
+                redirect_url=self._redirect_uri,
                 client_secret=self._client_secret,
             )
             with httpx.Client() as client:

{anaplan_sdk-0.4.4a2 → anaplan_sdk-0.4.4a4}/anaplan_sdk/models/_bulk.py

@@ -145,10 +145,10 @@ class TaskSummary(AnaplanModel):
 
 
 class TaskResultDetail(AnaplanModel):
-    local_message_text: str = Field(description="Error message text.")
+    local_message_text: str | None = Field(None, description="Error message text.")
     occurrences: int = Field(0, description="The number of occurrences of this error.")
     type: str = Field(description="The type of this error.")
-    values: list[str] = Field([], description="Further error information if available.")
+    values: list[str | None] = Field([], description="Further error information if available.")
 
 
 class TaskResult(AnaplanModel):

{anaplan_sdk-0.4.4a2 → anaplan_sdk-0.4.4a4}/docs/guides/authentication.md

@@ -7,9 +7,9 @@ There are three main ways to authenticate with Anaplan.
 - OAuth2
 
 Anaplan SDK supports all of them, though Basic Authentication is strictly not recommended for production use.
-Certificate
-Authentication is currently the most suitable for production use, since the Anaplan OAuth 2.0 implementation does not
-support the `client_credentials` grant type. This means you will have to manually manage the Refresh Token.
+Certificate Authentication is currently the most suitable for production use, since the Anaplan OAuth 2.0 
+implementation does not support the `client_credentials` grant type. This means you will have to manually manage the 
+refresh Token if you choose to use OAuth2.
 
 ## Basic Authentication
 
@@ -45,7 +45,7 @@ maintain and error-prone.
 
 Certificate Authentication is the most suitable for production use. It uses an X.509 S/MIME Certificate (aka. Client Certificate or HTTPS-Certificate) and Private Key. The Process of acquiring such a certificate is well [documented](https://help.anaplan.com/procure-ca-certificates-47842267-2cb3-4e38-90bf-13b1632bcd44). Anaplan does not support self-signed certificates, so you will need to procure a certificate from a trusted Certificate Authority (CA).
 
-??? tip "Requires Extra"
+???+ tip "Requires Extra"
     If you want to use certificate authentication, you need to install the `cert` extra:
     === "pip"
         ```shell
@@ -96,7 +96,8 @@ in which the authentication flow must occur outside the SDK for the user to log
 
 These Classes exist for convenience only, and you can use any other Library to handle the Oauth2 flow.
 
-An example for FastAPI is shown below, but you can use any other Web Framework.
+A minimal, illustrative example for FastAPI is shown below, but you can use any other Web Framework. This will not run
+until you implement the TODOs in a suitable way for your purpose.
 
 ??? tip "Requires Extra"
     If you want to use OAuth2 authentication, you need to install the `oauth` extra:
@@ -114,7 +115,6 @@ An example for FastAPI is shown below, but you can use any other Web Framework.
         ```
     This will install [OAuthLib](https://oauthlib.readthedocs.io/en/latest/index.html) to securely construct the authentication request.
 
-
 ```python
 import os
 from typing import Annotated
@@ -127,7 +127,7 @@ from anaplan_sdk import AsyncClient, AsyncOauth, exceptions
 _oauth = AsyncOauth(
     client_id=os.environ["OAUTH_CLIENT_ID"],
     client_secret=os.environ["OAUTH_CLIENT_SECRET"],
-    redirect_url="https://vinzenzklass.github.io/anaplan-sdk/oauth/callback",
+    redirect_uri="https://vinzenzklass.github.io/anaplan-sdk/oauth/callback",
 )
 
 app = FastAPI()
@@ -182,7 +182,7 @@ when it expires.
             token=token,
             client_id=os.environ["OAUTH_CLIENT_ID"],
             client_secret=os.environ["OAUTH_CLIENT_SECRET"],
-            redirect_url="https://vinzenzklass.github.io/anaplan-sdk",
+            redirect_uri="https://vinzenzklass.github.io/anaplan-sdk",
         )
     )
     ```
@@ -193,7 +193,7 @@ when it expires.
             token=token,
             client_id=os.environ["OAUTH_CLIENT_ID"],
             client_secret=os.environ["OAUTH_CLIENT_SECRET"],
-            redirect_url="https://vinzenzklass.github.io/anaplan-sdk",
+            redirect_uri="https://vinzenzklass.github.io/anaplan-sdk",
         )
     )
     ```
@@ -201,10 +201,10 @@ when it expires.
 
 ## OAuth for Local Applications
 
-For local applications, you can use `AnaplanOAuthCodeAuth` Class to handle the initial Oauth2 `authorization_code` flow 
+For local applications, you can use `AnaplanLocalOAuth` Class to handle the initial Oauth2 `authorization_code` flow 
 and the subsequent token refreshes.
 
-??? tip "Requires Extra"
+???+ tip "Requires Extra"
     If you want to use OAuth2 authentication, you need to install the `oauth` extra:
     === "pip"
         ```shell
@@ -223,20 +223,20 @@ and the subsequent token refreshes.
 === "Synchronous"
     ```python
     anaplan = Client(
-        auth=AnaplanOAuthCodeAuth(
+        auth=AnaplanLocalOAuth(
             client_id=os.environ["OAUTH_CLIENT_ID"],
             client_secret=os.environ["OAUTH_CLIENT_SECRET"],
-            redirect_url="https://vinzenzklass.github.io/anaplan-sdk",
+            redirect_uri="https://vinzenzklass.github.io/anaplan-sdk",
         )
     )
     ```
 === "Asynchronous"
     ```python
     anaplan = AsyncClient(
-        auth=AnaplanOAuthCodeAuth(
+        auth=AnaplanLocalOAuth(
             client_id=os.environ["OAUTH_CLIENT_ID"],
             client_secret=os.environ["OAUTH_CLIENT_SECRET"],
-            redirect_url="https://vinzenzklass.github.io/anaplan-sdk",
+            redirect_uri="https://vinzenzklass.github.io/anaplan-sdk",
         )
     )
     ```
@@ -248,6 +248,89 @@ will need to copy the entire redirect URI from your browser and paste it into th
     Unfortunately, registering localhost redirect URIs is not supported by Anaplan. This means we cannot intercept the
     redirect URI and extract the `authorization_code` automatically. This is a limitation of Anaplan's OAuth2 implementation. See [this Community Note](https://community.anaplan.com/discussion/156599/oauth-rediredt-url-port-for-desktop-apps).
 
+## Persisting OAuth Tokens
+
+The SDK provides the ability to persist OAuth refresh tokens between sessions using the system's secure keyring for 
+local applications. This allows you to avoid having to re-authenticate every time you run your application while using 
+OAuth2. 
+
+???+ tip "Requires Extras"
+    If you want to use persisting Tokens, you need to additionally install the `keyring` extra:
+    === "pip"
+        ```shell
+        pip install anaplan-sdk[oauth,keyring]
+        ```
+    ===+ "uv"
+        ```shell
+        uv add anaplan-sdk[oauth,keyring]
+        ```
+    === "Poetry"
+        ```shell
+        poetry add anaplan-sdk[oauth,keyring]
+        ```
+
+    This will install [Keyring](https://github.com/jaraco/keyring) to securely store refresh tokens.
+
+To enable token persistence, set the `persist_token=True` parameter when creating an `AnaplanLocalOAuth` instance:
+
+=== "Synchronous"
+    ```python
+    anaplan = Client(
+        auth=AnaplanLocalOAuth(
+            client_id=os.environ["OAUTH_CLIENT_ID"],
+            client_secret=os.environ["OAUTH_CLIENT_SECRET"],
+            redirect_uri="https://vinzenzklass.github.io/anaplan-sdk",
+            persist_token=True,
+        )
+    )
+    ```
+=== "Asynchronous"
+    ```python
+    anaplan = AsyncClient(
+        auth=AnaplanLocalOAuth(
+            client_id=os.environ["OAUTH_CLIENT_ID"],
+            client_secret=os.environ["OAUTH_CLIENT_SECRET"],
+            redirect_uri="https://vinzenzklass.github.io/anaplan-sdk",
+            persist_token=True,
+        )
+    )
+    ```
+When `persist_token` is set to True, the SDK will:
+
+- Look for a stored refresh token in the system's keyring
+- If found, use it to obtain a new access token. If also given, this will overwrite the passed `token` parameter.
+- If not found or if the token is invalid, prompt the user for authentication
+- After authentication, store the new refresh token in the keyring
+
+??? note "Keyring Configuration"
+    The keyring library may require additional configuration depending on your environment:
+
+    - In headless environments, you may need to explicitely configure a different keyring backend
+    - Some Linux distributions may require additional packages or configuration
+    
+    Configuring the keyring backend is your responsibility as it depends on your specific environment. 
+    
+    For example, to use the libsecret file backend:
+    
+    ```python
+    import keyring
+    from keyring.backends import libsecret
+    
+    keyring.set_keyring(libsecret.Keyring())
+    ```
+    
+    For more information, refer to the [keyring documentation](https://github.com/jaraco/keyring).
+
+## OAuth Token Ownership
+
+Instances of both `AnaplanLocalOAuth` and `AnaplanRefreshTokenAuth` assert ownership of the token you pass to them 
+for their entire lifetime. This means that you should not use the token outside of these classes, as it may lead to 
+errors when attempting to use the same refresh token in multiple places. You can access the current token by using the
+`token` property, but you should not use anything other than the `access_token`. You can use this property to 
+reassert control of the OAuth token when the instance is nor longer needed. If you do need to use the token in several
+places simultaneously, you should use a [custom scheme](#custom-authentication-schemes) to do so and handle all 
+potential conflicts appropriately.
+
 
 ## Custom Authentication Schemes
 

{anaplan_sdk-0.4.4a2 → anaplan_sdk-0.4.4a4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "anaplan-sdk"
-version = "0.4.4a2"
+version = "0.4.4a4"
 description = "Streamlined Python Interface for Anaplan"
 license = "Apache-2.0"
 authors = [{ name = "Vinzenz Klass", email = "vinzenz.klass@valantic.com" }]
@@ -26,6 +26,7 @@ dependencies = [
 [project.optional-dependencies]
 cert = ["cryptography>=42.0.7,<46.0.0"]
 oauth = ["oauthlib>=3.0.0,<4.0.0"]
+keyring = ["keyring>=25.6.0,<26.0.0"]
 
 [dependency-groups]
 dev = [
@@ -40,6 +41,7 @@ dev = [
     "griffe-fieldz>=0.2.1",
     "oauthlib>=3.2.2",
     "cryptography>=45.0.0",
+    "keyring>=25.6.0",
 ]
 
 [project.urls]