Add hook for integrating with Google Calendar (#20542)

Add GoogleCalendarHook to integrate with Google Calendar.

Author: rsg17

airflow/providers/google/provider.yaml

@@ -259,6 +259,10 @@ integrations:
     external-doc-url: https://github.com/googleapis/google-api-python-client/
     logo: /integration-logos/gcp/Google-API-Python-Client.png
     tags: [google]
+  - integration-name: Google Calendar
+    external-doc-url: https://calendar.google.com/
+    logo: /integration-logos/gcp/Google-Calendar.png
+    tags: [google]
   - integration-name: Google Campaign Manager
     external-doc-url: https://developers.google.com/doubleclick-advertisers
     how-to-guide:
@@ -642,6 +646,9 @@ hooks:
   - integration-name: Google Search Ads 360
     python-modules:
       - airflow.providers.google.marketing_platform.hooks.search_ads
+  - integration-name: Google Calendar
+    python-modules:
+      - airflow.providers.google.suite.hooks.calendar
   - integration-name: Google Drive
     python-modules:
       - airflow.providers.google.suite.hooks.drive

airflow/providers/google/suite/hooks/calendar.py

@@ -0,0 +1,239 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+"""This module contains a Google Calendar API hook"""
+
+from datetime import datetime
+from typing import Any, Dict, Optional, Sequence, Union
+
+from googleapiclient.discovery import build
+
+from airflow.exceptions import AirflowException
+from airflow.providers.google.common.hooks.base_google import GoogleBaseHook
+
+
+class GoogleCalendarHook(GoogleBaseHook):
+    """
+    Interact with Google Calendar via Google Cloud connection
+    Reading and writing cells in Google Sheet:
+    https://developers.google.com/calendar/api/v3/reference
+
+    :param gcp_conn_id: The connection ID to use when fetching connection info.
+    :type gcp_conn_id: str
+    :param api_version: API Version. For example v3
+    :type api_version: str
+    :param delegate_to: The account to impersonate using domain-wide delegation of authority,
+        if any. For this to work, the service account making the request must have
+        domain-wide delegation enabled.
+    :type delegate_to: str
+    :param impersonation_chain: Optional service account to impersonate using short-term
+        credentials, or chained list of accounts required to get the access_token
+        of the last account in the list, which will be impersonated in the request.
+        If set as a string, the account must grant the originating account
+        the Service Account Token Creator IAM role.
+        If set as a sequence, the identities from the list must grant
+        Service Account Token Creator IAM role to the directly preceding identity, with first
+        account from the list granting this role to the originating account.
+    :type impersonation_chain: Union[str, Sequence[str]]
+    """
+
+    def __init__(
+        self,
+        api_version: str,
+        gcp_conn_id: str = 'google_cloud_default',
+        delegate_to: Optional[str] = None,
+        impersonation_chain: Optional[Union[str, Sequence[str]]] = None,
+    ) -> None:
+        super().__init__(
+            gcp_conn_id=gcp_conn_id,
+            delegate_to=delegate_to,
+            impersonation_chain=impersonation_chain,
+        )
+        self.gcp_conn_id = gcp_conn_id
+        self.api_version = api_version
+        self.delegate_to = delegate_to
+        self._conn = None
+
+    def get_conn(self) -> Any:
+        """
+        Retrieves connection to Google Calendar.
+
+        :return: Google Calendar services object.
+        :rtype: Any
+        """
+        if not self._conn:
+            http_authorized = self._authorize()
+            self._conn = build('calendar', self.api_version, http=http_authorized, cache_discovery=False)
+
+        return self._conn
+
+    def get_events(
+        self,
+        calendar_id: str = 'primary',
+        i_cal_uid: Optional[str] = None,
+        max_attendees: Optional[int] = None,
+        max_results: Optional[int] = None,
+        order_by: Optional[str] = None,
+        private_extended_property: Optional[str] = None,
+        q: Optional[str] = None,
+        shared_extended_property: Optional[str] = None,
+        show_deleted: Optional[bool] = False,
+        show_hidden_invitation: Optional[bool] = False,
+        single_events: Optional[bool] = False,
+        sync_token: Optional[str] = None,
+        time_max: Optional[datetime] = None,
+        time_min: Optional[datetime] = None,
+        time_zone: Optional[str] = None,
+        updated_min: Optional[datetime] = None,
+    ) -> list:
+        """
+        Gets events from Google Calendar from a single calendar_id
+        https://developers.google.com/calendar/api/v3/reference/events/list
+
+        :param calendar_id: The Google Calendar ID to interact with
+        :type calendar_id: str
+        :param i_cal_uid: Optional. Specifies event ID in the ``iCalendar`` format in the response.
+        :type i_cal_uid: str
+        :param max_attendees: Optional. If there are more than the specified number of attendees,
+            only the participant is returned.
+        :type max_attendees: int
+        :param max_results: Optional. Maximum number of events returned on one result page.
+            Incomplete pages can be detected by a non-empty ``nextPageToken`` field in the response.
+            By default the value is 250 events. The page size can never be larger than 2500 events
+        :type max_results: int
+        :param order_by: Optional. Acceptable values are ``"startTime"`` or "updated"
+        :type order_by: str
+        :param private_extended_property: Optional. Extended properties constraint specified as
+            ``propertyName=value``. Matches only private properties. This parameter might be repeated
+            multiple times to return events that match all given constraints.
+        :type private_extended_property: str
+        :param q: Optional. Free text search.
+        :type q: str
+        :param shared_extended_property: Optional. Extended properties constraint specified as
+            ``propertyName=value``. Matches only shared properties. This parameter might be repeated
+            multiple times to return events that match all given constraints.
+        :type shared_extended_property: str
+        :param show_deleted: Optional. False by default
+        :type show_deleted: bool
+        :param show_hidden_invitation: Optional. False by default
+        :type show_hidden_invitation: bool
+        :param single_events: Optional. False by default
+        :type single_events: bool
+        :param sync_token: Optional. Token obtained from the ``nextSyncToken`` field returned
+        :type sync_token: str
+        :param time_max: Optional. Upper bound (exclusive) for an event's start time to filter by.
+            Default is no filter
+        :type time_max: datetime
+        :param time_min: Optional. Lower bound (exclusive) for an event's end time to filter by.
+            Default is no filter
+        :type time_min: datetime
+        :param time_zone: Optional. Time zone used in response. Default is calendars time zone.
+        :type time_zone: str
+        :param updated_min: Optional. Lower bound for an event's last modification time
+        :type updated_min: datetime
+        :rtype: List
+        """
+        service = self.get_conn()
+        page_token = None
+        events = []
+        while True:
+            response = (
+                service.events()
+                .list(
+                    calendarId=calendar_id,
+                    iCalUID=i_cal_uid,
+                    maxAttendees=max_attendees,
+                    maxResults=max_results,
+                    orderBy=order_by,
+                    pageToken=page_token,
+                    privateExtendedProperty=private_extended_property,
+                    q=q,
+                    sharedExtendedProperty=shared_extended_property,
+                    showDeleted=show_deleted,
+                    showHiddenInvitations=show_hidden_invitation,
+                    singleEvents=single_events,
+                    syncToken=sync_token,
+                    timeMax=time_max,
+                    timeMin=time_min,
+                    timeZone=time_zone,
+                    updatedMin=updated_min,
+                )
+                .execute(num_retries=self.num_retries)
+            )
+            events.extend(response["items"])
+            page_token = response.get("nextPageToken")
+            if not page_token:
+                break
+        return events
+
+    def create_event(
+        self,
+        event: Dict[str, Any],
+        calendar_id: str = 'primary',
+        conference_data_version: Optional[int] = 0,
+        max_attendees: Optional[int] = None,
+        send_notifications: Optional[bool] = False,
+        send_updates: Optional[str] = 'false',
+        supports_attachments: Optional[bool] = False,
+    ) -> dict:
+        """
+        Create event on the specified calendar
+        https://developers.google.com/calendar/api/v3/reference/events/insert
+
+        :param calendar_id: The Google Calendar ID to interact with
+        :type calendar_id: str
+        :param conference_data_version: Optional. Version number of conference data
+            supported by the API client.
+        :type conference_data_version: int
+        :param max_attendees: Optional. If there are more than the specified number of attendees,
+            only the participant is returned.
+        :type max_attendees: int
+        :param send_notifications: Optional. Default is False
+        :type send_notifications: bool
+        :param send_updates: Optional. Default is "false". Acceptable values as "all", "none",
+            ``"externalOnly"``
+        :type send_updates: str
+        :type supports_attachments: Optional. Default is False
+        :type supports_attachments: bool
+        :type event: Required. Request body of Events resource. Start and End are required
+            https://developers.google.com/calendar/api/v3/reference/events#resource
+        :type event: dict
+        :rtype: Dict
+        """
+        if "start" not in event or "end" not in event:
+            raise AirflowException(
+                f"start and end must be specified in the event body while creating an event. API docs:"
+                f"https://developers.google.com/calendar/api/{self.api_version}/reference/events/insert "
+            )
+        service = self.get_conn()
+
+        response = (
+            service.events()
+            .insert(
+                calendarId=calendar_id,
+                conferenceDataVersion=conference_data_version,
+                maxAttendees=max_attendees,
+                sendNotifications=send_notifications,
+                sendUpdates=send_updates,
+                supportsAttachments=supports_attachments,
+                body=event,
+            )
+            .execute(num_retries=self.num_retries)
+        )
+
+        return response

docs/integration-logos/gcp/Google-Calendar.png

@@ -0,0 +1,100 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+"""
+Unit Tests for the Google Calendar Hook
+"""
+
+import unittest
+from unittest import mock
+
+from airflow.providers.google.suite.hooks.calendar import GoogleCalendarHook
+from tests.providers.google.cloud.utils.base_gcp_mock import mock_base_gcp_hook_default_project_id
+
+API_VERSION = 'api_version'
+GCP_CONN_ID = 'test'
+CALENDAR_ID = 'test12345'
+EVENT = {
+    'summary': 'Calendar Test Event',
+    'description': 'A chance to test creating an event from airflow.',
+    'start': {
+        'dateTime': '2021-12-28T09:00:00-07:00',
+        'timeZone': 'America/Los_Angeles',
+    },
+    'end': {
+        'dateTime': '2021-12-28T17:00:00-07:00',
+        'timeZone': 'America/Los_Angeles',
+    },
+}
+NUM_RETRIES = 5
+API_RESPONSE = {'test': 'response'}
+
+
+class TestGoogleCalendarHook(unittest.TestCase):
+    def setUp(self):
+        with mock.patch(
+            'airflow.providers.google.common.hooks.base_google.GoogleBaseHook.__init__',
+            new=mock_base_gcp_hook_default_project_id,
+        ):
+            self.hook = GoogleCalendarHook(api_version=API_VERSION, gcp_conn_id=GCP_CONN_ID)
+
+    @mock.patch("airflow.providers.google.suite.hooks.calendar.GoogleCalendarHook.get_conn")
+    def test_get_events(self, get_conn):
+        get_method = get_conn.return_value.events.return_value.list
+        execute_method = get_method.return_value.execute
+        execute_method.return_value = {"kind": "calendar#events", "nextPageToken": None, "items": [EVENT]}
+        result = self.hook.get_events(calendar_id=CALENDAR_ID)
+        self.assertEqual(result, [EVENT])
+        execute_method.assert_called_once_with(num_retries=NUM_RETRIES)
+        get_method.assert_called_once_with(
+            calendarId=CALENDAR_ID,
+            iCalUID=None,
+            maxAttendees=None,
+            maxResults=None,
+            orderBy=None,
+            pageToken=None,
+            privateExtendedProperty=None,
+            q=None,
+            sharedExtendedProperty=None,
+            showDeleted=False,
+            showHiddenInvitations=False,
+            singleEvents=False,
+            syncToken=None,
+            timeMax=None,
+            timeMin=None,
+            timeZone=None,
+            updatedMin=None,
+        )
+
+    @mock.patch("airflow.providers.google.suite.hooks.calendar.GoogleCalendarHook.get_conn")
+    def test_create_event(self, mock_get_conn):
+        create_mock = mock_get_conn.return_value.events.return_value.insert
+        create_mock.return_value.execute.return_value = API_RESPONSE
+
+        result = self.hook.create_event(calendar_id=CALENDAR_ID, event=EVENT)
+
+        create_mock.assert_called_once_with(
+            body=EVENT,
+            calendarId=CALENDAR_ID,
+            conferenceDataVersion=0,
+            maxAttendees=None,
+            sendNotifications=False,
+            sendUpdates='false',
+            supportsAttachments=False,
+        )
+        assert result == API_RESPONSE