Metadata-Version: 2.1
Name: pg-async-events
Version: 0.1.0
Summary: A simple async event handling library using PostgreSQL notifications.
Home-page: https://github.com/255BITS/pg-async-events
Author: Martyn Garcia
Author-email: martyn@255bits.com
License: MIT
Classifier: Development Status :: 4 - Beta
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asyncpg>=0.24.0

# pg-async-events

A simple asynchronous event handling library using PostgreSQL notifications. This library allows you to subscribe to and publish events using PostgreSQL's `LISTEN/NOTIFY` mechanism in an asynchronous environment.

This is useful in generative AI applications or for situations where other pub/sub systems are overkill.

## Features

- **Asynchronous Event Handling:** Leverage `asyncio` and `asyncpg` to handle events without blocking your main application logic.
- **PostgreSQL Notifications:** Seamlessly integrates with PostgreSQL's `LISTEN/NOTIFY` to provide real-time event notifications.
- **Simple API:** Easy-to-use API for subscribing to channels and notifying events.

## Installation

You can install the package directly from PyPI:

```bash
pip install pg_async_events
```

## Usage

### Quart

```python
import pg_async_events as events

# Add your postgres credentials from the env
db_config = {
    "user": POSTGRES_USER,
    "password": POSTGRES_PASSWORD,
    "host": POSTGRES_HOST,
    "port": POSTGRES_PORT,
    "max_connections": 1,
}

@app.before_serving
async def setup():
    app.task_events = asyncio.create_task(events.server(db_config))

@app.after_serving
async def cleanup():
    app.task_events.cancel()
```


## Notifications

```python
import pg_async_events as events

async def listen_to_events():
    async for message in events.subscribe('your_channel'):
        print('Received:', message)

async def publish_event():
    payload = {'key': 'value'}
    await events.notify('your_channel', payload)
```

## Requirements
- Python 3.8+
- PostgreSQL 9.0+ (with support for LISTEN/NOTIFY)
- asyncpg library

## Author

Built by [255labs.xyz](https://255labs.xyz), the AI product and consulting startup helping people adapt to the AI age with consulting, product, and open-source development.

## Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss the changes.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

## Thanks

* asyncpg for providing the asynchronous PostgreSQL driver.
* PostgreSQL community for their robust database and features like LISTEN/NOTIFY.

