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

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)

{
    '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

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)

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

Attachments serializer

To json

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)

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

To object

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

AttachmentSerializer.to_object(attachment_json)

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

Person serializer

To json

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

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

PersonSerializer.to_json(person)

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

To object

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

PersonSerializer.to_object(person_json)

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

Attendees serializer

To json

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)

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

To object

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

AttendeeSerializer.to_object(attendee_json)

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

Conference serializer

EntryPoint

To json

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)

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

To object

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

EntryPointSerializer.to_object(entry_point_json)

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

ConferenceSolution

To json

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)

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

To object

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

ConferenceSolutionSerializer.to_object(conference_solution_json)

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

ConferenceSolutionCreateRequest

To json

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)

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

To object

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

ConferenceSolutionCreateRequestSerializer.to_object(conference_solution_create_request_json)

<ConferenceSolutionCreateRequest hangoutsMeet - status:'pending'>

Reminders serializer

To json

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

reminder = EmailReminder(minutes_before_start=30)

ReminderSerializer.to_json(reminder)

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

reminder = PopupReminder(minutes_before_start=30)

ReminderSerializer.to_json(reminder)

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

To object

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

ReminderSerializer.to_object(reminder_json)

<EmailReminder - minutes_before_start:30>

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

ReminderSerializer.to_object(reminder_json)

<PopupReminder - minutes_before_start:30>

Calendars serializer

To json

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)

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

To object

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

<Calendar Primary - Description>

CalendarListEntry serializer

To json

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)

{
    '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

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)

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

Access control rule serializer

To json

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)

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

To object

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

ACLRuleSerializer.to_object(acl_rule_json)

<AccessControlRule friend@gmail.com - reader>

FreeBusy serializer

To json

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)

{
    '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

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)

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