or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdcalendar.mdcontacts.mddirectory.mdemail.mdexcel.mdindex.mdsharepoint.mdstorage.mdtasks.mdteams.md
tile.json

tessl/pypi-o365

O365 - Microsoft Graph and Office 365 API made easy

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/o365@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-o365@2.1.0

index.mddocs/

O365

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.

Package Information

  • Package Name: o365
  • Language: Python
  • Installation: pip install o365
  • Minimum Python Version: 3.9+

Core Imports

from O365 import Account

For specific services:

from O365 import Account, Connection, Protocol, MSGraphProtocol
from O365 import FileSystemTokenBackend, EnvTokenBackend

Basic Usage

from O365 import Account

# Set up credentials (client_id, client_secret)
credentials = ('your_client_id', 'your_client_secret')
account = Account(credentials)

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

# Access services
mailbox = account.mailbox()
inbox = mailbox.inbox_folder()
messages = inbox.get_messages(limit=10)

calendar = account.schedule()
events = calendar.get_events(limit=5)

# Work with contacts
address_book = account.address_book()
contacts = address_book.get_contacts()

# Access file storage
storage = account.storage()
drive = storage.get_default_drive()

Architecture

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

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

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

Capabilities

Authentication and Account Management

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

class Account:
    def __init__(self, credentials: tuple[str, str], *, 
                 username: str = None, protocol: Protocol = None,
                 main_resource: str = None, **kwargs): ...
    
    def authenticate(self, *, requested_scopes: list[str] = None, **kwargs) -> bool: ...
    def is_authenticated(self) -> bool: ...
    def get_current_user(self) -> User: ...
    def get_authorization_url(self, requested_scopes: list[str], redirect_uri: str = None, **kwargs) -> tuple[str, dict]: ...
    def request_token(self, authorization_url: str, *, flow: str = None, requested_scopes: list[str] = None, store_token: bool = True, **kwargs) -> bool: ...
    def new_message(self, resource: str = None) -> Message: ...

Authentication

Email and Messaging

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

def mailbox(self, resource: str = None) -> MailBox: ...

class MailBox:
    def inbox_folder(self) -> Folder: ...
    def sent_folder(self) -> Folder: ...
    def get_messages(self, limit: int = None, **filters) -> list[Message]: ...
    def new_message(self, to_recipients: list = None) -> Message: ...

Email and Messaging

Calendar and Scheduling

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

def schedule(self, resource: str = None) -> Schedule: ...

class Schedule:
    def get_default_calendar(self) -> Calendar: ...
    def get_events(self, limit: int = None, **filters) -> list[Event]: ...
    def new_event(self, subject: str = None) -> Event: ...

Calendar and Scheduling

File Storage and Drive Management

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

def storage(self, resource: str = None) -> Storage: ...

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

class Drive:
    def get_root_folder(self) -> Folder: ...
    def get_items(self) -> list[DriveItem]: ...

File Storage

Contacts and Address Book

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

def address_book(self, resource: str = None) -> AddressBook: ...

class AddressBook:
    def get_contacts(self, limit: int = None) -> list[Contact]: ...
    def new_contact(self) -> Contact: ...
    def get_contact_folders(self) -> list[ContactFolder]: ...

Contacts

SharePoint Integration

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

def sharepoint(self, resource: str = None) -> Sharepoint: ...

class Sharepoint:
    def get_site(self, site_id: str) -> Site: ...
    def search_site(self, search_text: str) -> list[Site]: ...

SharePoint

Microsoft Teams

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

def teams(self, resource: str = None) -> Teams: ...

class Teams:
    def get_my_teams(self) -> list[Team]: ...
    def get_team(self, team_id: str) -> Team: ...

Teams

Tasks and Planning

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

def tasks(self, resource: str = None) -> ToDo: ...
def planner(self, resource: str = None) -> Planner: ...

class ToDo:
    def get_lists(self) -> list[TaskList]: ...
    def new_list(self, list_name: str) -> TaskList: ...

Tasks and Planning

Directory and User Management

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

def directory(self, resource: str = None) -> Directory: ...

class Directory:
    def get_users(self) -> list[User]: ...
    def get_user(self, user_id: str) -> User: ...

Directory

Excel Integration

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

def excel(self, resource: str = None) -> Excel: ...

class Excel:
    def get_workbooks(self) -> list[Workbook]: ...
    def get_workbook(self, workbook_id: str) -> Workbook: ...

Excel

Group Management

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

def groups(self, resource: str = '') -> Groups: ...

class Groups:
    def get_groups(self) -> list[Group]: ...
    def get_group(self, group_id: str) -> Group: ...

Outlook Categories

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

def outlook_categories(self, resource: str = '') -> Categories: ...

class Categories:
    def get_categories(self) -> list[Category]: ...
    def create_category(self, display_name: str, color: str = None) -> Category: ...

Types

# Core authentication types
from typing import Tuple, Optional, Dict, List, Union

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

# Protocol and connection types
class Protocol:
    default_resource: str
    api_version: str
    
class MSGraphProtocol(Protocol):
    service_url: str
    default_resource: str
    api_version: str

class Connection:
    session: requests.Session
    token_backend: BaseTokenBackend
    
    def __init__(self, credentials: Credentials, *,
                 proxy_server: str = None,
                 proxy_port: int = 8080,
                 proxy_username: str = None,
                 proxy_password: str = None,
                 requests_delay: int = 200,
                 raise_http_errors: bool = True,
                 request_retries: int = 3,
                 token_backend: BaseTokenBackend = None,
                 tenant_id: str = "common",
                 auth_flow_type: str = "authorization",
                 timeout: int = None,
                 **kwargs): ...

# Token Storage Backends
class BaseTokenBackend:
    def save_token(self, token: dict): ...
    def load_token(self) -> dict: ...
    def delete_token(self): ...

class FileSystemTokenBackend(BaseTokenBackend): ...
class EnvTokenBackend(BaseTokenBackend): ...
class AWSS3Backend(BaseTokenBackend): ...
class FirestoreBackend(BaseTokenBackend): ...
class AWSSecretsBackend(BaseTokenBackend): ...
class BitwardenSecretsManagerBackend(BaseTokenBackend): ...
class DjangoTokenBackend(BaseTokenBackend): ...

# Query and Filtering
class Query:
    def __init__(self, attribute: str = None): ...
    def select(self, *attributes: str) -> Query: ...
    def filter(self, attribute: str, operator: str, value: any) -> Query: ...
    def order_by(self, attribute: str, ascending: bool = True) -> Query: ...
    def top(self, count: int) -> Query: ...
    def skip(self, count: int) -> Query: ...

# Common data types
class Recipient:
    address: str
    name: str = None

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