Serializers
===========

The library implements the JSON serializers for all available Google Calendar objects. JSON format is as specified in
the `official API documentation`_. In general, you won't need to use them, ``gcsa`` serializes everything as needed
under the hood. It is documented just so you know they exist and can be used if necessary.

.. note::
    Note that serializers' ``to_json`` methods ignore read-only fields of the objects.
    Read-only fields of the objects are ones that are passed to the parameters of their ``__init__`` with
    underscores, e.g. ``Event(_updated=25/Nov/2020)``.

Events serializer
~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.event import Event
    from gcsa.serializers.event_serializer import EventSerializer


    event = Event(
        'Meeting',
        start=(22 / Nov / 2020)[18:00]
    )

    EventSerializer.to_json(event)

.. code-block:: javascript

    {
        'summary': 'Meeting',
        'start': {
            'dateTime': '2020-11-22T18:00:00+01:00',
            'timeZone': 'Europe/Prague'
        },
        'end': {
            'dateTime': '2020-11-22T19:00:00+01:00',
            'timeZone': 'Europe/Prague'
        },
        'attachments': [],
        'attendees': [],
        'recurrence': [],
        'reminders': {'useDefault': False},
        'visibility': 'default'
    }


To object
---------

.. code-block:: python

    event_json = {
        'start': {
            'dateTime': '2020-11-22T18:00:00+01:00',
            'timeZone': 'Europe/Prague'
        },
        'end': {
            'dateTime': '2020-11-22T19:00:00+01:00',
            'timeZone': 'Europe/Prague'
        },
        'attachments': [],
        'attendees': [],
        'recurrence': [],
        'reminders': {'useDefault': False},
        'summary': 'Meeting',
        'visibility': 'default'
    }

    EventSerializer.to_object(event_json)

.. code-block:: python

    <Event 2020-11-22 18:00:00+01:00 - Meeting>

Attachments serializer
~~~~~~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.attachment import Attachment
    from gcsa.serializers.attachment_serializer import AttachmentSerializer

    attachment = Attachment(
        file_url='https://bit.ly/3lZo0Cc',
        title='My file',
        mime_type='application/vnd.google-apps.document'
    )

    AttachmentSerializer.to_json(attachment)

.. code-block:: javascript

    {
        'title': 'My file',
        'fileUrl': 'https://bit.ly/3lZo0Cc',
        'mimeType': 'application/vnd.google-apps.document'
    }


To object
---------

.. code-block:: python

    attachment_json = {
        'fileUrl': 'https://bit.ly/3lZo0Cc',
        'mimeType': 'application/vnd.google-apps.document',
        'title': 'My file'
    }

    AttachmentSerializer.to_object(attachment_json)

.. code-block:: python

    <Attachment 'My file' - 'https://bit.ly/3lZo0Cc'>



Person serializer
~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.person import Person
    from gcsa.serializers.person_serializer import PersonSerializer

    person = Person(
        'john@gmail.com',
        display_name='BFF',
    )

    PersonSerializer.to_json(person)

.. code-block:: javascript

    {
        'email': 'john@gmail.com'
        'displayName': 'BFF',
    }


To object
---------


.. code-block:: python

    person_json = {
        'email': 'john@gmail.com',
        'displayName': 'BFF',
        'id': '123123',
        'self': True
    }

    PersonSerializer.to_object(person_json)

.. code-block:: python

    <Person 'john@gmail.com' - 'BFF'>


Attendees serializer
~~~~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.attendee import Attendee
    from gcsa.serializers.attendee_serializer import AttendeeSerializer

    attendee = Attendee(
        'john@gmail.com',
        display_name='BFF',
        additional_guests=2
    )

    AttendeeSerializer.to_json(attendee)

.. code-block:: javascript

    {
        'email': 'john@gmail.com'
        'displayName': 'BFF',
        'additionalGuests': 2,
    }


To object
---------

.. code-block:: python

    attendee_json = {
        'email': 'john@gmail.com',
        'displayName': 'BFF',
        'additionalGuests': 2,
        'responseStatus': 'needsAction'
    }

    AttendeeSerializer.to_object(attendee_json)

.. code-block:: python

    <Attendee 'john@gmail.com' - response: 'needsAction'>


Conference serializer
~~~~~~~~~~~~~~~~~~~~~

EntryPoint
----------

To json
*******


.. code-block:: python

    from gcsa.conference import EntryPoint
    from gcsa.serializers.conference_serializer import EntryPointSerializer

    entry_point = EntryPoint(
        EntryPoint.VIDEO,
        uri='https://meet.google.com/aaa-bbbb-ccc'
    )

    EntryPointSerializer.to_json(entry_point)

.. code-block:: javascript

    {
        'entryPointType': 'video',
        'uri': 'https://meet.google.com/aaa-bbbb-ccc'
    }


To object
*********

.. code-block:: python

    entry_point_json = {
        'entryPointType': 'video',
        'uri': 'https://meet.google.com/aaa-bbbb-ccc'
    }

    EntryPointSerializer.to_object(entry_point_json)

.. code-block:: python

    <EntryPoint video - 'https://meet.google.com/aaa-bbbb-ccc'>


ConferenceSolution
------------------

To json
*******


.. code-block:: python

    from gcsa.conference import ConferenceSolution, EntryPoint, SolutionType
    from gcsa.serializers.conference_serializer import ConferenceSolutionSerializer

    conference_solution = ConferenceSolution(
        entry_points=EntryPoint(
            EntryPoint.VIDEO,
            uri='https://meet.google.com/aaa-bbbb-ccc'
        ),
        solution_type=SolutionType.HANGOUTS_MEET,
    )

    ConferenceSolutionSerializer.to_json(conference_solution)

.. code-block:: javascript

    {
        'conferenceSolution': {
            'key': {
                'type': 'hangoutsMeet'
            }
        },
        'entryPoints': [
            {
                'entryPointType': 'video',
                'uri': 'https://meet.google.com/aaa-bbbb-ccc'
            }
        ]
    }


To object
*********

.. code-block:: python

    conference_solution_json = {
        'conferenceSolution': {
            'key': {
                'type': 'hangoutsMeet'
            }
        },
        'entryPoints': [
            {
                'entryPointType': 'video',
                'uri': 'https://meet.google.com/aaa-bbbb-ccc'
            }
        ]
    }

    ConferenceSolutionSerializer.to_object(conference_solution_json)

.. code-block:: python

    <ConferenceSolution hangoutsMeet - [<EntryPoint video - 'https://meet.google.com/aaa-bbbb-ccc'>]>


ConferenceSolutionCreateRequest
-------------------------------

To json
*******


.. code-block:: python

    from gcsa.conference import ConferenceSolutionCreateRequest, SolutionType
    from gcsa.serializers.conference_serializer import ConferenceSolutionCreateRequestSerializer

    conference_solution_create_request = ConferenceSolutionCreateRequest(
        solution_type=SolutionType.HANGOUTS_MEET,
    )

    ConferenceSolutionCreateRequestSerializer.to_json(conference_solution_create_request)

.. code-block:: javascript

    {
        'createRequest': {
            'conferenceSolutionKey': {
                'type': 'hangoutsMeet'
            },
            'requestId': '30b8e7c4d595445aa73c3feccf4b4f06'
        }
    }


To object
*********

.. code-block:: python

    conference_solution_create_request_json = {
        'createRequest': {
            'conferenceSolutionKey': {
                'type': 'hangoutsMeet'
            },
            'requestId': '30b8e7c4d595445aa73c3feccf4b4f06',
            'status': {
                'statusCode': 'pending'
            }
        }
    }

    ConferenceSolutionCreateRequestSerializer.to_object(conference_solution_create_request_json)

.. code-block:: python

    <ConferenceSolutionCreateRequest hangoutsMeet - status:'pending'>


Reminders serializer
~~~~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.reminders import EmailReminder, PopupReminder
    from gcsa.serializers.reminder_serializer import ReminderSerializer

    reminder = EmailReminder(minutes_before_start=30)

    ReminderSerializer.to_json(reminder)

.. code-block:: javascript

    {
        'method': 'email',
        'minutes': 30
    }

.. code-block:: python

    reminder = PopupReminder(minutes_before_start=30)

    ReminderSerializer.to_json(reminder)

.. code-block:: javascript

    {
        'method': 'popup',
        'minutes': 30
    }


To object
---------

.. code-block:: python

    reminder_json = {
        'method': 'email',
        'minutes': 30
    }

    ReminderSerializer.to_object(reminder_json)

.. code-block:: python

    <EmailReminder - minutes_before_start:30>

.. code-block:: python

    reminder_json = {
        'method': 'popup',
        'minutes': 30
    }

    ReminderSerializer.to_object(reminder_json)

.. code-block:: python

    <PopupReminder - minutes_before_start:30>



Calendars serializer
~~~~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.calendar import Calendar, AccessRoles
    from gcsa.serializers.calendar_serializer import CalendarSerializer

    calendar = Calendar(
        summary='Primary',
        calendar_id='primary',
        description='Description',
        location='Location',
        timezone='Timezone',
        allowed_conference_solution_types=[
            AccessRoles.FREE_BUSY_READER,
            AccessRoles.READER,
            AccessRoles.WRITER,
            AccessRoles.OWNER,
        ]
    )

    CalendarSerializer.to_json(calendar)

.. code-block:: javascript

    {
        'id': 'primary',
        'summary': 'Primary',
        'description': 'Description',
        'location': 'Location',
        'timeZone': 'Timezone',
        'conferenceProperties': {
            'allowedConferenceSolutionTypes': [
                'freeBusyReader',
                'reader',
                'writer',
                'owner'
            ]
        }
    }


To object
---------

.. code-block:: python

    calendar_json = {
        'id': 'primary',
        'summary': 'Primary',
        'description': 'Description',
        'location': 'Location',
        'timeZone': 'Timezone',
        'conferenceProperties': {
            'allowedConferenceSolutionTypes': [
                'freeBusyReader',
                'reader',
                'writer',
                'owner'
            ]
        }
    }
    CalendarSerializer.to_object(calendar_json)

.. code-block:: python

    <Calendar Primary - Description>



CalendarListEntry serializer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.calendar import CalendarListEntry, NotificationType
    from gcsa.reminders import EmailReminder
    from gcsa.serializers.calendar_serializer import CalendarListEntrySerializer

    calendar_list_entry = CalendarListEntry(
        calendar_id='<calendar_id>',
        summary_override='Holidays in Czechia 2022',
        color_id='2',
        background_color='#123456',
        foreground_color='#234567',
        hidden=True,
        selected=False,
        default_reminders=[EmailReminder(minutes_before_start=15)],
        notification_types=[
            NotificationType.EVENT_CREATION,
            NotificationType.EVENT_CHANGE
        ]
    )

    CalendarListEntrySerializer.to_json(calendar_list_entry)

.. code-block:: javascript

    {
        'id': '<calendar_id>',
        'summaryOverride': 'Holidays in Czechia 2022',
        'colorId': '2',
        'backgroundColor': '#123456',
        'foregroundColor': '#234567',
        'hidden': True,
        'selected': False,
        'defaultReminders': [
            {'method': 'email', 'minutes': 15}
        ],
        'notificationSettings': {
            'notifications': [
                {'type': 'eventCreation', 'method': 'email'},
                {'type': 'eventChange', 'method': 'email'}
            ]
        }
    }


To object
---------

.. code-block:: python

    calendar_list_entry_json = {
        'id': '<calendar_id>',
        'summary': 'Státní svátky v ČR',
        'summaryOverride': 'Holidays in Czechia 2022',
        'colorId': '2',
        'backgroundColor': '#123456',
        'foregroundColor': '#234567',
        'hidden': True,
        'selected': False,
        'defaultReminders': [
            {'method': 'email', 'minutes': 15}
        ],
        'notificationSettings': {
            'notifications': [
                {'type': 'eventCreation', 'method': 'email'},
                {'type': 'eventChange', 'method': 'email'}
            ]
        }
    }

    CalendarListEntrySerializer.to_object(calendar_list_entry_json)


.. code-block:: python

    <CalendarListEntry Holidays in Czechia 2022 - (Státní svátky v ČR)>



Access control rule serializer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.acl import AccessControlRule, ACLRole, ACLScopeType
    from gcsa.serializers.acl_rule_serializer import ACLRuleSerializer

    rule = AccessControlRule(
        role=ACLRole.READER,
        scope_type=ACLScopeType.USER,
        scope_value='friend@gmail.com',
    )

    ACLRuleSerializer.to_json(rule)


.. code-block:: javascript

    {
        'role': 'reader',
        'scope': {
            'type': 'user',
            'value': 'friend@gmail.com'
        }
    }


To object
---------

.. code-block:: python

    acl_rule_json = {
        'role': 'reader',
        'scope': {
            'type': 'user',
            'value': 'friend@gmail.com'
        },
        'id': 'user:friend@gmail.com'
    }

    ACLRuleSerializer.to_object(acl_rule_json)

.. code-block:: python

    <AccessControlRule friend@gmail.com - reader>



FreeBusy serializer
~~~~~~~~~~~~~~~~~~~

To json
-------

.. code-block:: python

    from gcsa.free_busy import FreeBusy, TimeRange
    from gcsa.serializers.free_busy_serializer import FreeBusySerializer

    free_busy = FreeBusy(
        time_min=(24 / Mar / 2023)[13:22],
        time_max=(25 / Mar / 2023)[13:22],
        groups={'group1': ['calendar1', 'calendar2']},
        calendars={
            'calendar1': [
                TimeRange((24 / Mar / 2023)[14:22], (24 / Mar / 2023)[15:22]),
                TimeRange((24 / Mar / 2023)[17:22], (24 / Mar / 2023)[18:22]),
            ],
            'calendar2': [
                TimeRange((24 / Mar / 2023)[15:22], (24 / Mar / 2023)[16:22]),
                TimeRange((24 / Mar / 2023)[18:22], (24 / Mar / 2023)[19:22]),
            ]
        },
        groups_errors={
            "non-existing-group": [
                {
                    "domain": "global",
                    "reason": "notFound"
                }
            ]
        },
        calendars_errors={
            "non-existing-calendar": [
                {
                    "domain": "global",
                    "reason": "notFound"
                }
            ]
        }
    )

    FreeBusySerializer.to_json(free_busy)


.. code-block:: javascript

    {
        'calendars': {
            'calendar1': {
                'busy': [
                    {'start': '2023-03-24T14:22:00', 'end': '2023-03-24T15:22:00'},
                    {'start': '2023-03-24T17:22:00', 'end': '2023-03-24T18:22:00'}
                ],
                'errors': []
            },
            'calendar2': {
                'busy': [
                    {'start': '2023-03-24T15:22:00', 'end': '2023-03-24T16:22:00'},
                    {'start': '2023-03-24T18:22:00', 'end': '2023-03-24T19:22:00'}
                ],
                'errors': []
            },
            'non-existing-calendar': {
                'busy': [],
                'errors': [
                    {'domain': 'global', 'reason': 'notFound'}
                ]
            }
        },
        'groups': {
            'group1': {
                'calendars': ['calendar1', 'calendar2'],
                'errors': []
            },
            'non-existing-group': {
                'calendars': [],
                'errors': [
                    {'domain': 'global', 'reason': 'notFound'}
                ]
            }
        },
        'timeMin': '2023-03-24T13:22:00',
        'timeMax': '2023-03-25T13:22:00'
    }


To object
---------

.. code-block:: python

    free_busy_json = {
        'calendars': {
            'calendar1': {
                'busy': [
                    {'start': '2023-03-24T14:22:00', 'end': '2023-03-24T15:22:00'},
                    {'start': '2023-03-24T17:22:00', 'end': '2023-03-24T18:22:00'}
                ],
                'errors': []
            },
            'calendar2': {
                'busy': [
                    {'start': '2023-03-24T15:22:00', 'end': '2023-03-24T16:22:00'},
                    {'start': '2023-03-24T18:22:00', 'end': '2023-03-24T19:22:00'}
                ],
                'errors': []
            },
            'non-existing-calendar': {
                'busy': [],
                'errors': [
                    {'domain': 'global', 'reason': 'notFound'}
                ]
            }
        },
        'groups': {
            'group1': {
                'calendars': ['calendar1', 'calendar2'],
                'errors': []
            },
            'non-existing-group': {
                'calendars': [],
                'errors': [
                    {'domain': 'global', 'reason': 'notFound'}
                ]
            }
        },
        'timeMin': '2023-03-24T13:22:00',
        'timeMax': '2023-03-25T13:22:00'
    }

    FreeBusySerializer.to_object(free_busy_json)

.. code-block:: python

    <FreeBusy 2023-03-24 13:22:00 - 2023-03-25 13:22:00>



.. _`official API documentation`: https://developers.google.com/calendar