SharePy - Simple SharePoint Online authentication for Python

2.0.0 · maintenance · verified Mon Apr 13

SharePy is a Python library designed for simple authentication with SharePoint Online (Office 365) sites, enabling straightforward HTTP requests. It extends the popular Requests library, providing a familiar interface for interacting with SharePoint APIs. The current stable version is 2.0.0, released on February 4, 2022. The library has a slow release cadence, with major updates being infrequent, and there are growing concerns about its compatibility with modern Microsoft 365 authentication flows.

Warnings

breaking Version 2.0.0 introduced a major refactor, converting authentication to a standard Requests auth class. This changes the internal workings significantly from v1.x.x. Old session objects (sp-session.pkl) saved with v1.x.x are not compatible with v2.x.x and will be invalidated by major version number changes.
Fix: Saved sessions from v1.x.x must be re-created from scratch in v2.x.x. Existing code interacting with `sharepy.connect()` might need adjustment if it relied on deprecated arguments like `auth_tld`.
breaking The `auth_tld` argument was removed from `sharepy.connect()` in v2.0.0. It is replaced by a `login_url` property in the authentication classes (e.g., `sharepy.auth.SharePointOnline`).
Fix: If custom authentication URLs are needed, manually instantiate an auth object and set its `login_url` property before passing it to `sharepy.SharePointSession`. Example: `auth = sharepy.auth.SharePointOnline(username='user@example.com'); auth.login_url = 'https://login.microsoftonline.de/extSES.srf'; s = sharepy.SharePointSession('example.sharepoint.com', auth)`.
gotcha SharePy might not be compatible with newer Microsoft 365 authentication models, especially when Multi-Factor Authentication (MFA) is enabled, or with federated logins (e.g., GoDaddy). Users have reported 'RTFA and authentication errors' and freezing during authentication. The traditional username/password method often fails if 'Security Defaults' are active in Azure AD.
Fix: Consider disabling 'Security Defaults' in Azure AD (if possible and secure for your environment) or exploring alternative authentication methods like App Passwords, SharePoint API client secrets, or Azure App Registration with Microsoft Graph API if `sharepy` fails.
gotcha SSL certificate verification errors are common. This can be due to outdated `certifi` package or issues with the SharePoint server's SSL certificate.
Fix: Ensure the `certifi` package is up to date (`pip install --upgrade certifi`). Verify your internet connectivity and the validity of the SharePoint server's SSL certificate. Disabling SSL verification is not recommended for production environments.
gotcha Incorrect SharePoint site URL format can lead to authentication errors. Specifically, a trailing slash (e.g., `https://example.sharepoint.com/` vs `https://example.sharepoint.com`) might cause issues.
Fix: Ensure the SharePoint site URL provided to `sharepy.connect()` is correct and does not contain an extraneous trailing slash.

Install

pip install sharepy Latest stable version

Imports

connect
```
import sharepy
s = sharepy.connect(...)
```
The `sharepy.connect` function is the primary entry point for establishing a SharePoint session.
SharePointOnline
```
from sharepy.auth import SharePointOnline
```
For advanced usage or explicit authentication class instantiation, import directly from `sharepy.auth`.

Quickstart

This quickstart demonstrates how to connect to SharePoint Online using `sharepy.connect()` and make a simple API call to retrieve the site's lists. It's crucial to provide the SharePoint site URL, username, and password, preferably via environment variables for security. The library handles token management and digest token refreshing automatically.

import os
import sharepy

SHAREPOINT_SITE = os.environ.get('SHAREPOINT_SITE', 'example.sharepoint.com')
SHAREPOINT_USERNAME = os.environ.get('SHAREPOINT_USERNAME', 'user@example.com')
SHAREPOINT_PASSWORD = os.environ.get('SHAREPOINT_PASSWORD', 'your_password')

if not all([SHAREPOINT_SITE, SHAREPOINT_USERNAME, SHAREPOINT_PASSWORD]):
    print("Please set SHAREPOINT_SITE, SHAREPOINT_USERNAME, and SHAREPOINT_PASSWORD environment variables.")
    exit(1)

try:
    # Establish a connection to SharePoint Online
    # Note: For MFA-enabled accounts, username/password might not work reliably.
    # See warnings for more details.
    s = sharepy.connect(SHAREPOINT_SITE, username=SHAREPOINT_USERNAME, password=SHAREPOINT_PASSWORD)
    print(f"Successfully connected to {SHAREPOINT_SITE}")

    # Example: Make an API call to get lists from the site
    response = s.get(f'https://{SHAREPOINT_SITE}/_api/web/lists')
    response.raise_for_status() # Raise an exception for bad status codes

    print("SharePoint Lists:")
    for item in response.json()['d']['results']:
        print(f"- {item['Title']}")

    # Example: Download a file (replace with a real URL)
    # file_url = f'https://{SHAREPOINT_SITE}/Shared Documents/MyDocument.pdf'
    # s.getfile(file_url, 'downloaded_file.pdf')
    # print(f"Downloaded {file_url} to downloaded_file.pdf")

except sharepy.errors.AuthError as e:
    print(f"Authentication failed: {e}")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →