tty-egpf-monitor 0.5.26__py3-none-any.whl

tty_egpf_monitor/__init__.py

@@ -0,0 +1,20 @@
+"""
+TTY eBPF Monitor Python Client Library
+
+A Python client library for interacting with the tty-egpf-monitord daemon.
+Provides a clean, Pythonic interface to the HTTP+JSON API over Unix domain sockets.
+"""
+
+from .client import TTYMonitorClient, TTYMonitorError
+from .models import Port, LogEntry
+
+__version__ = "0.5.26"
+__author__ = "TTY eBPF Monitor Team"
+__license__ = "GPL-3.0"
+
+__all__ = [
+    "TTYMonitorClient",
+    "TTYMonitorError", 
+    "Port",
+    "LogEntry",
+]

tty_egpf_monitor/cli.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""
+TTY eBPF Monitor CLI
+
+Command-line interface for the tty-egpf-monitor daemon using the Python client library.
+"""
+
+import argparse
+import sys
+import json
+from typing import Optional
+from .client import TTYMonitorClient, TTYMonitorError
+
+
+def cmd_add(client: TTYMonitorClient, args: argparse.Namespace) -> int:
+    """Add a port to monitor."""
+    try:
+        idx = client.add_port(args.device, args.baudrate, args.logfile)
+        print(json.dumps({"idx": idx}))
+        return 0
+    except TTYMonitorError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_list(client: TTYMonitorClient, args: argparse.Namespace) -> int:
+    """List configured ports."""
+    try:
+        ports = client.list_ports()
+        ports_data = [{"idx": p.idx, "dev": p.device} for p in ports]
+        print(json.dumps(ports_data))
+        return 0
+    except TTYMonitorError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_logs(client: TTYMonitorClient, args: argparse.Namespace) -> int:
+    """Download full log for a port."""
+    try:
+        # Parse port identifier (int or string)
+        port_id = args.port
+        try:
+            port_id = int(port_id)
+        except ValueError:
+            pass  # Keep as string (device path)
+        
+        logs = client.get_logs(port_id)
+        print(logs, end='')  # Don't add extra newline, logs already have them
+        return 0
+    except TTYMonitorError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_stream(client: TTYMonitorClient, args: argparse.Namespace) -> int:
+    """Live stream logs for a port."""
+    try:
+        # Parse port identifier (int or string)
+        port_id = args.port
+        try:
+            port_id = int(port_id)
+        except ValueError:
+            pass  # Keep as string (device path)
+        
+        for line in client.stream_logs(port_id):
+            print(line)
+            sys.stdout.flush()
+        
+        return 0
+    except KeyboardInterrupt:
+        return 0
+    except TTYMonitorError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_remove(client: TTYMonitorClient, args: argparse.Namespace) -> int:
+    """Remove a port from monitoring."""
+    try:
+        # Parse port identifier (int or string)
+        port_id = args.port
+        try:
+            port_id = int(port_id)
+        except ValueError:
+            pass  # Keep as string (device path)
+        
+        success = client.remove_port(port_id)
+        if success:
+            print(json.dumps({"ok": True}))
+            return 0
+        else:
+            print("Error: Remove failed", file=sys.stderr)
+            return 1
+    except TTYMonitorError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def main() -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="TTY eBPF Monitor Python CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  tty-egpf-monitor-py add /dev/ttyUSB0 115200
+  tty-egpf-monitor-py list
+  tty-egpf-monitor-py stream /dev/ttyUSB0
+  tty-egpf-monitor-py logs 0
+  tty-egpf-monitor-py remove /dev/ttyUSB0
+
+For more information, see: https://github.com/seelso-net/tty-egpf-monitor
+"""
+    )
+    
+    parser.add_argument(
+        "--socket",
+        default="/run/tty-egpf-monitord.sock",
+        help="Path to daemon socket (default: %(default)s)"
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # Add command
+    add_parser = subparsers.add_parser("add", help="Add a monitored port")
+    add_parser.add_argument("device", help="Device path (e.g., /dev/ttyUSB0)")
+    add_parser.add_argument("baudrate", nargs="?", type=int, default=115200, help="Baud rate (default: 115200)")
+    add_parser.add_argument("logfile", nargs="?", help="Custom log file path (optional)")
+    
+    # List command
+    subparsers.add_parser("list", help="List configured ports")
+    
+    # Logs command
+    logs_parser = subparsers.add_parser("logs", help="Download full log for a port")
+    logs_parser.add_argument("port", help="Port index or device path")
+    
+    # Stream command
+    stream_parser = subparsers.add_parser("stream", help="Live stream logs for a port")
+    stream_parser.add_argument("port", help="Port index or device path")
+    
+    # Remove command
+    remove_parser = subparsers.add_parser("remove", help="Remove a port from monitoring")
+    remove_parser.add_argument("port", help="Port index or device path")
+    
+    args = parser.parse_args()
+    
+    if not args.command:
+        parser.print_help()
+        return 2
+    
+    # Create client
+    client = TTYMonitorClient(args.socket)
+    
+    # Execute command
+    if args.command == "add":
+        return cmd_add(client, args)
+    elif args.command == "list":
+        return cmd_list(client, args)
+    elif args.command == "logs":
+        return cmd_logs(client, args)
+    elif args.command == "stream":
+        return cmd_stream(client, args)
+    elif args.command == "remove":
+        return cmd_remove(client, args)
+    else:
+        parser.print_help()
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tty_egpf_monitor/client.py

@@ -0,0 +1,324 @@
+"""
+TTY eBPF Monitor Python Client
+
+Provides a Python interface to the tty-egpf-monitord daemon via Unix domain socket.
+"""
+
+import json
+import socket
+import time
+from typing import List, Optional, Iterator, Dict, Any, Union
+from datetime import datetime
+from .models import Port, LogEntry
+
+
+class TTYMonitorError(Exception):
+    """Exception raised for TTY Monitor API errors."""
+    pass
+
+
+class TTYMonitorClient:
+    """Client for interacting with tty-egpf-monitord daemon."""
+    
+    def __init__(self, socket_path: str = "/run/tty-egpf-monitord.sock"):
+        """
+        Initialize the client.
+        
+        Args:
+            socket_path: Path to the daemon's Unix domain socket
+        """
+        self.socket_path = socket_path
+    
+    def _send_http_request(self, method: str, path: str, body: Optional[str] = None) -> str:
+        """Send HTTP request over Unix domain socket and return response body."""
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        try:
+            sock.connect(self.socket_path)
+            
+            # Build HTTP request
+            if body:
+                request = (
+                    f"{method} {path} HTTP/1.1\r\n"
+                    f"Host: localhost\r\n"
+                    f"Content-Type: application/json\r\n"
+                    f"Content-Length: {len(body)}\r\n"
+                    f"Connection: close\r\n"
+                    f"\r\n"
+                    f"{body}"
+                )
+            else:
+                request = (
+                    f"{method} {path} HTTP/1.1\r\n"
+                    f"Host: localhost\r\n"
+                    f"Connection: close\r\n"
+                    f"\r\n"
+                )
+            
+            sock.sendall(request.encode())
+            
+            # Read response
+            response = b""
+            while True:
+                chunk = sock.recv(4096)
+                if not chunk:
+                    break
+                response += chunk
+            
+            response_str = response.decode('utf-8')
+            
+            # Parse HTTP response
+            if '\r\n\r\n' not in response_str:
+                raise TTYMonitorError("Invalid HTTP response")
+            
+            headers, body = response_str.split('\r\n\r\n', 1)
+            
+            # Check status code
+            status_line = headers.split('\r\n')[0]
+            if not status_line.startswith('HTTP/1.1 2'):
+                # Extract error message from body if available
+                error_msg = body.strip() if body else "Request failed"
+                raise TTYMonitorError(f"HTTP error: {status_line} - {error_msg}")
+            
+            return body
+            
+        except socket.error as e:
+            raise TTYMonitorError(f"Socket error: {e}")
+        finally:
+            sock.close()
+    
+    def list_ports(self) -> List[Port]:
+        """
+        List all configured ports.
+        
+        Returns:
+            List of Port objects
+        """
+        body = self._send_http_request("GET", "/ports")
+        try:
+            ports_data = json.loads(body)
+            return [Port.from_dict(port_data) for port_data in ports_data]
+        except json.JSONDecodeError as e:
+            raise TTYMonitorError(f"Invalid JSON response: {e}")
+    
+    def add_port(self, device: str, baudrate: int = 115200, log_path: Optional[str] = None) -> int:
+        """
+        Add a port to monitor.
+        
+        Args:
+            device: Device path (e.g., "/dev/ttyUSB0")
+            baudrate: Baud rate (default: 115200)
+            log_path: Custom log path (optional)
+        
+        Returns:
+            Port index
+        """
+        request_data = {
+            "dev": device,
+            "log": log_path or "",
+            "baudrate": baudrate
+        }
+        
+        body = self._send_http_request("POST", "/ports", json.dumps(request_data))
+        try:
+            response = json.loads(body)
+            idx = response["idx"]
+            if not isinstance(idx, int):
+                raise TTYMonitorError(f"Invalid idx type: {type(idx)}")
+            return idx
+        except (json.JSONDecodeError, KeyError) as e:
+            raise TTYMonitorError(f"Invalid response: {e}")
+    
+    def remove_port(self, port_identifier: Union[str, int]) -> bool:
+        """
+        Remove a port from monitoring.
+        
+        Args:
+            port_identifier: Port index (int) or device path (str)
+        
+        Returns:
+            True if successful
+        """
+        if isinstance(port_identifier, int):
+            # Remove by index
+            body = self._send_http_request("DELETE", f"/ports/{port_identifier}")
+        else:
+            # Remove by device path
+            request_data = {"dev": str(port_identifier)}
+            body = self._send_http_request("DELETE", "/ports", json.dumps(request_data))
+        
+        try:
+            response = json.loads(body)
+            ok_value = response.get("ok", False)
+            return bool(ok_value)
+        except json.JSONDecodeError:
+            return False
+    
+    def get_logs(self, port_identifier: Union[str, int]) -> str:
+        """
+        Download full log for a port.
+        
+        Args:
+            port_identifier: Port index (int) or device path (str)
+        
+        Returns:
+            Raw log content
+        """
+        if isinstance(port_identifier, str):
+            # Resolve device path to index
+            ports = self.list_ports()
+            idx = None
+            for port in ports:
+                if port.device == port_identifier:
+                    idx = port.idx
+                    break
+            if idx is None:
+                raise TTYMonitorError(f"Device not found: {port_identifier}")
+        else:
+            idx = port_identifier
+        
+        return self._send_http_request("GET", f"/logs/{idx}")
+    
+    def parse_logs(self, log_content: str) -> List[LogEntry]:
+        """
+        Parse log content into LogEntry objects.
+        
+        Args:
+            log_content: Raw log content from get_logs()
+        
+        Returns:
+            List of parsed LogEntry objects
+        """
+        entries = []
+        for line in log_content.strip().split('\n'):
+            if line.strip():
+                try:
+                    entry = LogEntry.parse_simple_log(line)
+                    entries.append(entry)
+                except Exception:
+                    # If parsing fails, create a basic entry with raw line
+                    entries.append(LogEntry(
+                        timestamp=datetime.now(),
+                        event_type="UNPARSED",
+                        process="",
+                        raw_line=line.strip()
+                    ))
+        return entries
+    
+    def stream_logs(self, port_identifier: Union[str, int]) -> Iterator[str]:
+        """
+        Stream live logs for a port.
+        
+        Args:
+            port_identifier: Port index (int) or device path (str)
+        
+        Yields:
+            Log lines as they arrive
+        """
+        if isinstance(port_identifier, str):
+            # Resolve device path to index
+            ports = self.list_ports()
+            idx = None
+            for port in ports:
+                if port.device == port_identifier:
+                    idx = port.idx
+                    break
+            if idx is None:
+                raise TTYMonitorError(f"Device not found: {port_identifier}")
+        else:
+            idx = port_identifier
+        
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        try:
+            sock.connect(self.socket_path)
+            
+            # Send streaming request
+            request = (
+                f"GET /stream/{idx} HTTP/1.1\r\n"
+                f"Host: localhost\r\n"
+                f"Connection: close\r\n"
+                f"\r\n"
+            )
+            sock.sendall(request.encode())
+            
+            # Read response headers
+            headers = b""
+            while b'\r\n\r\n' not in headers:
+                chunk = sock.recv(1)
+                if not chunk:
+                    raise TTYMonitorError("Connection closed while reading headers")
+                headers += chunk
+            
+            # Check status
+            headers_str = headers.decode('utf-8')
+            if not headers_str.startswith('HTTP/1.1 200'):
+                raise TTYMonitorError(f"Stream failed: {headers_str.split()[1]}")
+            
+            # Read chunked response
+            buffer = b""
+            while True:
+                chunk = sock.recv(4096)
+                if not chunk:
+                    break
+                
+                buffer += chunk
+                
+                # Process complete lines
+                while b'\n' in buffer:
+                    line, buffer = buffer.split(b'\n', 1)
+                    line_str = line.decode('utf-8', errors='replace').strip()
+                    
+                    # Skip HTTP chunked encoding artifacts
+                    if line_str and not line_str.isdigit() and line_str != '0':
+                        # Skip chunked encoding hex numbers and empty lines
+                        if not all(c in '0123456789abcdefABCDEF' for c in line_str):
+                            yield line_str
+        
+        except socket.error as e:
+            raise TTYMonitorError(f"Socket error: {e}")
+        finally:
+            sock.close()
+    
+    def stream_parsed_logs(self, port_identifier: Union[str, int]) -> Iterator[LogEntry]:
+        """
+        Stream live logs for a port, parsed into LogEntry objects.
+        
+        Args:
+            port_identifier: Port index (int) or device path (str)
+        
+        Yields:
+            Parsed LogEntry objects as they arrive
+        """
+        for line in self.stream_logs(port_identifier):
+            try:
+                yield LogEntry.parse_simple_log(line)
+            except Exception:
+                # If parsing fails, yield raw entry
+                yield LogEntry(
+                    timestamp=datetime.now(),
+                    event_type="UNPARSED",
+                    process="",
+                    raw_line=line
+                )
+    
+    def wait_for_event(self, port_identifier: Union[str, int], event_type: str, timeout: float = 30.0) -> Optional[LogEntry]:
+        """
+        Wait for a specific event type on a port.
+        
+        Args:
+            port_identifier: Port index (int) or device path (str)
+            event_type: Event type to wait for (e.g., "OPEN", "WRITE", "READ")
+            timeout: Maximum time to wait in seconds
+        
+        Returns:
+            LogEntry if event found, None if timeout
+        """
+        start_time = time.time()
+        
+        for entry in self.stream_parsed_logs(port_identifier):
+            if entry.event_type == event_type:
+                return entry
+            
+            if time.time() - start_time > timeout:
+                break
+        
+        return None

tty_egpf_monitor/models.py

@@ -0,0 +1,141 @@
+"""
+Data models for TTY eBPF Monitor client.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Dict, Any
+from datetime import datetime
+
+
+@dataclass
+class Port:
+    """Represents a monitored TTY port."""
+    idx: int
+    device: str
+    baudrate: Optional[int] = None
+    log_path: Optional[str] = None
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Port':
+        """Create Port from daemon response dictionary."""
+        return cls(
+            idx=data['idx'],
+            device=data['dev'],
+            baudrate=data.get('baudrate'),
+            log_path=data.get('log_path')
+        )
+
+
+@dataclass 
+class LogEntry:
+    """Represents a single log entry from the TTY monitor."""
+    timestamp: datetime
+    event_type: str
+    process: str
+    direction: Optional[str] = None
+    data: Optional[bytes] = None
+    baudrate: Optional[int] = None
+    ioctl_cmd: Optional[int] = None
+    raw_line: str = ""
+    
+    @classmethod
+    def parse_simple_log(cls, line: str) -> 'LogEntry':
+        """Parse a simple format log line."""
+        import re
+        
+        # Parse format: [04.09.25 14:52:46.874] WRITE: picocom APP->DEV "data"
+        pattern = r'\[(\d{2}\.\d{2}\.\d{2}) (\d{2}:\d{2}:\d{2}\.\d{3})\] (\w+): (\w+)(?: (APP->DEV|DEV->APP))?(?: (.*))?'
+        match = re.match(pattern, line.strip())
+        
+        if not match:
+            # Fallback for other formats like MODE_CHANGE
+            pattern2 = r'\[(\d{2}\.\d{2}\.\d{2}) (\d{2}:\d{2}:\d{2}\.\d{3})\] (\w+): (.*)'
+            match2 = re.match(pattern2, line.strip())
+            if match2:
+                date_str, time_str, event_type, details = match2.groups()
+                timestamp = cls._parse_datetime(date_str, time_str)
+                return cls(
+                    timestamp=timestamp,
+                    event_type=event_type,
+                    process=details.split()[0] if details else "",
+                    raw_line=line.strip()
+                )
+            
+            # If no pattern matches, return basic entry
+            return cls(
+                timestamp=datetime.now(),
+                event_type="UNKNOWN",
+                process="",
+                raw_line=line.strip()
+            )
+        
+        date_str, time_str, event_type, process, direction, data_part = match.groups()
+        timestamp = cls._parse_datetime(date_str, time_str)
+        
+        # Parse data if present (quoted string with escapes)
+        data = None
+        if data_part and data_part.startswith('"') and data_part.endswith('"'):
+            data_str = data_part[1:-1]  # Remove quotes
+            # Decode escape sequences
+            data = cls._decode_escaped_data(data_str)
+        
+        return cls(
+            timestamp=timestamp,
+            event_type=event_type,
+            process=process,
+            direction=direction,
+            data=data,
+            raw_line=line.strip()
+        )
+    
+    @staticmethod
+    def _parse_datetime(date_str: str, time_str: str) -> datetime:
+        """Parse dd.mm.yy HH:MM:SS.mmm format."""
+        from datetime import datetime
+        
+        # Parse date: dd.mm.yy
+        day_str, month_str, year_str = date_str.split('.')
+        year_int = int('20' + year_str)  # Convert yy to 20yy
+        
+        # Parse time: HH:MM:SS.mmm
+        time_part, ms_part = time_str.split('.')
+        hour_str, minute_str, second_str = time_part.split(':')
+        
+        return datetime(
+            year=year_int,
+            month=int(month_str),
+            day=int(day_str),
+            hour=int(hour_str),
+            minute=int(minute_str),
+            second=int(second_str),
+            microsecond=int(ms_part) * 1000  # Convert ms to microseconds
+        )
+    
+    @staticmethod
+    def _decode_escaped_data(data_str: str) -> bytes:
+        """Decode escaped data string to bytes."""
+        result = bytearray()
+        i = 0
+        while i < len(data_str):
+            if data_str[i] == '\\' and i + 1 < len(data_str):
+                if data_str[i + 1] == 'x' and i + 3 < len(data_str):
+                    # Hex escape: \xNN
+                    try:
+                        hex_val = int(data_str[i+2:i+4], 16)
+                        result.append(hex_val)
+                        i += 4
+                    except ValueError:
+                        result.append(ord(data_str[i]))
+                        i += 1
+                elif data_str[i + 1] in ['\\', '"']:
+                    # Escaped backslash or quote
+                    result.append(ord(data_str[i + 1]))
+                    i += 2
+                else:
+                    result.append(ord(data_str[i]))
+                    i += 1
+            else:
+                result.append(ord(data_str[i]))
+                i += 1
+        
+        return bytes(result)

tty_egpf_monitor/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This package supports type hints

tty_egpf_monitor-0.5.26.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: tty-egpf-monitor
+Version: 0.5.26
+Summary: Python client library for TTY eBPF Monitor daemon
+Home-page: https://github.com/seelso-net/tty-egpf-monitor
+Author: TTY eBPF Monitor Team
+Author-email: TTY eBPF Monitor Team <contact@seelso.net>
+Maintainer-email: TTY eBPF Monitor Team <contact@seelso.net>
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/seelso-net/tty-egpf-monitor
+Project-URL: Documentation, https://github.com/seelso-net/tty-egpf-monitor/blob/main/README.md
+Project-URL: Repository, https://github.com/seelso-net/tty-egpf-monitor
+Project-URL: Bug Tracker, https://github.com/seelso-net/tty-egpf-monitor/issues
+Project-URL: APT Repository, https://seelso-net.github.io/tty-egpf-monitor
+Keywords: serial,tty,monitoring,ebpf,uart,debugging,reverse-engineering,protocol-analysis,hardware
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Terminals :: Serial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# TTY eBPF Monitor Python Client
+
+[![PyPI version](https://badge.fury.io/py/tty-egpf-monitor.svg)](https://badge.fury.io/py/tty-egpf-monitor)
+[![Python](https://img.shields.io/pypi/pyversions/tty-egpf-monitor.svg)](https://pypi.org/project/tty-egpf-monitor/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+A Python client library for [TTY eBPF Monitor](https://github.com/seelso-net/tty-egpf-monitor), providing a clean, Pythonic interface to monitor serial port activity using eBPF technology.
+
+## Features
+
+- 🐍 **Pure Python** - No C dependencies, works with any Python 3.8+
+- 🔌 **Unix Socket API** - Communicates with daemon via Unix domain socket
+- 📊 **Parsed Log Entries** - Automatic parsing of log format with timestamps
+- 🔄 **Live Streaming** - Real-time event streaming with iterator interface  
+- 🛠️ **CLI Wrapper** - Drop-in replacement for the C CLI tool
+- 📚 **Rich Examples** - Comprehensive examples for common use cases
+- 🔍 **Data Analysis** - Built-in support for protocol analysis and debugging
+
+## Installation
+
+### Install from PyPI
+
+```bash
+pip install tty-egpf-monitor
+```
+
+### Install the Daemon
+
+The Python client requires the `tty-egpf-monitord` daemon to be running:
+
+```bash
+# Install daemon via APT repository
+curl -fsSL https://raw.githubusercontent.com/seelso-net/tty-egpf-monitor/main/install.sh | bash
+
+# Or install manually
+CODENAME=$(lsb_release -cs)
+REPO_URL=https://seelso-net.github.io/tty-egpf-monitor
+curl -fsSL ${REPO_URL}/public-apt-key.asc | sudo gpg --dearmor -o /usr/share/keyrings/tty-egpf-monitor.gpg
+echo "deb [signed-by=/usr/share/keyrings/tty-egpf-monitor.gpg] ${REPO_URL} ${CODENAME} main" | sudo tee /etc/apt/sources.list.d/tty-egpf-monitor.list
+sudo apt-get update && sudo apt-get install -y tty-egpf-monitord
+sudo systemctl enable --now tty-egpf-monitord
+```
+
+## Quick Start
+
+### Library Usage
+
+```python
+from tty_egpf_monitor import TTYMonitorClient
+
+# Create client
+client = TTYMonitorClient()
+
+# Add a port to monitor
+idx = client.add_port("/dev/ttyUSB0", baudrate=115200)
+print(f"Monitoring port {idx}")
+
+# List all ports
+ports = client.list_ports()
+for port in ports:
+    print(f"Port {port.idx}: {port.device}")
+
+# Stream live events
+for entry in client.stream_parsed_logs("/dev/ttyUSB0"):
+    print(f"[{entry.timestamp}] {entry.event_type}: {entry.process}")
+    if entry.data:
+        print(f"  Data: {entry.data}")
+
+# Remove port when done
+client.remove_port("/dev/ttyUSB0")
+```
+
+### CLI Usage
+
+The package includes a CLI tool compatible with the C version:
+
+```bash
+# Add a port
+tty-egpf-monitor-py add /dev/ttyUSB0 115200
+
+# List ports
+tty-egpf-monitor-py list
+
+# Stream logs (by index or device path)
+tty-egpf-monitor-py stream 0
+tty-egpf-monitor-py stream /dev/ttyUSB0
+
+# Download logs
+tty-egpf-monitor-py logs /dev/ttyUSB0 > captured.jsonl
+
+# Remove port
+tty-egpf-monitor-py remove /dev/ttyUSB0
+```
+
+## API Reference
+
+### TTYMonitorClient
+
+#### Methods
+
+- **`list_ports()`** → `List[Port]`
+  
+  List all configured ports.
+
+- **`add_port(device, baudrate=115200, log_path=None)`** → `int`
+  
+  Add a port to monitor. Returns the port index.
+
+- **`remove_port(port_identifier)`** → `bool`
+  
+  Remove a port by index (int) or device path (str).
+
+- **`get_logs(port_identifier)`** → `str`
+  
+  Download full log content for a port.
+
+- **`stream_logs(port_identifier)`** → `Iterator[str]`
+  
+  Stream raw log lines as they arrive.
+
+- **`stream_parsed_logs(port_identifier)`** → `Iterator[LogEntry]`
+  
+  Stream parsed log entries as they arrive.
+
+- **`wait_for_event(port_identifier, event_type, timeout=30.0)`** → `Optional[LogEntry]`
+  
+  Wait for a specific event type with timeout.
+
+### LogEntry
+
+Represents a parsed log entry:
+
+```python
+@dataclass
+class LogEntry:
+    timestamp: datetime      # When the event occurred
+    event_type: str         # OPEN, CLOSE, READ, WRITE, IOCTL, MODE_CHANGE
+    process: str            # Process name that triggered the event
+    direction: Optional[str] # APP->DEV or DEV->APP (for READ/write)
+    data: Optional[bytes]   # Raw data (for read/write events)
+    raw_line: str          # Original log line
+```
+
+### Port
+
+Represents a monitored port:
+
+```python
+@dataclass  
+class Port:
+    idx: int                    # Port index
+    device: str                # Device path
+    baudrate: Optional[int]     # Configured baud rate
+    log_path: Optional[str]     # Log file path
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory for comprehensive usage examples:
+
+- **`basic_usage.py`** - Core functionality demonstration
+- **`monitor_serial_data.py`** - Real-time monitoring with processing
+- **`automation_script.py`** - Automated testing and analysis
+
+## Error Handling
+
+```python
+from tty_egpf_monitor import TTYMonitorError
+
+try:
+    client = TTYMonitorClient()
+    client.add_port("/dev/ttyUSB0")
+except TTYMonitorError as e:
+    print(f"Error: {e}")
+```
+
+## Requirements
+
+- **Python**: 3.8 or later
+- **Operating System**: Linux (Ubuntu 22.04+ recommended)
+- **Daemon**: `tty-egpf-monitord` must be installed and running
+- **Permissions**: Access to the daemon's Unix socket (usually `/run/tty-egpf-monitord.sock`)
+
+## Related Projects
+
+- **[TTY eBPF Monitor](https://github.com/seelso-net/tty-egpf-monitor)** - Main project with C daemon and CLI
+- **[APT Repository](https://seelso-net.github.io/tty-egpf-monitor)** - Binary packages for Ubuntu
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](https://github.com/seelso-net/tty-egpf-monitor/blob/main/LICENSE) file for details.

tty_egpf_monitor-0.5.26.dist-info/RECORD

@@ -0,0 +1,10 @@
+tty_egpf_monitor/__init__.py,sha256=fDYuwC4Fuu_EHgK8s08RiQmS_SaJdahFUKgyRGntI2M,473
+tty_egpf_monitor/cli.py,sha256=1QF1YS-uCowrUEFsYdmdwAqxOdmz94hvddlpljBYgng,5255
+tty_egpf_monitor/client.py,sha256=CZWZhdsYgMeUZwX-0yg53A-4qEx8wrfzJ6r5nVTUp18,10999
+tty_egpf_monitor/models.py,sha256=luhXtyXfQg1h8QYMiSTTaIG7BOfXX-QtNo6t0Yx1M4Y,4826
+tty_egpf_monitor/py.typed,sha256=UlkhTBVJqiS1Epx-KILVobCtCGlhR6YKM79R8vO1HdU,61
+tty_egpf_monitor-0.5.26.dist-info/METADATA,sha256=2z6OmNdCCMJBCbghGZnrT1JKEnzyxNHOcDLHXu_tW9k,7776
+tty_egpf_monitor-0.5.26.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tty_egpf_monitor-0.5.26.dist-info/entry_points.txt,sha256=l1X-FXgjKnh6pmOe16MjBN-9sww3FKFuknTy16IFW2s,66
+tty_egpf_monitor-0.5.26.dist-info/top_level.txt,sha256=uXb0ct7ljNig6oqHa1nVH-TkoURcJ0_uLf2q8SUJaQs,17
+tty_egpf_monitor-0.5.26.dist-info/RECORD,,

tty_egpf_monitor-0.5.26.dist-info/WHEEL

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

tty_egpf_monitor-0.5.26.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tty-egpf-monitor-py = tty_egpf_monitor.cli:main

tty_egpf_monitor-0.5.26.dist-info/top_level.txt

@@ -0,0 +1 @@
+tty_egpf_monitor