lifx-emulator 1.0.0__py3-none-any.whl

lifx_emulator-1.0.0.dist-info/METADATA

@@ -0,0 +1,445 @@
+Metadata-Version: 2.4
+Name: lifx-emulator
+Version: 1.0.0
+Summary: LIFX Emulator for testing LIFX LAN protocol libraries
+Author-email: Avi Miller <me@dje.li>
+Maintainer-email: Avi Miller <me@dje.li>
+License-Expression: UPL-1.0
+License-File: LICENSE
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cyclopts>=4.2.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=14.2.0
+Requires-Dist: uvicorn>=0.34.0
+Description-Content-Type: text/markdown
+
+# LIFX Emulator
+
+> A comprehensive LIFX device emulator for testing LIFX LAN protocol libraries
+
+[![License](https://img.shields.io/badge/License-UPL--1.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.13+-blue.svg)](https://www.python.org/downloads/)
+
+## Overview
+
+LIFX Emulator implements the complete binary UDP protocol from [lan.developer.lifx.com](https://lan.developer.lifx.com), providing virtual LIFX devices for testing without physical hardware.
+
+## Features
+
+- **Complete Protocol Support**: 44+ packet types from the LIFX LAN protocol
+- **Multiple Device Types**: Color lights, infrared, HEV, multizone strips, matrix tiles
+- **Product Registry**: 40+ official LIFX product definitions with accurate defaults
+- **Testing Scenarios**: Built-in support for packet loss, delays, malformed responses
+- **Easy Integration**: Simple Python API and comprehensive CLI
+- **Zero Dependencies**: Pure Python with only PyYAML for configuration
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install lifx-emulator
+```
+
+### CLI Usage
+
+```bash
+# Start with default configuration (1 color light)
+lifx-emulator
+
+# Create multiple device types with verbose logging
+lifx-emulator --color 2 --multizone 1 --tile 1 --verbose
+
+# Use specific products from registry
+lifx-emulator --product 27 --product 32 --product 55
+
+# List all available products
+lifx-emulator list-products
+```
+
+### Python API
+
+```python
+import asyncio
+from lifx_emulator import EmulatedLifxServer, create_color_light
+
+async def main():
+    # Create emulated device
+    device = create_color_light("d073d5000001")
+
+    # Start server
+    async with EmulatedLifxServer([device], "127.0.0.1", 56700) as server:
+        print(f"Server running with device: {device.state.label}")
+        await asyncio.Event().wait()
+
+asyncio.run(main())
+```
+
+### Integration Testing
+
+```python
+import pytest
+from lifx_emulator import EmulatedLifxServer, create_color_light
+from your_lifx_library import LifxClient
+
+@pytest.mark.asyncio
+async def test_discover_devices():
+    # Create emulated device
+    device = create_color_light("d073d5000001")
+
+    # Start emulator
+    async with EmulatedLifxServer([device], "127.0.0.1", 56700):
+        # Test your library
+        client = LifxClient()
+        await client.discover(port=56700)
+
+        assert len(client.devices) == 1
+        assert client.devices[0].mac == "d073d5000001"
+```
+
+## Supported Device Types
+
+| Device Type | Factory Function | Example Product |
+|------------|------------------|-----------------|
+| Color Lights | `create_color_light()` | LIFX A19 |
+| Color Temperature | `create_color_temperature_light()` | LIFX Mini White to Warm |
+| Infrared | `create_infrared_light()` | LIFX A19 Night Vision |
+| HEV | `create_hev_light()` | LIFX Clean |
+| Multizone | `create_multizone_light()` | LIFX Z, LIFX Beam |
+| Matrix Tiles | `create_tile_device()` | LIFX Tile |
+
+[See all 40+ supported products →](https://lifx-emulator.readthedocs.io/en/latest/guide/device-types/)
+
+## Documentation
+
+- **[Installation Guide](https://lifx-emulator.readthedocs.io/en/latest/getting-started/installation/)** - Get started
+- **[Quick Start](https://lifx-emulator.readthedocs.io/en/latest/getting-started/quickstart/)** - Your first emulated device
+- **[CLI Reference](https://lifx-emulator.readthedocs.io/en/latest/getting-started/cli/)** - All CLI options
+- **[Device Types](https://lifx-emulator.readthedocs.io/en/latest/guide/device-types/)** - Supported devices
+- **[API Reference](https://lifx-emulator.readthedocs.io/en/latest/api/)** - Complete API docs
+- **[Architecture](https://lifx-emulator.readthedocs.io/en/latest/architecture/overview/)** - How it works
+
+## CLI Examples
+
+### Basic Usage
+
+```bash
+# Single color light on default port 56700
+lifx-emulator
+
+# Multiple devices with verbose logging
+lifx-emulator --color 2 --multizone 1 --tile 1 --verbose
+```
+
+### Advanced Usage
+
+```bash
+# Extended multizone (LIFX Beam) with custom zone count
+lifx-emulator --multizone 1 --multizone-extended --multizone-zones 60
+
+# Specific products by ID
+lifx-emulator --product 27 --product 32 --product 55
+
+# Custom port and localhost only
+lifx-emulator --bind 127.0.0.1 --port 56701
+
+# Filter products list
+lifx-emulator list-products --filter-type multizone
+```
+
+## Python API Examples
+
+### Multiple Device Types
+
+```python
+from lifx_emulator import (
+    EmulatedLifxServer,
+    create_color_light,
+    create_multizone_light,
+    create_tile_device,
+)
+
+devices = [
+    create_color_light("d073d5000001"),
+    create_multizone_light("d073d8000001", zone_count=16),
+    create_tile_device("d073d9000001", tile_count=5),
+]
+
+async with EmulatedLifxServer(devices, "127.0.0.1", 56700) as server:
+    # All devices are discoverable and controllable
+    print(f"Emulating {len(devices)} devices")
+    await asyncio.Event().wait()
+```
+
+### Testing Scenarios
+
+```python
+# Configure error scenarios for testing
+device = create_color_light("d073d5000001")
+device.scenarios = {
+    'drop_packets': [101],           # Drop LightGet packets
+    'response_delays': {102: 0.5},   # Delay SetColor by 500ms
+    'malformed_packets': [107],      # Truncate StateLight
+}
+
+async with EmulatedLifxServer([device], "127.0.0.1", 56700) as server:
+    # Test your library's error handling
+    pass
+```
+
+## Use Cases
+
+- **Library Testing**: Test your LIFX library without physical devices
+- **CI/CD Integration**: Run automated tests in pipelines
+- **Protocol Development**: Experiment with LIFX protocol features
+- **Error Simulation**: Test error handling with configurable scenarios
+- **Performance Testing**: Test concurrent device handling
+
+## Requirements
+
+- Python 3.13+
+- PyYAML (automatically installed)
+
+## Performance
+
+The emulator includes comprehensive performance optimization with **51% average throughput improvement**:
+
+- Complete benchmarking and profiling suite
+- Detailed optimization analysis and recommendations
+- Before/after performance comparison
+
+**Key Results:**
+- **Packet Processing**: +51% (35K → 53K pkt/s)
+- **Serialization**: +77% (27K → 48K pkt/s)
+- **Latency**: -35% to -44% reduction
+
+See the [Performance Documentation](docs/performance/index.md) for details.
+
+### Run Performance Benchmarks
+
+```bash
+uv run python tools/performance/benchmark.py
+uv run python tools/performance/profiler.py
+```
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/Djelibeybi/lifx-emulator.git
+cd lifx-emulator
+
+# Install with uv (recommended)
+uv sync
+
+# Or with pip
+pip install -e ".[dev]"
+
+# Run tests
+uv run pytest
+
+# Run linter
+uv run ruff check .
+
+# Build docs
+uv run mkdocs serve
+```
+
+### Documentation Tools
+
+The emulator includes automated tools for documentation generation, validation, and quality checking:
+
+#### 1. API Reference Generator (`generate_api_reference.py`)
+
+Auto-generates API reference documentation from Python source code with docstrings, type hints, and inheritance diagrams.
+
+```bash
+# Generate API reference for a module
+python tools/docs/generate_api_reference.py src/lifx_emulator/device.py > docs/api/device.md
+
+# With output file
+python tools/docs/generate_api_reference.py src/lifx_emulator/storage.py --output docs/api/storage.md
+```
+
+#### 2. Diagram Generator (`generate_diagrams.py`)
+
+Auto-generates architecture diagrams from code analysis (component, packet flow, state machine, handler flow).
+
+```bash
+# Generate all diagrams
+python tools/docs/generate_diagrams.py --type all --output docs/architecture/diagrams/
+
+# Generate specific diagram type
+python tools/docs/generate_diagrams.py --type component
+python tools/docs/generate_diagrams.py --type packet-flow
+```
+
+#### 3. Example Validator (`validate_examples.py`)
+
+Validates that code examples in documentation actually work by extracting and compiling Python code blocks.
+
+```bash
+# Validate all examples in docs/
+python tools/docs/validate_examples.py docs/
+
+# Validate with verbose output
+python tools/docs/validate_examples.py docs/tutorials/ --verbose
+```
+
+#### 4. Coverage Reporter (`coverage_report.py`)
+
+Tracks documentation coverage across the codebase and enforces minimum coverage thresholds.
+
+```bash
+# Generate coverage report
+python tools/docs/coverage_report.py
+
+# Require minimum coverage
+python tools/docs/coverage_report.py --min-coverage 80
+
+# Generate HTML report
+python tools/docs/coverage_report.py --html --output coverage.html
+```
+
+#### 5. Terminology Checker (`check_terminology.py`)
+
+Validates consistent terminology usage across documentation against defined glossary.
+
+```bash
+# Check terminology
+python tools/docs/check_terminology.py docs/
+
+# Auto-fix violations
+python tools/docs/check_terminology.py docs/ --fix
+```
+
+#### Documentation Workflow
+
+When writing documentation:
+
+1. **Write content** with code examples
+2. **Run validation locally:**
+   ```bash
+   # Check terminology
+   python tools/docs/check_terminology.py docs/ --fix
+
+   # Validate examples
+   python tools/docs/validate_examples.py docs/ --verbose
+
+   # Check coverage
+   python tools/docs/coverage_report.py
+   ```
+
+3. **Auto-generate API reference:**
+   ```bash
+   python tools/docs/generate_api_reference.py src/lifx_emulator/device.py --output docs/api/device.md
+   ```
+
+4. **Generate diagrams:**
+   ```bash
+   python tools/docs/generate_diagrams.py --type all --output docs/architecture/diagrams/
+   ```
+
+5. **Commit changes** - CI will validate everything
+
+The `.github/workflows/docs.yml` workflow runs all validation tools on pull requests and pushes to main.
+
+See [Documentation Tools](docs/development/documentation-tools.md) for detailed documentation tool usage and troubleshooting.
+
+## Product Registry
+
+The emulator includes an auto-generated registry of all official LIFX products with accurate defaults:
+
+```python
+from lifx_emulator.products.registry import get_product, get_registry
+
+# Get specific product
+product = get_product(27)  # LIFX A19
+print(f"{product.name}: {product.pid}")
+print(f"Capabilities: color={product.has_color}, multizone={product.has_multizone}")
+
+# List all products
+registry = get_registry()
+for pid, product in registry.products.items():
+    print(f"PID {pid}: {product.name}")
+```
+
+## Testing Scenarios
+
+Configure devices to simulate real-world issues:
+
+```python
+device.scenarios = {
+    # Packet dropping (simulate packet loss)
+    'drop_packets': [101, 102],
+
+    # Response delays (simulate latency)
+    'response_delays': {102: 0.5, 107: 1.0},
+
+    # Malformed packets (test error handling)
+    'malformed_packets': [107],
+
+    # Invalid field values (test validation)
+    'invalid_field_values': {22: True},
+
+    # Partial responses (test timeout handling)
+    'partial_responses': [506],
+}
+```
+
+## Architecture
+
+```
+┌─────────────────┐
+│  LIFX Client    │
+│    Library      │
+└────────┬────────┘
+         │ UDP Packets
+         ▼
+┌─────────────────┐
+│ EmulatedLifx    │
+│     Server      │
+└────────┬────────┘
+         │ Route by MAC
+         ▼
+┌─────────────────┐     ┌──────────────┐
+│ EmulatedLifx    │────▶│ DeviceState  │
+│     Device      │     │  (Stateful)  │
+└────────┬────────┘     └──────────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Protocol Layer │
+│  (44+ packets)  │
+└─────────────────┘
+```
+
+[Learn more about the architecture →](https://lifx-emulator.readthedocs.io/en/latest/architecture/overview/)
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](https://lifx-emulator.readthedocs.io/en/latest/development/contributing/) for details.
+
+## License
+
+[UPL-1.0](LICENSE)
+
+## Links
+
+- **Documentation**: https://lifx-emulator.readthedocs.io
+- **GitHub**: https://github.com/Djelibeybi/lifx-emulator
+- **PyPI**: https://pypi.org/project/lifx-emulator/
+- **LIFX Protocol**: https://lan.developer.lifx.com

lifx_emulator-1.0.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+lifx_emulator/__init__.py,sha256=WzD3GRp_QFlYF9IexitPxuTVyOUDNv2ZApKhfRP0UGA,818
+lifx_emulator/__main__.py,sha256=gfx_SW0Vywlvt68KmozYuZMRWiTow0rgPmeiVHoTfHg,22437
+lifx_emulator/api.py,sha256=AVtaLYIjTtYJ-FL19Ny9WyvCOJHqfPmP5Tb1B_Gs20M,66810
+lifx_emulator/async_storage.py,sha256=-J4s_4Cxika_EDlFjBegKAaM8sY78wbTDWnttWH4Eik,10504
+lifx_emulator/constants.py,sha256=DFZkUsdewE-x_3MgO28tMGkjUCWPeYc3xLj_EXViGOw,1032
+lifx_emulator/device.py,sha256=qaTNgeyvg1S-g1rC91NnQpvDe4p1razMNVDTlv0vKMI,24109
+lifx_emulator/device_states.py,sha256=3juEk1PpBySOwB3XpvH4UqKAPek5ZNCbvepJ3Y97Sck,2855
+lifx_emulator/factories.py,sha256=vLsGFuP8E_9bbdo2Sry3G6Ax6qSl5QfpXsRfXE3SfBU,13017
+lifx_emulator/observers.py,sha256=-KnUgFcKdhlNo7CNVstP-u0wU2W0JAGg055ZPV15Sj0,3874
+lifx_emulator/scenario_manager.py,sha256=xv2NwdZjDcF83MTt7JjKgDvua6zx6SkGQT1P4156-RU,14154
+lifx_emulator/scenario_persistence.py,sha256=oytK5W2si1N-O31jBACHhGQyo5IrINlqfWE0K2bZq_8,7394
+lifx_emulator/server.py,sha256=Puw5OG1hVauv_EReu9Kp5i6S7q78H_6AT-X0zcx1kEs,16953
+lifx_emulator/state_restorer.py,sha256=isgCsmcjxc4aQrTXoIYr_FoIU4H5Swg7GNaoh_-X7zU,9793
+lifx_emulator/state_serializer.py,sha256=O4Cp3bbGkd4eZf5jzb0MKzWDTgiNhrSGgypmMWaB4dg,5097
+lifx_emulator/storage_protocol.py,sha256=j5wC4gI-2DtPgmY4kM3mKDI6OYpmiNpGulzdJnZnqYY,2929
+lifx_emulator/handlers/__init__.py,sha256=3Hj1hRo3yL3E7GKwG9TaYh33ymk_N3bRiQ8nvqSQULA,1306
+lifx_emulator/handlers/base.py,sha256=Kn_OoVOQPlJOkl-xiHRYsoNKsS054sxk7sZ8rI9NvXQ,1653
+lifx_emulator/handlers/device_handlers.py,sha256=MDUanFFDT9RWBcWtEZ3sXeGmoYjFW50T4zVIkkK2iB4,10239
+lifx_emulator/handlers/light_handlers.py,sha256=ycwOAD6skmBLVUlyeg5kBprHDlrllP-_0JRzQrDGFos,11778
+lifx_emulator/handlers/multizone_handlers.py,sha256=949FEt1Ilhp-LCxxY0xfHxYJccGNy_xnNhO14ePENaw,7913
+lifx_emulator/handlers/registry.py,sha256=s1ht4PmPhXhAcwu1hoY4yW39wy3SPJBMY-9Uxd0FWuE,3292
+lifx_emulator/handlers/tile_handlers.py,sha256=jzguqNr_aZheuqd4mikfQlkRcVeqs3HAEAseFSlkBlE,10038
+lifx_emulator/products/__init__.py,sha256=qcNop_kRYFF3zSjNemzQEgu3jPrIxfyQyLv9GsnaLEI,627
+lifx_emulator/products/generator.py,sha256=N8dNDTX9eoDtB3Nb02zHnLyooUR396GdjWGI4_I-Dls,25742
+lifx_emulator/products/registry.py,sha256=zNF3Nzzaj3Rlrs_YdI-KpDGCj3jA_zpoqFmcaD3_LJo,44526
+lifx_emulator/products/specs.py,sha256=2bpgr2z2Ugb_0IBl9LY8LGotB031Bim8zizwvtviFZ0,7186
+lifx_emulator/products/specs.yml,sha256=uxzdKFREAHphk8XSPiCHvQE2vwoPfT2m1xy-zC4ZIl4,8552
+lifx_emulator/protocol/__init__.py,sha256=-wjC-wBcb7fxi5I-mJr2Ad8K2YRflJFdLLdobfD-W1Q,56
+lifx_emulator/protocol/base.py,sha256=OH2fLGJCAFYCgaxkKB3-pLclRaCIMIQtLtlgS_Qe4Ko,12090
+lifx_emulator/protocol/const.py,sha256=ilhv-KcQpHtKh2MDCaIbMLQAsxKO_uTaxyR63v1W8cc,226
+lifx_emulator/protocol/generator.py,sha256=KuNuWUUNikBRudcnBNIFcJ_2h2zliceVmyxfyyHIpXc,48980
+lifx_emulator/protocol/header.py,sha256=RXMJ5YZG1jyxl4Mz46ZGJBYX41Jdp7J95BHuY-scYC0,5499
+lifx_emulator/protocol/packets.py,sha256=_xYYPuu6WfBpg1LwYVdzQdytFwTyMqpZRadmDdwZXWk,41567
+lifx_emulator/protocol/protocol_types.py,sha256=2Mccm9717EuTXQYaW44W_yReI4EtnlPp3-WEVASgdGY,24820
+lifx_emulator/protocol/serializer.py,sha256=2bZz7TddxaMRO4_6LujRGCS1w7GxD4E3rRk3r-hpEIE,10738
+lifx_emulator-1.0.0.dist-info/METADATA,sha256=6ULy_R-nnswf1Oa3bKMfgIZePm6ZrHrOil7rUjdWx4I,13190
+lifx_emulator-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lifx_emulator-1.0.0.dist-info/entry_points.txt,sha256=R9C_K_tTgt6yXEmhzH4r2Yx2Tu1rLlnYzeG4RFUVzSc,62
+lifx_emulator-1.0.0.dist-info/licenses/LICENSE,sha256=eBz48GRA3gSiWn3rYZAz2Ewp35snnhV9cSqkVBq7g3k,1832
+lifx_emulator-1.0.0.dist-info/RECORD,,

lifx_emulator-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lifx_emulator-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lifx-emulator = lifx_emulator.__main__:main

lifx_emulator-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,35 @@
+Copyright (c) 2025 Avi Miller <me@dje.li>
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.