mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-08 09:56:30 +00:00
Clarify image entity documentation (#1964)
* Clarify image entity documentation * Fix typo --------- Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
parent
55ee5f1d9b
commit
06cbb9a23b
@ -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 | 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 | 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 | 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):
|
||||
|
Loading…
x
Reference in New Issue
Block a user