{"id":4661,"library":"office365","title":"Office365 Python Wrapper","description":"The `office365` library is a Python wrapper that simplifies interactions with Microsoft 365 services by building upon the lower-level `O365` library. It provides a more Pythonic interface and additional utility methods for common tasks related to Outlook (mail, calendar), OneDrive, and SharePoint. The current version is 0.3.15, and the project frequently releases minor updates, indicating active development.","status":"active","version":"0.3.15","language":"en","source_language":"en","source_url":"https://github.com/matthewgdv/office","tags":["microsoft-365","office365","outlook","onedrive","sharepoint","microsoft-graph"],"install":[{"cmd":"pip install office365","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core functionality for interacting with Office 365 APIs.","package":"O365","optional":false},{"reason":"Image processing utilities used by some features.","package":"Pillow","optional":false}],"imports":[{"note":"The `Office` class is located within the `office` submodule.","wrong":"from office365 import Office","symbol":"Office","correct":"from office365.office import Office"}],"quickstart":{"code":"import os\nfrom office365.office import Office\nfrom O365 import FileSystemTokenBackend, MSGraphProtocol\n\n# --- Configuration ---\n# 1. Register an application in Azure AD (portal.azure.com).\n# 2. Grant 'Microsoft Graph' permissions (e.g., Mail.Read, Files.ReadWrite.All, Sites.ReadWrite.All).\n# 3. Configure a 'Web' platform with a Redirect URI (e.g., http://localhost:8000).\n# 4. Create a Client Secret.\n\nCLIENT_ID = os.environ.get('OFFICE365_CLIENT_ID', '')\nCLIENT_SECRET = os.environ.get('OFFICE365_CLIENT_SECRET', '')\nTOKEN_FILE = os.path.expanduser('~/.office365_token.json') # Path to store auth token\n\nif not CLIENT_ID or not CLIENT_SECRET:\n    print(\"WARNING: Please set OFFICE365_CLIENT_ID and OFFICE365_CLIENT_SECRET environment variables.\")\n    print(\"Cannot run quickstart without credentials. Exiting.\")\n    exit(1) # Exit if credentials are not provided\n\n# --- Authentication ---\ncredentials = (CLIENT_ID, CLIENT_SECRET)\ntoken_backend = FileSystemTokenBackend(token_path=TOKEN_FILE)\nprotocol = MSGraphProtocol() # Use Microsoft Graph protocol\n\n# Instantiate the Office wrapper\nms_office = Office(credentials=credentials, token_backend=token_backend, protocol=protocol)\n\n# Define the scopes needed for your application. Ensure these are granted in Azure AD.\nscopes = ['basic', 'onedrive_all', 'mail_all', 'sharepoint_all']\n\nif not ms_office.authenticate(scopes=scopes):\n    print(\"Authentication failed. This often requires an interactive browser step on the first run.\")\n    print(f\"Check for the token file at: {TOKEN_FILE}\")\n    print(\"If it's the first run or token expired, you might need to manually open \")\n    print(\"the authentication URL printed by the underlying O365 library's auth flow.\")\n    exit(1)\n\nprint(\"Successfully authenticated to Microsoft 365.\")\n\n# --- Using the Wrapper ---\n\n# Example 1: Accessing My Drive (OneDrive)\ntry:\n    my_drive = ms_office.my_drive()\n    print(f\"\\n--- My OneDrive Drive ---\")\n    print(f\"Drive ID: {my_drive.id}\")\n    root_folder = my_drive.get_root_folder()\n    print(f\"Root folder name: {root_folder.name}\")\n    print(f\"Items in root folder (first 3):\")\n    for item in root_folder.get_items(limit=3):\n        print(f\"  - {item.name} ({item.object_type})\")\nexcept Exception as e:\n    print(f\"Error accessing My Drive: {e}\")\n\n# Example 2: Accessing Inbox\ntry:\n    inbox = ms_office.inbox()\n    print(f\"\\n--- Inbox ---\")\n    messages = inbox.get_messages(limit=3)\n    print(f\"Total messages in inbox: {messages.count()}\")\n    for msg in messages:\n        print(f\"  - Subject: '{msg.subject}' From: '{msg.sender.address}'\")\nexcept Exception as e:\n    print(f\"Error accessing Inbox: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions dependent on specific `O365` versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}