Library

sppyte.libraries

Library: a thin wrapper around SharePoint document library endpoints.

DEFAULT_CHUNK_SIZE module-attribute

DEFAULT_CHUNK_SIZE = 64 * 1024

Chunk size in bytes for streamed downloads.

Document module-attribute

Document = bytes | IO[bytes] | str | os.PathLike[str]

Upload payload: raw bytes, a binary file object, or a path to open and stream.

Library

Library(name: str, site: Site)

Thin wrapper for SharePoint document library endpoints.

Obtain one from Site.library(name). The Site owns the HTTP session; a Library holds no resources of its own. Folder arguments are given as path segments beneath the library: docs.add_folder("Reports", "2025").

Parameters:

Name	Type	Description	Default
name	str	The library name as it appears in its URL, e.g. "Shared Documents".	required
site	Site	The site the library belongs to.	required

server_relative_url

server_relative_url(*parts: str) -> str

Return the server-relative URL of a path beneath this library (unescaped).

folder_path

folder_path(*subfolders: str) -> str

Return the site-relative REST path addressing a folder beneath this library.

The result is _api/web/GetFolderByServerRelativeUrl('...') with the URL escaped. Useful for Site.request and Batch sub-requests.

file_path

file_path(file_name: str, *subfolders: str) -> str

Return the site-relative REST path addressing a file beneath this library.

The result is _api/web/GetFileByServerRelativeUrl('...') with the URL escaped.

folder_exists

folder_exists(folder: str, *subfolders: str) -> bool

Return whether a folder path exists beneath this library.

A missing folder is False, not an error.

list_contents

list_contents(*subfolders: str, params: Params = None) -> Page

List the files directly inside a folder (subfolders are not included).

Each item is an SP.File object (Name, ServerRelativeUrl, Length, TimeLastModified, ...). The result is a Page whose next_link is set when more files remain.

Parameters:

Name	Type	Description	Default
*subfolders	str	Path segments beneath the library; none for the root.	()
params	Params	OData options such as $select, $top, $filter.	None

Example

docs.list_contents("Reports", "2025", params={"$select": "Name"})

list_folders

list_folders(*subfolders: str, params: Params = None) -> Page

List the folders directly inside a folder.

Each item is an SP.Folder object (Name, ServerRelativeUrl, ItemCount, ...).

Parameters:

Name	Type	Description	Default
*subfolders	str	Path segments beneath the library; none for the root.	()
params	Params	OData options such as $select, $top, $filter.	None

iter_pages

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

Yield each page of files in a folder, following next_link.

Parameters:

Name	Type	Description	Default
*subfolders	str	Path segments beneath the library; none for the root.	()
params	Params	OData options for the first page.	None
max_pages	int | None	Stop after this many pages; None for no limit.	None

iter_files

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

Yield every file in a folder across all pages, one request per page.

Parameters:

Name	Type	Description	Default
*subfolders	str	Path segments beneath the library; none for the root.	()
params	Params	OData options for the first page.	None
max_pages	int | None	Stop after this many pages; None for no limit.	None

get_all_files

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

Collect every file in a folder across all pages into one list.

Parameters:

Name	Type	Description	Default
*subfolders	str	Path segments beneath the library; none for the root.	()
params	Params	OData options for the first page.	None
max_pages	int | None	Stop after this many pages; None for no limit.	None

get_document

get_document(file_name: str, *subfolders: str) -> bytes

Download a file's contents into memory and return them.

iter_document

iter_document(file_name: str, *subfolders: str, chunk_size: int = DEFAULT_CHUNK_SIZE) -> Iterator[bytes]

Stream a file's contents as chunks of bytes without holding the whole file in memory.

HTTP errors are raised before the first chunk.

Parameters:

Name	Type	Description	Default
file_name	str	File name, including extension.	required
*subfolders	str	Path segments beneath the library; none for the root.	()
chunk_size	int	Size of each chunk in bytes.	DEFAULT_CHUNK_SIZE

Example

for chunk in docs.iter_document("big.iso", "ISOs"): out.write(chunk)

download

download(file_name: str, dest: str | PathLike[str] | IO[bytes], *subfolders: str, chunk_size: int = DEFAULT_CHUNK_SIZE) -> int

Stream a file to a path or a binary file object.

A path is created or overwritten; a file object is written at its current position and left open.

Parameters:

Name	Type	Description	Default
file_name	str	File name, including extension.	required
dest	str | PathLike[str] | IO[bytes]	Destination path or binary file object.	required
*subfolders	str	Path segments beneath the library; none for the root.	()
chunk_size	int	Size of each chunk in bytes.	DEFAULT_CHUNK_SIZE

Returns:

Type	Description
int	The number of bytes written.

Example

docs.download("report.pdf", "~/report.pdf", "Reports")

add_folder

add_folder(folder: str, *subfolders: str, digest: str | None = None) -> dict[str, Any]

Create a (nested) folder path within the library.

The parent folder must exist. Creating a folder that already exists is not an error.

Parameters:

Name	Type	Description	Default
folder	str	Name of the folder to create (or the first path segment).	required
*subfolders	str	Further path segments.	()
digest	str | None	Form digest to send instead of the managed one.	None

Returns:

Type	Description
dict[str, Any]	The SP.Folder object (Name, ServerRelativeUrl, UniqueId, Exists, ...).

add_document

add_document(file_name: str, document: Document, *subfolders: str, overwrite: bool = True, digest: str | None = None) -> dict[str, Any]

Upload a document into the given subfolder path.

A file object or path is streamed; a seekable one can be re-sent if the managed digest has to be refreshed, a non-seekable one cannot.

Parameters:

Name	Type	Description	Default
file_name	str	Name to store the file under, including extension.	required
document	Document	Bytes, a binary file object, or a path to a file to open and stream.	required
*subfolders	str	Path segments beneath the library; none for the root.	()
overwrite	bool	Replace an existing file with the same name. With False SharePoint answers 400 (SharePointError) if it exists.	True
digest	str | None	Form digest to send instead of the managed one.	None

Returns:

Type	Description
dict[str, Any]	The SP.File object SharePoint created (Name, ServerRelativeUrl,
dict[str, Any]	UniqueId, Length, ...).

delete_document

delete_document(file_name: str, *subfolders: str, digest: str | None = None) -> bool

Delete a document by name within an optional nested folder path.

Parameters:

Name	Type	Description	Default
file_name	str	File name, including extension.	required
*subfolders	str	Path segments beneath the library; none for the root.	()
digest	str | None	Form digest to send instead of the managed one.	None

Returns:

Type	Description
bool	True; failures raise.

delete_folder

delete_folder(folder: str, *subfolders: str, digest: str | None = None) -> bool

Delete a folder path.

Parameters:

Name	Type	Description	Default
folder	str	Name of the folder to delete (or the first path segment).	required
*subfolders	str	Further path segments.	()
digest	str | None	Form digest to send instead of the managed one.	None

Returns:

Type	Description
bool	True; failures raise.