DOCSEARCHbyAlgolia
Submit Docs

SharePlum

repository·master·Indexed 41 days ago

https://github.com/jasonrollins/shareplum

A Python library that provides a Pythonic interface for interacting with SharePoint services. It supports list manipulation, REST API-based file and folder operations, and authentication for both on-premises SharePoint (via NTLM) and Office 365. Key features include the Site and Folder classes, support for SharePoint versions via the Version enum, and advanced list querying using Where, OrderBy, and GroupBy elements.

Tokens
5.7K
Snippets
26
Records
30
Agent score
51%

What's inside SharePlum

  1. Overview of SharePlum

    master
    SharePlum is a Python library designed to simplify interactions with SharePoint services. It abstracts the complexities of SharePoint APIs, allowing developers to write clean, Pythonic code for reading and writing data to SharePoint lists and performing file/folder operations via the REST API.

  2. Key Features of SharePlum

    master

    SharePlum provides the following capabilities:

    • List Operations: Reading and writing data to SharePoint lists using Python Dictionaries.
    • Name Mapping: Automatic conversion between SharePoint internal names and displayed names.
    • Filtering: Using Queries to filter data when retrieving List Items.
    • Data Handling: Automatic conversion of data types and support for the Users datatype.
    • Cloud Support: Support for Office365 SharePoint sites.
    • REST API Support: Folder and File operations (requires SharePoint 2013+).

  3. Filter list items using the Where element

    master

    The Where element allows you to filter list items based on specific conditions. The Where key in the query dictionary accepts a list of tuples representing conditions.

    Single Condition: ('Operator', 'ColumnName', 'Value')

    Null Checks: For IsNull or IsNotNull, do not provide a third value in the tuple. ('IsNull', 'ColumnName')

    Logical Operators: You can combine conditions using 'And' or 'Or'. The structure is ['LogicalOperator', condition1, condition2, ...]. You can also nest these operators.

    Available Operators:

    • Eq: Equals
    • Neq: Not Equal To
    • Geq: Greater Than or Equal To
    • Gt: Greater Than
    • Leq: Less Than or Equal To
    • Lt: Less Than
    • IsNull: Value Is Null
    • IsNotNull: Value is not Null
    • BeginsWith: Begins With Text
    • Contains: Contains Text
    # Single condition
query = {'Where': [('Eq', 'My Other Column', 'Nice Value')]}

# Null check
query = {'Where': [('IsNull', 'My Other Column')]}

# Multiple conditions with AND
query = {'Where': ['And', ('Eq', 'Title', 'Good Title'), ('Eq', 'My Other Column', 'Nice Value')]}

# Complex nested logic
query = {'Where': ['Or', ('Eq', 'My Other Column', 'Great Title'), 'And', ('Eq', 'My Other Column', 'Good Title'), ('Eq', 'My Other Column', 'Nice Value')]}

  4. Quickstart with SharePlum

    master

    SharePlum provides a Pythonic interface for interacting with SharePoint services. To get started, you can authenticate using requests_ntlm and initialize a Site object to access specific SharePoint lists.

    from shareplum import Site
from requests_ntlm import HttpNtlmAuth

# Set up NTLM authentication
cred = HttpNtlmAuth('Username', 'Password')

# Initialize the SharePoint Site
site = Site('https://mysharepoint.server.com/sites/MySite', auth=cred)

# Access a specific list
sp_list = site.List('list name')

# Retrieve list items
list_data = sp_list.GetListItems()

  5. Perform Folder and File operations via REST API

    master

    SharePlum supports Folder and File operations (upload, download, check-in/out, delete) using the SharePoint REST API. This requires SharePoint 2013 or newer. You must specify the appropriate Version when initializing the Site object.

    from shareplum import Site
from shareplum import Office365
from shareplum.site import Version

authcookie = Office365('https://abc.sharepoint.com', username='username@abc.com', password='password').GetCookies()
site = Site('https://abc.sharepoint.com/sites/MySharePointSite/', version=Version.v2016, authcookie=authcookie)

folder = site.Folder('Shared Documents/This Folder')
folder.upload_file('Hello', 'new.txt')
folder.get_file('new.txt')
folder.check_out('new.txt')
folder.check_in('new.txt', "My check-in comment")
folder.delete_file('new.txt')

  6. Run SharePlum unit tests

    master

    To run the local unit tests, follow these steps:

    1. Copy tests/test_settings.py to tests/local_test_seetings.py and update the contents to point to your SharePoint environment.
    2. Export your SharePoint password as an environment variable named TEST_PASSWORD.
    3. Run the tests using unittest from the root folder.

    Commands:

    python -m unittest discover  # Run all tests
python -m unittest tests.test_site  # Run all site tests

  7. Authenticate to SharePoint using NTLM

    master

    For on-premise SharePoint environments, you can authenticate using requests_ntlm.HttpNtlmAuth. You pass the authentication object to the Site constructor.

    from shareplum import Site
from requests_ntlm import HttpNtlmAuth

auth = HttpNtlmAuth('DIR\\username', 'password')
site = Site('https://abc.com/sites/MySharePointSite/', auth=auth)
sp_list = site.List('list name')
data = sp_list.GetListItems('All Items', row_limit=200)

  10. Authenticate to Office365 SharePoint

    master

    To connect to Office365 SharePoint sites, use the Office365 class to retrieve authentication cookies, then pass those cookies to the Site constructor using the authcookie parameter.

    from shareplum import Site
from shareplum import Office365

authcookie = Office365('https://abc.sharepoint.com', username='username@abc.com', password='password').GetCookies()
site = Site('https://abc.sharepoint.com/sites/MySharePointSite/', authcookie=authcookie)
sp_list = site.List('list name')
data = sp_list.GetListItems('All Items', row_limit=200)

  11. Change the SSL/TLS protocol version for Site

    master

    On some Linux distributions using OpenSSL 1.0f or older, the TLS1.2 protocol may not be available. You can specify a different SSL/TLS protocol version by passing the ssl_version parameter to the Site constructor.

    site = Site(SITE, auth=auth, verify_ssl=True, ssl_version='TLSv1')

  12. Authenticate to On-Premises SharePoint

    master

    To connect to an on-premises SharePoint server, use HttpNtlmAuth from the requests_ntlm package. Pass the credentials to the Site object via the auth parameter.

    from shareplum import Site
from requests_ntlm import HttpNtlmAuth

cred = HttpNtlmAuth('Username', 'Password')
site = Site('https://mysharepoint.server.com/sites/MySite', auth=cred)