gh-rabbit-hole

1.6.0 verified Sat May 09 auth: no python

A Python library for simplified communication with RabbitMQ, providing a high-level wrapper around pika. Current version is 1.6.0, compatible with Python >=3.10. Release cadence is irregular; maintained by m-ghiani.

pip install gh-rabbit-hole

Common errors

error ModuleNotFoundError: No module named 'gh_rabbit_hole' ↓

cause Incorrect import path; package uses 'rabbit_hole' for Python import, not hyphens or 'gh_rabbit_hole'.

fix

Use 'from rabbit_hole import RabbitHole'

error pika.exceptions.AMQPConnectionError: Connection closed by remote server ↓

cause Authentication failure or RabbitMQ server not configured for guest access from remote.

fix

Set correct credentials via environment variables RABBIT_USER, RABBIT_PASS, or create a virtual host and user in RabbitMQ.

error TypeError: Object of type X is not JSON serializable ↓

cause Passing non-serializable object to publish method.

fix

Convert payload to dict or string before publishing.

Warnings

breaking In version 1.0.0, the library was renamed from 'gh-rabbit-hole' to 'rabbit_hole' for imports. The package name on PyPI remains 'gh-rabbit-hole'. ↓

fix Use 'from rabbit_hole import RabbitHole' instead of any old import path.

deprecated The method 'consume' without auto_ack parameter defaults to False, but future versions may change default to True. Explicitly pass auto_ack to avoid breakage. ↓

fix Always specify auto_ack=True or False explicitly when calling consume.

gotcha If RabbitMQ is not running or connection fails, the library may hang indefinitely due to default timeout settings. ↓

fix Set timeout parameter explicitly, e.g., RabbitHole(..., timeout=5).

gotcha The 'publish' method expects a dict or string; passing other types may cause serialization errors. ↓

fix Ensure payload is a JSON-serializable dict or a string.

Imports

RabbitHole
wrong
```
from gh_rabbit_hole import RabbitHole
```
correct
```
from rabbit_hole import RabbitHole
```
Package uses snake_case 'rabbit_hole' for import, not hyphenated or underscored with gh prefix.

Quickstart

Connect to RabbitMQ, declare a queue, publish and consume a message.

import os
from rabbit_hole import RabbitHole

# Initialize with environment variables or direct connection params
rh = RabbitHole(
    host=os.environ.get('RABBIT_HOST', 'localhost'),
    port=int(os.environ.get('RABBIT_PORT', 5672)),
    username=os.environ.get('RABBIT_USER', 'guest'),
    password=os.environ.get('RABBIT_PASS', 'guest')
)

# Declare a queue
rh.declare_queue('test_queue')

# Publish a message
rh.publish('test_queue', {'message': 'hello world'})

# Consume messages (callback)
def callback(ch, method, properties, body):
    print(f"Received: {body}")
    rh.ack(method.delivery_tag)

rh.consume('test_queue', callback=callback, auto_ack=False)

# Close connection
rh.close()