🔍 Code Extractor

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.

Purpose

The Event class is a comprehensive representation of a Microsoft 365 calendar event, inheriting from OutlookItem. It provides full lifecycle management for calendar events including responding to invitations, managing attendees, handling attachments, working with recurring events, and accessing extended properties. The class supports operations like accepting/declining invitations with optional comments, proposing new meeting times, dismissing reminders, and canceling events. It manages complex event data including time zones, locations, attendees, and various metadata properties.

Source Code

class Event(OutlookItem):
    """An event in a user calendar, or the default calendar of a Microsoft 365 group."""

    def accept(self, send_response, comment=None):
        """
        Accept the specified event in a user calendar.

        :param bool send_response: true if a response is to be sent to the organizer; otherwise, false.
        :param str comment: Text included in the response.
        """
        payload = {"SendResponse": send_response, "Comment": comment}
        qry = ServiceOperationQuery(self, "accept", None, payload)
        self.context.add_query(qry)
        return self

    def cancel(self, comment=None):
        """
        This action allows the organizer of a meeting to send a cancellation message and cancel the event.

        The action moves the event to the Deleted Items folder. The organizer can also cancel an occurrence
        of a recurring meeting by providing the occurrence event ID.
        An attendees calling this action gets an error (HTTP 400 Bad Request), with the following error message:
            Your request can't be completed. You need to be an organizer to cancel a meeting.

        :param str comment: Text included in the response.
        """
        payload = {"Comment": comment}
        qry = ServiceOperationQuery(self, "cancel", None, payload)
        self.context.add_query(qry)
        return self

    def decline(self, proposed_new_time=None, send_response=True, comment=None):
        """
        Decline invitation to the specified event in a user calendar.

        If the event allows proposals for new times, on declining the event, an invitee can choose to suggest
        an alternative time by including the proposedNewTime parameter. For more information on how to propose a time,
        and how to receive and accept a new time proposal, see Propose new meeting times.

        :param office365.outlook.calendar.time_slot.TimeSlot proposed_new_time: An alternate date/time proposed by an
            invitee for a meeting request to start and end. Valid only for events that allow new time proposals.
            Setting this parameter requires setting sendResponse to true. Optional.
        :param bool send_response: true if a response is to be sent to the organizer; otherwise, false.
        :param str comment: Text included in the response.
        """
        payload = {
            "ProposedNewTime": proposed_new_time,
            "SendResponse": send_response,
            "Comment": comment,
        }
        qry = ServiceOperationQuery(self, "decline", None, payload)
        self.context.add_query(qry)
        return self

    def dismiss_reminder(self):
        """
        Dismiss a reminder that has been triggered for an event in a user calendar.
        """
        qry = ServiceOperationQuery(self, "dismissReminder")
        self.context.add_query(qry)
        return self

    @property
    def allow_new_time_proposals(self):
        """
        true if the meeting organizer allows invitees to propose a new time when responding; otherwise, false.
        Optional. Default is true.
        :rtype: bool or None
        """
        return self.properties.get("allowNewTimeProposals", None)

    @property
    def has_attachments(self):
        """
        Set to true if the event has attachments.
        :rtype: bool or None
        """
        return self.properties.get("hasAttachments", None)

    @property
    def hide_attendees(self):
        """
        When set to true, each attendee only sees themselves in the meeting request and meeting Tracking list.
        Default is false.
        :rtype: bool or None
        """
        return self.properties.get("hideAttendees", None)

    @property
    def ical_uid(self):
        """
        A unique identifier for an event across calendars. This ID is different for each occurrence in a recurring
        series. Read-only.
        :rtype: str or None
        """
        return self.properties.get("iCalUId", None)

    @property
    def importance(self):
        """
        The importance of the event. The possible values are: low, normal, high.
        :rtype: str
        """
        return self.properties.get("importance", None)

    @property
    def is_all_day(self):
        """
        Set to true if the event lasts all day. If true, regardless of whether it's a single-day or multi-day event,
        start and end time must be set to midnight and be in the same time zone.
        :rtype: bool or None
        """
        return self.properties.get("isAllDay", None)

    @property
    def start(self):
        """
        The date, time, and time zone that the event starts. By default, the start time is in UTC.
        """
        return self.properties.get("start", DateTimeTimeZone())

    @start.setter
    def start(self, value):
        """
        Sets the date, time, and time zone that the event starts. By default, the start time is in UTC.

        :type value: datetime.datetime
        """
        self.set_property("start", DateTimeTimeZone.parse(value))

    @property
    def end(self):
        """
        The date, time, and time zone that the event starts. By default, the start time is in UTC.
        """
        return self.properties.get("end", DateTimeTimeZone())

    @end.setter
    def end(self, value):
        """
        Sets the date, time, and time zone that the event starts. By default, the start time is in UTC.

        :type value: datetime.datetime
        """
        self.set_property("end", DateTimeTimeZone.parse(value))

    @property
    def single_value_extended_properties(self):
        """The collection of single-value extended properties defined for the event."""
        return self.properties.get(
            "singleValueExtendedProperties",
            EntityCollection(
                self.context,
                SingleValueLegacyExtendedProperty,
                ResourcePath("singleValueExtendedProperties", self.resource_path),
            ),
        )

    @property
    def multi_value_extended_properties(self):
        """The collection of multi-value extended properties defined for the event."""
        return self.properties.get(
            "multiValueExtendedProperties",
            EntityCollection(
                self.context,
                MultiValueLegacyExtendedProperty,
                ResourcePath("multiValueExtendedProperties", self.resource_path),
            ),
        )

    @property
    def body(self):
        """
        The body of the message associated with the event. It can be in HTML or text format.
        """
        return self.properties.get("body", ItemBody())

    @body.setter
    def body(self, value):
        """
        Sets The body of the message associated with the event. It can be in HTML or text format.
        """
        self.set_property("body", ItemBody(value, "HTML"))

    @property
    def body_preview(self):
        """
        The preview of the message associated with the event. It is in text format.
        :rtype: str or None
        """
        return self.properties.get("bodyPreview", None)

    @property
    def subject(self):
        # type: () -> Optional[str]
        """
        The text of the event's subject line.
        """
        return self.properties.get("subject", None)

    @subject.setter
    def subject(self, value):
        """
        Sets The text of the event's subject line.
        :type: str or None
        """
        self.set_property("subject", value)

    @property
    def location(self):
        """
        The location of the event.
        """
        return self.properties.get("location", Location())

    @property
    def web_link(self):
        """
        The URL to open the event in Outlook on the web.

        Outlook on the web opens the event in the browser if you are signed in to your mailbox. Otherwise, Outlook
        on the web prompts you to sign in.

        This URL cannot be accessed from within an iFrame.

        :rtype: str or None
        """
        return self.properties.get("webLink", None)

    @property
    def calendar(self):
        """The calendar that contains the event. Navigation property. Read-only."""
        from office365.outlook.calendar.calendar import Calendar

        return self.properties.get(
            "calendar",
            Calendar(self.context, ResourcePath("calendar", self.resource_path)),
        )

    @property
    def attendees(self):
        """The collection of attendees for the event."""
        return self.properties.setdefault("attendees", ClientValueCollection(Attendee))

    @property
    def attachments(self):
        """The collection of fileAttachment and itemAttachment attachments for the event."""
        return self.properties.get(
            "attachments",
            AttachmentCollection(
                self.context, ResourcePath("attachments", self.resource_path)
            ),
        )

    @property
    def extensions(self):
        """The collection of open extensions defined for the event. Nullable."""
        return self.properties.get(
            "extensions",
            EntityCollection(
                self.context, Extension, ResourcePath("extensions", self.resource_path)
            ),
        )

    @property
    def instances(self):
        """The occurrences of a recurring series, if the event is a series master. This property includes occurrences
        that are part of the recurrence pattern, and exceptions that have been modified, but does not include
        occurrences that have been cancelled from the series"""
        from office365.outlook.calendar.events.collection import EventCollection

        return self.properties.get(
            "instances",
            EventCollection(
                self.context, ResourcePath("instances", self.resource_path)
            ),
        )

    def get_property(self, name, default_value=None):
        if default_value is None:
            property_mapping = {
                "multiValueExtendedProperties": self.multi_value_extended_properties,
                "singleValueExtendedProperties": self.single_value_extended_properties,
            }
            default_value = property_mapping.get(name, None)
        return super(Event, self).get_property(name, default_value)

Parameters

Parameter Details

context: The client context object required for making API calls to Microsoft 365 services. Inherited from OutlookItem base class.

resource_path: The resource path identifying this event in the Microsoft Graph API hierarchy. Inherited from OutlookItem base class.

Return Value

Instantiation returns an Event object representing a Microsoft 365 calendar event. Most methods return 'self' to enable method chaining. Properties return various types including bool, str, DateTimeTimeZone objects, collections (EntityCollection, ClientValueCollection), and related objects (Calendar, Location, ItemBody). The class manages state through its properties dictionary and communicates with Microsoft 365 services through the context object.

Class Interface

Methods

Attributes

Dependencies

• office365
• typing

Required Imports

from office365.outlook.calendar.events.event import Event
from office365.outlook.calendar.dateTimeTimeZone import DateTimeTimeZone
from office365.outlook.calendar.attendees.attendee import Attendee
from office365.outlook.mail.item_body import ItemBody
from office365.outlook.mail.location import Location
from office365.outlook.calendar.time_slot import TimeSlot

Conditional/Optional Imports

These imports are only needed under specific conditions:

from office365.outlook.calendar.calendar import Calendar

from office365.outlook.calendar.events.collection import EventCollection

from office365.outlook.mail.attachments.collection import AttachmentCollection

from office365.directory.extensions.extension import Extension

Usage Example

from office365.graph_client import GraphClient
from office365.outlook.calendar.dateTimeTimeZone import DateTimeTimeZone
from datetime import datetime, timedelta

# Initialize client with credentials
client = GraphClient.with_username_and_password(tenant_name, client_id, username, password)

# Get an event from the calendar
event = client.me.calendar.events.get_by_id('event_id').execute_query()

# Accept the event
event.accept(send_response=True, comment='Looking forward to it!').execute_query()

# Access event properties
print(f'Subject: {event.subject}')
print(f'Start: {event.start.dateTime}')
print(f'Location: {event.location.displayName}')
print(f'Has attachments: {event.has_attachments}')

# Modify event
event.subject = 'Updated Meeting Title'
event.start = datetime.now() + timedelta(days=1)
event.end = datetime.now() + timedelta(days=1, hours=1)
event.update().execute_query()

# Decline with proposed new time
from office365.outlook.calendar.time_slot import TimeSlot
new_time = TimeSlot()
event.decline(proposed_new_time=new_time, send_response=True, comment='Can we reschedule?').execute_query()

# Cancel event (organizer only)
event.cancel(comment='Meeting cancelled due to conflict').execute_query()

# Work with attendees
for attendee in event.attendees:
    print(f'{attendee.emailAddress.name}: {attendee.status.response}')

# Access recurring event instances
if event.instances:
    for instance in event.instances:
        print(f'Instance: {instance.start.dateTime}')

Best Practices

• Always call execute_query() after action methods (accept, decline, cancel) to commit changes to the server
• Use method chaining for multiple operations, but remember to call execute_query() at the end
• When setting start and end times, ensure they are datetime objects; the class will convert them to DateTimeTimeZone
• Only event organizers can cancel events; attendees will receive HTTP 400 errors if they attempt to cancel
• When declining with proposed new times, ensure allow_new_time_proposals is true for the event
• Set send_response=True when accepting/declining if you want the organizer to be notified
• For all-day events, set is_all_day=True and ensure start/end times are set to midnight in the same timezone
• Access nested collections (attachments, attendees, instances) through their respective properties
• Use the context object from the parent for all API operations; don't create new contexts
• Check has_attachments before attempting to iterate over attachments to avoid unnecessary API calls
• For recurring events, use the instances property to access individual occurrences
• Extended properties (single and multi-value) are loaded lazily; access them through their respective properties
• The ical_uid is read-only and unique across calendars but differs for each occurrence in a recurring series
• When working with time zones, use DateTimeTimeZone objects which handle timezone information properly

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class Calendar 78.2% 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

• class EventMessage 77.1% similar

  A class representing an event message in Outlook, which can be a meeting request, cancellation, or response (acceptance, tentative acceptance, or decline).

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

• class EventCollection 75.4% similar

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

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

• class Attendee 71.7% similar

  Represents an event attendee in Microsoft Exchange/Office 365, which can be a person or a resource (meeting room, equipment) configured on the Exchange server.

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

• class ScheduleItem 67.1% similar

  A data class representing a calendar schedule item that describes the availability of a user or resource (room/equipment) corresponding to an actual event on their default calendar.

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