From 31d2d968c4b1f80ffd239aea14c2e8049499d39d Mon Sep 17 00:00:00 2001
From: Andrew Jackson <andrew@codechimp.org>
Date: Sun, 9 Feb 2025 23:01:53 +0000
Subject: [PATCH] Add optional media description to Mastodon post action
 (#137224)

Add optional media description
---
 homeassistant/components/mastodon/const.py      |  1 +
 homeassistant/components/mastodon/services.py   | 10 +++++++++-
 homeassistant/components/mastodon/services.yaml |  4 ++++
 homeassistant/components/mastodon/strings.json  |  4 ++++
 tests/components/mastodon/test_services.py      | 17 +++++++++++++++++
 5 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/homeassistant/components/mastodon/const.py b/homeassistant/components/mastodon/const.py
index b7e86eaad5a..a4af49a27a6 100644
--- a/homeassistant/components/mastodon/const.py
+++ b/homeassistant/components/mastodon/const.py
@@ -26,3 +26,4 @@ ATTR_VISIBILITY = "visibility"
 ATTR_CONTENT_WARNING = "content_warning"
 ATTR_MEDIA_WARNING = "media_warning"
 ATTR_MEDIA = "media"
+ATTR_MEDIA_DESCRIPTION = "media_description"
diff --git a/homeassistant/components/mastodon/services.py b/homeassistant/components/mastodon/services.py
index 2a919e5fa5f..7ab351f8c29 100644
--- a/homeassistant/components/mastodon/services.py
+++ b/homeassistant/components/mastodon/services.py
@@ -16,6 +16,7 @@ from .const import (
     ATTR_CONFIG_ENTRY_ID,
     ATTR_CONTENT_WARNING,
     ATTR_MEDIA,
+    ATTR_MEDIA_DESCRIPTION,
     ATTR_MEDIA_WARNING,
     ATTR_STATUS,
     ATTR_VISIBILITY,
@@ -42,6 +43,7 @@ SERVICE_POST_SCHEMA = vol.Schema(
         vol.Optional(ATTR_VISIBILITY): vol.In([x.lower() for x in StatusVisibility]),
         vol.Optional(ATTR_CONTENT_WARNING): str,
         vol.Optional(ATTR_MEDIA): str,
+        vol.Optional(ATTR_MEDIA_DESCRIPTION): str,
         vol.Optional(ATTR_MEDIA_WARNING): bool,
     }
 )
@@ -81,6 +83,7 @@ def setup_services(hass: HomeAssistant) -> None:
         )
         spoiler_text: str | None = call.data.get(ATTR_CONTENT_WARNING)
         media_path: str | None = call.data.get(ATTR_MEDIA)
+        media_description: str | None = call.data.get(ATTR_MEDIA_DESCRIPTION)
         media_warning: str | None = call.data.get(ATTR_MEDIA_WARNING)
 
         await hass.async_add_executor_job(
@@ -91,6 +94,7 @@ def setup_services(hass: HomeAssistant) -> None:
                 visibility=visibility,
                 spoiler_text=spoiler_text,
                 media_path=media_path,
+                media_description=media_description,
                 sensitive=media_warning,
             )
         )
@@ -112,9 +116,12 @@ def setup_services(hass: HomeAssistant) -> None:
                 )
 
             media_type = get_media_type(media_path)
+            media_description = kwargs.get("media_description")
             try:
                 media_data = client.media_post(
-                    media_file=media_path, mime_type=media_type
+                    media_file=media_path,
+                    mime_type=media_type,
+                    description=media_description,
                 )
 
             except MastodonAPIError as err:
@@ -125,6 +132,7 @@ def setup_services(hass: HomeAssistant) -> None:
                 ) from err
 
         kwargs.pop("media_path", None)
+        kwargs.pop("media_description", None)
 
         try:
             media_ids: str | None = None
diff --git a/homeassistant/components/mastodon/services.yaml b/homeassistant/components/mastodon/services.yaml
index 161a0d152ca..206dc36c1a2 100644
--- a/homeassistant/components/mastodon/services.yaml
+++ b/homeassistant/components/mastodon/services.yaml
@@ -24,6 +24,10 @@ post:
     media:
       selector:
         text:
+    media_description:
+      required: false
+      selector:
+        text:
     media_warning:
       required: true
       selector:
diff --git a/homeassistant/components/mastodon/strings.json b/homeassistant/components/mastodon/strings.json
index 87858f768e4..24a4247636d 100644
--- a/homeassistant/components/mastodon/strings.json
+++ b/homeassistant/components/mastodon/strings.json
@@ -89,6 +89,10 @@
           "name": "Media",
           "description": "Attach an image or video to the post."
         },
+        "media_description": {
+          "name": "Media description",
+          "description": "If an image or video is attached, will add a description for this media for people with visual impairments."
+        },
         "media_warning": {
           "name": "Media warning",
           "description": "If an image or video is attached, will mark the media as sensitive (default: no media warning)."
diff --git a/tests/components/mastodon/test_services.py b/tests/components/mastodon/test_services.py
index b958bcff74c..4dafa9a8e5b 100644
--- a/tests/components/mastodon/test_services.py
+++ b/tests/components/mastodon/test_services.py
@@ -9,6 +9,7 @@ from homeassistant.components.mastodon.const import (
     ATTR_CONFIG_ENTRY_ID,
     ATTR_CONTENT_WARNING,
     ATTR_MEDIA,
+    ATTR_MEDIA_DESCRIPTION,
     ATTR_STATUS,
     ATTR_VISIBILITY,
     DOMAIN,
@@ -75,6 +76,21 @@ from tests.common import MockConfigEntry
                 "sensitive": None,
             },
         ),
+        (
+            {
+                ATTR_STATUS: "test toot",
+                ATTR_CONTENT_WARNING: "Spoiler",
+                ATTR_MEDIA: "/image.jpg",
+                ATTR_MEDIA_DESCRIPTION: "A test image",
+            },
+            {
+                "status": "test toot",
+                "spoiler_text": "Spoiler",
+                "visibility": None,
+                "media_ids": "1",
+                "sensitive": None,
+            },
+        ),
     ],
 )
 async def test_service_post(
@@ -128,6 +144,7 @@ async def test_service_post(
                 "spoiler_text": "Spoiler",
                 "visibility": None,
                 "media_ids": "1",
+                "media_description": None,
                 "sensitive": None,
             },
         ),