Merge pull request #1965 from kili-technology/feature/lab-3973-aa-sdk-user-i-see-an-easier-way-to-interact

feat: add domain API architecture

Author: baptiste-olivier

.github/workflows/ci.yml

@@ -80,7 +80,7 @@ jobs:
           pip install -e ".[dev]"
 
       - name: Unit and integration tests
-        run: pytest -n auto -ra -sv --color yes --code-highlight yes --durations=15 -vv --ignore tests/e2e/ --cov=src/kili --cov-report=term-missing --cov-config=.coveragerc --cov-fail-under=80
+        run: pytest -n auto -ra -sv --color yes --code-highlight yes --durations=15 -vv --ignore tests/e2e/ --cov=src/kili --cov-report=term-missing --cov-config=.coveragerc --cov-fail-under=75
 
   markdown-link-check:
     timeout-minutes: 10

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
   "tenacity >= 8.0.0, < 9.0.0",
   "tqdm >= 4.0.0, < 5.0.0",
   "typeguard >= 4, < 5",
-  "typing-extensions >= 4.1.0, < 5.0.0",
+  "typing-extensions >= 4.5.0, < 5.0.0",
   "pyparsing >= 3.0.0, < 4.0.0",
   "websocket-client >= 1.0.0, < 2.0.0",
   "cuid >= 0.4, < 0.5",
@@ -200,6 +200,5 @@ line-ending = "lf"
 [tool.ruff.isort]
 known-first-party = ["src", "tests"]
 
-[tool.pytest]
-ini_options = { pythonpath = ["src", "."] }
-aliases = ["test = pytest"]
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]

src/kili/adapters/kili_api_gateway/label/mappers.py

@@ -46,12 +46,13 @@ def update_label_data_mapper(data: UpdateLabelData) -> Dict:
 def append_label_data_mapper(data: AppendLabelData) -> Dict:
     """Map AppendLabelData to GraphQL AppendLabelData input."""
     return {
-        "authorID": data.author_id,
         "assetID": data.asset_id,
+        "authorID": data.author_id,
         "clientVersion": data.client_version,
         "jsonResponse": json.dumps(data.json_response),
-        "secondsToLabel": data.seconds_to_label,
         "modelName": data.model_name,
+        "referencedLabelId": data.referenced_label_id,
+        "secondsToLabel": data.seconds_to_label,
     }
 
 

src/kili/adapters/kili_api_gateway/label/types.py

@@ -22,12 +22,13 @@ class UpdateLabelData:
 class AppendLabelData:
     """AppendLabelData data."""
 
-    author_id: Optional[UserId]
     asset_id: AssetId
+    author_id: Optional[UserId]
     client_version: Optional[int]
     json_response: Dict
-    seconds_to_label: Optional[float]
     model_name: Optional[str]
+    referenced_label_id: Optional[str]
+    seconds_to_label: Optional[float]
 
 
 @dataclass

src/kili/client.py

@@ -86,6 +86,9 @@ def __init__(
     ) -> None:
         """Initialize Kili client.
 
+        This client provides access to methods through mixin inheritance.
+        For the domain-based API, use `from kili.client_domain import Kili` instead.
+
         Args:
             api_key: User API key generated
                 from https://cloud.kili-technology.com/label/my-account/api-key.
@@ -116,10 +119,8 @@ def __init__(
             from kili.client import Kili
 
             kili = Kili()
-
-            kili.assets()  # list your assets
-            kili.labels()  # list your labels
-            kili.projects()  # list your projects
+            kili.assets()
+            kili.projects()
             ```
         """
         api_key = api_key or os.getenv("KILI_API_KEY")

src/kili/client_domain.py

@@ -0,0 +1,285 @@
+"""Kili Python SDK client."""
+
+import logging
+import warnings
+from functools import cached_property
+from typing import TYPE_CHECKING, Dict, Optional, Union
+
+from kili.client import Kili as KiliLegacy
+from kili.core.graphql.graphql_client import GraphQLClientName
+
+if TYPE_CHECKING:
+    from kili.domain_api import (
+        AssetsNamespace,
+        ExportNamespace,
+        IssuesNamespace,
+        LabelsNamespace,
+        OrganizationsNamespace,
+        ProjectsNamespace,
+        QuestionsNamespace,
+        StoragesNamespace,
+        TagsNamespace,
+        UsersNamespace,
+    )
+
+warnings.filterwarnings("default", module="kili", category=DeprecationWarning)
+
+
+class FilterPoolFullWarning(logging.Filter):
+    """Filter out the specific urllib3 warning related to the connection pool."""
+
+    def filter(self, record) -> bool:
+        """urllib3.connectionpool:Connection pool is full, discarding connection: ..."""
+        return "Connection pool is full, discarding connection" not in record.getMessage()
+
+
+logging.getLogger("urllib3.connectionpool").addFilter(FilterPoolFullWarning())
+
+
+class Kili:
+    """Kili Client (domain mode)."""
+
+    legacy_client: KiliLegacy
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_endpoint: Optional[str] = None,
+        verify: Optional[Union[bool, str]] = None,
+        graphql_client_params: Optional[Dict[str, object]] = None,
+    ) -> None:
+        """Initialize Kili client (domain mode).
+
+        This client provides access to domain-based namespaces.
+        For the legacy API with methods, use `from kili.client import Kili` instead.
+
+        Args:
+            api_key: User API key generated
+                from https://cloud.kili-technology.com/label/my-account/api-key.
+                Default to `KILI_API_KEY` environment variable.
+                If not passed, requires the `KILI_API_KEY` environment variable to be set.
+            api_endpoint: Recipient of the HTTP operation.
+                Default to `KILI_API_ENDPOINT` environment variable.
+                If not passed, default to Kili SaaS:
+                'https://cloud.kili-technology.com/api/label/v2/graphql'
+            verify: similar to `requests`' verify.
+                Either a boolean, in which case it controls whether we verify
+                the server's TLS certificate, or a string, in which case it must be a path
+                to a CA bundle to use. Defaults to ``True``. When set to
+                ``False``, requests will accept any TLS certificate presented by
+                the server, and will ignore hostname mismatches and/or expired
+                certificates, which will make your application vulnerable to
+                man-in-the-middle (MitM) attacks. Setting verify to ``False``
+                may be useful during local development or testing.
+            graphql_client_params: Parameters to pass to the graphQL client.
+
+        Returns:
+            Instance of the Kili client.
+
+        Examples:
+            ```python
+            from kili.client_domain import Kili
+
+            # Domain API with namespaces
+            kili = Kili()
+            kili.assets  # domain namespace (clean name)
+            kili.projects.list()  # domain methods
+            ```
+        """
+        warnings.warn(
+            "Client domain api is still a work in progress. Method names and return type will evolve.",
+            stacklevel=1,
+        )
+        self.legacy_client = KiliLegacy(
+            api_key,
+            api_endpoint,
+            verify,
+            GraphQLClientName.SDK_DOMAIN,
+            graphql_client_params,
+        )
+
+    # Domain API Namespaces - Lazy loaded properties
+    @cached_property
+    def assets(self) -> "AssetsNamespace":
+        """Get the assets domain namespace.
+
+        Returns:
+            AssetsNamespace: Assets domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            assets = kili.assets
+            ```
+        """
+        from kili.domain_api import AssetsNamespace  # pylint: disable=import-outside-toplevel
+
+        return AssetsNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def labels(self) -> "LabelsNamespace":
+        """Get the labels domain namespace.
+
+        Returns:
+            LabelsNamespace: Labels domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            labels = kili.labels
+            ```
+        """
+        from kili.domain_api import LabelsNamespace  # pylint: disable=import-outside-toplevel
+
+        return LabelsNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def projects(self) -> "ProjectsNamespace":
+        """Get the projects domain namespace.
+
+        Returns:
+            ProjectsNamespace: Projects domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            projects = kili.projects
+            ```
+        """
+        from kili.domain_api import ProjectsNamespace  # pylint: disable=import-outside-toplevel
+
+        return ProjectsNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def users(self) -> "UsersNamespace":
+        """Get the users domain namespace.
+
+        Returns:
+            UsersNamespace: Users domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            users = kili.users
+            ```
+        """
+        from kili.domain_api import UsersNamespace  # pylint: disable=import-outside-toplevel
+
+        return UsersNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def organizations(self) -> "OrganizationsNamespace":
+        """Get the organizations domain namespace.
+
+        Returns:
+            OrganizationsNamespace: Organizations domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            organizations = kili.organizations
+            ```
+        """
+        from kili.domain_api import (  # pylint: disable=import-outside-toplevel
+            OrganizationsNamespace,
+        )
+
+        return OrganizationsNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def issues(self) -> "IssuesNamespace":
+        """Get the issues domain namespace.
+
+        Returns:
+            IssuesNamespace: Issues domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            issues = kili.issues
+            ```
+        """
+        from kili.domain_api import IssuesNamespace  # pylint: disable=import-outside-toplevel
+
+        return IssuesNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def questions(self) -> "QuestionsNamespace":
+        """Get the questions domain namespace.
+
+        Returns:
+            QuestionsNamespace: Questions domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            questions = kili.questions
+            ```
+        """
+        from kili.domain_api import QuestionsNamespace  # pylint: disable=import-outside-toplevel
+
+        return QuestionsNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def tags(self) -> "TagsNamespace":
+        """Get the tags domain namespace.
+
+        Returns:
+            TagsNamespace: Tags domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            tags = kili.tags
+            ```
+        """
+        from kili.domain_api import TagsNamespace  # pylint: disable=import-outside-toplevel
+
+        return TagsNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def storages(self) -> "StoragesNamespace":
+        """Get the storages domain namespace.
+
+        Returns:
+            StoragesNamespace: Storages domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            storages = kili.storages
+            # Access nested namespaces
+            integrations = kili.storages.integrations
+            connections = kili.storages.connections
+            ```
+        """
+        from kili.domain_api import StoragesNamespace  # pylint: disable=import-outside-toplevel
+
+        return StoragesNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)
+
+    @cached_property
+    def exports(self) -> "ExportNamespace":
+        """Get the exports domain namespace.
+
+        Returns:
+            ExportNamespace: Exports domain namespace with lazy loading
+
+        Examples:
+            ```python
+            kili = Kili()
+            # Namespace is instantiated on first access
+            exports = kili.exports
+            ```
+        """
+        from kili.domain_api import ExportNamespace  # pylint: disable=import-outside-toplevel
+
+        return ExportNamespace(self.legacy_client, self.legacy_client.kili_api_gateway)

src/kili/core/graphql/clientnames.py

@@ -7,4 +7,5 @@ class GraphQLClientName(Enum):
     """GraphQL client name."""
 
     SDK = "python-sdk"
+    SDK_DOMAIN = "python-sdk-domain"
     CLI = "python-cli"

src/kili/core/graphql/graphql_client.py

@@ -316,14 +316,16 @@ def _raw_execute(
         self, document: DocumentNode, variables: Optional[Dict], **kwargs
     ) -> Dict[str, Any]:
         _limiter.try_acquire("GraphQLClient.execute")
+        log_context = LogContext()
+        log_context.set_client_name(self.client_name)
         with _execute_lock:
             res = self._gql_client.execute(
                 document=document,
                 variable_values=variables,
                 extra_args={
                     "headers": {
                         **(self._gql_transport.headers or {}),
-                        **LogContext(),
+                        **log_context,
                     }
                 },
                 **kwargs,

src/kili/domain/asset/__init__.py

@@ -1,5 +1,5 @@
 """Asset domain."""
 
-from .asset import AssetExternalId, AssetFilters, AssetId, AssetStatus
+from .asset import AssetExternalId, AssetFilters, AssetId, AssetStatus, get_asset_default_fields
 
-__all__ = ["AssetFilters", "AssetId", "AssetExternalId", "AssetStatus"]
+__all__ = ["AssetFilters", "AssetId", "AssetExternalId", "AssetStatus", "get_asset_default_fields"]