google-calendar-simple-api/docs/source/free_busy.rst

.. _free_busy:

Free busy
=========

With `gcsa` you can retrieve the free/busy information of the calendars and groups.

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()


Then to retrieve a free/busy information of the calendar for the following two weeks starting now use
:py:meth:`~gcsa.google_calendar.GoogleCalendar.get_free_busy`:

.. code-block:: python

    free_busy = gc.get_free_busy()

this will return a :py:class:`~gcsa.free_busy.FreeBusy` object. If only one calendar has been requested (like in
the example above, only "primary" calendar's information has been requested), you can iterate over
:py:class:`~gcsa.free_busy.FreeBusy` object directly:


.. code-block:: python

    for start, end in free_busy:
        print(f'Busy from {start} to {end}')

To request group(s) or different calendar(s) (other than one specified as default during `GoogleCalendar` creation),
use `resource_ids` argument of :py:meth:`~gcsa.google_calendar.GoogleCalendar.get_free_busy`:


.. code-block:: python

    free_busy = gc.get_free_busy('secondary_calendar_id@gmail.com')

    for start, end in free_busy:
        print(f'Busy from {start} to {end}')

or

.. code-block:: python

    free_busy = gc.get_free_busy(
        [
            'primary',
            'secondary_calendar_id@gmail.com',
            'group_id'
        ]
    )

    print('Primary calendar:')
    for start, end in free_busy.calendars['primary']:
        print(f'Busy from {start} to {end}')

    print('Secondary calendar:')
    for start, end in free_busy.calendars['secondary_calendar_id@gmail.com']:
        print(f'Busy from {start} to {end}')

    print('Group info:')
    for calendar in free_busy.groups['group_id']:
        print(f'{calendar}:')
        for start, end in free_busy.calendars[calendar]:
            print(f'Busy from {start} to {end}')

Some calendars or groups in the request might cause errors. By default `gcsa` will
raise :py:class:`~gcsa.free_busy.FreeBusyQueryError` in case of any errors. But you can ignore them with `ignore_errors`
argument:

.. code-block:: python

    free_busy = gc.get_free_busy(
        resource_ids=[
            'primary',
            'secondary_calendar_id@gmail.com',
            'group_id'
        ],
        ignore_errors=True
    )

In that case, all the errors can be found in :py:class:`~gcsa.free_busy.FreeBusy`'s `groups_errors` and
`calendars_errors` fields:

.. code-block:: python

    print(free_busy.groups_errors)
    print(free_busy.calendars_errors)