Hi, I’d like to develop some python scripts…but why is there so few documentation?
How did-you learn to develop python script in HA?
I don’t find any real doc. It took me ages to create a simple script just because I had to search on the forum or google and try to guess how It works.
Also, It could be much easier to be able to debug the code. It seems to be possible but didn’t find a procedure
I’d like to know the same. I’m cobbling scripts together by analysing existing scripts, but that’s no way to write code. Where’s the documentation on how to interact with the various “things” in HA?
Nobody is asking a python tutorial.
But the script section it’s a bit in the middle of nowhere in terms of documentation. Do you use it? Because if you don’t use it it may look more or less complete, but as soon as you try to do something useful it falls apart.
A better place to check for docs about the python API is this:
However that page has two problems (leaving scripts, as I said before, in the middle of nowhere):
It is focused on integrations development
It provides absolutely useless examples rather than real ones (I don’t want to trigger “my_cool_event”, I want to subscribe to lighting events)
This is not possible in a python_script.
Only this is allowed in the hass object:
The Home Assistant object. Access is only allowed to call services, set/remove states and fire events. API reference
Also, there is no “lighting event”, there is a state_changed event so even it was possible you would have to create logic to filter the domain light. This is doable offcourse
Here is a simple script to turn on a light:
entity_id = data.get("entity_id")
if entity_id is not None:
service_data = {"entity_id": entity_id}
hass.services.call("light", "turn_on", service_data, False)
But if you only need to listen to state_changed, why not use automations with the event as trigger type?
Not a python_script, but maybe an even better solution in your use case?
Sorry for the confusion @Romkabouter
I was just writing an example of why I think documentation is poor, even if you follow the “lear more” links of the scripts section. What you said, that is not possible to subscribe to events on a python script it is not specified (that I found) in any place, and since the docs point you to the official HASS object, I expected it to be fully compatible. Therefore, the python scripts doc should state what is compatible and what is not and why.
And even if it were compatible there is no list (that I can find) of all the events and what you can expect from them. What other events apart from state_changed and the stupid examples about my_cool_event are? Where is the list?
I appreciate you put the time to write some code explaining how to do certain stuff. But this is not my use-case, it was just an example of why I think python scripts docs is not complete.
Thanks
The python_script might look like it missed documentation, but it is also a rather limited way of working with very little options. That is why it only one page I guess
I do not know what it is exactly that you miss, but there is always room for improvement.
Maybe your expection on the documentation is on how to write python code which can be used by Home Assistant?
That is more like an integration, the python_scripts section is for very small and simple scripts, you can’t even use imports.
You are really trying to be supportive and nice, and I really appreciate it, thanks.
But no, I am not missing documentation about integrating python code with home assistant, I am missing actual documentation about the specific scripts functionality.
To give you another example, the HA provides several filters that you can use within yaml templates. Are those filters/functions available to be used as scripts? If so, how? Which ones? I expect them all to be available, but there is no way to know how.
Searching on the forums I discovered that there is the random module available. This is specially important because you are not allowed to import anything, so I also want some documentation about which modules are also available on the scripts.
I understand that python scripts are somewhat in a middle ground: they are usually used by advanced users, that already know the intrinsic details of how HA works and probably don’t need such details. But IMO python scripts have the potential to become the best way to write complex scripts rather than that ugly soup of YAML templates that many users end doing
AppDaemon is way greater and has better docs, true, but it is not as greatly integrated into HA UI and life-cycle as scripts. You can easily see, modify and integrate scripts on the HA UI, AppDaemon is a separate entity like node-red is.
I am just exploring this space today, and I thought the same thing.
AppDaemon is fine, but it is this extra thing, and there is already a built in python_script integration for making scripts (presumably ones that would be too complicated, or much harder as a yaml script). Suggesting AppDaemon is fine, but it does not solve the problem.
My use case is that I want to trigger these scripts with a button or a regular automation, but I want it to have a lot of conditional knowledge of different systems, and I know the yaml script is going to be a huge pain.
I know python. These are some things that would be useful to document:
How do you read the state, or state attributes from an entity like a light?
How do you get the current time? (Can I use time.time()? Is there a hass method for time?)
How do you handle errors? Where can I see the exceptions for the scripts I’m writing? (I would really like to know what exceptions are being thrown when there is a problem, instead of just silence).
How should I handle missing state or entities?
How can I inspect variables inside my script? (I started by using the logger, but I found that listening to events and using hass.bus.fire was a bit easier to read)
Is there any additional state, like the name of the script that is running?
What else? Maybe we need to just dig in and edit these things. I can come up with some answers myself. I’m not sure they are right, but I am getting stuff to work.
Yes, the documentation is a total disaster - I get errors on the most basic functions like isinstance() and type(); probably because they have a limited implementation.
Basically, python_script is totally useless if there’s no reference of which/how/what functions are implemented. There’s a reference to the source code; do they really expect anyone reading through all that?!?!
I found out very quickly how limiting Python Script was so I switched completely to PyScript from HACS… better documentation and the biggest benefit for me was the ability to import modules!
I couldn’t imagine ever going back to YAML… PyScript was a game changer for me.