Metadata-Version: 2.4
Name: chatapult
Version: 0.1.0
Summary: A fast, Pythonic API wrapper for Google Chat webhooks.
Author-email: Demetrios Lambropoulos <d.lambropoulos@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,async,google chat,notifications,webhook,wrapper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.22.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

![Chatapult Banner](images/banner.png)

# Chatapult

A fast, Pythonic API wrapper for Google Chat webhooks.

Chatapult is designed to make sending automated notifications, CI/CD alerts, and rich UI cards to Google Workspace Spaces effortless. Whether you need a simple synchronous alert or a high-throughput async notification integration, Chatapult handles the boilerplate so you can focus on your application.

![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

## Features

* **Zero Boilerplate:** Send a message to a Google Chat Space in three lines of code.
* **Async Ready:** First-class support for `asyncio`, making it perfect for FastAPI, Discord bots, and high-concurrency event loops.
* **Rich V2 Cards (Coming Soon):** Construct complex Google Chat Cards and Widgets using clean Python objects instead of nested JSON.
* **Threaded Replies:** Easily group related alerts by replying to specific message threads.
* **Fully Typed:** Built with standard Python type hints for excellent IDE autocomplete and static checking.

## Installation

Install via pip:

```bash
pip install chatapult
```

## Quick Start

**Security Note:** Never hardcode your webhook URLs. Always load them securely from environment variables or a secrets manager.

### Synchronous Usage

Perfect for simple scripts, cron jobs, or basic data pipelines.

```python
import os
from chatapult import ChatClient, APIError

webhook_url = os.environ.get("GOOGLE_CHAT_WEBHOOK_URL")

try:
    with ChatClient(webhook_url) as client:
        response = client.send_message("Hello from Chatapult!")
        print("Message sent successfully!")
except APIError as e:
    print(f"Failed to send message: {e}")
```

### Asynchronous Usage

Ideal for web servers, async task queues, or applications where you cannot block the main thread.

```python
import asyncio
import os
from chatapult import AsyncChatClient, NetworkError

async def main():
    webhook_url = os.environ.get("GOOGLE_CHAT_WEBHOOK_URL")

    try:
        async with AsyncChatClient(webhook_url) as client:
            await client.send_message("Hello from the async event loop!")
            print("Async message sent successfully!")
    except NetworkError as e:
        print(f"Network issue encountered: {e}")

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

### Advanced Usage

Documentation for sending V2 Cards, threaded replies, and handling rate-limit exceptions will be added here as features are released.

## Contributing
Contributions are welcome! If you'd like to help improve Chatapult, please review our [Contributing Guidelines](CONTRIBUTING.md) and open an issue or pull request.

## License

This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
