Metadata-Version: 2.5
Name: tplink-deco-api
Version: 2.0.0
Summary: Python SDK for controlling TP-Link Deco routers via the internal HTTP API
Project-URL: Homepage, https://github.com/roquerodrigo/tplink-deco-api
Project-URL: Repository, https://github.com/roquerodrigo/tplink-deco-api
Project-URL: Issues, https://github.com/roquerodrigo/tplink-deco-api/issues
Author-email: Rodrigo Roque <rodrigogoncalvesroque@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,deco,mesh,router,sdk,tplink,wifi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Networking
Requires-Python: >=3.14
Requires-Dist: cryptography>=46.0.7
Description-Content-Type: text/markdown

# tplink-deco-api

[![CI](https://github.com/roquerodrigo/tplink-deco-api/actions/workflows/ci.yml/badge.svg)](https://github.com/roquerodrigo/tplink-deco-api/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/tplink-deco-api)](https://pypi.org/project/tplink-deco-api/)

[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-db61a2?logo=githubsponsors&logoColor=white&style=for-the-badge)](https://github.com/sponsors/roquerodrigo)

Python SDK for controlling **TP-Link Deco** mesh Wi-Fi routers via the internal HTTP API.

## Installation

```bash
pip install tplink-deco-api
```

## Usage

```python
from tplink_deco_api import DecoClient

with DecoClient("192.168.68.1", "admin", "your-password") as deco:
    for client in deco.get_client_list():
        print(client.name, client.ip, client.connection_type)
```

## Available methods

### Session

| Method | Returns |
|--------|---------|
| `login()` | `LoginResult` |
| `logout()` | `None` |
| `is_authenticated()` | `bool` |

### Typed queries

| Method | Returns |
|--------|---------|
| `get_device_list()` | `list[Device]` |
| `get_device_mode()` | `DeviceMode` |
| `get_wlan_config()` | `WlanConfig` |
| `get_performance()` | `Performance` |
| `get_client_list(deco_mac?)` | `list[ClientDevice]` |
| `get_client_totals(deco_mac?)` | `NetworkTotals` |
| `get_internet_status()` | `InternetStatus` |
| `get_wan_info(device_mac?)` | `WanInfo` |
| `get_dsl_status(device_mac?)` | `DslStatus` |
| `get_wireless_power(device_mac?)` | `WirelessPower` |
| `get_time_settings(device_mac?)` | `TimeSettings` |
| `get_log_types()` | `list[LogType]` |

### Client management — `deco.clients`

| Method | Returns |
|--------|---------|
| `update(mac, name, client_type?)` | `None` |
| `remove(mac)` | `None` |
| `get_blocked()` | `list[BlockedClient]` |
| `block(mac, name, client_type)` | `None` |
| `unblock(mac)` | `None` |

`update` always sends the name: the firmware ignores an edit that does not
carry one, so pass the current name to change only the device type. `remove`
forgets an offline client; the router lists it again if it reconnects.

### Fixed IPs — `deco.address_reservations`

| Method | Returns |
|--------|---------|
| `get_table()` | `AddressReservationTable` |
| `add(reservation)` | `None` |
| `modify(current, replacement)` | `None` |
| `remove(mac)` | `None` |

```python
from tplink_deco_api import AddressReservation, DecoClient

with DecoClient("192.168.68.1", "admin", "your-password") as deco:
    deco.address_reservations.add(AddressReservation("AA:BB:CC:DD:EE:FF", "192.168.68.50"))
    deco.clients.update("AA:BB:CC:DD:EE:FF", "Living Room TV")
```

MAC addresses are accepted with `:` or `-` separators. Malformed MAC or IPv4
input raises `ValueError` before any request is sent.

### Raw access

`request(path, form, data)` and `request_list(path, form, data)` send an
authenticated, encrypted request to any endpoint and return the decrypted
`result` (as an object or a list respectively). Use them for the endpoints
that have no typed wrapper yet — the full catalogue is documented in
[`docs/endpoints/`](./docs/endpoints/README.md).

## Models

Every method returns typed dataclasses — no generic dictionaries.

```python
client.mac              # "AA:BB:CC:DD:EE:FF"
client.name             # "MacBook Pro"
client.ip               # "192.168.68.10"
client.connection_type  # "band6"
client.online           # True

device.device_model     # "BE65"
device.software_ver     # "1.2.10 Build 20251229"

wlan.band2_4.host.ssid      # "My Network"
wlan.band2_4.guest.password # "guest-password"

perf.cpu_usage  # 0.03
perf.mem_usage  # 0.42
```

## Requirements

- Python 3.14+
- TP-Link Deco router reachable on the local network

## Support

This SDK is built and maintained on personal time, on hardware bought for the purpose. If it is useful to you, consider [sponsoring the work](https://github.com/sponsors/roquerodrigo) — it keeps the devices, the testing and the releases coming.

## License

[MIT](./LICENSE)
