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

label_studio_sdk/tokens/client.py

@@ -0,0 +1,470 @@
+# 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 ..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)
+
+
+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)

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())

label_studio_sdk/types/__init__.py

@@ -1,10 +1,12 @@
 # This file was auto-generated by Fern from our API Definition.
 
+from .access_token_response import AccessTokenResponse
 from .annotation import Annotation
 from .annotation_filter_options import AnnotationFilterOptions
 from .annotation_last_action import AnnotationLastAction
 from .annotations_dm_field import AnnotationsDmField
 from .annotations_dm_field_last_action import AnnotationsDmFieldLastAction
+from .api_token_response import ApiTokenResponse
 from .azure_blob_export_storage import AzureBlobExportStorage
 from .azure_blob_export_storage_status import AzureBlobExportStorageStatus
 from .azure_blob_import_storage import AzureBlobImportStorage
@@ -39,6 +41,7 @@ from .inference_run_created_by import InferenceRunCreatedBy
 from .inference_run_organization import InferenceRunOrganization
 from .inference_run_project_subset import InferenceRunProjectSubset
 from .inference_run_status import InferenceRunStatus
+from .jwt_settings_response import JwtSettingsResponse
 from .key_indicator_value import KeyIndicatorValue
 from .key_indicators import KeyIndicators
 from .key_indicators_item import KeyIndicatorsItem
@@ -57,6 +60,8 @@ from .model_provider_connection_created_by import ModelProviderConnectionCreated
 from .model_provider_connection_organization import ModelProviderConnectionOrganization
 from .model_provider_connection_provider import ModelProviderConnectionProvider
 from .model_provider_connection_scope import ModelProviderConnectionScope
+from .pause import Pause
+from .pause_paused_by import PausePausedBy
 from .prediction import Prediction
 from .project import Project
 from .project_import import ProjectImport
@@ -101,11 +106,13 @@ from .webhook_serializer_for_update_actions_item import WebhookSerializerForUpda
 from .workspace import Workspace
 
 __all__ = [
+    "AccessTokenResponse",
     "Annotation",
     "AnnotationFilterOptions",
     "AnnotationLastAction",
     "AnnotationsDmField",
     "AnnotationsDmFieldLastAction",
+    "ApiTokenResponse",
     "AzureBlobExportStorage",
     "AzureBlobExportStorageStatus",
     "AzureBlobImportStorage",
@@ -140,6 +147,7 @@ __all__ = [
     "InferenceRunOrganization",
     "InferenceRunProjectSubset",
     "InferenceRunStatus",
+    "JwtSettingsResponse",
     "KeyIndicatorValue",
     "KeyIndicators",
     "KeyIndicatorsItem",
@@ -158,6 +166,8 @@ __all__ = [
     "ModelProviderConnectionOrganization",
     "ModelProviderConnectionProvider",
     "ModelProviderConnectionScope",
+    "Pause",
+    "PausePausedBy",
     "Prediction",
     "Project",
     "ProjectImport",

label_studio_sdk/types/access_token_response.py

@@ -0,0 +1,22 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from ..core.pydantic_utilities import UniversalBaseModel
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+import typing
+
+
+class AccessTokenResponse(UniversalBaseModel):
+    access: str = pydantic.Field()
+    """
+    New JWT access token
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

label_studio_sdk/types/api_token_response.py

@@ -0,0 +1,32 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from ..core.pydantic_utilities import UniversalBaseModel
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+import typing
+
+
+class ApiTokenResponse(UniversalBaseModel):
+    token: str = pydantic.Field()
+    """
+    JWT token
+    """
+
+    created_at: str = pydantic.Field()
+    """
+    Token creation timestamp
+    """
+
+    expires_at: str = pydantic.Field()
+    """
+    Token expiration timestamp
+    """
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow