Metadata-Version: 2.4
Name: matter-python-client
Version: 0.7.1
Summary: Python Client for the OHF Matter Server
Author-email: Open Home Foundation <hello@openhomefoundation.io>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/matter-js/matterjs-server
Project-URL: Source, https://github.com/matter-js/matterjs-server/tree/main/python_client
Project-URL: Bug Tracker, https://github.com/matter-js/matterjs-server/issues
Project-URL: Changelog, https://github.com/matter-js/matterjs-server/blob/main/CHANGELOG.md
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: aiohttp
Requires-Dist: dacite
Requires-Dist: orjson
Provides-Extra: test
Requires-Dist: codespell==2.4.1; extra == "test"
Requires-Dist: isort==7.0.0; extra == "test"
Requires-Dist: mypy==1.19.1; extra == "test"
Requires-Dist: pylint==4.0.4; extra == "test"
Requires-Dist: pytest>=9.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.24; extra == "test"
Requires-Dist: pytest-aiohttp>=1.0; extra == "test"
Requires-Dist: pytest-cov>=7.0; extra == "test"
Requires-Dist: ruff==0.14.9; extra == "test"

# Python Client for the OHF Matter Server

A PyPI package (`matter-python-client`) providing Python bindings for the [OHF Matter Server](https://github.com/matter-js/matterjs-server). This is a drop-in replacement for the client portion of [`python-matter-server`](https://github.com/matter-js/python-matter-server), with custom cluster definitions updated to match the Matter.js server.

## Origin

The client and common modules were copied from [`python-matter-server` v8.1.2](https://github.com/matter-js/python-matter-server) and modified:

- **Source**: `matter_server/client/` and `matter_server/common/` from python-matter-server
- **Modified**: `matter_server/common/custom_clusters.py` — updated to match the JS server's cluster definitions
- **Excluded**: `matter_server/server/` (the JS server replaces it), `common/helpers/logger.py` (depends on `coloredlogs`, a server-only dependency)

### Custom Cluster Changes

| Cluster | Change |
|---------|--------|
| EveCluster | +8 attributes (getConfig, setConfig, loggingMetadata, loggingData, lastEventTime, statusFault, childLock, rloc16), wattAccumulatedControlPoint type fixed |
| HeimanCluster | Attribute IDs shortened to match JS server |
| NeoCluster | Types changed from float32 to uint |
| Polling | Removed (JS server handles polling natively) |

## Package

- **PyPI name**: `matter-python-client`
- **Python module**: `matter_server` (same import path as `python-matter-server`)
- **Python**: >= 3.12
- **Dependencies**: `aiohttp`, `orjson`, `home-assistant-chip-clusters`

## npm Scripts (from monorepo root)

```bash
# First-time setup: create venv and install with test dependencies
npm run python:install

# Run unit + mock server tests (fast, ~1s)
npm run python:test

# Run full integration tests against real Matter.js server + test device (~40s)
npm run python:test-integration

# Run all Python tests
npm run python:test-all

# Build the PyPI package (.tar.gz + .whl)
npm run python:build
```

## Usage

The package provides the same `matter_server.client` API as `python-matter-server`:

```python
import aiohttp
from matter_server.client import MatterClient

async with aiohttp.ClientSession() as session:
    client = MatterClient("ws://localhost:5580/ws", session)
    await client.connect()

    init_ready = asyncio.Event()
    listen_task = asyncio.create_task(client.start_listening(init_ready))
    await init_ready.wait()

    nodes = client.get_nodes()
```

To use this package instead of `python-matter-server` in the Home Assistant Matter integration, change `manifest.json`:

```diff
- "requirements": ["python-matter-server==8.1.2"],
+ "requirements": ["matter-python-client==1.0.0"],
```

## Testing

The test suite has three layers:

- **Import smoke tests** (8 tests) — verify all HA integration imports resolve
- **Mock server tests** (4 tests) — Python client against JS MockMatterServer subprocess
- **Integration tests** (63 tests) — Python client against real Matter.js server + test device, mirroring the JS `IntegrationTest.ts`