0
# Pika
1

2
Pure Python implementation of the AMQP 0.9.1 protocol including RabbitMQ's extensions. Pika provides a comprehensive client library for Python applications to communicate with RabbitMQ message brokers, supporting multiple connection adapters and various Python environments without requiring threads.
3

4
## Package Information
5

6
- **Package Name**: pika
7
- **Language**: Python
8
- **Installation**: `pip install pika`
9
- **Requires**: Python 3.7+
10

11
## Core Imports
12

13
```python
14
import pika
15
```
16

17
Essential classes and functions:
18

19
```python
20
from pika import ConnectionParameters, URLParameters, SSLOptions
21
from pika import PlainCredentials
22
from pika import BlockingConnection, SelectConnection
23
from pika import BasicProperties, DeliveryMode
24
from pika import AMQPConnectionWorkflow
25
```
26

27
Connection adapters:
28

29
```python
30
from pika.adapters import BlockingConnection, SelectConnection, BaseConnection, IOLoop
31
# Framework-specific adapters require direct imports:
32
from pika.adapters.asyncio_connection import AsyncioConnection
33
from pika.adapters.tornado_connection import TornadoConnection  
34
from pika.adapters.twisted_connection import TwistedProtocolConnection
35
from pika.adapters.gevent_connection import GeventConnection
36
```
37

38
## Basic Usage
39

40
```python
41
import pika
42

43
# Simple connection with default parameters (localhost:5672)
44
connection = pika.BlockingConnection(pika.ConnectionParameters())
45
channel = connection.channel()
46

47
# Declare a queue
48
channel.queue_declare(queue='hello')
49

50
# Publish a message
51
channel.basic_publish(
52
    exchange='',
53
    routing_key='hello',
54
    body='Hello World!'
55
)
56

57
# Consume messages
58
def callback(ch, method, properties, body):
59
    print(f"Received {body.decode()}")
60
    ch.basic_ack(delivery_tag=method.delivery_tag)
61

62
channel.basic_consume(queue='hello', on_message_callback=callback)
63
channel.start_consuming()
64

65
connection.close()
66
```
67

68
## Architecture
69

70
Pika's design enables flexible AMQP client implementation:
71

72
- **Connection**: Manages network connection to RabbitMQ broker with multiple adapter types
73
- **Channel**: Virtual connection within a connection for message operations
74
- **Connection Adapters**: Different networking models (blocking, async, event-driven)
75
- **Authentication**: Pluggable credential system supporting PLAIN and EXTERNAL methods
76
- **Frame Protocol**: Low-level AMQP frame handling and message serialization
77

78
The library supports both synchronous (BlockingConnection) and asynchronous programming models, making it suitable for simple message publishing/consuming scenarios and complex asynchronous messaging architectures.
79

80
## Capabilities
81

82
### Connection Management
83

84
Comprehensive connection configuration and management with multiple adapter types supporting different networking approaches (blocking, select-based, asyncio, framework-specific).
85

86
```python { .api }
87
class ConnectionParameters:
88
    def __init__(self, host='localhost', port=5672, virtual_host='/', 
89
                 credentials=None, channel_max=65535, frame_max=131072,
90
                 heartbeat=None, ssl_options=None, connection_attempts=1,
91
                 retry_delay=2.0, socket_timeout=10.0, stack_timeout=15.0,
92
                 locale='en_US', blocked_connection_timeout=None,
93
                 client_properties=None, tcp_options=None): ...
94

95
class URLParameters(ConnectionParameters):
96
    def __init__(self, url): ...
97

98
class BlockingConnection:
99
    def __init__(self, parameters): ...
100
    def channel(self, channel_number=None): ...
101
    def close(self): ...
102

103
class SelectConnection:
104
    def __init__(self, parameters, on_open_callback, on_open_error_callback,
105
                 on_close_callback, ioloop=None): ...
106
```
107

108
[Connection Management](./connection-management.md)
109

110
### Channel Operations
111

112
Channel-based message operations including publishing, consuming, queue/exchange management, and transaction support with comprehensive callback handling.
113

114
```python { .api }
115
class BlockingChannel:
116
    def basic_publish(self, exchange, routing_key, body, properties=None, mandatory=False): ...
117
    def basic_consume(self, queue, on_message_callback, auto_ack=False, exclusive=False, consumer_tag=None, arguments=None): ...
118
    def basic_ack(self, delivery_tag, multiple=False): ...
119
    def queue_declare(self, queue='', passive=False, durable=False, exclusive=False, auto_delete=False, arguments=None): ...
120
    def exchange_declare(self, exchange, exchange_type='direct', passive=False, durable=False, auto_delete=False, internal=False, arguments=None): ...
121
```
122

123
[Channel Operations](./channel-operations.md)
124

125
### Authentication & Security
126

127
Authentication credential management supporting username/password and external authentication methods with SSL/TLS connection security.
128

129
```python { .api }
130
class PlainCredentials:
131
    def __init__(self, username, password, erase_on_connect=False): ...
132

133
# ExternalCredentials available via: from pika.credentials import ExternalCredentials
134
class ExternalCredentials:
135
    def __init__(self): ...
136

137
class SSLOptions:
138
    def __init__(self, context=None, server_hostname=None): ...
139
```
140

141
[Authentication & Security](./authentication-security.md)
142

143
### Message Properties & Types
144

145
AMQP message properties, delivery modes, exchange types, and type definitions for comprehensive message handling and routing control.
146

147
```python { .api }
148
class BasicProperties:
149
    def __init__(self, content_type=None, content_encoding=None, headers=None,
150
                 delivery_mode=None, priority=None, correlation_id=None,
151
                 reply_to=None, expiration=None, message_id=None,
152
                 timestamp=None, type=None, user_id=None, app_id=None,
153
                 cluster_id=None): ...
154

155
class DeliveryMode(Enum):
156
    Transient = 1
157
    Persistent = 2
158

159
# ExchangeType available via: from pika.exchange_type import ExchangeType
160
class ExchangeType(Enum):
161
    direct = 'direct'
162
    fanout = 'fanout'
163
    headers = 'headers'  
164
    topic = 'topic'
165
```
166

167
[Message Properties & Types](./message-properties-types.md)
168

169
### Exception Handling
170

171
Comprehensive exception hierarchy for connection, channel, and protocol errors with detailed error information and recovery patterns.
172

173
```python { .api }
174
class AMQPConnectionError(AMQPError): ...
175
class ConnectionClosed(AMQPConnectionError):
176
    def __init__(self, reply_code, reply_text): ...
177
    @property
178
    def reply_code(self): ...
179
    @property  
180
    def reply_text(self): ...
181

182
class AMQPChannelError(AMQPError): ...
183
class ChannelClosed(AMQPChannelError):
184
    def __init__(self, reply_code, reply_text): ...
185
```
186

187
[Exception Handling](./exception-handling.md)
188

189
### Connection Adapters
190

191
Framework-specific connection adapters for asyncio, Tornado, Twisted, and Gevent integration enabling pika usage in different Python async frameworks.
192

193
```python { .api }
194
class AsyncioConnection(BaseConnection):
195
    def __init__(self, parameters, on_open_callback, on_open_error_callback,
196
                 on_close_callback, loop=None): ...
197

198
class TornadoConnection(BaseConnection):
199
    def __init__(self, parameters, on_open_callback, on_open_error_callback,
200
                 on_close_callback, ioloop=None): ...
201
```
202

203
[Connection Adapters](./connection-adapters.md)