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