jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-08 09:56:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clarify image entity documentation (#1964)

Browse Source 
* Clarify image entity documentation

* Fix typo

---------

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Erik Montnemery 2023-11-01 09:52:16 +01:00 committed by GitHub
parent 55ee5f1d9b
commit 06cbb9a23b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 6 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/core/entity/image.md
View File

@ -18,20 +18,22 @@ Properties should always only return information from memory and not do I/O (lik
| Name | Type | Default | Description |
| -------------------| --------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- |
| content_type | str | `image/jpeg` | The content-type of the image, set automatically if the image entity provides a URL. |
| image_last_updated | <code>datetime.datetime &#124; None</code> | `None` | Timestamp of when the image was last updated. Used to determine `state`. Frontend will refetch the image when this changes. |
| image_last_updated | <code>datetime.datetime &#124; None</code> | `None` | Timestamp of when the image was last updated. Used to determine `state`. Frontend will call `image` or `async_image` after this changes. |
| image_url | <code>str &#124; None</code> | `UNDEFINED` | Optional URL from where the image should be fetched. |
## Methods
### Image
Implement `async_image` or `image` if your entity returns bytes of the image instead of providing a URL.
Implement `async_image` or `image` if your entity returns bytes of the image instead of providing a URL. Frontend will call `async_image` or `image` to fetch the image. If the image is fetched remotely, image data should be cached and the cache invalidated when `image_last_updated` is changed.
Note that:
- The image entity's `async_image` or `image` method is only called when frontend fetches the image.
- Frontend will only refetch the image when the image entity's state changes.
- Frontend will:
- Fetch the image once when a page with an image entity is loaded
- Refetch the image when the image entity's state changed by the image entity changing `image_last_updated`
This means it's incorrect to bump the `image_last_updated` property inside `async def async_image`. It should instead be done as part of a state update to signal that an updated image is available.
This means it's incorrect to bump the `image_last_updated` property inside `async def async_image`. Instead, the image entity should, when an updated image is available or periodically if the image should be refetched after some time, update the `image_last_updated` timestamp. This can for example happen as part of an entity coordinator update.
```python
class MyImage(ImageEntity):