# Ambient Event Bus Client
A Python client library for interacting with the Ambient Labs Event Bus.
## Installation
```bash
pip install ambient-event-bus-client
```
## Quick Start
```python
from ambient_event_bus_client import Client, ClientOptions, MessageCreate
options = ClientOptions(
event_api_url="http://localhost:8000",
connection_service_url="http://localhost:8001",
api_token="your_api_token"
)
client = Client(options)
await client.init_client() # ensure you are in an async context
# Basic subscription
await client.add_subscription(topic="notifications")
# Subscribe and listen for messages
async for message in client.subscribe():
print(f"Received: {message}")
# Publish a basic message
message = MessageCreate(topic="notifications", message="Hello, World!")
await client.publish(message)
```
## Advanced Features
### Aggregate Filtering
Filter messages by resource type and ID:
```python
# Subscribe to all messages for a specific resource type
await client.add_subscription(
topic="resource_updates",
aggregate_type="node"
)
# Subscribe to messages for a specific resource instance
await client.add_subscription(
topic="resource_updates",
aggregate_type="node",
aggregate_id=123
)
# Publish messages with aggregate information
message = MessageCreate(
topic="node_update",
message="Node status changed",
aggregate_type="node",
aggregate_id=123
)
await client.publish(message)
```
### Regex Topic Matching
Use regular expressions for flexible topic matching:
```python
# Match multiple related topics
await client.add_subscription(
topic="user\\.(login|logout|signup)",
is_regex=True
)
# Match all user events
await client.add_subscription(
topic="user\\..*",
is_regex=True
)
```
## API Reference
### Client Methods
#### `add_subscription(topic, aggregate_type=None, aggregate_id=None, is_regex=False)`
Create a new subscription.
**Parameters:**
- `topic` (str): The topic to subscribe to
- `aggregate_type` (str, optional): Filter by resource type
- `aggregate_id` (int, optional): Filter by specific resource ID (requires aggregate_type)
- `is_regex` (bool): Whether to treat topic as a regex pattern (default: False)
**Returns:** `Subscription` object
#### `publish(message)`
Publish a message to the event bus.
**Parameters:**
- `message` (MessageCreate): The message to publish
### Models
#### `MessageCreate`
```python
MessageCreate(
topic: str,
message: str,
aggregate_type: Optional[str] = None,
aggregate_id: Optional[int] = None
)
```
## Development
### Running Tests
```bash
# Install development dependencies
make install-dev
# Run all tests
make test
# Run unit tests only
make test-unit
# Run end-to-end tests
make test-e2e
# Run tests with coverage
make test-cov
```
### Code Quality
```bash
# Run linting
make lint
# Format code
make format
```
## Migration from v1.x
See [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for detailed migration instructions.
### Key Breaking Changes in v2.0.0
- **ID fields changed from `int` to `str` (UUID format)**
- **Topic matching no longer supports glob patterns** - use regex with `is_regex=True`
- New aggregate filtering capabilities
- Enhanced validation for aggregate fields
## License
MIT License
Raw data
{
"_id": null,
"home_page": "https://github.com/ambientlabscomputing/ambient-event-bus-client",
"name": "ambient-event-bus-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Jose Catarino",
"author_email": "jose@ambientlabscomputing.com",
"download_url": "https://files.pythonhosted.org/packages/e7/14/c958883a96dbfa506bacb97f6071122201577af9bb7e7e8f675c0aa1dd48/ambient_event_bus_client-2.2.0.tar.gz",
"platform": null,
"description": "# Ambient Event Bus Client\n\nA Python client library for interacting with the Ambient Labs Event Bus.\n\n## Installation\n\n```bash\npip install ambient-event-bus-client\n```\n\n## Quick Start\n\n```python\nfrom ambient_event_bus_client import Client, ClientOptions, MessageCreate\n\noptions = ClientOptions(\n event_api_url=\"http://localhost:8000\",\n connection_service_url=\"http://localhost:8001\",\n api_token=\"your_api_token\"\n)\nclient = Client(options)\nawait client.init_client() # ensure you are in an async context\n\n# Basic subscription\nawait client.add_subscription(topic=\"notifications\")\n\n# Subscribe and listen for messages\nasync for message in client.subscribe():\n print(f\"Received: {message}\")\n\n# Publish a basic message\nmessage = MessageCreate(topic=\"notifications\", message=\"Hello, World!\")\nawait client.publish(message)\n```\n\n## Advanced Features\n\n### Aggregate Filtering\n\nFilter messages by resource type and ID:\n\n```python\n# Subscribe to all messages for a specific resource type\nawait client.add_subscription(\n topic=\"resource_updates\",\n aggregate_type=\"node\"\n)\n\n# Subscribe to messages for a specific resource instance \nawait client.add_subscription(\n topic=\"resource_updates\",\n aggregate_type=\"node\", \n aggregate_id=123\n)\n\n# Publish messages with aggregate information\nmessage = MessageCreate(\n topic=\"node_update\",\n message=\"Node status changed\",\n aggregate_type=\"node\",\n aggregate_id=123\n)\nawait client.publish(message)\n```\n\n### Regex Topic Matching\n\nUse regular expressions for flexible topic matching:\n\n```python\n# Match multiple related topics\nawait client.add_subscription(\n topic=\"user\\\\.(login|logout|signup)\",\n is_regex=True\n)\n\n# Match all user events\nawait client.add_subscription(\n topic=\"user\\\\..*\",\n is_regex=True \n)\n```\n\n## API Reference\n\n### Client Methods\n\n#### `add_subscription(topic, aggregate_type=None, aggregate_id=None, is_regex=False)`\n\nCreate a new subscription.\n\n**Parameters:**\n- `topic` (str): The topic to subscribe to\n- `aggregate_type` (str, optional): Filter by resource type\n- `aggregate_id` (int, optional): Filter by specific resource ID (requires aggregate_type)\n- `is_regex` (bool): Whether to treat topic as a regex pattern (default: False)\n\n**Returns:** `Subscription` object\n\n#### `publish(message)`\n\nPublish a message to the event bus.\n\n**Parameters:**\n- `message` (MessageCreate): The message to publish\n\n### Models\n\n#### `MessageCreate`\n\n```python\nMessageCreate(\n topic: str,\n message: str,\n aggregate_type: Optional[str] = None,\n aggregate_id: Optional[int] = None\n)\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# Install development dependencies\nmake install-dev\n\n# Run all tests\nmake test\n\n# Run unit tests only\nmake test-unit\n\n# Run end-to-end tests\nmake test-e2e\n\n# Run tests with coverage\nmake test-cov\n```\n\n### Code Quality\n\n```bash\n# Run linting\nmake lint\n\n# Format code\nmake format\n```\n\n## Migration from v1.x\n\nSee [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for detailed migration instructions.\n\n### Key Breaking Changes in v2.0.0\n\n- **ID fields changed from `int` to `str` (UUID format)**\n- **Topic matching no longer supports glob patterns** - use regex with `is_regex=True`\n- New aggregate filtering capabilities\n- Enhanced validation for aggregate fields\n\n## License\n\nMIT License\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A library to interact with the Ambient Labs Event Bus.",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/ambientlabscomputing/ambient-event-bus-client"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e02019f3f8deedfa52eb7f085d4f3fd8ef237d9e317c2bcc257595d2f72dc2fc",
"md5": "b711ab64b45975cf8abc7ac26034bc32",
"sha256": "5103914bda36b9b8cc936d4dec2564d69b85d9e6a9175ddbe49c2243e734a8d6"
},
"downloads": -1,
"filename": "ambient_event_bus_client-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b711ab64b45975cf8abc7ac26034bc32",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10222,
"upload_time": "2025-07-12T01:19:27",
"upload_time_iso_8601": "2025-07-12T01:19:27.776111Z",
"url": "https://files.pythonhosted.org/packages/e0/20/19f3f8deedfa52eb7f085d4f3fd8ef237d9e317c2bcc257595d2f72dc2fc/ambient_event_bus_client-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e714c958883a96dbfa506bacb97f6071122201577af9bb7e7e8f675c0aa1dd48",
"md5": "f73e6fc2a8b344e8a725420d4a38b415",
"sha256": "c5c72d7a53f88db39f87a1b568497296e54ca7d616080d1277550a656eefa4a1"
},
"downloads": -1,
"filename": "ambient_event_bus_client-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f73e6fc2a8b344e8a725420d4a38b415",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9748,
"upload_time": "2025-07-12T01:19:28",
"upload_time_iso_8601": "2025-07-12T01:19:28.913103Z",
"url": "https://files.pythonhosted.org/packages/e7/14/c958883a96dbfa506bacb97f6071122201577af9bb7e7e8f675c0aa1dd48/ambient_event_bus_client-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 01:19:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ambientlabscomputing",
"github_project": "ambient-event-bus-client",
"github_not_found": true,
"lcname": "ambient-event-bus-client"
}
JSON
