basicami 0.1.0__py3-none-any.whl

basicami/__init__.py

@@ -0,0 +1,6 @@
+__version__ = "0.1.0"
+
+from .basic_ami import BasicAMI
+from .marker import Marker, MarkerTrace, parse_marker
+
+__all__ = ["BasicAMI", "Marker", "MarkerTrace", "parse_marker"]

basicami/basic_ami.py

@@ -0,0 +1,232 @@
+"""AsyncIO-based Asterisk Manager Interface (AMI) client.
+
+Follows the patterns of basicagi but for AMI over TCP.
+"""
+
+import asyncio
+import logging
+import uuid
+
+logger = logging.getLogger(__name__)
+
+
+class AMIError(Exception):
+    """AMI protocol error."""
+
+
+class BasicAMI:
+    """AsyncIO AMI client.
+
+    Usage::
+
+        ami = await BasicAMI.connect("localhost", 5038, "admin", "secret")
+        resp = await ami.originate(
+            channel="Local/100@from_sbc-173",
+            application="Wait",
+            data="30",
+        )
+        events = await ami.get_events(timeout=1.0)
+        await ami.close()
+    """
+
+    def __init__(self):
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._event_queue: asyncio.Queue[dict[str, str]] = asyncio.Queue()
+        self._pending: dict[str, asyncio.Future[dict[str, str]]] = {}
+        self._read_task: asyncio.Task | None = None
+        self._connected = False
+
+    @classmethod
+    async def connect(
+        cls,
+        host: str,
+        port: int,
+        username: str,
+        secret: str,
+        timeout: float = 15.0,
+    ) -> "BasicAMI":
+        """Connect to AMI, login, and start the background reader."""
+        ami = cls()
+        ami._reader, ami._writer = await asyncio.wait_for(
+            asyncio.open_connection(host, port), timeout=timeout
+        )
+
+        # Read AMI greeting line
+        greeting = await asyncio.wait_for(ami._reader.readline(), timeout=timeout)
+        logger.debug("AMI greeting: %s", greeting.decode().strip())
+
+        # Start background reader before login so we can receive the response
+        ami._read_task = asyncio.create_task(ami._read_loop())
+        ami._connected = True
+
+        # Login
+        resp = await ami.send_action(
+            {"Action": "Login", "Username": username, "Secret": secret}
+        )
+        if resp.get("Response") != "Success":
+            await ami.close()
+            raise AMIError(f"Login failed: {resp.get('Message', 'unknown')}")
+
+        logger.info("AMI connected and logged in to %s:%d", host, port)
+        return ami
+
+    async def send_action(
+        self, action: dict[str, str], timeout: float = 10.0
+    ) -> dict[str, str]:
+        """Send an AMI action and wait for the response."""
+        action_id = action.get("ActionID", str(uuid.uuid4()))
+        action["ActionID"] = action_id
+
+        # Create a future for the response
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[dict[str, str]] = loop.create_future()
+        self._pending[action_id] = future
+
+        # Serialize and send
+        lines = [f"{k}: {v}" for k, v in action.items()]
+        payload = "\r\n".join(lines) + "\r\n\r\n"
+        self._writer.write(payload.encode())
+        await self._writer.drain()
+
+        logger.debug("Sent action: %s", action.get("Action"))
+
+        try:
+            return await asyncio.wait_for(future, timeout=timeout)
+        finally:
+            self._pending.pop(action_id, None)
+
+    async def originate(
+        self,
+        channel: str,
+        context: str | None = None,
+        exten: str | None = None,
+        priority: str | None = None,
+        application: str | None = None,
+        data: str | None = None,
+        caller_id: str | None = None,
+        timeout: int | None = None,
+        variables: dict[str, str] | None = None,
+        async_: bool = True,
+    ) -> dict[str, str]:
+        """Send an Originate action."""
+        action: dict[str, str] = {
+            "Action": "Originate",
+            "Channel": channel,
+        }
+        if context:
+            action["Context"] = context
+        if exten:
+            action["Exten"] = exten
+        if priority:
+            action["Priority"] = priority
+        if application:
+            action["Application"] = application
+        if data:
+            action["Data"] = data
+        if caller_id:
+            action["CallerID"] = caller_id
+        if timeout:
+            action["Timeout"] = str(timeout * 1000)  # seconds to ms
+        if async_:
+            action["Async"] = "true"
+        if variables:
+            action["Variable"] = ",".join(f"{k}={v}" for k, v in variables.items())
+
+        return await self.send_action(action)
+
+    async def get_events(
+        self, timeout: float = 0.1, max_events: int = 1000
+    ) -> list[dict[str, str]]:
+        """Drain buffered events, waiting briefly for new ones."""
+        events: list[dict[str, str]] = []
+
+        # Drain already-queued events
+        while not self._event_queue.empty() and len(events) < max_events:
+            events.append(self._event_queue.get_nowait())
+
+        # Wait briefly for more
+        try:
+            event = await asyncio.wait_for(self._event_queue.get(), timeout=timeout)
+            events.append(event)
+            # Drain any more that arrived
+            while not self._event_queue.empty() and len(events) < max_events:
+                events.append(self._event_queue.get_nowait())
+        except asyncio.TimeoutError:
+            pass
+
+        return events
+
+    async def close(self):
+        """Disconnect from AMI."""
+        self._connected = False
+        if self._read_task:
+            self._read_task.cancel()
+            try:
+                await self._read_task
+            except asyncio.CancelledError:
+                pass
+        if self._writer:
+            try:
+                self._writer.close()
+                await self._writer.wait_closed()
+            except Exception:
+                pass
+        logger.debug("AMI connection closed")
+
+    async def _read_loop(self):
+        """Background task: read AMI packets and dispatch."""
+        buf = b""
+        try:
+            while self._connected:
+                data = await self._reader.read(4096)
+                if not data:
+                    logger.warning("AMI connection closed by server")
+                    break
+                buf += data
+
+                # Split on double CRLF (AMI packet delimiter)
+                while b"\r\n\r\n" in buf:
+                    packet, buf = buf.split(b"\r\n\r\n", 1)
+                    self._dispatch_packet(packet.decode("utf-8", errors="replace"))
+
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.error("AMI read loop error: %s", e)
+        finally:
+            # Cancel any pending futures
+            for action_id, future in self._pending.items():
+                if not future.done():
+                    future.set_exception(
+                        AMIError("Connection closed while waiting for response")
+                    )
+
+    def _dispatch_packet(self, raw: str):
+        """Parse an AMI packet and route to response future or event queue."""
+        fields: dict[str, str] = {}
+        for line in raw.split("\r\n"):
+            if ":" in line:
+                key, _, value = line.partition(":")
+                fields[key.strip()] = value.strip()
+
+        if not fields:
+            return
+
+        # Check if this is a response to a pending action
+        action_id = fields.get("ActionID", "")
+        if action_id in self._pending:
+            future = self._pending[action_id]
+            if not future.done():
+                future.set_result(fields)
+            return
+
+        # Otherwise it's an event — queue it
+        if "Event" in fields:
+            try:
+                self._event_queue.put_nowait(fields)
+            except asyncio.QueueFull:
+                logger.warning(
+                    "Event queue full, dropping event: %s",
+                    fields.get("Event"),
+                )

basicami/marker.py

@@ -0,0 +1,106 @@
+"""Marker parsing for Asterisk Verbose/Log dialplan markers.
+
+Ported from the Go implementation in pbx-test collector/parser.go.
+"""
+
+import re
+from dataclasses import dataclass, field
+
+# Matches structured Verbose markers.
+# Format: "    -- MARKER_NAME: context key=value key=value"
+_MARKER_RE = re.compile(r"(?:^\s*(?:--\s*)?)?([A-Z][A-Z0-9_]+):\s+(\S+)\s*(.*)$")
+
+# Matches individual key=value pairs.
+_KV_RE = re.compile(r"(\w+)=(\S+)")
+
+# Strips ANSI escape sequences.
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+@dataclass
+class Marker:
+    """A parsed Verbose marker from the Asterisk dialplan."""
+
+    name: str  # e.g. "SBC_ENTER", "INBOUND_ROUTE"
+    context: str  # e.g. tenant ID or flow context name
+    kv: dict[str, str] = field(default_factory=dict)
+    raw: str = ""
+    channel: str = ""
+    uniqueid: str = ""
+
+
+def parse_marker(line: str) -> Marker | None:
+    """Parse a verbose line into a Marker, or return None if not recognized."""
+    line = _ANSI_RE.sub("", line)
+
+    m = _MARKER_RE.match(line)
+    if not m:
+        return None
+
+    kv = {}
+    kv_part = m.group(3)
+    if kv_part:
+        for kv_match in _KV_RE.finditer(kv_part):
+            kv[kv_match.group(1)] = kv_match.group(2)
+
+    return Marker(
+        name=m.group(1),
+        context=m.group(2),
+        kv=kv,
+        raw=line,
+    )
+
+
+class MarkerTrace:
+    """Ordered collection of markers for a single test call."""
+
+    def __init__(self, test_id: str = "", caller_id: str = ""):
+        self.test_id = test_id
+        self.caller_id = caller_id
+        self.channel: str = ""
+        self.uniqueid: str = ""
+        self.linkedid: str = ""
+        self.markers: list[Marker] = []
+
+    def marker_names(self) -> list[str]:
+        """Return list of marker names in order."""
+        return [m.name for m in self.markers]
+
+    def has_marker(self, name: str) -> bool:
+        """Check if a marker name exists in the trace."""
+        return any(m.name == name for m in self.markers)
+
+    def get_marker(self, name: str) -> Marker | None:
+        """Return the first marker with the given name, or None."""
+        for m in self.markers:
+            if m.name == name:
+                return m
+        return None
+
+    def get_marker_value(self, marker_name: str, key: str) -> str | None:
+        """Return a key-value from the first marker with the given name."""
+        m = self.get_marker(marker_name)
+        if m is None:
+            return None
+        return m.kv.get(key)
+
+    def contains_ordered(self, names: list[str]) -> bool:
+        """Check if marker names appear in order (not necessarily adjacent)."""
+        if not names:
+            return True
+        idx = 0
+        for m in self.markers:
+            if m.name == names[idx]:
+                idx += 1
+                if idx == len(names):
+                    return True
+        return False
+
+    def __str__(self) -> str:
+        lines = []
+        for i, m in enumerate(self.markers):
+            parts = [f"  {i}: {m.name}: {m.context}"]
+            for k, v in m.kv.items():
+                parts.append(f" {k}={v}")
+            lines.append("".join(parts))
+        return "\n".join(lines)

basicami-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: basicami
+Version: 0.1.0
+Summary: AsyncIO-based Asterisk Manager Interface (AMI) client for Python
+Author-email: Andrius Kairiukstis <k@andrius.mobi>
+License: MIT
+Project-URL: Homepage, https://github.com/andrius/asterisk-basicami
+Project-URL: Repository, https://github.com/andrius/asterisk-basicami
+Project-URL: Documentation, https://github.com/andrius/asterisk-basicami/blob/main/README.md
+Project-URL: Bug Reports, https://github.com/andrius/asterisk-basicami/issues
+Keywords: asterisk,ami,pbx,telephony,voip,asyncio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Topic :: Communications :: Internet Phone
+Classifier: Topic :: Communications :: Telephony
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# basicami
+
+AsyncIO-based Asterisk Manager Interface (AMI) client for Python.
+
+Companion to [basicagi](https://github.com/andrius/asterisk-basicagi).
+
+## Install
+
+```bash
+pip install basicami
+```
+
+## Usage
+
+```python
+import asyncio
+from basicami import BasicAMI
+
+async def main():
+    ami = await BasicAMI.connect("localhost", 5038, "admin", "secret")
+
+    # Send any AMI action
+    resp = await ami.send_action({"Action": "Ping"})
+    print(resp)
+
+    # Originate a call
+    resp = await ami.originate(
+        channel="Local/100@from-internal",
+        application="Wait",
+        data="30",
+        caller_id="Test <15550099999>",
+        timeout=30,
+    )
+
+    # Collect events
+    events = await ami.get_events(timeout=2.0)
+    for event in events:
+        print(event)
+
+    await ami.close()
+
+asyncio.run(main())
+```
+
+## Marker Parsing
+
+Includes a marker parser for Asterisk Verbose/Log markers used in PBX testing:
+
+```python
+from basicami import parse_marker, MarkerTrace
+
+marker = parse_marker("SBC_ENTER: 001D tenant=001D-dev-testing")
+print(marker.name)     # "SBC_ENTER"
+print(marker.context)  # "001D"
+print(marker.kv)       # {"tenant": "001D-dev-testing"}
+```
+
+## License
+
+MIT

basicami-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+basicami/__init__.py,sha256=inLUybDEF6pWGeHdsULKogmdzWbk--pot0YKc43wzIk,174
+basicami/basic_ami.py,sha256=Cu0utJGlfvFxB0dlNsbj-cpyEeRFvO2QkZ8tIW4oPxk,7655
+basicami/marker.py,sha256=axUBJ_hkqul-xQUu8uIZxNK4MYH-Yyck53X6Tq6b_ZM,3162
+basicami-0.1.0.dist-info/licenses/LICENSE,sha256=QJt4CycI4R_o_0_QBzzqfQ1urhx8TQpkF30AHKwSJnA,1076
+basicami-0.1.0.dist-info/METADATA,sha256=D0UYklBKP_0EtlO7vqZpiVphfZYRjqDflmoUSwJ88jI,2507
+basicami-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+basicami-0.1.0.dist-info/top_level.txt,sha256=F5_2CastfyA0zwPBKeNHhLGQ9Em2tGAxGPDS23J84Pg,9
+basicami-0.1.0.dist-info/RECORD,,

basicami-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

basicami-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrius Kairiukstis
+
+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.

basicami-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+basicami