From 41754785b14b71d3aa260d345bb6e63d64dce83a Mon Sep 17 00:00:00 2001
From: Allen Porter <allen@thebends.org>
Date: Tue, 29 Mar 2022 08:21:39 -0700
Subject: [PATCH] Add a CalendarEntity specification

Add documentation for CalendarEntity that describes the API, since it is currently ambiguous.

This proposes some specific behaviors around start/date times that may be inconsistent
which are inconsistent wiht some existing integrations as a path forward to making all
integrations have consistent behavior.
---
 docs/core/entity/calendar.md | 58 ++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 docs/core/entity/calendar.md

diff --git a/docs/core/entity/calendar.md b/docs/core/entity/calendar.md
new file mode 100644
index 00000000..0ed26f94
--- /dev/null
+++ b/docs/core/entity/calendar.md
@@ -0,0 +1,58 @@
+---
+title: Calendar Entity
+sidebar_label: Calendar
+---
+
+A calendar entity is an entity that represents a set of events with a start
+and end date and/or time, helpful for automations. A calendar entity is derived from the [`homeassistant.components.calendar.CalendarEventDevice`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/calendar/__init__.py).
+
+## Properties
+
+:::tip
+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                                             |
+| ----- | ------------- | --------------------- | ------------------------------------------------------- |
+| event | CalendarEvent | `NotImplementedError` | The current or next upcoming `CalendarEvent` or `None`. |
+
+### States
+
+| Constant    | Description                                 |
+| ----------- | ------------------------------------------- |
+| `STATE_ON`  | The calendar has an active event.           |
+| `STATE_OFF` | The calendar does not have an active event. |
+
+## Methods
+
+### Get Events
+
+A calendar entity can return events that occur during a particular time range. Some notes for implementors:
+
+- The `start_date` is the lower bound and applied to the event's `end` (exclusive).
+- The `end_date` is the upper bound and applied to the event's `start` (exclusive).
+- Recurring events should be flattened and returned as individual `CalendarEvent`.
+
+```python
+class MyCalendar(CalendarEventDevice):
+
+    async def async_get_events(
+        self,
+        hass: HomeAssistant,
+        start_date: datetime.datetime,
+        end_date: datetime.datetime,
+    ) -> list[CalendarEvent]:
+        """Return calendar events within a datetime range."""
+```
+
+## CalendarEvent
+
+A `CalendarEvent` represents individual event on a calendar.
+
+| Name        | Type             | Default      | Description                                                          |
+| ----------- | ---------------- | ------------ | -------------------------------------------------------------------- |
+| start       | datetime or date | **Required** | The start (inclusive) of the event.  Must be before `end`. Both `start` and `end` must be the same time.                                             |
+| end         | datetime or date | **Required** | The end (exclusive) of the event. Must be after `start`.                                               |
+| summary     | string           | **Required** | A title o summary of the event.                                      |
+| location    | string           | `None`       | A geographic location of the event.                                  |
+| description | string           | `None`       | A detailed description of the event.                                  |