label-studio-sdk 1.0.10__py3-none-any.whl → 1.0.12__py3-none-any.whl

label_studio_sdk/tokens/client.py

@@ -0,0 +1,610 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+from ..core.client_wrapper import SyncClientWrapper
+from ..core.request_options import RequestOptions
+from ..errors.not_found_error import NotFoundError
+from ..core.pydantic_utilities import parse_obj_as
+from json.decoder import JSONDecodeError
+from ..core.api_error import ApiError
+from ..types.api_token_response import ApiTokenResponse
+from ..types.access_token_response import AccessTokenResponse
+from ..errors.unauthorized_error import UnauthorizedError
+from ..types.rotate_token_response import RotateTokenResponse
+from ..errors.bad_request_error import BadRequestError
+from ..core.client_wrapper import AsyncClientWrapper
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class TokensClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    def blacklist(self, *, refresh: str, request_options: typing.Optional[RequestOptions] = None) -> None:
+        """
+        Blacklist a refresh token to prevent its future use.
+
+        Parameters
+        ----------
+        refresh : str
+            JWT refresh token
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        from label_studio_sdk import LabelStudio
+
+        client = LabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+        client.tokens.blacklist(
+            refresh="refresh",
+        )
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "api/token/blacklist",
+            method="POST",
+            json={
+                "refresh": refresh,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    typing.cast(
+                        typing.Optional[typing.Any],
+                        parse_obj_as(
+                            type_=typing.Optional[typing.Any],  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    )
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    def get(self, *, request_options: typing.Optional[RequestOptions] = None) -> typing.List[ApiTokenResponse]:
+        """
+        List all API tokens for the current user.
+
+        Parameters
+        ----------
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        typing.List[ApiTokenResponse]
+            List of API tokens retrieved successfully
+
+        Examples
+        --------
+        from label_studio_sdk import LabelStudio
+
+        client = LabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+        client.tokens.get()
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "api/token",
+            method="GET",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    typing.List[ApiTokenResponse],
+                    parse_obj_as(
+                        type_=typing.List[ApiTokenResponse],  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    def create(self, *, request_options: typing.Optional[RequestOptions] = None) -> ApiTokenResponse:
+        """
+        Create a new API token for the current user.
+
+        Parameters
+        ----------
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        ApiTokenResponse
+            Token created successfully
+
+        Examples
+        --------
+        from label_studio_sdk import LabelStudio
+
+        client = LabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+        client.tokens.create()
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "api/token",
+            method="POST",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    ApiTokenResponse,
+                    parse_obj_as(
+                        type_=ApiTokenResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    def refresh(self, *, refresh: str, request_options: typing.Optional[RequestOptions] = None) -> AccessTokenResponse:
+        """
+        Get a new access token, using a refresh token.
+
+        Parameters
+        ----------
+        refresh : str
+            JWT refresh token
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AccessTokenResponse
+            New access token created successfully
+
+        Examples
+        --------
+        from label_studio_sdk import LabelStudio
+
+        client = LabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+        client.tokens.refresh(
+            refresh="refresh",
+        )
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "api/token/refresh",
+            method="POST",
+            json={
+                "refresh": refresh,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    AccessTokenResponse,
+                    parse_obj_as(
+                        type_=AccessTokenResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    typing.cast(
+                        typing.Optional[typing.Any],
+                        parse_obj_as(
+                            type_=typing.Optional[typing.Any],  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    )
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    def rotate(self, *, refresh: str, request_options: typing.Optional[RequestOptions] = None) -> RotateTokenResponse:
+        """
+        Blacklist existing refresh token, and get a new refresh token.
+
+        Parameters
+        ----------
+        refresh : str
+            JWT refresh token
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        RotateTokenResponse
+            Refresh token successfully rotated
+
+        Examples
+        --------
+        from label_studio_sdk import LabelStudio
+
+        client = LabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+        client.tokens.rotate(
+            refresh="refresh",
+        )
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "api/token/rotate",
+            method="POST",
+            json={
+                "refresh": refresh,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    RotateTokenResponse,
+                    parse_obj_as(
+                        type_=RotateTokenResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    typing.cast(
+                        typing.Optional[typing.Any],
+                        parse_obj_as(
+                            type_=typing.Optional[typing.Any],  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    )
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+
+class AsyncTokensClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    async def blacklist(self, *, refresh: str, request_options: typing.Optional[RequestOptions] = None) -> None:
+        """
+        Blacklist a refresh token to prevent its future use.
+
+        Parameters
+        ----------
+        refresh : str
+            JWT refresh token
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        import asyncio
+
+        from label_studio_sdk import AsyncLabelStudio
+
+        client = AsyncLabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.tokens.blacklist(
+                refresh="refresh",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "api/token/blacklist",
+            method="POST",
+            json={
+                "refresh": refresh,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    typing.cast(
+                        typing.Optional[typing.Any],
+                        parse_obj_as(
+                            type_=typing.Optional[typing.Any],  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    )
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    async def get(self, *, request_options: typing.Optional[RequestOptions] = None) -> typing.List[ApiTokenResponse]:
+        """
+        List all API tokens for the current user.
+
+        Parameters
+        ----------
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        typing.List[ApiTokenResponse]
+            List of API tokens retrieved successfully
+
+        Examples
+        --------
+        import asyncio
+
+        from label_studio_sdk import AsyncLabelStudio
+
+        client = AsyncLabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.tokens.get()
+
+
+        asyncio.run(main())
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "api/token",
+            method="GET",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    typing.List[ApiTokenResponse],
+                    parse_obj_as(
+                        type_=typing.List[ApiTokenResponse],  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    async def create(self, *, request_options: typing.Optional[RequestOptions] = None) -> ApiTokenResponse:
+        """
+        Create a new API token for the current user.
+
+        Parameters
+        ----------
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        ApiTokenResponse
+            Token created successfully
+
+        Examples
+        --------
+        import asyncio
+
+        from label_studio_sdk import AsyncLabelStudio
+
+        client = AsyncLabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.tokens.create()
+
+
+        asyncio.run(main())
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "api/token",
+            method="POST",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    ApiTokenResponse,
+                    parse_obj_as(
+                        type_=ApiTokenResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    async def refresh(
+        self, *, refresh: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> AccessTokenResponse:
+        """
+        Get a new access token, using a refresh token.
+
+        Parameters
+        ----------
+        refresh : str
+            JWT refresh token
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AccessTokenResponse
+            New access token created successfully
+
+        Examples
+        --------
+        import asyncio
+
+        from label_studio_sdk import AsyncLabelStudio
+
+        client = AsyncLabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.tokens.refresh(
+                refresh="refresh",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "api/token/refresh",
+            method="POST",
+            json={
+                "refresh": refresh,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    AccessTokenResponse,
+                    parse_obj_as(
+                        type_=AccessTokenResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            if _response.status_code == 401:
+                raise UnauthorizedError(
+                    typing.cast(
+                        typing.Optional[typing.Any],
+                        parse_obj_as(
+                            type_=typing.Optional[typing.Any],  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    )
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    async def rotate(
+        self, *, refresh: str, request_options: typing.Optional[RequestOptions] = None
+    ) -> RotateTokenResponse:
+        """
+        Blacklist existing refresh token, and get a new refresh token.
+
+        Parameters
+        ----------
+        refresh : str
+            JWT refresh token
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        RotateTokenResponse
+            Refresh token successfully rotated
+
+        Examples
+        --------
+        import asyncio
+
+        from label_studio_sdk import AsyncLabelStudio
+
+        client = AsyncLabelStudio(
+            api_key="YOUR_API_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.tokens.rotate(
+                refresh="refresh",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "api/token/rotate",
+            method="POST",
+            json={
+                "refresh": refresh,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                return typing.cast(
+                    RotateTokenResponse,
+                    parse_obj_as(
+                        type_=RotateTokenResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    typing.cast(
+                        typing.Optional[typing.Any],
+                        parse_obj_as(
+                            type_=typing.Optional[typing.Any],  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    )
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, body=_response.text)
+        raise ApiError(status_code=_response.status_code, body=_response_json)

label_studio_sdk/tokens/client_ext.py

@@ -0,0 +1,94 @@
+import threading
+import typing
+from datetime import datetime, timezone
+
+import httpx
+import jwt
+
+from ..core.api_error import ApiError
+from ..types.access_token_response import AccessTokenResponse
+
+
+class TokensClientExt:
+    """Client for managing authentication tokens."""
+
+    def __init__(self, base_url: str, api_key: str):
+        self._base_url = base_url
+        self._api_key = api_key
+        self._use_legacy_token = not self._is_valid_jwt_token(api_key, raise_if_expired=True)
+
+        # cache state for access token when using jwt-based api_key
+        self._access_token: typing.Optional[str] = None
+        self._access_token_expiration: typing.Optional[datetime] = None
+        # Used to keep simultaneous refresh requests from spamming refresh endpoint
+        self._token_refresh_lock = threading.Lock()
+
+
+    def _is_valid_jwt_token(self, token: str, raise_if_expired: bool = False) -> bool:
+        """Check if a token is a valid JWT token by attempting to decode its header and check expiration."""
+        try:
+            decoded = jwt.decode(token, options={"verify_signature": False})
+        except jwt.InvalidTokenError:
+            # presumably a lagacy token
+            return False
+        expiration = decoded.get("exp")
+        if expiration is None:
+            raise ApiError(
+                status_code=401,
+                body={"detail": "API key does not have an expiration set, and is not valid. Please obtain a new refresh token."}
+            )
+        expiration_time = datetime.fromtimestamp(expiration, timezone.utc)
+        if expiration_time < datetime.now(timezone.utc):
+            if raise_if_expired:
+                raise ApiError(
+                    status_code=401,
+                    body={"detail": "API key has expired. Please obtain a new refresh token."}
+                )
+            else:
+                return False
+        return True
+
+    def _set_access_token(self, token: str) -> None:
+        """Set the access token and cache its expiration time."""
+        try:
+            decoded = jwt.decode(token, options={"verify_signature": False})
+            expiration = decoded.get("exp")
+            if expiration is not None:
+                self._access_token_expiration = datetime.fromtimestamp(expiration, timezone.utc)
+        except jwt.InvalidTokenError:
+            pass
+        self._access_token = token
+
+    @property
+    def api_key(self) -> str:
+        """Get the current access token, refreshing if necessary."""
+        # Legacy tokens: just return the API key directly
+        if self._use_legacy_token:
+            return self._api_key
+
+        # JWT tokens: handle refresh if needed
+        if (not self._access_token) or (not self._is_valid_jwt_token(self._access_token)):
+            with self._token_refresh_lock:
+                # Check again after acquiring lock, in case another invocation already refreshed
+                if (not self._access_token) or (not self._is_valid_jwt_token(self._access_token)):
+                    token_response = self.refresh()
+                    self._set_access_token(token_response.access)
+        
+        return self._access_token
+
+    def refresh(self) -> AccessTokenResponse:
+        """Refresh the access token and return the token response."""
+        # We don't do this often, just use a separate httpx client for simplicity here
+        # (avoids complicated state management and sync vs async handling)
+        with httpx.Client() as sync_client:
+            response = sync_client.request(
+                method="POST",
+                url=f"{self._base_url}/api/token/refresh/",
+                json={"refresh": self._api_key},
+                headers={"Content-Type": "application/json"},
+            )
+            
+            if response.status_code == 200:
+                return AccessTokenResponse.parse_obj(response.json())
+            else:
+                raise ApiError(status_code=response.status_code, body=response.json())