anaplan-sdk 0.4.4a3__py3-none-any.whl → 0.4.4a4__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,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_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,7 +165,7 @@ 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.
@@ -177,6 +174,15 @@ class AnaplanOAuthCodeAuth(_AnaplanAuth):
         :param client_secret: The client secret of your Anaplan Oauth 2.0 application.
         :param redirect_uri: The URL to which the user will be redirected after authorizing the
                application.
+        :param token: The OAuth token dictionary containing at least the `access_token` and
+               `refresh_token`. If not provided, the user will be prompted to interactive
+               authorize the application, if `persist_token` is set to False or no valid refresh
+               token is found in the keyring.
+        :param persist_token: If set to True, the refresh token will be stored in the system's
+               keyring, allowing the application to use the same refresh token across multiple
+               runs. If set to False, the user will be prompted to authorize the application each
+               time. This requires the `keyring` extra to be installed. If a valid refresh token
+               is found in the keyring, it will be used instead of the given `token` parameter.
         :param authorization_url: The URL to which the user will be redirected to authorize the
                application. Defaults to the Anaplan Prelogin Page, where the user can select the
                login method.
@@ -185,11 +191,27 @@ 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,
@@ -200,10 +222,20 @@ class AnaplanOAuthCodeAuth(_AnaplanAuth):
             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):
@@ -243,8 +279,20 @@ class AnaplanRefreshTokenAuth(_AnaplanAuth):
     ):
         """
         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.
@@ -256,6 +304,12 @@ class AnaplanRefreshTokenAuth(_AnaplanAuth):
         :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,
@@ -265,6 +319,16 @@ class AnaplanRefreshTokenAuth(_AnaplanAuth):
         )
         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/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.4a3.dist-info → anaplan_sdk-0.4.4a4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anaplan-sdk
-Version: 0.4.4a3
+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.4a3.dist-info → anaplan_sdk-0.4.4a4.dist-info}/RECORD

@@ -1,5 +1,5 @@
-anaplan_sdk/__init__.py,sha256=lDFhs0IobOH7a34jqtAgcj9X1bR5hnFRkkkCl_vPHpo,357
-anaplan_sdk/_auth.py,sha256=wB6znPwnUQ3pG7dRqpZZMdxb0V-XsZELASY881t4ocE,12834
+anaplan_sdk/__init__.py,sha256=WScEKtXlnRLjCb-j3qW9W4kEACTyPsTLFs-L54et2TQ,351
+anaplan_sdk/_auth.py,sha256=H5A_fujTMHf7J33w2jkqMYtlxKFwzqZgxFcBJHi8wvc,16612
 anaplan_sdk/_base.py,sha256=9CdLshORWsLixOyoFa3A0Bka5lhLwlZrQI5sEdBcGFI,12298
 anaplan_sdk/_oauth.py,sha256=AynlJDrGIinQT0jwxI2RSvtU4D7Wasyw3H1uicdlLVI,12672
 anaplan_sdk/exceptions.py,sha256=ALkA9fBF0NQ7dufFxV6AivjmHyuJk9DOQ9jtJV2n7f0,1809
@@ -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.4a3.dist-info/METADATA,sha256=GTtQ-OiFOT9r5UWggC_25nGzrCDZMilYZeSOxUiwNBI,3545
-anaplan_sdk-0.4.4a3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-anaplan_sdk-0.4.4a3.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
-anaplan_sdk-0.4.4a3.dist-info/RECORD,,
+anaplan_sdk-0.4.4a4.dist-info/METADATA,sha256=uf0KLkAvBJr3cY668F9T-wuIG5uya2zHvIRu-roipVo,3628
+anaplan_sdk-0.4.4a4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+anaplan_sdk-0.4.4a4.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+anaplan_sdk-0.4.4a4.dist-info/RECORD,,