From 1be6ac4854e41957597554ae5e2194b2ba389c90 Mon Sep 17 00:00:00 2001
From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Date: Thu, 14 Dec 2023 10:19:47 +0100
Subject: [PATCH] Remove deprecated service list_events in favor of get_events
 (#30196)

* Deprecate service list_events in favor of get_events

- The service `calendar.list_events` is deprecated in favor or `calendar.get_events`
- in 2023.12. Scheduled to be removed in 2024.6
- This PR adds a note that this service is deprecated
- The docs for `get_events` are a topic for a separate PR
- Unlike list_events, get_events supports multiple responses
- related parent PR in core: https://github.com/home-assistant/core/pull/102481

* remove newlines

* Remove dates to align with format of other deprecation notices

* WIP: add calendar.list_events

* Add example of get_event, remove list_event

* Fix exmaple in service-calls
---
 source/_docs/scripts/service-calls.markdown |  7 +++--
 source/_integrations/calendar.markdown      | 29 +++++++++++----------
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/source/_docs/scripts/service-calls.markdown b/source/_docs/scripts/service-calls.markdown
index d153233b4ca..03424e8a7d6 100644
--- a/source/_docs/scripts/service-calls.markdown
+++ b/source/_docs/scripts/service-calls.markdown
@@ -133,13 +133,12 @@ Examples of service response data are upcoming calendar events for the next week
 
 Templates can also be used for handling response data. The service call can specify
 a `response_variable`. This is the [variable](/docs/scripts/#variables)
-that contains the response data. You can define any name for your `response_variable`. This example calls a service and stores the response in 
-the variable called `agenda`.
+that contains the response data. You can define any name for your `response_variable`. This example calls a service and stores the response in the variable called `agenda`.
 
 {% raw %}
 
 ```yaml
-service: calendar.list_events
+service: calendar.get_events
 target:
   entity_id: calendar.school
 data:
@@ -168,7 +167,7 @@ data:
   message: >-
     Your agenda for today:
     <p>
-    {% for event in agenda.events %}
+    {% for event in agenda['calendar.school'].events %}
     {{ event.start}}: {{ event.summary }}<br>
     {% endfor %}
     </p>
diff --git a/source/_integrations/calendar.markdown b/source/_integrations/calendar.markdown
index de20cd1328d..dc539ba1af0 100644
--- a/source/_integrations/calendar.markdown
+++ b/source/_integrations/calendar.markdown
@@ -192,10 +192,10 @@ data:
 {% endraw %}
 
 
-### Service `calendar.list_events`
+### Service `calendar.get_events`
 
 This service populates [Response Data](/docs/scripts/service-calls#use-templates-to-handle-response-data)
-with calendar events within a date range.
+with calendar events within a date range. It can return events from multiple calendars.
 
 | Service data attribute | Optional | Description | Example |
 | ---------------------- | -------- | ----------- | --------|
@@ -209,20 +209,20 @@ Use only one of `end_date_time` or `duration`.
 
 </div>
 
-
-{% raw %}
 ```yaml
-service: calendar.list_events
+service: calendar.get_events
 target:
-  entity_id: calendar.school
+  entity_id:
+    - calendar.school
+    - calendar.work
 data:
   duration:
     hours: 24
 response_variable: agenda
 ```
-{% endraw %}
 
-The response data field `events` is a list of events with these fields:
+The response data contains a field for every calendar entity (e.g. `calendar.school` and `calendar.work` in this case).
+Every calendar entity has a field `events` containing a list of events with these fields:
 
 | Response data | Description | Example |
 | ---------------------- | ----------- | -------- |
@@ -236,16 +236,17 @@ This example uses a template with response data in another service call:
 
 {% raw %}
 ```yaml
-service: notify.gmail_com
+service: notify.nina
 data:
-  target: gduser1@workspacesamples.dev
   title: Daily agenda for {{ now().date() }}
   message: >-
-    Your agenda for today:
-    <p>
-    {% for event in agenda.events %}
+    Your school calendar for today:
+    {% for event in agenda["calendar.school_calendar"]["events"] %}
+    {{ event.start}}: {{ event.summary }}<br>
+    {% endfor %}
+    Your work calendar for today:
+    {% for event in agenda["calendar.work_calendar"]["events"] %}
     {{ event.start}}: {{ event.summary }}<br>
     {% endfor %}
-    </p>
 ```
 {% endraw %}