Ha Pyscript

Stubs

Stubs in modules/stubs/ provide IDE autocomplete and enable method syntax. Each pyscript file imports from them at the top:

from stubs.pyscript_builtins import event_trigger, state_trigger, task, time_trigger
from stubs.pyscript_generated import light, timer, input_number, input_select

These imports are ignored at runtime by pyscript. Check modules/stubs/pyscript_generated.py for exact entity names before writing service calls.

Method syntax (preferred for single known entities):

light.kitchen_front.turn_on(brightness_pct=100)      # method — single entity only
light.turn_on(entity_id="light.kitchen_front", ...)  # service — always valid
light.turn_on(entity_id=["light.a", "light.b"], ...) # lists always use service form

Syncing Stubs from HA

When stubs are stale or missing:

1. In HA: Developer Tools → Actions → run pyscript.generate_stubs
2. Sync to this machine:

   rsync -rv ha:config/pyscript/modules/stubs/ modules/stubs
   

3. Patch known defects in the generated stubs:

   uv run python .claude/skills/ha-pyscript/scripts/patch_stubs.py modules/stubs/pyscript_generated.py
   

Deploying to HA

rsync -rv ./pyscript/ "ha:/root/config/pyscript"

Reload after adding a new file: Developer Tools → Actions → pyscript.reload

Pyscript Syntax

See sources/pyscript_tutorial.md for the full language reference.

Triggers

@state_trigger("entity == 'on'")
@state_trigger("float(input_number.x) > 2.9 and float(input_number.x) < 3.1")
@state_trigger("binary_sensor.door")                  # any state change
@state_trigger("entity.old == 'off' and entity == 'on'")  # from/to
@time_trigger("once(7:00:00)")
@time_trigger("cron(30 22 * * *)")                    # 22:30 daily
@time_trigger("once(sunset - 30 min)")
@event_trigger("timer.finished", "entity_id == 'timer.my_timer'")
@event_trigger("zha_event", "device_id == '...' and command == 'toggle'")

Multiple triggers on one function — any one fires it:

@event_trigger("zha_event", "device_id == 'device_a' and command == 'toggle'")
@event_trigger("zha_event", "device_id == 'device_b' and command == 'toggle'")
def handle_button(**kwargs):
    ...

Conditions → early returns

def my_func(**kwargs):
    if input_select.lighting_mode not in ['evening', 'night']: return
    if not (float(sensor.luminance) < 15): return
    if light.kitchen_front != 'on': return

Actions

# Service calls
light.turn_on(entity_id="light.kitchen_front", brightness_pct=100, color_temp_kelvin=5400)
light.turn_on(entity_id=["light.a", "light.b"], brightness_pct=50)
light.turn_off(entity_id="light.kitchen_front")
input_number.kitchen_light_level.set_value(value=2)

# Delays
task.sleep(30)                               # sleep N seconds

# HA timers
timer.my_timer.start(duration="900")         # start (seconds as string)
timer.my_timer.start(duration="0:15:0")      # start (H:M:S)
timer.my_timer.cancel()

Mode → task.unique

def my_func(**kwargs):
    task.unique('my_func', kill_me=True)  # mode: single — new call kills old
    task.unique('my_func')                # mode: restart — old kills new
    # omit task.unique for mode: parallel or queued

State access

All HA state values are strings; cast explicitly for comparisons:

float(input_number.kitchen_light_level)   # numeric state
int(sensor.some_count)
state.get("timer.water_heater")           # dynamic entity name
state.names("input_text")                 # list all entities in a domain

Debugging

Trigger not firing? Check HA logs for:

trigger file.module.func got event trigger, but not active

This means the event filter expression has a syntax error or mismatched event type.

To find ZHA event command strings: Developer Tools → Events → listen to zha_event → press the button.

Reference Files

• trigger-mapping.md — complete syntax reference for all trigger, condition, and action types
• patterns.md — common patterns: level dispatch, motion lighting, ZHA buttons, timers, inter-function calls