SharePlum: Python SharePoint Library

Warnings

• breaking The Files API was significantly updated and stabilized in version 0.5.0. Existing code interacting with file uploads, downloads, and management methods might break or require adjustments.
  Fix: Review the official `shareplum` documentation or GitHub examples for the updated Files API methods. Test file-related operations thoroughly after upgrading.
• gotcha SharePoint authentication can be complex, especially with ADFS, multi-factor authentication (MFA), or specific corporate security policies. Basic username/password authentication might not always suffice.
  Fix: Consult your SharePoint administrator for the correct authentication method. shareplum primarily supports basic username/password; for more complex setups, you might need to handle authentication externally or use other tools like `MSAL.py` to obtain a bearer token, which `shareplum` can then use.
• gotcha Providing an incorrect SharePoint URL is a common mistake. The URL should typically include the full site collection path, e.g., `https://yourcompany.sharepoint.com/sites/yourteam`, rather than just the domain.
  Fix: Double-check the exact SharePoint site URL in your browser. Ensure it includes any `/sites/` or `/teams/` segments if applicable to your site collection.
• gotcha It is crucial to specify the correct SharePoint `Version` enum (e.g., `Version.v365` for SharePoint Online) when initializing the `Site` object, as API behavior can differ between SharePoint versions.
  Fix: Always pass the appropriate `version` parameter to the `Site` constructor. For SharePoint Online (Office 365), `Version.v365` is typically correct.

Install

• pip install shareplum Install stable version

Imports

• Site

  from shareplum import Site

• Version

  from shareplum.site import Version

Quickstart

Demonstrates how to connect to a SharePoint site using environment variables for credentials and retrieve a list of all available lists on the site. Highlights common issues and their troubleshooting.

import os
from shareplum import Site
from shareplum.site import Version

# Use environment variables for sensitive data
SHAREPOINT_URL = os.environ.get('SHAREPOINT_URL', 'https://yourcompany.sharepoint.com/sites/yourteam')
SHAREPOINT_USERNAME = os.environ.get('SHAREPOINT_USERNAME', 'your_username')
SHAREPOINT_PASSWORD = os.environ.get('SHAREPOINT_PASSWORD', 'your_password')

if not all([SHAREPOINT_URL, SHAREPOINT_USERNAME, SHAREPOINT_PASSWORD]):
    print("Error: Please set SHAREPOINT_URL, SHAREPOINT_USERNAME, and SHAREPOINT_PASSWORD environment variables.")
    print("Example: export SHAREPOINT_URL='https://yourcompany.sharepoint.com/sites/yourteam'")
else:
    try:
        # Initialize the Site object with the SharePoint URL, username, password, and version
        # Version.v365 is typically used for SharePoint Online (Office 365)
        # The constructor handles authentication if username/password are provided
        site = Site(SHAREPOINT_URL, username=SHAREPOINT_USERNAME, password=SHAREPOINT_PASSWORD, version=Version.v365)
        
        # Example: Get a list of all lists on the SharePoint site
        all_lists = site.GetListCollection()
        print(f"Successfully connected to SharePoint at {SHAREPOINT_URL}.")
        print(f"Found {len(all_lists)} lists:")
        for sp_list in all_lists:
            print(f"- {sp_list.get('Title')} (ID: {sp_list.get('ID')})")

    except Exception as e:
        print(f"An error occurred while connecting or fetching lists: {e}")
        print("Common issues:")
        print("1. Incorrect SHAREPOINT_URL (ensure it includes the full site collection path, e.g., /sites/yourteam).")
        print("2. Incorrect SHAREPOINT_USERNAME or SHAREPOINT_PASSWORD.")
        print("3. SharePoint site requires ADFS/MFA or other advanced authentication not supported by basic username/password.")
        print("4. Network issues or SharePoint API rate limits.")