rabbitmq-easy 1.0.0__tar.gz

rabbitmq_easy-1.0.0/.gitignore

@@ -0,0 +1,128 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Custom
+rabbitmq_manager.log
+*.log
+.DS_Store

rabbitmq_easy-1.0.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [1.0.0] - 2025-06-10
+
+### Added
+- Initial release of RabbitMQ Easy
+- Automatic connection management with retry logic
+- Dead letter queue support
+- Environment variable configuration
+- Comprehensive logging with emoji indicators
+- Context manager support
+- Health check functionality
+- Queue information retrieval
+- Batch queue setup
+- Custom exceptions for better error handling
+- Complete test suite
+- Documentation and examples
+
+### Features
+- Idempotent queue and exchange creation
+- Automatic reconnection on connection loss
+- Configurable retry logic
+- Support for both file and console logging
+- Production-ready error handling

rabbitmq_easy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rabbitmq_easy-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+include requirements-dev.txt
+recursive-include examples *.py
+recursive-include tests *.py

rabbitmq_easy-1.0.0/PKG-INFO

@@ -0,0 +1,435 @@
+Metadata-Version: 2.4
+Name: rabbitmq-easy
+Version: 1.0.0
+Summary: A simple, robust RabbitMQ manager for Python applications
+Home-page: https://github.com/yourusername/rabbitmq-easy
+Author: Your Name
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/rabbitmq-easy
+Project-URL: Bug Reports, https://github.com/yourusername/rabbitmq-easy/issues
+Project-URL: Source, https://github.com/yourusername/rabbitmq-easy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pika>=1.2.0
+Requires-Dist: python-dotenv>=0.19.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# RabbitMQ Easy
+
+[![PyPI version](https://badge.fury.io/py/rabbitmq-easy.svg)](https://badge.fury.io/py/rabbitmq-easy)
+[![Python Support](https://img.shields.io/pypi/pyversions/rabbitmq-easy.svg)](https://pypi.org/project/rabbitmq-easy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A simple, robust RabbitMQ manager for Python applications with built-in connection management, retry logic, and dead letter queue support.
+
+## 🚀 Features
+
+- **🔄 Automatic Connection Management**: Built-in retry logic and connection recovery
+- **🛡️ Dead Letter Queue Support**: Automatic setup of dead letter exchanges and queues
+- **📊 Comprehensive Logging**: Both file and console logging with emoji indicators
+- **🔧 Environment Variable Support**: Easy configuration through environment variables
+- **🧪 Idempotent Operations**: Safe to run multiple times without errors
+- **📦 Context Manager Support**: Proper resource cleanup
+- **⚡ Production Ready**: Used in production environments
+- **🗑️ Resource Management**: Built-in cleanup and deletion functions
+
+## 📦 Installation
+
+```bash
+pip install rabbitmq-easy
+```
+
+## 🏃‍♂️ Quick Start
+
+### Basic Usage
+
+```python
+from rabbitmq_easy import RabbitMQManager
+
+# Simple setup
+manager = RabbitMQManager(
+    host='localhost',
+    port=5672,
+    username='admin',
+    password='password',
+    queues=['queue1', 'queue2'],
+    routing_keys=['queue1.*', 'queue2.*'],
+    exchange='my_exchange'
+)
+
+# Publish a message
+manager.publish_message('my_exchange', 'queue1.new', '{"order_id": 123}')
+
+# Use as context manager
+with RabbitMQManager() as manager:  # Uses environment variables
+    manager.publish_message('my_exchange', 'queue1.new', '{"order_id": 123}')
+```
+
+### Environment Variables Setup
+
+Create a `.env` file:
+
+```bash
+RABBITMQ_HOST=localhost
+RABBITMQ_PORT=5672
+RABBITMQ_USERNAME=admin
+RABBITMQ_PASSWORD=password
+RABBITMQ_EXCHANGE=my_exchange
+RABBITMQ_QUEUES=queue1,queue2
+RABBITMQ_ROUTING_KEYS=queue1.*,queue2.*.*
+```
+
+Then use:
+
+```python
+from rabbitmq_easy import create_rabbitmq_manager
+
+# Auto-loads from environment variables
+manager = create_rabbitmq_manager()
+```
+
+## 🔧 Advanced Usage
+
+### Custom Configuration
+
+```python
+from rabbitmq_easy import RabbitMQManager
+
+# Advanced configuration
+manager = RabbitMQManager(
+    host='rabbitmq.example.com',
+    port=5672,
+    username='user',
+    password='pass',
+    queues=['high_priority', 'low_priority'],
+    routing_keys=['urgent.*', 'normal.*'],
+    exchange='task_exchange',
+    dead_letter_exchange='failed_tasks',
+    dead_letter_routing_key='failed',
+    max_retries=3,
+    retry_delay=5,
+    enable_console_logging=True,
+    log_level='INFO'
+)
+
+# Setup additional queues dynamically
+manager.setup_queue(
+    queue_name='special_queue',
+    exchange='task_exchange',
+    routing_key='special.*'
+)
+
+# Get queue information
+info = manager.get_queue_info('high_priority')
+print(f"Messages in queue: {info['message_count']}")
+
+# Health check
+health = manager.health_check()
+print(f"Status: {health['status']}")
+```
+
+### Consumer Example
+
+```python
+import json
+from rabbitmq_easy import RabbitMQManager
+
+def process_message(ch, method, properties, body):
+    """Process incoming message"""
+    try:
+        data = json.loads(body)
+        print(f"Processing: {data}")
+        
+        # Your business logic here
+        
+        # Acknowledge message
+        ch.basic_ack(delivery_tag=method.delivery_tag)
+    except Exception as e:
+        print(f"Error processing message: {e}")
+        # Reject message (will go to dead letter queue if configured)
+        ch.basic_nack(delivery_tag=method.delivery_tag, requeue=False)
+
+# Setup consumer
+with RabbitMQManager() as manager:
+    manager.start_consuming('queue1', process_message)
+```
+
+### Dead Letter Queue Handling
+
+```python
+def handle_failed_messages(ch, method, properties, body):
+    """Handle messages that failed processing"""
+    try:
+        # Get failure information
+        headers = properties.headers or {}
+        death_info = headers.get('x-death', [])
+        
+        if death_info:
+            failure_reason = death_info[0].get('reason')
+            failure_count = death_info[0].get('count')
+            print(f"Message failed {failure_count} times. Reason: {failure_reason}")
+        
+        # Reprocess or log the failure
+        data = json.loads(body)
+        print(f"Dead letter message: {data}")
+        
+        # Acknowledge to remove from DLQ
+        ch.basic_ack(delivery_tag=method.delivery_tag)
+        
+    except Exception as e:
+        print(f"Error handling dead letter: {e}")
+        # Acknowledge to prevent infinite loops
+        ch.basic_ack(delivery_tag=method.delivery_tag)
+
+# Monitor failed messages
+manager.start_consuming('failed_messages', handle_failed_messages)
+```
+
+## ⚙️ Configuration Options
+
+| Parameter | Environment Variable | Default | Description |
+|-----------|---------------------|---------|-------------|
+| `host` | `RABBITMQ_HOST` | `localhost` | RabbitMQ server host |
+| `port` | `RABBITMQ_PORT` | `5672` | RabbitMQ server port |
+| `username` | `RABBITMQ_USERNAME` | `guest` | Username for authentication |
+| `password` | `RABBITMQ_PASSWORD` | `guest` | Password for authentication |
+| `queues` | `RABBITMQ_QUEUES` | `[]` | Comma-separated list of queues |
+| `routing_keys` | `RABBITMQ_ROUTING_KEYS` | `[]` | Comma-separated list of routing keys |
+| `exchange` | `RABBITMQ_EXCHANGE` | `''` | Exchange name |
+| `dead_letter_exchange` | `RABBITMQ_DEAD_LETTER_EXCHANGE` | `{exchange}_dlx` | Dead letter exchange name |
+| `dead_letter_routing_key` | `RABBITMQ_DEAD_LETTER_ROUTING_KEY` | `dead_letter` | Dead letter routing key |
+| `max_retries` | `RABBITMQ_MAX_RETRIES` | `5` | Maximum connection retry attempts |
+| `retry_delay` | `RABBITMQ_RETRY_DELAY` | `5` | Delay between retry attempts |
+| `heartbeat` | `RABBITMQ_HEARTBEAT` | `60` | Connection heartbeat interval |
+| `enable_console_logging` | `RABBITMQ_CONSOLE_LOGGING` | `True` | Enable console logging |
+| `log_level` | `RABBITMQ_LOG_LEVEL` | `INFO` | Logging level |
+
+## 🛠️ Resource Management
+
+### Queue and Exchange Operations
+
+```python
+# Delete specific resources
+manager.delete_queue("old_queue")
+manager.delete_exchange("old_exchange")
+
+# Delete only if empty/unused
+manager.delete_queue("queue_name", if_empty=True)
+manager.delete_exchange("exchange_name", if_unused=True)
+
+# Purge messages without deleting queue
+message_count = manager.purge_queue("queue_name")
+print(f"Purged {message_count} messages")
+
+# Clean up dead letter infrastructure
+manager.cleanup_dead_letter_setup()
+
+# Delete all resources created by this manager
+results = manager.delete_all_setup_resources(confirm=True)
+
+# Complete reset
+manager.reset_manager(confirm=True)
+```
+
+## ❌ Error Handling
+
+The package includes custom exceptions for better error handling:
+
+```python
+from rabbitmq_easy import RabbitMQConnectionError, RabbitMQConfigurationError
+
+try:
+    manager = RabbitMQManager(
+        host='invalid-host',
+        queues=['queue1', 'queue2'],
+        routing_keys=['key1']  # Mismatch with queues count
+    )
+except RabbitMQConfigurationError as e:
+    print(f"Configuration error: {e}")
+except RabbitMQConnectionError as e:
+    print(f"Connection error: {e}")
+```
+
+## 🏗️ What Gets Created Automatically
+
+When you initialize with:
+
+```python
+manager = RabbitMQManager(
+    exchange='queue1',
+    queues=['new_queue1', 'pending_queue1'],
+    routing_keys=['queue1.new', 'queue1.pending']
+)
+```
+
+RabbitMQ Easy automatically creates:
+
+1. **`queue1`** exchange (main exchange)
+2. **`queue1_dlx`** exchange (dead letter exchange)
+3. **`new_queue1`** queue → bound to `queue1` exchange with `queue1.new` routing key
+4. **`pending_queue1`** queue → bound to `queue1` exchange with `queue1.pending` routing key
+5. **`failed_messages`** queue → bound to `queue1_dlx` exchange for error handling
+
+All queues are configured with dead letter routing to capture failed messages automatically.
+
+## 📋 Best Practices
+
+1. **Use Environment Variables**: Store sensitive information like passwords in environment variables
+2. **Context Managers**: Use `with` statements for automatic cleanup
+3. **Dead Letter Queues**: Always configure dead letter queues for production
+4. **Health Checks**: Implement health checks in your applications
+5. **Logging**: Monitor logs for connection issues and errors
+6. **Error Handling**: Always handle exceptions in your consumers
+7. **Resource Cleanup**: Use the provided cleanup functions during development
+
+## ⚠️ Important Notes
+
+### Queue and Routing Key Validation
+
+The number of queues must match the number of routing keys:
+
+```python
+# ✅ Correct
+manager = RabbitMQManager(
+    queues=['queue1', 'queue2'],
+    routing_keys=['key1', 'key2']  # Same count
+)
+
+# ❌ Will raise RabbitMQConfigurationError
+manager = RabbitMQManager(
+    queues=['queue1', 'queue2'],
+    routing_keys=['key1']  # Mismatch!
+)
+```
+
+### Dead Letter Configuration
+
+Don't configure dead letter queues to point to themselves:
+
+```python
+# ❌ Don't do this - creates infinite loop
+manager.setup_queue(
+    'my_dlq',
+    dead_letter_exchange='same_exchange'
+)
+
+# ✅ Do this instead
+manager.setup_queue('my_dlq', dead_letter_exchange=None)
+```
+
+## 🔍 Monitoring and Health Checks
+
+```python
+# Check connection health
+health = manager.health_check()
+if health['status'] == 'healthy':
+    print("✅ RabbitMQ connection is healthy")
+else:
+    print(f"❌ RabbitMQ connection issues: {health['error']}")
+
+# Get detailed queue information
+info = manager.get_queue_info('queue1')
+print(f"Queue: {info['queue']}")
+print(f"Messages: {info['message_count']}")
+print(f"Consumers: {info['consumer_count']}")
+```
+
+## 🚀 Production Deployment
+
+### Docker Compose Example
+
+```yaml
+version: '3.8'
+services:
+  app:
+    build: .
+    environment:
+      RABBITMQ_HOST: rabbitmq
+      RABBITMQ_USERNAME: admin
+      RABBITMQ_PASSWORD: ${RABBITMQ_PASSWORD}
+      RABBITMQ_EXCHANGE: production
+      RABBITMQ_QUEUES: queue1,queue2
+      RABBITMQ_ROUTING_KEYS: queue1.*,queue2.*.*
+    depends_on:
+      - rabbitmq
+  
+  rabbitmq:
+    image: rabbitmq:3-management
+    environment:
+      RABBITMQ_DEFAULT_USER: admin
+      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD}
+```
+
+### Kubernetes ConfigMap
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: rabbitmq-config
+data:
+  RABBITMQ_HOST: "rabbitmq-service"
+  RABBITMQ_PORT: "5672"
+  RABBITMQ_EXCHANGE: "production"
+  RABBITMQ_QUEUES: "queue1,queue2"
+  RABBITMQ_ROUTING_KEYS: "queue1.*,queue2.*.*"
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Run the test suite (`pytest`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🐛 Support
+
+- Create an issue on [GitHub](https://github.com/mount-isaac/rabbitmq-easy/issues)
+- Check the [documentation](https://github.com/mount-isaac/rabbitmq-easy#readme)
+
+## 📚 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes and version history.
+
+## 🙏 Acknowledgments
+
+- Built on top of the excellent [pika](https://github.com/pika/pika) library
+- Inspired by the need for simpler RabbitMQ management in Python applications
+- Thanks to the RabbitMQ team for creating an amazing message broker
+
+---
+
+**Made with ❤️ for the Python community**