Install & Compatibility
Where this runs
tested against v2.0.0 · 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
installs and imports cleanly · install 0.0s · import 0.468s · 22.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.0s · import 0.428s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
connect
✓ from sharepy import connect
✗ import sharepy; s = sharepy.connect(...)
SharePointSession
✓ from sharepy import SharePointSession
✗ import sharepy; s = sharepy.SharePointSession(...)
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}")
Debug
Known issues
breakingVersion 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.fixSaved 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`.
affects: >=2.0.0
breakingThe `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`).fixIf 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)`. affects: >=2.0.0
gotchaSharePy 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.fixConsider 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.
affects: All versions, particularly with modern M365 setups
gotchaSSL certificate verification errors are common. This can be due to outdated `certifi` package or issues with the SharePoint server's SSL certificate.fixEnsure 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.
affects: All versions
gotchaIncorrect 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.fixEnsure the SharePoint site URL provided to `sharepy.connect()` is correct and does not contain an extraneous trailing slash.
affects: All versions
Upgrade
Version history
2.0.0latest on PyPI · released Feb 5, 2022
Audit
Dependencies
requestsrequiredSharePy extends and relies on the Requests library for HTTP operations.
certifirequiredNeeded for robust SSL certificate verification to avoid common authentication errors.
pythonrequiredRequires Python 3.6 or higher, but less than Python 4.