0
# O365
1

2
A comprehensive Python library for interacting with Microsoft Graph and Office 365 APIs in a Pythonic way. It offers easy access to Email, Calendar, Contacts, OneDrive, SharePoint, Teams, Planner, and other Microsoft services through a well-designed abstraction layer with full OAuth support, automatic timezone conversion, resource switching capabilities, and pagination support.
3

4
## Package Information
5

6
- **Package Name**: o365
7
- **Language**: Python
8
- **Installation**: `pip install o365`
9
- **Minimum Python Version**: 3.9+
10

11
## Core Imports
12

13
```python
14
from O365 import Account
15
```
16

17
For specific services:
18

19
```python
20
from O365 import Account, Connection, Protocol, MSGraphProtocol
21
from O365 import FileSystemTokenBackend, EnvTokenBackend
22
```
23

24
## Basic Usage
25

26
```python
27
from O365 import Account
28

29
# Set up credentials (client_id, client_secret)
30
credentials = ('your_client_id', 'your_client_secret')
31
account = Account(credentials)
32

33
# Authenticate (first time only)
34
if account.authenticate(scopes=['Mail.Read', 'Calendar.Read']):
35
    print('Authenticated!')
36

37
# Access services
38
mailbox = account.mailbox()
39
inbox = mailbox.inbox_folder()
40
messages = inbox.get_messages(limit=10)
41

42
calendar = account.schedule()
43
events = calendar.get_events(limit=5)
44

45
# Work with contacts
46
address_book = account.address_book()
47
contacts = address_book.get_contacts()
48

49
# Access file storage
50
storage = account.storage()
51
drive = storage.get_default_drive()
52
```
53

54
## Architecture
55

56
The O365 library is built around a core set of architectural components:
57

58
- **Account**: Central authentication and service access point managing OAuth tokens and protocol selection
59
- **Connection**: HTTP communication layer handling requests, retries, and session management
60
- **Protocol**: API endpoint and resource management (MSGraph, Business Central)
61
- **Service Classes**: Specialized interfaces for each Microsoft 365 service (Mail, Calendar, Drive, etc.)
62
- **Token Backends**: Pluggable storage systems for OAuth tokens (FileSystem, AWS S3, Firestore, etc.)
63
- **Query System**: Advanced OData query builder for filtering, sorting, and pagination
64

65
This design enables maximum reusability across applications while providing fine-grained control over authentication, resource access, and data retrieval patterns.
66

67
## Capabilities
68

69
### Authentication and Account Management
70

71
Central authentication system supporting multiple OAuth flows (authorization code, client credentials, password), automatic token refresh, and flexible token storage backends.
72

73
```python { .api }
74
class Account:
75
    def __init__(self, credentials: tuple[str, str], *, 
76
                 username: str = None, protocol: Protocol = None,
77
                 main_resource: str = None, **kwargs): ...
78
    
79
    def authenticate(self, *, requested_scopes: list[str] = None, **kwargs) -> bool: ...
80
    def is_authenticated(self) -> bool: ...
81
    def get_current_user(self) -> User: ...
82
    def get_authorization_url(self, requested_scopes: list[str], redirect_uri: str = None, **kwargs) -> tuple[str, dict]: ...
83
    def request_token(self, authorization_url: str, *, flow: str = None, requested_scopes: list[str] = None, store_token: bool = True, **kwargs) -> bool: ...
84
    def new_message(self, resource: str = None) -> Message: ...
85
```
86

87
[Authentication](./authentication.md)
88

89
### Email and Messaging
90

91
Complete email management including inbox access, message composition, folder operations, attachment handling, and search capabilities with support for shared mailboxes.
92

93
```python { .api }
94
def mailbox(self, resource: str = None) -> MailBox: ...
95

96
class MailBox:
97
    def inbox_folder(self) -> Folder: ...
98
    def sent_folder(self) -> Folder: ...
99
    def get_messages(self, limit: int = None, **filters) -> list[Message]: ...
100
    def new_message(self, to_recipients: list = None) -> Message: ...
101
```
102

103
[Email and Messaging](./email.md)
104

105
### Calendar and Scheduling
106

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

109
```python { .api }
110
def schedule(self, resource: str = None) -> Schedule: ...
111

112
class Schedule:
113
    def get_default_calendar(self) -> Calendar: ...
114
    def get_events(self, limit: int = None, **filters) -> list[Event]: ...
115
    def new_event(self, subject: str = None) -> Event: ...
116
```
117

118
[Calendar and Scheduling](./calendar.md)
119

120
### File Storage and Drive Management
121

122
OneDrive and SharePoint file operations including upload, download, sharing, versioning, and folder management with support for large file transfers and permissions.
123

124
```python { .api }
125
def storage(self, resource: str = None) -> Storage: ...
126

127
class Storage:
128
    def get_default_drive(self) -> Drive: ...
129
    def get_drives(self) -> list[Drive]: ...
130

131
class Drive:
132
    def get_root_folder(self) -> Folder: ...
133
    def get_items(self) -> list[DriveItem]: ...
134
```
135

136
[File Storage](./storage.md)
137

138
### Contacts and Address Book
139

140
Contact management with support for personal contacts, shared address books, contact folders, and contact groups with full CRUD operations.
141

142
```python { .api }
143
def address_book(self, resource: str = None) -> AddressBook: ...
144

145
class AddressBook:
146
    def get_contacts(self, limit: int = None) -> list[Contact]: ...
147
    def new_contact(self) -> Contact: ...
148
    def get_contact_folders(self) -> list[ContactFolder]: ...
149
```
150

151
[Contacts](./contacts.md)
152

153
### SharePoint Integration
154

155
SharePoint site access, list management, item operations, and document libraries with support for custom columns, permissions, and workflows.
156

157
```python { .api }
158
def sharepoint(self, resource: str = None) -> Sharepoint: ...
159

160
class Sharepoint:
161
    def get_site(self, site_id: str) -> Site: ...
162
    def search_site(self, search_text: str) -> list[Site]: ...
163
```
164

165
[SharePoint](./sharepoint.md)
166

167
### Microsoft Teams
168

169
Teams integration including channel access, chat functionality, message posting, file sharing, and presence management.
170

171
```python { .api }
172
def teams(self, resource: str = None) -> Teams: ...
173

174
class Teams:
175
    def get_my_teams(self) -> list[Team]: ...
176
    def get_team(self, team_id: str) -> Team: ...
177
```
178

179
[Teams](./teams.md)
180

181
### Tasks and Planning
182

183
Microsoft To-Do and Planner integration for task management, project planning, bucket organization, and progress tracking.
184

185
```python { .api }
186
def tasks(self, resource: str = None) -> ToDo: ...
187
def planner(self, resource: str = None) -> Planner: ...
188

189
class ToDo:
190
    def get_lists(self) -> list[TaskList]: ...
191
    def new_list(self, list_name: str) -> TaskList: ...
192
```
193

194
[Tasks and Planning](./tasks.md)
195

196
### Directory and User Management
197

198
Active Directory integration for user management, group operations, and organizational information access.
199

200
```python { .api }
201
def directory(self, resource: str = None) -> Directory: ...
202

203
class Directory:
204
    def get_users(self) -> list[User]: ...
205
    def get_user(self, user_id: str) -> User: ...
206
```
207

208
[Directory](./directory.md)
209

210
### Excel Integration
211

212
Microsoft Excel workbook and worksheet operations including cell manipulation, formula evaluation, and data analysis with session management for complex operations.
213

214
```python { .api }
215
def excel(self, resource: str = None) -> Excel: ...
216

217
class Excel:
218
    def get_workbooks(self) -> list[Workbook]: ...
219
    def get_workbook(self, workbook_id: str) -> Workbook: ...
220
```
221

222
[Excel](./excel.md)
223

224
### Group Management
225

226
Microsoft 365 Groups integration for team collaboration, group membership management, and group-based resource access.
227

228
```python { .api }
229
def groups(self, resource: str = '') -> Groups: ...
230

231
class Groups:
232
    def get_groups(self) -> list[Group]: ...
233
    def get_group(self, group_id: str) -> Group: ...
234
```
235

236
### Outlook Categories
237

238
Outlook category management for organizing emails, calendar events, contacts, and tasks with custom color coding and naming.
239

240
```python { .api }
241
def outlook_categories(self, resource: str = '') -> Categories: ...
242

243
class Categories:
244
    def get_categories(self) -> list[Category]: ...
245
    def create_category(self, display_name: str, color: str = None) -> Category: ...
246
```
247

248
## Types
249

250
```python { .api }
251
# Core authentication types
252
from typing import Tuple, Optional, Dict, List, Union
253

254
Credentials = Tuple[str, str]  # (client_id, client_secret)
255

256
# Protocol and connection types
257
class Protocol:
258
    default_resource: str
259
    api_version: str
260
    
261
class MSGraphProtocol(Protocol):
262
    service_url: str
263
    default_resource: str
264
    api_version: str
265

266
class Connection:
267
    session: requests.Session
268
    token_backend: BaseTokenBackend
269
    
270
    def __init__(self, credentials: Credentials, *,
271
                 proxy_server: str = None,
272
                 proxy_port: int = 8080,
273
                 proxy_username: str = None,
274
                 proxy_password: str = None,
275
                 requests_delay: int = 200,
276
                 raise_http_errors: bool = True,
277
                 request_retries: int = 3,
278
                 token_backend: BaseTokenBackend = None,
279
                 tenant_id: str = "common",
280
                 auth_flow_type: str = "authorization",
281
                 timeout: int = None,
282
                 **kwargs): ...
283

284
# Token Storage Backends
285
class BaseTokenBackend:
286
    def save_token(self, token: dict): ...
287
    def load_token(self) -> dict: ...
288
    def delete_token(self): ...
289

290
class FileSystemTokenBackend(BaseTokenBackend): ...
291
class EnvTokenBackend(BaseTokenBackend): ...
292
class AWSS3Backend(BaseTokenBackend): ...
293
class FirestoreBackend(BaseTokenBackend): ...
294
class AWSSecretsBackend(BaseTokenBackend): ...
295
class BitwardenSecretsManagerBackend(BaseTokenBackend): ...
296
class DjangoTokenBackend(BaseTokenBackend): ...
297

298
# Query and Filtering
299
class Query:
300
    def __init__(self, attribute: str = None): ...
301
    def select(self, *attributes: str) -> Query: ...
302
    def filter(self, attribute: str, operator: str, value: any) -> Query: ...
303
    def order_by(self, attribute: str, ascending: bool = True) -> Query: ...
304
    def top(self, count: int) -> Query: ...
305
    def skip(self, count: int) -> Query: ...
306

307
# Common data types
308
class Recipient:
309
    address: str
310
    name: str = None
311

312
class Recipients:
313
    def add(self, recipients: Union[str, List[str], Recipient, List[Recipient]]): ...
314
```