Metadata-Version: 2.4
Name: pypurelinkmatrix
Version: 0.1.0
Summary: Python library for connecting and managing PureLink matrix devices
Project-URL: Homepage, https://github.com/matteogheza/pypurelinkmatrix
Project-URL: Documentation, https://github.com/matteogheza/pypurelinkmatrix?tab=readme-ov-file#usage
Project-URL: Repository, https://github.com/matteogheza/pypurelinkmatrix.git
Project-URL: Issues, https://github.com/matteogheza/pypurelinkmatrix/issues
Author-email: Matteo Gheza <me@matteogheza.it>
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: audiovisual,av-over-ip,broadcast,connection,device,matrix,pro-av,purelink,video-matrix
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Other Audience
Classifier: Intended Audience :: System Administrators
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Python: >=3.9
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: simulator
Requires-Dist: fastapi>=0.100.0; extra == 'simulator'
Requires-Dist: rich>=13.0.0; extra == 'simulator'
Requires-Dist: uvicorn>=0.22.0; extra == 'simulator'
Description-Content-Type: text/markdown

# PyPureLink Matrix

A modern Python library for connecting to and managing PureLink matrix switching devices.

## Features

- 🔐 Secure authentication with base64 encoding
- 🔗 Simple connection management
- ⚙️ Device API client for PureLink matrix devices
- 📝 Full type hints and documentation
- ✅ Input validation following device requirements
- 🎯 Context manager support for automatic resource cleanup

## Installation

### Using UV (recommended)

```bash
uv pip install -e .
```

### Using pip

```bash
pip install -e .
```

## Quick Start

```python
from pypurelinkmatrix import PureLinkClient

# Create a client instance
client = PureLinkClient(
    host="192.168.1.100",
    username="admin",
    password="password123"
)

# Authenticate with the device
try:
    if client.login():
        print("Successfully connected!")
        # Device is now authenticated and ready for commands
except Exception as e:
    print(f"Authentication failed: {e}")

# Always cleanup
client.close()
```

### Using Context Manager (recommended)

```python
from pypurelinkmatrix import PureLinkClient

with PureLinkClient(host="192.168.1.100") as client:
    if client.login("admin", "password123"):
        print("Connected to device")
        # Your code here
```

## Credential Requirements

Based on PureLink device specifications:

- **Username**: 1-15 characters (letters, numbers, underscore only)
- **Password**: 1-15 characters (letters, numbers, underscore only)

## Configuration

Create a `.env` file for sensitive credentials:

```env
PURELINK_HOST=192.168.1.100
PURELINK_USERNAME=admin
PURELINK_PASSWORD=secure_password
```

Then use in your code:

```python
import os
from dotenv import load_dotenv
from pypurelinkmatrix import PureLinkClient

load_dotenv()

client = PureLinkClient(
    host=os.getenv("PURELINK_HOST"),
    username=os.getenv("PURELINK_USERNAME"),
    password=os.getenv("PURELINK_PASSWORD")
)
```

## API Reference

### PureLinkClient

#### Constructor

```python
PureLinkClient(
    host: str,
    username: str = "",
    password: str = "",
    timeout: int = 30,
    use_https: bool = False,
    verify_ssl: bool = True
)
```

- **host**: Device IP address or hostname
- **username**: Username for authentication
- **password**: Password for authentication
- **timeout**: Request timeout in seconds (default: 30)
- **use_https**: Use HTTPS for connection (default: False)
- **verify_ssl**: Verify SSL certificates (default: True)

#### Methods

##### `login(username: Optional[str] = None, password: Optional[str] = None) -> bool`

Authenticate with the PureLink device.

Returns `True` if authentication succeeds.

Raises:
- `ValidationError`: Invalid credential format
- `AuthenticationError`: Authentication failed
- `PureLinkConnectionError`: Cannot connect to device

##### `logout() -> bool`

Logout from the device. Returns `True`.

##### `close() -> None`

Close the client session and cleanup resources.

## Error Handling

```python
from pypurelinkmatrix import PureLinkClient
from pypurelinkmatrix.exceptions import (
    ValidationError,
    AuthenticationError,
    PureLinkConnectionError
)

try:
    client = PureLinkClient(host="192.168.1.100")
    client.login("admin", "password")
except ValidationError as e:
    print(f"Invalid credentials: {e}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except PureLinkConnectionError as e:
    print(f"Cannot connect to device: {e}")
```

## Development

### Setup Development Environment

```bash
# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/pypurelinkmatrix

# Format code
black src tests

# Lint code
ruff check src tests

# Type checking
mypy src/pypurelinkmatrix
```

### Project Structure

```
pypurelinkmatrix/
├── src/pypurelinkmatrix/
│   ├── __init__.py           # Package initialization
│   ├── client.py             # Main connection client
│   └── exceptions.py         # Custom exceptions
├── tests/                    # Test suite
├── examples/                 # Examples
├── pyproject.toml            # Project configuration
└── README.md                 # This file
```

## Contributing

Contributions are welcome! Please ensure:

1. Code passes `black` formatting
2. Code passes `ruff` linting
3. Code passes `mypy` type checking
4. Tests pass with good coverage

## License

MIT License - see LICENSE file for details

## Support

For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/matteogheza/pypurelinkmatrix).

## Special Thanks
Many thanks to:
- PureLink for hardware (and less for their documentation)
- [HTTP Toolkit](https://httptoolkit.com/) for making reverse engineering so much easier
- [Github Copilot](https://github.com/features/copilot) for helping me writing a prototype (and unit testing) faster

## Changelog

### 0.1.0 (2026-01-03)

- Initial release
- Basic connection client implementation
- Login/authentication support
- Input validation following device requirements
- Full type hints and documentation
