From 3b64e4ef7845d4ef7da3ec9308927d283eb81fcc Mon Sep 17 00:00:00 2001 From: "alexei.dolgolyov" Date: Tue, 3 Feb 2026 04:56:41 +0300 Subject: [PATCH] Add .gitignore and CLAUDE.md with session lessons - Add comprehensive .gitignore for Python/HA projects - Document mistakes and lessons learned during development Co-Authored-By: Claude Opus 4.5 --- .gitignore | 90 +++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9daff8d --- /dev/null +++ b/.gitignore @@ -0,0 +1,90 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# IDEs +.idea/ +.vscode/ +*.swp +*.swo +*~ +.project +.pydevproject +.settings/ + +# macOS +.DS_Store +.AppleDouble +.LSOverride + +# Windows +Thumbs.db +ehthumbs.db +Desktop.ini + +# Claude Code +.claude/ + +# Home Assistant +.HA_VERSION +home-assistant.log +home-assistant_v2.db +home-assistant_v2.db-shm +home-assistant_v2.db-wal diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c0df4d9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,110 @@ +# Claude Code Session Notes + +This file documents mistakes and lessons learned during the development of this integration. + +## Mistakes Made + +### 1. Missing `/emby` Prefix on API Endpoints + +**Problem:** Initially created all API endpoints without the `/emby` prefix. + +```python +# Wrong +ENDPOINT_SYSTEM_INFO = "/System/Info" +ENDPOINT_USERS = "/Users" + +# Correct +ENDPOINT_SYSTEM_INFO = "/emby/System/Info" +ENDPOINT_USERS = "/emby/Users" +``` + +**Impact:** Connection to Emby server failed with "cannot connect" errors. + +**Lesson:** Always verify API endpoint formats against official documentation. Emby Server requires the `/emby` prefix for all API calls. + +--- + +### 2. Incorrect Volume Control API Format + +**Problem:** Tried multiple incorrect formats for the SetVolume command before finding the correct one. + +```python +# Attempt 1 - Wrong endpoint with body +endpoint = f"/Sessions/{session_id}/Command/SetVolume" +data = {"Arguments": {"Volume": 50}} + +# Attempt 2 - Wrong: query parameter +endpoint = f"/Sessions/{session_id}/Command/SetVolume?Volume=50" + +# Correct format +endpoint = f"/Sessions/{session_id}/Command" +data = {"Name": "SetVolume", "Arguments": {"Volume": "50"}} # Arguments as STRINGS +``` + +**Impact:** Volume control didn't work even though mute/unmute worked fine. + +**Lesson:** Emby general commands must be sent to `/Command` endpoint (not `/Command/{CommandName}`) with: +- `Name` field containing the command name +- `Arguments` as a dict with STRING values, not integers + +--- + +### 3. NumberSelector Returns Float, Not Int + +**Problem:** Home Assistant's `NumberSelector` widget returns float values, but port numbers must be integers. + +```python +# Wrong - port could be 8096.0 +self._port = user_input.get(CONF_PORT, DEFAULT_PORT) + +# Correct +self._port = int(user_input.get(CONF_PORT, DEFAULT_PORT)) +``` + +**Impact:** Potential type errors or malformed URLs with decimal port numbers. + +**Lesson:** Always explicitly convert NumberSelector values to the expected type. + +--- + +### 4. Inconsistent Use of Constants + +**Problem:** Hardcoded endpoint paths in some methods instead of using defined constants. + +```python +# Wrong - hardcoded +endpoint = f"/Sessions/{session_id}/Playing" + +# Correct - using constant +endpoint = f"{ENDPOINT_SESSIONS}/{session_id}/Playing" +``` + +**Impact:** When the `/emby` prefix was added to constants, hardcoded paths were missed, causing inconsistent behavior. + +**Lesson:** Always use constants consistently. When fixing issues, search for all occurrences of the affected strings. + +--- + +### 5. Import Confusion Between Local and HA Constants + +**Problem:** Initially imported `CONF_HOST` and `CONF_PORT` from `homeassistant.const` in some files, while also defining them in local `const.py`. + +```python +# Inconsistent imports +from homeassistant.const import CONF_HOST, CONF_PORT # in __init__.py +from .const import CONF_HOST, CONF_PORT # in config_flow.py +``` + +**Impact:** Potential confusion and maintenance issues, though values were identical. + +**Lesson:** Choose one source for constants and use it consistently across all files. For custom integrations, prefer local constants for full control. + +--- + +## Best Practices Established + +1. **Test API endpoints with curl first** - Verify the exact request format before implementing in code +2. **Add debug logging** - Include request URLs and response status codes for troubleshooting +3. **Handle multiple API formats** - Some servers may respond differently; implement fallbacks when sensible +4. **Type conversion** - Always explicitly convert UI input values to expected types +5. **Consistent constant usage** - Define constants once and use them everywhere