Metadata-Version: 2.4
Name: power_switch_pro
Version: 0.1.0
Summary: Python library for Digital Loggers Power Switch Pro REST API
Home-page: https://github.com/bryan/power_switch_pro
Author: Bryan Kemp
Author-email: Bryan Kemp <bryan@kempville.com>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/bryankemp/power_switch_pro
Project-URL: Documentation, https://power-switch-pro.readthedocs.io
Project-URL: Repository, https://github.com/bryankemp/power_switch_pro
Project-URL: Issues, https://github.com/bryankemp/power_switch_pro/issues
Keywords: power,switch,digital-loggers,automation,pdu
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Hardware
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: responses>=0.22.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: ruff>=0.0.200; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.7.0; extra == "dev"
Requires-Dist: safety>=2.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Power Switch Pro Python Library

[![PyPI version](https://badge.fury.io/py/power-switch-pro.svg)](https://badge.fury.io/py/power-switch-pro)
[![Python versions](https://img.shields.io/pypi/pyversions/power-switch-pro.svg)](https://pypi.org/project/power-switch-pro/)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
[![Documentation](https://readthedocs.org/projects/power-switch-pro/badge/?version=latest)](https://power-switch-pro.readthedocs.io/en/latest/)
[![CI](https://github.com/bryankemp/power_switch_pro/workflows/CI/badge.svg)](https://github.com/bryankemp/power_switch_pro/actions)
[![codecov](https://codecov.io/gh/bryankemp/power_switch_pro/branch/main/graph/badge.svg)](https://codecov.io/gh/bryankemp/power_switch_pro)

A professional-grade Python library for controlling [Digital Loggers](https://www.digital-loggers.com/) Power Switch Pro devices via their REST API.

**Designed for**: Firmware version 1.7.0+ with REST API support (API specification 20221009T204818Z)

## ✨ Features

### Core Functionality
- 🔌 **Full REST API Support** - Complete implementation of DLI REST-style API
- ⚡ **Outlet Control** - Turn outlets on/off/cycle individually or in bulk
- 📊 **Power Monitoring** - Real-time voltage, current, power, and energy measurements
- 👥 **User Management** - Create, modify, and manage device users
- 🔧 **Device Configuration** - Access and modify device settings
- 🏓 **AutoPing** - Configure automatic host monitoring and recovery
- 📜 **Script Execution** - Run custom scripts on the device

### Python Features
- 🐍 **Pythonic API** - Intuitive interface with properties and array indexing
- 🔒 **Secure** - HTTP Digest Authentication and CSRF protection
- 🌐 **HTTPS Support** - Optional SSL/TLS encryption
- 📝 **Type Hints** - Full type annotations for better IDE support
- 🧪 **Well Tested** - Comprehensive test suite with >80% coverage
- 📚 **Documented** - Extensive documentation with examples

## Installation

```bash
pip install power_switch_pro
```

## Quick Start

```python
from power_switch_pro import PowerSwitchPro

# Connect to device
switch = PowerSwitchPro("192.168.0.100", "admin", "1234")

# Turn on outlet 1
switch.outlets[0].on()

# Turn off outlet 2
switch.outlets[1].off()

# Cycle outlet 3
switch.outlets[2].cycle()

# Get outlet state
state = switch.outlets[0].state
print(f"Outlet 1 is {'ON' if state else 'OFF'}")

# Get all outlet states
states = switch.outlets.get_all_states()
print(states)

# Get power metrics
voltage = switch.meters.get_voltage()
current = switch.meters.get_current()
print(f"Voltage: {voltage}V, Current: {current}A")
```

## Advanced Usage

### Working with Multiple Outlets

```python
# Turn off all unlocked outlets
switch.outlets.bulk_operation(locked=False, action='off')

# Get states of specific outlets
states = switch.outlets.get_states([0, 1, 4])  # Outlets 1, 2, and 5
```

### User Management

```python
# Add a new user
switch.auth.add_user(
    name="operator",
    password="secret123",
    outlet_access=[True, True, False, False, False, False, False, False]
)

# List all users
users = switch.auth.list_users()

# Delete a user
switch.auth.delete_user("operator")
```

### AutoPing Configuration

```python
# Add AutoPing entry
switch.autoping.add_entry(
    host="192.168.0.50",
    outlet=0,
    enabled=True
)
```

### Configuration

```python
# Get device configuration
config = switch.config.get_all()

# Update timezone
switch.config.set_timezone("UTC-5")

# Get device info
info = switch.info
print(f"Serial: {info['serial']}, Version: {info['version']}")
```

## API Reference

### PowerSwitchPro

Main class for interacting with the device.

**Parameters:**
- `host` (str): Device IP address or hostname
- `username` (str): Admin username
- `password` (str): Admin password
- `use_https` (bool): Use HTTPS instead of HTTP (default: False)
- `verify_ssl` (bool): Verify SSL certificates (default: True)

**Properties:**
- `outlets`: OutletManager for controlling outlets
- `auth`: AuthManager for user management
- `config`: ConfigManager for device configuration
- `meters`: MeterManager for power metrics
- `autoping`: AutoPingManager for AutoPing settings
- `script`: ScriptManager for script execution

### OutletManager

Manage power outlets.

**Methods:**
- `on(outlet_id)`: Turn on an outlet
- `off(outlet_id)`: Turn off an outlet
- `cycle(outlet_id)`: Cycle an outlet
- `get_state(outlet_id)`: Get outlet state
- `get_all_states()`: Get all outlet states
- `get_name(outlet_id)`: Get outlet name
- `set_name(outlet_id, name)`: Set outlet name
- `bulk_operation(**filters, action)`: Perform bulk operations

## Requirements

- Python 3.7+
- requests >= 2.25.0

## License

BSD 3-Clause License. See LICENSE file for details.

## Author

Bryan Kemp (bryan@kempville.com)

## 📖 Documentation

Full documentation is available at [power-switch-pro.readthedocs.io](https://power-switch-pro.readthedocs.io)

- [Installation Guide](https://power-switch-pro.readthedocs.io/en/latest/installation.html)
- [Device Information](https://power-switch-pro.readthedocs.io/en/latest/device.html) - Hardware specs and firmware compatibility
- [Quick Start Guide](https://power-switch-pro.readthedocs.io/en/latest/quickstart.html)
- [API Reference](https://power-switch-pro.readthedocs.io/en/latest/api.html)
- [Code Examples](https://power-switch-pro.readthedocs.io/en/latest/examples.html)
- [Contributing Guidelines](https://power-switch-pro.readthedocs.io/en/latest/contributing.html)

## 🚀 Supported Devices

This library works with Digital Loggers power management devices that support the REST API:

- **Web Power Switch Pro** (LPC series)
- **Pro Switch** series
- **Ethernet Power Controller III** and later models

**Minimum Firmware**: 1.7.0 (REST API support required)

## 💡 Use Cases

- **Data Center Management**: Remotely control and monitor rack-mounted equipment
- **Lab Automation**: Automate test equipment power cycling
- **Server Management**: Implement automated recovery for unresponsive servers
- **IoT Projects**: Integrate power control into home automation systems
- **CI/CD Pipelines**: Reset test hardware between test runs
- **Energy Monitoring**: Track power consumption of connected devices

## 🛡️ Security Features

- **HTTP Digest Authentication** - More secure than Basic auth (default)
- **HTTPS/TLS Support** - Encrypted communication
- **CSRF Protection** - Built-in protection against cross-site request forgery
- **Session Management** - Efficient connection reuse
- **Per-Outlet Permissions** - Granular access control for users

## 🧪 Testing

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=power_switch_pro --cov-report=html

# Run linting
ruff check power_switch_pro tests
black --check power_switch_pro tests

# Run type checking
mypy power_switch_pro
```

## 🔧 Development

This project uses:

- **Black** for code formatting
- **Ruff** for fast Python linting  
- **mypy** for static type checking
- **pytest** for testing
- **Sphinx** for documentation

See [WARP.md](WARP.md) for detailed development guidelines.

## 📊 Project Status

- ✅ **Stable API** - v0.1.0 released
- ✅ **Well Tested** - Comprehensive test coverage
- ✅ **Documented** - Full documentation available
- ✅ **Type Safe** - Complete type annotations
- ✅ **CI/CD** - Automated testing and publishing

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting (`make test lint`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

Please read [CONTRIBUTING.md](docs/contributing.rst) for detailed guidelines.

## 📝 License

This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Digital Loggers for providing the REST API specification
- The Python community for excellent tools and libraries

## 📧 Support

- **Documentation**: https://power-switch-pro.readthedocs.io
- **Issues**: https://github.com/bryankemp/power_switch_pro/issues
- **Email**: bryan@kempville.com

## 🔗 Related Links

- [Digital Loggers Website](https://www.digital-loggers.com/)
- [DLI REST API Documentation](https://www.digital-loggers.com/restapi.pdf)
- [Product Support Forum](https://www.digital-loggers.com/forum/)

---

**Made with ❤️ by Bryan Kemp**
