ergon-framework-python 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

ergon/connector/ergon_platform/connector.py

@@ -1,200 +1,5 @@
-import logging
-from typing import Any, Dict, List, Optional
+"""Deprecated compatibility import for the Workflows connector."""
 
-from ..connector import Connector
-from ..transaction import Transaction
-from ._client import create_ergon_client
-from ._operations import _ErgonPlatformOperations
-from .models import (
-    CreateItemPayload,
-    ErgonPlatformClient,
-    ErgonPlatformConsumerConfig,
-    ErgonPlatformProducerConfig,
-)
-from .utils import get_value, normalize_create_payload
+from .workflows.connector import ErgonPlatformConnector
 
-logger = logging.getLogger(__name__)
-
-
-class ErgonPlatformConnector(Connector):
-    def __init__(
-        self,
-        client: ErgonPlatformClient,
-        consumer_config: Optional[ErgonPlatformConsumerConfig] = None,
-        producer_config: Optional[ErgonPlatformProducerConfig] = None,
-    ) -> None:
-        self.client = create_ergon_client(client)
-        self._operations = _ErgonPlatformOperations(client, self.client)
-        self._consumer_config = consumer_config
-        self._producer_config = producer_config or ErgonPlatformProducerConfig()
-
-    def fetch_transactions(
-        self,
-        batch_size: Optional[int] = None,
-        *args,
-        **kwargs,
-    ) -> List[Transaction]:
-        if self._consumer_config is None:
-            raise ValueError("ErgonPlatformConnector requires a consumer_config to fetch transactions")
-
-        config = self._consumer_config
-        limit = batch_size or config.batch_size
-        params: Dict[str, Any] = {**config.list_params, **kwargs}
-        if config.unassigned:
-            params.pop("assigned_to", None)
-            params["assigned"] = "no"
-
-        transactions = self._operations.fetch_items(
-            config.workflow_id,
-            config.phase_id,
-            limit=limit,
-            offset=config.offset,
-            **params,
-        )
-        if not config.unassigned:
-            return transactions
-
-        claimed_transactions: List[Transaction] = []
-        for transaction in transactions:
-            try:
-                self.client.workflows.items.claim(transaction.id, {})
-                claimed_transactions.append(self.fetch_transaction_by_id(transaction.id))
-            except Exception:
-                logger.warning(
-                    "Failed to claim item %s during unassigned fetch; skipping it",
-                    transaction.id,
-                    exc_info=True,
-                )
-        return claimed_transactions
-
-    def dispatch_transactions(self, transactions: List[Transaction], *args, **kwargs) -> List[str]:
-        created_ids: List[str] = []
-        for transaction in transactions:
-            result = self._create_from_payload(transaction.payload)
-            created_ids.append(self._created_item_id(result))
-        return created_ids
-
-    def fetch_child_transactions(
-        self,
-        parent_item_id: str,
-        *args,
-        **kwargs,
-    ) -> List[Transaction]:
-        return self._operations.fetch_child_items(parent_item_id, **kwargs)
-
-    def fetch_transaction_by_id(self, transaction_id: str, *args, **kwargs) -> Transaction:
-        workflow_id = self._consumer_config.workflow_id if self._consumer_config else ""
-        return self._operations.get_item_transaction(transaction_id, workflow_id, **kwargs)
-
-    def fetch_items_by_query(
-        self, workflow_id: str, query: Optional[Dict[str, Any]] = None, **fields: Any
-    ) -> List[Transaction]:
-        return self._operations.fetch_items_by_query(workflow_id, query, **fields)
-
-    def get_transactions_count(self, *args, **kwargs) -> int:
-        if self._consumer_config is None:
-            raise ValueError("ErgonPlatformConnector requires a consumer_config to count transactions")
-
-        config = self._consumer_config
-        params: Dict[str, Any] = {**config.list_params, **kwargs}
-        return self._operations.get_phase_items_count(
-            config.workflow_id,
-            config.phase_id,
-            **params,
-        )
-
-    def ack_transaction(self, transaction: Transaction, phase_id: Optional[str] = None) -> None:
-        target_phase = phase_id
-        if target_phase is None and self._consumer_config is not None:
-            target_phase = self._consumer_config.ack_phase_id
-        if not target_phase:
-            return
-        self.client.workflows.items.route(transaction.id, to_phase_id=target_phase)
-
-    def release_item(
-        self,
-        item_id: str,
-        data: Optional[Dict[str, Any]] = None,
-        *,
-        delay_seconds: Optional[int] = None,
-        **fields: Any,
-    ) -> Any:
-        return self._operations.release_item(
-            item_id,
-            data,
-            delay_seconds=delay_seconds,
-            **fields,
-        )
-
-    def nack_transaction(self, transaction: Transaction, requeue: bool = True, delay_seconds: int = 10) -> None:
-        if requeue:
-            self._operations.release_item(transaction.id, delay_seconds=delay_seconds)
-            return
-
-        target_phase = self._consumer_config.nack_phase_id if self._consumer_config is not None else None
-        if not target_phase:
-            raise ValueError("nack_phase_id is required when nack_transaction is called with requeue=False")
-
-        self.client.workflows.items.route(transaction.id, to_phase_id=target_phase)
-        logger.debug("Item %s moved to nack phase %s", transaction.id, target_phase)
-
-    def close(self) -> None:
-        self.client.close()
-
-    def list_phase_fields(
-        self,
-        phase_id: str,
-        *,
-        workflow_id: Optional[str] = None,
-        include_workflow_fields: bool = True,
-        **params: Any,
-    ) -> Any:
-        return self._operations.list_phase_fields(
-            phase_id,
-            workflow_id=workflow_id,
-            include_workflow_fields=include_workflow_fields,
-            **params,
-        )
-
-    def get_pipeline_result(
-        self,
-        workflow_id: str,
-        item_id: str,
-        field_id: str,
-        buckets_file_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        return self._operations.get_pipeline_result(workflow_id, item_id, field_id, buckets_file_id)
-
-    def _create_from_payload(self, payload: CreateItemPayload) -> Any:
-        data = normalize_create_payload(payload)
-        producer = self._producer_config
-
-        workflow_id = data.get("workflow_id") or producer.workflow_id
-        phase_id = data.get("phase_id") or producer.phase_id
-        if not workflow_id:
-            raise ValueError("workflow_id is required to create an item (set it in payload or producer_config)")
-        if not phase_id:
-            raise ValueError("phase_id is required to create an item (set it in payload or producer_config)")
-
-        attachment = data.get("attachment")
-        attachment_field_id = data.get("attachment_field_id") or producer.attachment_field_id
-        content_type = data.get("content_type") or producer.default_content_type
-        parent_item_id = data.get("parent_item_id") or producer.parent_item_id
-
-        return self._operations.create_item(
-            workflow_id,
-            phase_id,
-            data["title"],
-            parent_item_id=parent_item_id,
-            field_values=data.get("field_values"),
-            attachment=attachment,
-            attachment_field_id=attachment_field_id,
-            content_type=content_type,
-            **data.get("fields", {}),
-        )
-
-    @staticmethod
-    def _created_item_id(result: Any) -> str:
-        if isinstance(result, dict) and "item" in result:
-            return str(get_value(result["item"], "id", ""))
-        return str(get_value(result, "id", ""))
+__all__ = ["ErgonPlatformConnector"]

ergon/connector/ergon_platform/models.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, Optional, Union
+from typing import Optional
 
 from pydantic import BaseModel, Field
 
@@ -33,75 +33,3 @@ class ErgonPlatformClient(BaseModel):
     )
     timeout: float = Field(default=30.0, description="HTTP timeout in seconds")
     max_retries: int = Field(default=2, ge=0, description="Max automatic HTTP retries")
-
-
-class ErgonPlatformConsumerConfig(BaseModel):
-    """Parameters used to list workflow items as transactions."""
-
-    workflow_id: str = Field(description="Workflow ID to consume items from")
-    phase_id: str = Field(description="Phase ID to list items from")
-    batch_size: int = Field(default=50, ge=1, description="Max items per fetch")
-    offset: int = Field(default=0, ge=0, description="Pagination offset")
-    ack_phase_id: Optional[str] = Field(
-        default=None,
-        description="Phase to route an item to on ack; ack is a no-op when omitted",
-    )
-    nack_phase_id: Optional[str] = Field(
-        default=None,
-        description="Phase to route an item to on nack when requeue=False",
-    )
-    unassigned: bool = Field(
-        default=False,
-        description="When true, fetch only unassigned cards and claim them during fetch",
-    )
-    list_params: Dict[str, Any] = Field(
-        default_factory=dict,
-        description="Extra query params forwarded to the items listing endpoint",
-    )
-
-
-class ErgonPlatformProducerConfig(BaseModel):
-    """Defaults applied when creating items via dispatch."""
-
-    workflow_id: Optional[str] = Field(default=None, description="Default workflow for created items")
-    phase_id: Optional[str] = Field(default=None, description="Default phase for created items")
-    attachment_field_id: Optional[str] = Field(
-        default=None,
-        description="Default field ID used when an attachment is provided",
-    )
-    default_content_type: Optional[str] = Field(
-        default=None,
-        description="Fallback MIME type when it cannot be guessed from the filename",
-    )
-    parent_item_id: Optional[str] = Field(
-        default=None,
-        description="Default parent item ID used to create child items via dispatch",
-    )
-
-
-class CreateItemInput(BaseModel):
-    """Payload describing an item to create, with optional attachment upload."""
-
-    title: str = Field(description="Item title")
-    workflow_id: Optional[str] = Field(default=None, description="Workflow ID; falls back to producer config")
-    phase_id: Optional[str] = Field(default=None, description="Target phase ID; falls back to producer config")
-    parent_item_id: Optional[str] = Field(
-        default=None,
-        description="Optional parent item ID to create this item as a child",
-    )
-    field_values: Optional[Dict[str, Any]] = Field(default=None, description="Field values keyed by field ID")
-    attachment: Optional[str] = Field(default=None, description="Local file path to upload after creation")
-    attachment_field_id: Optional[str] = Field(
-        default=None,
-        description="Field ID that receives the attachment; falls back to producer config",
-    )
-    content_type: Optional[str] = Field(default=None, description="Override MIME type for the attachment")
-    extra_fields: Dict[str, Any] = Field(
-        default_factory=dict,
-        description="Additional keyword fields forwarded to create_item",
-    )
-
-    model_config = {"populate_by_name": True}
-
-
-CreateItemPayload = Union[CreateItemInput, Dict[str, Any]]

ergon/connector/ergon_platform/utils.py

@@ -1,250 +1,41 @@
-import base64
-import json
-from typing import Any, Dict, List, Optional
-
-from ..transaction import Transaction
-from .models import (
-    FAILURE_STATUSES,
-    PROCESSING_STATUSES,
-    SUCCESS_STATUSES,
-    CreateItemInput,
-    CreateItemPayload,
+"""Deprecated compatibility exports for Workflows connector helpers."""
+
+from .workflows.utils import (
+    as_payload,
+    build_redispatch_transaction,
+    classify_status,
+    decode_jwt_claims,
+    extract_buckets_file_id,
+    extract_buckets_file_id_from_attachments,
+    extract_items,
+    extract_status_entries,
+    extract_status_file_id,
+    extract_total,
+    find_status_entry,
+    get_value,
+    item_to_transaction,
+    latest_status_entry,
+    normalize_create_payload,
+    requeue,
+    serialize_object,
 )
 
-
-def get_value(obj: Any, key: str, default: Any = None) -> Any:
-    """Read a key from a dict or an attribute from an object, tolerating both shapes."""
-    if isinstance(obj, dict):
-        return obj.get(key, default)
-    return getattr(obj, key, default)
-
-
-def as_payload(obj: Any) -> Any:
-    """Convert SDK models to JSON-friendly payloads while leaving plain data untouched."""
-    if hasattr(obj, "model_dump"):
-        return obj.model_dump(mode="json")
-    return obj
-
-
-def serialize_object(obj: Any) -> Any:
-    if obj is None:
-        return None
-    if isinstance(obj, (str, int, float, bool, bytes)):
-        return obj
-    if isinstance(obj, dict):
-        return {k: serialize_object(v) for k, v in obj.items()}
-    if isinstance(obj, (list, tuple)):
-        return [serialize_object(item) for item in obj]
-    if hasattr(obj, "model_dump"):
-        return obj.model_dump(mode="json")
-    if hasattr(obj, "to_dict"):
-        return obj.to_dict()
-    if hasattr(obj, "__dict__"):
-        return {k: serialize_object(v) for k, v in obj.__dict__.items() if not k.startswith("_")}
-    return obj
-
-
-def classify_status(raw_status: str) -> str:
-    """Map a raw pipeline status string to a coarse state."""
-    status = (raw_status or "").lower()
-    if status in SUCCESS_STATUSES:
-        return "success"
-    if status in FAILURE_STATUSES:
-        return "failed"
-    if status in PROCESSING_STATUSES:
-        return "processing"
-    return "unknown"
-
-
-def find_status_entry(statuses: Any, buckets_file_id: str) -> Any:
-    for status in extract_status_entries(statuses):
-        if extract_status_file_id(status) == str(buckets_file_id):
-            return status
-    return {}
-
-
-def extract_status_entries(statuses: Any) -> List[Any]:
-    """Normalize SDK attachment status responses to a list of status entries."""
-    if statuses is None:
-        return []
-    if isinstance(statuses, list):
-        return statuses
-    if isinstance(statuses, tuple):
-        return list(statuses)
-    if isinstance(statuses, dict):
-        for key in ("items", "data", "results", "statuses", "attachments", "files"):
-            value = statuses.get(key)
-            if isinstance(value, list):
-                return value
-        if get_value(statuses, "status") is not None or extract_status_file_id(statuses):
-            return [statuses]
-        return []
-    for key in ("items", "data", "results", "statuses", "attachments", "files"):
-        value = getattr(statuses, key, None)
-        if isinstance(value, (list, tuple)):
-            return list(value)
-    if get_value(statuses, "status") is not None or extract_status_file_id(statuses):
-        return [statuses]
-    return []
-
-
-def extract_status_file_id(status: Any) -> Optional[str]:
-    for key in ("buckets_file_id", "bucketsFileId", "file_id", "fileId"):
-        value = get_value(status, key)
-        if value:
-            return str(value)
-    return None
-
-
-def latest_status_entry(statuses: Any) -> Any:
-    entries = extract_status_entries(statuses)
-    return entries[-1] if entries else {}
-
-
-def extract_buckets_file_id(item: Any, field_id: str) -> Optional[str]:
-    field_values = get_value(item, "field_values", []) or []
-    if isinstance(field_values, dict):
-        return extract_buckets_file_id_from_attachments(field_values.get(field_id))
-
-    for field_value in field_values:
-        if str(get_value(field_value, "field_id")) != str(field_id):
-            continue
-        buckets_file_id = extract_buckets_file_id_from_attachments(get_value(field_value, "value", []))
-        if buckets_file_id:
-            return buckets_file_id
-    return None
-
-
-def extract_buckets_file_id_from_attachments(value: Any) -> Optional[str]:
-    attachments = value or []
-    if isinstance(attachments, dict):
-        for key in ("attachments", "files", "items", "data", "results", "value"):
-            nested = attachments.get(key)
-            if isinstance(nested, list):
-                attachments = nested
-                break
-        else:
-            attachments = [attachments]
-    if not isinstance(attachments, list):
-        return None
-    for attachment in reversed(attachments):
-        buckets_file_id = get_value(attachment, "buckets_file_id")
-        if buckets_file_id:
-            return str(buckets_file_id)
-    return None
-
-
-def item_to_transaction(item: Any, workflow_id: str) -> Transaction:
-    payload = serialize_object(item)
-    payload = payload if isinstance(payload, dict) else {"value": payload}
-    return Transaction(
-        id=str(payload.get("id", "")),
-        payload=payload,
-        metadata={
-            "workflow_id": workflow_id,
-            "phase_id": payload.get("phase_id"),
-            "company_id": payload.get("company_id"),
-            "title": payload.get("title"),
-        },
-    )
-
-
-def normalize_create_payload(payload: CreateItemPayload) -> Dict[str, Any]:
-    """Flatten a CreateItemInput/dict into kwargs accepted by the service create_item."""
-    if isinstance(payload, CreateItemInput):
-        data: Dict[str, Any] = {
-            "title": payload.title,
-            "workflow_id": payload.workflow_id,
-            "phase_id": payload.phase_id,
-            "parent_item_id": payload.parent_item_id,
-            "field_values": payload.field_values,
-            "attachment": payload.attachment,
-            "attachment_field_id": payload.attachment_field_id,
-            "content_type": payload.content_type,
-            "fields": dict(payload.extra_fields),
-        }
-        return data
-    if isinstance(payload, dict):
-        data = dict(payload)
-        data.setdefault("fields", {})
-        return data
-    raise TypeError(f"Unsupported create payload type: {type(payload)}")
-
-
-def requeue(transaction: Transaction) -> CreateItemInput:
-    """Build a CreateItemInput from a transaction payload for re-dispatch."""
-    data = normalize_create_payload(transaction.payload)
-    workflow_id = data.get("workflow_id") or transaction.metadata.get("workflow_id")
-    phase_id = data.get("phase_id") or transaction.metadata.get("phase_id")
-    title = data.get("title")
-    if not isinstance(title, str) or not title.strip():
-        raise ValueError("title is required to requeue a transaction")
-
-    return CreateItemInput(
-        title=title,
-        workflow_id=workflow_id,
-        phase_id=phase_id,
-        parent_item_id=data.get("parent_item_id"),
-        field_values=data.get("field_values"),
-        attachment=data.get("attachment"),
-        attachment_field_id=data.get("attachment_field_id"),
-        content_type=data.get("content_type"),
-        extra_fields=dict(data.get("fields") or {}),
-    )
-
-
-def build_redispatch_transaction(transaction: Transaction) -> Transaction:
-    """Prepare a transaction payload suitable for re-dispatch."""
-    return Transaction(
-        id=transaction.id,
-        payload=requeue(transaction),
-        metadata=dict(transaction.metadata or {}),
-    )
-
-
-def decode_jwt_claims(jwt_token: str) -> Dict[str, Any]:
-    """Decode JWT payload claims without signature validation.
-
-    Raises:
-        ValueError: When the token shape or payload encoding is invalid.
-    """
-    parts = jwt_token.split(".")
-    if len(parts) < 2 or not parts[1]:
-        raise ValueError("Invalid JWT format: payload segment is missing")
-
-    payload = parts[1]
-    payload += "=" * (-len(payload) % 4)
-    try:
-        decoded = base64.urlsafe_b64decode(payload.encode("ascii"))
-        claims = json.loads(decoded.decode("utf-8"))
-    except Exception as exc:  # noqa: BLE001
-        raise ValueError("Invalid JWT payload encoding") from exc
-
-    if not isinstance(claims, dict):
-        raise ValueError("Invalid JWT payload: expected a JSON object")
-    return claims
-
-
-def extract_items(response: Any) -> List[Any]:
-    """Pull the item list out of a Page, dict, or raw list response."""
-    if isinstance(response, list):
-        return response
-    if isinstance(response, dict):
-        for key in ("items", "data", "results"):
-            value = response.get(key)
-            if isinstance(value, list):
-                return value
-        return []
-    items = getattr(response, "items", None)
-    if isinstance(items, (list, tuple)):
-        return list(items)
-    return []
-
-
-def extract_total(response: Any) -> int:
-    """Read total count from a paginated Page, dict, or SDK response."""
-    for key in ("total", "total_count", "count"):
-        value = get_value(response, key)
-        if value is not None:
-            return int(value)
-    return 0
+__all__ = [
+    "as_payload",
+    "build_redispatch_transaction",
+    "classify_status",
+    "decode_jwt_claims",
+    "extract_buckets_file_id",
+    "extract_buckets_file_id_from_attachments",
+    "extract_items",
+    "extract_status_entries",
+    "extract_status_file_id",
+    "extract_total",
+    "find_status_entry",
+    "get_value",
+    "item_to_transaction",
+    "latest_status_entry",
+    "normalize_create_payload",
+    "requeue",
+    "serialize_object",
+]

ergon/connector/ergon_platform/workflows/__init__.py

@@ -0,0 +1,52 @@
+from typing import TYPE_CHECKING, Any
+
+from ..._lazy import exported_names, load_optional_export
+from .models import (
+    FAILURE_STATUSES,
+    PROCESSING_STATUSES,
+    SUCCESS_STATUSES,
+    CreateItemInput,
+    CreateItemPayload,
+    ErgonPlatformConsumerConfig,
+    ErgonPlatformProducerConfig,
+)
+
+if TYPE_CHECKING:
+    from ._operations import ErgonPlatformWorkflowsService
+    from .async_connector import AsyncErgonPlatformConnector
+    from .connector import ErgonPlatformConnector
+
+_LAZY_EXPORTS = {
+    "AsyncErgonPlatformConnector": "async_connector",
+    "ErgonPlatformConnector": "connector",
+    "ErgonPlatformWorkflowsService": "_operations",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return load_optional_export(
+        name=name,
+        package=__name__,
+        exports=_LAZY_EXPORTS,
+        namespace=globals(),
+        extra="ergon-platform",
+        dependencies=("ergon_platform", "httpx"),
+    )
+
+
+def __dir__() -> list[str]:
+    return exported_names(globals(), _LAZY_EXPORTS)
+
+
+__all__ = [
+    "AsyncErgonPlatformConnector",
+    "CreateItemInput",
+    "CreateItemPayload",
+    "ErgonPlatformConnector",
+    "ErgonPlatformConsumerConfig",
+    "ErgonPlatformProducerConfig",
+    "ErgonPlatformWorkflowsService",
+    "FAILURE_STATUSES",
+    "PROCESSING_STATUSES",
+    "SUCCESS_STATUSES",
+]

ergon/connector/ergon_platform/{_operations.py → workflows/_operations.py}

@@ -5,8 +5,8 @@ from typing import Any, Dict, List, Optional
 
 import httpx
 
-from ..transaction import Transaction
-from .models import ErgonPlatformClient
+from ...transaction import Transaction
+from ..models import ErgonPlatformClient
 from .utils import (
     as_payload,
     classify_status,
@@ -22,7 +22,9 @@ from .utils import (
 )
 
 
-class _ErgonPlatformOperations:
+class ErgonPlatformWorkflowsService:
+    """Workflows HTTP, pagination, claim, and attachment service."""
+
     def __init__(self, config: ErgonPlatformClient, client: Any) -> None:
         self.config = config
         self.client = client
@@ -262,3 +264,6 @@ class _ErgonPlatformOperations:
                 seen_ids.add(field_id)
             merged.append(field)
         return merged
+
+
+_ErgonPlatformOperations = ErgonPlatformWorkflowsService