0
# py-Asterisk
1

2
A comprehensive Python interface for the Asterisk Manager API that enables programmatic control and monitoring of Asterisk PBX systems. The library provides high-level abstractions for manager connections, channel manipulation, event handling, and configuration management, making it easy to build telephony applications, call center systems, and automated PBX management tools.
3

4
## Package Information
5

6
- **Package Name**: py-Asterisk
7
- **Language**: Python
8
- **Installation**: `pip install py-Asterisk`
9

10
## Core Imports
11

12
```python
13
import Asterisk
14
from Asterisk import Manager, Config, CLI, Util, Logging
15
```
16

17
Most common usage pattern:
18

19
```python
20
from Asterisk.Manager import Manager
21
```
22

23
## Package Constants
24

25
```python { .api }
26
__version__: str = '0.1'
27
"""Package version string."""
28

29
cause_codes: dict
30
"""Dictionary mapping Asterisk cause codes to (code, name, description) tuples."""
31
```
32

33
## Basic Usage
34

35
```python
36
from Asterisk.Manager import Manager
37

38
# Connect to Asterisk Manager API
39
manager = Manager(('127.0.0.1', 5038), 'username', 'secret')
40

41
# Execute a basic command
42
channels = manager.CoreShowChannels()
43

44
# Get a channel object and manipulate it
45
channel = manager.get_channel('SIP/1001-00000001')
46
channel.Hangup()
47

48
# Execute console commands
49
output = manager.Command('core show channels')
50

51
# Clean up
52
manager.Logoff()
53
```
54

55
## Architecture
56

57
py-Asterisk is built around several key components:
58

59
- **Manager Classes**: BaseManager provides core protocol implementation, while Manager and CoreManager add action methods and event handling
60
- **Action Classes**: CoreActions and ZapataActions provide method interfaces for Asterisk Manager API actions
61
- **Channel Objects**: BaseChannel and ZapChannel represent active call channels with manipulation methods
62
- **Event System**: EventCollection manages event subscriptions and dispatching for real-time PBX monitoring
63
- **Configuration**: Config class handles py-asterisk.conf file parsing and connection settings
64
- **CLI Tools**: Command-line utilities for interactive Asterisk management and debugging
65

66
## Capabilities
67

68
### Manager API Connection and Actions
69

70
Core functionality for connecting to Asterisk Manager API and executing actions. Includes authentication, action execution, response handling, and 50+ built-in action methods for controlling PBX functionality.
71

72
```python { .api }
73
class Manager(BaseManager, CoreActions, ZapataActions):
74
    def __init__(address, username, secret, listen_events=True, timeout=None): ...
75

76
class CoreActions:
77
    def Command(command: str) -> list: ...
78
    def CoreShowChannels() -> list: ...
79
    def Originate(channel: str, context: str, exten: str, priority: int, **kwargs): ...
80
    def Hangup(channel: str): ...
81
    def QueueStatus() -> dict: ...
82
    def ParkedCalls() -> dict: ...
83
    def DBGet(family: str, key: str) -> dict: ...
84
    def DBPut(family: str, key: str, value: str) -> dict: ...
85
    def SipShowPeer(peer: str) -> dict: ...
86
    def MeetMe() -> list: ...
87
    def ConfbridgeListRooms() -> list: ...
88
```
89

90
[Manager API](./manager-api.md)
91

92
### Channel Management
93

94
Channel objects provide convenient interfaces for manipulating active call channels. Supports getting/setting channel variables, hanging up calls, monitoring, and channel-specific operations.
95

96
```python { .api }
97
class BaseChannel:
98
    def __init__(manager, id: str): ...
99
    def Hangup(): ...
100
    def AbsoluteTimeout(timeout: int): ...
101
    def Monitor(pathname: str): ...
102
    def __getitem__(key: str): ...  # Get channel variable
103
    def __setitem__(key: str, value: str): ...  # Set channel variable
104

105
class ZapChannel(BaseChannel):
106
    # Specialized for Zapata/DAHDI channels
107
```
108

109
[Channel Management](./channel-management.md)
110

111
### Configuration Management
112

113
Configuration file handling for py-asterisk connection settings. Supports multiple configuration file locations, environment variables, and structured configuration access.
114

115
```python { .api }
116
class Config:
117
    def __init__(config_pathname=None): ...
118

119
CONFIG_PATHNAMES: list  # Default search paths for config files
120
CONFIG_FILENAME: str   # Default config filename
121
```
122

123
[Configuration](./configuration.md)
124

125
### CLI Tools and Utilities
126

127
Command-line interface for interactive Asterisk management, plus utility classes for event handling, data structures, and debugging.
128

129
```python { .api }
130
# CLI functions
131
def usage(argv0, out_file): ...
132
def show_actions(action=None): ...
133
def execute_action(manager, argv): ...
134
def command_line(argv): ...
135

136
# Utility classes
137
class AttributeDict(dict): ...
138
class EventCollection: ...
139
class Unspecified: ...
140

141
# Utility functions
142
def dump_packet(packet, file=sys.stdout): ...
143
def dump_human(data, file=sys.stdout): ...
144
```
145

146
[CLI and Utilities](./cli-utilities.md)
147

148
### Exception Handling
149

150
Comprehensive exception classes for different error conditions in Manager API communication, authentication, and action execution.
151

152
```python { .api }
153
class BaseException(Exception): ...
154
class AuthenticationFailure(BaseException): ...
155
class CommunicationError(BaseException): ...
156
class ActionFailed(BaseException): ...
157
class PermissionDenied(BaseException): ...
158
class GoneAwayError(BaseException): ...
159
```
160

161
[Exception Handling](./exceptions.md)
162

163
## Types
164

165
```python { .api }
166
class BaseException(Exception):
167
    """Base class for all py-Asterisk exceptions."""
168
    def __init__(error: str): ...
169
    def __str__() -> str: ...
170
```