sift_client

Sift Client Library - Python client for interacting with Sift APIs.

Overview

This library provides a high-level Python client for interacting with Sift APIs. It offers:

• Synchronous and asynchronous interfaces for all operations
• Strong type checking with Pydantic models
• Pythonic API design with intuitive method names
• Comprehensive filtering capabilities for queries
• Automatic type conversion between protobuf and Python types

Installation

pip install sift-stack-py

Quick Start

Initialize the Client

from sift_client import SiftClient

# Initialize with credentials
client = SiftClient(
    api_key="your-api-key",
    grpc_url="https://grpc-api.siftstack.com",
    rest_url="https://api.siftstack.com"
)

Basic Operations

# Get an asset
asset = client.assets.get(asset_id="asset123")

# List resources with filtering
runs = client.runs.list_(
    assets=[asset.id_],
    start_time_after=datetime.now() - timedelta(days=7),
    limit=10
)

# Update a resource
asset.update({"tags": ["production", "v2"]})

# Create a new resource
run = client.runs.create({
    "name": "Test Run",
    "asset_ids": [asset.id_],
    "start_time": datetime.now()
})

Async Usage

import asyncio

async def main():
    # Use async_ accessor for async operations
    asset = await client.async_.assets.get(asset_id="asset123")
    runs = await client.async_.runs.list_(limit=10)
    return asset, runs

result = asyncio.run(main())

Key Components

Resources

Resource APIs provide methods for interacting with Sift services. Each resource supports operations like get(), list_(), create(), update(), and archive().

Available Resources:

• client.assets - Manage physical or logical entities
• client.runs - Manage time-bounded operational periods
• etc.

See resources for detailed documentation and a complete list.

Types

Sift types are immutable Pydantic models representing Sift objects. They provide type-safe access to properties and convenience methods for common operations.

Available Types:

• Asset, AssetUpdate - Asset resources
• Run, RunCreate, RunUpdate - Run resources
• etc.

See sift_types for detailed documentation and a complete list.

Examples

For complete examples, see the examples directory.

Connection Configuration

For advanced connection options:

from sift_client.transport import SiftConnectionConfig, GrpcConfig, RestConfig

config = SiftConnectionConfig(
    grpc_config=GrpcConfig(
        uri="https://grpc-api.siftstack.com",
        api_key="your-api-key",
        use_ssl=True
    ),
    rest_config=RestConfig(
        uri="https://api.siftstack.com",
        api_key="your-api-key"
    )
)

client = SiftClient(connection_config=config)

Best Practices

1. Use sync APIs for notebooks, scripts, and simple applications
2. Use async APIs for high-performance services with concurrent operations
3. Leverage filtering to reduce data transfer and improve performance
4. Reuse client instances rather than creating new ones for each operation
5. Use type hints to get full IDE support and catch errors early

MODULE	DESCRIPTION
client
config	Global configuration for the Sift client library.
errors
pytest_plugin
resources	Sift Resources - API interfaces for interacting with Sift services.
scripts
sift_types	Sift Types - Pydantic models for Sift resources.
transport
util	Utility modules for the sift_client package.

CLASS	DESCRIPTION
SiftClient	SiftClient is a high-level client for interacting with Sift's APIs.
SiftConnectionConfig	Configuration for Grpc and Rest connections.

SiftClient

SiftClient(
    api_key: str | None = None,
    grpc_url: str | None = None,
    rest_url: str | None = None,
    connection_config: SiftConnectionConfig | None = None,
    app_url: str | None = None,
)

Bases: WithGrpcClient, WithRestClient

SiftClient is a high-level client for interacting with Sift's APIs.

It provides both synchronous and asynchronous interfaces, strong type checking, and a Pythonic API design.

Initialize the SiftClient with specific connection parameters or a connection_config.

PARAMETER	DESCRIPTION
api_key	The Sift API key for authentication. TYPE: str | None DEFAULT: None
grpc_url	The Sift gRPC API URL. TYPE: str | None DEFAULT: None
rest_url	The Sift REST API URL. TYPE: str | None DEFAULT: None
connection_config	A SiftConnectionConfig object to configure the connection behavior of the SiftClient. TYPE: SiftConnectionConfig | None DEFAULT: None
app_url	The Sift web-app origin (e.g. https://app.siftstack.com). Set this for on-prem or custom deployments whose API host can't be mapped to a frontend automatically; see the app_url property. A value here takes precedence over connection_config.app_url. TYPE: str | None DEFAULT: None

METHOD	DESCRIPTION
get_asyncio_loop	Gets the default asyncio loop used by the gRPC client.

ATTRIBUTE	DESCRIPTION
app_url	The Sift web-app origin for this client, or None if it can't be determined. TYPE: str | None
assets	Instance of the Assets API for making synchronous requests. TYPE: AssetsAPI
async_	Accessor for the asynchronous APIs. All asynchronous APIs are available as attributes on this accessor. TYPE: AsyncAPIs
calculated_channels	Instance of the Calculated Channels API for making synchronous requests. TYPE: CalculatedChannelsAPI
channels	Instance of the Channels API for making synchronous requests. TYPE: ChannelsAPI
data_export	Instance of the Data Export API for making synchronous requests. TYPE: DataExportAPI
data_import	Instance of the Data Import API for making synchronous requests. TYPE: DataImportAPI
file_attachments	Instance of the File Attachments API for making synchronous requests. TYPE: FileAttachmentsAPI
grpc_client	The gRPC client used by the SiftClient for making gRPC API calls. TYPE: GrpcClient
ingestion	Instance of the Ingestion API for making synchronous requests. TYPE: IngestionAPIAsync
jobs	Instance of the Jobs API for making synchronous requests. TYPE: JobsAPI
ping	Instance of the Ping API for making synchronous requests. TYPE: PingAPI
reports	Instance of the Reports API for making synchronous requests. TYPE: ReportsAPI
rest_client	The REST client used by the SiftClient for making REST API calls. TYPE: RestClient
rules	Instance of the Rules API for making synchronous requests. TYPE: RulesAPI
runs	Instance of the Runs API for making synchronous requests. TYPE: RunsAPI
tags	Instance of the Tags API for making synchronous requests. TYPE: TagsAPI
test_results	Instance of the Test Results API for making synchronous requests. TYPE: TestResultsAPI

app_url property

app_url: str | None

The Sift web-app origin for this client, or None if it can't be determined.

Uses the explicit override passed at construction when set, otherwise derives the origin from the REST host for known Sift deployments (e.g. https://api.siftstack.com -> https://app.siftstack.com). Returns None for unrecognized hosts with no override.

TODO: Add a WithAppPage mixin on BaseType so resources (TestReport,

Run, ...) can expose their own web-app link from _client.app_url plus

a per-type path, instead of callers assembling paths by hand.

assets instance-attribute

assets: AssetsAPI = AssetsAPI(self)

Instance of the Assets API for making synchronous requests.

async_ instance-attribute

async_: AsyncAPIs = AsyncAPIs(
    ping=PingAPIAsync(self),
    assets=AssetsAPIAsync(self),
    calculated_channels=CalculatedChannelsAPIAsync(self),
    channels=ChannelsAPIAsync(self),
    file_attachments=FileAttachmentsAPIAsync(self),
    ingestion=IngestionAPIAsync(self),
    jobs=JobsAPIAsync(self),
    reports=ReportsAPIAsync(self),
    rules=RulesAPIAsync(self),
    runs=RunsAPIAsync(self),
    tags=TagsAPIAsync(self),
    test_results=TestResultsAPIAsync(self),
    data_export=DataExportAPIAsync(self),
    data_import=DataImportAPIAsync(self),
)

Accessor for the asynchronous APIs. All asynchronous APIs are available as attributes on this accessor.

calculated_channels instance-attribute

calculated_channels: CalculatedChannelsAPI = (
    CalculatedChannelsAPI(self)
)

Instance of the Calculated Channels API for making synchronous requests.

channels instance-attribute

channels: ChannelsAPI = ChannelsAPI(self)

Instance of the Channels API for making synchronous requests.

data_export instance-attribute

data_export: DataExportAPI = DataExportAPI(self)

Instance of the Data Export API for making synchronous requests.

data_import instance-attribute

data_import: DataImportAPI = DataImportAPI(self)

Instance of the Data Import API for making synchronous requests.

file_attachments instance-attribute

file_attachments: FileAttachmentsAPI = FileAttachmentsAPI(
    self
)

Instance of the File Attachments API for making synchronous requests.

grpc_client property

grpc_client: GrpcClient

The gRPC client used by the SiftClient for making gRPC API calls.

ingestion instance-attribute

ingestion: IngestionAPIAsync

Instance of the Ingestion API for making synchronous requests.

jobs instance-attribute

jobs: JobsAPI = JobsAPI(self)

Instance of the Jobs API for making synchronous requests.

ping instance-attribute

ping: PingAPI = PingAPI(self)

Instance of the Ping API for making synchronous requests.

reports instance-attribute

reports: ReportsAPI = ReportsAPI(self)

Instance of the Reports API for making synchronous requests.

rest_client property

rest_client: RestClient

The REST client used by the SiftClient for making REST API calls.

rules instance-attribute

rules: RulesAPI = RulesAPI(self)

Instance of the Rules API for making synchronous requests.

runs instance-attribute

runs: RunsAPI = RunsAPI(self)

Instance of the Runs API for making synchronous requests.

tags instance-attribute

tags: TagsAPI = TagsAPI(self)

Instance of the Tags API for making synchronous requests.

test_results instance-attribute

test_results: TestResultsAPI = TestResultsAPI(self)

Instance of the Test Results API for making synchronous requests.

get_asyncio_loop

get_asyncio_loop() -> AbstractEventLoop

Gets the default asyncio loop used by the gRPC client.

RETURNS	DESCRIPTION
AbstractEventLoop	The default asyncio loop.

SiftConnectionConfig

SiftConnectionConfig(
    grpc_url: str,
    rest_url: str,
    api_key: str,
    use_ssl: bool = True,
    cert_via_openssl: bool = False,
    app_url: str | None = None,
)

Configuration for Grpc and Rest connections.

This class provides a unified configuration for both gRPC and REST connections, allowing for consistent settings across different transport protocols.

Initialize the connection configuration.

PARAMETER	DESCRIPTION
grpc_url	The URL for the gRPC service. TYPE: str
rest_url	The URL for the REST service. TYPE: str
api_key	The API key for authentication. TYPE: str
use_ssl	Whether to use SSL/TLS for secure connections. TYPE: bool DEFAULT: True
cert_via_openssl	Whether to use OpenSSL for certificate validation. TYPE: bool DEFAULT: False
app_url	The Sift web-app origin (e.g. https://app.siftstack.com). Set this for on-prem or custom deployments whose API host can't be mapped to a frontend automatically. When unset, the web-app URL is derived from rest_url for known hosts. TYPE: str | None DEFAULT: None

METHOD	DESCRIPTION
get_grpc_config	Create and return a GrpcConfig with the current settings.
get_rest_config	Create and return a RestConfig with the current settings.

ATTRIBUTE	DESCRIPTION
api_key
app_url
cert_via_openssl
grpc_url
rest_url
use_ssl

api_key instance-attribute

api_key = api_key

app_url instance-attribute

app_url = app_url

cert_via_openssl instance-attribute

cert_via_openssl = cert_via_openssl

grpc_url instance-attribute

grpc_url = grpc_url

rest_url instance-attribute

rest_url = rest_url

use_ssl instance-attribute

use_ssl = use_ssl

get_grpc_config

get_grpc_config()

Create and return a GrpcConfig with the current settings.

RETURNS	DESCRIPTION
	A GrpcConfig object configured with this instance's settings.

get_rest_config

get_rest_config()

Create and return a RestConfig with the current settings.

RETURNS	DESCRIPTION
	A RestConfig object configured with this instance's settings.