chatapult 0.1.0

A fast, Pythonic API wrapper for Google Chat webhooks.

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.

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:

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.

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.

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 and open an issue or pull request.

License

This project is licensed under the MIT License - see LICENSE for details.