python-zendesk-sdk 0.10.0__tar.gz → 0.12.0__tar.gz

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-zendesk-sdk
-Version: 0.10.0
+Version: 0.12.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
@@ -266,6 +266,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",
@@ -289,6 +300,7 @@ await client.groups.delete(group_id)
 ```python
 # Read
 ticket = await client.tickets.get(ticket_id)           # Get ticket by ID
+tickets = await client.tickets.get_many([id1, id2])    # Get multiple tickets (batch)
 paginator = client.tickets.list()                      # List tickets (paginator)
 paginator = client.tickets.for_user(user_id)           # User's tickets (paginator)
 paginator = client.tickets.for_organization(org_id)    # Org's tickets (paginator)
@@ -358,9 +370,12 @@ Load tickets with all related data (comments, users, field definitions) in minim
 ```python
 from zendesk_sdk import SearchQueryConfig
 
-# Get ticket with all related data
+# Get single ticket with all related data
 enriched = await client.tickets.get_enriched(12345)
 
+# Batch: get multiple enriched tickets (much faster than calling get_enriched in a loop)
+enriched_list = await client.tickets.get_many_enriched([12345, 12346, 12347])
+
 print(f"Ticket: {enriched.ticket.subject}")
 print(f"Requester: {enriched.requester.name}")
 print(f"Assignee: {enriched.assignee.name if enriched.assignee else 'Unassigned'}")

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.0}/README.md

@@ -228,6 +228,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",
@@ -251,6 +262,7 @@ await client.groups.delete(group_id)
 ```python
 # Read
 ticket = await client.tickets.get(ticket_id)           # Get ticket by ID
+tickets = await client.tickets.get_many([id1, id2])    # Get multiple tickets (batch)
 paginator = client.tickets.list()                      # List tickets (paginator)
 paginator = client.tickets.for_user(user_id)           # User's tickets (paginator)
 paginator = client.tickets.for_organization(org_id)    # Org's tickets (paginator)
@@ -320,9 +332,12 @@ Load tickets with all related data (comments, users, field definitions) in minim
 ```python
 from zendesk_sdk import SearchQueryConfig
 
-# Get ticket with all related data
+# Get single ticket with all related data
 enriched = await client.tickets.get_enriched(12345)
 
+# Batch: get multiple enriched tickets (much faster than calling get_enriched in a loop)
+enriched_list = await client.tickets.get_many_enriched([12345, 12346, 12347])
+
 print(f"Ticket: {enriched.ticket.subject}")
 print(f"Requester: {enriched.requester.name}")
 print(f"Assignee: {enriched.assignee.name if enriched.assignee else 'Unassigned'}")

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.0}/examples/enriched_tickets.py

@@ -2,6 +2,7 @@
 
 This example demonstrates:
 - Loading tickets with all related data (comments, users, field definitions)
+- Batch loading multiple enriched tickets with get_many_enriched()
 - Using EnrichedTicket for efficient data access
 - Accessing custom field values with human-readable names
 - Minimizing API requests with batch loading
@@ -81,6 +82,23 @@ async def main() -> None:
             else:
                 print(f"  - Unknown: {body_preview}")
 
+        # ==================== Batch enriched tickets ====================
+
+        # Load multiple tickets with all related data at once
+        # Much more efficient than calling get_enriched() in a loop:
+        # - 1 API call for all tickets (show_many)
+        # - 1 API call for all users (show_many)
+        # - 1 API call for field definitions
+        # - N parallel API calls for comments (one per ticket)
+        ticket_ids = [12345, 12346, 12347]
+        enriched_list = await client.tickets.get_many_enriched(ticket_ids)
+
+        print(f"\n--- Batch loaded {len(enriched_list)} enriched tickets ---")
+        for item in enriched_list:
+            print(f"  #{item.ticket.id}: {item.ticket.subject}")
+            print(f"    Requester: {item.requester.name if item.requester else 'N/A'}")
+            print(f"    Comments: {len(item.comments)}")
+
         # ==================== Search with enrichment ====================
 
         # Search for tickets and load all related data

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.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.10.0 → python_zendesk_sdk-0.12.0}/pyproject.toml

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

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.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.10.0"
+__version__ = "0.12.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.10.0 → python_zendesk_sdk-0.12.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.10.0 → python_zendesk_sdk-0.12.0}/src/zendesk_sdk/clients/tickets.py

@@ -375,6 +375,32 @@ class TicketsClient(BaseClient):
         response = await self._get(f"tickets/{ticket_id}.json")
         return Ticket(**response["ticket"])
 
+    async def get_many(self, ticket_ids: List[int]) -> Dict[int, Ticket]:
+        """Fetch multiple tickets by IDs.
+
+        Uses show_many endpoint for efficiency (max 100 IDs per request).
+
+        Args:
+            ticket_ids: List of ticket IDs to fetch
+
+        Returns:
+            Dictionary mapping ticket_id to Ticket object
+        """
+        if not ticket_ids:
+            return {}
+
+        unique_ids = list(set(ticket_ids))[:100]
+        ids_param = ",".join(str(tid) for tid in unique_ids)
+
+        response = await self._get(f"tickets/show_many.json?ids={ids_param}")
+
+        tickets: Dict[int, Ticket] = {}
+        for ticket_data in response.get("tickets", []):
+            ticket = Ticket(**ticket_data)
+            if ticket.id is not None:
+                tickets[ticket.id] = ticket
+        return tickets
+
     def list(self, per_page: int = 100, limit: Optional[int] = None) -> "Paginator[Ticket]":
         """Get paginated list of all tickets in the account.
 
@@ -844,6 +870,35 @@ class TicketsClient(BaseClient):
         ticket_users = self._extract_users_from_response(response)
         return await self._build_enriched_ticket(ticket, ticket_users, fields)
 
+    async def get_many_enriched(self, ticket_ids: List[int]) -> List[EnrichedTicket]:
+        """Get multiple tickets with all related data: comments, users, and field definitions.
+
+        Batch-loads tickets, users, and fields in parallel, then fetches comments
+        for each ticket. Much more efficient than calling get_enriched() in a loop.
+
+        Args:
+            ticket_ids: List of ticket IDs to fetch (max 100)
+
+        Returns:
+            List of EnrichedTicket objects
+        """
+        if not ticket_ids:
+            return []
+
+        # Fetch tickets and fields in parallel (independent calls)
+        tickets_dict, fields = await asyncio.gather(
+            self.get_many(ticket_ids),
+            self._fetch_fields(),
+        )
+        if not tickets_dict:
+            return []
+
+        tickets = list(tickets_dict.values())
+        user_ids = self._collect_user_ids_from_tickets(tickets)
+        ticket_users = await self._fetch_users_batch(user_ids)
+
+        return await self._build_enriched_tickets(tickets, ticket_users, fields)
+
     async def search_enriched(
         self,
         query: Union[str, SearchQueryConfig],

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.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.12.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})"

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.0}/src/zendesk_sdk/pagination.py

@@ -5,7 +5,7 @@ from abc import ABC, abstractmethod
 from typing import Any, AsyncIterator, Dict, Generic, List, Optional, TypeVar
 
 from .exceptions import ZendeskPaginationException
-from .models import Article, Category, Comment, Group, Organization, Section, Ticket, TicketField, User
+from .models import Article, Category, Comment, Group, GroupMembership, Organization, Section, Ticket, TicketField, User
 
 logger = logging.getLogger(__name__)
 
@@ -557,6 +557,32 @@ class ZendeskPaginator:
 
         return AssignableGroupsPaginator(http_client, "groups/assignable.json", per_page=per_page, limit=limit)
 
+    @staticmethod
+    def create_group_memberships_paginator(
+        http_client: Any, per_page: int = 100, limit: Optional[int] = None
+    ) -> OffsetPaginator[GroupMembership]:
+        """Create paginator for all group memberships endpoint."""
+
+        class GroupMembershipsPaginator(OffsetPaginator[GroupMembership]):
+            def _extract_items(self, response: Dict[str, Any]) -> List[GroupMembership]:
+                return [GroupMembership(**m) for m in response.get("group_memberships", [])]
+
+        return GroupMembershipsPaginator(http_client, "group_memberships.json", per_page=per_page, limit=limit)
+
+    @staticmethod
+    def create_group_memberships_by_group_paginator(
+        http_client: Any, group_id: int, per_page: int = 100, limit: Optional[int] = None
+    ) -> OffsetPaginator[GroupMembership]:
+        """Create paginator for memberships of a specific group."""
+
+        class GroupMembershipsByGroupPaginator(OffsetPaginator[GroupMembership]):
+            def _extract_items(self, response: Dict[str, Any]) -> List[GroupMembership]:
+                return [GroupMembership(**m) for m in response.get("group_memberships", [])]
+
+        return GroupMembershipsByGroupPaginator(
+            http_client, f"groups/{group_id}/memberships.json", per_page=per_page, limit=limit
+        )
+
     @staticmethod
     def create_ticket_fields_paginator(
         http_client: Any, per_page: int = 100, limit: Optional[int] = None

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.0}/tests/test_clients.py

@@ -13,7 +13,7 @@ from zendesk_sdk.clients import (
     TicketsClient,
     UsersClient,
 )
-from zendesk_sdk.models import Comment, Organization, Ticket, User
+from zendesk_sdk.models import Comment, EnrichedTicket, Organization, Ticket, User
 
 
 class TestUsersClient:
@@ -960,6 +960,98 @@ class TestTicketsClient:
             assert result is True
             mock_delete.assert_called_once_with("tickets/12345.json")
 
+    @pytest.mark.asyncio
+    async def test_get_many(self):
+        """Test batch get tickets by IDs."""
+        client = self.get_client()
+        response_data = {
+            "tickets": [
+                {"id": 1, "subject": "Ticket 1", "status": "open", "created_at": "2023-01-01T00:00:00Z"},
+                {"id": 2, "subject": "Ticket 2", "status": "pending", "created_at": "2023-01-02T00:00:00Z"},
+                {"id": 3, "subject": "Ticket 3", "status": "solved", "created_at": "2023-01-03T00:00:00Z"},
+            ]
+        }
+
+        with patch.object(client, "_get", new_callable=AsyncMock) as mock_get:
+            mock_get.return_value = response_data
+
+            result = await client.get_many([1, 2, 3])
+
+            assert len(result) == 3
+            assert isinstance(result[1], Ticket)
+            assert result[1].subject == "Ticket 1"
+            assert result[2].subject == "Ticket 2"
+            assert result[3].subject == "Ticket 3"
+            mock_get.assert_called_once()
+            call_url = mock_get.call_args[0][0]
+            assert call_url.startswith("tickets/show_many.json?ids=")
+
+    @pytest.mark.asyncio
+    async def test_get_many_empty(self):
+        """Test batch get tickets with empty list."""
+        client = self.get_client()
+
+        result = await client.get_many([])
+
+        assert result == {}
+
+    @pytest.mark.asyncio
+    async def test_get_many_deduplicates(self):
+        """Test batch get tickets deduplicates IDs."""
+        client = self.get_client()
+        response_data = {
+            "tickets": [
+                {"id": 1, "subject": "Ticket 1", "status": "open", "created_at": "2023-01-01T00:00:00Z"},
+            ]
+        }
+
+        with patch.object(client, "_get", new_callable=AsyncMock) as mock_get:
+            mock_get.return_value = response_data
+
+            result = await client.get_many([1, 1, 1])
+
+            assert len(result) == 1
+            call_url = mock_get.call_args[0][0]
+            assert "ids=1" in call_url
+
+    @pytest.mark.asyncio
+    async def test_get_many_enriched(self):
+        """Test batch get enriched tickets."""
+        client = self.get_client()
+
+        tickets_dict = {
+            1: Ticket(id=1, subject="T1", status="open", requester_id=100, created_at="2023-01-01T00:00:00Z"),
+            2: Ticket(id=2, subject="T2", status="open", requester_id=200, created_at="2023-01-02T00:00:00Z"),
+        }
+        mock_users = {100: User(id=100, name="User A"), 200: User(id=200, name="User B")}
+        mock_enriched = [
+            EnrichedTicket(ticket=tickets_dict[1], comments=[], users={100: mock_users[100]}, fields={}),
+            EnrichedTicket(ticket=tickets_dict[2], comments=[], users={200: mock_users[200]}, fields={}),
+        ]
+
+        with (
+            patch.object(client, "get_many", new_callable=AsyncMock, return_value=tickets_dict) as mock_get_many,
+            patch.object(client, "_fetch_users_batch", new_callable=AsyncMock, return_value=mock_users),
+            patch.object(client, "_fetch_fields", new_callable=AsyncMock, return_value={}),
+            patch.object(client, "_build_enriched_tickets", new_callable=AsyncMock, return_value=mock_enriched),
+        ):
+            result = await client.get_many_enriched([1, 2])
+
+            assert len(result) == 2
+            assert isinstance(result[0], EnrichedTicket)
+            assert result[0].ticket.id == 1
+            assert result[1].ticket.id == 2
+            mock_get_many.assert_called_once_with([1, 2])
+
+    @pytest.mark.asyncio
+    async def test_get_many_enriched_empty(self):
+        """Test batch get enriched tickets with empty list."""
+        client = self.get_client()
+
+        result = await client.get_many_enriched([])
+
+        assert result == []
+
 
 class TestCommentsClient:
     """Test cases for CommentsClient."""

{python_zendesk_sdk-0.10.0 → python_zendesk_sdk-0.12.0}/tests/test_package_import.py

@@ -9,7 +9,7 @@ class TestPackageImport:
         import zendesk_sdk
 
         assert hasattr(zendesk_sdk, "__version__")
-        assert zendesk_sdk.__version__ == "0.10.0"
+        assert zendesk_sdk.__version__ == "0.12.0"
 
     def test_client_import(self):
         """Test importing ZendeskClient."""