File add read_file action with Response #139216

PeteRager · 2025-02-24T21:34:46Z

Proposed change

Add action to allow reading a file and returning the file content as the response to be used in an automation. This allows loading content or metadata; reading incoming files; and using this data in an automation. Initially, the action supports loading JSON or YAML files.

Example action call:

action: file.read_file
data:
  file_encoding: yaml
  file_name: config/media/my_file.yaml
response_variable: my_data

Sample result

aircons:
  ac1:
    info:
      climateControlModeIsRunning: false
      countDownToOff: 10
      countDownToOn: 0
      fan: high
      filterCleanStatus: 0
      freshAirStatus: "off"
      mode: vent
      myZone: 1
      name: AC One
      setTemp: 24
      state: "on"

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

This PR fixes or closes issue: fixes #
This PR is related to issue:
Link to documentation pull request: File action read_file documentation home-assistant.io#37702
Link to developer documentation pull request:
Link to frontend pull request:

Checklist

The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
The code has been formatted using Ruff (ruff format homeassistant tests)
Tests have been added to verify that the new code works.

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

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

home-assistant · 2025-02-24T21:34:54Z

Hey there @fabaff, mind taking a look at this pull request as it has been labeled with an integration (file) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of file can trigger bot actions by commenting:

@home-assistant close Closes the pull request.
@home-assistant rename Awesome new title Renames the pull request.
@home-assistant reopen Reopen the pull request.
@home-assistant unassign file Removes the current integration label and assignees on the pull request, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

NoRi2909 · 2025-02-25T08:18:49Z

homeassistant/components/file/strings.json

+  "services": {
+    "read_file": {
+      "name": "Read File",
+      "description": "Reads a file and return the contents.",


-> "… and returns …" (third-person for both verbs :-))

In all three name keys use sentence-casing:

"Read file"

"File name"

"File encoding"

thank you, i've updated.

arturpragacz · 2025-02-25T05:00:12Z

homeassistant/components/file/services.py

+            yaml_content = yaml.safe_load(file_content)
+            if isinstance(yaml_content, dict):
+                return yaml_content
+            return {"yaml": yaml_content}


Why are we putting it in a dictionary?

When the YAML file contains a list of elements - for example in the fixture file file_read_list.yaml - a list is returned. A list is not serializable as a dict (at least as the top most element) and a runtime error gets generated when HA tries to serialize. So placing it in a dict like this allows is to be serialized. I found a similar result if the YAML file contained only a string (returns a str). So if safe_load does not return a dict we need to create a dict.

I will add a comment to the code. Perhaps we should call the dict element something other than "yaml" like "data"?

We could also always create a dict regardless of the content type, this may be more consistent and simpler. I did not do that because most YAML file are typically dicts and it would add another level to navigate when processing the response.

I like data as a key more than yaml. But my main concern is different: I don't like that users would have to guess how the response is formatted. I think that if it is a dict, you should also put in into data, so that it is consistent.
That also prevents degenerate cases, like how do you differentiate a list from a dict with a single key data and a list as a value.

Edit: I didn't see your edit when writing my response, but yes, that is what I'm proposing. I think consistency here is more important.

Ok, makes sense to me. We should also do the same thing for the json branch? So the parsing result will always be in response["data"]

Yes, let's keep it the same for all.

frenck

Thanks for this pull request @PeteRager 👍

I do think this is something I want to check in a core architectural meeting to see if this is something we would like to have on core or not mostly because this can be a potential security risk.

I'll check and get back to you once I have more information. For now, I'm marking this PR as a draft.

../Frenck

PeteRager · 2025-03-01T21:28:08Z

Thanks. I am restricting it to paths registered in allowlist_external_dirs

https://www.home-assistant.io/integrations/homeassistant/

frenck · 2025-03-01T21:57:48Z

Yes, I've seen. That is already good. Just want to make sure the rest agrees on it as well.

../Frenck

github-actions · 2025-04-30T22:05:33Z

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days.
If you are the author of this PR, please leave a comment if you want to keep it open. Also, please rebase your PR onto the latest dev branch to ensure that it's up to date with the latest changes.
Thank you for your contribution!

PeteRager · 2025-04-30T22:28:07Z

Keep

github-actions · 2025-06-29T23:06:28Z

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days.
If you are the author of this PR, please leave a comment if you want to keep it open. Also, please rebase your PR onto the latest dev branch to ensure that it's up to date with the latest changes.
Thank you for your contribution!

PeteRager · 2025-06-30T03:10:38Z

Keep

PeteRager added 10 commits February 23, 2025 16:49

initial file_read action

9eb27dc

add unit tests

a32a8b6

add unit tests

3ef8e23

add unit tests

2633e81

refactor tests

cdf656c

test docstrings

76c6f4b

simplify

4c20e79

simplify

79dd18d

fix label

9320d6b

fix label

8b4a781

PeteRager requested a review from fabaff as a code owner February 24, 2025 21:34

home-assistant bot added cla-signed has-tests integration: file new-feature labels Feb 24, 2025

home-assistant bot assigned fabaff Feb 24, 2025

home-assistant bot added the Quality Scale: No score label Feb 24, 2025

PeteRager marked this pull request as draft February 24, 2025 21:36

PeteRager added 2 commits February 24, 2025 17:13

mypy issues

b0a9853

mypy issues

d45d22a

PeteRager marked this pull request as ready for review February 24, 2025 22:22

simplify further

d91593f

NoRi2909 reviewed Feb 25, 2025

View reviewed changes

arturpragacz reviewed Feb 25, 2025

View reviewed changes

updates from code reviews

66c5441

PeteRager mentioned this pull request Feb 25, 2025

File action read_file documentation home-assistant/home-assistant.io#37702

Open

8 tasks

capitilize JSON and YAML

2b27306

frenck reviewed Mar 1, 2025

View reviewed changes

frenck marked this pull request as draft March 1, 2025 21:13

github-actions bot added the stale label Apr 30, 2025

Merge branch 'dev' into file-read

87feb5b

github-actions bot removed the stale label Apr 30, 2025

github-actions bot added the stale label Jun 29, 2025

Merge branch 'dev' into file-read

481701b

github-actions bot removed the stale label Jun 30, 2025

Uh oh!

File add read_file action with Response #139216

Are you sure you want to change the base?

File add read_file action with Response #139216

Uh oh!

Conversation

PeteRager commented Feb 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Type of change

Additional information

Checklist

Uh oh!

home-assistant bot commented Feb 24, 2025

Uh oh!

NoRi2909 Feb 25, 2025

Choose a reason for hiding this comment

Uh oh!

PeteRager Feb 25, 2025

Choose a reason for hiding this comment

Uh oh!

arturpragacz Feb 25, 2025

Choose a reason for hiding this comment

Uh oh!

PeteRager Feb 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arturpragacz Feb 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PeteRager Feb 25, 2025

Choose a reason for hiding this comment

Uh oh!

arturpragacz Feb 25, 2025

Choose a reason for hiding this comment

Uh oh!

PeteRager Feb 25, 2025

Choose a reason for hiding this comment

Uh oh!

frenck left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PeteRager commented Mar 1, 2025

Uh oh!

frenck commented Mar 1, 2025

Uh oh!

github-actions bot commented Apr 30, 2025

Uh oh!

PeteRager commented Apr 30, 2025

Uh oh!

github-actions bot commented Jun 29, 2025

Uh oh!

PeteRager commented Jun 30, 2025

Uh oh!

Uh oh!

PeteRager commented Feb 24, 2025 •

edited

Loading

PeteRager Feb 25, 2025 •

edited

Loading

arturpragacz Feb 25, 2025 •

edited

Loading

frenck left a comment •

edited

Loading