List

sppyte.lists

List: a thin wrapper around SharePoint list endpoints.

List

List(name: str, site: Site)

Thin wrapper for SharePoint list endpoints.

Obtain one from Site.list(name). The Site owns the HTTP session; a List holds no resources of its own.

Parameters:

Name	Type	Description	Default
name	str	The list title as shown in SharePoint (not the URL segment).	required
site	Site	The site the list belongs to.	required

path property

path: str

Site-relative REST path of this list, with the title escaped.

For example _api/web/lists/GetByTitle('Tasks'). Useful for Site.request and Batch sub-requests: f"{tasks.path}/items".

item_type property

item_type: str

The list's ListItemEntityTypeFullName, e.g. SP.Data.TasksListItem.

Fetched once and cached for the lifetime of this object.

get_item_type

get_item_type() -> str

Fetch ListItemEntityTypeFullName from SharePoint and refresh the cache.

get_contents

get_contents(params: Params = None) -> Page

Return one page of list items.

SharePoint returns at most 100 items unless $top is given. The result is a Page (a list) whose next_link is set when more items remain; use iter_items or get_all_items to follow it.

Parameters:

Name	Type	Description	Default
params	Params	OData options, e.g. {"$select": "Id,Title", "$top": 5}.	None

iter_pages

iter_pages(params: Params = None, *, max_pages: int | None = None) -> Iterator[Page]

Yield each page of items, following next_link until exhausted or max_pages.

Parameters:

Name	Type	Description	Default
params	Params	OData options for the first page.	None
max_pages	int | None	Stop after this many pages; None for no limit.	None

iter_items

iter_items(params: Params = None, *, max_pages: int | None = None) -> Iterator[dict[str, Any]]

Yield every item across all pages, one request per page.

Parameters:

Name	Type	Description	Default
params	Params	OData options for the first page.	None
max_pages	int | None	Stop after this many pages; None for no limit.	None

Example

for task in tasks.iter_items({"$select": "Id,Title", "$top": 500}): ...

get_all_items

get_all_items(params: Params = None, *, max_pages: int | None = None) -> list[dict[str, Any]]

Collect every item across all pages into one list.

Parameters:

Name	Type	Description	Default
params	Params	OData options for the first page.	None
max_pages	int | None	Stop after this many pages; None for no limit.	None

get_item

get_item(sp_id: int) -> dict[str, Any]

Fetch a single list item by its SharePoint Id.

query

query(view_xml: str, *, paging_info: str | None = None, params: Params = None, digest: str | None = None) -> Page

Run a CAML query (POST .../GetItems) and return the matching items.

Use this instead of $filter on lists above the 5,000-item view threshold: a <Where> on an indexed column is evaluated by SQL Server and is not subject to it. Page with <RowLimit> in the view and paging_info ("Paged=TRUE&p_ID=<last Id>"), or let iter_query do it.

Parameters:

Name	Type	Description	Default
view_xml	str	CAML <View> XML, e.g. <View><Query><Where><Eq><FieldRef Name='Status'/> <Value Type='Text'>Open</Value></Eq></Where></Query><RowLimit>500</RowLimit></View>.	required
paging_info	str | None	Position token for the next page; omit for the first.	None
params	Params	OData options such as $select / $expand ($filter and $top belong in the CAML).	None
digest	str | None	Form digest to send instead of the managed one (GetItems is a POST).	None

iter_query

iter_query(view_xml: str, *, params: Params = None, max_pages: int | None = None, digest: str | None = None) -> Iterator[dict[str, Any]]

Yield every item matching a CAML query, one GetItems request per page.

view_xml must contain a <RowLimit>; each page is requested with Paged=TRUE&p_ID=<Id of the last item>, which assumes the view is ordered by ID ascending (the default when no <OrderBy> is given). Include Id in $select if you restrict the columns.

Parameters:

Name	Type	Description	Default
view_xml	str	CAML <View> XML containing a <RowLimit>.	required
params	Params	OData options such as $select / $expand.	None
max_pages	int | None	Stop after this many pages; None for no limit.	None
digest	str | None	Form digest to send instead of the managed one.	None

Raises:

Type	Description
ValueError	if view_xml has no <RowLimit>.
ResponseFormatError	if a page's last item has no integer Id.

query_all

query_all(view_xml: str, *, params: Params = None, max_pages: int | None = None, digest: str | None = None) -> list[dict[str, Any]]

Collect every item matching a CAML query across pages (see iter_query).

Parameters:

Name	Type	Description	Default
view_xml	str	CAML <View> XML containing a <RowLimit>.	required
params	Params	OData options such as $select / $expand.	None
max_pages	int | None	Stop after this many pages; None for no limit.	None
digest	str | None	Form digest to send instead of the managed one.	None

add_item

add_item(item: Mapping[str, Any], *, digest: str | None = None) -> dict[str, Any]

Add a list item and return it as SharePoint created it (including Id).

__metadata.type is added automatically from item_type unless the mapping already has one. item is not modified.

Parameters:

Name	Type	Description	Default
item	Mapping[str, Any]	Field values for the new item.	required
digest	str | None	Form digest to send instead of the managed one.	None

update_item

update_item(sp_id: int, patch: Mapping[str, Any], *, digest: str | None = None) -> int

Merge-update a list item (OData MERGE; fields you omit are untouched).

__metadata.type is added automatically unless present. patch is not modified.

Parameters:

Name	Type	Description	Default
sp_id	int	SharePoint Id of the item.	required
patch	Mapping[str, Any]	Fields to change.	required
digest	str | None	Form digest to send instead of the managed one.	None

Returns:

Type	Description
int	sp_id, for convenience.

delete_item

delete_item(sp_id: int, *, digest: str | None = None) -> bool

Delete a list item by its SharePoint Id.

Parameters:

Name	Type	Description	Default
sp_id	int	SharePoint Id of the item.	required
digest	str | None	Form digest to send instead of the managed one.	None

Returns:

Type	Description
bool	True; failures raise.

add_attachment

add_attachment(sp_id: int, file_name: str, attachment: IO[bytes] | bytes, *, digest: str | None = None) -> dict[str, Any]

Add a file attachment to an existing list item.

Parameters:

Name	Type	Description	Default
sp_id	int	SharePoint Id of the item.	required
file_name	str	Attachment file name, including extension.	required
attachment	IO[bytes] | bytes	Bytes or a file-like object opened in binary mode.	required
digest	str | None	Form digest to send instead of the managed one.	None

Returns:

Type	Description
dict[str, Any]	The SP.Attachment object SharePoint created (FileName, ServerRelativeUrl).