Data Types

Shared models for the flex_mls package.

AuthTokens dataclass

Container for OAuth token responses.

Attributes:

Name	Type	Description
access_token	str	Access token used for authenticated API requests.
token_type	str	Token type returned by Spark. Usually Bearer.
expires_in	int | None	Token lifetime in seconds, when the server supplies one.
refresh_token	str | None	Refresh token used to renew an expired access token.
id_token	str | None	OpenID Connect ID token returned by Spark.
obtained_at	datetime	Timestamp at which the token set was obtained.

authorization_header()

Build the Authorization header value for this token set.

Returns:

Type	Description
str	The Authorization header value.

expires_at()

Return the absolute expiration time for the access token.

Returns:

Type	Description
datetime | None	The UTC expiration timestamp when expires_in is available,
datetime | None	otherwise None.

is_expired(buffer_seconds=0)

Report whether the access token should be treated as expired.

Parameters:

Name	Type	Description	Default
buffer_seconds	int	Optional time buffer applied before expiration to proactively refresh the token.	0

Returns:

Type	Description
bool	True when the token is expired or about to expire.

ClientConfig dataclass

Resolved shared configuration for a FlexMlsClient instance.

Attributes:

Name	Type	Description
base_url	str	Base URL for standard RESO API requests.
timeout_seconds	float	Default timeout applied to all requests.
max_retries	int	Number of retries for transient errors.
retry_backoff_seconds	float	Initial delay applied before retrying a request.
user_agent	str	User-Agent header applied to outgoing requests.
extra_headers	dict[str, str]	Additional headers added to every request.

ODataPage dataclass

Bases: Generic[_T]

One page of OData response data.

Attributes:

Name	Type	Description
records	list[_T]	Records from the value array.
next_link	str | None	Absolute URL for the next page, when present.
count	int | None	Total number of matching records, when requested.
raw	JsonMapping	The raw JSON payload returned by Spark.

from_response(payload) classmethod

Create an ODataPage from a RESO response payload.

Parameters:

Name	Type	Description	Default
payload	Mapping[str, Any]	Raw JSON mapping returned by Spark.	required

Returns:

Type	Description
'ODataPage[JsonRecord]'	A typed page object built from the payload's value array.

Raises:

Type	Description
TypeError	If the response payload is not a mapping.

ODataQueryOptions dataclass

Typed representation of common OData query parameters.

Attributes:

Name	Type	Description
select	tuple[str, ...]	Top-level fields to include in the response.
top	int | None	Maximum number of records to return.
skip	int | None	Number of records to skip.
count	bool | None	Whether the server should include @odata.count.
order_by	tuple[str, ...]	Sort expressions sent via $orderby.
filter_expression	str | None	Raw OData filter expression.
expand	tuple[str, ...]	Expansion expressions for related entities.
extra_params	dict[str, ScalarQueryValue]	Any additional raw query parameters to include.

to_params()

Convert the query options into Spark-compatible request parameters.

Returns:

Type	Description
dict[str, ScalarQueryValue]	A dictionary that can be passed directly to requests.

ReplicationWindow dataclass

Time window used for incremental RESO replication polling.

Attributes:

Name	Type	Description
start	datetime	Exclusive lower bound for ModificationTimestamp.
end	datetime	Exclusive upper bound for ModificationTimestamp.

to_filter(additional_filter=None)

Build a bounded ModificationTimestamp filter expression.

Parameters:

Name	Type	Description	Default
additional_filter	str | None	Optional extra filter expression to append.	None

Returns:

Type	Description
str	A Spark-compatible OData filter expression.

Shared enums for the flex_mls package.

OpenIdScope

Bases: str, Enum

Spark OpenID Connect scopes exposed by the discovery document.

PropertyExpansion

Bases: str, Enum

Supported property expansions documented by Spark.

ResponseFormat

Bases: str, Enum

Supported response formats for Spark RESO requests.