python-zendesk-sdk 0.2.0__tar.gz → 0.3.1__tar.gz

{python_zendesk_sdk-0.2.0 → python_zendesk_sdk-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-zendesk-sdk
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8.1
+Requires-Dist: async-lru>=2.0.0
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: pydantic>=2.0.0
 Provides-Extra: dev
@@ -37,17 +38,69 @@ Description-Content-Type: text/markdown
 
 # Python Zendesk SDK
 
-Modern Python SDK for Zendesk API with async support, full type safety, and comprehensive error handling.
+[![PyPI](https://img.shields.io/pypi/v/python-zendesk-sdk)](https://pypi.org/project/python-zendesk-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/python-zendesk-sdk)](https://pypi.org/project/python-zendesk-sdk/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/python-zendesk-sdk?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/python-zendesk-sdk)
+[![License](https://img.shields.io/github/license/bormog/python-zendesk-sdk)](https://github.com/bormog/python-zendesk-sdk/blob/main/LICENSE)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Pydantic v2](https://img.shields.io/badge/Pydantic-v2-blue)](https://docs.pydantic.dev/)
+[![Async](https://img.shields.io/badge/async-first-blueviolet)](https://docs.python.org/3/library/asyncio.html)
+
+Modern Python SDK for Zendesk API, designed for automation and AI agents.
+
+## Table of Contents
+
+- [Why This SDK?](#why-this-sdk)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [API Methods](#api-methods)
+  - [Users](#users)
+  - [Organizations](#organizations)
+  - [Tickets](#tickets)
+  - [Comments](#comments-nested-under-tickets)
+  - [Tags](#tags-nested-under-tickets)
+  - [Enriched Tickets](#enriched-tickets)
+  - [Attachments](#attachments)
+  - [Search](#search)
+  - [Help Center](#help-center)
+- [Error Handling](#error-handling)
+- [Caching](#caching)
+- [Examples](#examples)
+
+## Why This SDK?
+
+Zendesk has a powerful REST API, but using it directly is painful:
+- Multiple API calls needed to get complete ticket context (ticket + comments + users)
+- No type safety — just raw JSON dictionaries
+- Manual pagination handling
+- Boilerplate retry/rate-limit logic in every project
+
+**This SDK solves these problems** with a clean, typed interface optimized for:
+
+- **Support automation** — workflows, triggers, integrations
+- **Internal tools** — dashboards, reports, bulk operations
+- **LLM agents** — Claude Code, Codex, custom AI assistants that need structured Zendesk access
+
+### Developer Experience
+
+- **Predictable structure** — typed Pydantic models instead of arbitrary dicts
+- **Complete context in one call** — `get_enriched()` returns ticket + all comments + all users
+- **No boilerplate** — pagination, caching, and object loading handled automatically
+- **Minimal API calls** — built-in caching and batching reduce redundant requests
+- **Clear namespaces** — `client.tickets.comments.add()` is self-documenting
 
 ## Features
 
-- **Async HTTP Client**: Built on httpx with retry logic, rate limiting, and exponential backoff
-- **Type Safety**: Full Pydantic v2 models for Users, Organizations, Tickets, Comments, and Help Center
-- **Namespace Pattern**: Clean API organization (`client.users`, `client.tickets`, `client.help_center`)
+- **Type Safety**: Full Pydantic v2 models for all Zendesk entities
+- **Namespace Pattern**: Clean API — `client.users`, `client.tickets`, `client.help_center`
+- **Search**: Raw queries + type-safe SearchQueryConfig, export methods for large datasets
+- **Pagination**: Offset-based and cursor-based (export) with async iterators
+- **Caching**: TTL-based caching for users, organizations, and Help Center
 - **Help Center**: Full CRUD for Categories, Sections, and Articles
-- **Pagination**: Both offset-based and cursor-based pagination support
-- **Search**: Zendesk search API support
-- **Configuration**: Flexible configuration with environment variable support
+- **Async HTTP**: Built on httpx with retry logic, rate limiting, exponential backoff
+- **Configuration**: Environment variables or direct instantiation
 
 ## Installation
 
@@ -80,9 +133,8 @@ async def main():
         ticket = await client.tickets.get(12345)
         print(f"Ticket: {ticket.subject}")
 
-        # Search tickets
-        results = await client.search.tickets("status:open priority:high")
-        for ticket in results:
+        # Search tickets (async iterator with auto-pagination)
+        async for ticket in client.search.tickets("status:open priority:high", limit=10):
             print(f"High priority: {ticket.subject}")
 
 asyncio.run(main())
@@ -117,7 +169,6 @@ config = ZendeskConfig()  # Will load from environment
 user = await client.users.get(user_id)           # Get user by ID
 paginator = await client.users.list()            # List users with pagination
 user = await client.users.by_email(email)        # Get user by email
-users = await client.users.search(query)         # Search users
 users = await client.users.get_many([id1, id2])  # Get multiple users
 ```
 
@@ -125,7 +176,6 @@ users = await client.users.get_many([id1, id2])  # Get multiple users
 ```python
 org = await client.organizations.get(org_id)     # Get organization by ID
 paginator = await client.organizations.list()    # List organizations
-orgs = await client.organizations.search(query)  # Search organizations
 ```
 
 ### Tickets
@@ -134,7 +184,6 @@ ticket = await client.tickets.get(ticket_id)           # Get ticket by ID
 paginator = await client.tickets.list()                # List tickets
 tickets = await client.tickets.for_user(user_id)       # Get user's tickets
 tickets = await client.tickets.for_organization(org_id) # Get org's tickets
-tickets = await client.tickets.search(query)           # Search tickets
 ```
 
 ### Comments (nested under tickets)
@@ -158,6 +207,8 @@ tags = await client.tickets.tags.remove(ticket_id, ["old"]) # Remove tags
 Load tickets with all related data (comments + users) in minimum API requests:
 
 ```python
+from zendesk_sdk import SearchQueryConfig
+
 # Get ticket with all related data
 enriched = await client.tickets.get_enriched(12345)
 
@@ -169,9 +220,15 @@ for comment in enriched.comments:
     author = enriched.get_comment_author(comment)
     print(f"Comment by {author.name}: {comment.body[:50]}...")
 
-# Search with all data loaded
-results = await client.tickets.search_enriched("status:open")
-for item in results:
+# Search with all data loaded (using SearchQueryConfig)
+config = SearchQueryConfig.tickets(
+    status=["open"],
+    priority=["high", "urgent"],
+    organization_id=12345,
+)
+
+# search_enriched returns async iterator
+async for item in client.tickets.search_enriched(config, limit=10):
     print(f"{item.ticket.subject} - {len(item.comments)} comments")
 ```
 
@@ -185,13 +242,120 @@ await client.tickets.comments.add(ticket_id, "See attached", uploads=[token])
 ```
 
 ### Search
+
+All search methods return **async iterators** with automatic pagination.
+
+#### Raw Queries (Zendesk syntax)
+
+Use the same query syntax as in Zendesk UI — it just works:
+
+```python
+# Tickets
+async for ticket in client.search.tickets("status:open priority:high"):
+    print(ticket.subject)
+
+# Users
+async for user in client.search.users("role:admin"):
+    print(user.name)
+
+# Organizations
+async for org in client.search.organizations("tags:enterprise"):
+    print(org.name)
+
+# Collect to list
+all_tickets = [t async for t in client.search.tickets("status:pending", limit=100)]
+
+# Search with enrichment (loads comments + users)
+async for item in client.tickets.search_enriched("status:open", limit=10):
+    print(f"{item.ticket.subject} - {len(item.comments)} comments")
+```
+
+#### SearchQueryConfig (typed alternative)
+
+Don't want to memorize Zendesk query syntax? Use `SearchQueryConfig` — your IDE will autocomplete available fields:
+
 ```python
-paginator = await client.search.all(query)        # General search
-tickets = await client.search.tickets(query)      # Search tickets
-users = await client.search.users(query)          # Search users
-orgs = await client.search.organizations(query)   # Search organizations
+from zendesk_sdk import SearchQueryConfig
+
+config = SearchQueryConfig.tickets(
+    status=["open", "pending"],
+    priority=["high", "urgent"],
+    organization_id=12345,
+    created_after=date(2024, 1, 1),
+    tags=["vip"],
+    exclude_tags=["spam"],
+)
+async for ticket in client.search.tickets(config):
+    print(ticket.subject)
+
+config = SearchQueryConfig.users(
+    role=["admin", "agent"],
+    is_verified=True,
+)
+async for user in client.search.users(config):
+    print(user.name)
+
+config = SearchQueryConfig.organizations(tags=["enterprise"])
+async for org in client.search.organizations(config):
+    print(org.name)
 ```
 
+<details>
+<summary>Available SearchQueryConfig fields</summary>
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | SearchType | TICKET (default), USER, ORGANIZATION |
+| `status` | List[str] | new, open, pending, hold, solved, closed |
+| `priority` | List[str] | low, normal, high, urgent |
+| `ticket_type` | List[str] | question, incident, problem, task |
+| `organization_id` | int | Filter by organization |
+| `requester_id` | int\|"me"\|"none" | Filter by requester |
+| `assignee_id` | int\|"me"\|"none" | Filter by assignee |
+| `group_id` | int | Filter by group |
+| `tags` | List[str] | Include items with tags (OR) |
+| `exclude_tags` | List[str] | Exclude items with tags |
+| `created_after` | date | Created after date |
+| `created_before` | date | Created before date |
+| `updated_after` | date | Updated after date |
+| `updated_before` | date | Updated before date |
+| `via` | List[str] | Channel: email, web, chat, api, phone |
+| `custom_fields` | Dict[int, Any] | Custom field values |
+| `order_by` | str | Sort field |
+| `sort` | str | asc or desc |
+
+</details>
+
+#### Export Search (No Zendesk Limit)
+
+Regular search is capped at 1000 results by Zendesk. Export endpoint has **no such limit**:
+
+```python
+# Export fetches ALL matching entities (no 1000 limit)
+async for ticket in client.search.export_tickets("status:open"):
+    print(ticket.subject)  # Will iterate through ALL open tickets
+
+async for user in client.search.export_users():
+    print(user.name)  # ALL users
+
+async for org in client.search.export_organizations():
+    print(org.name)  # ALL organizations
+
+# Works with SearchQueryConfig too
+config = SearchQueryConfig.tickets(status=["open"], priority=["high"])
+async for ticket in client.search.export_tickets(config):
+    print(ticket.subject)
+
+# With limit if you don't need everything
+async for ticket in client.search.export_tickets("priority:high", limit=500):
+    print(ticket.subject)
+```
+
+| Method | Zendesk Limit | Pagination | Duplicates |
+|--------|---------------|------------|------------|
+| `search.tickets()` | 1000 max | Offset | Possible |
+| `search.export_tickets()` | None | Cursor | None |
+
 ### Help Center
 
 Access Help Center (Guide) via `client.help_center` namespace:
@@ -317,20 +481,81 @@ config = ZendeskConfig(
 )
 ```
 
+## Caching
+
+The SDK includes built-in caching for frequently accessed resources. Caching is enabled by default and can be configured or disabled.
+
+### Default Cache Settings
+
+| Resource | TTL | Max Size |
+|----------|-----|----------|
+| Users | 5 min | 1000 |
+| Organizations | 10 min | 500 |
+| Articles | 15 min | 500 |
+| Categories | 30 min | 200 |
+| Sections | 30 min | 200 |
+
+### Custom Cache Configuration
+
+```python
+from zendesk_sdk import CacheConfig, ZendeskClient, ZendeskConfig
+
+config = ZendeskConfig(
+    subdomain="mycompany",
+    email="user@example.com",
+    token="api_token",
+    cache=CacheConfig(
+        enabled=True,
+        user_ttl=60,           # 1 minute
+        user_maxsize=100,
+        org_ttl=300,           # 5 minutes
+        article_ttl=600,       # 10 minutes
+    )
+)
+```
+
+### Disable Caching
+
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    email="user@example.com",
+    token="api_token",
+    cache=CacheConfig(enabled=False)
+)
+```
+
+### Cache Control
+
+```python
+# Check cache statistics
+info = client.users.get.cache_info()
+print(f"Hits: {info.hits}, Misses: {info.misses}")
+
+# Clear all cached users
+client.users.get.cache_clear()
+
+# Invalidate specific entry
+client.users.get.cache_invalidate(user_id)
+```
+
 ## Examples
 
 See the `examples/` directory for complete usage examples:
 - `basic_usage.py` - Basic configuration and API operations
+- `search.py` - Type-safe search with SearchQueryConfig
 - `pagination_example.py` - Working with paginated results
 - `error_handling.py` - Error handling patterns
 - `enriched_tickets.py` - Loading tickets with related data
 - `help_center.py` - Help Center categories, sections, and articles
+- `caching.py` - Cache configuration and usage
 
 ## Requirements
 
 - Python 3.8+
 - httpx
 - pydantic >=2.0
+- async-lru
 
 ## License