### Install SharePlum from source

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/install.md

Manual installation method by cloning the repository and running the setup script.

```bash
$ git clone git://github.com/jasonrollins/shareplum
$ cd shareplum
$ python setup.py install
```

--------------------------------

### Install SharePlum via pip

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/install.md

Standard installation method using the Python package manager.

```bash
$ pip install shareplum
```

--------------------------------

### Connect to SharePoint and Get List Items

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/index.md

Use this snippet to authenticate with SharePoint using NTLM and retrieve all items from a specific list. Ensure you have the 'shareplum' and 'requests-ntlm' libraries installed.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth

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

list_data = sp_list.GetListItems()
```

--------------------------------

### Connect to SharePoint Site (On-Premises and Office 365)

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Demonstrates how to establish a connection to a SharePoint site using either NTLM authentication for on-premises servers or cookie-based authentication for Office 365. Includes examples of accessing site information.

```python
from shareplum import Site, Office365
from shareplum.site import Version
from requests_ntlm import HttpNtlmAuth

# On-Premises SharePoint with NTLM Authentication
auth = HttpNtlmAuth('DOMAIN\username', 'password')
site = Site(
    'https://mysharepoint.server.com/sites/MySite',
    auth=auth,
    verify_ssl=True,
    ssl_version='TLSv1',
    timeout=30
)

# Office 365 SharePoint Online
authcookie = Office365(
    'https://mycompany.sharepoint.com',
    username='user@mycompany.com',
    password='password'
).GetCookies()

site = Site(
    'https://mycompany.sharepoint.com/sites/MySite',
    version=Version.v365,
    authcookie=authcookie
)

# Access site information
print(site.site_info)  # Site metadata
print(site.users)      # {'py': {...}, 'sp': {...}} user mappings
```

--------------------------------

### Get File Properties from SharePoint

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Retrieves and prints the properties (metadata) of a specific file in a SharePoint folder.

```python
props = folder.get_file_properties('report.pdf')
print(props)
```

--------------------------------

### Get All Lists on a Site

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Retrieve information about all lists present on the SharePoint site using the GetListCollection method.

```python
lists = sharepoint_site.GetListCollection()
```

--------------------------------

### Folder Management Methods

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Utilize methods within the Folder object to get files, upload files, check files in/out, and delete files or folders.

```python
# Get a file
file = my_folder.get_file('my_document.pdf')

# Upload a file
with open('local_file.txt', 'rb') as f:
    my_folder.upload_file(content=f.read(), file_name='remote_file.txt')

# Check out a file
my_folder.check_out('my_document.pdf')

# Check in a file
my_folder.check_in('my_document.pdf', comment='Updated version')

# Delete a file
my_folder.delete_file('old_file.txt')

# Delete a folder
my_folder.delete_folder('path/to/delete')
```

--------------------------------

### SharePoint Query: Begins With Text

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Use the 'BeginsWith' operator to filter list items where a specific field starts with a given text string.

```python
query = {'Where': [('BeginsWith', 'Title', 'Project')]}
```

--------------------------------

### SharePoint Complex Query with And/Or

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Construct a complex query combining multiple conditions using 'And' and 'Or' logical operators, along with comparison operators like 'Geq' (greater than or equal to) and 'Eq' (equal to). This example filters by price, category, and combines conditions with OR.

```python
query = {
    'Where': [
        'And',
        ('Geq', 'Price', '50'),
        'Or',
        ('Eq', 'Category', 'Electronics'),
        ('Eq', 'Category', 'Computers')
    ],
    'OrderBy': [('Price', 'DESCENDING')],
    'GroupBy': ['Category']
}
items = sp_list.GetListItems(
    fields=['Title', 'Price', 'Category', 'Stock'],
    query=query,
    row_limit=50
)
```

--------------------------------

### Access SharePoint REST API with Version Specification

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Access the SharePoint REST API by specifying a version higher than 2013 when creating the Site object. This example uses Office 365 authentication.

```python
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)
```

--------------------------------

### Get Site Users

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Fetch information about all users associated with the current SharePoint site using the GetUsers method.

```python
users = sharepoint_site.GetUsers()
```

--------------------------------

### Get Specific View Information

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Retrieve details about a specific view within a list by providing the view's name to the GetView method.

```python
view_info = my_list.GetView(viewname='MyCustomView')
```

--------------------------------

### Get List Items with Filters

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Retrieve items from a list, optionally specifying a view name, desired fields, a query filter, and a row limit.

```python
# Get all items from the default view
items = my_list.GetListItems()

# Get specific fields from a view
items = my_list.GetListItems(viewname='All Items', fields=['Title', 'Created'])

# Get items with a filter and row limit
items = my_list.GetListItems(query='<Where><Eq><FieldRef Name="ID"/><Value Type="Counter">1</Value></Eq></Where>', row_limit=10)
```

--------------------------------

### Get Attachments for a List Item

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Retrieves all attachments for a specific list item by its ID. Requires authentication and site connection.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth

auth = HttpNtlmAuth('username', 'password')
site = Site('https://sharepoint.server.com/sites/MySite', auth=auth)
sp_list = site.List('Tasks')

# Get attachments for item with ID 42
attachments = sp_list.GetAttachmentCollection('42')
for url in attachments:
    print(f"Attachment URL: {url}")

# Output:
# Attachment URL: https://sharepoint.server.com/sites/MySite/Lists/Tasks/Attachments/42/document.pdf
# Attachment URL: https://sharepoint.server.com/sites/MySite/Lists/Tasks/Attachments/42/image.png
```

--------------------------------

### Access List Views

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Retrieves information about views defined on a SharePoint list, including field configurations and view settings. Supports getting all views or a specific view.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth

auth = HttpNtlmAuth('username', 'password')
site = Site('https://sharepoint.server.com/sites/MySite', auth=auth)
sp_list = site.List('Tasks')

# Get all views for the list
views = sp_list.GetViewCollection()
for view_name, view_info in views.items():
    print(f"View: {view_name}")
    print(f"  Default: {view_info.get('DefaultView', 'FALSE')}")
    print(f"  Row Limit: {view_info.get('RowLimit', 'N/A')}")

# Get specific view details
view = sp_list.GetView('Active Tasks')
print(f"View fields: {view['fields']}")
print(f"View info: {view['info']}")

# Use view in GetListItems
items = sp_list.GetListItems(view_name='Active Tasks')
```

--------------------------------

### Retrieve Site Users

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Gets information about users who have access to the SharePoint site. Users are returned in both Python-friendly and SharePoint formats. For SharePoint 365, the REST API is used.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth
from shareplum.site import Version

auth = HttpNtlmAuth('username', 'password')
site = Site('https://sharepoint.server.com/sites/MySite', auth=auth)

# Users are loaded automatically during Site initialization
users = site.users

# Python-friendly format: name -> SharePoint ID format
print(users['py'])
# {'John Smith': '15;#John Smith', 'Jane Doe': '23;#Jane Doe'}

# SharePoint format: SharePoint ID -> name
print(users['sp'])
# {'15;#John Smith': 'John Smith', '23;#Jane Doe': 'Jane Doe'}

# For SharePoint 365, use REST API
site365 = Site(
    'https://mycompany.sharepoint.com/sites/MySite',
    version=Version.v365,
    authcookie=authcookie
)

# Get site users via REST API
site_users = site365.GetUsers()
for user in site_users:
    print(f"User: {user['Title']}, Email: {user.get('Email', 'N/A')}")

# Access site groups (365 only)
groups = site365.groups
for group in groups:
    print(f"Group: {group['Title']}")
```

--------------------------------

### Get a Specific List Object

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Obtain a List object for a specific list on the site by providing its name. Optionally, exclude hidden fields that might share names with visible fields.

```python
my_list = sharepoint_site.List(listName='MyList')

# Exclude hidden fields
my_list_no_hidden = sharepoint_site.List(listName='MyList', exclude_hidden_fields=True)
```

--------------------------------

### Get Attachment Collection for a Row

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Retrieve a list of attachments associated with a specific list item, identified by its ID, using the GetAttachmentCollection method.

```python
attachments = my_list.GetAttachmentCollection(_id='123')
```

--------------------------------

### Create or Access a SharePoint Folder

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/files.md

Instantiate a folder object by specifying its path. The folder will be created if it does not already exist.

```python
folder = site.Folder('Shared Documents/This Folder')
```

--------------------------------

### Run Unit Tests

Source: https://github.com/jasonrollins/shareplum/blob/master/README.rst

Execute the library's unit tests using the unittest module.

```bash
python -m unittest disover  # all tests
python -m unittest tests.test_site  # all site tests
```

--------------------------------

### Instantiate Site Object

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Create a Site object to interact with your SharePoint site. Specify the URL and optionally the SharePoint version, authentication, and SSL settings.

```python
from shareplum import Site
from shareplum.site import Version

# Example for SharePoint 2007
sharepoint_site = Site('https://mytenant.sharepoint.com/sites/mysite', version=Version.v2007)

# Example for SharePoint 2013
sharepoint_site = Site('https://mytenant.sharepoint.com/sites/mysite', version=Version.v2013)

# Example for SharePoint Online
sharepoint_site = Site('https://mytenant.sharepoint.com/sites/mysite', version=Version.v365)

# Example with authentication
sharepoint_site = Site('https://mytenant.sharepoint.com/sites/mysite', auth=('user', 'password'))
```

--------------------------------

### Upload a Binary File to SharePoint

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/files.md

Uploads a binary file by reading its content in binary mode. Ensure the file is opened with 'rb' mode.

```python
with open(fileName, mode='rb') as file:
        fileContent = file.read()
folder.upload_file(fileContent, "filename.bin")
```

--------------------------------

### Download a File from SharePoint

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/files.md

Retrieves a file from the specified folder. The argument is the name of the file to download.

```python
folder.get_file('source.txt')
```

--------------------------------

### Download File from SharePoint Folder

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Downloads a file from a SharePoint folder and prints its content. The content is returned as bytes.

```python
file_content = folder.get_file('greeting.txt')
print(file_content)  # b'Hello, World!'
```

--------------------------------

### List Files in SharePoint Folder

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Retrieves and prints the names and sizes of all files within a SharePoint folder.

```python
files = folder.files
for f in files:
    print(f"Name: {f['Name']}, Size: {f['Length']} bytes")
```

--------------------------------

### Connect to SharePoint Site

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/files.md

Specify the SharePoint version when creating a Site instance to access the REST API for versions 2013 and higher.

```python
site = Site('https://abc.sharepoint.com/sites/MySharePointSite/', version=Version.v2016, authcookie=authcookie)
```

--------------------------------

### Upload Binary File to SharePoint Folder

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Uploads a binary file to a specified SharePoint folder. Ensure the file is opened in binary read mode ('rb').

```python
with open('report.pdf', 'rb') as f:
    content = f.read()
folder.upload_file(content, 'report.pdf')
```

--------------------------------

### Manage SharePoint Lists

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Create and delete lists using template IDs or names, and retrieve the site's list collection.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth

auth = HttpNtlmAuth('username', 'password')
site = Site('https://sharepoint.server.com/sites/MySite', auth=auth)

# Create a new list using template name
result = site.AddList(
    list_name='Project Tasks',
    description='Task list for project management',
    template_id='Tasks'
)

# Create list using template ID directly
result = site.AddList(
    list_name='My Contacts',
    description='Contact information',
    template_id=105
)

# Delete a list
site.DeleteList('Project Tasks')

# Get all lists in the site
lists = site.GetListCollection()
for lst in lists:
    print(f"List: {lst['Title']}, Items: {lst.get('ItemCount', 'N/A')}")
```

--------------------------------

### Upload a Text File to SharePoint

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/files.md

Uploads a text file to the specified folder. The first argument is the file content and the second is the desired filename.

```python
folder.upload_file('Hello', 'new.txt')
```

--------------------------------

### Add a New SharePoint List

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Create a new list on a SharePoint site using the AddList method, specifying the list name, description, and template ID.

```python
site.AddList('My New List', description='Great List!', templateID='Custom List')
```

--------------------------------

### Save Downloaded File to Disk

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Downloads a file from SharePoint and saves it to the local disk in binary write mode ('wb').

```python
with open('downloaded_report.pdf', 'wb') as f:
    f.write(folder.get_file('report.pdf'))
```

--------------------------------

### Retrieve SharePoint List Items with GetListItems()

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Demonstrates various ways to retrieve items from a SharePoint list using the GetListItems() method, including fetching all items, selecting specific fields, using predefined views, limiting the number of rows, and applying filters with a Where query. It also highlights automatic type conversions.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth

auth = HttpNtlmAuth('username', 'password')
site = Site('https://sharepoint.server.com/sites/MySite', auth=auth)
sp_list = site.List('Tasks')

# Get all items from default view
all_items = sp_list.GetListItems()

# Get specific fields only
items = sp_list.GetListItems(fields=['Title', 'Status', 'DueDate'])

# Get items from a specific view
items = sp_list.GetListItems(view_name='Active Tasks')

# Limit number of rows returned
items = sp_list.GetListItems(row_limit=100)

# Filter with a Where query
query = {'Where': [('Eq', 'Status', 'In Progress')]}
items = sp_list.GetListItems(fields=['Title', 'Status'], query=query)
```

--------------------------------

### Check In a File in SharePoint

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/files.md

Completes the check-in process for a file after it has been checked out. Includes an optional comment for the check-in.

```python
folder.check_in('new.txt', "My check-in comment")
```

--------------------------------

### Check Out a File in SharePoint

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/files.md

Initiates a check-out for a file, preventing others from modifying it until checked in. Provide the filename as an argument.

```python
folder.check_out('new.txt')
```

--------------------------------

### Access SharePoint Lists using Site.List()

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Shows how to obtain a List object for a specific SharePoint list using the Site.List() method. This object provides access to list metadata such as fields, views, and regional settings, and can be used for further list item operations.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth

auth = HttpNtlmAuth('username', 'password')
site = Site('https://sharepoint.server.com/sites/MySite', auth=auth)

# Get a list object
sp_list = site.List('Contacts')

# Access list metadata
print(sp_list.fields)            # List of field definitions
print(sp_list.views)             # Available views
print(sp_list.regional_settings) # Regional settings
print(sp_list.server_settings)   # Server settings

# Exclude hidden fields (useful when field names conflict)
sp_list = site.List('Contacts', exclude_hidden_fields=True)
```

--------------------------------

### Access List Schema and Views

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

The schema (columns) and views for a list are automatically fetched when the List object is initialized. Access them via self.schema and self.views respectively.

```python
list_schema = my_list.schema
list_views = my_list.views
```

--------------------------------

### Set SSL Version for Site Connection

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/advanced.md

Use the ssl_version parameter when initializing a Site object to specify the SSL/TLS protocol version. This is useful for compatibility with older OpenSSL versions (e.g., 1.0f) that may not support TLS1.2.

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

--------------------------------

### Folder Object Initialization (REST API)

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

The Folder object is used with the REST API for SharePoint versions 2013 and later. Initialize it with the folder name.

```python
from shareplum.folder import Folder

my_folder = Folder('MyFolderName')
```

--------------------------------

### Site Management Methods

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Methods for interacting with the main SharePoint Site object, including list management and user retrieval.

```APIDOC
## Site Methods

### AddList
- **Description**: Adds a list to your site with the provided name, description, and template.
- **Parameters**:
  - **listName** (string) - Required
  - **description** (string) - Required
  - **templateID** (string) - Required

### DeleteList
- **Description**: Delete a list on your site with the provided List Name.
- **Parameters**:
  - **listName** (string) - Required

### GetListCollection
- **Description**: Returns information about the lists for the Site.

### GetUsers
- **Description**: Returns information on the userbase of the current Site.
```

--------------------------------

### Office365 Class for SharePoint Online Authentication

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Illustrates how to use the Office365 class to authenticate with SharePoint Online, obtain security tokens, and generate authentication cookies required by the Site class. This is essential for connecting to Office 365 environments.

```python
from shareplum import Office365

# Create Office365 authentication object
auth = Office365(
    'https://mycompany.sharepoint.com',
    username='user@mycompany.com',
    password='your-password'
)

# Get security token (called internally by GetCookies)
token = auth.GetSecurityToken('user@mycompany.com', 'your-password')

# Get authentication cookies for Site class
authcookie = auth.GetCookies()

# Use with Site class
from shareplum import Site
from shareplum.site import Version

site = Site(
    'https://mycompany.sharepoint.com/sites/MySite',
    version=Version.v365,
    authcookie=authcookie
)
```

--------------------------------

### List Subfolders in SharePoint Folder

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Retrieves and prints the names of all subfolders within a SharePoint folder.

```python
subfolders = folder.folders
print(subfolders)  # ['Subfolder1', 'Subfolder2']
```

--------------------------------

### List.GetView() / List.GetViewCollection()

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Access and retrieve information about views defined on a SharePoint list.

```APIDOC
## List.GetView() / List.GetViewCollection()

### Description
These methods retrieve information about views defined on a SharePoint list, including field configurations and view settings.
```

--------------------------------

### Batch Update List Items

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Perform batch creation, updates, and deletions using UpdateListItems. Boolean fields require 'Yes' or 'No' strings.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth
from datetime import datetime

auth = HttpNtlmAuth('username', 'password')
site = Site('https://sharepoint.server.com/sites/MySite', auth=auth)
sp_list = site.List('Tasks')

# Create new items
new_items = [
    {'Title': 'New Task 1', 'Status': 'Not Started', 'Priority': 'High'},
    {'Title': 'New Task 2', 'Status': 'Not Started', 'Priority': 'Medium'}
]
result = sp_list.UpdateListItems(data=new_items, kind='New')
# Result: {'1,New': '0x00000000', '2,New': '0x00000000'} (0x00000000 = success)

# Update existing items (must include ID)
updates = [
    {'ID': '5', 'Title': 'Updated Title', 'Status': 'In Progress'},
    {'ID': '7', 'Priority': 'Low'}
]
result = sp_list.UpdateListItems(data=updates, kind='Update')

# Delete items by ID
delete_ids = [5, 7, 12]
result = sp_list.UpdateListItems(data=delete_ids, kind='Delete')

# Working with dates
from datetime import datetime
new_item = [{'Title': 'Dated Task', 'DueDate': datetime(2024, 12, 31, 17, 0, 0)}]
result = sp_list.UpdateListItems(data=new_item, kind='New')

# Working with boolean fields (use 'Yes' or 'No')
new_item = [{'Title': 'Boolean Task', 'IsComplete': 'Yes'}]
result = sp_list.UpdateListItems(data=new_item, kind='New')
```

--------------------------------

### Authenticate with NTLM and Access SharePoint List

Source: https://github.com/jasonrollins/shareplum/blob/master/README.rst

Use HttpNtlmAuth for on-premise SharePoint authentication and retrieve list items.

```python
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)
```

--------------------------------

### Manage Lists

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Methods for creating and deleting SharePoint lists using template IDs.

```APIDOC
## POST Site.AddList / DELETE Site.DeleteList

### Description
Creates or deletes a SharePoint list. Creating a list requires a template ID or name.

### Method
POST / DELETE

### Parameters
#### Request Body
- **list_name** (string) - Required - Name of the list.
- **description** (string) - Optional - Description of the list.
- **template_id** (string/int) - Required - The template ID or name (e.g., 107 for Tasks).
```

--------------------------------

### File and Folder Operations

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Methods for managing files and folders within a SharePoint document library.

```APIDOC
## File and Folder Operations

### Description
Perform CRUD operations on files and folders, including uploading, downloading, listing contents, and metadata retrieval.

### Methods
- `upload_file(content, filename)`: Uploads binary content to the folder.
- `get_file(filename)`: Downloads file content.
- `get_file_properties(filename)`: Retrieves file metadata.
- `check_out(filename)`: Checks out a file for editing.
- `check_in(filename, comment)`: Checks in a file with a comment.
- `delete_file(filename)`: Deletes a specific file.
- `delete_folder(relative_url)`: Deletes a folder.
```

--------------------------------

### Combine Conditions with AND/OR

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/queries.md

Logical operators for complex filtering conditions.

```default
query = {'Where': ['And', ('Eq', 'Title', 'Good Title'),
                          ('Eq', 'My Other Column', 'Nice Value')]}

query = {'Where': ['Or', ('Eq', 'Title', 'Good Title'),
                         ('Eq', 'My Other Column', 'Nice Value')]}
```

--------------------------------

### Download Data from a SharePoint List

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Retrieve data from a SharePoint list using GetListItems. Data can be retrieved with all fields, a specific view, or a specified set of fields.

```python
sp_data = new_list.GetListItems()
sp_data = new_list.GetListItems('All Items')
sp_data = new_list.GetListItems(fields=['ID', 'Title'])
```

--------------------------------

### Query SharePoint List Items

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Use GetListItems with various query dictionaries to filter, order, and group results.

```python
query = {
    'Where': ['And',
              ('Eq', 'Status', 'In Progress'),
              ('Gt', 'Priority', '2')]
}
items = sp_list.GetListItems(fields=['Title', 'Status', 'Priority'], query=query)
```

```python
query = {
    'Where': ['Or',
              ('Eq', 'Status', 'Completed'),
              ('Eq', 'Status', 'In Progress')]
}
items = sp_list.GetListItems(query=query)
```

```python
query = {'Where': [('IsNull', 'AssignedTo')]}
unassigned = sp_list.GetListItems(query=query)
```

```python
query = {'OrderBy': ['DueDate']}
items = sp_list.GetListItems(query=query)
```

```python
query = {'OrderBy': [('DueDate', 'DESCENDING')]}
items = sp_list.GetListItems(query=query)
```

```python
query = {'GroupBy': ['Category']}
items = sp_list.GetListItems(query=query)
```

```python
query = {
    'Where': [('Eq', 'Status', 'Active')],
    'OrderBy': [('Title', 'ASCENDING')],
    'GroupBy': ['Department']
}
items = sp_list.GetListItems(fields=['Title', 'Status', 'Department'], query=query)
```

--------------------------------

### Site.GetUsers()

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Retrieve information about users who have access to the SharePoint site.

```APIDOC
## Site.GetUsers()

### Description
Returns information about users who have access to the SharePoint site. Users are returned in two formats: 'py' (Python-friendly, name to ID mapping) and 'sp' (SharePoint format, ID to name mapping).
```

--------------------------------

### Folder and File Operations

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Methods for managing folders and files, available when using the REST API (Version 2013 or greater).

```APIDOC
## Folder Methods

### upload_file
- **Description**: Uploads a file to the folder.
- **Parameters**:
  - **content** (bytes) - Required
  - **file_name** (string) - Required

### check_out
- **Description**: Checks out a file.
- **Parameters**:
  - **file_name** (string) - Required

### check_in
- **Description**: Checks in a file.
- **Parameters**:
  - **file_name** (string) - Required
  - **comment** (string) - Required
```

--------------------------------

### Group Data with GroupBy

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/queries.md

Grouping list items by specified columns.

```default
query = {'GroupBy': ['Title']}
```

--------------------------------

### SharePlum Query Operators Reference

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Reference for SharePlum query operators used in the 'Where' clause of GetListItems for filtering list items. Includes operators like Eq, Neq, Gt, Geq, Lt, Leq, IsNull, and IsNotNull.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth

auth = HttpNtlmAuth('username', 'password')
site = Site('https://sharepoint.server.com/sites/MySite', auth=auth)
sp_list = site.List('Products')

# Eq - Equals
query = {'Where': [('Eq', 'Category', 'Electronics')]}

# Neq - Not Equal To
query = {'Where': [('Neq', 'Status', 'Discontinued')]}

# Gt - Greater Than
query = {'Where': [('Gt', 'Price', '100')]}

# Geq - Greater Than or Equal To
query = {'Where': [('Geq', 'Stock', '10')]}

# Lt - Less Than
query = {'Where': [('Lt', 'Price', '50')]}

# Leq - Less Than or Equal To
query = {'Where': [('Leq', 'Priority', '3')]}

# IsNull - Value Is Null (no third parameter needed)
query = {'Where': [('IsNull', 'AssignedTo')]}

# IsNotNull - Value Is Not Null
query = {'Where': [('IsNotNull', 'DueDate')]}
```

--------------------------------

### Sort Data with OrderBy

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/queries.md

Sorting list items by column names in ascending or descending order.

```default
query = {'OrderBy': ['Title']}
```

```default
query = {'OrderBy': [('Title', 'DESCENDING')]}
```

--------------------------------

### SOAP Helper Class

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

The soap helper class is available for building SOAP requests, though direct usage is generally not required.

```python
from shareplum import soap

# Example usage (typically internal)
# soap_request = soap.build_get_list_request(list_name='MyList')
```

--------------------------------

### Delete a File from SharePoint

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/files.md

Removes a file from the specified folder. The filename must be provided as an argument.

```python
folder.delete_file('new.txt')
```

--------------------------------

### UpdateListItems

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Performs batch operations on list items including creation, updates, and deletions.

```APIDOC
## POST List.UpdateListItems

### Description
Performs batch operations on list items. Supports creating new items, updating existing items by ID, and deleting items by ID.

### Method
POST

### Parameters
#### Request Body
- **data** (list) - Required - A list of dictionaries (for New/Update) or a list of IDs (for Delete).
- **kind** (string) - Required - The operation type: 'New', 'Update', or 'Delete'.

### Response
#### Success Response (200)
- **result** (dict) - A dictionary containing the status of each operation.
```

--------------------------------

### Check Out File for Editing in SharePoint

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Checks out a file from a SharePoint folder to allow for editing. This locks the file from other users.

```python
folder.check_out('report.docx')
```

--------------------------------

### Authenticate with Office365 and Access SharePoint List

Source: https://github.com/jasonrollins/shareplum/blob/master/README.rst

Use Office365 authentication cookies to connect to SharePoint Online and retrieve list items.

```python
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)
```

--------------------------------

### Upload Data to a SharePoint List

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Upload data to a SharePoint list using the UpdateListItems method with kind set to 'New'. SharePlum automatically handles column name conversions.

```python
new_list = site.List('My New List')
my_data = data=[{'Title': 'First Row!'},
                {'Title': 'Another One!'}]
new_list.UpdateListItems(data=my_data, kind='New')
```

--------------------------------

### Check In File with Comment in SharePoint

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Checks in a file to a SharePoint folder after editing, optionally including a comment.

```python
folder.check_in('report.docx', 'Updated quarterly figures')
```

--------------------------------

### Perform Folder Operations via REST API

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Use the Folder class for file operations in SharePoint 2013+. The folder is created automatically if it does not exist.

```python
from shareplum import Site, Office365
from shareplum.site import Version

# Authenticate to Office 365
authcookie = Office365(
    'https://mycompany.sharepoint.com',
    username='user@mycompany.com',
    password='password'
).GetCookies()

# Create site with REST API support (version 2013+)
site = Site(
    'https://mycompany.sharepoint.com/sites/MySite',
    version=Version.v2016,
    authcookie=authcookie
)

# Create/access a folder (creates if doesn't exist)
folder = site.Folder('Shared Documents/Project Files')

# Upload a text file
folder.upload_file('Hello, World!', 'greeting.txt')
```

--------------------------------

### Access Folder Attributes

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Folder objects provide attributes like contextinfo, items, and files to access information about the folder's contents and context.

```python
folder_context = my_folder.contextinfo
folder_items = my_folder.items
folder_files = my_folder.files
```

--------------------------------

### Delete File from SharePoint

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Deletes a specified file from a SharePoint folder.

```python
folder.delete_file('old_document.txt')
```

--------------------------------

### On-Premises SharePoint Authentication

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Use HttpNtlmAuth for on-premises SharePoint authentication. Pass the URL and credentials to the Site object.

```python
from shareplum import Site
from requests_ntlm import HttpNtlmAuth

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

--------------------------------

### List Operations

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Methods for interacting with SharePoint Lists, including retrieving items, views, and updating data.

```APIDOC
## List Methods

### GetListItems
- **Description**: Retrieves items from the list.
- **Parameters**:
  - **viewname** (string) - Optional
  - **fields** (list) - Optional
  - **query** (string) - Optional
  - **row_limit** (int) - Optional

### UpdateListItems
- **Description**: Add, edit, or delete data on the current List.
- **Parameters**:
  - **data** (dict/list) - Required - Dictionary for 'New'/'Update', list of IDs for 'Delete'.
  - **kind** (string) - Required - 'New', 'Update', or 'Delete'.
```

--------------------------------

### Query Operators Reference

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Supported query operators for filtering list items.

```APIDOC
## Query Operators Reference

### Description
SharePlum supports various query operators for filtering list items used in the 'Where' clause of queries passed to GetListItems.

### Supported Operators
- **Eq**: Equals
- **Neq**: Not Equal To
- **Gt**: Greater Than
- **Geq**: Greater Than or Equal To
- **Lt**: Less Than
- **Leq**: Less Than or Equal To
- **IsNull**: Value Is Null
- **IsNotNull**: Value Is Not Null
```

--------------------------------

### Office 365 SharePoint Authentication

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Authenticate with Office 365 SharePoint by obtaining a login token and using the resulting cookie. Ensure the root URL is provided to the Office365 class.

```python
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)
```

--------------------------------

### Folder Operations

Source: https://context7.com/jasonrollins/shareplum/llms.txt

File and folder operations using the SharePoint REST API.

```APIDOC
## POST Site.Folder

### Description
Provides access to a folder and allows file operations like uploading. Automatically creates the folder if it does not exist.

### Method
POST

### Parameters
#### Request Body
- **folder_path** (string) - Required - The path to the folder.

### Response
#### Success Response (200)
- **folder** (object) - A folder instance supporting file operations.
```

--------------------------------

### Perform REST API File Operations

Source: https://github.com/jasonrollins/shareplum/blob/master/README.rst

Manage files within SharePoint folders using the REST API, requiring SharePoint 2013 or newer.

```python
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')
```

--------------------------------

### Update Data in a SharePoint List

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Update existing data in a SharePoint list by providing a list of dictionaries containing the row ID and the fields to update. Use kind='Update'.

```python
update_data = [{'ID': '1', 'Title': 'My Changed Title'},
               {'ID': '2', 'Title': 'Another Change'}]
new_list.UpdateListItems(data=update_data, kind='Update')
```

--------------------------------

### SharePoint REST API Folder Operations

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Perform operations on SharePoint folders using the REST API, including uploading, retrieving, checking in/out, and deleting files.

```python
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')
```

--------------------------------

### GetListItems

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Retrieves items from a SharePoint list based on complex query conditions including filtering, ordering, and grouping.

```APIDOC
## GET List.GetListItems

### Description
Retrieves list items based on specified query parameters such as Where clauses, OrderBy, and GroupBy.

### Method
GET

### Parameters
#### Query Parameters
- **fields** (list) - Optional - List of field names to retrieve.
- **query** (dict) - Optional - Dictionary containing 'Where', 'OrderBy', or 'GroupBy' keys to filter and structure the results.

### Response
#### Success Response (200)
- **items** (list) - A list of dictionaries representing the retrieved SharePoint items.
```

--------------------------------

### Delete Folder from SharePoint

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Deletes a specified folder from SharePoint. Requires the relative URL of the folder for safety.

```python
folder.delete_folder('Shared Documents/Project Files')
```

--------------------------------

### SharePoint Version Enum

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/tutorial.md

Enum values for specifying SharePoint versions. Note that v2010 is an alias for v2007, and v2013, v2016, v2019 are aliases for v365.

```python
Version.v2007 (default)
Version.v2010
Version.v2013
Version.v2016
Version.v2019
Version.v365
```

--------------------------------

### Nested Logical Conditions

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/queries.md

Combining AND and OR operators within a single query.

```default
query = {'Where': ['Or',  ('Eq', 'My Other Column', 'Great Title'),
                   'And', ('Eq', 'My Other Column', 'Good Title'),
                          ('Eq', 'My Other Column', 'Nice Value')]}
```

--------------------------------

### Filter List Items with Where Clause

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/queries.md

Basic usage of the Where element to filter list items by column values.

```default
fields = ['Title', 'My Other Column']
query = {'Where': [('Eq', 'My Other Column', 'Nice Value')]}
sp_data = sp_list.GetListItems(fields=fields, query=query)
```

--------------------------------

### Delete a List from a Site

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Remove a list from your SharePoint site using the DeleteList method by specifying the list's name.

```python
sharepoint_site.DeleteList(listName='MyOldList')
```

--------------------------------

### Update List Items

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/objects.md

Add or modify items in a list using the UpdateListItems method. Provide data as a dictionary for single item updates or a list of IDs for deletion.

```python
# Add a new item
data = {'Movie': 'Elf', 'Length': '1h 37min'}
my_list.UpdateListItems(data=data, kind='New')

# Update an existing item (requires ID)
data = {'ID': '123', 'Movie': 'Elf', 'Length': '1h 37min'}
my_list.UpdateListItems(data=data, kind='Update')

# Delete items by ID
data = ['46', '201', '403', '456']
my_list.UpdateListItems(data=data, kind='Delete')
```

--------------------------------

### List.GetAttachmentCollection()

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Retrieves all attachments for a specific list item.

```APIDOC
## List.GetAttachmentCollection()

### Description
Retrieves all attachments for a specific list item by its ID. Returns a list of URLs pointing to the attachment files.

### Parameters
- **item_id** (string) - Required - The ID of the list item.
```

--------------------------------

### Filter Null Values

Source: https://github.com/jasonrollins/shareplum/blob/master/docs/queries.md

Usage of the IsNull operator without providing a value.

```default
query = {'Where': [('IsNull', 'My Other Column')]}
sp_data = sp_list.GetListItems(fields=fields, query=query)
```

--------------------------------

### SharePoint Query: Contains Text

Source: https://context7.com/jasonrollins/shareplum/llms.txt

Use the 'Contains' operator to filter list items where a specific field includes a given text string.

```python
query = {'Where': [('Contains', 'Description', 'urgent')]}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.