Microsoft Graph Filesystem (msgraphfs)

Warnings

• gotcha Authentication failures (401/403 Forbidden) are common due to incorrect Azure AD application setup. Ensure your application registration in the Azure Portal has the correct API permissions (e.g., `Sites.Read.All` for read-only, `Sites.ReadWrite.All` for read/write access), and that admin consent has been granted. The library uses the client credentials flow for server-to-server authentication.
  Fix: Verify Azure AD app registration permissions and consent in the Azure Portal. Double-check `client_id`, `tenant_id`, and `client_secret`. Refer to Microsoft Graph authentication documentation for detailed setup.
• gotcha The 0.4 release introduced fallback support for `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` environment variables alongside the existing `MSGRAPHFS_*` variables. While convenient, mixing or misconfiguring these can lead to unexpected authentication behavior if both sets are present.
  Fix: Standardize on either `MSGRAPHFS_*` or `AZURE_*` prefixes for your environment variables to avoid ambiguity. Prioritize `MSGRAPHFS_*` if there's a conflict, as they are specific to the library.
• gotcha Version 0.3 fixed a pagination bug where listing a folder with more than 200 items (e.g., using `fs.ls()`) would only return the first 200 items, silently truncating the results. Users on versions prior to 0.3 will experience this limitation.
  Fix: Upgrade to `msgraphfs` version 0.3 or later to ensure all items are returned when listing large folders.
• breaking Version 0.4 significantly enhanced path handling by introducing URL-based filesystem paths (`msgd://`, `sharepoint://`, `onedrive://` protocols) and enabling a single filesystem instance to access multiple SharePoint sites. While existing explicit `site_name` and `drive_name` initialization might still work, leveraging the new features (especially multi-site or new URL formats) will require updating how paths are constructed and the filesystem is initialized.
  Fix: Review the documentation for version 0.4 regarding URL-based paths and multi-site access. Adapt your code to use the new protocol prefixes (e.g., `msgd://site/drive/path`) for enhanced flexibility and multi-site support.

Install

• pip install msgraphfs Install latest version

Imports

• MSGraphFileSystem

  from msgraphfs import MSGraphFileSystem

Quickstart

This quickstart demonstrates how to initialize `MSGraphFileSystem` using Azure AD application credentials (client ID, tenant ID, client secret) provided via environment variables. It then performs basic filesystem operations like listing directories, creating a new directory, writing a file, and reading a file. An Azure AD application with appropriate permissions (e.g., `Sites.ReadWrite.All`) and correct site/drive names are crucial for successful execution.

import os
from msgraphfs import MSGraphFileSystem

# Set environment variables for authentication (replace with your actual credentials)
# Ensure your Azure AD app has 'Sites.Read.All' or 'Files.Read.All' permissions.
# For more robust production, consider using a credential management system like Azure Key Vault.
os.environ['MSGRAPHFS_CLIENT_ID'] = os.environ.get('MSGRAPHFS_CLIENT_ID', 'YOUR_CLIENT_ID')
os.environ['MSGRAPHFS_TENANT_ID'] = os.environ.get('MSGRAPHFS_TENANT_ID', 'YOUR_TENANT_ID')
os.environ['MSGRAPHFS_CLIENT_SECRET'] = os.environ.get('MSGRAPHFS_CLIENT_SECRET', 'YOUR_CLIENT_SECRET')

# Initialize the filesystem for a specific SharePoint site and drive
# Replace 'your_sharepoint_site' and 'your_drive_name' with actual values.
# Alternatively, use URL-based paths directly, e.g., 'msgd://site/drive/path/file'.
try:
    fs = MSGraphFileSystem(
        protocol="sharepoint",
        site_name="your_sharepoint_site",
        drive_name="Documents"
    )

    # List contents of the root directory
    print("Listing root directory:")
    files = fs.ls("/", detail=False)
    for f in files:
        print(f)

    # Example: Check if a directory exists and create it if not
    dir_path = "/path/to/my/new_folder"
    if not fs.isdir(dir_path):
        print(f"Directory '{dir_path}' does not exist, creating it...")
        fs.mkdir(dir_path)
        print(f"Directory '{dir_path}' created.")
    else:
        print(f"Directory '{dir_path}' already exists.")

    # Example: Write a simple file
    file_content = "Hello from msgraphfs!"
    file_path = f"{dir_path}/test_file.txt"
    print(f"Writing to {file_path}...")
    with fs.open(file_path, "w") as f:
        f.write(file_content)
    print(f"Content written to {file_path}.")

    # Example: Read the file
    print(f"Reading from {file_path}...")
    with fs.open(file_path, "r") as f:
        read_content = f.read()
    print(f"Read content: '{read_content}'")

except Exception as e:
    print(f"\nAn error occurred: {e}")
    print("Please ensure:")
    print("- Your MSGRAPHFS_CLIENT_ID, MSGRAPHFS_TENANT_ID, and MSGRAPHFS_CLIENT_SECRET environment variables are set.")
    print("- Your Azure AD application has the necessary API permissions (e.g., Sites.ReadWrite.All or Files.ReadWrite.All).")
    print("- 'your_sharepoint_site' and 'your_drive_name' are correct for your Microsoft 365 environment.")