sift_client.resources

Sift Resources - API interfaces for interacting with Sift services.

This module provides high-level API interfaces for interacting with Sift resources. Each resource API provides methods for common operations like listing, getting, creating, updating, and archiving resources.

Overview

Resource APIs are the primary way to interact with Sift services. They provide:

• Type-safe methods with full IDE autocomplete support
• Automatic type conversion between protobuf and Python types
• Flexible filtering using CEL (Common Expression Language) queries
• Both sync and async versions of most APIs
• Consistent interface across all resource types

Synchronous vs Asynchronous APIs

All resource APIs are available in both synchronous and asynchronous versions:

• Synchronous APIs (e.g., AssetsAPI) - Ideal for scripts, notebooks, and simple applications
• Asynchronous APIs (e.g., AssetsAPIAsync) - Ideal for high-performance applications with concurrent operations

Example Usage

from sift_client import SiftClient

client = SiftClient(api_key="...", grpc_url="...", rest_url="...")

# Synchronous API usage
asset = client.assets.get(asset_id="asset123")
runs = client.runs.list_(assets=[asset.id_], limit=10)

# Asynchronous API usage
async def get_data():
    asset = await client.async_.assets.get(asset_id="asset123")
    runs = await client.async_.runs.list_(assets=[asset.id_], limit=10)
    return asset, runs

Common Methods

Most resource APIs provide a consistent set of methods:

Query Methods

• get() - Retrieve a single resource by ID or unique identifier
• list_() - Retrieve multiple resources with optional filtering
• find() - Find a single resource matching criteria (raises error if multiple found)

Modification Methods

• create() - Create a new resource (where applicable)
• update() - Update an existing resource
• archive() - Archive a resource (soft delete)
• unarchive() - Restore an archived resource

Filtering and Querying

Resource APIs support powerful filtering capabilities:

Common Filters

• Name filters: name, name_contains, name_regex
• Time filters: created_after, created_before, modified_after, modified_before
• User filters: created_by, modified_by
• Metadata filters: tags, metadata
• Archive filters: include_archived

Resource-Specific Filters

Each resource API may have additional filters:

• Runs: start_time_after, duration_greater_than, is_stopped
• Channels: asset, run
• Rules: asset_ids, asset_tag_ids

Example: Advanced Filtering

from datetime import datetime, timedelta

# Complex run query
runs = client.runs.list_(
    assets=["asset123"],
    start_time_after=datetime.now() - timedelta(days=7),
    duration_greater_than=timedelta(hours=1),
    is_stopped=True,
    tags=["production"],
    order_by="start_time desc",
    limit=20
)

# Channel search with regex
channels = client.channels.list_(
    asset="asset123",
    name_regex="sensor_[0-9]+_temp",
    limit=100
)

Data Retrieval

The ChannelsAPI provides methods for retrieving time-series data:

from datetime import datetime, timedelta

# Get channel data as pandas DataFrames
channels = client.channels.list_(asset="asset123", limit=5)
data = client.channels.get_data(
    channels=channels,
    run="run123",
    start_time=datetime.now() - timedelta(hours=1),
    end_time=datetime.now(),
    limit=10000
)

# data is a dict mapping channel names to DataFrames
for channel_name, df in data.items():
    print(f"{channel_name}: {len(df)} data points")
    print(df.head())

Async Context Usage

When using async APIs, ensure proper async context:

import asyncio
from sift_client import SiftClient

async def main():
    client = SiftClient(api_key="...", grpc_url="...", rest_url="...")

    # Use async_ accessor for async APIs
    assets = await client.async_.assets.list_(limit=10)

    # Concurrent operations
    asset_task = client.async_.assets.get(asset_id="asset123")
    runs_task = client.async_.runs.list_(limit=10)

    asset, runs = await asyncio.gather(asset_task, runs_task)

    return asset, runs

# Run the async function
result = asyncio.run(main())

MODULE	DESCRIPTION
assets
calculated_channels
channels
data_imports
exports
file_attachments
ingestion
jobs
ping
principal_attributes
reports
resource_attributes
rules
runs
sync_stubs
tags
test_results

CLASS	DESCRIPTION
AssetsAPI	Sync counterpart to AssetsAPIAsync.
AssetsAPIAsync	High-level API for interacting with assets.
AutoRegisterStreamingClient	Streaming client that automatically registers flows on first send.
CalculatedChannelsAPI	Sync counterpart to CalculatedChannelsAPIAsync.
CalculatedChannelsAPIAsync	High-level API for interacting with calculated channels.
ChannelsAPI	Sync counterpart to ChannelsAPIAsync.
ChannelsAPIAsync	High-level API for interacting with channels.
DataExportAPI	Sync counterpart to DataExportAPIAsync.
DataExportAPIAsync	High-level API for exporting data from Sift.
DataImportAPI	Sync counterpart to DataImportAPIAsync.
DataImportAPIAsync	High-level API for importing data into Sift.
FileAttachmentsAPI	Sync counterpart to FileAttachmentsAPIAsync.
FileAttachmentsAPIAsync	High-level API for interacting with file attachments (remote files).
IngestionAPIAsync	High-level API for interacting with ingestion services.
IngestionConfigStreamingClient	A client for streaming ingestion with an ingestion config.
JobsAPI	Sync counterpart to JobsAPIAsync.
JobsAPIAsync	High-level API for interacting with jobs.
PingAPI	Sync counterpart to PingAPIAsync.
PingAPIAsync	High-level API for performing health checks.
PrincipalAttributesAPI	Sync counterpart to PrincipalAttributesAPIAsync.
PrincipalAttributesAPIAsync	High-level API for principal attributes (ABAC).
ReportsAPI	Sync counterpart to ReportsAPIAsync.
ReportsAPIAsync	High-level API for interacting with reports.
ResourceAttributesAPI	Sync counterpart to ResourceAttributesAPIAsync.
ResourceAttributesAPIAsync	High-level API for resource attributes (ABAC).
RulesAPI	Sync counterpart to RulesAPIAsync.
RulesAPIAsync	High-level API for interacting with rules.
RunsAPI	Sync counterpart to RunsAPIAsync.
RunsAPIAsync	High-level API for interacting with runs.
StreamingMode	Selects the SiftStream transport mode.
TagsAPI	Sync counterpart to TagsAPIAsync.
TagsAPIAsync	High-level API for interacting with tags.
TestResultsAPI	Sync counterpart to TestResultsAPIAsync.
TestResultsAPIAsync	High-level API for interacting with test reports, steps, and measurements.
TracingConfig	Configuration for tracing in SiftStream.

AssetsAPI

AssetsAPI(sift_client: SiftClient)

Sync counterpart to AssetsAPIAsync.

High-level API for interacting with assets.

This class provides a Pythonic, notebook-friendly interface for interacting with the AssetsAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Asset class from the low-level wrapper, which is a user-friendly representation of an asset using standard Python data structures and types.

Initialize the AssetsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive an asset.
find	Find a single asset matching the given query. Takes the same arguments as list_. If more than one asset is found,
get	Get an Asset.
list_	List assets with optional filtering.
unarchive	Unarchive an asset.
update	Update an Asset.

archive

archive(
    asset: str | Asset, *, archive_runs: bool = False
) -> Asset

Archive an asset.

PARAMETER	DESCRIPTION
asset	The Asset or asset ID to archive. TYPE: str | Asset
archive_runs	If True, archive all Runs associated with the Asset. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Asset	The archived Asset.

find

find(**kwargs) -> Asset | None

Find a single asset matching the given query. Takes the same arguments as list_. If more than one asset is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
Asset | None	The Asset found or None.

get

get(
    *, asset_id: str | None = None, name: str | None = None
) -> Asset

Get an Asset.

PARAMETER	DESCRIPTION
asset_id	The ID of the asset. TYPE: str | None DEFAULT: None
name	The name of the asset. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Asset	The Asset.

list_

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    asset_ids: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    tags: list[Any] | list[str] | list[Tag] | None = None,
    metadata: list[Any] | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Asset]

List assets with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the asset. TYPE: str | None DEFAULT: None
names	List of asset names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the asset. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter assets by name. TYPE: str | Pattern | None DEFAULT: None
asset_ids	Filter to assets with any of these Ids. TYPE: list[str] | None DEFAULT: None
created_after	Filter assets created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter assets created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter assets modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter assets modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter assets created by this User or user ID. TYPE: Any | str | None DEFAULT: None
modified_by	Filter assets last modified by this User or user ID. TYPE: Any | str | None DEFAULT: None
tags	Filter assets with any of these Tags or tag names. TYPE: list[Any] | list[str] | list[Tag] | None DEFAULT: None
metadata	Filter assets by metadata criteria. TYPE: list[Any] | None DEFAULT: None
description_contains	Partial description of the asset. TYPE: str | None DEFAULT: None
include_archived	If True, include archived assets in results. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter assets. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of assets to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Asset]	A list of Asset objects that match the filter criteria.

unarchive

unarchive(asset: str | Asset) -> Asset

Unarchive an asset.

PARAMETER	DESCRIPTION
asset	The Asset or asset ID to unarchive. TYPE: str | Asset

RETURNS	DESCRIPTION
Asset	The unarchived Asset.

update

update(
    asset: str | Asset, update: AssetUpdate | dict
) -> Asset

Update an Asset.

PARAMETER	DESCRIPTION
asset	The Asset or asset ID to update. TYPE: str | Asset
update	Updates to apply to the Asset. TYPE: AssetUpdate | dict

RETURNS	DESCRIPTION
Asset	The updated Asset.

AssetsAPIAsync

AssetsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with assets.

This class provides a Pythonic, notebook-friendly interface for interacting with the AssetsAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Asset class from the low-level wrapper, which is a user-friendly representation of an asset using standard Python data structures and types.

Initialize the AssetsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive an asset.
find	Find a single asset matching the given query. Takes the same arguments as list_. If more than one asset is found,
get	Get an Asset.
list_	List assets with optional filtering.
unarchive	Unarchive an asset.
update	Update an Asset.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive async

archive(
    asset: str | Asset, *, archive_runs: bool = False
) -> Asset

Archive an asset.

PARAMETER	DESCRIPTION
asset	The Asset or asset ID to archive. TYPE: str | Asset
archive_runs	If True, archive all Runs associated with the Asset. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Asset	The archived Asset.

find async

find(**kwargs) -> Asset | None

Find a single asset matching the given query. Takes the same arguments as list_. If more than one asset is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
Asset | None	The Asset found or None.

get async

get(
    *, asset_id: str | None = None, name: str | None = None
) -> Asset

Get an Asset.

PARAMETER	DESCRIPTION
asset_id	The ID of the asset. TYPE: str | None DEFAULT: None
name	The name of the asset. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Asset	The Asset.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    asset_ids: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    tags: list[Any] | list[str] | list[Tag] | None = None,
    metadata: list[Any] | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Asset]

List assets with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the asset. TYPE: str | None DEFAULT: None
names	List of asset names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the asset. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter assets by name. TYPE: str | Pattern | None DEFAULT: None
asset_ids	Filter to assets with any of these Ids. TYPE: list[str] | None DEFAULT: None
created_after	Filter assets created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter assets created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter assets modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter assets modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter assets created by this User or user ID. TYPE: Any | str | None DEFAULT: None
modified_by	Filter assets last modified by this User or user ID. TYPE: Any | str | None DEFAULT: None
tags	Filter assets with any of these Tags or tag names. TYPE: list[Any] | list[str] | list[Tag] | None DEFAULT: None
metadata	Filter assets by metadata criteria. TYPE: list[Any] | None DEFAULT: None
description_contains	Partial description of the asset. TYPE: str | None DEFAULT: None
include_archived	If True, include archived assets in results. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter assets. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of assets to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Asset]	A list of Asset objects that match the filter criteria.

unarchive async

unarchive(asset: str | Asset) -> Asset

Unarchive an asset.

PARAMETER	DESCRIPTION
asset	The Asset or asset ID to unarchive. TYPE: str | Asset

RETURNS	DESCRIPTION
Asset	The unarchived Asset.

update async

update(
    asset: str | Asset, update: AssetUpdate | dict
) -> Asset

Update an Asset.

PARAMETER	DESCRIPTION
asset	The Asset or asset ID to update. TYPE: str | Asset
update	Updates to apply to the Asset. TYPE: AssetUpdate | dict

RETURNS	DESCRIPTION
Asset	The updated Asset.

AutoRegisterStreamingClient

AutoRegisterStreamingClient(
    sift_client: SiftClient,
    stream: SiftStreamAutoRegisterPy,
)

Bases: ResourceBase

Streaming client that automatically registers flows on first send.

Unlike IngestionConfigStreamingClient, this client requires no pre-declared flow schemas. On the first send for a given flow name, a FlowConfig is derived from the channel values in the Flow and registered with Sift before sending. Subsequent sends for the same flow name are cache-hits with no additional overhead.

Pre-registering known flows via the ingestion_config argument is still supported and recommended when schemas are known upfront — those flows bypass the registration step entirely, so first-send latency is identical to IngestionConfigStreamingClient.

Use IngestionAPIAsync.create_auto_register_streaming_client to create an instance. Do not instantiate this class directly.

Initialize an AutoRegisterStreamingClient.

PARAMETER	DESCRIPTION
sift_client	Authenticated Sift client used for API calls. TYPE: SiftClient
stream	Underlying auto-register stream handle from the Rust bindings. TYPE: SiftStreamAutoRegisterPy

METHOD	DESCRIPTION
attach_run	Attach a run to the stream.
detach_run	Detach the run, if any, currently associated with the stream.
finish	Drain remaining data and gracefully shut down the stream.
get_flow_descriptor	Retrieve the flow descriptor for a given flow name from the local cache.
get_metrics_snapshot	Retrieve a snapshot of the current stream metrics.
get_run_id	Return the ID of the attached run, or None if no run is attached.
send	Send a flow, auto-registering it with Sift if not already in the local cache.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

attach_run async

attach_run(
    run: RunCreate | dict | str | Run | RunFormPy,
) -> None

Attach a run to the stream.

Data sent after this call will be associated with the specified run.

PARAMETER	DESCRIPTION
run	The run to attach. Can be a Run, RunCreate, dict, run ID string, or RunFormPy. TYPE: RunCreate | dict | str | Run | RunFormPy

detach_run

detach_run() -> None

Detach the run, if any, currently associated with the stream.

finish async

finish() -> None

Drain remaining data and gracefully shut down the stream.

Must be called when ingestion is complete to ensure all data reaches Sift.

get_flow_descriptor

get_flow_descriptor(flow_name: str) -> FlowDescriptorPy

Retrieve the flow descriptor for a given flow name from the local cache.

PARAMETER	DESCRIPTION
flow_name	The flow name to look up. TYPE: str

RAISES	DESCRIPTION
RuntimeError	If the flow has not been registered yet.

get_metrics_snapshot

get_metrics_snapshot() -> SiftStreamMetricsSnapshotPy

Retrieve a snapshot of the current stream metrics.

NOTE: The returned metrics snapshot is currently an unstable feature and may change at any time.

RETURNS	DESCRIPTION
SiftStreamMetricsSnapshotPy	A snapshot of the current stream metrics.

get_run_id

get_run_id() -> str | None

Return the ID of the attached run, or None if no run is attached.

send async

send(flow: Flow | FlowPy) -> None

Send a flow, auto-registering it with Sift if not already in the local cache.

On the first call for a given flow name, a FlowConfig is derived from the channel values and registered before sending. Subsequent calls for the same flow name skip registration entirely.

PARAMETER	DESCRIPTION
flow	The flow to send. TYPE: Flow | FlowPy

CalculatedChannelsAPI

CalculatedChannelsAPI(sift_client: SiftClient)

Sync counterpart to CalculatedChannelsAPIAsync.

High-level API for interacting with calculated channels.

This class provides a Pythonic, notebook-friendly interface for interacting with the CalculatedChannelsAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the CalculatedChannel class from the low-level wrapper, which is a user-friendly representation of a calculated channel using standard Python data structures and types.

Initialize the CalculatedChannelsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a calculated channel.
create	Create a calculated channel.
find	Find a single calculated channel matching the given query. Takes the same arguments as list but handles checking for multiple matches.
get	Get a Calculated Channel.
list_	List calculated channels with optional filtering. This will return the latest version. To find all versions, use list_versions.
list_versions	List versions of a calculated channel.
unarchive	Unarchive a calculated channel.
update	Update a Calculated Channel.

archive

archive(
    calculated_channel: str | CalculatedChannel,
) -> CalculatedChannel

Archive a calculated channel.

PARAMETER	DESCRIPTION
calculated_channel	The id or CalculatedChannel object of the calculated channel to archive. TYPE: str | CalculatedChannel

RETURNS	DESCRIPTION
CalculatedChannel	The archived CalculatedChannel.

create

create(
    create: CalculatedChannelCreate | dict,
) -> CalculatedChannel

Create a calculated channel.

PARAMETER	DESCRIPTION
create	A CalculatedChannelCreate object or dictionary with configuration for the new calculated channel. This should include properties like name, expression, channel_references, etc. TYPE: CalculatedChannelCreate | dict

RETURNS	DESCRIPTION
CalculatedChannel	The created CalculatedChannel.

find

find(**kwargs) -> CalculatedChannel | None

Find a single calculated channel matching the given query. Takes the same arguments as list but handles checking for multiple matches. Will raise an error if multiple calculated channels are found.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
CalculatedChannel | None	The CalculatedChannel found or None.

get

get(
    *,
    calculated_channel_id: str | None = None,
    client_key: str | None = None,
) -> CalculatedChannel

Get a Calculated Channel.

PARAMETER	DESCRIPTION
calculated_channel_id	The ID of the calculated channel. TYPE: str | None DEFAULT: None
client_key	The client key of the calculated channel. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
CalculatedChannel	The CalculatedChannel.

RAISES	DESCRIPTION
ValueError	If neither calculated_channel_id nor client_key is provided.

list_

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    calculated_channel_ids: list[str] | None = None,
    client_keys: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    tags: list[Any] | list[str] | list[Tag] | None = None,
    metadata: list[Any] | None = None,
    asset: Asset | str | None = None,
    run: Run | str | None = None,
    version: int | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[CalculatedChannel]

List calculated channels with optional filtering. This will return the latest version. To find all versions, use list_versions.

PARAMETER	DESCRIPTION
name	Exact name of the calculated channel. TYPE: str | None DEFAULT: None
names	List of calculated channel names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the calculated channel. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter calculated channels by name. TYPE: str | Pattern | None DEFAULT: None
calculated_channel_ids	Filter to calculated channels with any of these IDs. TYPE: list[str] | None DEFAULT: None
client_keys	Filter to calculated channels with any of these client keys. TYPE: list[str] | None DEFAULT: None
created_after	Created after this date. TYPE: datetime | None DEFAULT: None
created_before	Created before this date. TYPE: datetime | None DEFAULT: None
modified_after	Modified after this date. TYPE: datetime | None DEFAULT: None
modified_before	Modified before this date. TYPE: datetime | None DEFAULT: None
created_by	Calculated channels created by this user. TYPE: Any | str | None DEFAULT: None
modified_by	Calculated channels last modified by this user. TYPE: Any | str | None DEFAULT: None
tags	Filter calculated channels with any of these Tags or tag names. TYPE: list[Any] | list[str] | list[Tag] | None DEFAULT: None
metadata	Filter calculated channels by metadata criteria. TYPE: list[Any] | None DEFAULT: None
asset	Filter calculated channels associated with this Asset or asset ID. TYPE: Asset | str | None DEFAULT: None
run	Filter calculated channels associated with this Run or run ID. TYPE: Run | str | None DEFAULT: None
version	The version of the calculated channel. TYPE: int | None DEFAULT: None
description_contains	Partial description of the calculated channel. TYPE: str | None DEFAULT: None
include_archived	Include archived calculated channels. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter calculated channels. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved calculated channels. TYPE: str | None DEFAULT: None
limit	How many calculated channels to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[CalculatedChannel]	A list of CalculatedChannels that matches the filter.

list_versions

list_versions(
    *,
    calculated_channel: CalculatedChannel
    | str
    | None = None,
    client_key: str | None = None,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    tags: list[Any] | list[str] | list[Tag] | None = None,
    metadata: list[Any] | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[CalculatedChannel]

List versions of a calculated channel.

PARAMETER	DESCRIPTION
calculated_channel	The CalculatedChannel or ID of the calculated channel to get versions for. TYPE: CalculatedChannel | str | None DEFAULT: None
client_key	The client key of the calculated channel. TYPE: str | None DEFAULT: None
name	Exact name of the calculated channel. TYPE: str | None DEFAULT: None
names	List of calculated channel names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the calculated channel. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter calculated channels by name. TYPE: str | Pattern | None DEFAULT: None
created_after	Filter versions created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter versions created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter versions modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter versions modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter versions created by this user or user ID. TYPE: Any | str | None DEFAULT: None
modified_by	Filter versions modified by this user or user ID. TYPE: Any | str | None DEFAULT: None
tags	Filter versions with any of these Tags or tag names. TYPE: list[Any] | list[str] | list[Tag] | None DEFAULT: None
metadata	Filter versions by metadata criteria. TYPE: list[Any] | None DEFAULT: None
description_contains	Partial description of the calculated channel. TYPE: str | None DEFAULT: None
include_archived	Include archived versions. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter versions. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved versions. TYPE: str | None DEFAULT: None
limit	Maximum number of versions to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[CalculatedChannel]	A list of CalculatedChannel versions that match the filter criteria.

unarchive

unarchive(
    calculated_channel: str | CalculatedChannel,
) -> CalculatedChannel

Unarchive a calculated channel.

PARAMETER	DESCRIPTION
calculated_channel	The id or CalculatedChannel object of the calculated channel to unarchive. TYPE: str | CalculatedChannel

RETURNS	DESCRIPTION
CalculatedChannel	The unarchived CalculatedChannel.

update

update(
    calculated_channel: CalculatedChannel | str,
    update: CalculatedChannelUpdate | dict,
    *,
    user_notes: str | None = None,
) -> CalculatedChannel

Update a Calculated Channel.

PARAMETER	DESCRIPTION
calculated_channel	The CalculatedChannel or id of the CalculatedChannel to update. TYPE: CalculatedChannel | str
update	Updates to apply to the CalculatedChannel. TYPE: CalculatedChannelUpdate | dict
user_notes	User notes for the update. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
CalculatedChannel	The updated CalculatedChannel.

CalculatedChannelsAPIAsync

CalculatedChannelsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with calculated channels.

This class provides a Pythonic, notebook-friendly interface for interacting with the CalculatedChannelsAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the CalculatedChannel class from the low-level wrapper, which is a user-friendly representation of a calculated channel using standard Python data structures and types.

Initialize the CalculatedChannelsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a calculated channel.
create	Create a calculated channel.
find	Find a single calculated channel matching the given query. Takes the same arguments as list but handles checking for multiple matches.
get	Get a Calculated Channel.
list_	List calculated channels with optional filtering. This will return the latest version. To find all versions, use list_versions.
list_versions	List versions of a calculated channel.
unarchive	Unarchive a calculated channel.
update	Update a Calculated Channel.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive async

archive(
    calculated_channel: str | CalculatedChannel,
) -> CalculatedChannel

Archive a calculated channel.

PARAMETER	DESCRIPTION
calculated_channel	The id or CalculatedChannel object of the calculated channel to archive. TYPE: str | CalculatedChannel

RETURNS	DESCRIPTION
CalculatedChannel	The archived CalculatedChannel.

create async

create(
    create: CalculatedChannelCreate | dict,
) -> CalculatedChannel

Create a calculated channel.

PARAMETER	DESCRIPTION
create	A CalculatedChannelCreate object or dictionary with configuration for the new calculated channel. This should include properties like name, expression, channel_references, etc. TYPE: CalculatedChannelCreate | dict

RETURNS	DESCRIPTION
CalculatedChannel	The created CalculatedChannel.

find async

find(**kwargs) -> CalculatedChannel | None

Find a single calculated channel matching the given query. Takes the same arguments as list but handles checking for multiple matches. Will raise an error if multiple calculated channels are found.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
CalculatedChannel | None	The CalculatedChannel found or None.

get async

get(
    *,
    calculated_channel_id: str | None = None,
    client_key: str | None = None,
) -> CalculatedChannel

Get a Calculated Channel.

PARAMETER	DESCRIPTION
calculated_channel_id	The ID of the calculated channel. TYPE: str | None DEFAULT: None
client_key	The client key of the calculated channel. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
CalculatedChannel	The CalculatedChannel.

RAISES	DESCRIPTION
ValueError	If neither calculated_channel_id nor client_key is provided.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    calculated_channel_ids: list[str] | None = None,
    client_keys: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    tags: list[Any] | list[str] | list[Tag] | None = None,
    metadata: list[Any] | None = None,
    asset: Asset | str | None = None,
    run: Run | str | None = None,
    version: int | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[CalculatedChannel]

List calculated channels with optional filtering. This will return the latest version. To find all versions, use list_versions.

PARAMETER	DESCRIPTION
name	Exact name of the calculated channel. TYPE: str | None DEFAULT: None
names	List of calculated channel names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the calculated channel. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter calculated channels by name. TYPE: str | Pattern | None DEFAULT: None
calculated_channel_ids	Filter to calculated channels with any of these IDs. TYPE: list[str] | None DEFAULT: None
client_keys	Filter to calculated channels with any of these client keys. TYPE: list[str] | None DEFAULT: None
created_after	Created after this date. TYPE: datetime | None DEFAULT: None
created_before	Created before this date. TYPE: datetime | None DEFAULT: None
modified_after	Modified after this date. TYPE: datetime | None DEFAULT: None
modified_before	Modified before this date. TYPE: datetime | None DEFAULT: None
created_by	Calculated channels created by this user. TYPE: Any | str | None DEFAULT: None
modified_by	Calculated channels last modified by this user. TYPE: Any | str | None DEFAULT: None
tags	Filter calculated channels with any of these Tags or tag names. TYPE: list[Any] | list[str] | list[Tag] | None DEFAULT: None
metadata	Filter calculated channels by metadata criteria. TYPE: list[Any] | None DEFAULT: None
asset	Filter calculated channels associated with this Asset or asset ID. TYPE: Asset | str | None DEFAULT: None
run	Filter calculated channels associated with this Run or run ID. TYPE: Run | str | None DEFAULT: None
version	The version of the calculated channel. TYPE: int | None DEFAULT: None
description_contains	Partial description of the calculated channel. TYPE: str | None DEFAULT: None
include_archived	Include archived calculated channels. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter calculated channels. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved calculated channels. TYPE: str | None DEFAULT: None
limit	How many calculated channels to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[CalculatedChannel]	A list of CalculatedChannels that matches the filter.

list_versions async

list_versions(
    *,
    calculated_channel: CalculatedChannel
    | str
    | None = None,
    client_key: str | None = None,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    tags: list[Any] | list[str] | list[Tag] | None = None,
    metadata: list[Any] | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[CalculatedChannel]

List versions of a calculated channel.

PARAMETER	DESCRIPTION
calculated_channel	The CalculatedChannel or ID of the calculated channel to get versions for. TYPE: CalculatedChannel | str | None DEFAULT: None
client_key	The client key of the calculated channel. TYPE: str | None DEFAULT: None
name	Exact name of the calculated channel. TYPE: str | None DEFAULT: None
names	List of calculated channel names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the calculated channel. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter calculated channels by name. TYPE: str | Pattern | None DEFAULT: None
created_after	Filter versions created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter versions created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter versions modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter versions modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter versions created by this user or user ID. TYPE: Any | str | None DEFAULT: None
modified_by	Filter versions modified by this user or user ID. TYPE: Any | str | None DEFAULT: None
tags	Filter versions with any of these Tags or tag names. TYPE: list[Any] | list[str] | list[Tag] | None DEFAULT: None
metadata	Filter versions by metadata criteria. TYPE: list[Any] | None DEFAULT: None
description_contains	Partial description of the calculated channel. TYPE: str | None DEFAULT: None
include_archived	Include archived versions. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter versions. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved versions. TYPE: str | None DEFAULT: None
limit	Maximum number of versions to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[CalculatedChannel]	A list of CalculatedChannel versions that match the filter criteria.

unarchive async

unarchive(
    calculated_channel: str | CalculatedChannel,
) -> CalculatedChannel

Unarchive a calculated channel.

PARAMETER	DESCRIPTION
calculated_channel	The id or CalculatedChannel object of the calculated channel to unarchive. TYPE: str | CalculatedChannel

RETURNS	DESCRIPTION
CalculatedChannel	The unarchived CalculatedChannel.

update async

update(
    calculated_channel: CalculatedChannel | str,
    update: CalculatedChannelUpdate | dict,
    *,
    user_notes: str | None = None,
) -> CalculatedChannel

Update a Calculated Channel.

PARAMETER	DESCRIPTION
calculated_channel	The CalculatedChannel or id of the CalculatedChannel to update. TYPE: CalculatedChannel | str
update	Updates to apply to the CalculatedChannel. TYPE: CalculatedChannelUpdate | dict
user_notes	User notes for the update. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
CalculatedChannel	The updated CalculatedChannel.

ChannelsAPI

ChannelsAPI(sift_client: SiftClient)

Sync counterpart to ChannelsAPIAsync.

High-level API for interacting with channels.

This class provides a Pythonic, notebook-friendly interface for interacting with the ChannelsAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Channel class from the low-level wrapper, which is a user-friendly representation of a channel using standard Python data structures and types.

Initialize the ChannelsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Batch archive channels by setting active to false.
find	Find a single channel matching the given query. Takes the same arguments as list. If more than one channel is found,
get	Get a Channel.
get_data	Get data for one or more channels.
get_data_as_arrow	Get data for one or more channels as pyarrow tables.
list_	List channels with optional filtering.
unarchive	Batch unarchive channels by setting active to true.
update	Update a Channel.

archive

archive(channels: list[str | Channel]) -> None

Batch archive channels by setting active to false.

PARAMETER	DESCRIPTION
channels	List of channel IDs or Channel objects to archive. If a Channel has no id set, raises ValueError. TYPE: list[str | Channel]

find

find(**kwargs) -> Channel | None

Find a single channel matching the given query. Takes the same arguments as list. If more than one channel is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
Channel | None	The Channel found or None.

get

get(*, channel_id: str) -> Channel

Get a Channel.

PARAMETER	DESCRIPTION
channel_id	The ID of the channel. TYPE: str

RETURNS	DESCRIPTION
Channel	The Channel.

get_data

get_data(
    *,
    channels: list[Channel],
    run: Run | str | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
    limit: int | None = None,
    ignore_cache: bool = False,
) -> dict[str, DataFrame]

Get data for one or more channels.

PARAMETER	DESCRIPTION
channels	The channels to get data for. TYPE: list[Channel]
run	The Run or run_id to get data for. TYPE: Run | str | None DEFAULT: None
start_time	The start time to get data for. TYPE: datetime | None DEFAULT: None
end_time	The end time to get data for. TYPE: datetime | None DEFAULT: None
limit	The maximum number of data points to return. Will be in increments of page_size or default page size defined by the call if no page_size is provided. TYPE: int | None DEFAULT: None
ignore_cache	Whether to ignore cached data and fetch fresh data from the server. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
dict[str, DataFrame]	A dictionary mapping channel names to pandas DataFrames containing the channel data.

get_data_as_arrow

get_data_as_arrow(
    *,
    channels: list[Channel],
    run: Run | str | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
    limit: int | None = None,
    ignore_cache: bool = False,
) -> dict[str, Table]

Get data for one or more channels as pyarrow tables.

list_

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    channel_ids: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    asset: Asset | str | None = None,
    assets: list[str | Asset] | None = None,
    run: Run | str | None = None,
    description_contains: str | None = None,
    archived: bool | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Channel]

List channels with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the channel. TYPE: str | None DEFAULT: None
names	List of channel names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the channel. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter channels by name. TYPE: str | Pattern | None DEFAULT: None
channel_ids	Filter to channels with any of these IDs. TYPE: list[str] | None DEFAULT: None
created_after	Filter channels created after this datetime. Note: This is related to the channel creation time, not the timestamp of the underlying data. TYPE: datetime | None DEFAULT: None
created_before	Filter channels created before this datetime. Note: This is related to the channel creation time, not the timestamp of the underlying data. TYPE: datetime | None DEFAULT: None
modified_after	Filter channels modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter channels modified before this datetime. TYPE: datetime | None DEFAULT: None
asset	Filter channels associated with this Asset or asset ID. TYPE: Asset | str | None DEFAULT: None
assets	Filter channels associated with these Assets or asset IDs. TYPE: list[str | Asset] | None DEFAULT: None
run	Filter channels associated with this Run or run ID. TYPE: Run | str | None DEFAULT: None
description_contains	Partial description of the channel. TYPE: str | None DEFAULT: None
archived	If True, searches for archived channels. TYPE: bool | None DEFAULT: None
filter_query	Explicit CEL query to filter channels. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of channels to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Channel]	A list of Channels that matches the filter criteria.

unarchive

unarchive(channels: list[str | Channel]) -> None

Batch unarchive channels by setting active to true.

PARAMETER	DESCRIPTION
channels	List of channel IDs or Channel objects to unarchive. If a Channel has no id set, raises ValueError. TYPE: list[str | Channel]

update

update(
    channel: str | Channel, update: ChannelUpdate | dict
) -> Channel

Update a Channel.

PARAMETER	DESCRIPTION
channel	The Channel or channel ID to update. TYPE: str | Channel
update	Updates to apply to the Channel. See ChannelUpdate for the updatable fields (description, unit, metadata, and archived status). TYPE: ChannelUpdate | dict

RETURNS	DESCRIPTION
Channel	The updated Channel.

ChannelsAPIAsync

ChannelsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with channels.

This class provides a Pythonic, notebook-friendly interface for interacting with the ChannelsAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Channel class from the low-level wrapper, which is a user-friendly representation of a channel using standard Python data structures and types.

Initialize the ChannelsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Batch archive channels by setting active to false.
find	Find a single channel matching the given query. Takes the same arguments as list. If more than one channel is found,
get	Get a Channel.
get_data	Get data for one or more channels.
get_data_as_arrow	Get data for one or more channels as pyarrow tables.
list_	List channels with optional filtering.
unarchive	Batch unarchive channels by setting active to true.
update	Update a Channel.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive async

archive(channels: list[str | Channel]) -> None

Batch archive channels by setting active to false.

PARAMETER	DESCRIPTION
channels	List of channel IDs or Channel objects to archive. If a Channel has no id set, raises ValueError. TYPE: list[str | Channel]

find async

find(**kwargs) -> Channel | None

Find a single channel matching the given query. Takes the same arguments as list. If more than one channel is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
Channel | None	The Channel found or None.

get async

get(*, channel_id: str) -> Channel

Get a Channel.

PARAMETER	DESCRIPTION
channel_id	The ID of the channel. TYPE: str

RETURNS	DESCRIPTION
Channel	The Channel.

get_data async

get_data(
    *,
    channels: list[Channel],
    run: Run | str | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
    limit: int | None = None,
    ignore_cache: bool = False,
) -> dict[str, DataFrame]

Get data for one or more channels.

PARAMETER	DESCRIPTION
channels	The channels to get data for. TYPE: list[Channel]
run	The Run or run_id to get data for. TYPE: Run | str | None DEFAULT: None
start_time	The start time to get data for. TYPE: datetime | None DEFAULT: None
end_time	The end time to get data for. TYPE: datetime | None DEFAULT: None
limit	The maximum number of data points to return. Will be in increments of page_size or default page size defined by the call if no page_size is provided. TYPE: int | None DEFAULT: None
ignore_cache	Whether to ignore cached data and fetch fresh data from the server. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
dict[str, DataFrame]	A dictionary mapping channel names to pandas DataFrames containing the channel data.

get_data_as_arrow async

get_data_as_arrow(
    *,
    channels: list[Channel],
    run: Run | str | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
    limit: int | None = None,
    ignore_cache: bool = False,
) -> dict[str, Table]

Get data for one or more channels as pyarrow tables.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    channel_ids: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    asset: Asset | str | None = None,
    assets: list[str | Asset] | None = None,
    run: Run | str | None = None,
    description_contains: str | None = None,
    archived: bool | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Channel]

List channels with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the channel. TYPE: str | None DEFAULT: None
names	List of channel names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the channel. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter channels by name. TYPE: str | Pattern | None DEFAULT: None
channel_ids	Filter to channels with any of these IDs. TYPE: list[str] | None DEFAULT: None
created_after	Filter channels created after this datetime. Note: This is related to the channel creation time, not the timestamp of the underlying data. TYPE: datetime | None DEFAULT: None
created_before	Filter channels created before this datetime. Note: This is related to the channel creation time, not the timestamp of the underlying data. TYPE: datetime | None DEFAULT: None
modified_after	Filter channels modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter channels modified before this datetime. TYPE: datetime | None DEFAULT: None
asset	Filter channels associated with this Asset or asset ID. TYPE: Asset | str | None DEFAULT: None
assets	Filter channels associated with these Assets or asset IDs. TYPE: list[str | Asset] | None DEFAULT: None
run	Filter channels associated with this Run or run ID. TYPE: Run | str | None DEFAULT: None
description_contains	Partial description of the channel. TYPE: str | None DEFAULT: None
archived	If True, searches for archived channels. TYPE: bool | None DEFAULT: None
filter_query	Explicit CEL query to filter channels. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of channels to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Channel]	A list of Channels that matches the filter criteria.

unarchive async

unarchive(channels: list[str | Channel]) -> None

Batch unarchive channels by setting active to true.

PARAMETER	DESCRIPTION
channels	List of channel IDs or Channel objects to unarchive. If a Channel has no id set, raises ValueError. TYPE: list[str | Channel]

update async

update(
    channel: str | Channel, update: ChannelUpdate | dict
) -> Channel

Update a Channel.

PARAMETER	DESCRIPTION
channel	The Channel or channel ID to update. TYPE: str | Channel
update	Updates to apply to the Channel. See ChannelUpdate for the updatable fields (description, unit, metadata, and archived status). TYPE: ChannelUpdate | dict

RETURNS	DESCRIPTION
Channel	The updated Channel.

DataExportAPI

DataExportAPI(sift_client: SiftClient)

Sync counterpart to DataExportAPIAsync.

High-level API for exporting data from Sift.

Initialize the DataExportAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
export	Export data from Sift.

export

export(
    *,
    output_format: ExportOutputFormat,
    runs: list[str | Run] | None = None,
    assets: list[str | Asset] | None = None,
    start_time: datetime | None = None,
    stop_time: datetime | None = None,
    channels: list[str | Channel] | None = None,
    calculated_channels: list[
        CalculatedChannel | CalculatedChannelCreate | dict
    ]
    | None = None,
    simplify_channel_names: bool = False,
    combine_runs: bool = False,
    split_export_by_asset: bool = False,
    split_export_by_run: bool = False,
) -> Job

Export data from Sift.

Initiates an export on the server and returns a Job handle. Use job.wait_and_download() to poll for completion and download the files.

There are three ways to scope the export, determined by which arguments are provided:

1. By runs — provide runs. The start_time/stop_time are optional (if omitted, the full time range of each run is used). If no channels or calculated_channels are provided, all channels from the runs' assets are included.

2. By assets — provide assets. Both start_time and stop_time are required. If no channels or calculated_channels are provided, all channels from the assets are included.

3. By time range only — provide start_time and stop_time without runs or assets. At least one of channels or calculated_channels must be provided to scope the data.

You cannot provide both runs and assets at the same time.

PARAMETER	DESCRIPTION
output_format	The file format for the export (CSV, Parquet, or Sun/WinPlot). TYPE: ExportOutputFormat
runs	One or more Run objects or run IDs to export data from. TYPE: list[str | Run] | None DEFAULT: None
assets	One or more Asset objects or asset IDs to export data from. TYPE: list[str | Asset] | None DEFAULT: None
start_time	Start of the time range to export. Required when using assets or time-range-only mode; optional when using runs. TYPE: datetime | None DEFAULT: None
stop_time	End of the time range to export. Required when using assets or time-range-only mode; optional when using runs. TYPE: datetime | None DEFAULT: None
channels	Channel objects or channel IDs to include. If omitted and runs or assets are provided, all channels are exported. Required (along with calculated_channels) in time-range-only mode. TYPE: list[str | Channel] | None DEFAULT: None
calculated_channels	Calculated channels to include in the export. Accepts existing CalculatedChannel objects, CalculatedChannelCreate definitions, or dictionaries that will be converted to CalculatedChannelCreate via model_validate. TYPE: list[CalculatedChannel | CalculatedChannelCreate | dict] | None DEFAULT: None
simplify_channel_names	Remove text preceding last period in channel names, only if the resulting simplified name is unique. TYPE: bool DEFAULT: False
combine_runs	Identical channels within the same asset across multiple runs will be combined into a single column. TYPE: bool DEFAULT: False
split_export_by_asset	Split each asset into a separate file, with asset name removed from channel name display. TYPE: bool DEFAULT: False
split_export_by_run	Split each run into a separate file, with run name removed from channel name display. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Job	A Job handle for the pending export.

DataExportAPIAsync

DataExportAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for exporting data from Sift.

Initialize the DataExportAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
export	Export data from Sift.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

export async

export(
    *,
    output_format: ExportOutputFormat,
    runs: list[str | Run] | None = None,
    assets: list[str | Asset] | None = None,
    start_time: datetime | None = None,
    stop_time: datetime | None = None,
    channels: list[str | Channel] | None = None,
    calculated_channels: list[
        CalculatedChannel | CalculatedChannelCreate | dict
    ]
    | None = None,
    simplify_channel_names: bool = False,
    combine_runs: bool = False,
    split_export_by_asset: bool = False,
    split_export_by_run: bool = False,
) -> Job

Export data from Sift.

Initiates an export on the server and returns a Job handle. Use job.wait_and_download() to poll for completion and download the files.

There are three ways to scope the export, determined by which arguments are provided:

1. By runs — provide runs. The start_time/stop_time are optional (if omitted, the full time range of each run is used). If no channels or calculated_channels are provided, all channels from the runs' assets are included.

2. By assets — provide assets. Both start_time and stop_time are required. If no channels or calculated_channels are provided, all channels from the assets are included.

3. By time range only — provide start_time and stop_time without runs or assets. At least one of channels or calculated_channels must be provided to scope the data.

You cannot provide both runs and assets at the same time.

PARAMETER	DESCRIPTION
output_format	The file format for the export (CSV, Parquet, or Sun/WinPlot). TYPE: ExportOutputFormat
runs	One or more Run objects or run IDs to export data from. TYPE: list[str | Run] | None DEFAULT: None
assets	One or more Asset objects or asset IDs to export data from. TYPE: list[str | Asset] | None DEFAULT: None
start_time	Start of the time range to export. Required when using assets or time-range-only mode; optional when using runs. TYPE: datetime | None DEFAULT: None
stop_time	End of the time range to export. Required when using assets or time-range-only mode; optional when using runs. TYPE: datetime | None DEFAULT: None
channels	Channel objects or channel IDs to include. If omitted and runs or assets are provided, all channels are exported. Required (along with calculated_channels) in time-range-only mode. TYPE: list[str | Channel] | None DEFAULT: None
calculated_channels	Calculated channels to include in the export. Accepts existing CalculatedChannel objects, CalculatedChannelCreate definitions, or dictionaries that will be converted to CalculatedChannelCreate via model_validate. TYPE: list[CalculatedChannel | CalculatedChannelCreate | dict] | None DEFAULT: None
simplify_channel_names	Remove text preceding last period in channel names, only if the resulting simplified name is unique. TYPE: bool DEFAULT: False
combine_runs	Identical channels within the same asset across multiple runs will be combined into a single column. TYPE: bool DEFAULT: False
split_export_by_asset	Split each asset into a separate file, with asset name removed from channel name display. TYPE: bool DEFAULT: False
split_export_by_run	Split each run into a separate file, with run name removed from channel name display. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Job	A Job handle for the pending export.

DataImportAPI

DataImportAPI(sift_client: SiftClient)

Sync counterpart to DataImportAPIAsync.

High-level API for importing data into Sift.

Initialize the DataImportAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
detect_config	Auto-detect import configuration from a file.
get_run	Get the run associated with a data import.
import_from_path	Import data from a local file.

detect_config

detect_config(
    file_path: str | Path,
    data_type: DataTypeKey | None = None,
    time_format: TimeFormat | None = None,
) -> ImportConfig

Auto-detect import configuration from a file.

Reads a sample of the file, sends it to the server's DetectConfig endpoint, and returns the detected configuration. The file format is inferred from the file extension when data_type is not provided.

CSV, Parquet, HDF5, and TDMS files are supported for auto-detection.

For CSV files, the server scans the first two rows for an optional JSON metadata row. Row 1 is checked first; row 2 is checked only if row 1 is not valid metadata. A row qualifies as metadata when every cell contains valid JSON that describes either a time column or a data column. When present, first_data_row in the returned config is set to the row after the metadata row.

Each data column cell is a JSON ChannelConfig::

{"name": "speed", "units": "m/s", "dataType": "CHANNEL_DATA_TYPE_DOUBLE"}

The time column cell is a JSON CsvTimeColumn::

{"format": "TIME_FORMAT_ABSOLUTE_RFC3339"}

Enum type definitions and bit field elements can also be specified in the metadata row; they are applied server-side during import but are not included in the returned config.

For file types with multiple supported layouts (Parquet, HDF5), data_type must be specified explicitly.

PARAMETER	DESCRIPTION
file_path	Path to the file to analyze. TYPE: str | Path
data_type	Explicit data type key. Required for formats with multiple supported layouts (Parquet, HDF5) where the file extension alone is ambiguous. TYPE: DataTypeKey | None DEFAULT: None
time_format	Time format override. When provided, takes precedence over the format returned by detection. When omitted, the returned config uses the detected format if available, falling back to TimeFormat.ABSOLUTE_UNIX_NANOSECONDS. TYPE: TimeFormat | None DEFAULT: None

RETURNS	DESCRIPTION
ImportConfig	The detected import config.

RAISES	DESCRIPTION
FileNotFoundError	If the file does not exist.
ValueError	If the file extension is unsupported, no supported configuration could be detected, or data_type was omitted for a file format that requires a variant.

get_run

get_run(data_import_id: str) -> Run

Get the run associated with a data import.

The data_import_id is available on the job returned by import_from_path via job.job_details.data_import_id. For a more ergonomic approach, use job.get_import_run() which calls this method internally.

PARAMETER	DESCRIPTION
data_import_id	The ID of the data import. TYPE: str

RETURNS	DESCRIPTION
Run	The Run created by or associated with the import.

RAISES	DESCRIPTION
ValueError	If the data import has no associated run.

import_from_path

import_from_path(
    file_path: str | Path,
    *,
    asset: Asset | str | None = None,
    config: ImportConfig | None = None,
    data_type: DataTypeKey | None = None,
    time_format: TimeFormat | None = None,
    run: Run | str | None = None,
    run_name: str | None = None,
    show_progress: bool | None = None,
) -> Job

Import data from a local file.

Creates a data import on the server, uploads the file, and returns a Job handle after uploading the file. The import processes server-side and typically completes shortly after upload. Use job.wait_until_complete() only if you need to confirm completion before proceeding.

When config is omitted the file format is auto-detected via detect_config (CSV, Parquet, HDF5, and TDMS). When asset is provided it overrides the config value; otherwise the config's asset_name is used. If neither run nor run_name is provided (and none is set on the config), run_name defaults to the filename.

PARAMETER	DESCRIPTION
file_path	Path to the local file to import. TYPE: str | Path
asset	Asset object or asset name to import data into. Optional when config already has asset_name set. TYPE: Asset | str | None DEFAULT: None
config	Import configuration describing the file format and column mapping. When provided, data_type is ignored. If omitted, the config is auto-detected via detect_config. You can call detect_config yourself to inspect and modify the config before passing it here. TYPE: ImportConfig | None DEFAULT: None
data_type	Explicit data type key. Required for formats with multiple supported layouts (Parquet, HDF5) where the file extension alone is ambiguous. Only used when config is not provided. TYPE: DataTypeKey | None DEFAULT: None
time_format	Time format override. When provided, takes precedence over the format returned by detection. When omitted, the returned config uses the detected format if available, falling back to TimeFormat.ABSOLUTE_UNIX_NANOSECONDS. Only used when config is not provided. TYPE: TimeFormat | None DEFAULT: None
run	Run object or run ID string to import into an existing run. Mutually exclusive with run_name. TYPE: Run | str | None DEFAULT: None
run_name	Name for a new run. Defaults to the filename if neither run nor run_name is set. TYPE: str | None DEFAULT: None
show_progress	If True, display a progress spinner during upload. Defaults to True for sync, False for async. TYPE: bool | None DEFAULT: None

RETURNS	DESCRIPTION
Job	A Job handle for the pending import.

RAISES	DESCRIPTION
FileNotFoundError	If the file does not exist.

DataImportAPIAsync

DataImportAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for importing data into Sift.

Initialize the DataImportAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
detect_config	Auto-detect import configuration from a file.
get_run	Get the run associated with a data import.
import_from_path	Import data from a local file.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

detect_config async

detect_config(
    file_path: str | Path,
    data_type: DataTypeKey | None = None,
    time_format: TimeFormat | None = None,
) -> ImportConfig

Auto-detect import configuration from a file.

Reads a sample of the file, sends it to the server's DetectConfig endpoint, and returns the detected configuration. The file format is inferred from the file extension when data_type is not provided.

CSV, Parquet, HDF5, and TDMS files are supported for auto-detection.

For CSV files, the server scans the first two rows for an optional JSON metadata row. Row 1 is checked first; row 2 is checked only if row 1 is not valid metadata. A row qualifies as metadata when every cell contains valid JSON that describes either a time column or a data column. When present, first_data_row in the returned config is set to the row after the metadata row.

Each data column cell is a JSON ChannelConfig::

{"name": "speed", "units": "m/s", "dataType": "CHANNEL_DATA_TYPE_DOUBLE"}

The time column cell is a JSON CsvTimeColumn::

{"format": "TIME_FORMAT_ABSOLUTE_RFC3339"}

Enum type definitions and bit field elements can also be specified in the metadata row; they are applied server-side during import but are not included in the returned config.

For file types with multiple supported layouts (Parquet, HDF5), data_type must be specified explicitly.

PARAMETER	DESCRIPTION
file_path	Path to the file to analyze. TYPE: str | Path
data_type	Explicit data type key. Required for formats with multiple supported layouts (Parquet, HDF5) where the file extension alone is ambiguous. TYPE: DataTypeKey | None DEFAULT: None
time_format	Time format override. When provided, takes precedence over the format returned by detection. When omitted, the returned config uses the detected format if available, falling back to TimeFormat.ABSOLUTE_UNIX_NANOSECONDS. TYPE: TimeFormat | None DEFAULT: None

RETURNS	DESCRIPTION
ImportConfig	The detected import config.

RAISES	DESCRIPTION
FileNotFoundError	If the file does not exist.
ValueError	If the file extension is unsupported, no supported configuration could be detected, or data_type was omitted for a file format that requires a variant.

get_run async

get_run(data_import_id: str) -> Run

Get the run associated with a data import.

The data_import_id is available on the job returned by import_from_path via job.job_details.data_import_id. For a more ergonomic approach, use job.get_import_run() which calls this method internally.

PARAMETER	DESCRIPTION
data_import_id	The ID of the data import. TYPE: str

RETURNS	DESCRIPTION
Run	The Run created by or associated with the import.

RAISES	DESCRIPTION
ValueError	If the data import has no associated run.

import_from_path async

import_from_path(
    file_path: str | Path,
    *,
    asset: Asset | str | None = None,
    config: ImportConfig | None = None,
    data_type: DataTypeKey | None = None,
    time_format: TimeFormat | None = None,
    run: Run | str | None = None,
    run_name: str | None = None,
    show_progress: bool | None = None,
) -> Job

Import data from a local file.

Creates a data import on the server, uploads the file, and returns a Job handle after uploading the file. The import processes server-side and typically completes shortly after upload. Use job.wait_until_complete() only if you need to confirm completion before proceeding.

When config is omitted the file format is auto-detected via detect_config (CSV, Parquet, HDF5, and TDMS). When asset is provided it overrides the config value; otherwise the config's asset_name is used. If neither run nor run_name is provided (and none is set on the config), run_name defaults to the filename.

PARAMETER	DESCRIPTION
file_path	Path to the local file to import. TYPE: str | Path
asset	Asset object or asset name to import data into. Optional when config already has asset_name set. TYPE: Asset | str | None DEFAULT: None
config	Import configuration describing the file format and column mapping. When provided, data_type is ignored. If omitted, the config is auto-detected via detect_config. You can call detect_config yourself to inspect and modify the config before passing it here. TYPE: ImportConfig | None DEFAULT: None
data_type	Explicit data type key. Required for formats with multiple supported layouts (Parquet, HDF5) where the file extension alone is ambiguous. Only used when config is not provided. TYPE: DataTypeKey | None DEFAULT: None
time_format	Time format override. When provided, takes precedence over the format returned by detection. When omitted, the returned config uses the detected format if available, falling back to TimeFormat.ABSOLUTE_UNIX_NANOSECONDS. Only used when config is not provided. TYPE: TimeFormat | None DEFAULT: None
run	Run object or run ID string to import into an existing run. Mutually exclusive with run_name. TYPE: Run | str | None DEFAULT: None
run_name	Name for a new run. Defaults to the filename if neither run nor run_name is set. TYPE: str | None DEFAULT: None
show_progress	If True, display a progress spinner during upload. Defaults to True for sync, False for async. TYPE: bool | None DEFAULT: None

RETURNS	DESCRIPTION
Job	A Job handle for the pending import.

RAISES	DESCRIPTION
FileNotFoundError	If the file does not exist.

FileAttachmentsAPI

FileAttachmentsAPI(sift_client: SiftClient)

Sync counterpart to FileAttachmentsAPIAsync.

High-level API for interacting with file attachments (remote files).

This class provides a Pythonic interface for managing file attachments on Sift entities like runs, assets, and test reports.

Initialize the FileAttachmentsAPIAsync.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
delete	Batch delete multiple file attachments.
download	Download a file attachment to a local path.
get	Get a file attachment by ID.
get_download_url	Get a download URL for a file attachment.
list_	List file attachments with optional filtering.
update	Update a file attachment.
upload	Upload a file attachment to a remote file.

delete

delete(
    *,
    file_attachments: list[FileAttachment | str]
    | FileAttachment
    | str,
) -> None

Batch delete multiple file attachments.

PARAMETER	DESCRIPTION
file_attachments	List of FileAttachments or the IDs of the file attachments to delete (up to 1000). TYPE: list[FileAttachment | str] | FileAttachment | str

download

download(
    *,
    file_attachment: FileAttachment | str,
    output_path: str | Path,
) -> None

Download a file attachment to a local path.

PARAMETER	DESCRIPTION
file_attachment	The FileAttachment or the ID of the file attachment to download. TYPE: FileAttachment | str
output_path	The path to download the file attachment to. TYPE: str | Path

get

get(*, file_attachment_id: str) -> FileAttachment

Get a file attachment by ID.

PARAMETER	DESCRIPTION
file_attachment_id	The ID of the file attachment to retrieve. TYPE: str

RETURNS	DESCRIPTION
FileAttachment	The FileAttachment.

get_download_url

get_download_url(
    *, file_attachment: FileAttachment | str
) -> str

Get a download URL for a file attachment.

PARAMETER	DESCRIPTION
file_attachment	The FileAttachment or the ID of the file attachment. TYPE: FileAttachment | str

RETURNS	DESCRIPTION
str	The download URL for the file attachment.

list_

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    remote_file_ids: list[str] | None = None,
    entities: list[Run | Asset | TestReport | TestStep]
    | None = None,
    entity_type: RemoteFileEntityType | None = None,
    entity_ids: list[str] | None = None,
    description_contains: str | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[FileAttachment]

List file attachments with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the file attachment. TYPE: str | None DEFAULT: None
names	List of file attachment names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the file attachment. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter file attachments by name. TYPE: str | Pattern | None DEFAULT: None
remote_file_ids	Filter to file attachments with any of these IDs. TYPE: list[str] | None DEFAULT: None
entities	Filter to file attachments associated with these entities. TYPE: list[Run | Asset | TestReport | TestStep] | None DEFAULT: None
entity_type	Filter to file attachments associated with this entity type. TYPE: RemoteFileEntityType | None DEFAULT: None
entity_ids	Filter to file attachments associated with these entity IDs. TYPE: list[str] | None DEFAULT: None
description_contains	Partial description of the file attachment. TYPE: str | None DEFAULT: None
filter_query	Explicit CEL query to filter file attachments. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. Note: Not supported by the backend, but it is here for API consistency. TYPE: str | None DEFAULT: None
limit	Maximum number of file attachments to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[FileAttachment]	A list of FileAttachment objects that match the filter criteria.

update

update(
    *, file_attachment: FileAttachmentUpdate | dict
) -> FileAttachment

Update a file attachment.

PARAMETER	DESCRIPTION
file_attachment	The FileAttachmentUpdate with fields to update. TYPE: FileAttachmentUpdate | dict

RETURNS	DESCRIPTION
FileAttachment	The updated FileAttachment.

upload

upload(
    *,
    path: str | Path,
    entity: Asset | Run | TestReport | TestStep,
    metadata: dict[str, Any] | None = None,
    description: str | None = None,
    organization_id: str | None = None,
) -> FileAttachment

Upload a file attachment to a remote file.

PARAMETER	DESCRIPTION
path	The path to the file to upload. TYPE: str | Path
entity	The entity that the file is attached to. TYPE: Asset | Run | TestReport | TestStep
metadata	Optional metadata for the file (e.g., video/image metadata). TYPE: dict[str, Any] | None DEFAULT: None
description	Optional description of the file. TYPE: str | None DEFAULT: None
organization_id	Optional organization ID. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
FileAttachment	The uploaded FileAttachment.

FileAttachmentsAPIAsync

FileAttachmentsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with file attachments (remote files).

This class provides a Pythonic interface for managing file attachments on Sift entities like runs, assets, and test reports.

Initialize the FileAttachmentsAPIAsync.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
delete	Batch delete multiple file attachments.
download	Download a file attachment to a local path.
get	Get a file attachment by ID.
get_download_url	Get a download URL for a file attachment.
list_	List file attachments with optional filtering.
update	Update a file attachment.
upload	Upload a file attachment to a remote file.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

delete async

delete(
    *,
    file_attachments: list[FileAttachment | str]
    | FileAttachment
    | str,
) -> None

Batch delete multiple file attachments.

PARAMETER	DESCRIPTION
file_attachments	List of FileAttachments or the IDs of the file attachments to delete (up to 1000). TYPE: list[FileAttachment | str] | FileAttachment | str

download async

download(
    *,
    file_attachment: FileAttachment | str,
    output_path: str | Path,
) -> None

Download a file attachment to a local path.

PARAMETER	DESCRIPTION
file_attachment	The FileAttachment or the ID of the file attachment to download. TYPE: FileAttachment | str
output_path	The path to download the file attachment to. TYPE: str | Path

get async

get(*, file_attachment_id: str) -> FileAttachment

Get a file attachment by ID.

PARAMETER	DESCRIPTION
file_attachment_id	The ID of the file attachment to retrieve. TYPE: str

RETURNS	DESCRIPTION
FileAttachment	The FileAttachment.

get_download_url async

get_download_url(
    *, file_attachment: FileAttachment | str
) -> str

Get a download URL for a file attachment.

PARAMETER	DESCRIPTION
file_attachment	The FileAttachment or the ID of the file attachment. TYPE: FileAttachment | str

RETURNS	DESCRIPTION
str	The download URL for the file attachment.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    remote_file_ids: list[str] | None = None,
    entities: list[Run | Asset | TestReport | TestStep]
    | None = None,
    entity_type: RemoteFileEntityType | None = None,
    entity_ids: list[str] | None = None,
    description_contains: str | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[FileAttachment]

List file attachments with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the file attachment. TYPE: str | None DEFAULT: None
names	List of file attachment names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the file attachment. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter file attachments by name. TYPE: str | Pattern | None DEFAULT: None
remote_file_ids	Filter to file attachments with any of these IDs. TYPE: list[str] | None DEFAULT: None
entities	Filter to file attachments associated with these entities. TYPE: list[Run | Asset | TestReport | TestStep] | None DEFAULT: None
entity_type	Filter to file attachments associated with this entity type. TYPE: RemoteFileEntityType | None DEFAULT: None
entity_ids	Filter to file attachments associated with these entity IDs. TYPE: list[str] | None DEFAULT: None
description_contains	Partial description of the file attachment. TYPE: str | None DEFAULT: None
filter_query	Explicit CEL query to filter file attachments. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. Note: Not supported by the backend, but it is here for API consistency. TYPE: str | None DEFAULT: None
limit	Maximum number of file attachments to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[FileAttachment]	A list of FileAttachment objects that match the filter criteria.

update async

update(
    *, file_attachment: FileAttachmentUpdate | dict
) -> FileAttachment

Update a file attachment.

PARAMETER	DESCRIPTION
file_attachment	The FileAttachmentUpdate with fields to update. TYPE: FileAttachmentUpdate | dict

RETURNS	DESCRIPTION
FileAttachment	The updated FileAttachment.

upload async

upload(
    *,
    path: str | Path,
    entity: Asset | Run | TestReport | TestStep,
    metadata: dict[str, Any] | None = None,
    description: str | None = None,
    organization_id: str | None = None,
) -> FileAttachment

Upload a file attachment to a remote file.

PARAMETER	DESCRIPTION
path	The path to the file to upload. TYPE: str | Path
entity	The entity that the file is attached to. TYPE: Asset | Run | TestReport | TestStep
metadata	Optional metadata for the file (e.g., video/image metadata). TYPE: dict[str, Any] | None DEFAULT: None
description	Optional description of the file. TYPE: str | None DEFAULT: None
organization_id	Optional organization ID. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
FileAttachment	The uploaded FileAttachment.

IngestionAPIAsync

IngestionAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with ingestion services.

This class provides a Pythonic, notebook-friendly interface for interacting with the IngestionAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Flow class from the types module, which is a user-friendly representation of ingestion flows using standard Python data structures and types.

Initialize the IngestionAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
create_auto_register_streaming_client	Create an AutoRegisterStreamingClient.
create_ingestion_config_streaming_client	Create an IngestionConfigStreamingClient.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

create_auto_register_streaming_client async

create_auto_register_streaming_client(
    ingestion_config: IngestionConfig
    | IngestionConfigCreate
    | IngestionConfigFormPy,
    *,
    run: RunCreate | dict | str | Run | None = None,
    asset_tags: list[str] | list[Tag] | None = None,
    asset_metadata: dict[str, str | float | bool]
    | None = None,
    streaming_mode: StreamingMode = LIVE_WITH_BACKUPS,
    retry_policy: RetryPolicyPy | None = None,
    disk_backup_policy: DiskBackupPolicyPy | None = None,
    checkpoint_interval_seconds: int | None = None,
    enable_tls: bool = True,
    tracing_config: TracingConfig | None = None,
    staged_configs: list[FlowConfig] | None = None,
) -> AutoRegisterStreamingClient

Create an AutoRegisterStreamingClient.

Flows are registered automatically on first send — no pre-declared schema is required. Pre-registering known flows via the ingestion_config argument is still supported: those flows are placed in the local cache at build time and bypass the registration step on first send, so latency is the same as create_ingestion_config_streaming_client.

Using the AutoRegisterStreamingClient can be useful in the following scenarios: * Your ingestion config is too large to be registered or returned in a single gRPC call. * Many of the flows defined for your ingestion config will not be actively streamed.

In both of these scenarios, the amount of time that it can take to initialize the client due to the number of flows may be undesirable. The "lazy" registration, or "just in time" registration provided through AutoRegisterStreamingClient can improve this by delaying registration to when the flow is first provided to the client.

PARAMETER	DESCRIPTION
ingestion_config	The ingestion config. Use IngestionConfigCreate with flows=[] for a fully schema-free start, or provide flow definitions to pre-register known flows and avoid any first-send latency for those flows. TYPE: IngestionConfig | IngestionConfigCreate | IngestionConfigFormPy
run	The run to associate with ingestion. Can be a Run, RunCreate, dict, or run ID string. TYPE: RunCreate | dict | str | Run | None DEFAULT: None
asset_tags	Tags to associate with the asset. TYPE: list[str] | list[Tag] | None DEFAULT: None
asset_metadata	Metadata to associate with the asset. TYPE: dict[str, str | float | bool] | None DEFAULT: None
streaming_mode	Transport mode for the stream. Defaults to LIVE_WITH_BACKUPS. TYPE: StreamingMode DEFAULT: LIVE_WITH_BACKUPS
retry_policy	Retry policy for LIVE_WITH_BACKUPS mode. TYPE: RetryPolicyPy | None DEFAULT: None
disk_backup_policy	Disk backup policy for LIVE_WITH_BACKUPS or FILE_BACKUP mode. TYPE: DiskBackupPolicyPy | None DEFAULT: None
checkpoint_interval_seconds	Checkpoint interval in seconds (LIVE_WITH_BACKUPS only). TYPE: int | None DEFAULT: None
enable_tls	Whether to enable TLS for the connection. TYPE: bool DEFAULT: True
tracing_config	Configuration for SiftStream tracing. TYPE: TracingConfig | None DEFAULT: None
staged_configs	Optional flow configs to use when auto-registering flows for the first time. When a staged config exists for a flow, it is used for registration instead of a minimal derived config, preserving units, descriptions, and other metadata. The staged config is validated against the flow's channel names and types before use; a mismatch raises RuntimeError. TYPE: list[FlowConfig] | None DEFAULT: None

RETURNS	DESCRIPTION
AutoRegisterStreamingClient	An initialized AutoRegisterStreamingClient.

create_ingestion_config_streaming_client async

create_ingestion_config_streaming_client(
    ingestion_config: IngestionConfig
    | IngestionConfigCreate
    | IngestionConfigFormPy,
    *,
    run: RunCreate | dict | str | Run | None = None,
    asset_tags: list[str] | list[Tag] | None = None,
    asset_metadata: dict[str, str | float | bool]
    | None = None,
    streaming_mode: StreamingMode = LIVE_WITH_BACKUPS,
    retry_policy: RetryPolicyPy | None = None,
    disk_backup_policy: DiskBackupPolicyPy | None = None,
    checkpoint_interval_seconds: int | None = None,
    enable_tls: bool = True,
    tracing_config: TracingConfig | None = None,
) -> IngestionConfigStreamingClient

Create an IngestionConfigStreamingClient.

PARAMETER	DESCRIPTION
ingestion_config	The ingestion config. Can be a IngestionConfig or IngestionConfigFormPy. TYPE: IngestionConfig | IngestionConfigCreate | IngestionConfigFormPy
run	The run to associate with ingestion. Can be a Run, RunCreate, dict, or run ID string. TYPE: RunCreate | dict | str | Run | None DEFAULT: None
asset_tags	Tags to associate with the asset. TYPE: list[str] | list[Tag] | None DEFAULT: None
asset_metadata	Metadata to associate with the asset. TYPE: dict[str, str | float | bool] | None DEFAULT: None
streaming_mode	Transport mode for the stream. Defaults to LIVE_WITH_BACKUPS. TYPE: StreamingMode DEFAULT: LIVE_WITH_BACKUPS
retry_policy	Retry policy for LIVE_WITH_BACKUPS mode. TYPE: RetryPolicyPy | None DEFAULT: None
disk_backup_policy	Disk backup policy for LIVE_WITH_BACKUPS or FILE_BACKUP mode. TYPE: DiskBackupPolicyPy | None DEFAULT: None
checkpoint_interval_seconds	Checkpoint interval in seconds (LIVE_WITH_BACKUPS only). TYPE: int | None DEFAULT: None
enable_tls	Whether to enable TLS for the connection. TYPE: bool DEFAULT: True
tracing_config	Configuration for SiftStream tracing. Use TracingConfig.console_only() to enable tracing to stdout only, or TracingConfig.with_file() to enable tracing to both stdout and rolling log files. Defaults to None (tracing will be initialized with default settings if not already initialized). TYPE: TracingConfig | None DEFAULT: None

RETURNS	DESCRIPTION
IngestionConfigStreamingClient	An initialized IngestionConfigStreamingClient.

IngestionConfigStreamingClient

IngestionConfigStreamingClient(
    sift_client: SiftClient,
    low_level_client: IngestionConfigStreamingLowLevelClient,
)

Bases: ResourceBase

A client for streaming ingestion with an ingestion config.

This client provides a high-level interface for streaming data to Sift using an ingestion config. Under the hood, this client uses the Rust powered SiftStream library to provide a high-performance, low-latency, and reliable streaming interface to Sift.

This client should be initialized using the create classmethod, and not directly. Once streaming has ended, the client should be shutdown using the finish method.

Initialize an IngestionConfigStreamingClient. Users should not initialize this class directly, but rather use the create classmethod.

METHOD	DESCRIPTION
add_new_flows	Modify the existing ingestion config by adding new flows that weren't accounted for during initialization.
attach_run	Attach a run to the stream.
batch_send	Send multiple flows to Sift in a single batch operation.
detach_run	Detach the run, if any, associated with the stream.
finish	Conclude the stream and return when Sift has sent its final response.
get_flow_descriptor	Retrieve a flow descriptor by name.
get_metrics_snapshot	Retrieve a snapshot of the current metrics for this stream.
get_run_id	Retrieve the ID of the attached run, if one exists.
send	Send telemetry to Sift in the form of a Flow.
send_requests	Send data in a manner identical to the raw gRPC service for ingestion-config based streaming.
try_send	Non-blocking send — returns immediately without awaiting channel capacity.
try_send_requests	Send data non-blocking in a manner identical to the raw gRPC service for ingestion-config based streaming.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

add_new_flows async

add_new_flows(flow_configs: list[FlowConfig])

Modify the existing ingestion config by adding new flows that weren't accounted for during initialization.

This allows you to dynamically add new flow configurations to the ingestion config after the stream has been initialized. The new flows will be registered with Sift and can then be used in subsequent send calls.

PARAMETER	DESCRIPTION
flow_configs	List of flow configurations to add to the ingestion config. TYPE: list[FlowConfig]

attach_run async

attach_run(run: RunCreate | dict | str | Run | RunFormPy)

Attach a run to the stream.

Any data provided through send after this function returns will be associated with the run. The run can be specified as a Run object, RunCreate object, dict, run ID string, or RunFormPy object.

PARAMETER	DESCRIPTION
run	The run to attach. Can be a Run, RunCreate, dict, run ID string, or RunFormPy. TYPE: RunCreate | dict | str | Run | RunFormPy

batch_send async

batch_send(flows: Iterable[Flow | FlowPy])

Send multiple flows to Sift in a single batch operation.

This method allows you to send multiple flows efficiently in a single batch, which can improve performance by reducing overhead compared to calling send multiple times.

PARAMETER	DESCRIPTION
flows	An iterable of flows to send. Each flow can be either a Flow or FlowPy instance. TYPE: Iterable[Flow | FlowPy]

detach_run

detach_run()

Detach the run, if any, associated with the stream.

Any data provided through send after this function is called will not be associated with a run.

finish async

finish()

Conclude the stream and return when Sift has sent its final response.

It is important that this method be called in order to obtain the final checkpoint acknowledgement from Sift, otherwise some tail-end data may fail to send. This method will gracefully shut down the streaming system and ensure all data has been properly sent to Sift.

get_flow_descriptor

get_flow_descriptor(flow_name: str) -> FlowDescriptorPy

Retrieve a flow descriptor by name.

PARAMETER	DESCRIPTION
flow_name	The name of the flow descriptor to retrieve. TYPE: str

get_metrics_snapshot

get_metrics_snapshot() -> SiftStreamMetricsSnapshotPy

Retrieve a snapshot of the current metrics for this stream.

NOTE: The returned metrics snapshot is currently an unstable feature and may change at any time.

Metrics are recorded related to the performance and operational status of the stream. Snapshots are taken at any time this method is called. Metrics are internally updated atomically, and calls to get metric snapshots are non-blocking to stream operation.

RETURNS	DESCRIPTION
SiftStreamMetricsSnapshotPy	A snapshot of the current stream metrics.

get_run_id

get_run_id() -> str | None

Retrieve the ID of the attached run, if one exists.

RETURNS	DESCRIPTION
str | None	The run ID if a run is attached, None otherwise.

send async

send(flow: Flow | FlowPy)

Send telemetry to Sift in the form of a Flow.

This is the entry-point to send actual telemetry to Sift. If a message is sent that doesn't match any flows that the stream knows about locally, the message will still be transmitted and a warning log emitted. If you are certain that the message corresponds to an unregistered flow then add_new_flows should be called first to register the flow before calling send; otherwise you should monitor the Sift DLQ either in the Sift UI or Sift API to ensure successful transmission.

When sending messages, if backups are enabled, first the message is sent to the backup system. This system is used to backup data to disk until the data is confirmed received by Sift. If streaming encounters errors, the backed up data will be re-ingested ensuring all data is received by Sift.

If the backup system has fallen behind and the backup queue/channel is full, it will still proceed to sending the message to Sift. This ensures data is sent to Sift even if the backup system is lagging.

PARAMETER	DESCRIPTION
flow	The flow to send to Sift. TYPE: Flow | FlowPy

send_requests async

send_requests(
    requests: list[IngestWithConfigDataStreamRequestPy],
)

Send data in a manner identical to the raw gRPC service for ingestion-config based streaming.

This method offers a way to send data that matches the raw gRPC service interface. You are expected to handle channel value ordering as well as empty values correctly.

Important

Most users should prefer to use send. This method primarily exists to make it easier for existing integrations to utilize sift-stream.

PARAMETER	DESCRIPTION
requests	List of ingestion requests to send to Sift. TYPE: list[IngestWithConfigDataStreamRequestPy]

try_send

try_send(flow: Flow | FlowPy) -> None

Non-blocking send — returns immediately without awaiting channel capacity.

PARAMETER	DESCRIPTION
flow	The flow to send to Sift. TYPE: Flow | FlowPy

try_send_requests

try_send_requests(
    requests: Iterable[
        IngestWithConfigDataStreamRequestWrapperPy
    ],
) -> None

Send data non-blocking in a manner identical to the raw gRPC service for ingestion-config based streaming.

This method offers a way to send data that matches the raw gRPC service interface. You are expected to handle channel value ordering as well as empty values correctly.

Important

If using this interface, you should use FlowBuilderPy::request to ensure proper building of the request.

PARAMETER	DESCRIPTION
requests	Iterable of ingestion requests to send to Sift. TYPE: Iterable[IngestWithConfigDataStreamRequestWrapperPy]

JobsAPI

JobsAPI(sift_client: SiftClient)

Sync counterpart to JobsAPIAsync.

High-level API for interacting with jobs.

This class provides a Pythonic interface for managing jobs in Sift. Jobs represent long-running operations like data imports, rule evaluations, and data exports.

Initialize the JobsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
cancel	Cancel a job.
get	Get a job by ID.
list_	List jobs with optional filtering.
retry	Retry a failed job.
wait_and_download	Wait for a job to complete and download the result files.
wait_until_complete	Wait until the job is complete or the timeout is reached.

cancel

cancel(job: Job | str) -> None

Cancel a job.

If the job hasn't started yet, it will be cancelled immediately. Jobs that are already finished, failed, or cancelled are not affected.

PARAMETER	DESCRIPTION
job	The Job or ID of the job to cancel. TYPE: Job | str

get

get(job_id: str) -> Job

Get a job by ID.

PARAMETER	DESCRIPTION
job_id	The ID of the job to retrieve. TYPE: str

RETURNS	DESCRIPTION
Job	The Job object.

list_

list_(
    *,
    job_ids: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by_user_id: str | None = None,
    modified_by_user_id: str | None = None,
    job_type: JobType | None = None,
    job_status: JobStatus | None = None,
    started_date_after: datetime | None = None,
    started_date_before: datetime | None = None,
    completed_date_after: datetime | None = None,
    completed_date_before: datetime | None = None,
    organization_id: str | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Job]

List jobs with optional filtering.

PARAMETER	DESCRIPTION
job_ids	Filter to jobs with any of these IDs. TYPE: list[str] | None DEFAULT: None
created_after	Filter to jobs created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter to jobs created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter to jobs modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter to jobs modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by_user_id	Filter to jobs created by this user ID. TYPE: str | None DEFAULT: None
modified_by_user_id	Filter to jobs last modified by this user ID. TYPE: str | None DEFAULT: None
job_type	Filter to jobs with this type. TYPE: JobType | None DEFAULT: None
job_status	Filter to jobs with this status. TYPE: JobStatus | None DEFAULT: None
started_date_after	Filter to jobs started after this datetime. TYPE: datetime | None DEFAULT: None
started_date_before	Filter to jobs started before this datetime. TYPE: datetime | None DEFAULT: None
completed_date_after	Filter to jobs completed after this datetime. TYPE: datetime | None DEFAULT: None
completed_date_before	Filter to jobs completed before this datetime. TYPE: datetime | None DEFAULT: None
organization_id	Organization ID. Required if your user belongs to multiple organizations. TYPE: str | None DEFAULT: None
filter_query	Explicit CEL query to filter jobs. If provided, other filter arguments are ignored. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of jobs to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Job]	A list of Job objects that match the filter criteria.

retry

retry(job: Job | str) -> Job

Retry a failed job.

Jobs that are finished, in progress, or in the process of being cancelled are not affected.

PARAMETER	DESCRIPTION
job	The Job or ID of the job to retry. TYPE: Job | str

RETURNS	DESCRIPTION
Job	The updated Job object.

wait_and_download

wait_and_download(
    job: Job | str,
    *,
    polling_interval_secs: int = 5,
    timeout_secs: int | None = None,
    output_dir: str | Path | None = None,
    extract: bool = True,
    show_progress: bool | None = None,
) -> list[Path]

Wait for a job to complete and download the result files.

Polls the job status at the given interval until the job is FINISHED, FAILED, or CANCELLED, then downloads the result files.

PARAMETER	DESCRIPTION
job	The Job or job ID to wait for. TYPE: Job | str
polling_interval_secs	Seconds between status polls. Defaults to 5. TYPE: int DEFAULT: 5
timeout_secs	Maximum seconds to wait. If None, polls indefinitely. TYPE: int | None DEFAULT: None
output_dir	Directory to save the downloaded files. If omitted, a temporary directory is created automatically. TYPE: str | Path | None DEFAULT: None
extract	If True (default) and the downloaded file is a zip, extract it and delete the archive, returning paths to the extracted files. Non-zip files are returned as-is regardless of this flag. TYPE: bool DEFAULT: True
show_progress	If True, display an animated progress spinner while waiting and a download progress bar. Defaults to True for sync, False for async. Use sift_client.config.show_progress = False to disable globally for sync. TYPE: bool | None DEFAULT: None

RETURNS	DESCRIPTION
list[Path]	List of paths to the downloaded/extracted files.

RAISES	DESCRIPTION
RuntimeError	If the job fails or is cancelled.
TimeoutError	If the job does not complete within timeout_secs.

wait_until_complete

wait_until_complete(
    job: Job | str,
    *,
    polling_interval_secs: int = 5,
    timeout_secs: int | None = None,
    show_progress: bool | None = None,
) -> Job

Wait until the job is complete or the timeout is reached.

Polls the job status at the given interval until the job is FINISHED, FAILED, or CANCELLED, returning the completed Job

PARAMETER	DESCRIPTION
job	The Job or job_id to wait for. TYPE: Job | str
polling_interval_secs	Seconds between status polls. Defaults to 5s. TYPE: int DEFAULT: 5
timeout_secs	Maximum seconds to wait. If None, polls indefinitely. Defaults to None (indefinite). TYPE: int | None DEFAULT: None
show_progress	If True, display an animated progress spinner alongside the job status while polling. Defaults to True for sync, False for async. Use sift_client.config.show_progress = False to disable globally for sync. TYPE: bool | None DEFAULT: None

RETURNS	DESCRIPTION
Job	The Job in the completed state.

JobsAPIAsync

JobsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with jobs.

This class provides a Pythonic interface for managing jobs in Sift. Jobs represent long-running operations like data imports, rule evaluations, and data exports.

Initialize the JobsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
cancel	Cancel a job.
get	Get a job by ID.
list_	List jobs with optional filtering.
retry	Retry a failed job.
wait_and_download	Wait for a job to complete and download the result files.
wait_until_complete	Wait until the job is complete or the timeout is reached.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

cancel async

cancel(job: Job | str) -> None

Cancel a job.

If the job hasn't started yet, it will be cancelled immediately. Jobs that are already finished, failed, or cancelled are not affected.

PARAMETER	DESCRIPTION
job	The Job or ID of the job to cancel. TYPE: Job | str

get async

get(job_id: str) -> Job

Get a job by ID.

PARAMETER	DESCRIPTION
job_id	The ID of the job to retrieve. TYPE: str

RETURNS	DESCRIPTION
Job	The Job object.

list_ async

list_(
    *,
    job_ids: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by_user_id: str | None = None,
    modified_by_user_id: str | None = None,
    job_type: JobType | None = None,
    job_status: JobStatus | None = None,
    started_date_after: datetime | None = None,
    started_date_before: datetime | None = None,
    completed_date_after: datetime | None = None,
    completed_date_before: datetime | None = None,
    organization_id: str | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Job]

List jobs with optional filtering.

PARAMETER	DESCRIPTION
job_ids	Filter to jobs with any of these IDs. TYPE: list[str] | None DEFAULT: None
created_after	Filter to jobs created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter to jobs created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter to jobs modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter to jobs modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by_user_id	Filter to jobs created by this user ID. TYPE: str | None DEFAULT: None
modified_by_user_id	Filter to jobs last modified by this user ID. TYPE: str | None DEFAULT: None
job_type	Filter to jobs with this type. TYPE: JobType | None DEFAULT: None
job_status	Filter to jobs with this status. TYPE: JobStatus | None DEFAULT: None
started_date_after	Filter to jobs started after this datetime. TYPE: datetime | None DEFAULT: None
started_date_before	Filter to jobs started before this datetime. TYPE: datetime | None DEFAULT: None
completed_date_after	Filter to jobs completed after this datetime. TYPE: datetime | None DEFAULT: None
completed_date_before	Filter to jobs completed before this datetime. TYPE: datetime | None DEFAULT: None
organization_id	Organization ID. Required if your user belongs to multiple organizations. TYPE: str | None DEFAULT: None
filter_query	Explicit CEL query to filter jobs. If provided, other filter arguments are ignored. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of jobs to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Job]	A list of Job objects that match the filter criteria.

retry async

retry(job: Job | str) -> Job

Retry a failed job.

Jobs that are finished, in progress, or in the process of being cancelled are not affected.

PARAMETER	DESCRIPTION
job	The Job or ID of the job to retry. TYPE: Job | str

RETURNS	DESCRIPTION
Job	The updated Job object.

wait_and_download async

wait_and_download(
    job: Job | str,
    *,
    polling_interval_secs: int = 5,
    timeout_secs: int | None = None,
    output_dir: str | Path | None = None,
    extract: bool = True,
    show_progress: bool | None = None,
) -> list[Path]

Wait for a job to complete and download the result files.

Polls the job status at the given interval until the job is FINISHED, FAILED, or CANCELLED, then downloads the result files.

PARAMETER	DESCRIPTION
job	The Job or job ID to wait for. TYPE: Job | str
polling_interval_secs	Seconds between status polls. Defaults to 5. TYPE: int DEFAULT: 5
timeout_secs	Maximum seconds to wait. If None, polls indefinitely. TYPE: int | None DEFAULT: None
output_dir	Directory to save the downloaded files. If omitted, a temporary directory is created automatically. TYPE: str | Path | None DEFAULT: None
extract	If True (default) and the downloaded file is a zip, extract it and delete the archive, returning paths to the extracted files. Non-zip files are returned as-is regardless of this flag. TYPE: bool DEFAULT: True
show_progress	If True, display an animated progress spinner while waiting and a download progress bar. Defaults to True for sync, False for async. Use sift_client.config.show_progress = False to disable globally for sync. TYPE: bool | None DEFAULT: None

RETURNS	DESCRIPTION
list[Path]	List of paths to the downloaded/extracted files.

RAISES	DESCRIPTION
RuntimeError	If the job fails or is cancelled.
TimeoutError	If the job does not complete within timeout_secs.

wait_until_complete async

wait_until_complete(
    job: Job | str,
    *,
    polling_interval_secs: int = 5,
    timeout_secs: int | None = None,
    show_progress: bool | None = None,
) -> Job

Wait until the job is complete or the timeout is reached.

Polls the job status at the given interval until the job is FINISHED, FAILED, or CANCELLED, returning the completed Job

PARAMETER	DESCRIPTION
job	The Job or job_id to wait for. TYPE: Job | str
polling_interval_secs	Seconds between status polls. Defaults to 5s. TYPE: int DEFAULT: 5
timeout_secs	Maximum seconds to wait. If None, polls indefinitely. Defaults to None (indefinite). TYPE: int | None DEFAULT: None
show_progress	If True, display an animated progress spinner alongside the job status while polling. Defaults to True for sync, False for async. Use sift_client.config.show_progress = False to disable globally for sync. TYPE: bool | None DEFAULT: None

RETURNS	DESCRIPTION
Job	The Job in the completed state.

PingAPI

PingAPI(sift_client: SiftClient)

Sync counterpart to PingAPIAsync.

High-level API for performing health checks.

Initialize the AssetsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
ping	Send a ping request to the server.

ping

ping() -> str

Send a ping request to the server.

RETURNS	DESCRIPTION
str	The response from the server.

PingAPIAsync

PingAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for performing health checks.

Initialize the AssetsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
ping	Send a ping request to the server.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

ping async

ping() -> str

Send a ping request to the server.

RETURNS	DESCRIPTION
str	The response from the server.

PrincipalAttributesAPI

PrincipalAttributesAPI(sift_client: SiftClient)

Sync counterpart to PrincipalAttributesAPIAsync.

High-level API for principal attributes (ABAC).

Principal attributes assign attribute keys to principals (users or user groups). The attribute key is the entry point: enum values and assignments are managed through methods on a key, or through the corresponding methods here.

Initialize the PrincipalAttributesAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive_assignments	Batch archive assignments.
archive_enum_value	Archive an enum value, migrating existing assignments to a replacement.
archive_key	Archive a key. Cascades to its enum values and assignments.
assign	Assign a value to principals for a key.
check_key_archive_impact	Return the number of active assignments archiving this key would affect.
create_enum_value	Create a single enum value for a key.
create_key	Create a principal attribute key.
find_key	Find a single key matching the query. Raises if more than one matches.
get_assignment	Get a single assignment by ID.
get_key	Get a principal attribute key by ID.
get_or_create_enum_values	Get enum values for a key by name, creating any that don't exist.
get_or_create_key	Get a key by display name, creating it if it does not exist.
list_assignments	List principal attribute assignments.
list_enum_values	List the enum values defined for a key.
list_keys	List principal attribute keys with optional filtering.
resolve_user_id	Resolve a user's email (its user name) to a user ID.
resolve_user_ids	Resolve user emails (their user names) to user IDs.
unarchive_assignments	Batch unarchive assignments.
unarchive_enum_value	Unarchive an enum value.
unarchive_key	Unarchive a key. Does not restore its cascaded enum values or assignments.
update_key	Update a key's display name or description.

archive_assignments

archive_assignments(
    assignments: list[str | PrincipalAttributeValue],
    *,
    principal_type: PrincipalType = USER,
) -> None

Batch archive assignments.

archive_enum_value

archive_enum_value(
    enum_value: str | PrincipalAttributeEnumValue,
    *,
    replacement: str
    | PrincipalAttributeEnumValue
    | None = None,
) -> int

Archive an enum value, migrating existing assignments to a replacement.

Returns the number of assignments migrated.

archive_key

archive_key(
    key: str | PrincipalAttributeKey,
) -> PrincipalAttributeKey

Archive a key. Cascades to its enum values and assignments.

assign

assign(
    key: PrincipalAttributeKey,
    principals: list[str],
    *,
    value: Any,
    principal_type: PrincipalType = USER,
) -> list[PrincipalAttributeValue]

Assign a value to principals for a key.

PARAMETER	DESCRIPTION
key	The key to assign. Its value_type determines how value is interpreted. TYPE: PrincipalAttributeKey
principals	Principal IDs. For USER principals, an entry containing @ is treated as an email and resolved to a user ID. TYPE: list[str]
value	For SET_OF_ENUM, a list of enum values (or their IDs) that becomes the full set on each principal; for ENUM, a single enum value; for BOOLEAN, a bool; for NUMBER, an int. TYPE: Any
principal_type	The kind of principal being assigned to. Defaults to USER. TYPE: PrincipalType DEFAULT: USER

RETURNS	DESCRIPTION
list[PrincipalAttributeValue]	The created assignments.

check_key_archive_impact

check_key_archive_impact(
    key: str | PrincipalAttributeKey,
) -> int

Return the number of active assignments archiving this key would affect.

Counts both user and user-group assignments.

create_enum_value

create_enum_value(
    key: str | PrincipalAttributeKey,
    display_name: str,
    *,
    description: str = "",
) -> PrincipalAttributeEnumValue

Create a single enum value for a key.

create_key

create_key(
    display_name: str,
    value_type: PrincipalAttributeValueType,
    *,
    description: str = "",
) -> PrincipalAttributeKey

Create a principal attribute key.

find_key

find_key(**kwargs) -> PrincipalAttributeKey | None

Find a single key matching the query. Raises if more than one matches.

get_assignment

get_assignment(
    *,
    assignment_id: str,
    principal_type: PrincipalType = USER,
) -> PrincipalAttributeValue

Get a single assignment by ID.

get_key

get_key(*, key_id: str) -> PrincipalAttributeKey

Get a principal attribute key by ID.

get_or_create_enum_values

get_or_create_enum_values(
    key: str | PrincipalAttributeKey, names: list[str]
) -> list[PrincipalAttributeEnumValue]

Get enum values for a key by name, creating any that don't exist.

Returns the values in the same order as names.

get_or_create_key

get_or_create_key(
    display_name: str,
    value_type: PrincipalAttributeValueType,
    *,
    description: str = "",
) -> PrincipalAttributeKey

Get a key by display name, creating it if it does not exist.

Note

Display names are not guaranteed unique. If multiple keys share the display name, the first active match is returned.

list_assignments

list_assignments(
    *,
    key: str | PrincipalAttributeKey | None = None,
    principal: str | None = None,
    principal_type: PrincipalType = USER,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeValue]

List principal attribute assignments.

PARAMETER	DESCRIPTION
key	Filter to assignments of this key. TYPE: str | PrincipalAttributeKey | None DEFAULT: None
principal	Filter to assignments for this principal (user ID, or email for users). TYPE: str | None DEFAULT: None
principal_type	The kind of principal to list assignments for. Defaults to USER. TYPE: PrincipalType DEFAULT: USER
include_archived	If True, include archived assignments. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of assignments to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

list_enum_values

list_enum_values(
    key: str | PrincipalAttributeKey,
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeEnumValue]

List the enum values defined for a key.

list_keys

list_keys(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    value_type: PrincipalAttributeValueType | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeKey]

List principal attribute keys with optional filtering.

PARAMETER	DESCRIPTION
name	Exact display name of the key. TYPE: str | None DEFAULT: None
names	Display names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Substring match on the display name. TYPE: str | None DEFAULT: None
name_regex	Regex match on the display name. TYPE: str | Pattern | None DEFAULT: None
value_type	Filter to keys of this value type. TYPE: PrincipalAttributeValueType | None DEFAULT: None
include_archived	If True, include archived keys. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of keys to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

resolve_user_id

resolve_user_id(email: str) -> str

Resolve a user's email (its user name) to a user ID.

RAISES	DESCRIPTION
ValueError	If no user with that email is found.

resolve_user_ids

resolve_user_ids(emails: list[str]) -> dict[str, str]

Resolve user emails (their user names) to user IDs.

Returns a mapping of email to user ID for the emails that were found. Emails with no matching user are omitted.

unarchive_assignments

unarchive_assignments(
    assignments: list[str | PrincipalAttributeValue],
    *,
    principal_type: PrincipalType = USER,
) -> None

Batch unarchive assignments.

unarchive_enum_value

unarchive_enum_value(
    enum_value: str | PrincipalAttributeEnumValue,
) -> PrincipalAttributeEnumValue

Unarchive an enum value.

unarchive_key

unarchive_key(
    key: str | PrincipalAttributeKey,
) -> PrincipalAttributeKey

Unarchive a key. Does not restore its cascaded enum values or assignments.

update_key

update_key(
    key: str | PrincipalAttributeKey,
    *,
    display_name: str | None = None,
    description: str | None = None,
) -> PrincipalAttributeKey

Update a key's display name or description.

PrincipalAttributesAPIAsync

PrincipalAttributesAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for principal attributes (ABAC).

Principal attributes assign attribute keys to principals (users or user groups). The attribute key is the entry point: enum values and assignments are managed through methods on a key, or through the corresponding methods here.

Initialize the PrincipalAttributesAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive_assignments	Batch archive assignments.
archive_enum_value	Archive an enum value, migrating existing assignments to a replacement.
archive_key	Archive a key. Cascades to its enum values and assignments.
assign	Assign a value to principals for a key.
check_key_archive_impact	Return the number of active assignments archiving this key would affect.
create_enum_value	Create a single enum value for a key.
create_key	Create a principal attribute key.
find_key	Find a single key matching the query. Raises if more than one matches.
get_assignment	Get a single assignment by ID.
get_key	Get a principal attribute key by ID.
get_or_create_enum_values	Get enum values for a key by name, creating any that don't exist.
get_or_create_key	Get a key by display name, creating it if it does not exist.
list_assignments	List principal attribute assignments.
list_enum_values	List the enum values defined for a key.
list_keys	List principal attribute keys with optional filtering.
resolve_user_id	Resolve a user's email (its user name) to a user ID.
resolve_user_ids	Resolve user emails (their user names) to user IDs.
unarchive_assignments	Batch unarchive assignments.
unarchive_enum_value	Unarchive an enum value.
unarchive_key	Unarchive a key. Does not restore its cascaded enum values or assignments.
update_key	Update a key's display name or description.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive_assignments async

archive_assignments(
    assignments: list[str | PrincipalAttributeValue],
    *,
    principal_type: PrincipalType = USER,
) -> None

Batch archive assignments.

archive_enum_value async

archive_enum_value(
    enum_value: str | PrincipalAttributeEnumValue,
    *,
    replacement: str
    | PrincipalAttributeEnumValue
    | None = None,
) -> int

Archive an enum value, migrating existing assignments to a replacement.

Returns the number of assignments migrated.

archive_key async

archive_key(
    key: str | PrincipalAttributeKey,
) -> PrincipalAttributeKey

Archive a key. Cascades to its enum values and assignments.

assign async

assign(
    key: PrincipalAttributeKey,
    principals: list[str],
    *,
    value: Any,
    principal_type: PrincipalType = USER,
) -> list[PrincipalAttributeValue]

Assign a value to principals for a key.

PARAMETER	DESCRIPTION
key	The key to assign. Its value_type determines how value is interpreted. TYPE: PrincipalAttributeKey
principals	Principal IDs. For USER principals, an entry containing @ is treated as an email and resolved to a user ID. TYPE: list[str]
value	For SET_OF_ENUM, a list of enum values (or their IDs) that becomes the full set on each principal; for ENUM, a single enum value; for BOOLEAN, a bool; for NUMBER, an int. TYPE: Any
principal_type	The kind of principal being assigned to. Defaults to USER. TYPE: PrincipalType DEFAULT: USER

RETURNS	DESCRIPTION
list[PrincipalAttributeValue]	The created assignments.

check_key_archive_impact async

check_key_archive_impact(
    key: str | PrincipalAttributeKey,
) -> int

Return the number of active assignments archiving this key would affect.

Counts both user and user-group assignments.

create_enum_value async

create_enum_value(
    key: str | PrincipalAttributeKey,
    display_name: str,
    *,
    description: str = "",
) -> PrincipalAttributeEnumValue

Create a single enum value for a key.

create_key async

create_key(
    display_name: str,
    value_type: PrincipalAttributeValueType,
    *,
    description: str = "",
) -> PrincipalAttributeKey

Create a principal attribute key.

find_key async

find_key(**kwargs) -> PrincipalAttributeKey | None

Find a single key matching the query. Raises if more than one matches.

get_assignment async

get_assignment(
    *,
    assignment_id: str,
    principal_type: PrincipalType = USER,
) -> PrincipalAttributeValue

Get a single assignment by ID.

get_key async

get_key(*, key_id: str) -> PrincipalAttributeKey

Get a principal attribute key by ID.

get_or_create_enum_values async

get_or_create_enum_values(
    key: str | PrincipalAttributeKey, names: list[str]
) -> list[PrincipalAttributeEnumValue]

Get enum values for a key by name, creating any that don't exist.

Returns the values in the same order as names.

get_or_create_key async

get_or_create_key(
    display_name: str,
    value_type: PrincipalAttributeValueType,
    *,
    description: str = "",
) -> PrincipalAttributeKey

Get a key by display name, creating it if it does not exist.

Note

Display names are not guaranteed unique. If multiple keys share the display name, the first active match is returned.

list_assignments async

list_assignments(
    *,
    key: str | PrincipalAttributeKey | None = None,
    principal: str | None = None,
    principal_type: PrincipalType = USER,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeValue]

List principal attribute assignments.

PARAMETER	DESCRIPTION
key	Filter to assignments of this key. TYPE: str | PrincipalAttributeKey | None DEFAULT: None
principal	Filter to assignments for this principal (user ID, or email for users). TYPE: str | None DEFAULT: None
principal_type	The kind of principal to list assignments for. Defaults to USER. TYPE: PrincipalType DEFAULT: USER
include_archived	If True, include archived assignments. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of assignments to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

list_enum_values async

list_enum_values(
    key: str | PrincipalAttributeKey,
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeEnumValue]

List the enum values defined for a key.

list_keys async

list_keys(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    value_type: PrincipalAttributeValueType | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[PrincipalAttributeKey]

List principal attribute keys with optional filtering.

PARAMETER	DESCRIPTION
name	Exact display name of the key. TYPE: str | None DEFAULT: None
names	Display names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Substring match on the display name. TYPE: str | None DEFAULT: None
name_regex	Regex match on the display name. TYPE: str | Pattern | None DEFAULT: None
value_type	Filter to keys of this value type. TYPE: PrincipalAttributeValueType | None DEFAULT: None
include_archived	If True, include archived keys. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of keys to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

resolve_user_id async

resolve_user_id(email: str) -> str

Resolve a user's email (its user name) to a user ID.

RAISES	DESCRIPTION
ValueError	If no user with that email is found.

resolve_user_ids async

resolve_user_ids(emails: list[str]) -> dict[str, str]

Resolve user emails (their user names) to user IDs.

Returns a mapping of email to user ID for the emails that were found. Emails with no matching user are omitted.

unarchive_assignments async

unarchive_assignments(
    assignments: list[str | PrincipalAttributeValue],
    *,
    principal_type: PrincipalType = USER,
) -> None

Batch unarchive assignments.

unarchive_enum_value async

unarchive_enum_value(
    enum_value: str | PrincipalAttributeEnumValue,
) -> PrincipalAttributeEnumValue

Unarchive an enum value.

unarchive_key async

unarchive_key(
    key: str | PrincipalAttributeKey,
) -> PrincipalAttributeKey

Unarchive a key. Does not restore its cascaded enum values or assignments.

update_key async

update_key(
    key: str | PrincipalAttributeKey,
    *,
    display_name: str | None = None,
    description: str | None = None,
) -> PrincipalAttributeKey

Update a key's display name or description.

ReportsAPI

ReportsAPI(sift_client: SiftClient)

Sync counterpart to ReportsAPIAsync.

High-level API for interacting with reports.

Initialize the ReportsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a report.
cancel	Cancel a report.
create_from_applicable_rules	Create a new report from applicable rules based on a run.
create_from_rule_versions	Create a new report from rule versions.
create_from_rules	Create a new report from rules.
create_from_template	Create a new report from a report template.
find	Find a single report matching the given query. Takes the same arguments as list. If more than one report is found,
get	Get a Report.
list_	List reports with optional filtering.
rerun	Rerun a report.
unarchive	Unarchive a report.
update	Update a report.
wait_until_complete	Wait until the report is complete or the timeout is reached.

archive

archive(*, report: str | Report) -> Report

Archive a report.

cancel

cancel(*, report: str | Report) -> None

Cancel a report.

PARAMETER	DESCRIPTION
report	The Report or report ID to cancel. TYPE: str | Report

create_from_applicable_rules

create_from_applicable_rules(
    *,
    run: Run | str | None = None,
    organization_id: str | None = None,
    name: str | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
) -> Job | None

Create a new report from applicable rules based on a run. If you want to evaluate against assets, use the rules client instead since no report is created in that case.

PARAMETER	DESCRIPTION
run	The run or run ID to associate with the report. TYPE: Run | str | None DEFAULT: None
organization_id	The organization ID. TYPE: str | None DEFAULT: None
name	Optional name for the report. TYPE: str | None DEFAULT: None
start_time	Start of the time range to evaluate rules over. Ignored unless end_time is also set and a run is provided. TYPE: datetime | None DEFAULT: None
end_time	End of the time range to evaluate rules over. Ignored unless start_time is also set and a run is provided. TYPE: datetime | None DEFAULT: None

RETURNS	DESCRIPTION
Job | None	The Job for the pending report, or None if no report was created.

create_from_rule_versions

create_from_rule_versions(
    *,
    name: str,
    run: Run | str | None = None,
    organization_id: str | None = None,
    rule_versions: list[RuleVersion] | list[str],
) -> Job | None

Create a new report from rule versions.

PARAMETER	DESCRIPTION
name	The name of the report. TYPE: str
run	The run or run ID to associate with the report. TYPE: Run | str | None DEFAULT: None
organization_id	The organization ID. TYPE: str | None DEFAULT: None
rule_versions	List of RuleVersions or rule_version IDs to include in the report. TYPE: list[RuleVersion] | list[str]

RETURNS	DESCRIPTION
Job | None	The Job for the pending report, or None if no report was created.

create_from_rules

create_from_rules(
    *,
    name: str,
    run: Run | str | None = None,
    organization_id: str | None = None,
    rules: list[Rule] | list[str],
    start_time: datetime | None = None,
    end_time: datetime | None = None,
) -> Job | None

Create a new report from rules.

PARAMETER	DESCRIPTION
name	The name of the report. TYPE: str
run	The run or run ID to associate with the report. TYPE: Run | str | None DEFAULT: None
organization_id	The organization ID. TYPE: str | None DEFAULT: None
rules	List of rules or rule IDs to include in the report. TYPE: list[Rule] | list[str]
start_time	Start of the time range to evaluate rules over. Ignored unless end_time is also set and a run is provided. TYPE: datetime | None DEFAULT: None
end_time	End of the time range to evaluate rules over. Ignored unless start_time is also set and a run is provided. TYPE: datetime | None DEFAULT: None

RETURNS	DESCRIPTION
Job | None	The Job for the pending report, or None if no report was created.

create_from_template

create_from_template(
    *,
    report_template_id: str,
    run_id: str,
    organization_id: str | None = None,
    name: str | None = None,
) -> Job | None

Create a new report from a report template.

PARAMETER	DESCRIPTION
report_template_id	The ID of the report template to use. TYPE: str
run_id	The run ID to associate with the report. TYPE: str
organization_id	The organization ID. TYPE: str | None DEFAULT: None
name	Optional name for the report. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Job | None	The Job for the pending report, or None if no report was created.

find

find(**kwargs) -> Report | None

Find a single report matching the given query. Takes the same arguments as list. If more than one report is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list. DEFAULT: {}

RETURNS	DESCRIPTION
Report | None	The Report found or None.

get

get(*, report_id: str) -> Report

Get a Report.

PARAMETER	DESCRIPTION
report_id	The ID of the report. TYPE: str

RETURNS	DESCRIPTION
Report	The Report.

list_

list_(
    *,
    name: str | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    names: list[str] | None = None,
    description_contains: str | None = None,
    run: Run | str | None = None,
    organization_id: str | None = None,
    report_ids: list[str] | None = None,
    report_template_id: str | None = None,
    metadata: dict[str, str | float | bool] | None = None,
    tag_names: list[str] | list[Tag] | None = None,
    created_by: str | None = None,
    modified_by: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
) -> list[Report]

List reports with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the report. TYPE: str | None DEFAULT: None
name_contains	Partial name of the report. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter reports by name. TYPE: str | Pattern | None DEFAULT: None
names	List of report names to filter by. TYPE: list[str] | None DEFAULT: None
description_contains	Partial description of the report. TYPE: str | None DEFAULT: None
run	Run/run ID to filter by. TYPE: Run | str | None DEFAULT: None
organization_id	Organization ID to filter by. TYPE: str | None DEFAULT: None
report_ids	List of report IDs to filter by. TYPE: list[str] | None DEFAULT: None
report_template_id	Report template ID to filter by. TYPE: str | None DEFAULT: None
metadata	Metadata to filter by. TYPE: dict[str, str | float | bool] | None DEFAULT: None
tag_names	List of tags or tag names to filter by. TYPE: list[str] | list[Tag] | None DEFAULT: None
created_by	The user ID of the creator of the reports. TYPE: str | None DEFAULT: None
modified_by	The user ID of the last modifier of the reports. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved reports. TYPE: str | None DEFAULT: None
limit	How many reports to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None
include_archived	Whether to include archived reports. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter reports. TYPE: str | None DEFAULT: None
created_after	Filter reports created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter reports created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter reports modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter reports modified before this datetime. TYPE: datetime | None DEFAULT: None

RETURNS	DESCRIPTION
list[Report]	A list of Reports that matches the filter.

rerun

rerun(*, report: str | Report) -> Job

Rerun a report.

PARAMETER	DESCRIPTION
report	The Report or report ID to rerun. TYPE: str | Report

RETURNS	DESCRIPTION
Job	The Job for the new pending report.

unarchive

unarchive(*, report: str | Report) -> Report

Unarchive a report.

update

update(
    report: str | Report, update: ReportUpdate | dict
) -> Report

Update a report.

PARAMETER	DESCRIPTION
report	The Report or report ID to update. TYPE: str | Report
update	The updates to apply. TYPE: ReportUpdate | dict

wait_until_complete

wait_until_complete(
    *,
    report: Report | str | None = None,
    job: Job | str | None = None,
    polling_interval_secs: int = 5,
    timeout_secs: int | None = None,
) -> Report

Wait until the report is complete or the timeout is reached.

Polls the report job status at the given interval until the job is FINISHED, FAILED, or CANCELLED, returning the completed Report.

Either a report or job must be provided. The job must be a rule evaluation job.

PARAMETER	DESCRIPTION
report	The Report or report ID to wait for. TYPE: Report | str | None DEFAULT: None
job	The pending rule evaluation Job or job ID to wait for. TYPE: Job | str | None DEFAULT: None
polling_interval_secs	Seconds between status polls. Defaults to 5s. TYPE: int DEFAULT: 5
timeout_secs	Maximum seconds to wait. If None, polls indefinitely. Defaults to None (indefinite). TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
Report	The Report in the completed state.

RAISES	DESCRIPTION
ValueError	If both or neither report and job are provided, or if job is not a rule evaluation job.

ReportsAPIAsync

ReportsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with reports.

Initialize the ReportsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a report.
cancel	Cancel a report.
create_from_applicable_rules	Create a new report from applicable rules based on a run.
create_from_rule_versions	Create a new report from rule versions.
create_from_rules	Create a new report from rules.
create_from_template	Create a new report from a report template.
find	Find a single report matching the given query. Takes the same arguments as list. If more than one report is found,
get	Get a Report.
list_	List reports with optional filtering.
rerun	Rerun a report.
unarchive	Unarchive a report.
update	Update a report.
wait_until_complete	Wait until the report is complete or the timeout is reached.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive async

archive(*, report: str | Report) -> Report

Archive a report.

cancel async

cancel(*, report: str | Report) -> None

Cancel a report.

PARAMETER	DESCRIPTION
report	The Report or report ID to cancel. TYPE: str | Report

create_from_applicable_rules async

create_from_applicable_rules(
    *,
    run: Run | str | None = None,
    organization_id: str | None = None,
    name: str | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
) -> Job | None

Create a new report from applicable rules based on a run. If you want to evaluate against assets, use the rules client instead since no report is created in that case.

PARAMETER	DESCRIPTION
run	The run or run ID to associate with the report. TYPE: Run | str | None DEFAULT: None
organization_id	The organization ID. TYPE: str | None DEFAULT: None
name	Optional name for the report. TYPE: str | None DEFAULT: None
start_time	Start of the time range to evaluate rules over. Ignored unless end_time is also set and a run is provided. TYPE: datetime | None DEFAULT: None
end_time	End of the time range to evaluate rules over. Ignored unless start_time is also set and a run is provided. TYPE: datetime | None DEFAULT: None

RETURNS	DESCRIPTION
Job | None	The Job for the pending report, or None if no report was created.

create_from_rule_versions async

create_from_rule_versions(
    *,
    name: str,
    run: Run | str | None = None,
    organization_id: str | None = None,
    rule_versions: list[RuleVersion] | list[str],
) -> Job | None

Create a new report from rule versions.

PARAMETER	DESCRIPTION
name	The name of the report. TYPE: str
run	The run or run ID to associate with the report. TYPE: Run | str | None DEFAULT: None
organization_id	The organization ID. TYPE: str | None DEFAULT: None
rule_versions	List of RuleVersions or rule_version IDs to include in the report. TYPE: list[RuleVersion] | list[str]

RETURNS	DESCRIPTION
Job | None	The Job for the pending report, or None if no report was created.

create_from_rules async

create_from_rules(
    *,
    name: str,
    run: Run | str | None = None,
    organization_id: str | None = None,
    rules: list[Rule] | list[str],
    start_time: datetime | None = None,
    end_time: datetime | None = None,
) -> Job | None

Create a new report from rules.

PARAMETER	DESCRIPTION
name	The name of the report. TYPE: str
run	The run or run ID to associate with the report. TYPE: Run | str | None DEFAULT: None
organization_id	The organization ID. TYPE: str | None DEFAULT: None
rules	List of rules or rule IDs to include in the report. TYPE: list[Rule] | list[str]
start_time	Start of the time range to evaluate rules over. Ignored unless end_time is also set and a run is provided. TYPE: datetime | None DEFAULT: None
end_time	End of the time range to evaluate rules over. Ignored unless start_time is also set and a run is provided. TYPE: datetime | None DEFAULT: None

RETURNS	DESCRIPTION
Job | None	The Job for the pending report, or None if no report was created.

create_from_template async

create_from_template(
    *,
    report_template_id: str,
    run_id: str,
    organization_id: str | None = None,
    name: str | None = None,
) -> Job | None

Create a new report from a report template.

PARAMETER	DESCRIPTION
report_template_id	The ID of the report template to use. TYPE: str
run_id	The run ID to associate with the report. TYPE: str
organization_id	The organization ID. TYPE: str | None DEFAULT: None
name	Optional name for the report. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Job | None	The Job for the pending report, or None if no report was created.

find async

find(**kwargs) -> Report | None

Find a single report matching the given query. Takes the same arguments as list. If more than one report is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list. DEFAULT: {}

RETURNS	DESCRIPTION
Report | None	The Report found or None.

get async

get(*, report_id: str) -> Report

Get a Report.

PARAMETER	DESCRIPTION
report_id	The ID of the report. TYPE: str

RETURNS	DESCRIPTION
Report	The Report.

list_ async

list_(
    *,
    name: str | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    names: list[str] | None = None,
    description_contains: str | None = None,
    run: Run | str | None = None,
    organization_id: str | None = None,
    report_ids: list[str] | None = None,
    report_template_id: str | None = None,
    metadata: dict[str, str | float | bool] | None = None,
    tag_names: list[str] | list[Tag] | None = None,
    created_by: str | None = None,
    modified_by: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
) -> list[Report]

List reports with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the report. TYPE: str | None DEFAULT: None
name_contains	Partial name of the report. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter reports by name. TYPE: str | Pattern | None DEFAULT: None
names	List of report names to filter by. TYPE: list[str] | None DEFAULT: None
description_contains	Partial description of the report. TYPE: str | None DEFAULT: None
run	Run/run ID to filter by. TYPE: Run | str | None DEFAULT: None
organization_id	Organization ID to filter by. TYPE: str | None DEFAULT: None
report_ids	List of report IDs to filter by. TYPE: list[str] | None DEFAULT: None
report_template_id	Report template ID to filter by. TYPE: str | None DEFAULT: None
metadata	Metadata to filter by. TYPE: dict[str, str | float | bool] | None DEFAULT: None
tag_names	List of tags or tag names to filter by. TYPE: list[str] | list[Tag] | None DEFAULT: None
created_by	The user ID of the creator of the reports. TYPE: str | None DEFAULT: None
modified_by	The user ID of the last modifier of the reports. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved reports. TYPE: str | None DEFAULT: None
limit	How many reports to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None
include_archived	Whether to include archived reports. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter reports. TYPE: str | None DEFAULT: None
created_after	Filter reports created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter reports created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter reports modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter reports modified before this datetime. TYPE: datetime | None DEFAULT: None

RETURNS	DESCRIPTION
list[Report]	A list of Reports that matches the filter.

rerun async

rerun(*, report: str | Report) -> Job

Rerun a report.

PARAMETER	DESCRIPTION
report	The Report or report ID to rerun. TYPE: str | Report

RETURNS	DESCRIPTION
Job	The Job for the new pending report.

unarchive async

unarchive(*, report: str | Report) -> Report

Unarchive a report.

update async

update(
    report: str | Report, update: ReportUpdate | dict
) -> Report

Update a report.

PARAMETER	DESCRIPTION
report	The Report or report ID to update. TYPE: str | Report
update	The updates to apply. TYPE: ReportUpdate | dict

wait_until_complete async

wait_until_complete(
    *,
    report: Report | str | None = None,
    job: Job | str | None = None,
    polling_interval_secs: int = 5,
    timeout_secs: int | None = None,
) -> Report

Wait until the report is complete or the timeout is reached.

Polls the report job status at the given interval until the job is FINISHED, FAILED, or CANCELLED, returning the completed Report.

Either a report or job must be provided. The job must be a rule evaluation job.

PARAMETER	DESCRIPTION
report	The Report or report ID to wait for. TYPE: Report | str | None DEFAULT: None
job	The pending rule evaluation Job or job ID to wait for. TYPE: Job | str | None DEFAULT: None
polling_interval_secs	Seconds between status polls. Defaults to 5s. TYPE: int DEFAULT: 5
timeout_secs	Maximum seconds to wait. If None, polls indefinitely. Defaults to None (indefinite). TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
Report	The Report in the completed state.

RAISES	DESCRIPTION
ValueError	If both or neither report and job are provided, or if job is not a rule evaluation job.

ResourceAttributesAPI

ResourceAttributesAPI(sift_client: SiftClient)

Sync counterpart to ResourceAttributesAPIAsync.

High-level API for resource attributes (ABAC).

Resource attributes assign attribute keys to Sift entities (assets, channels, runs). The attribute key is the entry point: enum values and assignments are managed through methods on a key, or through the corresponding methods here.

Initialize the ResourceAttributesAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive_assignments	Batch archive assignments.
archive_enum_value	Archive an enum value, migrating existing assignments to a replacement.
archive_key	Archive a key. Cascades to its enum values and assignments.
assign	Assign a value to entities for a key.
check_key_archive_impact	Return the number of active assignments archiving this key would affect.
create_enum_value	Create a single enum value for a key.
create_key	Create a resource attribute key.
find_key	Find a single key matching the query. Raises if more than one matches.
get_assignment	Get a single assignment by ID.
get_key	Get a resource attribute key by ID.
get_or_create_enum_values	Get enum values for a key by name, creating any that don't exist.
get_or_create_key	Get a key by display name, creating it if it does not exist.
list_assignments	List resource attribute assignments.
list_enum_values	List the enum values defined for a key.
list_keys	List resource attribute keys with optional filtering.
unarchive_assignments	Batch unarchive assignments.
unarchive_enum_value	Unarchive an enum value.
unarchive_key	Unarchive a key. Does not restore its cascaded enum values or assignments.
update_key	Update a key's display name or description.

archive_assignments

archive_assignments(
    assignments: list[str | ResourceAttribute],
) -> None

Batch archive assignments.

archive_enum_value

archive_enum_value(
    enum_value: str | ResourceAttributeEnumValue,
    *,
    replacement: str
    | ResourceAttributeEnumValue
    | None = None,
) -> int

Archive an enum value, migrating existing assignments to a replacement.

Returns the number of assignments migrated.

archive_key

archive_key(
    key: str | ResourceAttributeKey,
) -> ResourceAttributeKey

Archive a key. Cascades to its enum values and assignments.

assign

assign(
    key: ResourceAttributeKey,
    entities: list[
        ResourceAttributeEntity | Asset | Channel | Run
    ],
    *,
    value: Any,
) -> list[ResourceAttribute]

Assign a value to entities for a key.

PARAMETER	DESCRIPTION
key	The key to assign. Its key_type determines how value is interpreted. TYPE: ResourceAttributeKey
entities	Entities to assign to (ResourceAttributeEntity, Asset, Channel, or Run). TYPE: list[ResourceAttributeEntity | Asset | Channel | Run]
value	For SET_OF_ENUM, a list of enum values (or their IDs) that becomes the full set on each entity; for ENUM, a single enum value; for BOOLEAN, a bool; for NUMBER, an int. TYPE: Any

RETURNS	DESCRIPTION
list[ResourceAttribute]	The created assignments.

check_key_archive_impact

check_key_archive_impact(
    key: str | ResourceAttributeKey,
) -> int

Return the number of active assignments archiving this key would affect.

create_enum_value

create_enum_value(
    key: str | ResourceAttributeKey,
    display_name: str,
    *,
    description: str = "",
) -> ResourceAttributeEnumValue

Create a single enum value for a key.

create_key

create_key(
    display_name: str,
    key_type: ResourceAttributeKeyType,
    *,
    description: str = "",
) -> ResourceAttributeKey

Create a resource attribute key.

PARAMETER	DESCRIPTION
display_name	The human-readable name of the key. TYPE: str
key_type	The value type of the key. TYPE: ResourceAttributeKeyType
description	Optional description. TYPE: str DEFAULT: ''

RETURNS	DESCRIPTION
ResourceAttributeKey	The created key.

find_key

find_key(**kwargs) -> ResourceAttributeKey | None

Find a single key matching the query. Raises if more than one matches.

get_assignment

get_assignment(*, assignment_id: str) -> ResourceAttribute

Get a single assignment by ID.

get_key

get_key(*, key_id: str) -> ResourceAttributeKey

Get a resource attribute key by ID.

get_or_create_enum_values

get_or_create_enum_values(
    key: str | ResourceAttributeKey, names: list[str]
) -> list[ResourceAttributeEnumValue]

Get enum values for a key by name, creating any that don't exist.

Returns the values in the same order as names.

get_or_create_key

get_or_create_key(
    display_name: str,
    key_type: ResourceAttributeKeyType,
    *,
    description: str = "",
) -> ResourceAttributeKey

Get a key by display name, creating it if it does not exist.

Note

Display names are not guaranteed unique. If multiple keys share the display name, the first active match is returned.

list_assignments

list_assignments(
    *,
    key: str | ResourceAttributeKey | None = None,
    entity: ResourceAttributeEntity
    | Asset
    | Channel
    | Run
    | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[ResourceAttribute]

List resource attribute assignments.

PARAMETER	DESCRIPTION
key	Filter to assignments of this key. TYPE: str | ResourceAttributeKey | None DEFAULT: None
entity	Filter to assignments on this entity. When set, other filters are ignored. TYPE: ResourceAttributeEntity | Asset | Channel | Run | None DEFAULT: None
include_archived	If True, include archived assignments. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of assignments to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

list_enum_values

list_enum_values(
    key: str | ResourceAttributeKey,
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[ResourceAttributeEnumValue]

List the enum values defined for a key.

list_keys

list_keys(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    key_type: ResourceAttributeKeyType | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[ResourceAttributeKey]

List resource attribute keys with optional filtering.

PARAMETER	DESCRIPTION
name	Exact display name of the key. TYPE: str | None DEFAULT: None
names	Display names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Substring match on the display name. TYPE: str | None DEFAULT: None
name_regex	Regex match on the display name. TYPE: str | Pattern | None DEFAULT: None
key_type	Filter to keys of this value type. TYPE: ResourceAttributeKeyType | None DEFAULT: None
include_archived	If True, include archived keys. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of keys to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[ResourceAttributeKey]	The matching keys.

unarchive_assignments

unarchive_assignments(
    assignments: list[str | ResourceAttribute],
) -> None

Batch unarchive assignments.

unarchive_enum_value

unarchive_enum_value(
    enum_value: str | ResourceAttributeEnumValue,
) -> ResourceAttributeEnumValue

Unarchive an enum value.

unarchive_key

unarchive_key(
    key: str | ResourceAttributeKey,
) -> ResourceAttributeKey

Unarchive a key. Does not restore its cascaded enum values or assignments.

update_key

update_key(
    key: str | ResourceAttributeKey,
    *,
    display_name: str | None = None,
    description: str | None = None,
) -> ResourceAttributeKey

Update a key's display name or description.

ResourceAttributesAPIAsync

ResourceAttributesAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for resource attributes (ABAC).

Resource attributes assign attribute keys to Sift entities (assets, channels, runs). The attribute key is the entry point: enum values and assignments are managed through methods on a key, or through the corresponding methods here.

Initialize the ResourceAttributesAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive_assignments	Batch archive assignments.
archive_enum_value	Archive an enum value, migrating existing assignments to a replacement.
archive_key	Archive a key. Cascades to its enum values and assignments.
assign	Assign a value to entities for a key.
check_key_archive_impact	Return the number of active assignments archiving this key would affect.
create_enum_value	Create a single enum value for a key.
create_key	Create a resource attribute key.
find_key	Find a single key matching the query. Raises if more than one matches.
get_assignment	Get a single assignment by ID.
get_key	Get a resource attribute key by ID.
get_or_create_enum_values	Get enum values for a key by name, creating any that don't exist.
get_or_create_key	Get a key by display name, creating it if it does not exist.
list_assignments	List resource attribute assignments.
list_enum_values	List the enum values defined for a key.
list_keys	List resource attribute keys with optional filtering.
unarchive_assignments	Batch unarchive assignments.
unarchive_enum_value	Unarchive an enum value.
unarchive_key	Unarchive a key. Does not restore its cascaded enum values or assignments.
update_key	Update a key's display name or description.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive_assignments async

archive_assignments(
    assignments: list[str | ResourceAttribute],
) -> None

Batch archive assignments.

archive_enum_value async

archive_enum_value(
    enum_value: str | ResourceAttributeEnumValue,
    *,
    replacement: str
    | ResourceAttributeEnumValue
    | None = None,
) -> int

Archive an enum value, migrating existing assignments to a replacement.

Returns the number of assignments migrated.

archive_key async

archive_key(
    key: str | ResourceAttributeKey,
) -> ResourceAttributeKey

Archive a key. Cascades to its enum values and assignments.

assign async

assign(
    key: ResourceAttributeKey,
    entities: list[
        ResourceAttributeEntity | Asset | Channel | Run
    ],
    *,
    value: Any,
) -> list[ResourceAttribute]

Assign a value to entities for a key.

PARAMETER	DESCRIPTION
key	The key to assign. Its key_type determines how value is interpreted. TYPE: ResourceAttributeKey
entities	Entities to assign to (ResourceAttributeEntity, Asset, Channel, or Run). TYPE: list[ResourceAttributeEntity | Asset | Channel | Run]
value	For SET_OF_ENUM, a list of enum values (or their IDs) that becomes the full set on each entity; for ENUM, a single enum value; for BOOLEAN, a bool; for NUMBER, an int. TYPE: Any

RETURNS	DESCRIPTION
list[ResourceAttribute]	The created assignments.

check_key_archive_impact async

check_key_archive_impact(
    key: str | ResourceAttributeKey,
) -> int

Return the number of active assignments archiving this key would affect.

create_enum_value async

create_enum_value(
    key: str | ResourceAttributeKey,
    display_name: str,
    *,
    description: str = "",
) -> ResourceAttributeEnumValue

Create a single enum value for a key.

create_key async

create_key(
    display_name: str,
    key_type: ResourceAttributeKeyType,
    *,
    description: str = "",
) -> ResourceAttributeKey

Create a resource attribute key.

PARAMETER	DESCRIPTION
display_name	The human-readable name of the key. TYPE: str
key_type	The value type of the key. TYPE: ResourceAttributeKeyType
description	Optional description. TYPE: str DEFAULT: ''

RETURNS	DESCRIPTION
ResourceAttributeKey	The created key.

find_key async

find_key(**kwargs) -> ResourceAttributeKey | None

Find a single key matching the query. Raises if more than one matches.

get_assignment async

get_assignment(*, assignment_id: str) -> ResourceAttribute

Get a single assignment by ID.

get_key async

get_key(*, key_id: str) -> ResourceAttributeKey

Get a resource attribute key by ID.

get_or_create_enum_values async

get_or_create_enum_values(
    key: str | ResourceAttributeKey, names: list[str]
) -> list[ResourceAttributeEnumValue]

Get enum values for a key by name, creating any that don't exist.

Returns the values in the same order as names.

get_or_create_key async

get_or_create_key(
    display_name: str,
    key_type: ResourceAttributeKeyType,
    *,
    description: str = "",
) -> ResourceAttributeKey

Get a key by display name, creating it if it does not exist.

Note

Display names are not guaranteed unique. If multiple keys share the display name, the first active match is returned.

list_assignments async

list_assignments(
    *,
    key: str | ResourceAttributeKey | None = None,
    entity: ResourceAttributeEntity
    | Asset
    | Channel
    | Run
    | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[ResourceAttribute]

List resource attribute assignments.

PARAMETER	DESCRIPTION
key	Filter to assignments of this key. TYPE: str | ResourceAttributeKey | None DEFAULT: None
entity	Filter to assignments on this entity. When set, other filters are ignored. TYPE: ResourceAttributeEntity | Asset | Channel | Run | None DEFAULT: None
include_archived	If True, include archived assignments. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of assignments to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

list_enum_values async

list_enum_values(
    key: str | ResourceAttributeKey,
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[ResourceAttributeEnumValue]

List the enum values defined for a key.

list_keys async

list_keys(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    key_type: ResourceAttributeKeyType | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[ResourceAttributeKey]

List resource attribute keys with optional filtering.

PARAMETER	DESCRIPTION
name	Exact display name of the key. TYPE: str | None DEFAULT: None
names	Display names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Substring match on the display name. TYPE: str | None DEFAULT: None
name_regex	Regex match on the display name. TYPE: str | Pattern | None DEFAULT: None
key_type	Filter to keys of this value type. TYPE: ResourceAttributeKeyType | None DEFAULT: None
include_archived	If True, include archived keys. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query. TYPE: str | None DEFAULT: None
order_by	Field and direction to order by. TYPE: str | None DEFAULT: None
limit	Maximum number of keys to return. TYPE: int | None DEFAULT: None
page_size	Results to fetch per request. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[ResourceAttributeKey]	The matching keys.

unarchive_assignments async

unarchive_assignments(
    assignments: list[str | ResourceAttribute],
) -> None

Batch unarchive assignments.

unarchive_enum_value async

unarchive_enum_value(
    enum_value: str | ResourceAttributeEnumValue,
) -> ResourceAttributeEnumValue

Unarchive an enum value.

unarchive_key async

unarchive_key(
    key: str | ResourceAttributeKey,
) -> ResourceAttributeKey

Unarchive a key. Does not restore its cascaded enum values or assignments.

update_key async

update_key(
    key: str | ResourceAttributeKey,
    *,
    display_name: str | None = None,
    description: str | None = None,
) -> ResourceAttributeKey

Update a key's display name or description.

RulesAPI

RulesAPI(sift_client: SiftClient)

Sync counterpart to RulesAPIAsync.

High-level API for interacting with rules.

This class provides a Pythonic, notebook-friendly interface for interacting with the RulesAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Rule class from the low-level wrapper, which is a user-friendly representation of a rule using standard Python data structures and types.

Initialize the RulesAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a rule.
batch_get_rule_versions	Get multiple rules at specific versions by rule version IDs.
batch_update_or_create_rules	Batch update or create multiple rules.
create	Create a new rule.
find	Find a single rule matching the given query. Takes the same arguments as list. If more than one rule is found,
get	Get a Rule.
get_rule_version	Get a rule at a specific version by rule version ID.
list_	List rules with optional filtering.
list_rule_versions	List versions of a rule with optional filtering.
unarchive	Unarchive a rule.
update	Update a Rule.

archive

archive(rule: str | Rule) -> Rule

Archive a rule.

PARAMETER	DESCRIPTION
rule	The id or Rule object of the rule to archive. TYPE: str | Rule

RETURNS	DESCRIPTION
Rule	The archived Rule.

batch_get_rule_versions

batch_get_rule_versions(
    rule_versions: list[RuleVersion] | list[str],
) -> list[Rule]

Get multiple rules at specific versions by rule version IDs.

PARAMETER	DESCRIPTION
rule_versions	List of RuleVersion instances or rule version IDs. TYPE: list[RuleVersion] | list[str]

RETURNS	DESCRIPTION
list[Rule]	List of Rules at those versions.

batch_update_or_create_rules

batch_update_or_create_rules(
    rules: Sequence[RuleCreate | RuleUpdate],
    *,
    override_expression_validation: bool = False,
) -> list[Rule]

Batch update or create multiple rules.

PARAMETER	DESCRIPTION
rules	List of rule creates or updates to apply. RuleUpdate objects must have resource_id set. TYPE: Sequence[RuleCreate | RuleUpdate]
override_expression_validation	When true, the rules will be created even if the expressions are invalid. TYPE: bool DEFAULT: False

WARNS	DESCRIPTION
SiftWarning	If not all rules are created or updated.

RETURNS	DESCRIPTION
list[Rule]	List of updated or created Rules.

RAISES	DESCRIPTION
ValueError	If the update/create fails or if not all rules were updated/created.

create

create(
    create: RuleCreate | dict | Sequence[RuleCreate | dict],
    *,
    override_expression_validation: bool = True,
) -> Rule | list[Rule]

Create a new rule.

PARAMETER	DESCRIPTION
create	A RuleCreate object, a dictionary with configuration for the new rule, or a list of the previously mentioned objects. TYPE: RuleCreate | dict | Sequence[RuleCreate | dict]
override_expression_validation	When true, the rule will be created even if the expression is invalid. TYPE: bool DEFAULT: True

WARNS	DESCRIPTION
SiftWarning	If not all rules are created.

RETURNS	DESCRIPTION
Rule | list[Rule]	The created Rule (if a single dictionary or RuleCreate was provided) otherwise a list of the created rules.

find

find(**kwargs) -> Rule | None

Find a single rule matching the given query. Takes the same arguments as list. If more than one rule is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list. DEFAULT: {}

RETURNS	DESCRIPTION
Rule | None	The Rule found or None.

get

get(
    *,
    rule_id: str | None = None,
    client_key: str | None = None,
) -> Rule

Get a Rule.

PARAMETER	DESCRIPTION
rule_id	The ID of the rule. TYPE: str | None DEFAULT: None
client_key	The client key of the rule. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Rule	The Rule.

get_rule_version

get_rule_version(rule_version: RuleVersion | str) -> Rule

Get a rule at a specific version by rule version ID.

PARAMETER	DESCRIPTION
rule_version	The RuleVersion instance or rule version ID. TYPE: RuleVersion | str

RETURNS	DESCRIPTION
Rule	The Rule at that version.

list_

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    rule_ids: list[str] | None = None,
    client_keys: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    metadata: list[Any] | None = None,
    assets: list[str] | list[Asset] | None = None,
    asset_tags: list[str | Tag] | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Rule]

List rules with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the rule. TYPE: str | None DEFAULT: None
names	List of rule names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the rule. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter rules by name. TYPE: str | Pattern | None DEFAULT: None
client_keys	Client keys of rules to filter to. TYPE: list[str] | None DEFAULT: None
rule_ids	IDs of rules to filter to. TYPE: list[str] | None DEFAULT: None
created_after	Rules created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Rules created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Rules modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Rules modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter rules created by this User or user ID. TYPE: Any | str | None DEFAULT: None
modified_by	Filter rules last modified by this User or user ID. TYPE: Any | str | None DEFAULT: None
metadata	Filter rules by metadata criteria. TYPE: list[Any] | None DEFAULT: None
assets	Filter rules associated with any of these Assets. TYPE: list[str] | list[Asset] | None DEFAULT: None
asset_tags	Filter rules associated with any Assets that have these Tag IDs. TYPE: list[str | Tag] | None DEFAULT: None
description_contains	Partial description of the rule. TYPE: str | None DEFAULT: None
include_archived	If True, include archived rules in results. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter rules. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of rules to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, defaults to limit. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Rule]	A list of Rules that matches the filter.

list_rule_versions

list_rule_versions(
    rule: Rule | str,
    *,
    user_notes_contains: str | None = None,
    change_message_contains: str | None = None,
    rule_version_ids: list[str] | None = None,
    filter_query: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[RuleVersion]

List versions of a rule with optional filtering.

PARAMETER	DESCRIPTION
rule	The Rule instance or rule ID. TYPE: Rule | str
user_notes_contains	Filter by user notes (notes for a given version) containing this string. TYPE: str | None DEFAULT: None
change_message_contains	Filter by change messages containing this string. TYPE: str | None DEFAULT: None
rule_version_ids	Limit to these rule version IDs. TYPE: list[str] | None DEFAULT: None
filter_query	Raw CEL filter (fields: rule_version_id, user_notes, change_message). TYPE: str | None DEFAULT: None
limit	Maximum number of versions to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, defaults to limit. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[RuleVersion]	A list of RuleVersion objects matching the filters, ordered by newest versions first.

unarchive

unarchive(rule: str | Rule) -> Rule

Unarchive a rule.

PARAMETER	DESCRIPTION
rule	The id or Rule object of the rule to unarchive. TYPE: str | Rule

RETURNS	DESCRIPTION
Rule	The unarchived Rule.

update

update(
    rule: Rule | str,
    update: RuleUpdate | dict,
    *,
    version_notes: str | None = None,
) -> Rule

Update a Rule.

PARAMETER	DESCRIPTION
rule	The Rule or rule ID to update. TYPE: Rule | str
update	Updates to apply to the Rule. TYPE: RuleUpdate | dict
version_notes	Notes to include in the rule version. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Rule	The updated Rule.

RulesAPIAsync

RulesAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with rules.

This class provides a Pythonic, notebook-friendly interface for interacting with the RulesAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Rule class from the low-level wrapper, which is a user-friendly representation of a rule using standard Python data structures and types.

Initialize the RulesAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a rule.
batch_get_rule_versions	Get multiple rules at specific versions by rule version IDs.
batch_update_or_create_rules	Batch update or create multiple rules.
create	Create a new rule.
find	Find a single rule matching the given query. Takes the same arguments as list. If more than one rule is found,
get	Get a Rule.
get_rule_version	Get a rule at a specific version by rule version ID.
list_	List rules with optional filtering.
list_rule_versions	List versions of a rule with optional filtering.
unarchive	Unarchive a rule.
update	Update a Rule.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive async

archive(rule: str | Rule) -> Rule

Archive a rule.

PARAMETER	DESCRIPTION
rule	The id or Rule object of the rule to archive. TYPE: str | Rule

RETURNS	DESCRIPTION
Rule	The archived Rule.

batch_get_rule_versions async

batch_get_rule_versions(
    rule_versions: list[RuleVersion] | list[str],
) -> list[Rule]

Get multiple rules at specific versions by rule version IDs.

PARAMETER	DESCRIPTION
rule_versions	List of RuleVersion instances or rule version IDs. TYPE: list[RuleVersion] | list[str]

RETURNS	DESCRIPTION
list[Rule]	List of Rules at those versions.

batch_update_or_create_rules async

batch_update_or_create_rules(
    rules: Sequence[RuleCreate | RuleUpdate],
    *,
    override_expression_validation: bool = False,
) -> list[Rule]

Batch update or create multiple rules.

PARAMETER	DESCRIPTION
rules	List of rule creates or updates to apply. RuleUpdate objects must have resource_id set. TYPE: Sequence[RuleCreate | RuleUpdate]
override_expression_validation	When true, the rules will be created even if the expressions are invalid. TYPE: bool DEFAULT: False

WARNS	DESCRIPTION
SiftWarning	If not all rules are created or updated.

RETURNS	DESCRIPTION
list[Rule]	List of updated or created Rules.

RAISES	DESCRIPTION
ValueError	If the update/create fails or if not all rules were updated/created.

create async

create(
    create: RuleCreate | dict | Sequence[RuleCreate | dict],
    *,
    override_expression_validation: bool = True,
) -> Rule | list[Rule]

Create a new rule.

PARAMETER	DESCRIPTION
create	A RuleCreate object, a dictionary with configuration for the new rule, or a list of the previously mentioned objects. TYPE: RuleCreate | dict | Sequence[RuleCreate | dict]
override_expression_validation	When true, the rule will be created even if the expression is invalid. TYPE: bool DEFAULT: True

WARNS	DESCRIPTION
SiftWarning	If not all rules are created.

RETURNS	DESCRIPTION
Rule | list[Rule]	The created Rule (if a single dictionary or RuleCreate was provided) otherwise a list of the created rules.

find async

find(**kwargs) -> Rule | None

Find a single rule matching the given query. Takes the same arguments as list. If more than one rule is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list. DEFAULT: {}

RETURNS	DESCRIPTION
Rule | None	The Rule found or None.

get async

get(
    *,
    rule_id: str | None = None,
    client_key: str | None = None,
) -> Rule

Get a Rule.

PARAMETER	DESCRIPTION
rule_id	The ID of the rule. TYPE: str | None DEFAULT: None
client_key	The client key of the rule. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Rule	The Rule.

get_rule_version async

get_rule_version(rule_version: RuleVersion | str) -> Rule

Get a rule at a specific version by rule version ID.

PARAMETER	DESCRIPTION
rule_version	The RuleVersion instance or rule version ID. TYPE: RuleVersion | str

RETURNS	DESCRIPTION
Rule	The Rule at that version.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    rule_ids: list[str] | None = None,
    client_keys: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    metadata: list[Any] | None = None,
    assets: list[str] | list[Asset] | None = None,
    asset_tags: list[str | Tag] | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Rule]

List rules with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the rule. TYPE: str | None DEFAULT: None
names	List of rule names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the rule. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter rules by name. TYPE: str | Pattern | None DEFAULT: None
client_keys	Client keys of rules to filter to. TYPE: list[str] | None DEFAULT: None
rule_ids	IDs of rules to filter to. TYPE: list[str] | None DEFAULT: None
created_after	Rules created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Rules created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Rules modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Rules modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter rules created by this User or user ID. TYPE: Any | str | None DEFAULT: None
modified_by	Filter rules last modified by this User or user ID. TYPE: Any | str | None DEFAULT: None
metadata	Filter rules by metadata criteria. TYPE: list[Any] | None DEFAULT: None
assets	Filter rules associated with any of these Assets. TYPE: list[str] | list[Asset] | None DEFAULT: None
asset_tags	Filter rules associated with any Assets that have these Tag IDs. TYPE: list[str | Tag] | None DEFAULT: None
description_contains	Partial description of the rule. TYPE: str | None DEFAULT: None
include_archived	If True, include archived rules in results. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter rules. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of rules to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, defaults to limit. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Rule]	A list of Rules that matches the filter.

list_rule_versions async

list_rule_versions(
    rule: Rule | str,
    *,
    user_notes_contains: str | None = None,
    change_message_contains: str | None = None,
    rule_version_ids: list[str] | None = None,
    filter_query: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[RuleVersion]

List versions of a rule with optional filtering.

PARAMETER	DESCRIPTION
rule	The Rule instance or rule ID. TYPE: Rule | str
user_notes_contains	Filter by user notes (notes for a given version) containing this string. TYPE: str | None DEFAULT: None
change_message_contains	Filter by change messages containing this string. TYPE: str | None DEFAULT: None
rule_version_ids	Limit to these rule version IDs. TYPE: list[str] | None DEFAULT: None
filter_query	Raw CEL filter (fields: rule_version_id, user_notes, change_message). TYPE: str | None DEFAULT: None
limit	Maximum number of versions to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, defaults to limit. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[RuleVersion]	A list of RuleVersion objects matching the filters, ordered by newest versions first.

unarchive async

unarchive(rule: str | Rule) -> Rule

Unarchive a rule.

PARAMETER	DESCRIPTION
rule	The id or Rule object of the rule to unarchive. TYPE: str | Rule

RETURNS	DESCRIPTION
Rule	The unarchived Rule.

update async

update(
    rule: Rule | str,
    update: RuleUpdate | dict,
    *,
    version_notes: str | None = None,
) -> Rule

Update a Rule.

PARAMETER	DESCRIPTION
rule	The Rule or rule ID to update. TYPE: Rule | str
update	Updates to apply to the Rule. TYPE: RuleUpdate | dict
version_notes	Notes to include in the rule version. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Rule	The updated Rule.

RunsAPI

RunsAPI(sift_client: SiftClient)

Sync counterpart to RunsAPIAsync.

High-level API for interacting with runs.

This class provides a Pythonic, notebook-friendly interface for interacting with the RunsAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Run class from the low-level wrapper, which is a user-friendly representation of a run using standard Python data structures and types.

Initialize the RunsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a run.
create	Create a new run.
find	Find a single run matching the given query. Takes the same arguments as list_. If more than one run is found,
get	Get a Run.
list_	List runs with optional filtering.
stop	Stop a run by setting its stop time to the current time.
unarchive	Unarchive a run.
update	Update a Run.

archive

archive(run: str | Run) -> Run

Archive a run.

PARAMETER	DESCRIPTION
run	The Run or run ID to archive. TYPE: str | Run

create

create(
    create: RunCreate | dict,
    assets: list[str | Asset] | None = None,
    associate_new_data: bool = False,
) -> Run

Create a new run.

The behavior depends on the arguments:

• No assets: a standard run. Assets are associated later, automatically, when the run is used in their ingestion configs, so asset info is not needed up front.
• assets, associate_new_data=False (default): an adhoc run over the assets' existing data within the run's time period. Nothing is imported.
• assets, associate_new_data=True: a standard run that also captures data ingested later. Data is associated when it lands in one of the assets within the run's time period, even if its timestamp is in the past.

PARAMETER	DESCRIPTION
create	The run definition. For an adhoc run, set start_time and stop_time to bound the window. TYPE: RunCreate | dict
assets	Assets to associate with the run; required when associate_new_data is True. Asset objects work in either mode. A bare string is read as an asset ID for an adhoc run, and as an asset name when associate_new_data is True. TYPE: list[str | Asset] | None DEFAULT: None
associate_new_data	If True, associate data ingested after the run is created that falls within its time period. Requires assets. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Run	The created Run.

find

find(**kwargs) -> Run | None

Find a single run matching the given query. Takes the same arguments as list_. If more than one run is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
Run | None	The Run found or None.

get

get(
    *,
    run_id: str | None = None,
    client_key: str | None = None,
) -> Run

Get a Run.

PARAMETER	DESCRIPTION
run_id	The ID of the run. TYPE: str | None DEFAULT: None
client_key	The client key of the run. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Run	The Run.

list_

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    run_ids: list[str] | None = None,
    client_keys: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    tags: list[str | Tag] | None = None,
    metadata: list[Any] | None = None,
    assets: list[Asset] | list[str] | None = None,
    asset_tags: list[str | Tag] | None = None,
    duration_less_than: timedelta | None = None,
    duration_greater_than: timedelta | None = None,
    start_time_after: datetime | None = None,
    start_time_before: datetime | None = None,
    stop_time_after: datetime | None = None,
    stop_time_before: datetime | None = None,
    is_stopped: bool | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Run]

List runs with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the run. TYPE: str | None DEFAULT: None
names	List of run names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the run. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter runs by name. TYPE: str | Pattern | None DEFAULT: None
run_ids	Filter to runs with any of these IDs. TYPE: list[str] | None DEFAULT: None
client_keys	Filter to runs with any of these client keys. TYPE: list[str] | None DEFAULT: None
created_after	Filter runs created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter runs created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter runs modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter runs modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter runs created by this User or user ID. TYPE: Any | str | None DEFAULT: None
modified_by	Filter runs last modified by this User or user ID. TYPE: Any | str | None DEFAULT: None
tags	Filter runs with any of these Tags IDs. TYPE: list[str | Tag] | None DEFAULT: None
metadata	Filter runs by metadata criteria. TYPE: list[Any] | None DEFAULT: None
assets	Filter runs associated with any of these Assets or asset IDs. TYPE: list[Asset] | list[str] | None DEFAULT: None
asset_tags	Filter runs associated with any Assets that have these Tag IDs. TYPE: list[str | Tag] | None DEFAULT: None
duration_less_than	Filter runs with duration less than this time. TYPE: timedelta | None DEFAULT: None
duration_greater_than	Filter runs with duration greater than this time. TYPE: timedelta | None DEFAULT: None
start_time_after	Filter runs that started after this datetime. TYPE: datetime | None DEFAULT: None
start_time_before	Filter runs that started before this datetime. TYPE: datetime | None DEFAULT: None
stop_time_after	Filter runs that stopped after this datetime. TYPE: datetime | None DEFAULT: None
stop_time_before	Filter runs that stopped before this datetime. TYPE: datetime | None DEFAULT: None
is_stopped	Whether the run is stopped. TYPE: bool | None DEFAULT: None
description_contains	Partial description of the run. TYPE: str | None DEFAULT: None
include_archived	If True, include archived runs in results. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter runs. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of runs to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Run]	A list of Run objects that match the filter criteria.

stop

stop(run: str | Run) -> Run

Stop a run by setting its stop time to the current time.

PARAMETER	DESCRIPTION
run	The Run or run ID to stop. TYPE: str | Run

unarchive

unarchive(run: str | Run) -> Run

Unarchive a run.

PARAMETER	DESCRIPTION
run	The Run or run ID to unarchive. TYPE: str | Run

update

update(run: str | Run, update: RunUpdate | dict) -> Run

Update a Run.

PARAMETER	DESCRIPTION
run	The Run or run ID to update. TYPE: str | Run
update	Updates to apply to the Run. TYPE: RunUpdate | dict

RETURNS	DESCRIPTION
Run	The updated Run.

RunsAPIAsync

RunsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with runs.

This class provides a Pythonic, notebook-friendly interface for interacting with the RunsAPI. It handles automatic handling of gRPC services, seamless type conversion, and clear error handling.

All methods in this class use the Run class from the low-level wrapper, which is a user-friendly representation of a run using standard Python data structures and types.

Initialize the RunsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a run.
create	Create a new run.
find	Find a single run matching the given query. Takes the same arguments as list_. If more than one run is found,
get	Get a Run.
list_	List runs with optional filtering.
stop	Stop a run by setting its stop time to the current time.
unarchive	Unarchive a run.
update	Update a Run.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive async

archive(run: str | Run) -> Run

Archive a run.

PARAMETER	DESCRIPTION
run	The Run or run ID to archive. TYPE: str | Run

create async

create(
    create: RunCreate | dict,
    assets: list[str | Asset] | None = None,
    associate_new_data: bool = False,
) -> Run

Create a new run.

The behavior depends on the arguments:

• No assets: a standard run. Assets are associated later, automatically, when the run is used in their ingestion configs, so asset info is not needed up front.
• assets, associate_new_data=False (default): an adhoc run over the assets' existing data within the run's time period. Nothing is imported.
• assets, associate_new_data=True: a standard run that also captures data ingested later. Data is associated when it lands in one of the assets within the run's time period, even if its timestamp is in the past.

PARAMETER	DESCRIPTION
create	The run definition. For an adhoc run, set start_time and stop_time to bound the window. TYPE: RunCreate | dict
assets	Assets to associate with the run; required when associate_new_data is True. Asset objects work in either mode. A bare string is read as an asset ID for an adhoc run, and as an asset name when associate_new_data is True. TYPE: list[str | Asset] | None DEFAULT: None
associate_new_data	If True, associate data ingested after the run is created that falls within its time period. Requires assets. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Run	The created Run.

find async

find(**kwargs) -> Run | None

Find a single run matching the given query. Takes the same arguments as list_. If more than one run is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
Run | None	The Run found or None.

get async

get(
    *,
    run_id: str | None = None,
    client_key: str | None = None,
) -> Run

Get a Run.

PARAMETER	DESCRIPTION
run_id	The ID of the run. TYPE: str | None DEFAULT: None
client_key	The client key of the run. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Run	The Run.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    run_ids: list[str] | None = None,
    client_keys: list[str] | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    created_by: Any | str | None = None,
    modified_by: Any | str | None = None,
    tags: list[str | Tag] | None = None,
    metadata: list[Any] | None = None,
    assets: list[Asset] | list[str] | None = None,
    asset_tags: list[str | Tag] | None = None,
    duration_less_than: timedelta | None = None,
    duration_greater_than: timedelta | None = None,
    start_time_after: datetime | None = None,
    start_time_before: datetime | None = None,
    stop_time_after: datetime | None = None,
    stop_time_before: datetime | None = None,
    is_stopped: bool | None = None,
    description_contains: str | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Run]

List runs with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the run. TYPE: str | None DEFAULT: None
names	List of run names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the run. TYPE: str | None DEFAULT: None
name_regex	Regular expression to filter runs by name. TYPE: str | Pattern | None DEFAULT: None
run_ids	Filter to runs with any of these IDs. TYPE: list[str] | None DEFAULT: None
client_keys	Filter to runs with any of these client keys. TYPE: list[str] | None DEFAULT: None
created_after	Filter runs created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter runs created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter runs modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter runs modified before this datetime. TYPE: datetime | None DEFAULT: None
created_by	Filter runs created by this User or user ID. TYPE: Any | str | None DEFAULT: None
modified_by	Filter runs last modified by this User or user ID. TYPE: Any | str | None DEFAULT: None
tags	Filter runs with any of these Tags IDs. TYPE: list[str | Tag] | None DEFAULT: None
metadata	Filter runs by metadata criteria. TYPE: list[Any] | None DEFAULT: None
assets	Filter runs associated with any of these Assets or asset IDs. TYPE: list[Asset] | list[str] | None DEFAULT: None
asset_tags	Filter runs associated with any Assets that have these Tag IDs. TYPE: list[str | Tag] | None DEFAULT: None
duration_less_than	Filter runs with duration less than this time. TYPE: timedelta | None DEFAULT: None
duration_greater_than	Filter runs with duration greater than this time. TYPE: timedelta | None DEFAULT: None
start_time_after	Filter runs that started after this datetime. TYPE: datetime | None DEFAULT: None
start_time_before	Filter runs that started before this datetime. TYPE: datetime | None DEFAULT: None
stop_time_after	Filter runs that stopped after this datetime. TYPE: datetime | None DEFAULT: None
stop_time_before	Filter runs that stopped before this datetime. TYPE: datetime | None DEFAULT: None
is_stopped	Whether the run is stopped. TYPE: bool | None DEFAULT: None
description_contains	Partial description of the run. TYPE: str | None DEFAULT: None
include_archived	If True, include archived runs in results. TYPE: bool DEFAULT: False
filter_query	Explicit CEL query to filter runs. TYPE: str | None DEFAULT: None
order_by	Field and direction to order results by. TYPE: str | None DEFAULT: None
limit	Maximum number of runs to return. If None, returns all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Run]	A list of Run objects that match the filter criteria.

stop async

stop(run: str | Run) -> Run

Stop a run by setting its stop time to the current time.

PARAMETER	DESCRIPTION
run	The Run or run ID to stop. TYPE: str | Run

unarchive async

unarchive(run: str | Run) -> Run

Unarchive a run.

PARAMETER	DESCRIPTION
run	The Run or run ID to unarchive. TYPE: str | Run

update async

update(run: str | Run, update: RunUpdate | dict) -> Run

Update a Run.

PARAMETER	DESCRIPTION
run	The Run or run ID to update. TYPE: str | Run
update	Updates to apply to the Run. TYPE: RunUpdate | dict

RETURNS	DESCRIPTION
Run	The updated Run.

StreamingMode

Bases: str, Enum

Selects the SiftStream transport mode.

ATTRIBUTE	DESCRIPTION
FILE_BACKUP
LIVE_ONLY
LIVE_WITH_BACKUPS

FILE_BACKUP class-attribute instance-attribute

FILE_BACKUP = 'file_backup'

LIVE_ONLY class-attribute instance-attribute

LIVE_ONLY = 'live_only'

LIVE_WITH_BACKUPS class-attribute instance-attribute

LIVE_WITH_BACKUPS = 'live_with_backups'

TagsAPI

TagsAPI(sift_client: SiftClient)

Sync counterpart to TagsAPIAsync.

High-level API for interacting with tags.

Initialize the TagsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
create	Create a new tag.
find	Find a single tag matching the given query. Takes the same arguments as list. If more than one tag is found,
find_or_create	Find tags by name or create them if they don't exist.
list_	List tags with optional filtering.
update	Update a Tag.

create

create(name: str) -> Tag

Create a new tag.

PARAMETER	DESCRIPTION
name	The name of the tag. TYPE: str

RETURNS	DESCRIPTION
Tag	The created Tag.

find

find(**kwargs) -> Tag | None

Find a single tag matching the given query. Takes the same arguments as list. If more than one tag is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list. DEFAULT: {}

RETURNS	DESCRIPTION
Tag | None	The Tag found or None.

find_or_create

find_or_create(names: list[str]) -> list[Tag]

Find tags by name or create them if they don't exist.

PARAMETER	DESCRIPTION
names	List of tag names to find or create. TYPE: list[str]

RETURNS	DESCRIPTION
list[Tag]	List of Tags that were found or created.

list_

list_(
    *,
    name: str | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    names: list[str] | None = None,
    tag_ids: list[str] | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Tag]

List tags with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the tag. TYPE: str | None DEFAULT: None
name_contains	Partial name of the tag. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter tags by name. TYPE: str | Pattern | None DEFAULT: None
names	List of tag names to filter by. TYPE: list[str] | None DEFAULT: None
tag_ids	List of tag IDs to filter by. TYPE: list[str] | None DEFAULT: None
filter_query	Explicit CEL query to filter tags. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved tags. TYPE: str | None DEFAULT: None
limit	How many tags to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Tag]	A list of Tags that matches the filter.

update

update(tag: str | Tag, update: TagUpdate | dict) -> Tag

Update a Tag.

PARAMETER	DESCRIPTION
tag	The Tag or tag ID to update. TYPE: str | Tag
update	Updates to apply to the Tag. TYPE: TagUpdate | dict

RETURNS	DESCRIPTION
Tag	The updated Tag.

Note

The tags API doesn't have an update method in the proto, so this would need to be implemented if the API supports it.

TagsAPIAsync

TagsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with tags.

Initialize the TagsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
create	Create a new tag.
find	Find a single tag matching the given query. Takes the same arguments as list. If more than one tag is found,
find_or_create	Find tags by name or create them if they don't exist.
list_	List tags with optional filtering.
update	Update a Tag.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

create async

create(name: str) -> Tag

Create a new tag.

PARAMETER	DESCRIPTION
name	The name of the tag. TYPE: str

RETURNS	DESCRIPTION
Tag	The created Tag.

find async

find(**kwargs) -> Tag | None

Find a single tag matching the given query. Takes the same arguments as list. If more than one tag is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list. DEFAULT: {}

RETURNS	DESCRIPTION
Tag | None	The Tag found or None.

find_or_create async

find_or_create(names: list[str]) -> list[Tag]

Find tags by name or create them if they don't exist.

PARAMETER	DESCRIPTION
names	List of tag names to find or create. TYPE: list[str]

RETURNS	DESCRIPTION
list[Tag]	List of Tags that were found or created.

list_ async

list_(
    *,
    name: str | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    names: list[str] | None = None,
    tag_ids: list[str] | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[Tag]

List tags with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the tag. TYPE: str | None DEFAULT: None
name_contains	Partial name of the tag. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter tags by name. TYPE: str | Pattern | None DEFAULT: None
names	List of tag names to filter by. TYPE: list[str] | None DEFAULT: None
tag_ids	List of tag IDs to filter by. TYPE: list[str] | None DEFAULT: None
filter_query	Explicit CEL query to filter tags. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved tags. TYPE: str | None DEFAULT: None
limit	How many tags to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[Tag]	A list of Tags that matches the filter.

update async

update(tag: str | Tag, update: TagUpdate | dict) -> Tag

Update a Tag.

PARAMETER	DESCRIPTION
tag	The Tag or tag ID to update. TYPE: str | Tag
update	Updates to apply to the Tag. TYPE: TagUpdate | dict

RETURNS	DESCRIPTION
Tag	The updated Tag.

Note

The tags API doesn't have an update method in the proto, so this would need to be implemented if the API supports it.

TestResultsAPI

TestResultsAPI(sift_client: SiftClient)

Sync counterpart to TestResultsAPIAsync.

High-level API for interacting with test reports, steps, and measurements.

Initialize the TestResultsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a test report.
create	Create a new test report.
create_measurement	Create a new test measurement.
create_measurements	Create multiple test measurements in a single request.
create_step	Create a new test step.
delete	Delete a test report.
delete_measurement	Delete a test measurement.
delete_step	Delete a test step.
find	Find a single test report matching the given query. Takes the same arguments as list_. If more than one test report is found,
get	Get a TestReport.
get_step	Get a TestStep.
import_	Import a test report from an already-uploaded file.
import_log_file	Replay a log file by parsing each entry, simulating the results, then creating for real.
list_	List test reports with optional filtering.
list_measurements	List test measurements with optional filtering.
list_steps	List test steps with optional filtering.
unarchive	Unarchive a test report.
update	Update a TestReport.
update_measurement	Update a TestMeasurement.
update_step	Update a TestStep.

archive

archive(*, test_report: str | TestReport) -> TestReport

Archive a test report.

PARAMETER	DESCRIPTION
test_report	The TestReport or test report ID to archive. TYPE: str | TestReport

create

create(
    test_report: TestReportCreate | dict,
    log_file: str | Path | None = None,
) -> TestReport

Create a new test report.

PARAMETER	DESCRIPTION
test_report	The test report to create (can be TestReport or TestReportCreate). TYPE: TestReportCreate | dict
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestReport	The created TestReport.

create_measurement

create_measurement(
    test_measurement: TestMeasurementCreate | dict,
    update_step: bool = False,
    log_file: str | Path | None = None,
) -> TestMeasurement

Create a new test measurement.

PARAMETER	DESCRIPTION
test_measurement	The test measurement to create (can be TestMeasurement or TestMeasurementCreate). TYPE: TestMeasurementCreate | dict
update_step	Whether to update the step to failed if the measurement is being created is failed. TYPE: bool DEFAULT: False
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestMeasurement	The created TestMeasurement.

create_measurements

create_measurements(
    test_measurements: list[TestMeasurementCreate],
    log_file: str | Path | None = None,
) -> tuple[int, list[str]]

Create multiple test measurements in a single request.

PARAMETER	DESCRIPTION
test_measurements	The test measurements to create. TYPE: list[TestMeasurementCreate]
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
tuple[int, list[str]]	A tuple of (measurements_created_count, measurement_ids).

create_step

create_step(
    test_step: TestStepCreate | dict,
    log_file: str | Path | None = None,
) -> TestStep

Create a new test step.

PARAMETER	DESCRIPTION
test_step	The test step to create (can be TestStep or TestStepCreate). TYPE: TestStepCreate | dict
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestStep	The created TestStep.

delete

delete(*, test_report: str | TestReport) -> None

Delete a test report.

PARAMETER	DESCRIPTION
test_report	The TestReport or test report ID to delete. TYPE: str | TestReport

delete_measurement

delete_measurement(
    *, test_measurement: str | TestMeasurement
) -> None

Delete a test measurement.

PARAMETER	DESCRIPTION
test_measurement	The TestMeasurement or measurement ID to delete. TYPE: str | TestMeasurement

delete_step

delete_step(*, test_step: str | TestStep) -> None

Delete a test step.

PARAMETER	DESCRIPTION
test_step	The TestStep or test step ID to delete. TYPE: str | TestStep

find

find(**kwargs) -> TestReport | None

Find a single test report matching the given query. Takes the same arguments as list_. If more than one test report is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
TestReport | None	The TestReport found or None.

get

get(*, test_report_id: str) -> TestReport

Get a TestReport.

PARAMETER	DESCRIPTION
test_report_id	The ID of the test report. TYPE: str

RETURNS	DESCRIPTION
TestReport	The TestReport.

get_step

get_step(test_step: str | TestStep) -> TestStep

Get a TestStep.

PARAMETER	DESCRIPTION
test_step	The TestStep or test step ID to get. TYPE: str | TestStep

import_

import_(test_file: str | Path) -> TestReport

Import a test report from an already-uploaded file.

PARAMETER	DESCRIPTION
test_file	The path to the test report file to import. We currently only support XML files exported from NI TestStand. TYPE: str | Path

RETURNS	DESCRIPTION
TestReport	The imported TestReport.

import_log_file

import_log_file(
    log_file: str | Path, incremental: bool = False
) -> ReplayResult

Replay a log file by parsing each entry, simulating the results, then creating for real.

This method reads a log file created by the simulation logging, reconstructs all the objects via simulation, and then creates them via the actual API. IDs are mapped from simulated to real during the creation process.

PARAMETER	DESCRIPTION
log_file	Path to the log file to import. TYPE: str | Path
incremental	(internal tooling) If True, goes line by line and calls API every event -- keeps track of last line sent so it can be called after some updates and be additive vs. replaying the entire log file each time(i.e. when False, reads the entire log file, building a test report in memory, then sends the calls for each step/measurement to the API). TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
ReplayResult	A ReplayResult containing the created report, steps, and measurements.

list_

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    test_report_ids: list[str] | None = None,
    status: TestStatus | None = None,
    test_system_name: str | None = None,
    test_case: str | None = None,
    serial_numbers: list[str] | None = None,
    part_numbers: list[str] | None = None,
    system_operator: str | None = None,
    created_by: str | None = None,
    modified_by: str | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    metadata: list[Any] | dict[str, Any] | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[TestReport]

List test reports with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the test report. TYPE: str | None DEFAULT: None
names	List of test report names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the test report. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter test reports by name. TYPE: str | Pattern | None DEFAULT: None
test_report_ids	Test report IDs to filter by. TYPE: list[str] | None DEFAULT: None
status	Status to filter by (TestStatus enum). TYPE: TestStatus | None DEFAULT: None
test_system_name	Test system name to filter by. TYPE: str | None DEFAULT: None
test_case	Test case to filter by. TYPE: str | None DEFAULT: None
serial_numbers	Serial numbers to filter by. TYPE: list[str] | None DEFAULT: None
part_numbers	Part numbers to filter by. TYPE: list[str] | None DEFAULT: None
system_operator	System operator to filter by. TYPE: str | None DEFAULT: None
created_by	User ID who created the test report. TYPE: str | None DEFAULT: None
modified_by	User ID who last modified the test report. TYPE: str | None DEFAULT: None
created_after	Filter test reports created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter test reports created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter test reports modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter test reports modified before this datetime. TYPE: datetime | None DEFAULT: None
metadata	Filter test reports by metadata criteria. TYPE: list[Any] | dict[str, Any] | None DEFAULT: None
include_archived	Whether to include only archived or non-archived reports. TYPE: bool DEFAULT: False
filter_query	Custom filter to apply to the test reports. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved test reports. If used, this will override the other filters. TYPE: str | None DEFAULT: None
limit	How many test reports to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[TestReport]	A list of TestReports that matches the filter.

list_measurements

list_measurements(
    *,
    measurements: list[str]
    | list[TestMeasurement]
    | None = None,
    test_steps: list[str] | list[TestStep] | None = None,
    test_reports: list[str]
    | list[TestReport]
    | None = None,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    measurement_type: TestMeasurementType | None = None,
    passed: bool | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[TestMeasurement]

List test measurements with optional filtering.

PARAMETER	DESCRIPTION
measurements	Measurements to filter by. TYPE: list[str] | list[TestMeasurement] | None DEFAULT: None
test_steps	Test steps to filter by. TYPE: list[str] | list[TestStep] | None DEFAULT: None
test_reports	Test reports to filter by. TYPE: list[str] | list[TestReport] | None DEFAULT: None
name	Exact name of the test measurement. TYPE: str | None DEFAULT: None
names	List of test measurement names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the test measurement. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter test measurements by name. TYPE: str | Pattern | None DEFAULT: None
measurement_type	Measurement type to filter by (TestMeasurementType enum). TYPE: TestMeasurementType | None DEFAULT: None
passed	Whether the measurement passed. TYPE: bool | None DEFAULT: None
filter_query	Explicit CEL query to filter test measurements. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved test measurements. TYPE: str | None DEFAULT: None
limit	How many test measurements to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[TestMeasurement]	A list of TestMeasurements that matches the filter.

list_steps

list_steps(
    *,
    test_steps: list[str] | list[TestStep] | None = None,
    test_reports: list[str]
    | list[TestReport]
    | None = None,
    parent_steps: list[str] | list[TestStep] | None = None,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    status: TestStatus | None = None,
    step_type: TestStepType | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[TestStep]

List test steps with optional filtering.

PARAMETER	DESCRIPTION
test_steps	Test steps to filter by. TYPE: list[str] | list[TestStep] | None DEFAULT: None
test_reports	Test reports to filter by. TYPE: list[str] | list[TestReport] | None DEFAULT: None
parent_steps	Parent steps to filter by. TYPE: list[str] | list[TestStep] | None DEFAULT: None
name	Exact name of the test step. TYPE: str | None DEFAULT: None
names	List of test step names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the test step. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter test steps by name. TYPE: str | Pattern | None DEFAULT: None
status	Status to filter by (TestStatus enum). TYPE: TestStatus | None DEFAULT: None
step_type	Step type to filter by (TestStepType enum). TYPE: TestStepType | None DEFAULT: None
filter_query	Explicit CEL query to filter test steps. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved test steps. TYPE: str | None DEFAULT: None
limit	How many test steps to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[TestStep]	A list of TestSteps that matches the filter.

unarchive

unarchive(*, test_report: str | TestReport) -> TestReport

Unarchive a test report.

PARAMETER	DESCRIPTION
test_report	The TestReport or test report ID to unarchive. TYPE: str | TestReport

update

update(
    test_report: str | TestReport,
    update: TestReportUpdate | dict,
    log_file: str | Path | None = None,
) -> TestReport

Update a TestReport.

PARAMETER	DESCRIPTION
test_report	The TestReport or test report ID to update. TYPE: str | TestReport
update	Updates to apply to the TestReport. TYPE: TestReportUpdate | dict
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestReport	The updated TestReport.

update_measurement

update_measurement(
    test_measurement: TestMeasurement,
    update: TestMeasurementUpdate | dict,
    update_step: bool = False,
    log_file: str | Path | None = None,
) -> TestMeasurement

Update a TestMeasurement.

PARAMETER	DESCRIPTION
test_measurement	The TestMeasurement or measurement ID to update. TYPE: TestMeasurement
update	Updates to apply to the TestMeasurement. TYPE: TestMeasurementUpdate | dict
update_step	Whether to update the step to failed if the measurement is being updated to failed. TYPE: bool DEFAULT: False
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestMeasurement	The updated TestMeasurement.

update_step

update_step(
    test_step: str | TestStep,
    update: TestStepUpdate | dict,
    log_file: str | Path | None = None,
) -> TestStep

Update a TestStep.

PARAMETER	DESCRIPTION
test_step	The TestStep or test step ID to update. TYPE: str | TestStep
update	Updates to apply to the TestStep. TYPE: TestStepUpdate | dict
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestStep	The updated TestStep.

TestResultsAPIAsync

TestResultsAPIAsync(sift_client: SiftClient)

Bases: ResourceBase

High-level API for interacting with test reports, steps, and measurements.

Initialize the TestResultsAPI.

PARAMETER	DESCRIPTION
sift_client	The Sift client to use. TYPE: SiftClient

METHOD	DESCRIPTION
archive	Archive a test report.
create	Create a new test report.
create_measurement	Create a new test measurement.
create_measurements	Create multiple test measurements in a single request.
create_step	Create a new test step.
delete	Delete a test report.
delete_measurement	Delete a test measurement.
delete_step	Delete a test step.
find	Find a single test report matching the given query. Takes the same arguments as list_. If more than one test report is found,
get	Get a TestReport.
get_step	Get a TestStep.
import_	Import a test report from an already-uploaded file.
import_log_file	Replay a log file by parsing each entry, simulating the results, then creating for real.
list_	List test reports with optional filtering.
list_measurements	List test measurements with optional filtering.
list_steps	List test steps with optional filtering.
unarchive	Unarchive a test report.
update	Update a TestReport.
update_measurement	Update a TestMeasurement.
update_step	Update a TestStep.

ATTRIBUTE	DESCRIPTION
client	TYPE: SiftClient
grpc_client	TYPE: GrpcClient
rest_client	TYPE: RestClient

client property

client: SiftClient

grpc_client property

grpc_client: GrpcClient

rest_client property

rest_client: RestClient

archive async

archive(*, test_report: str | TestReport) -> TestReport

Archive a test report.

PARAMETER	DESCRIPTION
test_report	The TestReport or test report ID to archive. TYPE: str | TestReport

create async

create(
    test_report: TestReportCreate | dict,
    log_file: str | Path | None = None,
) -> TestReport

Create a new test report.

PARAMETER	DESCRIPTION
test_report	The test report to create (can be TestReport or TestReportCreate). TYPE: TestReportCreate | dict
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestReport	The created TestReport.

create_measurement async

create_measurement(
    test_measurement: TestMeasurementCreate | dict,
    update_step: bool = False,
    log_file: str | Path | None = None,
) -> TestMeasurement

Create a new test measurement.

PARAMETER	DESCRIPTION
test_measurement	The test measurement to create (can be TestMeasurement or TestMeasurementCreate). TYPE: TestMeasurementCreate | dict
update_step	Whether to update the step to failed if the measurement is being created is failed. TYPE: bool DEFAULT: False
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestMeasurement	The created TestMeasurement.

create_measurements async

create_measurements(
    test_measurements: list[TestMeasurementCreate],
    log_file: str | Path | None = None,
) -> tuple[int, list[str]]

Create multiple test measurements in a single request.

PARAMETER	DESCRIPTION
test_measurements	The test measurements to create. TYPE: list[TestMeasurementCreate]
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
tuple[int, list[str]]	A tuple of (measurements_created_count, measurement_ids).

create_step async

create_step(
    test_step: TestStepCreate | dict,
    log_file: str | Path | None = None,
) -> TestStep

Create a new test step.

PARAMETER	DESCRIPTION
test_step	The test step to create (can be TestStep or TestStepCreate). TYPE: TestStepCreate | dict
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestStep	The created TestStep.

delete async

delete(*, test_report: str | TestReport) -> None

Delete a test report.

PARAMETER	DESCRIPTION
test_report	The TestReport or test report ID to delete. TYPE: str | TestReport

delete_measurement async

delete_measurement(
    *, test_measurement: str | TestMeasurement
) -> None

Delete a test measurement.

PARAMETER	DESCRIPTION
test_measurement	The TestMeasurement or measurement ID to delete. TYPE: str | TestMeasurement

delete_step async

delete_step(*, test_step: str | TestStep) -> None

Delete a test step.

PARAMETER	DESCRIPTION
test_step	The TestStep or test step ID to delete. TYPE: str | TestStep

find async

find(**kwargs) -> TestReport | None

Find a single test report matching the given query. Takes the same arguments as list_. If more than one test report is found, raises an error.

PARAMETER	DESCRIPTION
**kwargs	Keyword arguments to pass to list_. DEFAULT: {}

RETURNS	DESCRIPTION
TestReport | None	The TestReport found or None.

get async

get(*, test_report_id: str) -> TestReport

Get a TestReport.

PARAMETER	DESCRIPTION
test_report_id	The ID of the test report. TYPE: str

RETURNS	DESCRIPTION
TestReport	The TestReport.

get_step async

get_step(test_step: str | TestStep) -> TestStep

Get a TestStep.

PARAMETER	DESCRIPTION
test_step	The TestStep or test step ID to get. TYPE: str | TestStep

import_ async

import_(test_file: str | Path) -> TestReport

Import a test report from an already-uploaded file.

PARAMETER	DESCRIPTION
test_file	The path to the test report file to import. We currently only support XML files exported from NI TestStand. TYPE: str | Path

RETURNS	DESCRIPTION
TestReport	The imported TestReport.

import_log_file async

import_log_file(
    log_file: str | Path, incremental: bool = False
) -> ReplayResult

Replay a log file by parsing each entry, simulating the results, then creating for real.

This method reads a log file created by the simulation logging, reconstructs all the objects via simulation, and then creates them via the actual API. IDs are mapped from simulated to real during the creation process.

PARAMETER	DESCRIPTION
log_file	Path to the log file to import. TYPE: str | Path
incremental	(internal tooling) If True, goes line by line and calls API every event -- keeps track of last line sent so it can be called after some updates and be additive vs. replaying the entire log file each time(i.e. when False, reads the entire log file, building a test report in memory, then sends the calls for each step/measurement to the API). TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
ReplayResult	A ReplayResult containing the created report, steps, and measurements.

list_ async

list_(
    *,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    test_report_ids: list[str] | None = None,
    status: TestStatus | None = None,
    test_system_name: str | None = None,
    test_case: str | None = None,
    serial_numbers: list[str] | None = None,
    part_numbers: list[str] | None = None,
    system_operator: str | None = None,
    created_by: str | None = None,
    modified_by: str | None = None,
    created_after: datetime | None = None,
    created_before: datetime | None = None,
    modified_after: datetime | None = None,
    modified_before: datetime | None = None,
    metadata: list[Any] | dict[str, Any] | None = None,
    include_archived: bool = False,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[TestReport]

List test reports with optional filtering.

PARAMETER	DESCRIPTION
name	Exact name of the test report. TYPE: str | None DEFAULT: None
names	List of test report names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the test report. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter test reports by name. TYPE: str | Pattern | None DEFAULT: None
test_report_ids	Test report IDs to filter by. TYPE: list[str] | None DEFAULT: None
status	Status to filter by (TestStatus enum). TYPE: TestStatus | None DEFAULT: None
test_system_name	Test system name to filter by. TYPE: str | None DEFAULT: None
test_case	Test case to filter by. TYPE: str | None DEFAULT: None
serial_numbers	Serial numbers to filter by. TYPE: list[str] | None DEFAULT: None
part_numbers	Part numbers to filter by. TYPE: list[str] | None DEFAULT: None
system_operator	System operator to filter by. TYPE: str | None DEFAULT: None
created_by	User ID who created the test report. TYPE: str | None DEFAULT: None
modified_by	User ID who last modified the test report. TYPE: str | None DEFAULT: None
created_after	Filter test reports created after this datetime. TYPE: datetime | None DEFAULT: None
created_before	Filter test reports created before this datetime. TYPE: datetime | None DEFAULT: None
modified_after	Filter test reports modified after this datetime. TYPE: datetime | None DEFAULT: None
modified_before	Filter test reports modified before this datetime. TYPE: datetime | None DEFAULT: None
metadata	Filter test reports by metadata criteria. TYPE: list[Any] | dict[str, Any] | None DEFAULT: None
include_archived	Whether to include only archived or non-archived reports. TYPE: bool DEFAULT: False
filter_query	Custom filter to apply to the test reports. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved test reports. If used, this will override the other filters. TYPE: str | None DEFAULT: None
limit	How many test reports to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[TestReport]	A list of TestReports that matches the filter.

list_measurements async

list_measurements(
    *,
    measurements: list[str]
    | list[TestMeasurement]
    | None = None,
    test_steps: list[str] | list[TestStep] | None = None,
    test_reports: list[str]
    | list[TestReport]
    | None = None,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    measurement_type: TestMeasurementType | None = None,
    passed: bool | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[TestMeasurement]

List test measurements with optional filtering.

PARAMETER	DESCRIPTION
measurements	Measurements to filter by. TYPE: list[str] | list[TestMeasurement] | None DEFAULT: None
test_steps	Test steps to filter by. TYPE: list[str] | list[TestStep] | None DEFAULT: None
test_reports	Test reports to filter by. TYPE: list[str] | list[TestReport] | None DEFAULT: None
name	Exact name of the test measurement. TYPE: str | None DEFAULT: None
names	List of test measurement names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the test measurement. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter test measurements by name. TYPE: str | Pattern | None DEFAULT: None
measurement_type	Measurement type to filter by (TestMeasurementType enum). TYPE: TestMeasurementType | None DEFAULT: None
passed	Whether the measurement passed. TYPE: bool | None DEFAULT: None
filter_query	Explicit CEL query to filter test measurements. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved test measurements. TYPE: str | None DEFAULT: None
limit	How many test measurements to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[TestMeasurement]	A list of TestMeasurements that matches the filter.

list_steps async

list_steps(
    *,
    test_steps: list[str] | list[TestStep] | None = None,
    test_reports: list[str]
    | list[TestReport]
    | None = None,
    parent_steps: list[str] | list[TestStep] | None = None,
    name: str | None = None,
    names: list[str] | None = None,
    name_contains: str | None = None,
    name_regex: str | Pattern | None = None,
    status: TestStatus | None = None,
    step_type: TestStepType | None = None,
    filter_query: str | None = None,
    order_by: str | None = None,
    limit: int | None = None,
    page_size: int | None = None,
) -> list[TestStep]

List test steps with optional filtering.

PARAMETER	DESCRIPTION
test_steps	Test steps to filter by. TYPE: list[str] | list[TestStep] | None DEFAULT: None
test_reports	Test reports to filter by. TYPE: list[str] | list[TestReport] | None DEFAULT: None
parent_steps	Parent steps to filter by. TYPE: list[str] | list[TestStep] | None DEFAULT: None
name	Exact name of the test step. TYPE: str | None DEFAULT: None
names	List of test step names to filter by. TYPE: list[str] | None DEFAULT: None
name_contains	Partial name of the test step. TYPE: str | None DEFAULT: None
name_regex	Regular expression string to filter test steps by name. TYPE: str | Pattern | None DEFAULT: None
status	Status to filter by (TestStatus enum). TYPE: TestStatus | None DEFAULT: None
step_type	Step type to filter by (TestStepType enum). TYPE: TestStepType | None DEFAULT: None
filter_query	Explicit CEL query to filter test steps. TYPE: str | None DEFAULT: None
order_by	How to order the retrieved test steps. TYPE: str | None DEFAULT: None
limit	How many test steps to retrieve. If None, retrieves all matches. TYPE: int | None DEFAULT: None
page_size	Number of results to fetch per request. Lower this if you hit gRPC message size limits on responses. If None, uses the server default. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[TestStep]	A list of TestSteps that matches the filter.

unarchive async

unarchive(*, test_report: str | TestReport) -> TestReport

Unarchive a test report.

PARAMETER	DESCRIPTION
test_report	The TestReport or test report ID to unarchive. TYPE: str | TestReport

update async

update(
    test_report: str | TestReport,
    update: TestReportUpdate | dict,
    log_file: str | Path | None = None,
) -> TestReport

Update a TestReport.

PARAMETER	DESCRIPTION
test_report	The TestReport or test report ID to update. TYPE: str | TestReport
update	Updates to apply to the TestReport. TYPE: TestReportUpdate | dict
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestReport	The updated TestReport.

update_measurement async

update_measurement(
    test_measurement: TestMeasurement,
    update: TestMeasurementUpdate | dict,
    update_step: bool = False,
    log_file: str | Path | None = None,
) -> TestMeasurement

Update a TestMeasurement.

PARAMETER	DESCRIPTION
test_measurement	The TestMeasurement or measurement ID to update. TYPE: TestMeasurement
update	Updates to apply to the TestMeasurement. TYPE: TestMeasurementUpdate | dict
update_step	Whether to update the step to failed if the measurement is being updated to failed. TYPE: bool DEFAULT: False
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestMeasurement	The updated TestMeasurement.

update_step async

update_step(
    test_step: str | TestStep,
    update: TestStepUpdate | dict,
    log_file: str | Path | None = None,
) -> TestStep

Update a TestStep.

PARAMETER	DESCRIPTION
test_step	The TestStep or test step ID to update. TYPE: str | TestStep
update	Updates to apply to the TestStep. TYPE: TestStepUpdate | dict
log_file	If set, log the request to this file and return a simulated response. TYPE: str | Path | None DEFAULT: None

RETURNS	DESCRIPTION
TestStep	The updated TestStep.

TracingConfig

TracingConfig(
    is_enabled: bool = True,
    level: str = "info",
    log_dir: str | None = None,
    filename_prefix: str | None = None,
    max_log_files: int | None = None,
)

Configuration for tracing in SiftStream.

This class provides factory methods to create tracing configurations for use with IngestionConfigStreamingClient. Tracing will only be initialized once per process.

Initialize a TracingConfig.

PARAMETER	DESCRIPTION
is_enabled	Whether tracing is enabled. Defaults to True. TYPE: bool DEFAULT: True
level	Logging level as string - one of "trace", "debug", "info", "warn", "error". Defaults to "info". TYPE: str DEFAULT: 'info'
log_dir	Directory path for log files. Required if using file logging. Defaults to "./logs" when using with_file. TYPE: str | None DEFAULT: None
filename_prefix	Prefix for log filenames. Required if using file logging. Defaults to "sift_stream_bindings.log" when using with_file. TYPE: str | None DEFAULT: None
max_log_files	Maximum number of log files to keep. Required if using file logging. Defaults to 7 when using with_file. TYPE: int | None DEFAULT: None

METHOD	DESCRIPTION
console_only	Create a configuration that enables tracing to stdout/stderr only.
disabled	Create a configuration that disables tracing.
with_file	Create a configuration that enables tracing to both stdout and rolling log files.

ATTRIBUTE	DESCRIPTION
filename_prefix
is_enabled
level
log_dir
max_log_files

filename_prefix instance-attribute

filename_prefix = filename_prefix

is_enabled instance-attribute

is_enabled = is_enabled

level instance-attribute

level = level

log_dir instance-attribute

log_dir = log_dir

max_log_files instance-attribute

max_log_files = max_log_files

console_only classmethod

console_only(level: str = 'info') -> TracingConfig

Create a configuration that enables tracing to stdout/stderr only.

PARAMETER	DESCRIPTION
level	Logging level as string - one of "trace", "debug", "info", "warn", "error". Defaults to "info". TYPE: str DEFAULT: 'info'

RETURNS	DESCRIPTION
TracingConfig	A TracingConfig with tracing enabled (outputs to stdout/stderr only).

disabled classmethod

disabled() -> TracingConfig

Create a configuration that disables tracing.

RETURNS	DESCRIPTION
TracingConfig	A TracingConfig with tracing disabled.

with_file classmethod

with_file(
    level: str = "info",
    log_dir: str = "./logs",
    filename_prefix: str = "sift_stream_bindings.log",
    max_log_files: int = 7,
) -> TracingConfig

Create a configuration that enables tracing to both stdout and rolling log files.

PARAMETER	DESCRIPTION
level	Logging level as string - one of "trace", "debug", "info", "warn", "error". Defaults to "info". TYPE: str DEFAULT: 'info'
log_dir	Directory path for log files. Defaults to "./logs". TYPE: str DEFAULT: './logs'
filename_prefix	Prefix for log filenames. Defaults to "sift_stream_bindings.log". TYPE: str DEFAULT: 'sift_stream_bindings.log'
max_log_files	Maximum number of log files to keep. Defaults to 7. TYPE: int DEFAULT: 7

RETURNS	DESCRIPTION
TracingConfig	A TracingConfig with tracing enabled for both stdout and file output.