chatapult 0.1.0__py3-none-any.whl

chatapult/__init__.py

@@ -0,0 +1,28 @@
+"""
+Chatapult: A fast, Pythonic API wrapper for Google Chat webhooks.
+"""
+
+# Explicitly define the version so developers can check it programmatically
+__version__ = "0.1.0"
+
+# Import the core components to expose them at the top level of the package
+from .client import ChatClient
+from .async_client import AsyncChatClient
+from .exceptions import (
+    APIError,
+    ChatapultError,
+    ConfigurationError,
+    NetworkError,
+)
+
+# The __all__ list strictly defines the public API of your module.
+# It tells IDEs and linters exactly what is safe for end-users to import,
+# and hides internal modules (like 'logging' or 'httpx') from autocomplete.
+__all__ = [
+    "APIError",
+    "AsyncChatClient",
+    "ChatClient",
+    "ChatapultError",
+    "ConfigurationError",
+    "NetworkError",
+]

chatapult/async_client.py

@@ -0,0 +1,82 @@
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .exceptions import APIError, ConfigurationError, NetworkError
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncChatClient:
+    """
+    An asynchronous client for interacting with Google Chat Webhooks.
+    """
+
+    def __init__(self, webhook_url: str, timeout: float = 10.0) -> None:
+        """
+        Initialize the AsyncChatClient.
+
+        Args:
+            webhook_url (str): The full Google Chat webhook URL.
+            timeout (float): Connection timeout in seconds. Defaults to 10.0.
+
+        Raises:
+            ConfigurationError: If the webhook_url is empty.
+        """
+        if not webhook_url:
+            raise ConfigurationError("A valid webhook_url must be provided.")
+
+        self.webhook_url = webhook_url
+        self._client = httpx.AsyncClient(timeout=timeout)
+
+    async def send_message(
+        self, text: str, thread_name: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Asynchronously send a simple text message to the Google Chat Space.
+
+        Args:
+            text (str): The markdown-formatted text to send.
+            thread_name (Optional[str]): The ID of an existing thread to reply to.
+
+        Returns:
+            Dict[str, Any]: The JSON response from the Google Chat API.
+
+        Raises:
+            APIError: If the Google API returns a non-200 status code.
+            NetworkError: If the connection times out or fails.
+        """
+        payload: Dict[str, Any] = {"text": text}
+
+        if thread_name:
+            payload["thread"] = {"name": thread_name}
+
+        try:
+            response = await self._client.post(self.webhook_url, json=payload)
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            logger.error(
+                f"Google Chat API error: {e.response.status_code} - {e.response.text}"
+            )
+            raise APIError(
+                message=f"API request failed: {e.response.text}",
+                status_code=e.response.status_code,
+            ) from e
+        except httpx.RequestError as e:
+            logger.error(f"Network error while connecting to Google Chat: {e}")
+            raise NetworkError(f"Network request failed: {str(e)}") from e
+
+    async def aclose(self) -> None:
+        """Close the underlying asynchronous HTTP client connections."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncChatClient":
+        """Enable usage as an asynchronous context manager."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Ensure connections are closed when exiting the context manager."""
+        await self.aclose()

chatapult/client.py

@@ -0,0 +1,85 @@
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+# Import our new custom exceptions
+from .exceptions import APIError, ConfigurationError, NetworkError
+
+logger = logging.getLogger(__name__)
+
+
+class ChatClient:
+    """
+    A synchronous client for interacting with Google Chat Webhooks.
+    """
+
+    def __init__(self, webhook_url: str, timeout: float = 10.0) -> None:
+        """
+        Initialize the ChatClient.
+
+        Args:
+            webhook_url (str): The full Google Chat webhook URL.
+            timeout (float): Connection timeout in seconds. Defaults to 10.0.
+
+        Raises:
+            ConfigurationError: If the webhook_url is empty or invalid.
+        """
+        if not webhook_url:
+            raise ConfigurationError("A valid webhook_url must be provided.")
+
+        self.webhook_url = webhook_url
+        self._client = httpx.Client(timeout=timeout)
+
+    def send_message(
+        self, text: str, thread_name: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Send a simple text message to the configured Google Chat Space.
+
+        Args:
+            text (str): The markdown-formatted text to send.
+            thread_name (Optional[str]): The ID of an existing thread to reply to
+                                         (e.g., 'spaces/SPACE_ID/threads/THREAD_ID').
+
+        Returns:
+            Dict[str, Any]: The JSON response from the Google Chat API representing the message.
+
+        Raises:
+            APIError: If the Google API returns a non-200 status code.
+            NetworkError: If the network connection times out or fails.
+        """
+        payload: Dict[str, Any] = {"text": text}
+
+        if thread_name:
+            payload["thread"] = {"name": thread_name}
+
+        try:
+            response = self._client.post(self.webhook_url, json=payload)
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            logger.error(
+                f"Google Chat API error: {e.response.status_code} - {e.response.text}"
+            )
+            raise APIError(
+                message=f"API request failed: {e.response.text}",
+                status_code=e.response.status_code,
+            ) from e
+
+        except httpx.RequestError as e:
+            logger.error(f"Network error while connecting to Google Chat: {e}")
+            raise NetworkError(f"Network request failed: {str(e)}") from e
+
+    def close(self) -> None:
+        """Close the underlying HTTP client connections."""
+        self._client.close()
+
+    def __enter__(self) -> "ChatClient":
+        """Enable usage as a context manager."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Ensure connections are closed when exiting the context manager."""
+        self.close()

chatapult/exceptions.py

@@ -0,0 +1,39 @@
+"""
+Custom exceptions for the Chatapult library.
+"""
+
+
+class ChatapultError(Exception):
+    """
+    Base exception class for all Chatapult errors.
+    All other custom exceptions in this library inherit from this base class,
+    allowing users to catch any Chatapult-related error with a single except block.
+    """
+
+    pass
+
+
+class ConfigurationError(ChatapultError):
+    """
+    Raised when there is a configuration issue, such as an empty or invalid webhook URL.
+    """
+
+    pass
+
+
+class APIError(ChatapultError):
+    """
+    Raised when the Google Chat API returns an HTTP error response (e.g., 400 or 404).
+    """
+
+    def __init__(self, message: str, status_code: int) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class NetworkError(ChatapultError):
+    """
+    Raised when a network connection fails, times out, or the host is unreachable.
+    """
+
+    pass

chatapult-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+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.

chatapult-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+chatapult/__init__.py,sha256=15l6_leVRYapJfm2Ap4VDMycnG7jvcjoPFo1eez3l7Q,784
+chatapult/async_client.py,sha256=fxRmPOas-nz4LTpPTcEwMaCfi-L9bs4F7LnYrPPsJhI,2777
+chatapult/client.py,sha256=KQZDLOI7iD7Tdyxce6PEtOs4MWSwdkkTFY02ptridnM,2842
+chatapult/exceptions.py,sha256=NEzZq02YvzHtPaHNrenjALrVem_Nk96Lr-9JoZNVir0,908
+chatapult/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chatapult-0.1.0.dist-info/METADATA,sha256=kQ8NCD1BDQRuUTxkwDKQeLqQZU7OKvccG--psX9oqWk,4273
+chatapult-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+chatapult-0.1.0.dist-info/licenses/LICENSE,sha256=YKs-BeMD4E_SIN9dxk98anfj7ccELurtRG34m7IzvTM,1079
+chatapult-0.1.0.dist-info/RECORD,,

chatapult-0.1.0.dist-info/WHEEL

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

chatapult-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Demetrios Lambropoulos
+
+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.