# Antonnia Events
Python SDK for Antonnia Events and Webhooks
## Overview
The `antonnia-events` package provides type-safe event definitions for Antonnia webhook events. It's part of the Antonnia Python SDK ecosystem and works seamlessly with other Antonnia packages.
## Installation
```bash
pip install antonnia-events
```
Note: This package has a dependency on `antonnia-conversations` for the underlying data types.
## Quick Start
```python
from antonnia.events import Event, MessageCreated, SessionCreated
# Parse webhook events
def handle_webhook(event_data: dict):
event = Event.model_validate(event_data)
if isinstance(event, MessageCreated):
print(f"New message: {event.data.object.id}")
elif isinstance(event, SessionCreated):
print(f"New session: {event.data.object.id}")
```
## Event Types
### Available Events
- `MessageCreated` - Fired when a new message is created
- `SessionCreated` - Fired when a new session is created
- `SessionFinished` - Fired when a session is finished
- `SessionTransferred` - Fired when a session is transferred
### Event Structure
All events inherit from `EventBase` and have this structure:
```python
{
"id": "event_123",
"created_at": "2023-12-01T12:00:00Z",
"type": "message.created",
"data": {
"object": {
# The actual Message or Session object
}
}
}
```
## Usage with Frameworks
### FastAPI
```python
from fastapi import FastAPI
from antonnia.events import Event
app = FastAPI()
@app.post("/webhook")
async def handle_webhook(event: Event):
# Event is automatically validated and parsed
return {"status": "received"}
```
### Flask
```python
from flask import Flask, request
from antonnia.events import Event
app = Flask(__name__)
@app.route("/webhook", methods=["POST"])
def handle_webhook():
event = Event.model_validate(request.json)
# Handle the event
return {"status": "received"}
```
## Type Safety
The package provides full type safety with discriminated unions:
```python
from antonnia.events import Event, MessageCreated
def process_event(event: Event):
# Type checker knows the event type based on isinstance check
if isinstance(event, MessageCreated):
# event.data.object is typed as Message
message = event.data.object
print(f"Message content: {message.content}")
```
## Development
### Installing for Development
```bash
pip install -e .[dev]
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black .
isort .
```
### Type Checking
```bash
mypy .
```
## License
MIT License - see LICENSE file for details.
## Related Packages
- [`antonnia-conversations`](https://pypi.org/project/antonnia-conversations/) - Conversations API client
- More Antonnia packages coming soon!
## Support
For support, please visit [https://antonnia.com/support](https://antonnia.com/support) or create an issue in our GitHub repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/antonnia/antonnia-python",
"name": "antonnia-events",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Antonnia <support@antonnia.com>",
"keywords": "antonnia, events, webhooks, api, sdk",
"author": "Antonnia",
"author_email": "Antonnia <support@antonnia.com>",
"download_url": "https://files.pythonhosted.org/packages/73/a7/4ba9cd162271f6e41cb9265dc3acf6842418a862a82d4f93b4ab1195ae67/antonnia_events-1.0.3.tar.gz",
"platform": null,
"description": "# Antonnia Events\n\nPython SDK for Antonnia Events and Webhooks\n\n## Overview\n\nThe `antonnia-events` package provides type-safe event definitions for Antonnia webhook events. It's part of the Antonnia Python SDK ecosystem and works seamlessly with other Antonnia packages.\n\n## Installation\n\n```bash\npip install antonnia-events\n```\n\nNote: This package has a dependency on `antonnia-conversations` for the underlying data types.\n\n## Quick Start\n\n```python\nfrom antonnia.events import Event, MessageCreated, SessionCreated\n\n# Parse webhook events\ndef handle_webhook(event_data: dict):\n event = Event.model_validate(event_data)\n \n if isinstance(event, MessageCreated):\n print(f\"New message: {event.data.object.id}\")\n elif isinstance(event, SessionCreated):\n print(f\"New session: {event.data.object.id}\")\n```\n\n## Event Types\n\n### Available Events\n\n- `MessageCreated` - Fired when a new message is created\n- `SessionCreated` - Fired when a new session is created \n- `SessionFinished` - Fired when a session is finished\n- `SessionTransferred` - Fired when a session is transferred\n\n### Event Structure\n\nAll events inherit from `EventBase` and have this structure:\n\n```python\n{\n \"id\": \"event_123\",\n \"created_at\": \"2023-12-01T12:00:00Z\",\n \"type\": \"message.created\",\n \"data\": {\n \"object\": {\n # The actual Message or Session object\n }\n }\n}\n```\n\n## Usage with Frameworks\n\n### FastAPI\n\n```python\nfrom fastapi import FastAPI\nfrom antonnia.events import Event\n\napp = FastAPI()\n\n@app.post(\"/webhook\")\nasync def handle_webhook(event: Event):\n # Event is automatically validated and parsed\n return {\"status\": \"received\"}\n```\n\n### Flask\n\n```python\nfrom flask import Flask, request\nfrom antonnia.events import Event\n\napp = Flask(__name__)\n\n@app.route(\"/webhook\", methods=[\"POST\"])\ndef handle_webhook():\n event = Event.model_validate(request.json)\n # Handle the event\n return {\"status\": \"received\"}\n```\n\n## Type Safety\n\nThe package provides full type safety with discriminated unions:\n\n```python\nfrom antonnia.events import Event, MessageCreated\n\ndef process_event(event: Event):\n # Type checker knows the event type based on isinstance check\n if isinstance(event, MessageCreated):\n # event.data.object is typed as Message\n message = event.data.object\n print(f\"Message content: {message.content}\")\n```\n\n## Development\n\n### Installing for Development\n\n```bash\npip install -e .[dev]\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack .\nisort .\n```\n\n### Type Checking\n\n```bash\nmypy .\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Related Packages\n\n- [`antonnia-conversations`](https://pypi.org/project/antonnia-conversations/) - Conversations API client\n- More Antonnia packages coming soon!\n\n## Support\n\nFor support, please visit [https://antonnia.com/support](https://antonnia.com/support) or create an issue in our GitHub repository. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Antonnia Events and Webhooks",
"version": "1.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/antonnia/antonnia-python/issues",
"Documentation": "https://docs.antonnia.com/events",
"Homepage": "https://antonnia.com",
"Repository": "https://github.com/antonnia/antonnia-python"
},
"split_keywords": [
"antonnia",
" events",
" webhooks",
" api",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42432ccc684abdd44229fc680fbcccb246a103f0fdbbf5114c3f36d5d303f650",
"md5": "eb0857f35e826f60a4c351c64098805b",
"sha256": "9476c26ec496606784fa54d0b13376b7f93e1adf77a16bbce99ede19bfa1ea71"
},
"downloads": -1,
"filename": "antonnia_events-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb0857f35e826f60a4c351c64098805b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8338,
"upload_time": "2025-08-16T21:04:10",
"upload_time_iso_8601": "2025-08-16T21:04:10.414994Z",
"url": "https://files.pythonhosted.org/packages/42/43/2ccc684abdd44229fc680fbcccb246a103f0fdbbf5114c3f36d5d303f650/antonnia_events-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73a74ba9cd162271f6e41cb9265dc3acf6842418a862a82d4f93b4ab1195ae67",
"md5": "6606c206eff70fb6c35653eaff793e67",
"sha256": "71ba19616441621c3ef435c8c83522750daec02977733166ee35cd560460028e"
},
"downloads": -1,
"filename": "antonnia_events-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "6606c206eff70fb6c35653eaff793e67",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7766,
"upload_time": "2025-08-16T21:04:11",
"upload_time_iso_8601": "2025-08-16T21:04:11.489239Z",
"url": "https://files.pythonhosted.org/packages/73/a7/4ba9cd162271f6e41cb9265dc3acf6842418a862a82d4f93b4ab1195ae67/antonnia_events-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 21:04:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "antonnia",
"github_project": "antonnia-python",
"github_not_found": true,
"lcname": "antonnia-events"
}
JSON
