Add support for parameters in scripts

[jimtng]

What does this implement/fix?

Add support for parameters in scripts

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Other

Related issue or feature (if applicable): fixes esphome/feature-requests#241

Pull request in esphome-docs with documentation (if applicable): esphome/esphome-docs#2120

Test Environment

• ESP32
• ESP32 IDF
• ESP8266

Example entry for config.yaml:

# Example config.yaml
script:
  - id: control_light
    parameters:
      turn_on: bool
    then:
      # The script can receive and use the params e.g. turn_on
      - lambda: |-
          if (turn_on)
            id(status_light)->turn_on().perform();
          else
            id(status_light)->turn_off().perform();

binary_sensor:
  - platform: gpio
    pin: D2
    id: input2
    on_press:
      # call script through lambda, passing the args to execute
      - lambda: |-
          id(control_light)->execute(true);
    on_release:
      # call script through script.execute
      - script.execute:
          id: control_light
          turn_on: false

Checklist:

• The code change is tested and works locally.
• Tests have been added to verify that the new code works (under tests/ folder).

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated in esphome-docs.

[probot-esphome]

Hey there @esphome/core, mind taking a look at this pull request as it has been labeled with an integration (script) you are listed as a code owner for? Thanks!
_{^{(message by CodeOwnersMention)}}

[mmakaay]

Nice, striking this one from my personal TODO list 😄

[nagyrobi]

Great!

[jimtng]

ping @OttoWinter @jesserockz

[nagyrobi]

@jimtng how could I test this in my addon version of ESPHome?

Trying with:

external_components:
  - source: github://pr#3538
    components:
      - script

fails with

ERROR Unable to import component script:
Traceback (most recent call last):
  File "/esphome/esphome/loader.py", line 162, in _lookup_module
    module = importlib.import_module(f"esphome.components.{domain}")
  File "/usr/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 790, in exec_module
  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed
  File "/config/esphome/.esphome/external_components/b61925cd/esphome/components/script/__init__.py", line 5, in <module>
    from esphome.const import CONF_ID, CONF_MODE, CONF_PARAMETERS
ImportError: cannot import name 'CONF_PARAMETERS' from 'esphome.const' (/esphome/esphome/const.py)
Failed config

[jimtng]

@nagyrobi you'd need to check out my branch in order to test. This PR contains changes to esphome/const.py which is not a part of the script component, hence you couldn't just source the component.

[mmakaay]

For that reason, it's not a bad idea to keep new constants in your component, at least during development. That makes it possible to handle it as an external component.
After merging, these constants can be moved to const.py, or even kept within the component when they aren't likely to be reused.

[nagyrobi]

For my use case I was offered a nice workaround, so I don't need to test anymore: esphome/feature-requests#241 (comment)

[jimtng]

For that reason, it's not a bad idea to keep new constants in your component, at least during development. That makes it possible to handle it as an external component. After merging, these constants can be moved to const.py, or even kept within the component when they aren't likely to be reused.

@jesserockz WDYT?

[jesserockz]

Very minor change request. Otherwise looks good, and tested locally

[jesserockz]

I actually pushed some commits that "fix" having lists in the types. The docs mentioned [] becomes std::vector, but this was not the case in the code. It now is.

Also fixed the "crash" when parameters were not set on the execute action, this is a limitation of not being able to raise cv.Invalid inside to_code functions.