lists

Lists

A list is a container for rows of data, like a database table. A document library is a special kind of list that also stores files. Every list has a title and a unique ID (GUID).

---

Prerequisites

Requirement	Description	Reference
Site Owner or Member role	Required to create, update, and delete lists. Read access for browsing.	SharePoint admin roles

---

How lists work

graph TD
    Site["SharePoint Site"]
    Site --> List["List"]
    Site --> Lib["Document Library"]
    List --> Fields["Fields (Columns)"]
    List --> Items["List Items"]
    Lib --> Files["Files"]
    Lib --> Fields

Loading

---

Examples

Create and manage

Operation	File	Required role	API reference
Create a list	create.py	Member on site	Lists REST API
Update list properties	update_list.py	Member on site	Lists REST API
Delete a list	delete.py	Member on site	Lists REST API
Save as template	save_as_template.py	Member on site	Lists REST API
Clear all items	clear.py	Member on site	Lists REST API
Show or hide columns	show_hide_columns.py	Member on site	Lists REST API

Read and browse

Operation	File	Required role	API reference
Read list properties	read_properties.py	Read access	Lists REST API
Read list schema	read_schema.py	Read access	Lists REST API
Read all lists on site	read_all.py	Read access	Lists REST API
Read with paging	read_paged.py	Read access	Lists REST API
Get list storage size	read_lib_size.py	Read access	Lists REST API
Get changes (change log)	get_changes.py	Read access	Lists REST API
Get data as stream	get_data_as_stream.py	Read access	Lists REST API
Export list metadata (XML)	export_list.py	Read access	Lists REST API
Query large list (CAML)	query_large_list.py	Read access	Lists REST API

Import, filter, and query

Operation	File	Required role	API reference
Import from CSV	import_list.py	Member on list	Lists REST API
Import into library	import_lib.py	Member on library	Lists REST API
Filter with OData	read_items_with_filter.py	Read access	Lists REST API
Filter with CAML	read_items_with_caml_query.py	Read access	Lists REST API
Filter list collection	filter.py	Read access	Lists REST API
Parallel import (concurrent batches)	import_list_parallel.py	Member on list	Lists REST API

Advanced

Operation	File	Required role	API reference
Diagnose broken taxonomy field	assessment/broken_tax_field_value.py	Site Owner	Lists REST API

---

Quick start

from office365.sharepoint.client_context import ClientContext

ctx = ClientContext("https://contoso.sharepoint.com/sites/team").with_client_secret(
    "contoso.onmicrosoft.com", "client_id", "client_secret"
)

# Read all lists on the site
all_lists = ctx.web.lists.get().execute_query()
for l in all_lists:
    print(f"  {l.title}  (ID: {l.id})")

# Get a specific list by title
target = ctx.web.lists.get_by_title("Documents").get().execute_query()
print(f"Items: {target.item_count}, Fields: {len(target.fields)}")

---

API reference

• Working with lists, SharePoint REST API