From a06dab27d015343395e9a6a93c92abcaab6dad02 Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Wed, 28 Jun 2023 10:41:23 +0200
Subject: [PATCH] Update image entity documentation (#1821)

---
 docs/core/entity/image.md | 27 ++++++++-------------------
 1 file changed, 8 insertions(+), 19 deletions(-)

diff --git a/docs/core/entity/image.md b/docs/core/entity/image.md
index e9dfa6cf..506ad120 100644
--- a/docs/core/entity/image.md
+++ b/docs/core/entity/image.md
@@ -7,6 +7,8 @@ An image entity can display a static image. Derive a platform entity from [`home
 
 The image entity is a simplified version of the [`camera`](/docs/core/entity/camera) entity, and supports serving a static image or an image URL that can be fetched.
 
+An implementation can provide either a URL from where an image will automatically be fetched or image data as `bytes`. When providing a URL, the fetched image will be cached in `self._cached_image`, set `self._cached_image` to `None` to invalidate the cache.
+
 To make frontend refetch the image, bump the `image_last_updated` property.
 
 ## Properties
@@ -15,15 +17,17 @@ To make frontend refetch the image, bump the `image_last_updated` property.
 Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
 :::
 
-| Name                     | Type  | Default | Description                                                                                                                        |
-| ------------------------ | ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| image_last_updated             | datetime  | `None`  | Timestamp of when the image was last updated. Used to determine `state`.                                                          |
+| 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       | datetime    | `None`       | Timestamp of when the image was last updated. Used to determine `state`.                                                           |
+| image_url                | str or None | `UNDEFINED`  | Optional URL from where the image should be fetched.                                                                               |
 
 ## Methods
 
 ### Image
 
-Return bytes of the image.
+Implement if your entity returns bytes of the image instead of providing a URL.
 
 ```python
 class MyImage(ImageEntity):
@@ -35,18 +39,3 @@ class MyImage(ImageEntity):
     async def async_image(self) -> bytes | None:
         """Return bytes of image."""
 ```
-
-Return the URL of an image to be fetched.
-
-```python
-class MyImage(ImageEntity):
-    # Implement one of these methods.
-
-    def image_url(self) -> str | None:
-        """Return URL of image."""
-
-    async def async_image_url(self) -> str | None:
-        """Return URL of image."""
-```
-
-By default `image_url` or `async_image_url` return `None`, and `async_image` or `image` will be called expecting to return the bytes of the image.