Python scripts: Is there any real documentation?

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?


+1 & subscribed

This is your best bet:

You could also try the documentation page :wink:

It says all about the HA API and how to fire events. It is obviously not a page to teach you to program python.

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 :slight_smile:
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}"light", "turn_on", service_data, False)

You can call it like this:

service: python_script.light_on

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.

1 Like

My quote is coming directly from the documentation page, but I can understand it is easily missed.

Yes there is, it is in de API reference here: Using Events | Home Assistant Developer Docs
There is a link on the top to this page: Events - Home Assistant

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 :slight_smile:

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

Just use appdemon and call it a day Welcome to AppDaemon’s documentation! — AppDaemon 4.1.0 documentation

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 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.


Thumb up for real + working examples.


The hello world example is working … but it needs an extra explanation… or a link to how logging and the bus works.

By default, the logger is not enabled at “info” level, so you will not see anything in the logs.

Also, to check the events on the bus, you will need to use the /developer-tools/event and subscribe to your event.

I think the hello world can be a good start, to demonstrate logging and events… but it needs a bit of extra info.

And maybe, also, insert time and datetime in the mix :slight_smile:

The documentation is open source so it should be easy to improve it :slight_smile:

I will try to find some time to send a PR for the docs.

You can access time it is already imported

builtins with limited access (see sourcce code)

  • datetime
  • sorted
  • time - which is TimeWrapper()
  • dt_util
  • min
  • max
  • sum
  • any
  • all
  • enumerate
1 Like

I started to improve the docs here Update docs for imports, logging, and events by adiroiban · Pull Request #24179 · home-assistant/ · GitHub

I think is best to move the discussion over the PR and get some constructive feedback in terms of the actual content of the docs.

the current PR is misisng info about using states and I plan to add it soon.

1 Like

God bless you