File size: 6,066 Bytes
550665c |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 |
.. _calendars:
Calendars and Calendar list
============================
Calendars in `gcsa` are represented by the :py:class:`~gcsa.calendar.Calendar` and
:py:class:`~gcsa.calendar.CalendarListEntry` classes.
Calendars vs Calendar List
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The **Calendars** collection represents all existing calendars. It can be used to create and delete calendars. You can also
retrieve or set global properties shared across all users with access to a calendar. For example, a calendar's title and
default time zone are global properties.
The **Calendar List** is a collection of all calendar entries that a user has added to their list (shown in the left panel
of the web UI). You can use it to add and remove existing calendars to/from the users’ list. You also use it to retrieve
and set the values of user-specific calendar properties, such as default reminders. Another example is foreground color,
since different users can have different colors set for the same calendar.
The **GoogleCalendar** is a service responsible for processing API requests.
Calendars
~~~~~~~~~
`gcsa` allows you to create a new calendar, retrieve, update, delete and clear existing calendars.
To do so, create a :py:class:`~gcsa.google_calendar.GoogleCalendar` instance (see :ref:`getting_started` to get your
credentials):
.. code-block:: python
from gcsa.google_calendar import GoogleCalendar
gc = GoogleCalendar()
Get calendar by id
------------------
This returns an objects that stores metadata of the calendar (see more in :py:class:`~gcsa.calendar.Calendar`).
Get a calendar specified as a default in `GoogleCalendar()`
.. code-block:: python
calendar = gc.get_calendar()
To get a calendar other than the one specified as a default in `GoogleCalendar()`
.. code-block:: python
calendar = gc.get_calendar('<calendar_id>')
Add a secondary calendar
------------------------
.. code-block:: python
from gcsa.calendar import Calendar
calendar = Calendar(
'Travel calendar',
description='Calendar for travel related events'
)
calendar = gc.add_calendar(calendar)
Update calendar
---------------
.. code-block:: python
calendar.summary = 'New summary'
calendar.description = 'New description'
calendar = gc.update_calendar(calendar)
Delete calendar
---------------
.. code-block:: python
gc.delete_calendar(calendar)
or by id
.. code-block:: python
gc.delete_calendar('<calendar_id>')
Calendar has to have ``calendar_id`` to be updated or deleted. Calendars that you get from
:py:meth:`~gcsa.google_calendar.GoogleCalendar.get_calendar_list` method already have their ids.
You can also delete the calendar by providing its id.
Clear calendar
--------------
You can only clear (remove all events from) **primary** calendar.
.. code-block:: python
gc.clear_calendar()
.. warning::
This will always try to clear a **primary** calendar, regardless of the `default_calendar` value.
Calendar List
~~~~~~~~~~~~~
`gcsa` allows you to add an existing calendar into the user's calendar list, retrieve user's calendar list,
retrieve, update, and delete single entries in the user's calendar list.
To do so, create a :py:class:`~gcsa.google_calendar.GoogleCalendar` instance (see :ref:`getting_started` to get your
credentials):
.. code-block:: python
from gcsa.google_calendar import GoogleCalendar
gc = GoogleCalendar()
Get user's calendar list
------------------------
This returns the collection of calendars in the user's calendar list.
(see more in :py:class:`~gcsa.calendar.CalendarListEntry`).
.. code-block:: python
for calendar in gc.get_calendar_list():
print(calendar)
you can include deleted and hidden entries and specify the minimal access role:
.. code-block:: python
from gcsa.calendar import AccessRoles
gc.get_calendar_list(
min_access_role=AccessRoles.READER
show_deleted=True,
show_hidden=True
)
Get calendar list entry by id
-----------------------------
Get a calendar specified as a default in `GoogleCalendar()`
.. code-block:: python
gc.get_calendar_list_entry()
To get calendar other then the one specified as a default in `GoogleCalendar()`
.. code-block:: python
gc.get_calendar_list_entry('calendar_id')
Add calendar list entry
-----------------------
This adds an existing calendar into the user's calendar list
(see more in :py:class:`~gcsa.calendar.CalendarListEntry`):
.. code-block:: python
from gcsa.calendar import CalendarListEntry
calendar_list_entry = CalendarListEntry(
calendar_id='calendar_id',
summary_override='Holidays in Czechia'
)
gc.add_calendar_list_entry(calendar_list_entry)
You can make a :py:class:`~gcsa.calendar.CalendarListEntry` out of :py:class:`~gcsa.calendar.Calendar` with
:py:meth:`~gcsa.calendar.Calendar.to_calendar_list_entry` method:
.. code-block:: python
calendar = Calendar(
calendar_id='calendar_id',
summary='Státní svátky v ČR'
)
calendar_list_entry = calendar.to_calendar_list_entry(
summary_override='Holidays in Czechia'
)
gc.add_calendar_list_entry(calendar_list_entry)
Update calendar list entry
--------------------------
.. code-block:: python
calendar_list_entry.summary_override = 'Holidays in Czechia 2022'
gc.update_calendar_list_entry(calendar_list_entry)
Delete calendar list entry
--------------------------
You can use :py:class:`~gcsa.calendar.CalendarListEntry`, :py:class:`~gcsa.calendar.Calendar`, or calendar id:
.. code-block:: python
gc.delete_calendar_list_entry(calendar)
or
.. code-block:: python
gc.delete_calendar_list_entry(calendar_list_entry)
or
.. code-block:: python
gc.delete_calendar_list_entry('<calendar_id>')
|