Event notifications and alerts for Python applications
Website • Documentation • Python Guide • Git
--- **IronNotify** helps you send event notifications and alerts to your users instantly. Built for developers who want simple, powerful notification infrastructure without the complexity. ## Installation ```bash pip install ironnotify ``` ## Quick Start ### Send a Simple Notification ```python import ironnotify # Initialize ironnotify.init("ak_live_xxxxx") # Send a simple notification ironnotify.notify( "order.created", "New Order Received", message="Order #1234 has been placed", severity="success", metadata={"order_id": "1234", "amount": 99.99}, ) ``` ### Fluent Event Builder ```python import ironnotify ironnotify.init("ak_live_xxxxx") # Build complex notifications with the fluent API result = ironnotify.event("payment.failed") \ .with_title("Payment Failed") \ .with_message("Payment could not be processed") \ .with_severity("error") \ .with_metadata({"order_id": "1234", "reason": "Card declined"}) \ .with_action("Retry Payment", url="/orders/1234/retry", style="primary") \ .with_action("Contact Support", action="open_support") \ .for_user("user-123") \ .with_deduplication_key("payment-failed-1234") \ .expires_in(86400) # 24 hours \ .send() ``` ### Async Support ```python import asyncio import ironnotify async def main(): ironnotify.init("ak_live_xxxxx") # Async notification result = await ironnotify.notify_async( "user.signup", "New User Registered", severity="success", ) # Async event builder result = await ironnotify.event("order.shipped") \ .with_title("Order Shipped") \ .for_user("user-123") \ .send_async() # Get notifications async notifications = await ironnotify.get_notifications_async(limit=10) asyncio.run(main()) ``` ### Using the Client Directly ```python from ironnotify import NotifyClient, NotifyOptions client = NotifyClient(NotifyOptions( api_key="ak_live_xxxxx", debug=True, )) # Send notification result = client.notify("event.type", "Title") # Use event builder result = client.event("event.type") \ .with_title("Title") \ .send() # Clean up client.close() ``` ## Configuration ```python from ironnotify import NotifyOptions, NotifyClient options = NotifyOptions( api_key="ak_live_xxxxx", api_base_url="https://api.ironnotify.com", ws_url="wss://ws.ironnotify.com", debug=False, enable_offline_queue=True, max_offline_queue_size=100, auto_reconnect=True, max_reconnect_attempts=5, reconnect_delay=1.0, ) client = NotifyClient(options) ``` ### Configuration Options | Option | Type | Default | Description | |--------|------|---------|-------------| | `api_key` | str | required | Your API key (ak_live_xxx or ak_test_xxx) | | `api_base_url` | str | 'https://api.ironnotify.com' | API base URL | | `ws_url` | str | 'wss://ws.ironnotify.com' | WebSocket URL | | `debug` | bool | False | Enable debug logging | | `enable_offline_queue` | bool | True | Queue notifications when offline | | `max_offline_queue_size` | int | 100 | Max offline queue size | | `auto_reconnect` | bool | True | Auto-reconnect WebSocket | | `max_reconnect_attempts` | int | 5 | Max reconnection attempts | | `reconnect_delay` | float | 1.0 | Base reconnection delay (seconds) | ## Features - **Simple Notifications**: Send notifications with one line of code - **Fluent Builder**: Build complex notifications with an intuitive API - **Async Support**: Full async/await support for all operations - **Offline Queue**: Notifications are queued when offline - **Type Hints**: Full type annotations for IDE support - **Dataclasses**: Clean data models using Python dataclasses ## Notification Options ### Severity Levels ```python from ironnotify import SeverityLevel # Available levels: "info", "success", "warning", "error", "critical" ironnotify.notify("alert", "System Alert", severity="critical") ``` ### Actions ```python ironnotify.event("order.shipped") \ .with_title("Order Shipped") \ .with_action("Track Package", url="https://tracking.example.com/123", style="primary") \ .with_action("View Order", action="view_order") \ .send() ``` ### Deduplication Prevent duplicate notifications: ```python ironnotify.event("reminder") \ .with_title("Daily Reminder") \ .with_deduplication_key("daily-reminder-2024-01-15") \ .send() ``` ### Grouping Group related notifications: ```python ironnotify.event("comment.new") \ .with_title("New Comment") \ .with_group_key("post-123-comments") \ .send() ``` ### Expiration ```python from datetime import datetime, timedelta # Expires in 1 hour ironnotify.event("flash_sale") \ .with_title("Flash Sale!") \ .expires_in(3600) \ .send() # Expires at specific time ironnotify.event("event_reminder") \ .with_title("Event Tomorrow") \ .expires_on(datetime.utcnow() + timedelta(days=1)) \ .send() ``` ## Managing Notifications ### Get Notifications ```python # Get all notifications notifications = ironnotify.get_notifications() # With options unread = ironnotify.get_notifications(limit=10, offset=0, unread_only=True) # Async notifications = await ironnotify.get_notifications_async() ``` ### Mark as Read ```python # Mark single notification client.mark_as_read("notification-id") # Mark all as read client.mark_all_as_read() ``` ### Get Unread Count ```python count = client.get_unread_count() print(f"You have {count} unread notifications") ``` ## Real-Time Notifications ```python import ironnotify ironnotify.init("ak_live_xxxxx") def handle_notification(notification): print(f"New notification: {notification.title}") ironnotify.on_notification(handle_notification) ironnotify.connect() ironnotify.subscribe_to_user("user-123") ironnotify.subscribe_to_app() ``` ## Offline Support Notifications are automatically queued when offline: ```python import ironnotify ironnotify.init("ak_live_xxxxx") # This will be queued if offline ironnotify.notify("event", "Title") # Manually flush the queue ironnotify.flush() # Or async await ironnotify.flush_async() ``` ## Requirements - Python 3.8+ - httpx - websockets (for real-time features) ## Documentation For complete documentation, visit [ironnotify.com/docs](https://ironnotify.com/docs). ## Other SDKs | Platform | Package | |----------|---------| | JavaScript/TypeScript | [@ironservices/notify](https://git.marketally.com/ironservices/ironnotify-js) | | .NET | [IronNotify.Client](https://git.marketally.com/ironservices/ironnotify-dotnet) | | Go | [ironnotify-go](https://git.marketally.com/ironservices/ironnotify-go) | | Java | [ironnotify-java](https://git.marketally.com/ironservices/ironnotify-java) | | Rust | [ironnotify](https://git.marketally.com/ironservices/ironnotify-rust) | ## Support - **Documentation**: [ironnotify.com/docs](https://ironnotify.com/docs) - **Email**: dev@ironservices.io - **Issues**: [git.marketally.com/ironservices/ironnotify-python/issues](https://git.marketally.com/ironservices/ironnotify-python/issues) ## License MIT License - see [LICENSE](LICENSE) for details.