tty-egpf-monitor 0.5.26__tar.gz

tty_egpf_monitor-0.5.26/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include examples *.py *.md
+recursive-include tty_egpf_monitor *.py
+exclude tests/*
+exclude .git*
+exclude .pytest_cache
+exclude __pycache__
+exclude *.pyc
+exclude *.pyo

tty_egpf_monitor-0.5.26/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,191 @@
+# 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/examples/README.md

@@ -0,0 +1,137 @@
+# TTY eBPF Monitor Python Examples
+
+This directory contains example scripts demonstrating how to use the TTY eBPF Monitor Python client library.
+
+## Prerequisites
+
+1. **Install the daemon** (if not already installed):
+   ```bash
+   curl -fsSL https://raw.githubusercontent.com/seelso-net/tty-egpf-monitor/main/install.sh | bash
+   ```
+
+2. **Install the Python client**:
+   ```bash
+   pip install tty-egpf-monitor
+   ```
+
+3. **Ensure the daemon is running**:
+   ```bash
+   sudo systemctl status tty-egpf-monitord
+   ```
+
+## Examples
+
+### 1. Basic Usage (`basic_usage.py`)
+
+Demonstrates core functionality of the Python client library:
+- Adding and removing ports
+- Listing configured ports  
+- Getting historical logs
+- Streaming live events
+
+```bash
+python basic_usage.py
+```
+
+### 2. Serial Data Monitoring (`monitor_serial_data.py`)
+
+Advanced example showing real-time monitoring with event processing:
+- Event filtering and categorization
+- Data pattern detection
+- Formatted output with emojis
+- Graceful shutdown handling
+
+```bash
+python monitor_serial_data.py /dev/ttyUSB0
+python monitor_serial_data.py /dev/ttyUSB0 --baudrate 9600
+```
+
+### 3. Automation Script (`automation_script.py`)
+
+Example for automated testing and monitoring:
+- Waiting for device activity
+- Capturing session data
+- Protocol analysis
+- Summary reporting
+
+```bash
+python automation_script.py /dev/ttyUSB0 30
+```
+
+## Library Usage
+
+### Quick Start
+
+```python
+from tty_egpf_monitor import TTYMonitorClient
+
+# Create client
+client = TTYMonitorClient()
+
+# Add a port
+idx = client.add_port("/dev/ttyUSB0", baudrate=115200)
+
+# List 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} by {entry.process}")
+    if entry.data:
+        print(f"  Data: {entry.data}")
+
+# Remove port
+client.remove_port("/dev/ttyUSB0")
+```
+
+### API Reference
+
+#### TTYMonitorClient
+
+- `list_ports()` → `List[Port]`
+- `add_port(device, baudrate=115200, log_path=None)` → `int`
+- `remove_port(port_identifier)` → `bool`
+- `get_logs(port_identifier)` → `str`
+- `stream_logs(port_identifier)` → `Iterator[str]`
+- `stream_parsed_logs(port_identifier)` → `Iterator[LogEntry]`
+- `wait_for_event(port_identifier, event_type, timeout=30.0)` → `Optional[LogEntry]`
+
+#### LogEntry
+
+- `timestamp: datetime`
+- `event_type: str` (OPEN, CLOSE, READ, WRITE, IOCTL, MODE_CHANGE)
+- `process: str`
+- `direction: Optional[str]` (APP->DEV, DEV->APP)
+- `data: Optional[bytes]`
+- `raw_line: str`
+
+## Error Handling
+
+All API methods may raise `TTYMonitorError` for:
+- Connection failures
+- HTTP errors
+- Invalid responses
+- Device not found
+
+```python
+from tty_egpf_monitor import TTYMonitorError
+
+try:
+    client.add_port("/dev/ttyUSB0")
+except TTYMonitorError as e:
+    print(f"Failed to add port: {e}")
+```
+
+## Tips
+
+1. **Run with appropriate permissions**: The daemon runs as root, but the Python client can run as any user with access to the socket.
+
+2. **Handle interrupts gracefully**: Use signal handlers for clean shutdown in long-running scripts.
+
+3. **Device path vs index**: Most methods accept either a device path (`"/dev/ttyUSB0"`) or port index (`0`).
+
+4. **Stream processing**: Use `stream_parsed_logs()` for real-time processing, `get_logs()` for historical data.
+
+5. **Data handling**: Serial data is returned as `bytes` objects, allowing proper handling of binary protocols.