0
# Calendar and Scheduling
1

2
Full calendar functionality including event creation, scheduling, attendee management, recurring events, meeting rooms, and calendar sharing across multiple calendars.
3

4
## Capabilities
5

6
### Schedule Access
7

8
Access calendar services for the authenticated user or other users with proper permissions.
9

10
```python { .api }
11
def schedule(self, resource: str = None) -> Schedule:
12
    """
13
    Get a schedule instance for calendar operations.
14
    
15
    Parameters:
16
    - resource: user resource identifier (defaults to authenticated user)
17
    
18
    Returns:
19
    - Schedule: Schedule instance for calendar operations
20
    """
21

22
class Schedule:
23
    def __init__(self, parent: Account, main_resource: str = None): ...
24
    
25
    def get_default_calendar(self) -> Calendar:
26
        """Get the user's default calendar."""
27
    
28
    def get_calendars(self, limit: int = None) -> list[Calendar]:
29
        """
30
        Get all accessible calendars.
31
        
32
        Parameters:
33
        - limit: maximum number of calendars to return
34
        
35
        Returns:
36
        - list[Calendar]: List of calendar objects
37
        """
38
    
39
    def get_calendar(self, calendar_id: str = None, calendar_name: str = None) -> Calendar:
40
        """
41
        Get a specific calendar by ID or name.
42
        
43
        Parameters:
44
        - calendar_id: calendar identifier
45
        - calendar_name: calendar display name
46
        
47
        Returns:
48
        - Calendar: Calendar object
49
        """
50
```
51

52
### Calendar Management
53

54
Manage calendars including creation, sharing, and permissions.
55

56
```python { .api }
57
def new_calendar(self, calendar_name: str) -> Calendar:
58
    """
59
    Create a new calendar.
60
    
61
    Parameters:
62
    - calendar_name: name for the new calendar
63
    
64
    Returns:
65
    - Calendar: Created calendar object
66
    """
67

68
class Calendar:
69
    @property
70
    def name(self) -> str:
71
        """Calendar display name."""
72
    
73
    @property
74
    def color(self) -> str:
75
        """Calendar color identifier."""
76
    
77
    @property
78
    def owner(self) -> str:
79
        """Calendar owner email address."""
80
    
81
    @property
82
    def can_edit(self) -> bool:
83
        """Whether the user can edit this calendar."""
84
    
85
    @property
86
    def can_share(self) -> bool:
87
        """Whether the user can share this calendar."""
88
    
89
    def delete(self) -> bool:
90
        """Delete this calendar."""
91
    
92
    def update(self) -> bool:
93
        """Save changes to the calendar."""
94
```
95

96
### Event Operations
97

98
Create, retrieve, update, and delete calendar events.
99

100
```python { .api }
101
def get_events(self, limit: int = None, include_recurring: bool = True, **filters) -> list[Event]:
102
    """
103
    Get events from calendars.
104
    
105
    Parameters:
106
    - limit: maximum number of events to return
107
    - include_recurring: whether to include recurring event instances
108
    - filters: OData query filters (start_time, end_time, subject, etc.)
109
    
110
    Returns:
111
    - list[Event]: List of event objects
112
    """
113

114
def new_event(self, subject: str = None, start: datetime = None, end: datetime = None) -> Event:
115
    """
116
    Create a new event.
117
    
118
    Parameters:
119
    - subject: event subject/title
120
    - start: event start datetime
121
    - end: event end datetime
122
    
123
    Returns:
124
    - Event: New event object
125
    """
126

127
class Event:
128
    @property
129
    def subject(self) -> str:
130
        """Event subject/title."""
131
    
132
    @property
133
    def body(self) -> str:
134
        """Event body/description."""
135
    
136
    @property
137
    def start(self) -> datetime:
138
        """Event start datetime."""
139
    
140
    @property
141
    def end(self) -> datetime:
142
        """Event end datetime."""
143
    
144
    @property
145
    def location(self) -> str:
146
        """Event location."""
147
    
148
    @property
149
    def is_all_day(self) -> bool:
150
        """Whether this is an all-day event."""
151
    
152
    @property
153
    def organizer(self) -> Recipient:
154
        """Event organizer information."""
155
    
156
    @property
157
    def attendees(self) -> list[Attendee]:
158
        """Event attendees list."""
159
    
160
    @property
161
    def importance(self) -> str:
162
        """Event importance level (Low, Normal, High)."""
163
    
164
    @property
165
    def sensitivity(self) -> str:
166
        """Event sensitivity (Normal, Personal, Private, Confidential)."""
167
    
168
    def save(self) -> bool:
169
        """Save changes to the event."""
170
    
171
    def delete(self) -> bool:
172
        """Delete this event."""
173
    
174
    def accept(self, send_response: bool = True) -> bool:
175
        """Accept the event invitation."""
176
    
177
    def decline(self, send_response: bool = True) -> bool:
178
        """Decline the event invitation."""
179
    
180
    def tentative(self, send_response: bool = True) -> bool:
181
        """Respond tentatively to the event invitation."""
182
```
183

184
### Attendee Management
185

186
Manage event attendees and their responses.
187

188
```python { .api }
189
class Attendee:
190
    @property
191
    def address(self) -> str:
192
        """Attendee email address."""
193
    
194
    @property
195
    def name(self) -> str:
196
        """Attendee display name."""
197
    
198
    @property
199
    def response_status(self) -> str:
200
        """Response status (None, Accepted, Declined, TentativelyAccepted)."""
201
    
202
    @property
203
    def response_time(self) -> datetime:
204
        """When the attendee responded."""
205
    
206
    @property
207
    def type(self) -> str:
208
        """Attendee type (Required, Optional, Resource)."""
209

210
def add_attendees(self, attendees: list) -> bool:
211
    """
212
    Add attendees to the event.
213
    
214
    Parameters:
215
    - attendees: list of email addresses or Attendee objects
216
    
217
    Returns:
218
    - bool: True if successful
219
    """
220

221
def remove_attendees(self, attendees: list) -> bool:
222
    """
223
    Remove attendees from the event.
224
    
225
    Parameters:
226
    - attendees: list of email addresses or Attendee objects
227
    
228
    Returns:
229
    - bool: True if successful
230
    """
231
```
232

233
### Recurring Events
234

235
Create and manage recurring event patterns.
236

237
```python { .api }
238
class RecurrencePattern:
239
    @property
240
    def type(self) -> str:
241
        """Recurrence type (Daily, Weekly, Monthly, Yearly)."""
242
    
243
    @property
244
    def interval(self) -> int:
245
        """Recurrence interval."""
246
    
247
    @property
248
    def days_of_week(self) -> list[str]:
249
        """Days of week for weekly recurrence."""
250
    
251
    @property
252
    def day_of_month(self) -> int:
253
        """Day of month for monthly recurrence."""
254
    
255
    @property
256
    def month(self) -> int:
257
        """Month for yearly recurrence."""
258

259
class RecurrenceRange:
260
    @property
261
    def start_date(self) -> date:
262
        """Recurrence start date."""
263
    
264
    @property
265
    def end_date(self) -> date:
266
        """Recurrence end date."""
267
    
268
    @property
269
    def number_of_occurrences(self) -> int:
270
        """Number of occurrences."""
271
    
272
    @property
273
    def type(self) -> str:
274
        """Range type (EndDate, NoEnd, Numbered)."""
275

276
class Event:
277
    @property
278
    def recurrence_pattern(self) -> RecurrencePattern:
279
        """Event recurrence pattern."""
280
    
281
    @property
282
    def recurrence_range(self) -> RecurrenceRange:
283
        """Event recurrence range."""
284
    
285
    def make_recurring(self, pattern_type: str, interval: int = 1, **kwargs) -> bool:
286
        """
287
        Make the event recurring.
288
        
289
        Parameters:
290
        - pattern_type: 'daily', 'weekly', 'monthly', or 'yearly'
291
        - interval: recurrence interval
292
        - kwargs: additional recurrence parameters
293
        
294
        Returns:
295
        - bool: True if successful
296
        """
297
```
298

299
### Free/Busy Information
300

301
Check availability and schedule meetings based on attendee availability.
302

303
```python { .api }
304
def get_free_busy(self, attendees: list[str], start_time: datetime, 
305
                  end_time: datetime, interval: int = 30) -> dict:
306
    """
307
    Get free/busy information for attendees.
308
    
309
    Parameters:
310
    - attendees: list of attendee email addresses
311
    - start_time: period start time
312
    - end_time: period end time
313
    - interval: time slot interval in minutes
314
    
315
    Returns:
316
    - dict: Free/busy information for each attendee
317
    """
318

319
def find_meeting_times(self, attendees: list[str], duration: int,
320
                      max_candidates: int = 20, **constraints) -> list[dict]:
321
    """
322
    Find available meeting times for attendees.
323
    
324
    Parameters:
325
    - attendees: list of attendee email addresses
326
    - duration: meeting duration in minutes
327
    - max_candidates: maximum number of suggestions
328
    - constraints: time constraints (earliest_time, latest_time, etc.)
329
    
330
    Returns:
331
    - list[dict]: Suggested meeting times with confidence scores
332
    """
333
```
334

335
### Room and Resource Booking
336

337
Find and book meeting rooms and other resources.
338

339
```python { .api }
340
def get_rooms(self, room_list: str = None) -> list[Room]:
341
    """
342
    Get available meeting rooms.
343
    
344
    Parameters:
345
    - room_list: specific room list to query
346
    
347
    Returns:
348
    - list[Room]: Available meeting rooms
349
    """
350

351
def get_room_lists(self) -> list[RoomList]:
352
    """
353
    Get available room lists.
354
    
355
    Returns:
356
    - list[RoomList]: Available room lists
357
    """
358

359
class Room:
360
    @property
361
    def address(self) -> str:
362
        """Room email address."""
363
    
364
    @property
365
    def name(self) -> str:
366
        """Room display name."""
367
    
368
    @property
369
    def capacity(self) -> int:
370
        """Room capacity."""
371
    
372
    @property
373
    def equipment(self) -> list[str]:
374
        """Available equipment in the room."""
375
```
376

377
## Usage Examples
378

379
### Basic Calendar Operations
380

381
```python
382
from O365 import Account
383
from datetime import datetime, timedelta
384

385
account = Account(credentials)
386
schedule = account.schedule()
387

388
# Get events for the next week
389
start_time = datetime.now()
390
end_time = start_time + timedelta(days=7)
391

392
events = schedule.get_events(
393
    start_time__gte=start_time,
394
    end_time__lte=end_time
395
)
396

397
for event in events:
398
    print(f"Subject: {event.subject}")
399
    print(f"Start: {event.start}")
400
    print(f"End: {event.end}")
401
    print(f"Location: {event.location}")
402
    print("---")
403
```
404

405
### Create and Schedule Meeting
406

407
```python
408
from datetime import datetime, timedelta
409

410
# Create a new meeting
411
meeting = schedule.new_event()
412
meeting.subject = "Project Review Meeting"
413
meeting.body = "Weekly project status review"
414
meeting.location = "Conference Room A"
415

416
# Set meeting time (tomorrow at 2 PM)
417
tomorrow = datetime.now() + timedelta(days=1)
418
meeting.start = tomorrow.replace(hour=14, minute=0, second=0, microsecond=0)
419
meeting.end = meeting.start + timedelta(hours=1)
420

421
# Add attendees
422
meeting.add_attendees([
423
    'team.member1@company.com',
424
    'team.member2@company.com',
425
    'manager@company.com'
426
])
427

428
# Save and send invitations
429
if meeting.save():
430
    print("Meeting created and invitations sent!")
431
```
432

433
### Working with Recurring Events
434

435
```python
436
# Create a recurring weekly meeting
437
weekly_standup = schedule.new_event()
438
weekly_standup.subject = "Weekly Standup"
439
weekly_standup.start = datetime(2023, 10, 2, 9, 0)  # Monday 9 AM
440
weekly_standup.end = weekly_standup.start + timedelta(minutes=30)
441

442
# Make it recurring (every Monday for 12 weeks)
443
weekly_standup.make_recurring(
444
    pattern_type='weekly',
445
    interval=1,
446
    days_of_week=['Monday'],
447
    end_date=weekly_standup.start.date() + timedelta(weeks=12)
448
)
449

450
weekly_standup.add_attendees(['team@company.com'])
451
weekly_standup.save()
452
```
453

454
### Find Meeting Times
455

456
```python
457
from datetime import datetime, timedelta
458

459
# Find available meeting times for next week
460
attendees = [
461
    'person1@company.com',
462
    'person2@company.com',
463
    'person3@company.com'
464
]
465

466
next_week = datetime.now() + timedelta(days=7)
467
suggestions = schedule.find_meeting_times(
468
    attendees=attendees,
469
    duration=60,  # 1 hour meeting
470
    earliest_time=next_week.replace(hour=9),
471
    latest_time=next_week.replace(hour=17),
472
    max_candidates=10
473
)
474

475
for suggestion in suggestions:
476
    print(f"Suggested time: {suggestion['start_time']}")
477
    print(f"Confidence: {suggestion['confidence']}")
478
    print("---")
479
```
480

481
### Room Booking
482

483
```python
484
# Find and book a meeting room
485
rooms = schedule.get_rooms()
486
available_rooms = []
487

488
for room in rooms:
489
    if room.capacity >= 10:  # Need room for 10 people
490
        available_rooms.append(room)
491

492
if available_rooms:
493
    # Create meeting with room
494
    meeting = schedule.new_event()
495
    meeting.subject = "Large Team Meeting"
496
    meeting.location = available_rooms[0].name
497
    
498
    # Add the room as a required attendee
499
    meeting.add_attendees([available_rooms[0].address])
500
    meeting.save()
501
```