From 41754785b14b71d3aa260d345bb6e63d64dce83a Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Tue, 29 Mar 2022 08:21:39 -0700 Subject: [PATCH 1/5] 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. | From 47e56b4c161d7b9c8cc6d7c1dc3ff9dcd3d27ea3 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Tue, 29 Mar 2022 20:52:05 -0700 Subject: [PATCH 2/5] Rename entity to CalendarEntity --- docs/core/entity/calendar.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/entity/calendar.md b/docs/core/entity/calendar.md index 0ed26f94..5c94f232 100644 --- a/docs/core/entity/calendar.md +++ b/docs/core/entity/calendar.md @@ -4,7 +4,7 @@ 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). +and end date and/or time, helpful for automations. A calendar entity is derived from the [`homeassistant.components.calendar.CalendarEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/calendar/__init__.py). ## Properties @@ -34,7 +34,7 @@ A calendar entity can return events that occur during a particular time range. S - Recurring events should be flattened and returned as individual `CalendarEvent`. ```python -class MyCalendar(CalendarEventDevice): +class MyCalendar(CalendarEntity): async def async_get_events( self, From 4bd1062318acce822c68ba9572e5a6cc96506ed5 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Tue, 29 Mar 2022 20:53:46 -0700 Subject: [PATCH 3/5] Fix typo in calendar entity descriptions. --- docs/core/entity/calendar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/entity/calendar.md b/docs/core/entity/calendar.md index 5c94f232..d257f775 100644 --- a/docs/core/entity/calendar.md +++ b/docs/core/entity/calendar.md @@ -51,7 +51,7 @@ 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. | +| start | datetime or date | **Required** | The start (inclusive) of the event. Must be before `end`. Both `start` and `end` must be the same type. | | 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. | From 8b03cd649e6b3ed6830b1b8c820f1b127d4569a6 Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Tue, 29 Mar 2022 20:55:19 -0700 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Martin Hjelmare --- docs/core/entity/calendar.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/entity/calendar.md b/docs/core/entity/calendar.md index d257f775..d59b9dc4 100644 --- a/docs/core/entity/calendar.md +++ b/docs/core/entity/calendar.md @@ -47,12 +47,12 @@ class MyCalendar(CalendarEntity): ## CalendarEvent -A `CalendarEvent` represents individual event on a calendar. +A `CalendarEvent` represents an 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 type. | | 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. | +| summary | string | **Required** | A title or summary of the event. | | location | string | `None` | A geographic location of the event. | | description | string | `None` | A detailed description of the event. | From 5edf0f2b1d78dc229768966df2438f8ba671d9eb Mon Sep 17 00:00:00 2001 From: Allen Porter Date: Wed, 30 Mar 2022 14:48:30 +0000 Subject: [PATCH 5/5] Update CalendarEvent table to include a mention of required timezone --- docs/core/entity/calendar.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/core/entity/calendar.md b/docs/core/entity/calendar.md index d59b9dc4..6c6dcbc7 100644 --- a/docs/core/entity/calendar.md +++ b/docs/core/entity/calendar.md @@ -49,10 +49,10 @@ class MyCalendar(CalendarEntity): A `CalendarEvent` represents an 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 type. | -| end | datetime or date | **Required** | The end (exclusive) of the event. Must be after `start`. | -| summary | string | **Required** | A title or summary of the event. | -| location | string | `None` | A geographic location of the event. | -| description | string | `None` | A detailed description of the event. | +| 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 type. As a datetime, must be in UTC timezone. | +| end | datetime or date | **Required** | The end (exclusive) of the event. Must be after `start`. As a datetime, must be in UTC timezone. | +| summary | string | **Required** | A title or summary of the event. | +| location | string | `None` | A geographic location of the event. | +| description | string | `None` | A detailed description of the event. |