Merge pull request #2007 from kili-technology/feature/lab-4126-aa-sdk-user-i-can-load-sdk-settings-using-a-dedicated-file

feat: Add configuration file

Author: florianlega

kili-sdk-config.example.json

@@ -0,0 +1,6 @@
+{
+  "api_key": "your-api-key-here",
+  "api_endpoint": "https://api-endpoint.com",
+  "verify_ssl": true,
+  "disable_tqdm": false
+}

src/kili/client.py

@@ -11,6 +11,7 @@
 from kili.adapters.authentification import is_api_key_valid
 from kili.adapters.http_client import HttpClient
 from kili.adapters.kili_api_gateway.kili_api_gateway import KiliAPIGateway
+from kili.core.config_loader import load_config_from_file
 from kili.core.graphql.graphql_client import GraphQLClient, GraphQLClientName
 from kili.entrypoints.mutations.asset import MutationsAsset
 from kili.entrypoints.mutations.issue import MutationsIssue
@@ -91,6 +92,7 @@ def __init__(
         verify: Optional[Union[bool, str]] = None,
         client_name: GraphQLClientName = GraphQLClientName.SDK,
         graphql_client_params: Optional[GraphQLClientParams] = None,
+        disable_tqdm: bool | None = None,
     ) -> None:
         """Initialize Kili client.
 
@@ -118,6 +120,10 @@ def __init__(
             client_name: For internal use only.
                 Define the name of the graphQL client whith which graphQL calls will be sent.
             graphql_client_params: Parameters to pass to the graphQL client.
+            disable_tqdm: Global setting to disable progress bars (tqdm) for all operations.
+                Can be overridden by individual function calls.
+                Default to `KILI_DISABLE_TQDM` environment variable.
+                If not passed, default to `disable_tqdm` in config file or False.
 
         Returns:
             Instance of the Kili client.
@@ -130,33 +136,57 @@ def __init__(
             kili.assets()
             kili.projects()
             ```
+
+            Disable progress bars globally:
+            ```python
+            kili = Kili(disable_tqdm=True)
+            ```
         """
-        api_key = api_key or os.getenv("KILI_API_KEY")
+        config_file = load_config_from_file()
+
+        api_key = api_key or os.getenv("KILI_API_KEY") or config_file.get("api_key")
 
         if not api_key and sys.stdin.isatty():
             api_key = getpass.getpass(
                 "No `KILI_API_KEY` environment variable found.\nPlease enter your API key: "
             )
 
         if api_endpoint is None:
-            api_endpoint = os.getenv(
-                "KILI_API_ENDPOINT",
-                "https://cloud.kili-technology.com/api/label/v2/graphql",
+            api_endpoint = (
+                os.getenv("KILI_API_ENDPOINT")
+                or config_file.get("api_endpoint")
+                or "https://cloud.kili-technology.com/api/label/v2/graphql"
             )
 
+        if verify is None:
+            verify_env = os.getenv("KILI_VERIFY")
+            if verify_env is not None:
+                verify = verify_env.lower() in ("true", "1", "yes")
+            elif "verify_ssl" in config_file:
+                verify = config_file["verify_ssl"]
+            else:
+                verify = True
+
+        # Load disable_tqdm from env or config if not explicitly provided
+        if disable_tqdm is None:
+            disable_tqdm_env = os.getenv("KILI_DISABLE_TQDM")
+            if disable_tqdm_env is not None:
+                disable_tqdm = disable_tqdm_env.lower() in ("true", "1", "yes")
+            elif "disable_tqdm" in config_file:
+                disable_tqdm = config_file["disable_tqdm"]
+            # Otherwise keep as None to let individual functions use their own defaults
+
+        assert api_endpoint is not None
+        assert verify is not None
+
         if not api_key:
             raise AuthenticationFailed(api_key, api_endpoint)
 
-        if verify is None:
-            verify = os.getenv(
-                "KILI_VERIFY",
-                "True",
-            ).lower() in ("true", "1", "yes")
-
         self.api_key = api_key
         self.api_endpoint = api_endpoint
         self.verify = verify
         self.client_name = client_name
+        self.disable_tqdm = disable_tqdm
         self.http_client = HttpClient(kili_endpoint=api_endpoint, verify=verify, api_key=api_key)
         skip_checks = os.getenv("KILI_SDK_SKIP_CHECKS") is not None
         if not skip_checks and not is_api_key_valid(

src/kili/core/config_loader.py

@@ -0,0 +1,54 @@
+"""Configuration file loader for the Kili SDK."""
+
+import json
+import warnings
+from pathlib import Path
+from typing import Any, Optional
+
+
+def load_config_from_file(
+    filename: str = "kili-sdk-config.json",
+    search_paths: Optional[list[Path]] = None,
+) -> dict[str, Any]:
+    """Load configuration from a JSON file.
+
+    Searches for the configuration file in the provided search paths.
+    If no search paths are provided, searches in the current working directory
+    and the user's home directory.
+
+    Args:
+        filename: Name of the configuration file. Defaults to "kili-sdk-config.json".
+        search_paths: List of directories to search for the configuration file.
+            If None, defaults to [cwd, home].
+
+    Returns:
+        A dictionary containing the configuration, or an empty dict if no file is found.
+    """
+    if search_paths is None:
+        search_paths = [
+            Path.cwd(),
+            Path.home(),
+        ]
+
+    for search_path in search_paths:
+        config_path = search_path / filename
+        if config_path.exists():
+            try:
+                with open(config_path, encoding="utf-8") as f:
+                    return json.load(f)
+            except json.JSONDecodeError as e:
+                warnings.warn(
+                    f"Invalid JSON in configuration file '{config_path}': {e}. Skipping this file",
+                    UserWarning,
+                    stacklevel=2,
+                )
+                continue
+            except OSError as e:
+                warnings.warn(
+                    f"Could not read configuration file '{config_path}': {e}. Skipping this file.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+                continue
+
+    return {}

src/kili/presentation/client/asset.py

@@ -29,6 +29,7 @@
 from kili.domain.types import ListOrTuple
 from kili.presentation.client.helpers.common_validators import (
     disable_tqdm_if_as_generator,
+    resolve_disable_tqdm,
 )
 from kili.presentation.client.helpers.filter_conversion import (
     extract_step_ids_from_project_steps,
@@ -499,6 +500,9 @@ def assets(
                     step_name_in=step_name_not_in,
                 )
 
+        # Resolve disable_tqdm: function parameter > client global setting > function default
+        disable_tqdm = resolve_disable_tqdm(disable_tqdm, getattr(self, "disable_tqdm", None))
+
         asset_use_cases = AssetUseCases(self.kili_api_gateway)
         filters = AssetFilters(
             project_id=ProjectId(project_id),

src/kili/presentation/client/base.py

@@ -1,6 +1,7 @@
 """Base class for all client methods classes."""
 
 from abc import ABC
+from typing import Optional
 
 from kili.adapters.kili_api_gateway.kili_api_gateway import KiliAPIGateway
 
@@ -14,3 +15,4 @@ class BaseClientMethods(ABC):
     """
 
     kili_api_gateway: KiliAPIGateway  # instantiated in the Kili client child class
+    disable_tqdm: Optional[bool]  # instantiated in the Kili client child class

src/kili/presentation/client/cloud_storage.py

@@ -20,6 +20,7 @@
 from kili.domain.types import ListOrTuple
 from kili.presentation.client.helpers.common_validators import (
     disable_tqdm_if_as_generator,
+    resolve_disable_tqdm,
 )
 from kili.use_cases.cloud_storage import CloudStorageUseCases
 from kili.utils.logcontext import for_all_methods, log_call
@@ -127,6 +128,7 @@ def cloud_storage_connections(
                 " project_id must be specified"
             )
 
+        disable_tqdm = resolve_disable_tqdm(disable_tqdm, getattr(self, "disable_tqdm", None))
         disable_tqdm = disable_tqdm_if_as_generator(as_generator, disable_tqdm)
 
         cloud_storage_use_cases = CloudStorageUseCases(self.kili_api_gateway)
@@ -230,6 +232,7 @@ def cloud_storage_integrations(
             >>> kili.cloud_storage_integrations()
             [{'name': 'My bucket', 'id': '123456789', 'platform': 'AWS', 'status': 'CONNECTED'}]
         """
+        disable_tqdm = resolve_disable_tqdm(disable_tqdm, getattr(self, "disable_tqdm", None))
         disable_tqdm = disable_tqdm_if_as_generator(as_generator, disable_tqdm)
         options = QueryOptions(disable_tqdm, first, skip)
         data_integrations_gen = CloudStorageUseCases(self.kili_api_gateway).list_data_integrations(

src/kili/presentation/client/helpers/common_validators.py

@@ -20,6 +20,32 @@ def disable_tqdm_if_as_generator(
     return disable_tqdm
 
 
+def resolve_disable_tqdm(
+    disable_tqdm: bool | None, client_disable_tqdm: bool | None
+) -> bool | None:
+    """Resolve the disable_tqdm parameter with priority: function param > client global setting.
+
+    Args:
+        disable_tqdm: The disable_tqdm parameter passed to the function.
+        client_disable_tqdm: The global disable_tqdm setting from the client.
+            Can be None if the client doesn't have this attribute set (e.g., in tests).
+
+    Returns:
+        The resolved disable_tqdm value, or None if both are None (to use function default).
+
+    Examples:
+        >>> resolve_disable_tqdm(True, False)  # Function param takes priority
+        True
+        >>> resolve_disable_tqdm(None, True)   # Use client global setting
+        True
+        >>> resolve_disable_tqdm(None, None)   # Use function default
+        None
+    """
+    if disable_tqdm is not None:
+        return disable_tqdm
+    return client_disable_tqdm
+
+
 def assert_all_arrays_have_same_size(
     arrays: list[Optional[ListOrTuple[Any]]], raise_error: bool = True
 ) -> bool:

src/kili/presentation/client/internal.py

@@ -11,6 +11,7 @@
 from kili.domain.api_key import ApiKeyFilters
 from kili.domain.types import ListOrTuple
 from kili.entrypoints.mutations.project.queries import GQL_DELETE_PROJECT
+from kili.presentation.client.helpers.common_validators import resolve_disable_tqdm
 from kili.presentation.client.organization import InternalOrganizationClientMethods
 from kili.use_cases.api_key import ApiKeyUseCases
 
@@ -97,6 +98,7 @@ def api_keys(
             A result object which contains the query if it was successful,
                 or an error message.
         """
+        disable_tqdm = resolve_disable_tqdm(disable_tqdm, getattr(self, "disable_tqdm", None))
         api_key_use_cases = ApiKeyUseCases(self.kili_api_gateway)
         filters = ApiKeyFilters(api_key_id=api_key_id, user_id=user_id, api_key=api_key)
         api_keys_gen = api_key_use_cases.list_api_keys(

src/kili/presentation/client/issue.py

@@ -15,6 +15,7 @@
 from kili.presentation.client.helpers.common_validators import (
     assert_all_arrays_have_same_size,
     disable_tqdm_if_as_generator,
+    resolve_disable_tqdm,
 )
 from kili.use_cases.issue import IssueUseCases
 from kili.use_cases.issue.types import IssueToCreateUseCaseInput
@@ -195,6 +196,7 @@ def issues(
                 "You cannot provide both `asset_id` and `asset_id_in` at the same time."
             )
 
+        disable_tqdm = resolve_disable_tqdm(disable_tqdm, getattr(self, "disable_tqdm", None))
         disable_tqdm = disable_tqdm_if_as_generator(as_generator, disable_tqdm)
         options = QueryOptions(disable_tqdm=disable_tqdm, first=first, skip=skip)
         issues_gen = IssueUseCases(self.kili_api_gateway).list_issues(

src/kili/presentation/client/label.py

@@ -37,6 +37,7 @@
 from kili.presentation.client.helpers.common_validators import (
     assert_all_arrays_have_same_size,
     disable_tqdm_if_as_generator,
+    resolve_disable_tqdm,
 )
 from kili.presentation.client.helpers.filter_conversion import (
     extract_step_ids_from_project_steps,
@@ -454,6 +455,7 @@ def labels(
         if category_search:
             validate_category_search_query(category_search)
 
+        disable_tqdm = resolve_disable_tqdm(disable_tqdm, getattr(self, "disable_tqdm", None))
         disable_tqdm = disable_tqdm_if_as_generator(as_generator, disable_tqdm)
         options = QueryOptions(disable_tqdm, first, skip)