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

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/_auth.py

@@ -1,7 +1,7 @@
 import logging
 import os
 from base64 import b64encode
-from typing import Awaitable, Callable
+from typing import Callable
 
 import httpx
 
@@ -10,11 +10,6 @@ from .exceptions import AnaplanException, InvalidCredentialsException, InvalidPr
 
 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 +149,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 +164,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 +190,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 = ""  # Set to blank to trigger the super().__init__ auth request.
+            except ImportError as e:
+                raise AnaplanException(
+                    "keyring is not available. Please install anaplan-sdk with the keyring extra "
+                    "`pip install anaplan-sdk[keyring]` or install keyring separately."
+                ) from e
+        self._persist_token = persist_token
         self._oauth = _OAuthRequestFactory(
             client_id=client_id,
             client_secret=client_secret,
-            redirect_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 +244,12 @@ 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:
+            import keyring
+
+            keyring.set_password(
+                self._service_name, self._service_name, self._oauth_token["refresh_token"]
+            )
         self._token: str = self._oauth_token["access_token"]
 
     def __auth_code_flow(self):
@@ -237,30 +274,61 @@ 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) or not all(
+            key in token for key in ("access_token", "refresh_token")
+        ):
+            raise ValueError(
+                "The token must at least contain 'access_token' and 'refresh_token' keys."
+            )
         self._oauth_token = token
         self._oauth = _OAuthRequestFactory(
             client_id=client_id,
             client_secret=client_secret,
-            redirect_url=redirect_url,
+            redirect_uri=redirect_uri,
             token_url=token_url,
         )
-        super().__init__(self._token)
+        super().__init__(self._oauth_token["access_token"])
+
+    @property
+    def token(self) -> dict[str, str]:
+        """
+        Returns the current OAuth token. You can safely use the `access_token`, but you
+        must not use the `refresh_token` outside of this class, if you expect to use this instance
+        further. If you do use the `refresh_token` outside of this class, this will error on the
+        next attempt to refresh the token, as the `refresh_token` can only be used once.
+        """
+        return self._oauth_token
 
     def _build_auth_request(self) -> httpx.Request:
         return self._oauth.refresh_token_request(self._oauth_token["refresh_token"])

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)
@@ -133,7 +133,7 @@ class AsyncOauth(_BaseOauth):
     Applications.
     """
 
-    async def fetch_token(self, authorization_response: str) -> dict[str, str]:
+    async def fetch_token(self, authorization_response: str) -> dict[str, str | int]:
         """
         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
@@ -151,7 +151,7 @@ class AsyncOauth(_BaseOauth):
             logger.error(error)
             raise AnaplanException("Error during token creation.") from error
 
-    async def validate_token(self, token: str) -> dict[str, str | dict[str, str]]:
+    async def validate_token(self, token: str) -> dict[str, str | dict[str, str | int]]:
         """
         Validates the provided token by checking its validity with the Anaplan Authentication API.
         If the token is not valid, an `InvalidCredentialsException` is raised.
@@ -168,7 +168,7 @@ class AsyncOauth(_BaseOauth):
             logger.error(error)
             raise AnaplanException("Error during token validation.") from error
 
-    async def refresh_token(self, refresh_token: str) -> dict[str, str]:
+    async def refresh_token(self, refresh_token: str) -> dict[str, str | int]:
         """
         Refreshes the token using a refresh token.
         :param refresh_token: The refresh token to use for refreshing the access token.
@@ -192,7 +192,7 @@ class Oauth(_BaseOauth):
     Applications.
     """
 
-    def fetch_token(self, authorization_response: str) -> dict[str, str]:
+    def fetch_token(self, authorization_response: str) -> dict[str, str | int]:
         """
         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
@@ -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:
@@ -216,7 +216,7 @@ class Oauth(_BaseOauth):
             logger.error(error)
             raise AnaplanException("Error during token creation.") from error
 
-    def validate_token(self, token: str) -> dict[str, str | dict[str, str]]:
+    def validate_token(self, token: str) -> dict[str, str | dict[str, str | int]]:
         """
         Validates the provided token by checking its validity with the Anaplan Authentication API.
         If the token is not valid, an `InvalidCredentialsException` is raised.
@@ -233,7 +233,7 @@ class Oauth(_BaseOauth):
             logger.error(error)
             raise AnaplanException("Error during token validation.") from error
 
-    def refresh_token(self, refresh_token: str) -> dict[str, str]:
+    def refresh_token(self, refresh_token: str) -> dict[str, str | int]:
         """
         Refreshes the token using a refresh token.
         :param refresh_token: The refresh token to use for refreshing the access token.

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.3a2.dist-info → anaplan_sdk-0.4.4.dist-info}/METADATA

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

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

@@ -1,7 +1,7 @@
-anaplan_sdk/__init__.py,sha256=lDFhs0IobOH7a34jqtAgcj9X1bR5hnFRkkkCl_vPHpo,357
-anaplan_sdk/_auth.py,sha256=u7AHeTAWJnOQo7LtdgCmRY1CeITizX_Hqg1aKoZs9EE,12684
+anaplan_sdk/__init__.py,sha256=WScEKtXlnRLjCb-j3qW9W4kEACTyPsTLFs-L54et2TQ,351
+anaplan_sdk/_auth.py,sha256=l5z2WCcfQ05OkuQ1dcmikp6dB87Rw1qy2zu8bbaAQTs,16620
 anaplan_sdk/_base.py,sha256=9CdLshORWsLixOyoFa3A0Bka5lhLwlZrQI5sEdBcGFI,12298
-anaplan_sdk/_oauth.py,sha256=FGOStYTtlTruQQDcDjN8JEEKEiEpdPwJM-chCrG1oao,12636
+anaplan_sdk/_oauth.py,sha256=AynlJDrGIinQT0jwxI2RSvtU4D7Wasyw3H1uicdlLVI,12672
 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
@@ -20,11 +20,11 @@ anaplan_sdk/_clients/_transactional.py,sha256=YUVbA54uhMloQcahwMtmZO3YooO6qQzwZN
 anaplan_sdk/models/__init__.py,sha256=nSplwPG_74CG9CKbv1PzP9bsA9v5-daS4azpTCvCQTI,925
 anaplan_sdk/models/_alm.py,sha256=IqsTPvkx_ujLpaqZgIrTcr44KHJyKc4dyeRs9rkDjms,2307
 anaplan_sdk/models/_base.py,sha256=6AZc9CfireUKgpZfMxYKu4MbwiyHQOsGLjKrxGXBLic,508
-anaplan_sdk/models/_bulk.py,sha256=dHP3kMvsKONCZS6mHB271-wp2S4P3rM874Ita8TzABU,8256
+anaplan_sdk/models/_bulk.py,sha256=_lHARGGjJgi-AmA7u5ZfCmGpLecPnr73LSAsZSX-a_A,8276
 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.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,,
+anaplan_sdk-0.4.4.dist-info/METADATA,sha256=VU-hRC5mvfO5owSGRjfY7TTMFKL4z3QMRJM_ddiSPU4,3667
+anaplan_sdk-0.4.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+anaplan_sdk-0.4.4.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+anaplan_sdk-0.4.4.dist-info/RECORD,,