🔍 Code Extractor

A collection class for managing Microsoft Outlook calendar events, providing methods to create and manage events with attendees, time zones, and other properties.

Purpose

EventCollection is a specialized collection class that extends DeltaCollection to manage Microsoft Outlook calendar events. It provides a high-level interface for creating calendar events with support for subjects, bodies, start/end times, attendees, and other event properties. The class handles the conversion of simple Python types (strings, datetimes) into the appropriate Office365 API objects (ItemBody, DateTimeTimeZone, Attendee) required by the Microsoft Graph API.

Source Code

class EventCollection(DeltaCollection[Event]):
    def __init__(self, context, resource_path=None):
        super(EventCollection, self).__init__(context, Event, resource_path)

    def add(
        self, subject=None, body=None, start=None, end=None, attendees=None, **kwargs
    ):
        # type: (str, str|ItemBody, datetime.datetime, datetime.datetime, List[str], ...) -> Event
        """
        Create an event in the user's default calendar or specified calendar.

        By default, the allowNewTimeProposals property is set to true when an event is created,
        which means invitees can propose a different date/time for the event. See Propose new meeting times
        for more information on how to propose a time, and how to receive and accept a new time proposal.

        :param str subject: The subject of the message.
        :param str or ItemBody body: The body of the message. It can be in HTML or text format
        :param datetime.datetime start: The start date, time, and time zone of the event.
             By default, the start time is in UTC.
        :param datetime.datetime end: The date, time, and time zone that the event ends.
            By default, the end time is in UTC.
        :param list[str] attendees: The collection of attendees for the event.
        """

        if body is not None:
            kwargs["body"] = body if isinstance(body, ItemBody) else ItemBody(body)
        if subject is not None:
            kwargs["subject"] = subject
        if start is not None:
            kwargs["start"] = DateTimeTimeZone.parse(start)
        if end is not None:
            kwargs["end"] = DateTimeTimeZone.parse(end)

        if attendees is not None:
            kwargs["attendees"] = ClientValueCollection(
                Attendee,
                [
                    Attendee(EmailAddress(v), attendee_type="required")
                    for v in attendees
                ],
            )

        return super(EventCollection, self).add(**kwargs)

Parameters

Parameter Details

context: The client context object that provides authentication and connection information to the Microsoft Graph API. This is required for all API operations.

resource_path: Optional path to the resource in the Microsoft Graph API. If not provided, defaults to the user's default calendar. Can be used to target specific calendars by providing their resource path.

Return Value

The constructor returns an EventCollection instance. The add() method returns an Event object representing the newly created calendar event with all its properties populated from the API response.

Class Interface

Methods

Attributes

Dependencies

• datetime
• typing
• office365

Required Imports

import datetime
from typing import List
from office365.delta_collection import DeltaCollection
from office365.outlook.calendar.attendees.attendee import Attendee
from office365.outlook.calendar.dateTimeTimeZone import DateTimeTimeZone
from office365.outlook.calendar.email_address import EmailAddress
from office365.outlook.calendar.events.event import Event
from office365.outlook.mail.item_body import ItemBody
from office365.runtime.client_value_collection import ClientValueCollection

Usage Example

from office365.graph_client import GraphClient
from datetime import datetime, timedelta

# Authenticate and get client context
client = GraphClient.with_token(access_token)

# Get the event collection from user's calendar
events = client.me.calendar.events

# Create a new event
start_time = datetime.now() + timedelta(days=1)
end_time = start_time + timedelta(hours=1)

new_event = events.add(
    subject="Team Meeting",
    body="Discuss project updates",
    start=start_time,
    end=end_time,
    attendees=["user1@example.com", "user2@example.com"]
)

# Execute the request
client.execute_query()

print(f"Event created with ID: {new_event.id}")

Best Practices

• Always provide a valid context object with proper authentication before instantiating EventCollection
• Call execute_query() on the client context after add() to actually create the event on the server
• Use datetime objects with timezone information to avoid confusion with UTC conversions
• The add() method accepts both string and ItemBody objects for the body parameter - use ItemBody for HTML formatted content
• Attendees are automatically set as 'required' type - use kwargs to pass additional Attendee objects with different types if needed
• The allowNewTimeProposals property defaults to true, allowing invitees to propose alternative times
• Handle API exceptions appropriately as network calls may fail
• Consider batch operations for creating multiple events to reduce API calls

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class Event 75.4% similar

  Represents a calendar event in Microsoft 365, providing methods to manage event responses (accept, decline, cancel), reminders, and access to event properties like attendees, attachments, and scheduling details.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/outlook/calendar/events/event.py

• class ContactCollection 72.7% similar

  A collection class for managing Microsoft Outlook contacts, providing methods to add and manage Contact objects within a contact folder or root Contacts folder.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/outlook/contacts/collection.py

• class CalendarPermissionCollection 71.6% similar

  A collection class for managing CalendarPermission entities, providing methods to add and manage permissions for calendar sharing and delegation in Microsoft 365/Outlook.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/outlook/calendar/permissions/collection.py

• class MessageCollection 70.7% similar

  A collection class for managing Microsoft Outlook email messages, extending DeltaCollection to provide message-specific operations like creating draft messages.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/outlook/mail/messages/collection.py

• class Calendar 67.4% similar

  A Calendar class representing a Microsoft 365 calendar container for events, which can be a user calendar or a Microsoft 365 group's default calendar.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/outlook/calendar/calendar.py