File size: 4,711 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 |
.. _events:
Events
======
Event in `gcsa` is represented by the class :py:class:`~gcsa.event.Event`. It stores all the needed information about
the event including its summary, starting and ending dates/times, attachments, reminders, recurrence rules, etc.
`gcsa` allows you to create a new events, retrieve, update, move and delete existing events.
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()
List events
~~~~~~~~~~~
This code will print out events for one year starting today:
.. code-block:: python
for event in gc:
print(event)
.. note::
In the following examples, :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_events` and
:py:meth:`~gcsa.google_calendar.GoogleCalendar.get_instances` return generators_. You can iterate over them directly:
.. code-block::
for event in gc.get_events():
print(event)
but to get the list of events use:
.. code-block::
events = list(gc.get_events())
Specify range of listed events in two ways:
.. code-block:: python
events = gc.get_events(time_min, time_max, order_by='updated')
or
.. code-block:: python
events = gc[time_min:time_max:'updated']
``time_min`` and ``time_max`` can be ``date`` or ``datetime`` objects. ``order_by`` can be `'startTime'`
or `'updated'`. If not specified, unspecified stable order is used.
Use ``query`` parameter for free text search through all event fields (except for extended properties):
.. code-block:: python
events = gc.get_events(query='Meeting')
or
.. code-block:: python
events = gc.get_events(query='John') # Name of attendee
Use ``single_events`` parameter to expand recurring events into instances and only return single one-off events and
instances of recurring events, but not the underlying recurring events themselves.
.. code-block:: python
events = gc.get_events(single_events=True)
List recurring event instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
events = gc.get_instances('<recurring_event_id>')
or
.. code-block:: python
events = gc.get_instances(recurring_event)
where ``recurring_event`` is :py:class:`~gcsa.event.Event` object with set ``event_id``. You'd probably get it from
the ``get_events`` method.
Get event by id
~~~~~~~~~~~~~~~
.. code-block:: python
event = gc.get_event('<event_id>')
Create event
~~~~~~~~~~~~
.. code-block:: python
from beautiful_date import Apr, hours
from gcsa.event import Event
start = (22/Apr/2019)[12:00]
end = start + 2 * hours
event = Event('Meeting',
start=start,
end=end)
or to create an **all-day** event, use a `date` object:
.. code-block:: python
from beautiful_date import Aug, days
from gcsa.event import Event
start = 1/Aug/2021
end = start + 7 * days
event = Event('Vacation',
start=start,
end=end)
For ``date``/``datetime`` objects you can use Pythons datetime_ module or as in the
example beautiful_date_ library (*because it's beautiful... just like you*).
Now **add** your event to the calendar:
.. code-block:: python
event = gc.add_event(event)
See dedicated pages on how to add :ref:`attendees`, :ref:`attachments`, :ref:`conference`, :ref:`reminders`, and
:ref:`recurrence` to an event.
Update event
~~~~~~~~~~~~
.. code-block:: python
event.location = 'Prague'
event = gc.update_event(event)
Import event
~~~~~~~~~~~~
.. code-block:: python
event = gc.import_event(event)
This operation is used to add a private copy of an existing event to a calendar.
Move event to another calendar
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
event = gc.move_event(event, destination_calendar_id='primary')
Delete event
~~~~~~~~~~~~
.. code-block:: python
gc.delete_event(event)
Event has to have ``event_id`` to be updated, moved, or deleted. Events that you get from
:py:meth:`~gcsa.google_calendar.GoogleCalendar.get_events` method already have their ids.
You can also delete the event by providing its id.
.. code-block:: python
gc.delete_event('<event_id>')
.. _datetime: https://docs.python.org/3/library/datetime.html
.. _beautiful_date: https://github.com/kuzmoyev/beautiful-date
.. _generators: https://wiki.python.org/moin/Generators
|