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

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

@@ -190,5 +190,7 @@ debug_*.py
 
 # Local directories
 .claude/
-llm/
-CLAUDE.md
+CLAUDE.md
+# Note: `llm/` is excluded via .git/info/exclude (local git-ignore not committed)
+# so Claude Code can still see it via @-autocomplete, which honors .gitignore
+# but not .git/info/exclude.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-zendesk-sdk
-Version: 0.13.0
+Version: 0.14.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
@@ -63,9 +63,11 @@ Modern Python SDK for Zendesk API, designed for automation and AI agents.
   - [Comments](#comments-nested-under-tickets)
   - [Tags](#tags-nested-under-tickets)
   - [Ticket Fields](#ticket-fields)
+  - [Ticket Metrics](#ticket-metrics)
   - [Enriched Tickets](#enriched-tickets)
   - [Attachments](#attachments)
   - [Search](#search)
+  - [Views](#views)
   - [Help Center](#help-center)
 - [Error Handling](#error-handling)
 - [Proactive Rate Limiting](#proactive-rate-limiting)
@@ -194,6 +196,11 @@ async for user in client.users.list():
 
 # 3. Collect to list
 users = await client.users.list(limit=50).collect()
+
+# Get total count without iterating (uses Zendesk's count from response)
+paginator = client.users.list()
+total = await paginator.count()       # async; issues a probe request if needed
+cached = paginator.total_count        # sync; None until at least one page fetched
 ```
 
 ### Users
@@ -379,6 +386,32 @@ field = await client.ticket_fields.get(field_id)
 field = await client.ticket_fields.get_by_title("Subscription")
 ```
 
+### Ticket Metrics
+
+Read-only access to per-ticket metrics: first reply time, full resolution time,
+agent/requester wait time, on-hold time. Every time field exposes both calendar
+(wall-clock) and business (business-hours) values.
+
+```python
+# Metrics for a specific ticket — primary use case
+metrics = await client.ticket_metrics.for_ticket(ticket_id)
+print(metrics.reply_time_in_minutes)
+# {"calendar": 42, "business": 15}
+
+# Metric by its own id
+metrics = await client.ticket_metrics.get(metric_id)
+
+# Iterate over all metrics (offset pagination)
+async for m in client.ticket_metrics.list(per_page=100):
+    if m.full_resolution_time_in_minutes:
+        ...
+
+# Total count (single extra request, see Pagination)
+total = await client.ticket_metrics.list().count()
+```
+
+Metrics are live data — the client intentionally does not cache responses.
+
 ### Enriched Tickets
 
 Load tickets with all related data (comments, users, field definitions) in minimum API requests:
@@ -543,6 +576,48 @@ async for ticket in client.search.export_tickets("priority:high", limit=500):
 | `search.tickets()` | 1000 max | Offset | Possible |
 | `search.export_tickets()` | None | Cursor | None |
 
+### Views
+
+Views are saved searches over tickets — the day-to-day workspace of an
+agent. Read-only access through `client.views`: list views, fetch a
+view's tickets, count tickets without loading them. Useful for
+LLM-agents (skip query construction — use views the support team has
+already curated) and dashboards (counts in one request).
+
+```python
+# List views
+async for view in client.views.list():
+    print(f"{view.title} (active={view.active})")
+
+# Active views only
+active = await client.views.list(active_only=True).collect()
+
+# Get a single view (cached)
+view = await client.views.get(12345)
+print(view.conditions)  # raw {'all': [...], 'any': [...]}
+
+# Get many views in one request (max 100 IDs)
+views = await client.views.get_many([1, 2, 3])
+
+# Iterate tickets in a view
+async for ticket in client.views.tickets(12345):
+    print(f"#{ticket.id}: {ticket.subject}")
+
+# Count tickets without loading them
+count = await client.views.count(12345)
+print(f"{count.value} tickets (fresh={count.fresh})")
+
+# Counts for several views in one request (great for dashboards, max 20 IDs)
+counts = await client.views.count_many([1, 2, 3])
+for c in counts:
+    print(f"view {c.view_id}: {c.value}")
+```
+
+> **Read-only** by design. Views are owned by admins and rarely edited
+> via API. For very large views the count is served from a server-side
+> cache — check `ViewCount.fresh` to know if it's authoritative.
+
+
 ### Help Center
 
 Access Help Center (Guide) via `client.help_center` namespace:

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

@@ -25,9 +25,11 @@ Modern Python SDK for Zendesk API, designed for automation and AI agents.
   - [Comments](#comments-nested-under-tickets)
   - [Tags](#tags-nested-under-tickets)
   - [Ticket Fields](#ticket-fields)
+  - [Ticket Metrics](#ticket-metrics)
   - [Enriched Tickets](#enriched-tickets)
   - [Attachments](#attachments)
   - [Search](#search)
+  - [Views](#views)
   - [Help Center](#help-center)
 - [Error Handling](#error-handling)
 - [Proactive Rate Limiting](#proactive-rate-limiting)
@@ -156,6 +158,11 @@ async for user in client.users.list():
 
 # 3. Collect to list
 users = await client.users.list(limit=50).collect()
+
+# Get total count without iterating (uses Zendesk's count from response)
+paginator = client.users.list()
+total = await paginator.count()       # async; issues a probe request if needed
+cached = paginator.total_count        # sync; None until at least one page fetched
 ```
 
 ### Users
@@ -341,6 +348,32 @@ field = await client.ticket_fields.get(field_id)
 field = await client.ticket_fields.get_by_title("Subscription")
 ```
 
+### Ticket Metrics
+
+Read-only access to per-ticket metrics: first reply time, full resolution time,
+agent/requester wait time, on-hold time. Every time field exposes both calendar
+(wall-clock) and business (business-hours) values.
+
+```python
+# Metrics for a specific ticket — primary use case
+metrics = await client.ticket_metrics.for_ticket(ticket_id)
+print(metrics.reply_time_in_minutes)
+# {"calendar": 42, "business": 15}
+
+# Metric by its own id
+metrics = await client.ticket_metrics.get(metric_id)
+
+# Iterate over all metrics (offset pagination)
+async for m in client.ticket_metrics.list(per_page=100):
+    if m.full_resolution_time_in_minutes:
+        ...
+
+# Total count (single extra request, see Pagination)
+total = await client.ticket_metrics.list().count()
+```
+
+Metrics are live data — the client intentionally does not cache responses.
+
 ### Enriched Tickets
 
 Load tickets with all related data (comments, users, field definitions) in minimum API requests:
@@ -505,6 +538,48 @@ async for ticket in client.search.export_tickets("priority:high", limit=500):
 | `search.tickets()` | 1000 max | Offset | Possible |
 | `search.export_tickets()` | None | Cursor | None |
 
+### Views
+
+Views are saved searches over tickets — the day-to-day workspace of an
+agent. Read-only access through `client.views`: list views, fetch a
+view's tickets, count tickets without loading them. Useful for
+LLM-agents (skip query construction — use views the support team has
+already curated) and dashboards (counts in one request).
+
+```python
+# List views
+async for view in client.views.list():
+    print(f"{view.title} (active={view.active})")
+
+# Active views only
+active = await client.views.list(active_only=True).collect()
+
+# Get a single view (cached)
+view = await client.views.get(12345)
+print(view.conditions)  # raw {'all': [...], 'any': [...]}
+
+# Get many views in one request (max 100 IDs)
+views = await client.views.get_many([1, 2, 3])
+
+# Iterate tickets in a view
+async for ticket in client.views.tickets(12345):
+    print(f"#{ticket.id}: {ticket.subject}")
+
+# Count tickets without loading them
+count = await client.views.count(12345)
+print(f"{count.value} tickets (fresh={count.fresh})")
+
+# Counts for several views in one request (great for dashboards, max 20 IDs)
+counts = await client.views.count_many([1, 2, 3])
+for c in counts:
+    print(f"view {c.view_id}: {c.value}")
+```
+
+> **Read-only** by design. Views are owned by admins and rarely edited
+> via API. For very large views the count is served from a server-side
+> cache — check `ViewCount.fresh` to know if it's authoritative.
+
+
 ### Help Center
 
 Access Help Center (Guide) via `client.help_center` namespace:

{python_zendesk_sdk-0.13.0 → python_zendesk_sdk-0.14.0}/examples/pagination_example.py

@@ -1,9 +1,10 @@
 """Pagination example for Zendesk SDK.
 
-This example demonstrates three ways to work with paginators:
+This example demonstrates four ways to work with paginators:
 1. Get specific page
 2. Iterate through all items
 3. Collect to list
+4. Ask for total count without collecting
 
 All list() and search() methods return Paginator objects.
 """
@@ -68,6 +69,23 @@ async def main() -> None:
         # Collect all (be careful with large datasets!)
         # all_users = await client.users.list().collect()
 
+        # ==================== Method 4: Total count only ====================
+
+        print("\n=== Method 4: Total count without collecting ===")
+
+        # count() issues a lightweight probe (per_page=1) when no page has been
+        # fetched yet; returns the cached count otherwise. Does not mutate state.
+        total_open = await client.search.tickets("status:open").count()
+        print(f"Open tickets in total: {total_open}")
+
+        # After iteration / get_page(), total_count is a free sync property.
+        paginator = client.users.list(per_page=100)
+        await paginator.get_page()
+        print(f"Users total_count (cached): {paginator.total_count}")
+
+        # Cursor-based paginators (incremental, search export) return None:
+        # the Zendesk API does not expose a total for them.
+
         # ==================== Pagination with search ====================
 
         print("\n=== Pagination with search ===")

python_zendesk_sdk-0.14.0/examples/ticket_metrics_example.py

@@ -0,0 +1,74 @@
+"""Ticket Metrics example for Zendesk SDK.
+
+Three ways to use ticket_metrics:
+1. Get metrics for a specific ticket (primary use case)
+2. Iterate over all metrics
+3. Find tickets that took long to resolve
+"""
+
+import asyncio
+
+from zendesk_sdk import ZendeskClient, ZendeskConfig
+
+
+async def main() -> None:
+    config = ZendeskConfig(
+        subdomain="your-subdomain",
+        email="your-email@example.com",
+        token="your-api-token",
+    )
+
+    async with ZendeskClient(config) as client:
+        # ==================== Method 1: Metrics for a ticket ====================
+
+        print("=== Method 1: Metrics for a specific ticket ===")
+
+        ticket_id = 12345
+        metrics = await client.ticket_metrics.for_ticket(ticket_id)
+
+        # Time fields are dicts with "calendar" (wall-clock) and "business"
+        # (business hours) sub-values, either of which may be None.
+        reply = metrics.reply_time_in_minutes or {}
+        resolution = metrics.full_resolution_time_in_minutes or {}
+
+        print(f"Ticket #{metrics.ticket_id}")
+        print(f"  Replies:                    {metrics.replies}")
+        print(f"  Reply time (calendar):      {reply.get('calendar')} min")
+        print(f"  Reply time (business):      {reply.get('business')} min")
+        print(f"  Full resolution (calendar): {resolution.get('calendar')} min")
+        print(f"  Reopens:                    {metrics.reopens}")
+
+        # ==================== Method 2: Iterate all ====================
+
+        print("\n=== Method 2: Iterate over all metrics ===")
+
+        total = await client.ticket_metrics.list().count()
+        print(f"Total ticket_metrics: {total}")
+
+        count = 0
+        async for m in client.ticket_metrics.list(per_page=100, limit=10):
+            count += 1
+            print(f"  #{m.ticket_id}: replies={m.replies}, reopens={m.reopens}")
+
+        print(f"Looked at {count} metric records")
+
+        # ==================== Method 3: Long-to-resolve tickets =================
+
+        print("\n=== Method 3: Tickets that took > 1 day of business hours ===")
+
+        threshold_minutes = 24 * 60
+        slow = []
+        async for m in client.ticket_metrics.list(limit=500):
+            resolution = m.full_resolution_time_in_minutes or {}
+            business = resolution.get("business")
+            if business is not None and business > threshold_minutes:
+                slow.append((m.ticket_id, business))
+
+        slow.sort(key=lambda pair: pair[1], reverse=True)
+        for ticket_id, business_minutes in slow[:10]:
+            hours = business_minutes / 60
+            print(f"  #{ticket_id}: {hours:.1f} business hours to resolve")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python_zendesk_sdk-0.14.0/examples/views.py

@@ -0,0 +1,84 @@
+"""Views API example for Zendesk SDK.
+
+This example demonstrates read-only operations on Views:
+- Listing views (all + active only)
+- Getting a single view (cached)
+- Iterating tickets in a view
+- Counting tickets in views (single + bulk)
+"""
+
+import asyncio
+
+from zendesk_sdk import ZendeskClient, ZendeskConfig
+
+
+async def main() -> None:
+    config = ZendeskConfig(
+        subdomain="your-subdomain",
+        email="your-email@example.com",
+        token="your-api-token",
+    )
+
+    async with ZendeskClient(config) as client:
+        # ==================== List views ====================
+
+        print("=== All views ===")
+        async for view in client.views.list(limit=10):
+            status = "active" if view.active else "inactive"
+            default = " (default)" if view.default else ""
+            print(f"  {view.id}: {view.title} [{status}]{default}")
+
+        print("\n=== Active views only ===")
+        active_views = await client.views.list(active_only=True, limit=10).collect()
+        for view in active_views:
+            print(f"  {view.id}: {view.title}")
+
+        if not active_views:
+            print("  (no active views found)")
+            return
+
+        sample_view = active_views[0]
+
+        # ==================== Get a single view ====================
+
+        print(f"\n=== Get view {sample_view.id} ===")
+        view = await client.views.get(sample_view.id)  # type: ignore[arg-type]
+        print(f"  Title: {view.title}")
+        print(f"  Description: {view.description or '(none)'}")
+        print(f"  Conditions: {view.conditions}")
+
+        # Second call hits the cache
+        view_cached = await client.views.get(sample_view.id)  # type: ignore[arg-type]
+        print(f"  (cached) Title: {view_cached.title}")
+
+        # ==================== get_many ====================
+
+        print("\n=== get_many ===")
+        ids = [v.id for v in active_views[:3] if v.id is not None]
+        many = await client.views.get_many(ids)
+        for vid, v in many.items():
+            print(f"  {vid}: {v.title}")
+
+        # ==================== Tickets in a view ====================
+
+        print(f"\n=== First 5 tickets in view {sample_view.id} ===")
+        async for ticket in client.views.tickets(sample_view.id, limit=5):  # type: ignore[arg-type]
+            print(f"  #{ticket.id}: {ticket.subject} [{ticket.status}]")
+
+        # ==================== Count tickets in a view ====================
+
+        print(f"\n=== Count for view {sample_view.id} ===")
+        count = await client.views.count(sample_view.id)  # type: ignore[arg-type]
+        staleness = "fresh" if count.fresh else "stale (cached server-side)"
+        print(f"  {count.value} tickets ({staleness})")
+
+        # ==================== count_many for a dashboard ====================
+
+        print("\n=== count_many for several views ===")
+        counts = await client.views.count_many(ids)
+        for c in counts:
+            print(f"  view {c.view_id}: {c.value} tickets")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

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

{python_zendesk_sdk-0.13.0 → python_zendesk_sdk-0.14.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.13.0"
+__version__ = "0.14.0"
 
 from .client import ZendeskClient
 from .clients import (
@@ -20,8 +20,10 @@ from .clients import (
     SectionsClient,
     TagsClient,
     TicketFieldsClient,
+    TicketMetricsClient,
     TicketsClient,
     UsersClient,
+    ViewsClient,
 )
 from .config import CacheConfig, ZendeskConfig
 from .exceptions import (
@@ -46,6 +48,7 @@ from .models import (
     SortOrder,
     TicketChannel,
     TicketField,
+    TicketMetrics,
     TicketPriority,
     TicketPriorityInput,
     TicketStatus,
@@ -53,6 +56,8 @@ from .models import (
     TicketType,
     TicketTypeInput,
     UserRole,
+    View,
+    ViewCount,
 )
 
 __all__ = [
@@ -66,10 +71,12 @@ __all__ = [
     "OrganizationsClient",
     "TicketsClient",
     "TicketFieldsClient",
+    "TicketMetricsClient",
     "CommentsClient",
     "TagsClient",
     "AttachmentsClient",
     "SearchClient",
+    "ViewsClient",
     # Help Center
     "HelpCenterClient",
     "CategoriesClient",
@@ -80,9 +87,12 @@ __all__ = [
     "GroupMembership",
     "EnrichedTicket",
     "TicketField",
+    "TicketMetrics",
     "Category",
     "Section",
     "Article",
+    "View",
+    "ViewCount",
     # Search
     "SearchQueryConfig",
     "SearchType",

{python_zendesk_sdk-0.13.0 → python_zendesk_sdk-0.14.0}/src/zendesk_sdk/client.py

@@ -14,8 +14,10 @@ if TYPE_CHECKING:
         OrganizationsClient,
         SearchClient,
         TicketFieldsClient,
+        TicketMetricsClient,
         TicketsClient,
         UsersClient,
+        ViewsClient,
     )
 
 
@@ -204,6 +206,30 @@ class ZendeskClient:
 
         return TicketFieldsClient(self.http_client, self.config.cache)
 
+    @cached_property
+    def ticket_metrics(self) -> "TicketMetricsClient":
+        """Access Ticket Metrics API.
+
+        Read-only access to per-ticket metrics: first reply time, full
+        resolution time, agent/requester wait time, on-hold time, etc.
+        Time fields expose both calendar and business hours.
+
+        Example:
+            # Metrics for a specific ticket (primary use case)
+            metrics = await client.ticket_metrics.for_ticket(12345)
+            print(metrics.reply_time_in_minutes)  # {"calendar": 42, "business": 15}
+
+            # Metric by its own id
+            metrics = await client.ticket_metrics.get(999)
+
+            # Iterate over all metrics
+            async for m in client.ticket_metrics.list():
+                ...
+        """
+        from .clients import TicketMetricsClient
+
+        return TicketMetricsClient(self.http_client)
+
     @cached_property
     def attachments(self) -> "AttachmentsClient":
         """Access Attachments API.
@@ -234,6 +260,34 @@ class ZendeskClient:
 
         return SearchClient(self.http_client)
 
+    @cached_property
+    def views(self) -> "ViewsClient":
+        """Access Views API (read-only).
+
+        Views are saved searches over tickets — the way agents work
+        with tickets day-to-day. Read-only: list, get, tickets, count,
+        count_many.
+
+        Example:
+            # List all views
+            async for view in client.views.list():
+                print(f"{view.title} (active={view.active})")
+
+            # Get a specific view (cached)
+            view = await client.views.get(12345)
+
+            # Tickets in a view
+            async for ticket in client.views.tickets(12345):
+                print(ticket.subject)
+
+            # Counts without loading tickets
+            count = await client.views.count(12345)
+            counts = await client.views.count_many([1, 2, 3])
+        """
+        from .clients import ViewsClient
+
+        return ViewsClient(self.http_client, self.config.cache)
+
     @cached_property
     def help_center(self) -> "HelpCenterClient":
         """Access Help Center API with nested categories, sections, articles.

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

@@ -6,8 +6,10 @@ from .help_center import ArticlesClient, CategoriesClient, HelpCenterClient, Sec
 from .organizations import OrganizationsClient
 from .search import SearchClient
 from .ticket_fields import TicketFieldsClient
+from .ticket_metrics import TicketMetricsClient
 from .tickets import CommentsClient, TagsClient, TicketsClient
 from .users import UsersClient
+from .views import ViewsClient
 
 __all__ = [
     # Main clients
@@ -16,8 +18,10 @@ __all__ = [
     "OrganizationsClient",
     "TicketsClient",
     "TicketFieldsClient",
+    "TicketMetricsClient",
     "AttachmentsClient",
     "SearchClient",
+    "ViewsClient",
     # Ticket sub-clients
     "CommentsClient",
     "TagsClient",

python_zendesk_sdk-0.14.0/src/zendesk_sdk/clients/ticket_metrics.py

@@ -0,0 +1,84 @@
+"""Ticket Metrics API client."""
+
+from typing import TYPE_CHECKING, Optional
+
+from ..models.ticket import TicketMetrics
+from ..pagination import ZendeskPaginator
+from .base import BaseClient
+
+if TYPE_CHECKING:
+    from ..http_client import HTTPClient
+    from ..pagination import Paginator
+
+
+class TicketMetricsClient(BaseClient):
+    """Client for Zendesk Ticket Metrics API.
+
+    Provides read-only access to per-ticket metrics: first reply time,
+    full resolution time, requester/agent wait time, on-hold time, etc.
+    All time-based fields expose both calendar and business hours.
+
+    Metrics are live data — they change with every ticket update, so
+    responses are not cached.
+
+    Example:
+        async with ZendeskClient(config) as client:
+            # Metrics for a specific ticket (most common)
+            metrics = await client.ticket_metrics.for_ticket(12345)
+            print(metrics.reply_time_in_minutes)
+            # {"calendar": 42, "business": 15}
+
+            # Metric by its own id
+            metrics = await client.ticket_metrics.get(999)
+
+            # Iterate over all metrics
+            async for m in client.ticket_metrics.list(per_page=100):
+                if m.full_resolution_time_in_minutes:
+                    ...
+    """
+
+    def __init__(self, http_client: "HTTPClient") -> None:
+        """Initialize TicketMetricsClient.
+
+        No cache: metrics are live data and change with each ticket update.
+        """
+        super().__init__(http_client)
+
+    async def get(self, metric_id: int) -> TicketMetrics:
+        """Get a ticket metric by its own id.
+
+        Args:
+            metric_id: The ticket metric id (not the ticket id)
+
+        Returns:
+            TicketMetrics object
+        """
+        response = await self._get(f"ticket_metrics/{metric_id}.json")
+        return TicketMetrics(**response["ticket_metric"])
+
+    async def for_ticket(self, ticket_id: int) -> TicketMetrics:
+        """Get metrics for a given ticket.
+
+        This is the primary use case — look up metrics for a ticket
+        you already have an id for.
+
+        Args:
+            ticket_id: The ticket id
+
+        Returns:
+            TicketMetrics object
+        """
+        response = await self._get(f"tickets/{ticket_id}/metrics.json")
+        return TicketMetrics(**response["ticket_metric"])
+
+    def list(self, per_page: int = 100, limit: Optional[int] = None) -> "Paginator[TicketMetrics]":
+        """Get paginated list of all ticket metrics.
+
+        Args:
+            per_page: Number of metrics per page (max 100)
+            limit: Maximum total items when iterating (None = no limit)
+
+        Returns:
+            Paginator yielding TicketMetrics objects
+        """
+        return ZendeskPaginator.create_ticket_metrics_paginator(self._http, per_page=per_page, limit=limit)