Office365 Python Wrapper

Warnings

• gotcha Authentication 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.
  Fix: Be 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.
• gotcha Users 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.
  Fix: Clearly 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.
• breaking As `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.
  Fix: Always 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.

Install

• pip install office365 Install stable version

Imports

• Office

  from office365.office import Office

  The `Office` class is located within the `office` submodule.

Quickstart

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}")