Site

sppyte.site

Site: the authenticated session and managed request digest for one SharePoint site.

DIGEST_REFRESH_MARGIN module-attribute

DIGEST_REFRESH_MARGIN = 60.0

Refresh the digest this many seconds before SharePoint says it expires.

DEFAULT_TIMEOUT module-attribute

DEFAULT_TIMEOUT = 30.0

Default per-request timeout in seconds (connect and read).

Timeout module-attribute

Timeout = float | tuple[float, float] | None

A requests timeout: seconds, a (connect, read) pair, or None for no timeout.

Site

Site(host: str, site_relative_url: str, username: str | None = None, password: str | None = None, *, domain: str | None = None, protocol: Protocol = 'ntlm', auth: AuthBase | None = None, timeout: Timeout = DEFAULT_TIMEOUT, verify: bool | str | None = None, cert: str | tuple[str, str] | None = None, session: Session | None = None, retry: RetryOptions | bool | None = None)

A connection to one SharePoint site.

• Lazily establishes an authenticated requests.Session (NTLM or Kerberos) on first use.
• Obtains, caches and refreshes the form digest required for write operations.
• Hands out List and Library helpers bound to this site.

Use as a context manager to connect eagerly and ensure the session is closed:

with Site(host, "/sites/demo", username, password) as site:
    docs = site.library("Shared Documents")
    docs.add_folder("Reports", "2025")

Parameters:

Name	Type	Description	Default
host	str	Scheme and host only, e.g. "https://sharepoint.example.com".	required
site_relative_url	str	Server-relative URL of the site (web), e.g. "/sites/demo"; "" or "/" for the root site.	required
username	str | None	Account name without the domain. Required for NTLM; omit with protocol="negotiate" to use the current user's Kerberos ticket.	None
password	str | None	Password for username; omit for single sign-on.	None
domain	str | None	NTLM (NetBIOS) domain, e.g. "CONTOSO". Omit for a local account or when username already contains a domain.	None
protocol	Protocol	"ntlm" (default), "negotiate" (Kerberos when a ticket is available, NTLM otherwise) or "kerberos". See sppyte.auth.	'ntlm'
auth	AuthBase | None	Any requests authentication handler to use instead of sppyte's SpPremAuth; username, password, domain and protocol are then ignored.	None
timeout	Timeout	Per-request timeout in seconds, or a (connect, read) tuple. None disables the timeout (not recommended).	DEFAULT_TIMEOUT
verify	bool | str | None	TLS verification; False to disable, or a path to a CA bundle for an internal certificate authority. Forwarded to requests.Session.verify.	None
cert	str | tuple[str, str] | None	Client certificate (path or (cert, key) tuple). Forwarded to requests.Session.cert.	None
session	Session | None	Pre-configured requests.Session to use instead of creating one. sppyte attaches its SpPremAuth handler only if it has no auth, and does not close it.	None
retry	RetryOptions | bool | None	Retry transient failures on reads (GET requests and CAML queries). True for the defaults, a RetryOptions to tune, None (default) for off. Writes are never retried. See sppyte.retry.	None

Raises:

Type	Description
ConfigurationError	if host, site_relative_url or the credentials are malformed.

principal property

principal: str | None

The account name sent to the server: DOMAIN\user when a domain was given.

None when authenticating with the current user's Kerberos ticket or a custom auth handler.

form_digest property

form_digest: str | None

The currently cached form digest, or None if none has been fetched.

connect

connect() -> None

Create the authenticated session and fetch a form digest eagerly.

close

close() -> None

Close the HTTP session (if sppyte created it) and forget the cached digest.

digest

digest(*, refresh: bool = False) -> str

Return a valid form digest, fetching or refreshing it as needed.

The digest is cached until shortly before SharePoint says it expires. Concurrent callers share one fetch.

Parameters:

Name	Type	Description	Default
refresh	bool	Fetch a new digest even if the cached one is still valid.	False

invalidate_digest

invalidate_digest() -> None

Drop the cached digest so the next write fetches a fresh one.

get_form_digest

get_form_digest() -> str

Fetch a fresh form digest from /_api/contextinfo, bypassing the cache.

request

request(method: str, path: str, *, digest: str | bool | None = None, retry: bool | None = None, **kwargs: Any) -> Response

Perform an HTTP request against the site.

Keyword arguments mirror requests.Session.request; timeout defaults to the Site's timeout.

Parameters:

Name	Type	Description	Default
method	str	HTTP method.	required
path	str	Path relative to the site root (_api/web/...); leading and trailing slashes are tolerated.	required
digest	str | bool | None	True to send the managed form digest as X-RequestDigest (required for writes). If SharePoint rejects it with 403 the digest is refreshed and the request retried once, provided the body can be re-sent (bytes, str, JSON, or a seekable file). A str sends that digest as-is with no retry. None / False sends none.	None
retry	bool | None	Whether the Site's retry policy applies to this call. Defaults to True for GET without a digest (reads) and False otherwise. Has no effect unless the Site was created with retry.	None
**kwargs	Any	Passed to requests.Session.request (params, headers, json, data, stream, timeout, ...).	{}

Returns:

Type	Description
Response	The requests.Response.

Raises:

Type	Description
AuthError	on 401/403.
SharePointError	on any other 4xx/5xx.

get_page

get_page(next_link: str, **kwargs: Any) -> Page

Fetch the page a previous Page.next_link points at.

Parameters:

Name	Type	Description	Default
next_link	str	The link from a previous Page.	required
**kwargs	Any	Passed to requests.Session.request.	{}

Raises:

Type	Description
ConfigurationError	if the link is not on this site's host, so credentials are never sent elsewhere.

list

list(name: str) -> List

Return a List bound to this site; performs no network I/O.

Parameters:

Name	Type	Description	Default
name	str	The list title as shown in SharePoint.	required

library

library(name: str) -> Library

Return a Library bound to this site; performs no network I/O.

Parameters:

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

batch

batch() -> Batch

Return an empty Batch to send several requests in one round trip.

Requires SharePoint 2016 or later. See sppyte.batch.