python-zendesk-sdk 0.11.0__tar.gz → 0.13.0__tar.gz

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/.gitignore

@@ -190,4 +190,5 @@ debug_*.py
 
 # Local directories
 .claude/
-llm/
+llm/
+CLAUDE.md

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-zendesk-sdk
-Version: 0.11.0
+Version: 0.13.0
 Summary: Modern Python SDK for Zendesk API
 Project-URL: Homepage, https://github.com/bormog/python-zendesk-sdk
 Project-URL: Repository, https://github.com/bormog/python-zendesk-sdk
@@ -68,6 +68,7 @@ Modern Python SDK for Zendesk API, designed for automation and AI agents.
   - [Search](#search)
   - [Help Center](#help-center)
 - [Error Handling](#error-handling)
+- [Proactive Rate Limiting](#proactive-rate-limiting)
 - [Caching](#caching)
 - [Examples](#examples)
 
@@ -102,6 +103,8 @@ Zendesk has a powerful REST API, but using it directly is painful:
 - **Caching**: TTL-based caching for users, organizations, and Help Center
 - **Help Center**: Full CRUD for Categories, Sections, and Articles
 - **Async HTTP**: Built on httpx with retry logic, rate limiting, exponential backoff
+- **Proactive Rate Limiting**: Monitors `X-Rate-Limit-Remaining` and throttles before hitting limits
+- **Authentication**: Token auth (Basic Auth) and OAuth (Bearer token)
 - **Configuration**: Environment variables or direct instantiation
 
 ## Installation
@@ -141,20 +144,33 @@ asyncio.run(main())
 
 ## Configuration
 
-### Direct instantiation
+### Token Authentication
 ```python
 config = ZendeskConfig(
     subdomain="mycompany",
     email="user@example.com",
-    token="api_token_here"
+    token="api_token_here",
+)
+```
+
+### OAuth Authentication
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    oauth_token="your_oauth_token",
 )
 ```
 
 ### Environment variables
 ```bash
+# Token auth
 export ZENDESK_SUBDOMAIN=mycompany
 export ZENDESK_EMAIL=user@example.com
 export ZENDESK_TOKEN=api_token_here
+
+# Or OAuth
+export ZENDESK_SUBDOMAIN=mycompany
+export ZENDESK_OAUTH_TOKEN=your_oauth_token
 ```
 
 ```python
@@ -266,6 +282,17 @@ count = await client.groups.count()              # Get total number of groups
 paginator = client.groups.list()                 # List all groups (paginator)
 paginator = client.groups.list_assignable()      # List assignable groups (paginator)
 
+# Memberships — find which agents belong to a group
+paginator = client.groups.list_memberships()              # All memberships (paginator)
+paginator = client.groups.list_group_members(group_id)    # Members of specific group (paginator)
+membership = await client.groups.get_membership(membership_id)  # Get specific membership
+
+# Example: get all agents in a group
+members = await client.groups.list_group_members(group_id).collect()
+for m in members:
+    user = await client.users.get(m.user_id)
+    print(f"  {user.name} (default={m.default})")
+
 # Create
 group = await client.groups.create(
     name="Support Team",
@@ -645,6 +672,29 @@ config = ZendeskConfig(
 )
 ```
 
+### Proactive Rate Limiting
+
+By default, the SDK reacts to rate limiting after hitting a 429 response. With proactive rate limiting, the SDK reads the `X-Rate-Limit-Remaining` header from every response and starts throttling **before** hitting the limit:
+
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    email="user@example.com",
+    token="api_token",
+    proactive_ratelimit=50,                     # Start throttling when < 50 requests remaining
+    proactive_ratelimit_request_interval=10,    # Wait 10s between requests when throttling
+)
+```
+
+When `X-Rate-Limit-Remaining` drops below the threshold, the SDK pauses between requests to let the quota recover. Once remaining goes back above the threshold, requests resume at full speed.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `proactive_ratelimit` | None (disabled) | Threshold to start throttling |
+| `proactive_ratelimit_request_interval` | 10 | Seconds to wait between requests when throttling |
+
+Zendesk typically allows 400 requests per minute. A threshold of 40-60 provides a good safety margin.
+
 ## Caching
 
 The SDK includes built-in caching for frequently accessed resources. Caching is enabled by default and can be configured or disabled.

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/README.md

@@ -30,6 +30,7 @@ Modern Python SDK for Zendesk API, designed for automation and AI agents.
   - [Search](#search)
   - [Help Center](#help-center)
 - [Error Handling](#error-handling)
+- [Proactive Rate Limiting](#proactive-rate-limiting)
 - [Caching](#caching)
 - [Examples](#examples)
 
@@ -64,6 +65,8 @@ Zendesk has a powerful REST API, but using it directly is painful:
 - **Caching**: TTL-based caching for users, organizations, and Help Center
 - **Help Center**: Full CRUD for Categories, Sections, and Articles
 - **Async HTTP**: Built on httpx with retry logic, rate limiting, exponential backoff
+- **Proactive Rate Limiting**: Monitors `X-Rate-Limit-Remaining` and throttles before hitting limits
+- **Authentication**: Token auth (Basic Auth) and OAuth (Bearer token)
 - **Configuration**: Environment variables or direct instantiation
 
 ## Installation
@@ -103,20 +106,33 @@ asyncio.run(main())
 
 ## Configuration
 
-### Direct instantiation
+### Token Authentication
 ```python
 config = ZendeskConfig(
     subdomain="mycompany",
     email="user@example.com",
-    token="api_token_here"
+    token="api_token_here",
+)
+```
+
+### OAuth Authentication
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    oauth_token="your_oauth_token",
 )
 ```
 
 ### Environment variables
 ```bash
+# Token auth
 export ZENDESK_SUBDOMAIN=mycompany
 export ZENDESK_EMAIL=user@example.com
 export ZENDESK_TOKEN=api_token_here
+
+# Or OAuth
+export ZENDESK_SUBDOMAIN=mycompany
+export ZENDESK_OAUTH_TOKEN=your_oauth_token
 ```
 
 ```python
@@ -228,6 +244,17 @@ count = await client.groups.count()              # Get total number of groups
 paginator = client.groups.list()                 # List all groups (paginator)
 paginator = client.groups.list_assignable()      # List assignable groups (paginator)
 
+# Memberships — find which agents belong to a group
+paginator = client.groups.list_memberships()              # All memberships (paginator)
+paginator = client.groups.list_group_members(group_id)    # Members of specific group (paginator)
+membership = await client.groups.get_membership(membership_id)  # Get specific membership
+
+# Example: get all agents in a group
+members = await client.groups.list_group_members(group_id).collect()
+for m in members:
+    user = await client.users.get(m.user_id)
+    print(f"  {user.name} (default={m.default})")
+
 # Create
 group = await client.groups.create(
     name="Support Team",
@@ -607,6 +634,29 @@ config = ZendeskConfig(
 )
 ```
 
+### Proactive Rate Limiting
+
+By default, the SDK reacts to rate limiting after hitting a 429 response. With proactive rate limiting, the SDK reads the `X-Rate-Limit-Remaining` header from every response and starts throttling **before** hitting the limit:
+
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    email="user@example.com",
+    token="api_token",
+    proactive_ratelimit=50,                     # Start throttling when < 50 requests remaining
+    proactive_ratelimit_request_interval=10,    # Wait 10s between requests when throttling
+)
+```
+
+When `X-Rate-Limit-Remaining` drops below the threshold, the SDK pauses between requests to let the quota recover. Once remaining goes back above the threshold, requests resume at full speed.
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `proactive_ratelimit` | None (disabled) | Threshold to start throttling |
+| `proactive_ratelimit_request_interval` | 10 | Seconds to wait between requests when throttling |
+
+Zendesk typically allows 400 requests per minute. A threshold of 40-60 provides a good safety margin.
+
 ## Caching
 
 The SDK includes built-in caching for frequently accessed resources. Caching is enabled by default and can be configured or disabled.

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/examples/groups.py

@@ -6,6 +6,7 @@ This example demonstrates:
 - Updating groups
 - Deleting groups
 - Listing assignable groups
+- Group memberships (list members of a group)
 """
 
 import asyncio
@@ -97,6 +98,25 @@ async def main() -> None:
         await client.groups.delete(detailed_group.id)
         print(f"Deleted group: {detailed_group.id}")
 
+        # ==================== Membership Operations ====================
+
+        print("\n=== Membership Operations ===")
+
+        # List all memberships across all groups
+        print("All memberships:")
+        async for membership in client.groups.list_memberships(limit=10):
+            print(f"  User {membership.user_id} -> Group {membership.group_id} (default={membership.default})")
+
+        # List members of a specific group
+        print("\nMembers of first group:")
+        first_group = groups[0] if groups else None
+        if first_group:
+            members = await client.groups.list_group_members(first_group.id).collect()
+            for m in members:
+                user = await client.users.get(m.user_id)
+                default_str = " [DEFAULT]" if m.default else ""
+                print(f"  {user.name}{default_str}")
+
         # ==================== Caching Example ====================
 
         print("\n=== Caching Example ===")

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-zendesk-sdk"
-version = "0.11.0"
+version = "0.13.0"
 description = "Modern Python SDK for Zendesk API"
 authors = [
     {name = "bormog"}

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/src/zendesk_sdk/__init__.py

@@ -5,7 +5,7 @@ This package provides a clean, async-first interface to the Zendesk API
 with full type safety and comprehensive error handling.
 """
 
-__version__ = "0.11.0"
+__version__ = "0.13.0"
 
 from .client import ZendeskClient
 from .clients import (
@@ -38,6 +38,7 @@ from .models import (
     Category,
     EnrichedTicket,
     Group,
+    GroupMembership,
     PasswordRequirements,
     SearchQueryConfig,
     SearchType,
@@ -76,6 +77,7 @@ __all__ = [
     "ArticlesClient",
     # Models
     "Group",
+    "GroupMembership",
     "EnrichedTicket",
     "TicketField",
     "Category",

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/src/zendesk_sdk/clients/groups.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, Callable, Dict, Optional
 
-from ..models import Group
+from ..models import Group, GroupMembership
 from ..pagination import ZendeskPaginator
 from .base import BaseClient
 
@@ -300,3 +300,68 @@ class GroupsClient(BaseClient):
         """
         await self._delete(f"groups/{group_id}.json")
         return True
+
+    # ==================== Membership Operations ====================
+
+    def list_memberships(self, per_page: int = 100, limit: Optional[int] = None) -> "Paginator[GroupMembership]":
+        """Get paginated list of all group memberships.
+
+        Returns all group membership records across the entire account.
+
+        Args:
+            per_page: Number of memberships per API request (max 100).
+            limit: Maximum total memberships to return. None for no limit.
+
+        Returns:
+            Paginator[GroupMembership] for iterating through all memberships
+
+        Example:
+            async for membership in client.groups.list_memberships():
+                print(f"User {membership.user_id} in Group {membership.group_id}")
+        """
+        return ZendeskPaginator.create_group_memberships_paginator(self._http, per_page=per_page, limit=limit)
+
+    def list_group_members(
+        self, group_id: int, per_page: int = 100, limit: Optional[int] = None
+    ) -> "Paginator[GroupMembership]":
+        """Get paginated list of memberships for a specific group.
+
+        Returns membership records for agents in the given group.
+        Use this to find out which agents belong to a group.
+
+        Args:
+            group_id: The group's ID
+            per_page: Number of memberships per API request (max 100).
+            limit: Maximum total memberships to return. None for no limit.
+
+        Returns:
+            Paginator[GroupMembership] for iterating through group's memberships
+
+        Example:
+            # List all agents in a group
+            async for membership in client.groups.list_group_members(12345):
+                print(f"Agent {membership.user_id}, default={membership.default}")
+
+            # Collect all members
+            members = await client.groups.list_group_members(12345).collect()
+            user_ids = [m.user_id for m in members]
+        """
+        return ZendeskPaginator.create_group_memberships_by_group_paginator(
+            self._http, group_id, per_page=per_page, limit=limit
+        )
+
+    async def get_membership(self, membership_id: int) -> GroupMembership:
+        """Get a specific group membership by ID.
+
+        Args:
+            membership_id: The membership's ID
+
+        Returns:
+            GroupMembership object
+
+        Example:
+            membership = await client.groups.get_membership(99999)
+            print(f"User {membership.user_id} in Group {membership.group_id}")
+        """
+        response = await self._get(f"group_memberships/{membership_id}.json")
+        return GroupMembership(**response["group_membership"])

python_zendesk_sdk-0.13.0/src/zendesk_sdk/config.py

@@ -0,0 +1,175 @@
+"""Configuration management for Zendesk SDK."""
+
+import os
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, computed_field, field_validator, model_validator
+
+
+class CacheConfig(BaseModel):
+    """Cache configuration for Zendesk SDK.
+
+    Controls TTL (time-to-live) and max size for different resource caches.
+    Set enabled=False to disable caching entirely.
+    """
+
+    enabled: bool = Field(default=True, description="Enable/disable caching")
+
+    # Users cache
+    user_ttl: int = Field(default=300, description="User cache TTL in seconds (default: 5 min)", ge=0)
+    user_maxsize: int = Field(default=1000, description="Max cached users", ge=1)
+
+    # Organizations cache
+    org_ttl: int = Field(default=600, description="Organization cache TTL in seconds (default: 10 min)", ge=0)
+    org_maxsize: int = Field(default=500, description="Max cached organizations", ge=1)
+
+    # Groups cache
+    group_ttl: int = Field(default=600, description="Group cache TTL in seconds (default: 10 min)", ge=0)
+    group_maxsize: int = Field(default=500, description="Max cached groups", ge=1)
+
+    # Help Center cache
+    article_ttl: int = Field(default=900, description="Article cache TTL in seconds (default: 15 min)", ge=0)
+    article_maxsize: int = Field(default=500, description="Max cached articles", ge=1)
+
+    category_ttl: int = Field(default=1800, description="Category cache TTL in seconds (default: 30 min)", ge=0)
+    category_maxsize: int = Field(default=200, description="Max cached categories", ge=1)
+
+    section_ttl: int = Field(default=1800, description="Section cache TTL in seconds (default: 30 min)", ge=0)
+    section_maxsize: int = Field(default=200, description="Max cached sections", ge=1)
+
+
+class ZendeskConfig(BaseModel):
+    """Configuration for Zendesk API client.
+
+    Supports two authentication methods (mutually exclusive):
+    - Token auth: email + token (Basic Auth)
+    - OAuth: oauth_token (Bearer token)
+
+    Environment variables: ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_TOKEN, ZENDESK_OAUTH_TOKEN.
+    """
+
+    subdomain: str = Field(
+        ...,
+        description="Zendesk subdomain (e.g., 'mycompany' for mycompany.zendesk.com)",
+        min_length=1,
+    )
+    email: Optional[str] = Field(
+        default=None,
+        description="User email for token authentication",
+    )
+    token: Optional[str] = Field(
+        default=None,
+        description="API token for token authentication",
+    )
+    oauth_token: Optional[str] = Field(
+        default=None,
+        description="OAuth token for Bearer authentication",
+    )
+    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,
+    )
+    proactive_ratelimit: Optional[int] = Field(
+        default=None,
+        description="Start sleeping when X-Rate-Limit-Remaining drops below this threshold",
+        ge=1,
+    )
+    proactive_ratelimit_request_interval: int = Field(
+        default=10,
+        description="Seconds to wait between requests when proactive rate limit threshold is reached",
+        ge=1,
+    )
+    cache: CacheConfig = Field(
+        default_factory=CacheConfig,
+        description="Cache configuration",
+    )
+
+    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"))
+
+        # Only load env vars for one auth method — explicit args take precedence
+        has_explicit_token_auth = "email" in data or "token" in data
+        has_explicit_oauth = "oauth_token" in data
+
+        if not has_explicit_token_auth and not has_explicit_oauth:
+            # Nothing explicit — try env vars, token auth first
+            env_email = os.getenv("ZENDESK_EMAIL")
+            env_token = os.getenv("ZENDESK_TOKEN")
+            env_oauth = os.getenv("ZENDESK_OAUTH_TOKEN")
+            if env_email or env_token:
+                data.setdefault("email", env_email)
+                data.setdefault("token", env_token)
+            elif env_oauth:
+                data.setdefault("oauth_token", env_oauth)
+        elif has_explicit_token_auth and not has_explicit_oauth:
+            # Token auth explicit — fill missing from env
+            data.setdefault("email", os.getenv("ZENDESK_EMAIL"))
+            data.setdefault("token", os.getenv("ZENDESK_TOKEN"))
+        elif has_explicit_oauth and not has_explicit_token_auth:
+            # OAuth explicit — only fill oauth from env
+            data.setdefault("oauth_token", os.getenv("ZENDESK_OAUTH_TOKEN"))
+
+        super().__init__(**data)
+
+    @model_validator(mode="after")
+    def validate_auth(self) -> "ZendeskConfig":
+        """Validate that exactly one auth method is provided."""
+        has_token_auth = self.email is not None or self.token is not None
+        has_oauth = self.oauth_token is not None
+
+        if has_token_auth and has_oauth:
+            raise ValueError("Cannot use both token auth (email/token) and oauth_token simultaneously")
+
+        if not has_token_auth and not has_oauth:
+            raise ValueError("Either email/token or oauth_token must be provided")
+
+        if has_token_auth:
+            if not self.email or not self.token:
+                raise ValueError("Both email and token are required for token authentication")
+            if "@" not in self.email:
+                raise ValueError("Invalid email format")
+
+        return self
+
+    @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()
+
+    @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) -> Optional[tuple[str, str]]:
+        """Generate authentication tuple for HTTP requests. None for OAuth mode."""
+        if self.email and self.token:
+            return f"{self.email}/token", self.token
+        return None
+
+    def __repr__(self) -> str:
+        """String representation without exposing credentials."""
+        auth_info = f"email='{self.email}'" if self.email else "oauth=True"
+        parts = [
+            f"subdomain='{self.subdomain}'",
+            auth_info,
+            f"timeout={self.timeout}",
+            f"max_retries={self.max_retries}",
+        ]
+        if self.proactive_ratelimit is not None:
+            parts.append(f"proactive_ratelimit={self.proactive_ratelimit}")
+        return f"ZendeskConfig({', '.join(parts)})"

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/src/zendesk_sdk/http_client.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+from time import monotonic
 from typing import Any, Dict, Optional
 from urllib.parse import urljoin
 
@@ -31,6 +32,10 @@ class HTTPClient:
         self._client: Optional[httpx.AsyncClient] = None
         self._closed = False
 
+        # Proactive rate limit tracking
+        self._last_call_time: Optional[float] = None
+        self._last_limit_remaining: Optional[int] = None
+
     @property
     def client(self) -> httpx.AsyncClient:
         """Get or create httpx async client."""
@@ -40,14 +45,18 @@ class HTTPClient:
 
     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",
         }
 
+        auth: Optional[httpx.BasicAuth] = None
+        if self.config.auth_tuple:
+            auth = httpx.BasicAuth(username=self.config.auth_tuple[0], password=self.config.auth_tuple[1])
+        elif self.config.oauth_token:
+            headers["Authorization"] = f"Bearer {self.config.oauth_token}"
+
         return httpx.AsyncClient(
             auth=auth,
             headers=headers,
@@ -55,6 +64,40 @@ class HTTPClient:
             limits=httpx.Limits(max_keepalive_connections=10, max_connections=20),
         )
 
+    async def _apply_proactive_ratelimit(self) -> None:
+        """Apply proactive rate limiting by sleeping if remaining requests are below threshold."""
+        if self.config.proactive_ratelimit is None:
+            return
+        if self._last_limit_remaining is None or self._last_call_time is None:
+            return
+
+        if self._last_limit_remaining >= self.config.proactive_ratelimit:  # type: ignore[operator]
+            return
+
+        time_since_last = monotonic() - self._last_call_time
+        interval = self.config.proactive_ratelimit_request_interval
+        if time_since_last >= interval:
+            return
+
+        remaining_sleep = interval - time_since_last
+        logger.warning(
+            f"Proactive rate limit: {self._last_limit_remaining} remaining "
+            f"(threshold: {self.config.proactive_ratelimit}), sleeping {remaining_sleep:.1f}s"
+        )
+        await asyncio.sleep(remaining_sleep)
+
+    def _update_rate_limit_state(self, response: httpx.Response) -> None:
+        """Update rate limit tracking state from response headers."""
+        if self.config.proactive_ratelimit is None:
+            return
+        self._last_call_time = monotonic()
+        remaining_header = response.headers.get("X-Rate-Limit-Remaining")
+        if remaining_header is not None:
+            try:
+                self._last_limit_remaining = int(remaining_header)
+            except (ValueError, TypeError):
+                pass
+
     async def _make_request_with_retry(
         self,
         method: str,
@@ -72,6 +115,9 @@ class HTTPClient:
 
         for attempt in range(max_retries + 1):
             try:
+                # Apply proactive rate limiting before request
+                await self._apply_proactive_ratelimit()
+
                 # Make the actual request
                 response = await self.client.request(
                     method=method,
@@ -80,6 +126,9 @@ class HTTPClient:
                     json=json,
                 )
 
+                # Update rate limit tracking state
+                self._update_rate_limit_state(response)
+
                 # Handle different response types
                 retry_info = await self._handle_response(response, attempt, max_retries)
                 if retry_info:

{python_zendesk_sdk-0.11.0 → python_zendesk_sdk-0.13.0}/src/zendesk_sdk/models/__init__.py

@@ -4,6 +4,7 @@ from .base import ZendeskModel
 from .comment import Comment, CommentAttachment, CommentMetadata, CommentVia
 from .enriched_ticket import EnrichedTicket
 from .group import Group
+from .group_membership import GroupMembership
 from .help_center import Article, Category, Section
 from .organization import Organization, OrganizationField, OrganizationSubscription
 from .search import (
@@ -43,6 +44,7 @@ __all__ = [
     "PasswordRequirements",
     # Group models
     "Group",
+    "GroupMembership",
     # Organization models
     "Organization",
     "OrganizationField",

python_zendesk_sdk-0.13.0/src/zendesk_sdk/models/group_membership.py

@@ -0,0 +1,31 @@
+"""Group Membership model for Zendesk API."""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import Field
+
+from .base import ZendeskModel
+
+
+class GroupMembership(ZendeskModel):
+    """Zendesk Group Membership model.
+
+    Represents the association between a user (agent) and a group.
+    Agents can be members of multiple groups, and one group is marked
+    as their default group for ticket assignment.
+    """
+
+    # Read-only fields
+    id: Optional[int] = Field(None, description="Automatically assigned when creating memberships")
+    url: Optional[str] = Field(None, description="The API url of the membership")
+    user_id: int = Field(..., description="The ID of the agent")
+    group_id: int = Field(..., description="The ID of the group")
+    default: Optional[bool] = Field(None, description="If true, tickets assigned directly to the agent use this group")
+    created_at: Optional[datetime] = Field(None, description="The time the membership was created")
+    updated_at: Optional[datetime] = Field(None, description="The time of the last update")
+
+    def __str__(self) -> str:
+        """Human-readable string representation."""
+        default_str = " (default)" if self.default else ""
+        return f"User {self.user_id} -> Group {self.group_id}{default_str} (id={self.id})"