or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

channel-management.mdcli-utilities.mdconfiguration.mdexceptions.mdindex.mdmanager-api.md
tile.json

tessl/pypi-py-asterisk

Asterisk Manager API Python interface for programmatically controlling and monitoring Asterisk PBX systems

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/py-asterisk@0.5.x

To install, run

npx @tessl/cli install tessl/pypi-py-asterisk@0.5.0

index.mddocs/

py-Asterisk

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.

Package Information

  • Package Name: py-Asterisk
  • Language: Python
  • Installation: pip install py-Asterisk

Core Imports

import Asterisk
from Asterisk import Manager, Config, CLI, Util, Logging

Most common usage pattern:

from Asterisk.Manager import Manager

Package Constants

__version__: str = '0.1'
"""Package version string."""

cause_codes: dict
"""Dictionary mapping Asterisk cause codes to (code, name, description) tuples."""

Basic Usage

from Asterisk.Manager import Manager

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

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

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

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

# Clean up
manager.Logoff()

Architecture

py-Asterisk is built around several key components:

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

Capabilities

Manager API Connection and Actions

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.

class Manager(BaseManager, CoreActions, ZapataActions):
    def __init__(address, username, secret, listen_events=True, timeout=None): ...

class CoreActions:
    def Command(command: str) -> list: ...
    def CoreShowChannels() -> list: ...
    def Originate(channel: str, context: str, exten: str, priority: int, **kwargs): ...
    def Hangup(channel: str): ...
    def QueueStatus() -> dict: ...
    def ParkedCalls() -> dict: ...
    def DBGet(family: str, key: str) -> dict: ...
    def DBPut(family: str, key: str, value: str) -> dict: ...
    def SipShowPeer(peer: str) -> dict: ...
    def MeetMe() -> list: ...
    def ConfbridgeListRooms() -> list: ...

Manager API

Channel Management

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

class BaseChannel:
    def __init__(manager, id: str): ...
    def Hangup(): ...
    def AbsoluteTimeout(timeout: int): ...
    def Monitor(pathname: str): ...
    def __getitem__(key: str): ...  # Get channel variable
    def __setitem__(key: str, value: str): ...  # Set channel variable

class ZapChannel(BaseChannel):
    # Specialized for Zapata/DAHDI channels

Channel Management

Configuration Management

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

class Config:
    def __init__(config_pathname=None): ...

CONFIG_PATHNAMES: list  # Default search paths for config files
CONFIG_FILENAME: str   # Default config filename

Configuration

CLI Tools and Utilities

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

# CLI functions
def usage(argv0, out_file): ...
def show_actions(action=None): ...
def execute_action(manager, argv): ...
def command_line(argv): ...

# Utility classes
class AttributeDict(dict): ...
class EventCollection: ...
class Unspecified: ...

# Utility functions
def dump_packet(packet, file=sys.stdout): ...
def dump_human(data, file=sys.stdout): ...

CLI and Utilities

Exception Handling

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

class BaseException(Exception): ...
class AuthenticationFailure(BaseException): ...
class CommunicationError(BaseException): ...
class ActionFailed(BaseException): ...
class PermissionDenied(BaseException): ...
class GoneAwayError(BaseException): ...

Exception Handling

Types

class BaseException(Exception):
    """Base class for all py-Asterisk exceptions."""
    def __init__(error: str): ...
    def __str__() -> str: ...