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

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

@@ -190,4 +190,7 @@ debug_*.py
 
 # Local directories
 .claude/
-llm/
+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.12.0 → python_zendesk_sdk-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-zendesk-sdk
-Version: 0.12.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,11 +63,14 @@ 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)
 - [Caching](#caching)
 - [Examples](#examples)
 
@@ -102,6 +105,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 +146,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
@@ -178,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
@@ -363,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:
@@ -527,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:
@@ -656,6 +747,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.12.0 → python_zendesk_sdk-0.14.0}/README.md

@@ -25,11 +25,14 @@ 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)
 - [Caching](#caching)
 - [Examples](#examples)
 
@@ -64,6 +67,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 +108,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
@@ -140,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
@@ -325,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:
@@ -489,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:
@@ -618,6 +709,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.12.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.12.0 → python_zendesk_sdk-0.14.0}/pyproject.toml

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

{python_zendesk_sdk-0.12.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.12.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",