poelis-sdk 0.5.4__py3-none-any.whl

poelis_sdk/client.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field, HttpUrl
+
+from ._transport import Transport
+from .browser import Browser
+from .change_tracker import PropertyChangeTracker
+from .items import ItemsClient
+from .logging import quiet_logging
+from .products import ProductsClient
+from .search import SearchClient
+from .workspaces import WorkspacesClient
+from .versions import VersionsClient
+
+"""Core client for the Poelis Python SDK.
+
+This module exposes the `PoelisClient` which configures base URL, authentication,
+tenant scoping, and provides accessors for resource clients. The initial
+implementation is sync-first and keeps the transport layer swappable for
+future async parity.
+"""
+
+
+class ClientConfig(BaseModel):
+    """Configuration for `PoelisClient`.
+    
+    Attributes:
+        base_url: Base URL of the Poelis API.
+        api_key: API key used for authentication.
+        timeout_seconds: Request timeout in seconds.
+    """
+
+    base_url: HttpUrl = Field(default="https://poelis-be-py-753618215333.europe-west1.run.app")
+    api_key: str = Field(min_length=1)
+    timeout_seconds: float = 30.0
+
+
+class PoelisClient:
+    """Synchronous Poelis SDK client.
+
+    Provides access to resource-specific clients (e.g., `products`, `items`).
+    This prototype only validates configuration and exposes placeholders for
+    resource accessors to unblock incremental development.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://poelis-be-py-753618215333.europe-west1.run.app",
+        timeout_seconds: float = 30.0,
+        org_id: Optional[str] = None,
+        enable_change_detection: bool = True,
+        baseline_file: Optional[str] = None,
+        log_file: Optional[str] = None,
+    ) -> None:
+        """Initialize the client with API endpoint and credentials.
+
+        Args:
+            api_key: API key for API authentication.
+            base_url: Base URL of the Poelis API. Defaults to production.
+            timeout_seconds: Network timeout in seconds.
+            org_id: Deprecated, ignored parameter kept for backwards compatibility.
+            enable_change_detection: If True, enables automatic warnings when property
+                values change between accesses. When True, defaults to using
+                `.poelis/baseline.json` for baseline_file and `poelis_changes.log` for
+                log_file if not explicitly provided. Defaults to False.
+            baseline_file: Optional path to JSON file for persistent baseline storage.
+                If provided, property baselines will be saved and loaded between script runs.
+                If enable_change_detection is True and this is None, defaults to
+                `.poelis/baseline.json`. Defaults to None (in-memory only).
+            log_file: Optional path to log file for recording property changes.
+                Changes will be appended to this file. If enable_change_detection is True
+                and this is None, defaults to `poelis_changes.log`. Defaults to None
+                (no file logging).
+        """
+
+        # Configure quiet logging by default for production use
+        quiet_logging()
+
+        self._config = ClientConfig(
+            base_url=base_url,
+            api_key=api_key,
+            timeout_seconds=timeout_seconds,
+        )
+
+        # Shared transport
+        self._transport = Transport(
+            base_url=str(self._config.base_url),
+            api_key=self._config.api_key,
+            timeout_seconds=self._config.timeout_seconds,
+        )
+
+        # Auto-configure baseline_file and log_file if change detection is enabled
+        if enable_change_detection:
+            if baseline_file is None:
+                baseline_file = ".poelis/baseline.json"
+            if log_file is None:
+                log_file = "poelis_changes.log"
+
+        # Property change tracking
+        self._change_tracker = PropertyChangeTracker(
+            enabled=enable_change_detection,
+            baseline_file=baseline_file,
+            log_file=log_file,
+        )
+
+        # Resource clients
+        self.workspaces = WorkspacesClient(self._transport)
+        self.products = ProductsClient(self._transport, self.workspaces)
+        self.items = ItemsClient(self._transport)
+        self.versions = VersionsClient(self._transport)
+        self.search = SearchClient(self._transport)
+        self.browser = Browser(self)
+
+    @classmethod
+    def from_env(cls) -> "PoelisClient":
+        """Construct a client using environment variables.
+
+        Expected variables:
+        - POELIS_BASE_URL (optional, defaults to managed GCP endpoint)
+        - POELIS_API_KEY
+        """
+
+        base_url = os.environ.get("POELIS_BASE_URL", "https://poelis-be-py-753618215333.europe-west1.run.app")
+        api_key = os.environ.get("POELIS_API_KEY")
+
+        if not api_key:
+            raise ValueError("POELIS_API_KEY must be set")
+
+        return cls(api_key=api_key, base_url=base_url)
+
+    @property
+    def base_url(self) -> str:
+        """Return the configured base URL as a string."""
+
+        return str(self._config.base_url)
+
+    @property
+    def org_id(self) -> Optional[str]:
+        """Return the configured organization id if any.
+        
+        Note:
+            This property is deprecated and always returns ``None``. The backend
+            now derives organization and workspace access from the API key
+            itself, so explicit org selection on the client is no longer used.
+        """
+
+        return None
+
+    @property
+    def enable_change_detection(self) -> bool:
+        """Get whether property change detection is enabled.
+
+        Returns:
+            bool: True if change detection is enabled, False otherwise.
+        """
+        return self._change_tracker.is_enabled()
+
+    @enable_change_detection.setter
+    def enable_change_detection(self, value: bool) -> None:
+        """Enable or disable property change detection.
+
+        Args:
+            value: True to enable, False to disable.
+        """
+        if value:
+            self._change_tracker.enable()
+        else:
+            self._change_tracker.disable()
+
+    def clear_property_baselines(self) -> None:
+        """Clear all recorded property baseline values.
+
+        This resets the change tracking state, so all properties will be
+        treated as new on their next access.
+        """
+        self._change_tracker.clear_baselines()
+
+    def get_changed_properties(self) -> Dict[str, Dict[str, Any]]:
+        """Get information about properties that have changed.
+
+        Returns:
+            Dict[str, Dict[str, Any]]: Dictionary mapping property_id to change info.
+                Currently returns empty dict as change tracking is per-access.
+        """
+        return self._change_tracker.get_changed_properties()
+
+    def write_change_log(self) -> None:
+        """Write all changes detected in this session to the log file.
+        
+        This should be called at the end of a script run to ensure all changes
+        are logged, even if warnings were suppressed. If no log file is configured,
+        this method does nothing.
+        """
+        self._change_tracker.write_change_log()
+
+
+class _Deprecated:  # pragma: no cover
+    pass
+
+

poelis_sdk/exceptions.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Optional
+
+"""SDK exception hierarchy for Poelis."""
+
+
+class PoelisError(Exception):
+    """Base SDK exception."""
+
+
+class HTTPError(PoelisError):
+    """HTTP error from API response."""
+
+    def __init__(self, status_code: int, message: str | None = None) -> None:
+        super().__init__(message or f"HTTP error: {status_code}")
+        self.status_code = status_code
+        self.message = message or ""
+
+
+class UnauthorizedError(HTTPError):
+    """Raised on 401 Unauthorized."""
+
+
+class NotFoundError(HTTPError):
+    """Raised on 404 Not Found."""
+
+
+class RateLimitError(HTTPError):
+    """Raised on 429 Too Many Requests with optional retry-after seconds."""
+
+    def __init__(self, status_code: int, message: str | None = None, retry_after_seconds: Optional[float] = None) -> None:
+        super().__init__(status_code=status_code, message=message)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ClientError(HTTPError):
+    """Raised on other 4xx errors."""
+
+
+class ServerError(HTTPError):
+    """Raised on 5xx errors."""
+
+

poelis_sdk/items.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Generator, List, Optional
+
+from ._transport import Transport
+
+"""Items resource client."""
+
+
+class ItemsClient:
+    """Client for draft item resources.
+
+    This client is intended for accessing the current draft view of items,
+    i.e., items that are not bound to a specific product version. Versioned
+    (snapshot) items for a given product version should be accessed via the
+    `VersionsClient`.
+    """
+
+    def __init__(self, transport: Transport) -> None:
+        """Initialize the client with shared transport.
+
+        Args:
+            transport: Shared HTTP/GraphQL transport used by the SDK.
+        """
+
+        self._t = transport
+
+    def list_by_product(self, *, product_id: str, q: Optional[str] = None, limit: int = 100, offset: int = 0) -> List[Dict[str, Any]]:
+        """List draft items for a product via GraphQL with optional text filter.
+
+        This method is intended to return the current draft state of items for
+        the given product (items without a bound product version). To retrieve
+        historical/versioned items, use `VersionsClient.list_items`.
+
+        Args:
+            product_id: Identifier of the parent product.
+            q: Optional free-text filter applied to item name/description.
+            limit: Maximum number of items to return.
+            offset: Offset for pagination.
+
+        Returns:
+            List of draft item dictionaries belonging to the client's
+            configured organization.
+
+        Raises:
+            RuntimeError: If the GraphQL response contains errors.
+        """
+
+        query = (
+            "query($pid: ID!, $q: String, $limit: Int!, $offset: Int!) {\n"
+            "  items(productId: $pid, q: $q, limit: $limit, offset: $offset) { id name readableId productId parentId owner position }\n"
+            "}"
+        )
+        variables = {"pid": product_id, "q": q, "limit": int(limit), "offset": int(offset)}
+        resp = self._t.graphql(query=query, variables=variables)
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        
+        items = payload.get("data", {}).get("items", [])
+        
+        return items
+
+    def get(self, item_id: str) -> Dict[str, Any]:
+        """Get a single draft item by identifier via GraphQL.
+
+        Returns the item only if it belongs to the client's configured
+        organization. The returned representation reflects the current draft
+        state, not a specific historical product version.
+
+        Args:
+            item_id: Identifier of the item to retrieve.
+
+        Returns:
+            Dictionary representing the draft item.
+
+        Raises:
+            RuntimeError: If the GraphQL response contains errors or the item
+                cannot be found.
+        """
+
+        query = (
+            "query($id: ID!) {\n"
+            "  item(id: $id) { id name readableId productId parentId owner position }\n"
+            "}"
+        )
+        resp = self._t.graphql(query=query, variables={"id": item_id})
+        resp.raise_for_status()
+        payload = resp.json()
+        if "errors" in payload:
+            raise RuntimeError(str(payload["errors"]))
+        
+        item = payload.get("data", {}).get("item")
+        if item is None:
+            raise RuntimeError(f"Item with id '{item_id}' not found")
+        
+        return item
+
+    def iter_all_by_product(self, *, product_id: str, q: Optional[str] = None, page_size: int = 100) -> Generator[dict, None, None]:
+        """Iterate draft items via GraphQL for a given product.
+
+        Args:
+            product_id: Identifier of the parent product.
+            q: Optional free-text filter applied to item name/description.
+            page_size: Page size for each GraphQL request.
+
+        Yields:
+            Individual draft item dictionaries.
+        """
+
+        offset = 0
+        while True:
+            data = self.list_by_product(product_id=product_id, q=q, limit=page_size, offset=offset)
+            if not data:
+                break
+            for item in data:
+                yield item
+            offset += len(data)
+
+

poelis_sdk/logging.py

@@ -0,0 +1,73 @@
+"""Logging configuration for the Poelis SDK.
+
+This module provides utilities to configure logging levels for the SDK and its dependencies.
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+def configure_logging(
+    level: str = "WARNING",
+    disable_httpx_logs: bool = True,
+    disable_urllib3_logs: bool = True,
+    enable_sdk_logs: bool = False,
+) -> None:
+    """Configure logging for the Poelis SDK and its dependencies.
+    
+    Args:
+        level: Logging level for the root logger (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        disable_httpx_logs: Whether to disable httpx HTTP request logs.
+        disable_urllib3_logs: Whether to disable urllib3 logs.
+        enable_sdk_logs: Whether to enable SDK-specific debug logs.
+    """
+    # Set root logger level
+    numeric_level = getattr(logging, level.upper(), logging.WARNING)
+    logging.basicConfig(level=numeric_level)
+    
+    # Configure httpx logging
+    if disable_httpx_logs:
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+    else:
+        logging.getLogger("httpx").setLevel(logging.INFO)
+    
+    # Configure urllib3 logging
+    if disable_urllib3_logs:
+        logging.getLogger("urllib3").setLevel(logging.WARNING)
+        logging.getLogger("urllib3.connectionpool").setLevel(logging.WARNING)
+    
+    # Configure SDK logging
+    sdk_logger = logging.getLogger("poelis_sdk")
+    if enable_sdk_logs:
+        sdk_logger.setLevel(logging.DEBUG)
+    else:
+        sdk_logger.setLevel(logging.WARNING)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger for the given name.
+    
+    Args:
+        name: Logger name, typically __name__.
+        
+    Returns:
+        Logger instance.
+    """
+    return logging.getLogger(f"poelis_sdk.{name}")
+
+
+# Convenience functions for common logging configurations
+def quiet_logging() -> None:
+    """Configure quiet logging - only show warnings and errors."""
+    configure_logging(level="WARNING", disable_httpx_logs=True, disable_urllib3_logs=True)
+
+
+def verbose_logging() -> None:
+    """Configure verbose logging - show all logs including HTTP requests."""
+    configure_logging(level="INFO", disable_httpx_logs=False, disable_urllib3_logs=False, enable_sdk_logs=True)
+
+
+def debug_logging() -> None:
+    """Configure debug logging - show everything including SDK debug logs."""
+    configure_logging(level="DEBUG", disable_httpx_logs=False, disable_urllib3_logs=False, enable_sdk_logs=True)

poelis_sdk/models.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional, Union
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+"""Pydantic models for SDK resources."""
+
+
+class Product(BaseModel):
+    """Product resource representation."""
+
+    id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    readableId: Optional[str] = None
+    workspaceId: Optional[str] = None
+    baseline_version_number: Optional[int] = Field(
+        alias="baselineVersionNumber",
+        default=None,
+    )
+    code: Optional[str] = None
+    description: Optional[str] = None
+
+
+class ProductVersion(BaseModel):
+    """Product version resource representation.
+
+    Represents a frozen snapshot of a product at a specific version number.
+
+    Attributes:
+        product_id: Identifier of the parent product.
+        version_number: Monotonic version number for the product.
+        title: Human-friendly title for this version.
+        description: Optional free-text description of the version.
+        created_by: Optional identifier of the user who created the version (not currently queried from GraphQL).
+        created_at: Timestamp when the version was created.
+        updated_at: Optional timestamp of the last update to the version (not in GraphQL schema yet).
+        org_id: Optional identifier of the owning organization (not in GraphQL schema yet).
+    """
+
+    product_id: str = Field(alias="productId", min_length=1)
+    version_number: int = Field(alias="versionNumber")
+    title: str = Field(min_length=1)
+    description: Optional[str] = None
+    created_by: Optional[str] = Field(alias="createdBy", default=None)
+    created_at: datetime = Field(alias="createdAt")
+    updated_at: Optional[datetime] = Field(alias="updatedAt", default=None)
+    org_id: Optional[str] = Field(alias="orgId", default=None)
+
+
+class PaginatedProducts(BaseModel):
+    """Paginated response for products list."""
+
+    data: list[Product]
+    limit: int
+    offset: int
+
+
+class PaginatedProductVersions(BaseModel):
+    """Paginated response for product versions list."""
+
+    data: list[ProductVersion]
+    limit: int
+    offset: int
+
+
+class PropertyValue(BaseModel):
+    """Base class for property values with typed access."""
+    
+    raw_value: str = Field(alias="value")
+    parsed_value: Optional[Any] = Field(alias="parsedValue", default=None)
+    
+    @property
+    def value(self) -> Any:
+        """Get the properly typed value, falling back to raw string if parsing failed."""
+        return self.parsed_value if self.parsed_value is not None else self.raw_value
+
+
+class NumericProperty(BaseModel):
+    """Numeric property representation.
+    
+    Note: The `category` field contains normalized/canonicalized values.
+    Categories are normalized server-side (upper-cased, deduplicated) and
+    may differ from the original input values.
+    """
+    
+    id: str = Field(min_length=1)
+    product_id: Optional[str] = Field(alias="productId", default=None)
+    product_version_number: Optional[int] = Field(alias="productVersionNumber", default=None)
+    item_id: str = Field(alias="itemId", min_length=1)
+    position: float
+    name: str = Field(min_length=1)
+    value: str
+    category: str
+    display_unit: Optional[str] = Field(alias="displayUnit", default=None)
+    owner: str = Field(min_length=1)
+    type: str = Field(min_length=1)
+    parsed_value: Optional[Union[int, float, List[Any], str]] = Field(alias="parsedValue", default=None)
+    
+    @property
+    def typed_value(self) -> Union[int, float, List[Any], str]:
+        """Get the properly typed value, falling back to raw string if parsing failed."""
+        return self.parsed_value if self.parsed_value is not None else self.value
+
+
+class TextProperty(BaseModel):
+    """Text property representation."""
+    
+    id: str = Field(min_length=1)
+    product_id: Optional[str] = Field(alias="productId", default=None)
+    product_version_number: Optional[int] = Field(alias="productVersionNumber", default=None)
+    item_id: str = Field(alias="itemId", min_length=1)
+    position: float
+    name: str = Field(min_length=1)
+    value: str
+    owner: str = Field(min_length=1)
+    type: str = Field(min_length=1)
+    parsed_value: Optional[Union[int, float, List[Any], str]] = Field(alias="parsedValue", default=None)
+    
+    @property
+    def typed_value(self) -> Union[int, float, List[Any], str]:
+        """Get the properly typed value, falling back to raw string if parsing failed."""
+        return self.parsed_value if self.parsed_value is not None else self.value
+
+
+class DateProperty(BaseModel):
+    """Date property representation."""
+    
+    id: str = Field(min_length=1)
+    product_id: Optional[str] = Field(alias="productId", default=None)
+    product_version_number: Optional[int] = Field(alias="productVersionNumber", default=None)
+    item_id: str = Field(alias="itemId", min_length=1)
+    position: float
+    name: str = Field(min_length=1)
+    value: str
+    owner: str = Field(min_length=1)
+    type: str = Field(min_length=1)
+    parsed_value: Optional[str] = Field(alias="parsedValue", default=None)
+    
+    @property
+    def typed_value(self) -> str:
+        """Get the properly typed value, falling back to raw string if parsing failed."""
+        return self.parsed_value if self.parsed_value is not None else self.value
+
+
+class PropertySearchResult(BaseModel):
+    """Property search result with unified fields across all property types."""
+    
+    id: str = Field(min_length=1)
+    workspace_id: str = Field(alias="workspaceId", min_length=1)
+    product_id: str = Field(alias="productId", min_length=1)
+    product_version_number: Optional[int] = Field(alias="productVersionNumber", default=None)
+    item_id: str = Field(alias="itemId", min_length=1)
+    property_type: str = Field(alias="propertyType", min_length=1)
+    name: str = Field(min_length=1)
+    category: Optional[str] = None
+    display_unit: Optional[str] = Field(alias="displayUnit", default=None)
+    value: Any  # Raw value from GraphQL
+    parsed_value: Optional[Union[int, float, List[Any], str]] = Field(alias="parsedValue", default=None)
+    owner: str = Field(min_length=1)
+    created_by: str = Field(alias="createdBy", min_length=1)
+    created_at: str = Field(alias="createdAt", min_length=1)
+    updated_at: str = Field(alias="updatedAt", min_length=1)
+    
+    @property
+    def typed_value(self) -> Union[int, float, List[Any], str]:
+        """Get the properly typed value, falling back to raw string if parsing failed."""
+        return self.parsed_value if self.parsed_value is not None else self.value
+
+
+class PropertySearchResponse(BaseModel):
+    """Response for property search queries."""
+    
+    query: str
+    hits: List[PropertySearchResult]
+    total: int
+    limit: int
+    offset: int
+    processing_time_ms: int = Field(alias="processingTimeMs")
+
+