sipx 0.0.4__py3-none-any.whl

sipx/__init__.py

@@ -0,0 +1,299 @@
+"""
+sipx — Modern SIP library for Python.
+
+Quick Start:
+    >>> import sipx
+    >>> r = sipx.register("sip:alice@pbx.com", auth=("alice", "secret"))
+    >>> r = sipx.options("sip:pbx.com")
+
+With Client:
+    >>> from sipx import Client, Events, on, SDPBody
+    >>>
+    >>> class MyEvents(Events):
+    ...     @on('INVITE', status=200)
+    ...     def on_call(self, request, response, context):
+    ...         print("Call accepted!")
+    ...
+    >>> with Client() as client:
+    ...     client.auth = ("alice", "secret")
+    ...     client.events = MyEvents()
+    ...     r = client.invite("sip:bob@pbx.com", body=SDPBody.audio("10.0.0.1", 8000).to_string())
+
+Server with DI:
+    >>> from sipx import SIPServer, Request, Response, SDPBody, FromHeader, SDP
+    >>> from typing import Annotated
+    >>>
+    >>> server = SIPServer(port=5060)
+    >>> @server.invite
+    ... def on_invite(request: Request, caller: Annotated[str, FromHeader]) -> Response:
+    ...     return Response(200)
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+# ============================================================================
+# Client / Server
+# ============================================================================
+
+from .client import Client, AsyncClient
+from .server import SIPServer
+
+# ============================================================================
+# Events
+# ============================================================================
+
+from ._events import Events, EventContext, event_handler, on
+
+# ============================================================================
+# Models
+# ============================================================================
+
+from .models import (
+    SIPMessage,
+    Request,
+    Response,
+    MessageParser,
+    Headers,
+    HeaderParser,
+    HeaderContainer,
+    MessageBody,
+    RawBody,
+    SDPBody,
+    BodyParser,
+    Auth,
+    SipAuthCredentials,
+    AuthMethod,
+    DigestAuth,
+    DigestChallenge,
+    DigestCredentials,
+    Challenge,
+    Credentials,
+    AuthParser,
+)
+
+# ============================================================================
+# DI Extractors
+# ============================================================================
+
+from ._depends import (
+    Extractor,
+    FromHeader,
+    ToHeader,
+    CallID,
+    CSeqValue,
+    ViaValue,
+    SDP,
+    Source,
+    Header,
+    AutoRTP,
+    resolve_handler,
+)
+
+# ============================================================================
+# URI
+# ============================================================================
+
+from ._uri import SipURI
+from .session import AsyncSessionTimer, SessionTimer, SessionTimerConfig
+from ._routing import RouteSet
+from .dns import SipResolver, ResolvedTarget
+from .session import AsyncSubscription, Subscription, SubscriptionState
+
+# ============================================================================
+# FSM
+# ============================================================================
+
+from .fsm import AsyncTimerManager, Dialog, StateManager, TimerManager, Transaction
+
+# ============================================================================
+# Transport
+# ============================================================================
+
+from .transports import (
+    BaseTransport,
+    AsyncBaseTransport,
+    TransportAddress,
+    TransportConfig,
+    TransportError,
+)
+
+# ============================================================================
+# Types
+# ============================================================================
+
+from ._types import (
+    DialogState,
+    TransactionState,
+    TransactionType,
+    HeaderTypes,
+    ConnectionError,
+    ReadError,
+    WriteError,
+    TimeoutError,
+)
+
+# ============================================================================
+# Version
+# ============================================================================
+
+from ._version import __version__
+
+
+# ============================================================================
+# One-liner functions (httpx-style)
+# ============================================================================
+
+
+def register(
+    aor: str,
+    *,
+    auth: Optional[tuple[str, str]] = None,
+    transport: str = "UDP",
+    expires: int = 3600,
+) -> Response:
+    """Register with a SIP server.
+
+    >>> r = sipx.register("sip:alice@pbx.com", auth=("alice", "secret"))
+    """
+    with Client(transport=transport, auto_auth=bool(auth)) as client:
+        if auth:
+            client.auth = auth
+        return client.register(aor, expires=expires)
+
+
+def options(
+    uri: str,
+    *,
+    auth: Optional[tuple[str, str]] = None,
+    transport: str = "UDP",
+) -> Response:
+    """Query server capabilities.
+
+    >>> r = sipx.options("sip:pbx.com")
+    """
+    with Client(transport=transport, auto_auth=bool(auth)) as client:
+        if auth:
+            client.auth = auth
+        return client.options(uri)
+
+
+def call(
+    uri: str,
+    *,
+    auth: Optional[tuple[str, str]] = None,
+    transport: str = "UDP",
+    body: Optional[str] = None,
+) -> Response:
+    """Make a SIP call (INVITE).
+
+    >>> r = sipx.call("sip:100@pbx.com", auth=("alice", "secret"))
+    """
+    with Client(transport=transport, auto_auth=bool(auth)) as client:
+        if auth:
+            client.auth = auth
+        return client.invite(to_uri=uri, body=body)
+
+
+def send(
+    uri: str,
+    content: str = "",
+    *,
+    auth: Optional[tuple[str, str]] = None,
+    transport: str = "UDP",
+) -> Response:
+    """Send a SIP MESSAGE.
+
+    >>> r = sipx.send("sip:bob@pbx.com", "Hello!", auth=("alice", "secret"))
+    """
+    with Client(transport=transport, auto_auth=bool(auth)) as client:
+        if auth:
+            client.auth = auth
+        return client.message(to_uri=uri, content=content)
+
+
+# ============================================================================
+# Public API
+# ============================================================================
+
+__all__ = [
+    # ------ Main API ------
+    "Client",
+    "AsyncClient",
+    "SIPServer",
+    "SipURI",
+    "AsyncSessionTimer",
+    "SessionTimer",
+    "SessionTimerConfig",
+    "RouteSet",
+    "SipResolver",
+    "ResolvedTarget",
+    "AsyncSubscription",
+    "Subscription",
+    "SubscriptionState",
+    "Events",
+    "EventContext",
+    "event_handler",
+    "on",
+    "__version__",
+    # ------ One-liners ------
+    "register",
+    "options",
+    "call",
+    "send",
+    # ------ Auth ------
+    "Auth",
+    "SipAuthCredentials",
+    # ------ Models ------
+    "Request",
+    "Response",
+    "SDPBody",
+    "Headers",
+    # ------ DI Extractors ------
+    "Extractor",
+    "FromHeader",
+    "ToHeader",
+    "CallID",
+    "CSeqValue",
+    "ViaValue",
+    "SDP",
+    "Source",
+    "Header",
+    "AutoRTP",
+    # ------ Transport ------
+    "BaseTransport",
+    "TransportAddress",
+    "TransportConfig",
+    "TransportError",
+    # ------ Advanced ------
+    "SIPMessage",
+    "MessageParser",
+    "HeaderParser",
+    "HeaderContainer",
+    "MessageBody",
+    "RawBody",
+    "BodyParser",
+    "AuthMethod",
+    "DigestAuth",
+    "DigestChallenge",
+    "DigestCredentials",
+    "Challenge",
+    "Credentials",
+    "AuthParser",
+    "AsyncBaseTransport",
+    "StateManager",
+    "AsyncTimerManager",
+    "TimerManager",
+    "Transaction",
+    "Dialog",
+    "TransactionState",
+    "DialogState",
+    "TransactionType",
+    "HeaderTypes",
+    "ConnectionError",
+    "ReadError",
+    "WriteError",
+    "TimeoutError",
+    "resolve_handler",
+]

sipx/_depends.py

@@ -0,0 +1,219 @@
+"""
+Dependency injection extractors for SIP server handlers.
+
+Provides an Extractor ABC and built-in extractors that resolve handler
+parameters from SIP requests via ``typing.Annotated`` metadata, similar
+to FastAPI's ``Depends``.
+
+Example::
+
+    from typing import Annotated
+    from sipx._depends import FromHeader, SDP, AutoRTP
+
+    @server.invite
+    def on_invite(
+        request: Request,
+        caller: Annotated[str, FromHeader()],
+        sdp: Annotated[SDPBody, SDP()],
+        rtp: Annotated[RTPSession, AutoRTP(port=19000)],
+    ) -> Response:
+        ...
+"""
+
+from __future__ import annotations
+
+import typing
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ._utils import logger
+from .models._message import Request
+from ._types import TransportAddress
+
+_log = logger.getChild("di")
+
+
+# ============================================================================
+# Base Extractor
+# ============================================================================
+
+
+class Extractor(ABC):
+    """Abstract base class for dependency injection extractors.
+
+    Subclass and implement ``extract`` to create custom extractors
+    usable with ``typing.Annotated``.
+    """
+
+    @abstractmethod
+    def extract(self, request: Request, source: TransportAddress) -> Any:
+        """Extract a value from a SIP request and transport source."""
+        ...
+
+    @classmethod
+    def resolve_handler(
+        cls, handler: Any, request: Request, source: TransportAddress
+    ) -> Any:
+        """Inspect handler type hints and inject dependencies.
+
+        Resolves ``Annotated[X, <Extractor>]`` metadata, ``Request`` and
+        ``TransportAddress`` type hints. Falls back to ``handler(request, source)``.
+        """
+        import inspect
+
+        _log.debug("Resolving handler %s", getattr(handler, "__name__", handler))
+        hints = typing.get_type_hints(handler, include_extras=True)
+        kwargs: dict[str, Any] = {}
+
+        for name, hint in hints.items():
+            if name == "return":
+                continue
+            if hint is Request or (
+                hasattr(hint, "__name__") and hint.__name__ == "Request"
+            ):
+                kwargs[name] = request
+                continue
+            if hint is TransportAddress:
+                kwargs[name] = source
+                continue
+            if hasattr(hint, "__metadata__"):
+                for meta in hint.__metadata__:
+                    if isinstance(meta, cls):
+                        _log.debug("Extracting %s via %s", name, type(meta).__name__)
+                        kwargs[name] = meta.extract(request, source)
+                        break
+                    if isinstance(meta, type) and issubclass(meta, cls):
+                        _log.debug("Extracting %s via %s()", name, meta.__name__)
+                        kwargs[name] = meta().extract(request, source)
+                        break
+
+        if not kwargs:
+            return handler(request, source)
+
+        sig = inspect.signature(handler)
+        positional = [p.name for p in sig.parameters.values() if p.name != "return"]
+        for i, name in enumerate(positional):
+            if name not in kwargs:
+                if i == 0:
+                    kwargs[name] = request
+                elif i == 1:
+                    kwargs[name] = source
+
+        return handler(**kwargs)
+
+
+# ============================================================================
+# Built-in Extractors
+# ============================================================================
+
+
+class FromHeader(Extractor):
+    """Extract the ``From`` header value."""
+
+    def extract(self, request: Request, source: TransportAddress) -> str | None:
+        return request.from_header
+
+
+class ToHeader(Extractor):
+    """Extract the ``To`` header value."""
+
+    def extract(self, request: Request, source: TransportAddress) -> str | None:
+        return request.to_header
+
+
+class CallID(Extractor):
+    """Extract the ``Call-ID`` header value."""
+
+    def extract(self, request: Request, source: TransportAddress) -> str | None:
+        return request.call_id
+
+
+class CSeqValue(Extractor):
+    """Extract the ``CSeq`` header value."""
+
+    def extract(self, request: Request, source: TransportAddress) -> str | None:
+        return request.cseq
+
+
+class ViaValue(Extractor):
+    """Extract the ``Via`` header value."""
+
+    def extract(self, request: Request, source: TransportAddress) -> str | None:
+        return request.via
+
+
+class SDP(Extractor):
+    """Extract the lazily-parsed SDP body (``SDPBody`` or ``None``)."""
+
+    def extract(self, request: Request, source: TransportAddress) -> Any:
+        return request.body
+
+
+class Source(Extractor):
+    """Extract the ``TransportAddress`` the request arrived from."""
+
+    def extract(self, request: Request, source: TransportAddress) -> TransportAddress:
+        return source
+
+
+class Header(Extractor):
+    """Extract an arbitrary header by name.
+
+    Args:
+        name: The header name to look up.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def extract(self, request: Request, source: TransportAddress) -> str | None:
+        return request.headers.get(self.name)
+
+
+class AutoRTP(Extractor):
+    """Create an ``RTPSession`` from the request SDP automatically.
+
+    Args:
+        port: Local RTP port to bind.
+    """
+
+    def __init__(self, port: int) -> None:
+        self.port = port
+
+    def extract(self, request: Request, source: TransportAddress) -> Any:
+        from .media._rtp import RTPSession
+        from .models._body import SDPBody
+
+        body = request.body
+        if isinstance(body, SDPBody):
+            return RTPSession.from_sdp(body, source.host, self.port)
+        return None
+
+
+# ============================================================================
+# Handler Resolver
+# ============================================================================
+
+
+def resolve_handler(handler: Any, request: Request, source: TransportAddress) -> Any:
+    """Shortcut for Extractor.resolve_handler()."""
+    return Extractor.resolve_handler(handler, request, source)
+
+
+# ============================================================================
+# Exports
+# ============================================================================
+
+__all__ = [
+    "Extractor",
+    "FromHeader",
+    "ToHeader",
+    "CallID",
+    "CSeqValue",
+    "ViaValue",
+    "SDP",
+    "Source",
+    "Header",
+    "AutoRTP",
+    "resolve_handler",
+]