python-zendesk-sdk 0.1.0__py3-none-any.whl

python_zendesk_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: python-zendesk-sdk
+Version: 0.1.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
+Project-URL: Issues, https://github.com/bormog/python-zendesk-sdk/issues
+Author: bormog
+License: MIT
+License-File: LICENSE
+Keywords: api,client,sdk,zendesk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+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: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Python Zendesk SDK
+
+Modern Python SDK for Zendesk API with async support, full type safety, and comprehensive error handling.
+
+## Status: Ready for Read-Only Operations ✅
+
+This project has completed iterations 1-4 and is ready for production use in read-only mode.
+
+### Completed Features ✅
+
+- **Project Infrastructure**: Complete setup with `pyproject.toml`, dependencies, and linting
+- **Configuration System**: `ZendeskConfig` with environment variable support and validation
+- **Exception Handling**: Comprehensive exception hierarchy for different error types
+- **HTTP Client**: Async HTTP client with retry logic, rate limiting, and exponential backoff
+- **Pagination**: Both offset-based and cursor-based pagination support
+- **Data Models**: Full Pydantic v2 models for Users, Organizations, Tickets, and Comments
+- **Read API Methods**: 13 methods for reading data from Zendesk
+  - Users: `get_users()`, `get_user()`, `get_user_by_email()`
+  - Organizations: `get_organizations()`, `get_organization()`
+  - Tickets: `get_tickets()`, `get_ticket()`, `get_user_tickets()`, `get_organization_tickets()`
+  - Comments: `get_ticket_comments()`
+  - Search: `search()`, `search_users()`, `search_tickets()`, `search_organizations()`
+- **Testing Framework**: Full test suite with 128+ passing tests
+- **Code Quality**: Black, isort, flake8, and mypy configured
+
+### In Development 🚧
+
+- Write operations (create/update/delete) - planned for future iteration
+- Documentation & Examples (Iteration 5)
+
+## Installation
+
+```bash
+# Install from PyPI (when published)
+pip install python-zendesk-sdk
+
+# Or install from source
+git clone <repository-url>
+cd python-zendesk-sdk
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+import asyncio
+from zendesk_sdk import ZendeskClient, ZendeskConfig
+
+async def main():
+    # Create configuration
+    config = ZendeskConfig(
+        subdomain="your-subdomain",
+        email="your-email@example.com",
+        token="your-api-token",  # or use password="your-password"
+    )
+
+    # Use async context manager
+    async with ZendeskClient(config) as client:
+        # Get users with pagination
+        users_paginator = await client.get_users(per_page=10)
+        users = await users_paginator.get_page()
+
+        for user in users:
+            print(f"User: {user.name} ({user.email})")
+
+        # Get specific ticket
+        ticket = await client.get_ticket(ticket_id=12345)
+        print(f"Ticket: {ticket.subject}")
+
+        # Search tickets
+        results = await client.search_tickets("status:open priority:high")
+        for ticket in results:
+            print(f"High priority: {ticket.subject}")
+
+asyncio.run(main())
+```
+
+## Configuration
+
+The SDK supports multiple ways to configure authentication:
+
+### 1. Direct instantiation
+```python
+config = ZendeskConfig(
+    subdomain="mycompany",
+    email="user@example.com",
+    token="api_token_here"
+)
+```
+
+### 2. Environment variables
+```bash
+export ZENDESK_SUBDOMAIN=mycompany
+export ZENDESK_EMAIL=user@example.com
+export ZENDESK_TOKEN=api_token_here
+```
+
+```python
+config = ZendeskConfig()  # Will load from environment
+```
+
+### 3. Mixed approach
+```python
+# Override specific values, rest from environment
+config = ZendeskConfig(subdomain="different-subdomain")
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src/zendesk_sdk --cov-report=html
+
+# Run specific test file
+pytest tests/test_config.py -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+python -m black src tests
+python -m isort src tests
+
+# Lint code
+python -m flake8 src tests
+
+# Type checking
+python -m mypy src
+```
+
+### Running All Checks
+
+```bash
+# Format, lint, and test
+python -m black src tests && python -m isort src tests && python -m flake8 src tests && python -m mypy src && pytest
+```
+
+## Project Structure
+
+```
+├── src/zendesk_sdk/          # Main package
+│   ├── __init__.py           # Public API exports
+│   ├── client.py             # Main ZendeskClient class
+│   ├── config.py             # Configuration management
+│   ├── exceptions.py         # Exception hierarchy
+│   └── models/               # Data models
+│       ├── __init__.py
+│       └── base.py           # Base model class
+├── tests/                    # Test suite
+├── pyproject.toml            # Project configuration
+└── README.md                 # This file
+```
+
+## Requirements
+
+- Python 3.8+
+- httpx (for async HTTP client)
+- pydantic >=2.0 (for data validation)
+
+## Development Roadmap
+
+- [x] **Iteration 1**: Infrastructure Setup
+- [x] **Iteration 2**: HTTP Client & Pagination
+- [x] **Iteration 3**: Data Models (Users, Tickets, Organizations, Comments)
+- [x] **Iteration 4**: Read-Only API Methods & Search
+- [ ] **Iteration 5**: Documentation & Examples (in progress)
+- [ ] **Future**: Write operations (create/update/delete)
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+This project is currently in early development. Contribution guidelines will be added in future iterations.

python_zendesk_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+zendesk_sdk/__init__.py,sha256=xxTf8ePsDZwIlHs_obXSXOnvu9m8kz60SaBR9ElIzJQ,641
+zendesk_sdk/client.py,sha256=n4xAexkX_VDXJ1x7VkO7L-3pdBNB5OJIb_i5D7hq3oE,10432
+zendesk_sdk/config.py,sha256=2GT0LcW6u3oALy9gMhJ1_fk2l_p1PJgitGij-13YmOY,3833
+zendesk_sdk/exceptions.py,sha256=ByzdL68EQZaP6BY5ukWfr8Myhr11PpEm4Xy0FgBwHJ4,5672
+zendesk_sdk/http_client.py,sha256=n41KJ0fCYLGbCkEw1uNLmD7XpHweNxwdSSXR9Q0ehnk,9696
+zendesk_sdk/pagination.py,sha256=9bm7x0-N0gM-Y0FjPGK6szxwsRZOdKQzxb4Ii68BMhs,10815
+zendesk_sdk/models/__init__.py,sha256=xxRGGZgyelMKHK53lSyFWiqmrxDTk8OSPa_eWH8zbQM,894
+zendesk_sdk/models/base.py,sha256=SMLcNW2lHOpuOn0DUB3CPQ7lIjPGtcwA85cC604iIMI,1686
+zendesk_sdk/models/comment.py,sha256=us1vaH7bRYET3ChoJdUhbKXJfwb0jjqLC3t2h-PUwtE,3474
+zendesk_sdk/models/organization.py,sha256=fZL3Sg4pOo3k6CynbqcVFT2jZKLG0BPyplnb4tpuovw,3970
+zendesk_sdk/models/ticket.py,sha256=okCBCghhFhDCOtDAXa5q-cM3w8aI61fEY8NgHt1fD3c,11496
+zendesk_sdk/models/user.py,sha256=jUxorGLVFb1dizFH167H7Q3S_PAkuh6z-Lh2i25beoM,7694
+python_zendesk_sdk-0.1.0.dist-info/METADATA,sha256=AxjvMwXNwxzO3uz9bxx41ErBClbC5u59GnlPw-Ez948,6624
+python_zendesk_sdk-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_zendesk_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=JwtuUB9xpnmbUUkeC96rIL5z7MOicj9zULISh1-_1Dg,1063
+python_zendesk_sdk-0.1.0.dist-info/RECORD,,

python_zendesk_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_zendesk_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bormog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zendesk_sdk/__init__.py

@@ -0,0 +1,28 @@
+"""
+Modern Python SDK for Zendesk API.
+
+This package provides a clean, async-first interface to the Zendesk API
+with full type safety and comprehensive error handling.
+"""
+
+__version__ = "0.1.0"
+
+from .client import ZendeskClient
+from .config import ZendeskConfig
+from .exceptions import (
+    ZendeskAuthException,
+    ZendeskBaseException,
+    ZendeskHTTPException,
+    ZendeskPaginationException,
+    ZendeskRateLimitException,
+)
+
+__all__ = [
+    "ZendeskClient",
+    "ZendeskConfig",
+    "ZendeskBaseException",
+    "ZendeskHTTPException",
+    "ZendeskAuthException",
+    "ZendeskRateLimitException",
+    "ZendeskPaginationException",
+]

zendesk_sdk/client.py

@@ -0,0 +1,321 @@
+"""Main Zendesk API client."""
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from .config import ZendeskConfig
+from .http_client import HTTPClient
+from .models import Comment, Organization, Ticket, User
+from .pagination import ZendeskPaginator
+
+if TYPE_CHECKING:
+    from .pagination import Paginator
+
+
+class ZendeskClient:
+    """Main client for interacting with the Zendesk API.
+
+    This client provides a unified interface to all Zendesk API resources
+    including users, tickets, organizations, and search functionality.
+    """
+
+    def __init__(self, config: ZendeskConfig) -> None:
+        """Initialize the Zendesk client.
+
+        Args:
+            config: Zendesk configuration object containing authentication
+                   and connection settings.
+        """
+        self.config = config
+        self._http_client: Optional[HTTPClient] = None
+
+    def __repr__(self) -> str:
+        """String representation of the client."""
+        return f"ZendeskClient(subdomain='{self.config.subdomain}')"
+
+    @property
+    def http_client(self) -> HTTPClient:
+        """Get or create HTTP client instance."""
+        if self._http_client is None:
+            self._http_client = HTTPClient(self.config)
+        return self._http_client
+
+    async def get(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        max_retries: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Make GET request to Zendesk API.
+
+        Args:
+            path: API endpoint path (e.g., 'users.json')
+            params: Query parameters
+            max_retries: Override default retry count
+
+        Returns:
+            JSON response from API
+        """
+        return await self.http_client.get(path, params=params, max_retries=max_retries)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        max_retries: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Make POST request to Zendesk API.
+
+        Args:
+            path: API endpoint path (e.g., 'users.json')
+            json: Request body data
+            max_retries: Override default retry count
+
+        Returns:
+            JSON response from API
+        """
+        return await self.http_client.post(path, json=json, max_retries=max_retries)
+
+    async def put(
+        self,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        max_retries: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Make PUT request to Zendesk API.
+
+        Args:
+            path: API endpoint path (e.g., 'users/123.json')
+            json: Request body data
+            max_retries: Override default retry count
+
+        Returns:
+            JSON response from API
+        """
+        return await self.http_client.put(path, json=json, max_retries=max_retries)
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        max_retries: Optional[int] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Make DELETE request to Zendesk API.
+
+        Args:
+            path: API endpoint path (e.g., 'users/123.json')
+            max_retries: Override default retry count
+
+        Returns:
+            JSON response from API if any, None for empty responses
+        """
+        return await self.http_client.delete(path, max_retries=max_retries)
+
+    async def close(self) -> None:
+        """Close HTTP client and cleanup resources."""
+        if self._http_client:
+            await self._http_client.close()
+
+    async def __aenter__(self) -> "ZendeskClient":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
+        """Async context manager exit."""
+        await self.close()
+
+    # Users API methods
+
+    async def get_users(self, per_page: int = 100) -> "Paginator[Dict[str, Any]]":
+        """Get paginated list of users.
+
+        Args:
+            per_page: Number of users per page (max 100)
+
+        Returns:
+            Paginator for iterating through all users
+        """
+        paginator = ZendeskPaginator.create_users_paginator(self.http_client, per_page=per_page)
+        return paginator
+
+    async def get_user(self, user_id: int) -> User:
+        """Get a specific user by ID.
+
+        Args:
+            user_id: The user's ID
+
+        Returns:
+            User object
+        """
+        response = await self.get(f"users/{user_id}.json")
+        return User(**response["user"])
+
+    async def get_user_by_email(self, email: str) -> Optional[User]:
+        """Get a user by email address.
+
+        Args:
+            email: The user's email address
+
+        Returns:
+            User object if found, None otherwise
+        """
+        response = await self.get("users/search.json", params={"query": email})
+        users = response.get("users", [])
+        if users:
+            return User(**users[0])
+        return None
+
+    # Organizations API methods
+
+    async def get_organizations(self, per_page: int = 100) -> "Paginator[Dict[str, Any]]":
+        """Get paginated list of organizations.
+
+        Args:
+            per_page: Number of organizations per page (max 100)
+
+        Returns:
+            Paginator for iterating through all organizations
+        """
+        paginator = ZendeskPaginator.create_organizations_paginator(self.http_client, per_page=per_page)
+        return paginator
+
+    async def get_organization(self, org_id: int) -> Organization:
+        """Get a specific organization by ID.
+
+        Args:
+            org_id: The organization's ID
+
+        Returns:
+            Organization object
+        """
+        response = await self.get(f"organizations/{org_id}.json")
+        return Organization(**response["organization"])
+
+    # Tickets API methods
+
+    async def get_tickets(self, per_page: int = 100) -> "Paginator[Dict[str, Any]]":
+        """Get paginated list of tickets.
+
+        Args:
+            per_page: Number of tickets per page (max 100)
+
+        Returns:
+            Paginator for iterating through all tickets
+        """
+        paginator = ZendeskPaginator.create_tickets_paginator(self.http_client, per_page=per_page)
+        return paginator
+
+    async def get_ticket(self, ticket_id: int) -> Ticket:
+        """Get a specific ticket by ID.
+
+        Args:
+            ticket_id: The ticket's ID
+
+        Returns:
+            Ticket object
+        """
+        response = await self.get(f"tickets/{ticket_id}.json")
+        return Ticket(**response["ticket"])
+
+    async def get_user_tickets(self, user_id: int, per_page: int = 100) -> List[Ticket]:
+        """Get tickets requested by a specific user.
+
+        Args:
+            user_id: The user's ID
+            per_page: Number of tickets per page (max 100)
+
+        Returns:
+            List of Ticket objects
+        """
+        response = await self.get(f"users/{user_id}/tickets/requested.json", params={"per_page": per_page})
+        return [Ticket(**ticket_data) for ticket_data in response.get("tickets", [])]
+
+    async def get_organization_tickets(self, org_id: int, per_page: int = 100) -> List[Ticket]:
+        """Get tickets for a specific organization.
+
+        Args:
+            org_id: The organization's ID
+            per_page: Number of tickets per page (max 100)
+
+        Returns:
+            List of Ticket objects
+        """
+        response = await self.get(f"organizations/{org_id}/tickets.json", params={"per_page": per_page})
+        return [Ticket(**ticket_data) for ticket_data in response.get("tickets", [])]
+
+    # Comments API methods
+
+    async def get_ticket_comments(self, ticket_id: int, per_page: int = 100) -> List[Comment]:
+        """Get comments for a specific ticket.
+
+        Args:
+            ticket_id: The ticket's ID
+            per_page: Number of comments per page (max 100)
+
+        Returns:
+            List of Comment objects
+        """
+        response = await self.get(f"tickets/{ticket_id}/comments.json", params={"per_page": per_page})
+        return [Comment(**comment_data) for comment_data in response.get("comments", [])]
+
+    # Search API methods
+
+    async def search(self, query: str, per_page: int = 100) -> "Paginator[Dict[str, Any]]":
+        """Search across all Zendesk resources.
+
+        Args:
+            query: Search query string
+            per_page: Number of results per page (max 100)
+
+        Returns:
+            Paginator for iterating through search results
+        """
+        paginator = ZendeskPaginator.create_search_paginator(self.http_client, query=query, per_page=per_page)
+        return paginator
+
+    async def search_users(self, query: str, per_page: int = 100) -> List[User]:
+        """Search for users.
+
+        Args:
+            query: Search query string
+            per_page: Number of results per page (max 100)
+
+        Returns:
+            List of User objects
+        """
+        full_query = f"type:user {query}"
+        response = await self.get("search.json", params={"query": full_query, "per_page": per_page})
+        results = response.get("results", [])
+        return [User(**result) for result in results if result.get("result_type") == "user"]
+
+    async def search_tickets(self, query: str, per_page: int = 100) -> List[Ticket]:
+        """Search for tickets.
+
+        Args:
+            query: Search query string
+            per_page: Number of results per page (max 100)
+
+        Returns:
+            List of Ticket objects
+        """
+        full_query = f"type:ticket {query}"
+        response = await self.get("search.json", params={"query": full_query, "per_page": per_page})
+        results = response.get("results", [])
+        return [Ticket(**result) for result in results if result.get("result_type") == "ticket"]
+
+    async def search_organizations(self, query: str, per_page: int = 100) -> List[Organization]:
+        """Search for organizations.
+
+        Args:
+            query: Search query string
+            per_page: Number of results per page (max 100)
+
+        Returns:
+            List of Organization objects
+        """
+        full_query = f"type:organization {query}"
+        response = await self.get("search.json", params={"query": full_query, "per_page": per_page})
+        results = response.get("results", [])
+        return [Organization(**result) for result in results if result.get("result_type") == "organization"]