python-zendesk-sdk 0.1.0__py3-none-any.whl

zendesk_sdk/config.py

@@ -0,0 +1,111 @@
+"""Configuration management for Zendesk SDK."""
+
+import os
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, computed_field, field_validator
+
+
+class ZendeskConfig(BaseModel):
+    """Configuration for Zendesk API client.
+
+    This class handles authentication and connection settings for the Zendesk API.
+    It supports both email/password and email/token authentication methods.
+    Environment variables can be used for configuration.
+    """
+
+    subdomain: str = Field(
+        ...,
+        description="Zendesk subdomain (e.g., 'mycompany' for mycompany.zendesk.com)",
+        min_length=1,
+    )
+    email: str = Field(
+        ...,
+        description="User email for authentication",
+        min_length=1,
+    )
+    password: Optional[str] = Field(
+        default=None,
+        description="User password (for email/password auth)",
+    )
+    token: Optional[str] = Field(
+        default=None,
+        description="API token (for email/token auth)",
+    )
+    timeout: float = Field(
+        default=30.0,
+        description="HTTP request timeout in seconds",
+        gt=0,
+    )
+    max_retries: int = Field(
+        default=3,
+        description="Maximum number of retry attempts",
+        ge=0,
+    )
+
+    def __init__(self, **data: Any) -> None:
+        # Load from environment variables if not provided
+        if "subdomain" not in data:
+            data["subdomain"] = os.getenv("ZENDESK_SUBDOMAIN", data.get("subdomain"))
+        if "email" not in data:
+            data["email"] = os.getenv("ZENDESK_EMAIL", data.get("email"))
+        if "password" not in data:
+            data["password"] = os.getenv("ZENDESK_PASSWORD", data.get("password"))
+        if "token" not in data:
+            data["token"] = os.getenv("ZENDESK_TOKEN", data.get("token"))
+
+        super().__init__(**data)
+
+    @field_validator("email")
+    @classmethod
+    def validate_email(cls, v: str) -> str:
+        """Basic email validation."""
+        if "@" not in v:
+            raise ValueError("Invalid email format")
+        return v
+
+    @field_validator("subdomain")
+    @classmethod
+    def validate_subdomain(cls, v: str) -> str:
+        """Validate subdomain format."""
+        if not v.replace("-", "").replace("_", "").isalnum():
+            raise ValueError("Subdomain can only contain letters, numbers, hyphens and underscores")
+        return v.lower()
+
+    def model_post_init(self, __context: Any) -> None:
+        """Validate that either password or token is provided."""
+        if not self.password and not self.token:
+            raise ValueError("Either password or token must be provided")
+        if self.password and self.token:
+            raise ValueError("Cannot provide both password and token")
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def endpoint(self) -> str:
+        """Generate the base API endpoint URL."""
+        return f"https://{self.subdomain}.zendesk.com/api/v2"
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def auth_tuple(self) -> tuple[str, str]:
+        """Generate authentication tuple for HTTP requests."""
+        if self.token:
+            return (f"{self.email}/token", self.token)
+        return (self.email, self.password or "")
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def auth_type(self) -> str:
+        """Return the authentication type being used."""
+        return "token" if self.token else "password"
+
+    def __repr__(self) -> str:
+        """String representation without exposing credentials."""
+        return (
+            f"ZendeskConfig("
+            f"subdomain='{self.subdomain}', "
+            f"email='{self.email}', "
+            f"auth_type='{self.auth_type}', "
+            f"timeout={self.timeout}, "
+            f"max_retries={self.max_retries})"
+        )

zendesk_sdk/exceptions.py

@@ -0,0 +1,178 @@
+"""Exception classes for Zendesk SDK."""
+
+from typing import Any, Optional
+
+import httpx
+
+
+class ZendeskBaseException(Exception):
+    """Base exception for all Zendesk SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class ZendeskHTTPException(ZendeskBaseException):
+    """Exception raised for HTTP-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        response: Optional[httpx.Response] = None,
+        request: Optional[httpx.Request] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+        self.request = request
+
+    def __str__(self) -> str:
+        return f"HTTP {self.status_code}: {self.message}"
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> "ZendeskHTTPException":
+        """Create exception from HTTP response."""
+        try:
+            # Try to extract error message from JSON response
+            json_data = response.json()
+            if isinstance(json_data, dict):
+                if "error" in json_data:
+                    message = json_data["error"]
+                elif "description" in json_data:
+                    message = json_data["description"]
+                elif "message" in json_data:
+                    message = json_data["message"]
+                else:
+                    message = f"HTTP {response.status_code} error"
+            else:
+                message = f"HTTP {response.status_code} error"
+        except Exception:
+            # If JSON parsing fails, use status text or generic message
+            message = response.reason_phrase or f"HTTP {response.status_code} error"
+
+        return cls(
+            message=message,
+            status_code=response.status_code,
+            response=response,
+            request=response.request,
+        )
+
+
+class ZendeskAuthException(ZendeskHTTPException):
+    """Exception raised for authentication-related errors (401, 403)."""
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        status_code: int = 401,
+        response: Optional[httpx.Response] = None,
+        request: Optional[httpx.Request] = None,
+    ) -> None:
+        super().__init__(message, status_code, response, request)
+
+
+class ZendeskRateLimitException(ZendeskHTTPException):
+    """Exception raised when rate limits are exceeded (429)."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        status_code: int = 429,
+        response: Optional[httpx.Response] = None,
+        request: Optional[httpx.Request] = None,
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(message, status_code, response, request)
+        self.retry_after = retry_after
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> "ZendeskRateLimitException":
+        """Create rate limit exception from HTTP response."""
+        # Extract retry-after header if present
+        retry_after = None
+        retry_after_header = response.headers.get("retry-after")
+        if retry_after_header:
+            try:
+                retry_after = int(retry_after_header)
+            except ValueError:
+                pass
+
+        try:
+            json_data = response.json()
+            message = json_data.get("description") or json_data.get("error") or "Rate limit exceeded"
+        except Exception:
+            message = "Rate limit exceeded"
+
+        return cls(
+            message=message,
+            status_code=response.status_code,
+            response=response,
+            request=response.request,
+            retry_after=retry_after,
+        )
+
+    def __str__(self) -> str:
+        base_str = super().__str__()
+        if self.retry_after:
+            return f"{base_str} (retry after {self.retry_after}s)"
+        return base_str
+
+
+class ZendeskPaginationException(ZendeskBaseException):
+    """Exception raised for pagination-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        page_info: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.page_info = page_info or {}
+
+
+class ZendeskValidationException(ZendeskBaseException):
+    """Exception raised for data validation errors."""
+
+    def __init__(
+        self,
+        message: str,
+        field: Optional[str] = None,
+        value: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.field = field
+        self.value = value
+
+    def __str__(self) -> str:
+        if self.field:
+            return f"Validation error for field '{self.field}': {self.message}"
+        return f"Validation error: {self.message}"
+
+
+class ZendeskTimeoutException(ZendeskBaseException):
+    """Exception raised when requests timeout."""
+
+    def __init__(
+        self,
+        message: str = "Request timed out",
+        timeout: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.timeout = timeout
+
+    def __str__(self) -> str:
+        if self.timeout:
+            return f"Request timed out after {self.timeout}s"
+        return self.message
+
+
+def create_exception_from_response(response: httpx.Response) -> ZendeskHTTPException:
+    """Create appropriate exception based on response status code."""
+    if response.status_code in (401, 403):
+        return ZendeskAuthException.from_response(response)
+    elif response.status_code == 429:
+        return ZendeskRateLimitException.from_response(response)
+    else:
+        return ZendeskHTTPException.from_response(response)

zendesk_sdk/http_client.py

@@ -0,0 +1,256 @@
+"""HTTP client for Zendesk API with retry, rate limiting, and error handling."""
+
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+from urllib.parse import urljoin
+
+import httpx
+
+from .config import ZendeskConfig
+from .exceptions import (
+    ZendeskHTTPException,
+    ZendeskRateLimitException,
+    ZendeskTimeoutException,
+    create_exception_from_response,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class HTTPClient:
+    """Async HTTP client for Zendesk API with advanced error handling and retry logic."""
+
+    def __init__(self, config: ZendeskConfig) -> None:
+        """Initialize HTTP client with configuration.
+
+        Args:
+            config: Zendesk configuration containing auth and connection settings
+        """
+        self.config = config
+        self._client: Optional[httpx.AsyncClient] = None
+        self._closed = False
+
+    @property
+    def client(self) -> httpx.AsyncClient:
+        """Get or create httpx async client."""
+        if self._client is None:
+            self._client = self._create_client()
+        return self._client
+
+    def _create_client(self) -> httpx.AsyncClient:
+        """Create configured httpx async client."""
+        auth = httpx.BasicAuth(username=self.config.auth_tuple[0], password=self.config.auth_tuple[1])
+
+        headers = {
+            "User-Agent": "python-zendesk-sdk/0.1.0",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+        return httpx.AsyncClient(
+            auth=auth,
+            headers=headers,
+            timeout=httpx.Timeout(self.config.timeout),
+            limits=httpx.Limits(max_keepalive_connections=10, max_connections=20),
+        )
+
+    async def _make_request_with_retry(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        max_retries: Optional[int] = None,
+    ) -> httpx.Response:
+        """Make HTTP request with retry logic and rate limiting handling."""
+        if max_retries is None:
+            max_retries = self.config.max_retries
+
+        last_exception: Optional[Exception] = None
+
+        for attempt in range(max_retries + 1):
+            try:
+                # Make the actual request
+                response = await self.client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json,
+                )
+
+                # Handle different response types
+                retry_info = await self._handle_response(response, attempt, max_retries)
+                if retry_info:
+                    last_exception = retry_info
+                    continue
+                return response
+
+            except httpx.TimeoutException:
+                last_exception = await self._handle_timeout_exception(attempt, max_retries)
+                if last_exception:
+                    continue
+
+            except (httpx.NetworkError, httpx.ConnectError) as e:
+                last_exception = await self._handle_network_exception(e, attempt, max_retries)
+                if last_exception:
+                    continue
+
+        # This shouldn't happen, but just in case
+        if last_exception:
+            raise last_exception
+        raise ZendeskHTTPException("Unexpected error: no response after retries", 0)
+
+    async def _handle_response(self, response: httpx.Response, attempt: int, max_retries: int) -> Optional[Exception]:
+        """Handle HTTP response based on status code. Return exception if should retry, None if success."""
+        # Handle rate limiting (429)
+        if response.status_code == 429:
+            return await self._handle_rate_limit(response, attempt, max_retries)
+
+        # Handle server errors (5xx) - retry these
+        if 500 <= response.status_code < 600:
+            return await self._handle_server_error(response, attempt, max_retries)
+
+        # Handle other HTTP errors (4xx, etc.) - don't retry these
+        if not response.is_success:
+            raise create_exception_from_response(response)
+
+        # Success!
+        return None
+
+    async def _handle_rate_limit(self, response: httpx.Response, attempt: int, max_retries: int) -> Optional[Exception]:
+        """Handle rate limiting response. Return exception if should retry, otherwise raise."""
+        rate_limit_exc = ZendeskRateLimitException.from_response(response)
+
+        if attempt < max_retries:
+            # Wait based on retry-after header or default backoff
+            wait_time = rate_limit_exc.retry_after or self._calculate_backoff(attempt)
+            logger.warning(f"Rate limited, waiting {wait_time}s before retry {attempt + 1}/{max_retries}")
+            await asyncio.sleep(wait_time)
+            return rate_limit_exc
+        else:
+            raise rate_limit_exc
+
+    async def _handle_server_error(
+        self, response: httpx.Response, attempt: int, max_retries: int
+    ) -> Optional[Exception]:
+        """Handle server error response. Return exception if should retry, otherwise raise."""
+        server_error = create_exception_from_response(response)
+
+        if attempt < max_retries:
+            wait_time = self._calculate_backoff(attempt)
+            logger.warning(
+                f"Server error {response.status_code}, retrying in {wait_time}s (attempt {attempt + 1}/{max_retries})"
+            )
+            await asyncio.sleep(wait_time)
+            return server_error
+        else:
+            raise server_error
+
+    async def _handle_timeout_exception(self, attempt: int, max_retries: int) -> Optional[ZendeskTimeoutException]:
+        """Handle timeout exception. Return exception if should retry, otherwise raise."""
+        timeout_exc = ZendeskTimeoutException(f"Request timed out after {self.config.timeout}s", self.config.timeout)
+
+        if attempt < max_retries:
+            wait_time = self._calculate_backoff(attempt)
+            logger.warning(f"Request timeout, retrying in {wait_time}s (attempt {attempt + 1}/{max_retries})")
+            await asyncio.sleep(wait_time)
+            return timeout_exc
+        else:
+            raise timeout_exc
+
+    async def _handle_network_exception(
+        self, exc: Exception, attempt: int, max_retries: int
+    ) -> Optional[ZendeskHTTPException]:
+        """Handle network exception. Return exception if should retry, otherwise raise."""
+        network_exc = ZendeskHTTPException(f"Network error: {str(exc)}", 0)
+
+        if attempt < max_retries:
+            wait_time = self._calculate_backoff(attempt)
+            logger.warning(f"Network error, retrying in {wait_time}s (attempt {attempt + 1}/{max_retries}): {exc}")
+            await asyncio.sleep(wait_time)
+            return network_exc
+        else:
+            raise network_exc
+
+    def _calculate_backoff(self, attempt: int) -> float:
+        """Calculate exponential backoff delay."""
+        return min(2**attempt, 60.0)  # Max 60 seconds
+
+    def _build_url(self, path: str) -> str:
+        """Build full URL from path."""
+        if path.startswith("http"):
+            return path
+        return urljoin(f"{self.config.endpoint}/", path.lstrip("/"))
+
+    async def get(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        max_retries: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Make GET request and return JSON response."""
+        url = self._build_url(path)
+        response = await self._make_request_with_retry("GET", url, params=params, max_retries=max_retries)
+        return response.json()
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        max_retries: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Make POST request and return JSON response."""
+        url = self._build_url(path)
+        response = await self._make_request_with_retry("POST", url, json=json, max_retries=max_retries)
+        return response.json()
+
+    async def put(
+        self,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        max_retries: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Make PUT request and return JSON response."""
+        url = self._build_url(path)
+        response = await self._make_request_with_retry("PUT", url, json=json, max_retries=max_retries)
+        return response.json()
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        max_retries: Optional[int] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Make DELETE request and return JSON response if any."""
+        url = self._build_url(path)
+        response = await self._make_request_with_retry("DELETE", url, max_retries=max_retries)
+
+        # Some DELETE requests return empty responses
+        if response.content:
+            return response.json()
+        return None
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client and not self._closed:
+            await self._client.aclose()
+            self._closed = True
+
+    async def __aenter__(self) -> "HTTPClient":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
+        """Async context manager exit."""
+        await self.close()
+
+    def __del__(self) -> None:
+        """Destructor to ensure client is closed."""
+        if self._client and not self._closed:
+            # Can't call async method in __del__, so we log a warning
+            logger.warning("HTTPClient was not properly closed. Use 'async with' or call close() explicitly.")

zendesk_sdk/models/__init__.py

@@ -0,0 +1,40 @@
+"""Zendesk API data models."""
+
+from .base import ZendeskModel
+from .comment import Comment, CommentAttachment, CommentMetadata, CommentVia
+from .organization import Organization, OrganizationField, OrganizationSubscription
+from .ticket import (
+    SatisfactionRating,
+    Ticket,
+    TicketCustomField,
+    TicketField,
+    TicketMetrics,
+    TicketVia,
+)
+from .user import User, UserField, UserIdentity, UserPhoto
+
+__all__ = [
+    # Base
+    "ZendeskModel",
+    # User models
+    "User",
+    "UserField",
+    "UserIdentity",
+    "UserPhoto",
+    # Organization models
+    "Organization",
+    "OrganizationField",
+    "OrganizationSubscription",
+    # Ticket models
+    "Ticket",
+    "TicketField",
+    "TicketMetrics",
+    "TicketCustomField",
+    "TicketVia",
+    "SatisfactionRating",
+    # Comment models
+    "Comment",
+    "CommentAttachment",
+    "CommentMetadata",
+    "CommentVia",
+]

zendesk_sdk/models/base.py

@@ -0,0 +1,50 @@
+"""Base model for all Zendesk API data models."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, field_serializer
+
+
+class ZendeskModel(BaseModel):
+    """Base model for all Zendesk API responses."""
+
+    model_config = ConfigDict(
+        # Allow field aliases (id -> uid, etc.)
+        populate_by_name=True,
+        # Use enum values instead of enum names
+        use_enum_values=True,
+        # Validate assignment to fields
+        validate_assignment=True,
+        # Allow extra fields that aren't defined in the model
+        extra="ignore",
+        # Convert string dates to datetime objects
+        str_to_lower=False,
+        # Allow arbitrary types (for complex nested structures)
+        arbitrary_types_allowed=True,
+    )
+
+    @field_serializer("*", when_used="json")
+    def serialize_datetime(self, value: Any) -> Any:
+        """Serialize datetime objects to ISO format strings."""
+        if isinstance(value, datetime):
+            return value.isoformat()
+        return value
+
+    def __str__(self) -> str:
+        """String representation showing class name and key fields."""
+        class_name = self.__class__.__name__
+        # Try to find an ID field to display
+        id_field = None
+        for field in ["uid", "id", "name", "subject"]:
+            if hasattr(self, field):
+                id_field = f"{field}={getattr(self, field)!r}"
+                break
+
+        if id_field:
+            return f"{class_name}({id_field})"
+        return f"{class_name}()"
+
+    def __repr__(self) -> str:
+        """Detailed string representation."""
+        return f"{self.__class__.__name__}({self.model_dump()})"