feat: Add list events method (#1831)

Author: florianlega

docs/sdk/event.md

@@ -0,0 +1,3 @@
+# Event module
+
+::: kili.event.presentation.client.event.EventClientMethods

mkdocs.yml

@@ -16,6 +16,7 @@ nav:
       - Reference:
           - Asset: sdk/asset.md
           - Cloud Storage: sdk/cloud_storage.md
+          - Event: sdk/event.md
           - Issue: sdk/issue.md
           - Label: sdk/label.md
           - Label Utils: sdk/label_utils.md

src/kili/adapters/kili_api_gateway/event/__init__.py

@@ -0,0 +1 @@
+"""Api key Kili Gateway module."""

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

@@ -0,0 +1,24 @@
+"""GraphQL payload data mappers for api keys operations."""
+
+from typing import Dict
+
+from kili.domain.event import EventFilters, QueryOptions
+
+
+def event_where_wrapper(filter: EventFilters) -> Dict:
+    """Build the GraphQL EventMapperWhere variable to be sent in an operation."""
+    return {
+        "projectId": filter.project_id,
+        "createdAtGte": filter.created_at_gte,
+        "createdAtLte": filter.created_at_lte,
+        "userId": filter.user_id,
+        "event": filter.event,
+    }
+
+
+def event_pagination_wrapper(options: QueryOptions) -> Dict:
+    """Build the GraphQL EventMapperPagination variable to be sent in an operation."""
+    return {
+        "fromEventId": options.from_event_id,
+        "untilEventId": options.until_event_id,
+    }

src/kili/adapters/kili_api_gateway/event/operations.py

@@ -0,0 +1,12 @@
+"""GraphQL Event operations."""
+
+
+def get_events_query(fragment: str) -> str:
+    """Return the GraphQL events query."""
+    return f"""
+          query Events($where: EventsWhere!, $pagination: EventPagination!, $order: Order) {{
+            data: events(where: $where, pagination: $pagination, order: $order) {{
+                {fragment}
+              }}
+            }}
+        """

src/kili/adapters/kili_api_gateway/event/operations_mixin.py

@@ -0,0 +1,54 @@
+"""Mixin extending Kili API Gateway class with Api Keys related operations."""
+
+from typing import List, Optional, cast
+
+from kili.adapters.kili_api_gateway.base import BaseOperationMixin
+from kili.adapters.kili_api_gateway.event.mappers import (
+    event_pagination_wrapper,
+    event_where_wrapper,
+)
+from kili.adapters.kili_api_gateway.event.operations import get_events_query
+from kili.adapters.kili_api_gateway.event.queries import (
+    PaginatedGraphQLQuery,
+)
+from kili.adapters.kili_api_gateway.helpers.queries import fragment_builder
+from kili.domain.event import EventDict, EventFilters, QueryOptions
+from kili.domain.types import ListOrTuple
+
+DEFAULT_EVENT_FIELDS = [
+    "createdAt",
+    "event",
+    "id",
+    "organizationId",
+    "payload",
+    "projectId",
+    "userId",
+]
+
+
+class EventOperationMixin(BaseOperationMixin):
+    """Mixin extending Kili API Gateway class with event related operations."""
+
+    def list_events(
+        self,
+        filters: EventFilters,
+        options: QueryOptions,
+        fields: Optional[ListOrTuple[str]] = None,
+    ) -> List[EventDict]:
+        """List events with given options."""
+        fragment = fragment_builder(fields or DEFAULT_EVENT_FIELDS)
+        query = get_events_query(fragment)
+        where = event_where_wrapper(filters)
+        pagination = event_pagination_wrapper(options)
+
+        return [
+            cast(EventDict, item)
+            for item in PaginatedGraphQLQuery(
+                self.graphql_client
+            ).execute_query_from_paginated_call(
+                query,
+                where,
+                pagination,
+                options,
+            )
+        ]

src/kili/adapters/kili_api_gateway/event/queries.py

@@ -0,0 +1,60 @@
+"""GraphQL module."""
+
+from typing import Any, Dict, Generator
+
+from kili.core.graphql.graphql_client import GraphQLClient
+from kili.domain.event import QueryOptions
+
+
+class PaginatedGraphQLQuery:
+    """Query class for querying Kili objects.
+
+    It factorizes code for executing paginated queries.
+    """
+
+    def __init__(self, graphql_client: GraphQLClient) -> None:
+        """Initialize the paginator."""
+        self._graphql_client = graphql_client
+
+    # pylint: disable=too-many-arguments
+    def execute_query_from_paginated_call(
+        self,
+        query: str,
+        where: Dict[str, Any],
+        pagination: Dict[str, Any],
+        options: QueryOptions,
+    ) -> Generator[Dict, None, None]:
+        """Build a row generator from paginated query calls with the first and skip pattern.
+
+        Args:
+            query: The object query to execute and to send to graphQL, in string format
+            where: The where payload to send in the graphQL query
+            pagination: The where pagination payload to send in the graphQL query
+            options: The query options with skip and first and disable_tqdm
+        """
+        count_elements_retrieved = 0
+        while True:
+            skip = count_elements_retrieved + options.skip
+            first = options.batch_size
+            order = options.order
+
+            payload = {
+                "where": where,
+                "pagination": {"skip": skip, "first": first, **pagination},
+                "order": order,
+            }
+            elements = self._graphql_client.execute(query, payload)["data"]
+            if not isinstance(elements, list):
+                raise TypeError(
+                    "PaginatedGraphQLQuery only support operations returning a list of objects"
+                )
+
+            if len(elements) == 0:
+                break
+
+            yield from elements
+
+            count_elements_retrieved += len(elements)
+
+            if len(elements) < first:
+                break

src/kili/adapters/kili_api_gateway/kili_api_gateway.py

@@ -4,6 +4,7 @@
 from kili.adapters.kili_api_gateway.api_key.operations_mixin import ApiKeyOperationMixin
 from kili.adapters.kili_api_gateway.asset.operations_mixin import AssetOperationMixin
 from kili.adapters.kili_api_gateway.cloud_storage import CloudStorageOperationMixin
+from kili.adapters.kili_api_gateway.event.operations_mixin import EventOperationMixin
 from kili.adapters.kili_api_gateway.issue import IssueOperationMixin
 from kili.adapters.kili_api_gateway.label.operations_mixin import LabelOperationMixin
 from kili.adapters.kili_api_gateway.llm.operations_mixin import (
@@ -33,6 +34,7 @@ class KiliAPIGateway(
     ProjectOperationMixin,
     TagOperationMixin,
     UserOperationMixin,
+    EventOperationMixin,
 ):
     """GraphQL gateway to communicate with Kili backend."""
 

src/kili/client.py

@@ -21,6 +21,7 @@
 from kili.entrypoints.queries.project_user import QueriesProjectUser
 from kili.entrypoints.queries.project_version import QueriesProjectVersion
 from kili.entrypoints.subscriptions.label import SubscriptionsLabel
+from kili.event.presentation.client.event import EventClientMethods
 from kili.exceptions import AuthenticationFailed
 from kili.llm.presentation.client.llm import LlmClientMethods
 from kili.presentation.client.asset import AssetClientMethods
@@ -167,6 +168,7 @@ def __init__(
         self.kili_api_gateway = KiliAPIGateway(self.graphql_client, self.http_client)
         self.internal = InternalClientMethods(self.kili_api_gateway)
         self.llm = LlmClientMethods(self.kili_api_gateway)
+        self.events = EventClientMethods(self.kili_api_gateway)
 
         if not skip_checks:
             api_key_use_cases = ApiKeyUseCases(self.kili_api_gateway)

src/kili/domain/event.py

@@ -0,0 +1,49 @@
+"""Event domain."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, NamedTuple, Optional
+
+from typing_extensions import TypedDict
+
+from kili.core.constants import QUERY_BATCH_SIZE
+
+if TYPE_CHECKING:
+    from .project import ProjectId
+    from .user import UserId
+
+OrderType = Literal["asc", "desc"]
+
+
+@dataclass
+# pylint: disable=too-many-instance-attributes
+class EventFilters:
+    """Event filters for running an event search."""
+
+    project_id: "ProjectId"
+    created_at_gte: Optional[str] = None
+    created_at_lte: Optional[str] = None
+    user_id: Optional["UserId"] = None
+    event: Optional[str] = None
+
+
+class EventDict(TypedDict):
+    """Dict that represents an Event."""
+
+    created_at: str
+    event: str
+    id: str
+    organization_id: str
+    payload: dict
+    project_id: str
+    user_id: str
+
+
+class QueryOptions(NamedTuple):
+    """Options when calling GraphQLQuery from the SDK."""
+
+    first: Optional[int] = None
+    skip: int = 0
+    batch_size: int = QUERY_BATCH_SIZE
+    from_event_id: Optional[str] = None
+    until_event_id: Optional[str] = None
+    order: Optional[OrderType] = "asc"