# py-pg-notify
[](https://pepy.tech/projects/py-pg-notify)
**py-pg-notify** is a Python library that simplifies listening to and sending notifications using PostgreSQL. This package leverages `asyncpg` for asynchronous communication with the database, making it ideal for real-time applications.
---
## 📖 Features
- 🔊 **PostgreSQL Notifications**: Easy-to-use interfaces for `PostgreSQL` notifications.
- 🔄 **Asynchronous**: Fully asynchronous with support for multiple listeners and channels.
- 📦 **Lightweight**: Built on top of `asyncpg`, offering high performance.
- ⚙️ **Custom Handlers**: Define your notification handling logic dynamically.
---
## 🚀 Installation
Install the package via pip:
```bash
pip install py-pg-notify
```
---
## Usage
### Configuration Example
You can use `PGConfig` to manage PostgreSQL connection parameters via a dictionary, environment variables, or direct parameters.
```python
from py_pg_notify import PGConfig
# Example using keyword args
kwargs = {
"user": "<username>",
"password": "<password>",
"host": "<host>",
"port": 5432,
"dbname": "<dbname>"
}
config = PGConfig(**kwargs)
# Example using environment variables
# Ensure PG_USER, PG_PASSWORD, PG_HOST, PG_PORT, and PG_DBNAME are set in your environment
config = PGConfig()
# Example using direct parameters
config = PGConfig(user="<username>", password="<password>", host="<host>", port=5432, dbname="<dbname>")
```
### Notifier Example
```python
import asyncio
from py_pg_notify import Notifier, PGConfig
async def create_trigger_example():
# Define the configuration using environment variables
config = PGConfig()
async with Notifier(config) as notifier:
# Send a custom message to 'ch_01' channel
await notifier.notify("ch_01", "message")
# Set up a trigger to notify 'ch_01' when the table is modified
await notifier.create_trigger_function("notify_function", "ch_01")
await notifier.create_trigger(
table_name="my_table",
trigger_name="my_trigger",
function_name="notify_function",
event="INSERT",
)
trigger_functions = await notifier.get_trigger_functions("my_table")
print("Existing Trigger Functions:", trigger_functions)
triggers = await notifier.get_triggers("my_table")
print("Existing Triggers:", triggers)
await notifier.remove_trigger("my_table", "my_trigger")
await notifier.remove_trigger_function("notify_function")
if __name__ == "__main__":
asyncio.run(create_trigger_example())
```
### Listener Example
```python
import asyncio
from py_pg_notify import Listener, PGConfig, Notification
async def notification_handler(msg: Notification):
# Perform any processing on the received notification
print(f"Notification received: Channel={msg.channel}, Payload={msg.payload}")
async def main():
# Define the configuration using environment variables
config = PGConfig()
async with Listener(config) as listener:
await listener.add_listener("ch_01", notification_handler)
await asyncio.sleep(3600) # Simulate long-running process
if __name__ == "__main__":
try:
asyncio.run(main())
except KeyboardInterrupt:
exit(0)
```
### Examples
Refer to the [examples](./examples) folder for complete usage scenarios.
1. 📬 **[PubSub Example](./examples/pubsub)** - Demonstrates a simple Pub/Sub implementation using `py-pg-notify`.
---
## 📄 License
This project is licensed under the MIT License. See the LICENSE file for details.
---
## 🤝 Contributing
We welcome contributions! Please follow these steps:
1. Fork the repository.
2. Create a new branch.
3. Make your changes.
4. Add the test cases if needed.
5. Test all the test cases for verfication.
6. Submit a pull request.
---
## 📢 Feedback and Support
For bugs or feature requests, create an issue in the GitHub repository. We'd love to hear your feedback!
Raw data
{
"_id": null,
"home_page": null,
"name": "py-pg-notify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "postgresql, listen, notify, python, database, notification, postgres",
"author": null,
"author_email": "D S Sanjaya <dssanjay55555@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9c/d7/9d605fccdcee965e1a8c8cf5159588eb1e379ff2169acc92e996d163139e/py_pg_notify-1.0.1.tar.gz",
"platform": null,
"description": "# py-pg-notify\r\n\r\n\r\n[](https://pepy.tech/projects/py-pg-notify)\r\n\r\n**py-pg-notify** is a Python library that simplifies listening to and sending notifications using PostgreSQL. This package leverages `asyncpg` for asynchronous communication with the database, making it ideal for real-time applications.\r\n\r\n---\r\n\r\n## \ud83d\udcd6 Features\r\n\r\n- \ud83d\udd0a **PostgreSQL Notifications**: Easy-to-use interfaces for `PostgreSQL` notifications.\r\n- \ud83d\udd04 **Asynchronous**: Fully asynchronous with support for multiple listeners and channels.\r\n- \ud83d\udce6 **Lightweight**: Built on top of `asyncpg`, offering high performance.\r\n- \u2699\ufe0f **Custom Handlers**: Define your notification handling logic dynamically.\r\n\r\n---\r\n\r\n## \ud83d\ude80 Installation\r\n\r\nInstall the package via pip:\r\n\r\n```bash\r\npip install py-pg-notify\r\n```\r\n\r\n---\r\n\r\n## Usage\r\n\r\n### Configuration Example\r\nYou can use `PGConfig` to manage PostgreSQL connection parameters via a dictionary, environment variables, or direct parameters.\r\n```python\r\nfrom py_pg_notify import PGConfig\r\n\r\n# Example using keyword args\r\nkwargs = {\r\n \"user\": \"<username>\",\r\n \"password\": \"<password>\",\r\n \"host\": \"<host>\",\r\n \"port\": 5432,\r\n \"dbname\": \"<dbname>\"\r\n}\r\nconfig = PGConfig(**kwargs)\r\n\r\n# Example using environment variables\r\n# Ensure PG_USER, PG_PASSWORD, PG_HOST, PG_PORT, and PG_DBNAME are set in your environment\r\nconfig = PGConfig()\r\n\r\n# Example using direct parameters\r\nconfig = PGConfig(user=\"<username>\", password=\"<password>\", host=\"<host>\", port=5432, dbname=\"<dbname>\")\r\n```\r\n\r\n### Notifier Example\r\n```python\r\nimport asyncio\r\nfrom py_pg_notify import Notifier, PGConfig\r\n\r\nasync def create_trigger_example():\r\n # Define the configuration using environment variables\r\n config = PGConfig()\r\n\r\n async with Notifier(config) as notifier:\r\n\r\n # Send a custom message to 'ch_01' channel\r\n await notifier.notify(\"ch_01\", \"message\")\r\n\r\n # Set up a trigger to notify 'ch_01' when the table is modified\r\n await notifier.create_trigger_function(\"notify_function\", \"ch_01\")\r\n \r\n await notifier.create_trigger(\r\n table_name=\"my_table\",\r\n trigger_name=\"my_trigger\",\r\n function_name=\"notify_function\",\r\n event=\"INSERT\",\r\n )\r\n\r\n trigger_functions = await notifier.get_trigger_functions(\"my_table\")\r\n print(\"Existing Trigger Functions:\", trigger_functions)\r\n\r\n triggers = await notifier.get_triggers(\"my_table\")\r\n print(\"Existing Triggers:\", triggers)\r\n\r\n await notifier.remove_trigger(\"my_table\", \"my_trigger\")\r\n\r\n await notifier.remove_trigger_function(\"notify_function\")\r\n\r\nif __name__ == \"__main__\":\r\n asyncio.run(create_trigger_example())\r\n```\r\n\r\n### Listener Example\r\n```python\r\nimport asyncio\r\nfrom py_pg_notify import Listener, PGConfig, Notification\r\n\r\nasync def notification_handler(msg: Notification):\r\n # Perform any processing on the received notification\r\n print(f\"Notification received: Channel={msg.channel}, Payload={msg.payload}\")\r\n\r\nasync def main():\r\n # Define the configuration using environment variables\r\n config = PGConfig()\r\n\r\n async with Listener(config) as listener:\r\n await listener.add_listener(\"ch_01\", notification_handler)\r\n await asyncio.sleep(3600) # Simulate long-running process\r\n\r\nif __name__ == \"__main__\":\r\n try: \r\n asyncio.run(main())\r\n except KeyboardInterrupt:\r\n exit(0)\r\n```\r\n\r\n### Examples\r\n\r\nRefer to the [examples](./examples) folder for complete usage scenarios.\r\n\r\n1. \ud83d\udcec **[PubSub Example](./examples/pubsub)** - Demonstrates a simple Pub/Sub implementation using `py-pg-notify`.\r\n---\r\n\r\n## \ud83d\udcc4 License\r\nThis project is licensed under the MIT License. See the LICENSE file for details.\r\n\r\n---\r\n\r\n## \ud83e\udd1d Contributing\r\nWe welcome contributions! Please follow these steps:\r\n\r\n1. Fork the repository.\r\n2. Create a new branch.\r\n3. Make your changes.\r\n4. Add the test cases if needed.\r\n5. Test all the test cases for verfication.\r\n6. Submit a pull request.\r\n\r\n---\r\n\r\n## \ud83d\udce2 Feedback and Support\r\nFor bugs or feature requests, create an issue in the GitHub repository. We'd love to hear your feedback!\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Simplifies listening to and sending notifications using PostgreSQL",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/DSSanjaya5/py-pg-notify"
},
"split_keywords": [
"postgresql",
" listen",
" notify",
" python",
" database",
" notification",
" postgres"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb3a243dfde925c13ac526ec4d7f743eecbddbed24092f6bd1c5017dcd07b1f4",
"md5": "73a22d11d4be7f9b11aa087f9560d2be",
"sha256": "c40b172b795989ed1cc3e8569db7485f5fcde445b994f014bff833d5ff8615d0"
},
"downloads": -1,
"filename": "py_pg_notify-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73a22d11d4be7f9b11aa087f9560d2be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9581,
"upload_time": "2025-01-21T13:58:46",
"upload_time_iso_8601": "2025-01-21T13:58:46.039353Z",
"url": "https://files.pythonhosted.org/packages/eb/3a/243dfde925c13ac526ec4d7f743eecbddbed24092f6bd1c5017dcd07b1f4/py_pg_notify-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9cd79d605fccdcee965e1a8c8cf5159588eb1e379ff2169acc92e996d163139e",
"md5": "f96e09b101418d88078486cca97475d7",
"sha256": "4e341b64da6bd9c9a508c65936b9f43db1ca7a7783cd90e2cf28feab4e6bac25"
},
"downloads": -1,
"filename": "py_pg_notify-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "f96e09b101418d88078486cca97475d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12849,
"upload_time": "2025-01-21T13:58:58",
"upload_time_iso_8601": "2025-01-21T13:58:58.157342Z",
"url": "https://files.pythonhosted.org/packages/9c/d7/9d605fccdcee965e1a8c8cf5159588eb1e379ff2169acc92e996d163139e/py_pg_notify-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-21 13:58:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DSSanjaya5",
"github_project": "py-pg-notify",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "asyncpg",
"specs": [
[
"==",
"0.30.0"
]
]
}
],
"lcname": "py-pg-notify"
}
JSON
