Merge pull request #182 from kuzmoyev/dev

v2.3.0

Author: kuzmoyev

.github/ISSUE_TEMPLATE/bug_report.md

@@ -50,7 +50,7 @@ If applicable, add screenshots to help explain your problem.
 
 - OS: [e.g. Linux/Windows/MacOS]
 - GCSA version: [e.g. 2.0.1]
-- Python version: [e.g. 3.11]
+- Python version: [e.g. 3.12]
 
 ## Additional context
 

.github/workflows/code-cov.yml

@@ -13,7 +13,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v2
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Install dependencies
         run: pip install tox

.github/workflows/tests.yml

@@ -12,9 +12,9 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ '3.7', '3.8', '3.9', '3.10', '3.11' ]
+        python-version: [ '3.7', '3.8', '3.9', '3.10', '3.11', '3.12' ]
         include:
-          - python-version: '3.11'
+          - python-version: '3.12'
             note: with-style-and-docs-checks
 
     steps:

.gitignore

@@ -9,6 +9,7 @@ build
 dist
 .eggs
 gcsa.egg-info
+docs/html
 
 example.py
 coverage.xml

.readthedocs.yml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
 
 sphinx:
   configuration: docs/source/conf.py

docs/source/attendees.rst

@@ -61,5 +61,21 @@ or
 
     event.add_attendee('attendee@gmail.com')
 
+to add a single attendee.
+
+Use :py:meth:`~gcsa.event.Event.add_attendees` method to add multiple at once:
+
+.. code-block:: python
+
+    event.add_attendees(
+        [
+            Attendee('attendee@gmail.com',
+                display_name='Friend',
+                additional_guests=3
+            ),
+            'attendee_by_email1@gmail.com',
+            'attendee_by_email2@gmail.com'
+        ]
+    )
 
 Update event using :py:meth:`~gcsa.google_calendar.GoogleCalendar.update_event` method to save the changes.

docs/source/change_log.rst

@@ -3,6 +3,26 @@
 Change log
 ==========
 
+v2.3.0
+~~~~~~
+
+API
+---
+* Adds `add_attendees` method to the `Event` for adding multiple attendees
+* Add specific time reminders (N days before at HH:MM)
+* Support Python3.12
+* Allow service account credentials in `GoogleCalendar`
+
+Core
+----
+* Don't evaluate default arguments in code docs (primarily for `timezone=get_localzone_name()`)
+
+Backward compatibility
+----------------------
+* If token is expired but doesn't have refresh token, raises `google.auth.exceptions.RefreshError`
+  instead of sending the request
+
+
 v2.2.0
 ~~~~~~
 

docs/source/conf.py

@@ -186,3 +186,5 @@
     'css/custom.css',
     'css/colors.css',
 ]
+
+autodoc_preserve_defaults = True

docs/source/reminders.rst

@@ -56,3 +56,60 @@ To use default reminders of the calendar, set ``default_reminders`` parameter of
 to ``True``.
 
 .. note:: You can add up to 5 reminders to one event.
+
+Specific time reminders
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also set specific time for a reminder.
+
+.. code-block:: python
+
+    from datetime import time
+
+    event = Event(
+        'Meeting',
+        start=(22/Apr/2019)[12:00],
+        reminders=[
+            # Day before the event at 13:30
+            EmailReminder(days_before=1, at=time(13, 30)),
+            # 2 days before the event at 19:15
+            PopupReminder(days_before=2, at=time(19, 15))
+        ]
+    )
+
+    event.add_popup_reminder(days_before=3, at=time(8, 30))
+    event.add_email_reminder(days_before=4, at=time(9, 0))
+
+
+.. note:: Google calendar API only works with ``minutes_before_start``.
+    The GCSA's interface that uses ``days_before`` and ``at`` arguments is only a convenient way of setting specific time.
+    GCSA will convert ``days_before`` and ``at`` to ``minutes_before_start`` during API requests.
+    So after you add or update the event, it will have reminders with only ``minutes_before_start`` set even if they
+    were initially created with ``days_before`` and ``at``.
+
+    .. code-block:: python
+
+        from datetime import time
+
+        event = Event(
+            'Meeting',
+            start=(22/Apr/2019)[12:00],
+            reminders=[
+                # Day before the event at 12:00
+                EmailReminder(days_before=1, at=time(12, 00))
+            ]
+        )
+
+        event.reminders[0].minutes_before_start is None
+        event.reminders[0].days_before == 1
+        event.reminders[0].at == time(12, 00)
+
+        event = gc.add_event(event)
+
+        event.reminders[0].minutes_before_start == 24 * 60  # exactly one day before
+        event.reminders[0].days_before is None
+        event.reminders[0].at is None
+
+    GCSA does not convert ``minutes_before_start`` to ``days_before`` and ``at`` (even for the whole-day events)
+    for backwards compatibility reasons.
+

gcsa/_services/authentication.py

@@ -6,7 +6,7 @@
 from googleapiclient import discovery
 from google_auth_oauthlib.flow import InstalledAppFlow
 from google.auth.transport.requests import Request
-from google.oauth2.credentials import Credentials
+from google.auth.credentials import Credentials
 
 
 class AuthenticatedService:
@@ -24,7 +24,8 @@ def __init__(
             save_token: bool = True,
             read_only: bool = False,
             authentication_flow_host: str = 'localhost',
-            authentication_flow_port: int = 8080
+            authentication_flow_port: int = 8080,
+            authentication_flow_bind_addr: str = None
     ):
         """
         Specify ``credentials`` to use in requests or ``credentials_path`` and ``token_path`` to get credentials from.
@@ -49,6 +50,9 @@ def __init__(
                 Host to receive response during authentication flow
         :param authentication_flow_port:
                 Port to receive response during authentication flow
+        :param authentication_flow_bind_addr:
+                Optional IP address for the redirect server to listen on when it is not the same as host
+                (e.g. in a container)
         """
 
         if credentials:
@@ -66,7 +70,8 @@ def __init__(
                 scopes,
                 save_token,
                 authentication_flow_host,
-                authentication_flow_port
+                authentication_flow_port,
+                authentication_flow_bind_addr
             )
 
         self.service = discovery.build('calendar', 'v3', credentials=self.credentials)
@@ -75,7 +80,7 @@ def __init__(
     def _ensure_refreshed(
             credentials: Credentials
     ) -> Credentials:
-        if not credentials.valid and credentials.expired and credentials.refresh_token:
+        if not credentials.valid and credentials.expired:
             credentials.refresh(Request())
         return credentials
 
@@ -87,7 +92,8 @@ def _get_credentials(
             scopes: List[str],
             save_token: bool,
             host: str,
-            port: int
+            port: int,
+            bind_addr: str
     ) -> Credentials:
         credentials = None
 
@@ -101,7 +107,7 @@ def _get_credentials(
             else:
                 credentials_path = os.path.join(credentials_dir, credentials_file)
                 flow = InstalledAppFlow.from_client_secrets_file(credentials_path, scopes)
-                credentials = flow.run_local_server(host=host, port=port)
+                credentials = flow.run_local_server(host=host, port=port, bind_addr=bind_addr)
 
             if save_token:
                 with open(token_path, 'wb') as token_file: