Install & Compatibility
Where this runs
tested against v0.3.15 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 21.7s · import 0.000s · 546MB
557MB installed
● package 557MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Office
✓ from office import Office
✗ from office import Office
This quickstart demonstrates how to authenticate with Microsoft 365 using the `office365` wrapper and then access OneDrive and Outlook Inbox services. It highlights the use of `FileSystemTokenBackend` for persistent, unattended authentication after an initial interactive setup. Ensure your Azure AD application is correctly configured with the necessary API permissions and environment variables for Client ID and Secret are set.
import os
from office365.office import Office
from O365 import FileSystemTokenBackend, MSGraphProtocol
# --- Configuration ---
# 1. Register an application in Azure AD (portal.azure.com).
# 2. Grant 'Microsoft Graph' permissions (e.g., Mail.Read, Files.ReadWrite.All, Sites.ReadWrite.All).
# 3. Configure a 'Web' platform with a Redirect URI (e.g., http://localhost:8000).
# 4. Create a Client Secret.
CLIENT_ID = os.environ.get('OFFICE365_CLIENT_ID', '')
CLIENT_SECRET = os.environ.get('OFFICE365_CLIENT_SECRET', '')
TOKEN_FILE = os.path.expanduser('~/.office365_token.json') # Path to store auth token
if not CLIENT_ID or not CLIENT_SECRET:
print("WARNING: Please set OFFICE365_CLIENT_ID and OFFICE365_CLIENT_SECRET environment variables.")
print("Cannot run quickstart without credentials. Exiting.")
exit(1) # Exit if credentials are not provided
# --- Authentication ---
credentials = (CLIENT_ID, CLIENT_SECRET)
token_backend = FileSystemTokenBackend(token_path=TOKEN_FILE)
protocol = MSGraphProtocol() # Use Microsoft Graph protocol
# Instantiate the Office wrapper
ms_office = Office(credentials=credentials, token_backend=token_backend, protocol=protocol)
# Define the scopes needed for your application. Ensure these are granted in Azure AD.
scopes = ['basic', 'onedrive_all', 'mail_all', 'sharepoint_all']
if not ms_office.authenticate(scopes=scopes):
print("Authentication failed. This often requires an interactive browser step on the first run.")
print(f"Check for the token file at: {TOKEN_FILE}")
print("If it's the first run or token expired, you might need to manually open ")
print("the authentication URL printed by the underlying O365 library's auth flow.")
exit(1)
print("Successfully authenticated to Microsoft 365.")
# --- Using the Wrapper ---
# Example 1: Accessing My Drive (OneDrive)
try:
my_drive = ms_office.my_drive()
print(f"\n--- My OneDrive Drive ---")
print(f"Drive ID: {my_drive.id}")
root_folder = my_drive.get_root_folder()
print(f"Root folder name: {root_folder.name}")
print(f"Items in root folder (first 3):")
for item in root_folder.get_items(limit=3):
print(f" - {item.name} ({item.object_type})")
except Exception as e:
print(f"Error accessing My Drive: {e}")
# Example 2: Accessing Inbox
try:
inbox = ms_office.inbox()
print(f"\n--- Inbox ---")
messages = inbox.get_messages(limit=3)
print(f"Total messages in inbox: {messages.count()}")
for msg in messages:
print(f" - Subject: '{msg.subject}' From: '{msg.sender.address}'")
except Exception as e:
print(f"Error accessing Inbox: {e}")
Debug
Known issues
gotchaAuthentication with `office365` often requires direct imports and setup from the underlying `O365` library. This includes `FileSystemTokenBackend` for token persistence and `MSGraphProtocol` for specifying the API endpoint. Initial authentication typically involves an interactive browser step, which can be a hurdle for server-side or CI/CD environments if not pre-configured.fixBe prepared to import `FileSystemTokenBackend` and `MSGraphProtocol` from the `O365` library. For unattended authentication, perform the initial interactive login once to generate a token file, and then use `token_backend` to load it in subsequent runs. Ensure your Azure AD app has correct Redirect URIs and API permissions.
affects: All versions
gotchaUsers frequently confuse the `office365` wrapper library (this package) with its core dependency, the `O365` library (PyPI package `O365`). While `office365` provides convenience, direct `O365` imports are necessary for fundamental components like authentication backends and protocol settings. Incorrectly mixing imports or expecting `office365` to fully abstract away `O365` can lead to errors.fixClearly differentiate between `from office365.office import Office` for the wrapper's entry point and `from O365 import ...` for core `O365` components (e.g., `FileSystemTokenBackend`, `MSGraphProtocol`). Consult both libraries' documentation for specific import paths.
affects: All versions
breakingAs `office365` is a wrapper, major breaking changes in its core dependency, the `O365` library (e.g., `O365` v3.x vs v2.x), can indirectly impact `office365` functionality or require updates, even if `office365` itself doesn't have a major version bump. This can lead to unexpected behavior or API mismatches.fixAlways check the `install_requires` in `office365`'s `setup.py` or PyPI page to identify the compatible `O365` version range. When updating `O365`, ensure it falls within this range or wait for `office365` to release a compatible update. Test thoroughly after any `O365` dependency updates.
affects: All versions dependent on specific `O365` versions
Upgrade
Version history
0.3.15latest on PyPI · released Dec 15, 2020
Audit
Dependencies
O365requiredCore functionality for interacting with Office 365 APIs.
PillowrequiredImage processing utilities used by some features.