konecty-sdk-python 2.0.0__tar.gz → 2.0.2__tar.gz

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/KonectySdkPython/lib/client.py

@@ -10,7 +10,6 @@ import aiohttp
 from .exceptions import (
     KonectyAPIError,
     KonectyError,
-    KonectySerializationError,
     KonectyValidationError,
 )
 from .file_manager import FileManager
@@ -18,6 +17,7 @@ from .filters import KonectyFilter, KonectyFindParams
 from .http import request as _http_request
 from .http import StreamResponse
 from .feature_types.kpi import KpiConfig
+from .serialization import json_serial
 from .services.aggregation import AggregationService
 from .services.change_user import ChangeUserService
 from .services.comments import CommentsService
@@ -27,15 +27,13 @@ from .services.notifications import NotificationsService
 from .services.query import QueryResult, QueryService
 from .services.stream import FindStreamResult, StreamService
 from .services.subscriptions import SubscriptionsService
-from .types import KonectyDateTime, KonectyUpdateId
+from .types import KonectyDateTime, KonectyDict, KonectyUpdateId
 
 # Configura o logger do urllib3 para mostrar apenas erros
 logging.getLogger("urllib3.connectionpool").setLevel(logging.ERROR)
 
 logger = logging.getLogger(__name__)
 
-KonectyDict = Dict[str, Any]
-
 KONECTY_UPDATE_IGNORE_FIELDS = [
     "_id",
     "code",
@@ -57,13 +55,6 @@ def get_first_dict(items: List[Any]) -> Optional[KonectyDict]:
     return None
 
 
-def json_serial(obj: Any) -> str:
-    """Serializa objetos para JSON."""
-    if isinstance(obj, datetime):
-        return {"$date": obj.isoformat()}
-    raise KonectySerializationError()
-
-
 class KonectyClient:
     def __init__(self, base_url: str, token: str) -> None:
         self.base_url = base_url

konecty_sdk_python-2.0.2/KonectySdkPython/lib/feature_types/__init__.py

@@ -0,0 +1,46 @@
+"""Feature-specific types (KPI, Graph, Pivot, CrossModuleQuery, QueryJson, etc.). Re-exported for convenience."""
+
+from .cross_module_query import (
+    DEFAULT_PRIMARY_LIMIT,
+    MAX_RELATION_LIMIT,
+    MAX_RELATIONS,
+    Aggregator,
+    CrossModuleQuery,
+    CrossModuleRelation,
+)
+from .kpi import KpiConfig, KpiOperation
+from .query_json import (
+    AggregatorName,
+    AggregatorSpec,
+    ConditionValue,
+    ExplicitJoinCondition,
+    FilterMatch,
+    QueryFilter,
+    QueryFilterCondition,
+    QueryJson,
+    QueryRelation,
+    QuerySortItem,
+    SortDirection,
+)
+
+__all__ = [
+    "Aggregator",
+    "AggregatorName",
+    "AggregatorSpec",
+    "ConditionValue",
+    "CrossModuleQuery",
+    "CrossModuleRelation",
+    "DEFAULT_PRIMARY_LIMIT",
+    "ExplicitJoinCondition",
+    "FilterMatch",
+    "KpiConfig",
+    "KpiOperation",
+    "MAX_RELATION_LIMIT",
+    "MAX_RELATIONS",
+    "QueryFilter",
+    "QueryFilterCondition",
+    "QueryJson",
+    "QueryRelation",
+    "QuerySortItem",
+    "SortDirection",
+]

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/KonectySdkPython/lib/feature_types/cross_module_query.py

@@ -10,7 +10,9 @@ MAX_RELATION_LIMIT = 100_000
 DEFAULT_RELATION_LIMIT = 1000
 DEFAULT_PRIMARY_LIMIT = 1000
 
-AggregatorName = str  # count, countDistinct, sum, avg, min, max, first, last, push, addToSet
+AggregatorName = (
+    str  # count, countDistinct, sum, avg, min, max, first, last, push, addToSet
+)
 
 
 class Aggregator(BaseModel):
@@ -46,7 +48,9 @@ class CrossModuleRelation(BaseModel):
     limit: int = Field(default=DEFAULT_RELATION_LIMIT, ge=1, le=MAX_RELATION_LIMIT)
     start: int = Field(default=0, ge=0)
     aggregators: Dict[str, Aggregator] = Field(..., min_length=1)
-    relations: Optional[List["CrossModuleRelation"]] = Field(default=None, max_length=MAX_RELATIONS)
+    relations: Optional[List["CrossModuleRelation"]] = Field(
+        default=None, max_length=MAX_RELATIONS
+    )
 
     model_config = {"extra": "allow"}
 
@@ -63,7 +67,9 @@ class CrossModuleQuery(BaseModel):
     sort: Optional[Union[str, List[SortItem]]] = None
     limit: int = Field(default=DEFAULT_PRIMARY_LIMIT, ge=1, le=MAX_RELATION_LIMIT)
     start: int = Field(default=0, ge=0)
-    relations: List[CrossModuleRelation] = Field(default_factory=list, max_length=MAX_RELATIONS)
+    relations: List[CrossModuleRelation] = Field(
+        default_factory=list, max_length=MAX_RELATIONS
+    )
     groupBy: List[str] = Field(default_factory=list, alias="groupBy")
     aggregators: Dict[str, Aggregator] = Field(default_factory=dict)
     includeTotal: bool = Field(default=True, alias="includeTotal")

konecty_sdk_python-2.0.2/KonectySdkPython/lib/feature_types/query_json.py

@@ -0,0 +1,242 @@
+"""
+Strongly-typed query creator for POST /rest/query/json (Konecty cross-module query).
+Use classes/dataclasses with properties for full intellisense; no builder pattern.
+Serializes to the exact payload Konecty expects via to_dict().
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Union
+
+# ---------------------------------------------------------------------------
+# Literal types (Konecty schema)
+# ---------------------------------------------------------------------------
+
+AggregatorName = Literal[
+    "count",
+    "countDistinct",
+    "sum",
+    "avg",
+    "min",
+    "max",
+    "first",
+    "last",
+    "push",
+    "addToSet",
+]
+"""Allowed aggregator names for relations (Konecty schema)."""
+
+FilterMatch = Literal["and", "or"]
+SortDirection = Literal["ASC", "DESC"]
+
+# Value in a filter condition: scalar or list (e.g. for "in" operator)
+ConditionValue = Union[str, int, float, bool, None, List[Union[str, int, float, bool]]]
+
+
+# ---------------------------------------------------------------------------
+# Filter (KonFilter)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=False)
+class QueryFilterCondition:
+    """Single condition: term, operator, optional value. Mirrors Konecty Condition."""
+
+    term: str
+    operator: str
+    value: Optional[ConditionValue] = None
+    editable: Optional[bool] = None
+    disabled: Optional[bool] = None
+    sort: Optional[int] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"term": self.term, "operator": self.operator}
+        if self.value is not None:
+            out["value"] = self.value
+        if self.editable is not None:
+            out["editable"] = self.editable
+        if self.disabled is not None:
+            out["disabled"] = self.disabled
+        if self.sort is not None:
+            out["sort"] = self.sort
+        return out
+
+
+@dataclass(frozen=False)
+class QueryFilter:
+    """Filter for query or relation. match + conditions; optional textSearch and nested filters."""
+
+    match: FilterMatch = "and"
+    conditions: List[QueryFilterCondition] = field(default_factory=list)
+    text_search: Optional[str] = None
+    filters: Optional[List["QueryFilter"]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"match": self.match}
+        if self.conditions:
+            out["conditions"] = [c.to_dict() for c in self.conditions]
+        if self.text_search is not None:
+            out["textSearch"] = self.text_search
+        if self.filters:
+            out["filters"] = [f.to_dict() for f in self.filters]
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Sort
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class QuerySortItem:
+    """Sort item: property and direction. Konecty sort element."""
+
+    property: str
+    direction: SortDirection = "ASC"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"property": self.property, "direction": self.direction}
+
+
+# ---------------------------------------------------------------------------
+# Join (explicit on)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ExplicitJoinCondition:
+    """Explicit join: left and right keys. Optional in relation."""
+
+    left: str
+    right: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"left": self.left, "right": self.right}
+
+
+# ---------------------------------------------------------------------------
+# Aggregator
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AggregatorSpec:
+    """Aggregator in a relation. aggregator (name); field required for countDistinct and similar."""
+
+    aggregator: AggregatorName
+    field: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"aggregator": self.aggregator}
+        if self.field is not None:
+            out["field"] = self.field
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Relation (nested)
+# ---------------------------------------------------------------------------
+
+# Sort in relation: list of QuerySortItem or single string (e.g. "_createdAt DESC")
+RelationSort = Union[List[QuerySortItem], str]
+
+
+@dataclass(frozen=False)
+class QueryRelation:
+    """
+    Relation in a cross-module query. document + lookup; at least one aggregator required.
+    Optional: on, filter, fields, sort, limit, start; optional nested relations.
+    """
+
+    document: str
+    lookup: str
+    aggregators: Dict[str, AggregatorSpec]
+    on: Optional[ExplicitJoinCondition] = None
+    filter: Optional[QueryFilter] = None
+    fields: Optional[str] = None
+    sort: Optional[RelationSort] = None
+    limit: int = 1000
+    start: int = 0
+    relations: Optional[List["QueryRelation"]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        if not self.aggregators:
+            raise ValueError("At least one aggregator is required per relation")
+        out: Dict[str, Any] = {
+            "document": self.document,
+            "lookup": self.lookup,
+            "aggregators": {k: v.to_dict() for k, v in self.aggregators.items()},
+            "limit": self.limit,
+            "start": self.start,
+        }
+        if self.on is not None:
+            out["on"] = self.on.to_dict()
+        if self.filter is not None:
+            out["filter"] = self.filter.to_dict()
+        if self.fields is not None:
+            out["fields"] = self.fields
+        if self.sort is not None:
+            if isinstance(self.sort, str):
+                out["sort"] = self.sort
+            else:
+                out["sort"] = [s.to_dict() for s in self.sort]
+        if self.relations:
+            out["relations"] = [r.to_dict() for r in self.relations]
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Root query (CrossModuleQuery)
+# ---------------------------------------------------------------------------
+
+# Sort at root: list of QuerySortItem or string
+QuerySort = Union[List[QuerySortItem], str]
+
+# Limits (Konecty constants)
+MAX_RELATION_LIMIT_QUERY = 100_000
+DEFAULT_PRIMARY_LIMIT_QUERY = 1000
+
+
+@dataclass(frozen=False)
+class QueryJson:
+    """
+    Fully-typed body for POST /rest/query/json. Primary document + optional filter,
+    fields, sort, limit, start, relations, groupBy, aggregators, includeTotal, includeMeta.
+    Use to_dict() to get the API payload (camelCase where required).
+    """
+
+    document: str
+    filter: Optional[QueryFilter] = None
+    fields: Optional[str] = None
+    sort: Optional[QuerySort] = None
+    limit: int = DEFAULT_PRIMARY_LIMIT_QUERY
+    start: int = 0
+    relations: List[QueryRelation] = field(default_factory=list)
+    group_by: List[str] = field(default_factory=list)
+    aggregators: Dict[str, AggregatorSpec] = field(default_factory=dict)
+    include_total: bool = True
+    include_meta: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Payload for POST /rest/query/json (camelCase for includeTotal, includeMeta, groupBy)."""
+        out: Dict[str, Any] = {
+            "document": self.document,
+            "limit": max(1, min(self.limit, MAX_RELATION_LIMIT_QUERY)),
+            "start": max(0, self.start),
+            "relations": [r.to_dict() for r in self.relations],
+            "groupBy": self.group_by,
+            "aggregators": {k: v.to_dict() for k, v in self.aggregators.items()},
+            "includeTotal": self.include_total,
+            "includeMeta": self.include_meta,
+        }
+        if self.filter is not None:
+            out["filter"] = self.filter.to_dict()
+        if self.fields is not None:
+            out["fields"] = self.fields
+        if self.sort is not None:
+            if isinstance(self.sort, str):
+                out["sort"] = self.sort
+            else:
+                out["sort"] = [s.to_dict() for s in self.sort]
+        return out

konecty_sdk_python-2.0.2/KonectySdkPython/lib/serialization.py

@@ -0,0 +1,13 @@
+"""JSON serialization helpers for Konecty API (e.g. $date format)."""
+
+from datetime import datetime
+from typing import Any
+
+from .exceptions import KonectySerializationError
+
+
+def json_serial(obj: Any) -> Any:
+    """Serialize objects to JSON-friendly form (e.g. datetime -> $date)."""
+    if isinstance(obj, datetime):
+        return {"$date": obj.isoformat()}
+    raise KonectySerializationError()

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/KonectySdkPython/lib/services/aggregation.py

@@ -3,7 +3,7 @@
 import json
 from typing import Any, Dict, Optional, Union
 
-from ..client import json_serial
+from ..serialization import json_serial
 from ..filters import KonectyFilter
 from ..feature_types.kpi import KpiConfig
 from .base import BaseService

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/KonectySdkPython/lib/services/export.py

@@ -3,7 +3,7 @@
 import json
 from typing import Any, Dict, List, Literal, Optional, Union
 
-from ..client import json_serial
+from ..serialization import json_serial
 from ..filters import KonectyFilter
 from .base import BaseService
 

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/KonectySdkPython/lib/services/query.py

@@ -3,7 +3,7 @@
 import json
 from typing import Any, AsyncGenerator, Dict, List, Optional, Union
 
-from ..client import KonectyDict
+from ..types import KonectyDict
 from ..exceptions import KonectyAPIError
 from ..http import StreamResponse
 from .base import BaseService
@@ -93,7 +93,9 @@ class QueryService(BaseService):
         Execute a cross-module query. POST /rest/query/json. Body is CrossModuleQuery (dict or model).
         Returns QueryResult with .stream (async generator), .total, .meta.
         """
-        if hasattr(body, "model_dump"):
+        if hasattr(body, "to_dict"):
+            payload = body.to_dict()
+        elif hasattr(body, "model_dump"):
             payload = body.model_dump(by_alias=True, exclude_none=True)
         else:
             payload = dict(body)

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/KonectySdkPython/lib/services/stream.py

@@ -3,7 +3,8 @@
 import json
 from typing import Any, AsyncGenerator, Dict, Optional
 
-from ..client import KonectyDict, json_serial
+from ..serialization import json_serial
+from ..types import KonectyDict
 from ..filters import KonectyFilter, KonectyFindParams
 from ..http import StreamResponse
 from .base import BaseService

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/KonectySdkPython/lib/types.py

@@ -8,6 +8,8 @@ from pydantic import BaseModel, ConfigDict, Field
 from pydantic.json_schema import JsonSchemaValue
 from pydantic_core import CoreSchema, core_schema
 
+KonectyDict = Dict[str, Any]
+
 
 class KonectyDateTimeError(Exception):
     """Exceção base para erros de data/hora."""

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: konecty_sdk_python
-Version: 2.0.0
+Version: 2.0.2
 Summary: Konecty SDK Python
 Author-email: Leonardo Leal <leonardo.leal@konecty.com>, Derotino Silveira <derotino.silveira@konecty.com>
 License: MIT

{konecty_sdk_python-2.0.0 → konecty_sdk_python-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "konecty_sdk_python"
-version = "2.0.0"
+version = "2.0.2"
 description = "Konecty SDK Python"
 readme = "README.md"
 requires-python = ">=3.11"

konecty_sdk_python-2.0.0/KonectySdkPython/lib/feature_types/__init__.py

@@ -1,22 +0,0 @@
-"""Feature-specific types (KPI, Graph, Pivot, CrossModuleQuery, etc.). Re-exported for convenience."""
-
-from .cross_module_query import (
-    CrossModuleQuery,
-    CrossModuleRelation,
-    Aggregator,
-    DEFAULT_PRIMARY_LIMIT,
-    MAX_RELATION_LIMIT,
-    MAX_RELATIONS,
-)
-from .kpi import KpiConfig, KpiOperation
-
-__all__ = [
-    "Aggregator",
-    "CrossModuleQuery",
-    "CrossModuleRelation",
-    "DEFAULT_PRIMARY_LIMIT",
-    "KpiConfig",
-    "KpiOperation",
-    "MAX_RELATION_LIMIT",
-    "MAX_RELATIONS",
-]