OData and parsing¶
sppyte.odata ¶
Helpers for building SharePoint REST / OData URLs and reading collection responses.
JSON_NOMETADATA
module-attribute
¶
JSON_NOMETADATA = 'application/json;odata=nometadata'
Accept value that makes SharePoint return plain JSON (no d wrapper, no __metadata).
JSON_VERBOSE
module-attribute
¶
JSON_VERBOSE = 'application/json;odata=verbose'
Content-Type SharePoint requires for JSON request bodies.
Params
module-attribute
¶
Params: TypeAlias = Mapping[str, ParamValue] | Sequence[tuple[str, ParamValue]] | None
OData query options such as {"$select": "Id,Title", "$top": 5}.
Page ¶
Page(items: Iterable[dict[str, Any]] = (), next_link: str | None = None)
Bases: list[dict[str, Any]]
One page of results: a list of items plus the link to the next page.
next_link is the URL of the following page when SharePoint has more items,
and None otherwise. A Page behaves exactly like a list, so
for item in site.list("Tasks").get_contents() keeps working. Follow
next_link with Site.get_page, or use the iter_* / get_all_* helpers.
build_path ¶
build_path(*parts: str | None) -> str
Join path segments into a normalized server-relative path.
Empty and None segments are skipped; surrounding slashes are trimmed.
Example
build_path("sites/demo", "Shared Documents", "Reports")
returns "/sites/demo/Shared Documents/Reports".
odata_literal ¶
odata_literal(value: str) -> str
Escape a value for use inside an OData string literal ('...') in a URL path.
Apostrophes are doubled per OData and the result is percent-encoded so that
spaces, #, %, ? and & cannot break the URL. The doubled apostrophes
survive encoding because SharePoint expects them literally.
Example
odata_literal("O'Brien's #1 Report") returns "O''Brien''s%20%231%20Report".
odata_path ¶
odata_path(path: str) -> str
Escape a server-relative path for use inside an OData string literal.
Each /-separated segment is passed through odata_literal, so slashes are
preserved while everything else is escaped.
Example
odata_path("/sites/demo/Shared Documents/Q1 '25")
returns "/sites/demo/Shared%20Documents/Q1%20''25".
parse_page ¶
parse_page(payload: Any) -> Page
Build a Page from an OData collection response (odata=nometadata).
Reads the value array and odata.nextLink (or @odata.nextLink). A
missing value yields an empty page.
Raises:
| Type | Description |
|---|---|
ResponseFormatError
|
if the payload is not an object or |
follow_pages ¶
follow_pages(first: Page, fetch_next: Callable[[str], Page], max_pages: int | None = None) -> Iterator[Page]
Yield first, then each following page until next_link runs out or max_pages is reached.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
first
|
Page
|
The page to start from. |
required |
fetch_next
|
Callable[[str], Page]
|
Fetches the page a |
required |
max_pages
|
int | None
|
Stop after this many pages even if more remain; |
None
|
sppyte.utils ¶
Response-parsing helpers.
Each parse_* function pulls one value out of a SharePoint JSON payload and
raises ResponseFormatError if it is missing. URL helpers live in
sppyte.odata and are re-exported here for compatibility with 0.x.
ContextInfo ¶
Bases: TypedDict
Parsed /_api/contextinfo response.
FormDigestResponse ¶
Bases: TypedDict
Minimal shape of the /_api/contextinfo response (odata=nometadata).
ItemTypeResponse ¶
Bases: TypedDict
Response shape for list metadata carrying the item entity type.
parse_context_info ¶
parse_context_info(r: FormDigestResponse) -> ContextInfo
Extract the form digest and its lifetime.
Falls back to SharePoint's 30-minute default when the lifetime is missing or not a positive integer.
Raises:
| Type | Description |
|---|---|
ResponseFormatError
|
if |
parse_form_digest ¶
parse_form_digest(r: FormDigestResponse) -> str
parse_item_type ¶
parse_item_type(r: ItemTypeResponse) -> str
parse_created_item ¶
parse_created_item(r: Any) -> dict[str, Any]
Return the created list item from an add-item response, guaranteeing an integer Id.
Accepts both the nometadata shape (flat object) and the verbose shape
({"d": {...}}).
Raises:
| Type | Description |
|---|---|
ResponseFormatError
|
if the body is not an object or has no integer |
parse_object ¶
parse_object(r: Any) -> dict[str, Any]
Return a single SharePoint object from a response.
Accepts both the nometadata shape (flat object) and the verbose shape
({"d": {...}}).
Raises:
| Type | Description |
|---|---|
ResponseFormatError
|
if the body is not an object. |
parse_add_item ¶
parse_add_item(r: AddItemResponse) -> int
Extract ID from an add-item response.
Deprecated: use parse_created_item, which returns the whole item.
Raises:
| Type | Description |
|---|---|
ResponseFormatError
|
if |
parse_add_document ¶
parse_add_document(r: AddDocumentResponse) -> str
Extract UniqueId from an add-document response.
Deprecated: use parse_object, which returns the whole SP.File.
Raises:
| Type | Description |
|---|---|
ResponseFormatError
|
if |