Metadata-Version: 2.4
Name: clickup-async
Version: 0.1.0
Summary: Modern async Python client for ClickUp API with type hints, rate limiting and fluent interface
Home-page: https://github.com/catorch/clickup-async
Author: catorch
Author-email: catorch <catorch@example.com>
License: MIT
Project-URL: Homepage, https://github.com/catorch/clickup-async
Project-URL: Repository, https://github.com/catorch/clickup-async.git
Project-URL: Issues, https://github.com/catorch/clickup-async/issues
Keywords: clickup,api,async,python,httpx,asyncio,task-management,productivity,project-management,pydantic
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ClickUp Async ✨

[![PyPI Version](https://img.shields.io/pypi/v/clickup-async.svg)](https://pypi.org/project/clickup-async/)
[![Python Versions](https://img.shields.io/pypi/pyversions/clickup-async.svg)](https://pypi.org/project/clickup-async/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/clickup-async/month)](https://pepy.tech/project/clickup-async)

A modern, high-performance Python client for the ClickUp API with first-class async support.

## Why Choose ClickUp Async?

| Feature | ClickUp Async | Other Libraries |
|---------|--------------|-----------------|
| **Async Support** | ✅ Full async/await | ❌ Synchronous only |
| **Type Safety** | ✅ Full type hints & validation | ❌ Limited or none |
| **Rate Limiting** | ✅ Intelligent handling | ❌ Basic or none |
| **Fluent Interface** | ✅ Clean, chainable API | ❌ Verbose calls |
| **Modern Python** | ✅ Python 3.9+ features | ❌ Legacy compatibility |
| **Error Handling** | ✅ Comprehensive | ❌ Basic exceptions |
| **Pagination** | ✅ Automatic | ❌ Manual handling |
| **Maintenance** | ✅ Active development | ❌ Limited updates |

## Installation

```bash
pip install clickup-async
```

## Quick Start

```python
import asyncio
from clickup_async import ClickUp, Priority

async def main():
    # Use as a context manager for automatic cleanup
    async with ClickUp(api_token="your_token_here") as client:
        # Get all workspaces
        workspaces = await client.get_workspaces()
        
        # Create a task with fluent interface
        task = await client.list("your_list_id").create_task(
            name="Implement new feature",
            description="Add the awesome new feature",
            priority=Priority.HIGH,
            due_date="next Friday"
        )
        
        print(f"Created task: {task.name} (ID: {task.id})")

if __name__ == "__main__":
    asyncio.run(main())
```

## Key Features

### ⚡ Async First

All API operations use `httpx` for non-blocking I/O, making your applications more efficient and responsive.

```python
# Concurrent API calls
tasks = await asyncio.gather(
    client.get_task("task1"),
    client.get_task("task2"),
    client.get_task("task3")
)
```

### 🔄 Smart Rate Limiting

Automatically handles ClickUp API rate limits with exponential backoff and proactive throttling.

```python
# Configure rate limiting behavior
client = ClickUp(
    api_token="your_token",
    retry_rate_limited_requests=True,  # Auto retry when rate limited
    rate_limit_buffer=5                # Buffer seconds before hitting limits
)
```

### 🔍 Type Safety

Comprehensive type hints for better IDE integration and Pydantic models for runtime validation.

```python
# Full type hints
from clickup_async.models import Task, Workspace, Space

async def process_task(task: Task) -> None:
    # IDE auto-completion works!
    print(f"Task: {task.name}, Status: {task.status.status}")
```

### 📝 Fluent Interface

Intuitive, chainable API design that reflects ClickUp's resource hierarchy.

```python
# Traditional approach
task = await client.get_task("task_id")
comment = await client.create_task_comment(task.id, "Great work!")

# Fluent approach
task = await client.task("task_id").get_task()
comment = await client.task("task_id").create_task_comment("Great work!")
```

## Documentation

For more detailed examples and API documentation, visit our [GitHub repository](https://github.com/catorch/clickup-async).

### Working with Tasks

```python
# Create a task
task = await client.list("list_id").create_task(
    name="New task",
    description="Task description with **markdown** support",
    priority=Priority.HIGH,
    due_date=datetime.now() + timedelta(days=7),
    assignees=["user_id"],
    tags=["feature", "backend"]
)

# Update a task
updated_task = await client.task(task.id).update_task(
    name="Updated task name",
    status="In Progress"
)

# Get tasks with filtering
tasks = await client.list("list_id").get_tasks(
    due_date_gt="today",
    due_date_lt="next week",
    assignees=["user_id"],
    include_closed=False
)
```

### Pagination Handling

```python
# Get first page of tasks
tasks_page = await client.get_tasks(list_id="list_id")

# Process all tasks across all pages
all_tasks = []
while True:
    all_tasks.extend(tasks_page.items)
    if not tasks_page.has_more:
        break
    tasks_page = await tasks_page.next_page()
```

## Development

1. Clone the repository
   ```bash
   git clone https://github.com/catorch/clickup-async.git
   cd clickup-async
   ```

2. Set up a virtual environment
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. Install development dependencies
   ```bash
   pip install -e ".[dev,test]"
   ```

4. Run tests (requires a ClickUp API token in the environment)
   ```bash
   export CLICKUP_API_TOKEN=your_token_here
   pytest
   ```

## License

MIT License - See [LICENSE](LICENSE) for details.

---

⭐ If you find this library helpful, please consider starring it on GitHub!
