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¶

Use sync APIs for notebooks, scripts, and simple applications
Use async APIs for high-performance services with concurrent operations
Leverage filtering to reduce data transfer and improve performance
Reuse client instances rather than creating new ones for each operation
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`	Sift pytest plugin: records each test as a step in a Sift test report.
`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.
`CacheNamespace`	Resource-agnostic surface for the on-disk cache shared by all resources.
`CacheStats`	Snapshot of the shared on-disk cache at call time.

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
`ping`	Instance of the Ping API for making synchronous requests. TYPE: `PingAPI`
`assets`	Instance of the Assets API for making synchronous requests. TYPE: `AssetsAPI`
`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`
`file_attachments`	Instance of the File Attachments API for making synchronous requests. TYPE: `FileAttachmentsAPI`
`ingestion`	Instance of the Ingestion API for making synchronous requests. TYPE: `IngestionAPIAsync`
`jobs`	Instance of the Jobs API for making synchronous requests. TYPE: `JobsAPI`
`reports`	Instance of the Reports API for making synchronous requests. TYPE: `ReportsAPI`
`rules`	Instance of the Rules API for making synchronous requests. TYPE: `RulesAPI`
`runs`	Instance of the Runs API for making synchronous requests. TYPE: `RunsAPI`
`access_control`	Access-control APIs for configuring who can access what in Sift. TYPE: `AccessControlAPI`
`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`
`users`	Instance of the Users API for making synchronous requests. TYPE: `UsersAPI`
`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`
`cache`	Surface for the shared on-disk cache used by every cache-aware resource. TYPE: `CacheNamespace`
`async_`	Accessor for the asynchronous APIs. All asynchronous APIs are available as attributes on this accessor. TYPE: `AsyncAPIs`
`grpc_client`	The gRPC client used by the SiftClient for making gRPC API calls. TYPE: `GrpcClient`
`is_loop_running`	Whether the background event loop is still accepting synchronous API work. TYPE: `bool`
`rest_client`	The REST client used by the SiftClient for making REST API calls. TYPE: `RestClient`
`app_url`	The Sift web-app origin for this client, or None if it can't be determined. TYPE: `str \| None`

ping `instance-attribute` ¶

ping: PingAPI = PingAPI(self)

Instance of the Ping API for making synchronous requests.

assets `instance-attribute` ¶

assets: AssetsAPI = AssetsAPI(self)

Instance of the Assets API for making synchronous requests.

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.

file_attachments `instance-attribute` ¶

file_attachments: FileAttachmentsAPI = FileAttachmentsAPI(
    self
)

Instance of the File Attachments API for making synchronous requests.

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.

reports `instance-attribute` ¶

reports: ReportsAPI = ReportsAPI(self)

Instance of the Reports API for making synchronous requests.

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.

access_control `instance-attribute` ¶

access_control: AccessControlAPI = AccessControlAPI(
    resource_attributes=ResourceAttributesAPI(self),
    principal_attributes=PrincipalAttributesAPI(self),
)

Access-control APIs for configuring who can access what in Sift.

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.

users `instance-attribute` ¶

users: UsersAPI = UsersAPI(self)

Instance of the Users 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.

cache `instance-attribute` ¶

cache: CacheNamespace = CacheNamespace(self)

Surface for the shared on-disk cache used by every cache-aware resource.

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),
    access_control=AccessControlAPIAsync(
        resource_attributes=ResourceAttributesAPIAsync(
            self
        ),
        principal_attributes=PrincipalAttributesAPIAsync(
            self
        ),
    ),
    tags=TagsAPIAsync(self),
    test_results=TestResultsAPIAsync(self),
    users=UsersAPIAsync(self),
    data_export=DataExportAPIAsync(self),
    data_import=DataImportAPIAsync(self),
)

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

grpc_client `property` ¶

grpc_client: GrpcClient

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

is_loop_running `property` ¶

is_loop_running: bool

Whether the background event loop is still accepting synchronous API work.

rest_client `property` ¶

rest_client: RestClient

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

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.¶

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`
`grpc_url`
`rest_url`
`use_ssl`
`cert_via_openssl`
`app_url`

api_key `instance-attribute` ¶

api_key = api_key

grpc_url `instance-attribute` ¶

grpc_url = grpc_url

rest_url `instance-attribute` ¶

rest_url = rest_url

use_ssl `instance-attribute` ¶

use_ssl = use_ssl

cert_via_openssl `instance-attribute` ¶

cert_via_openssl = cert_via_openssl

app_url `instance-attribute` ¶

app_url = app_url

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.

CacheNamespace ¶

CacheNamespace(client: SiftClient)

Resource-agnostic surface for the on-disk cache shared by all resources.

Exposed as client.cache. The actual handle (:class:~sift_client._internal.disk_cache.DiskCache) is constructed lazily on first use so importing :mod:sift_client doesn't pay the diskcache cost up front. Configuration changes made before that first use are recorded against the client's :class:~sift_client._internal.disk_cache_config.DiskCacheConfig and applied when the store opens; changes after first use are routed directly to the live store.

Default policy: disk caching is opt-out (the config is constructed with enabled=True). Users who don't want any state on disk call :meth:disable to silence it; users who want a custom location or byte cap call :meth:enable with arguments.

Bind this namespace to client. Constructed by :class:SiftClient.

METHOD	DESCRIPTION
`enable`	Enable (or reconfigure) on-disk caching.
`disable`	Opt out of on-disk caching (no reads or writes).
`stats`	Return a snapshot of the current cache state.
`clear`	Delete a previously-persisted on-disk cache directory.

enable ¶

enable(
    *,
    path: str | PathLike[str] | None = None,
    max_bytes: int | None = None,
) -> None

Enable (or reconfigure) on-disk caching.

Disk caching is on by default at :attr:~sift_client._internal.disk_cache.DiskCache.DEFAULT_DISK_PATH; use this method to override the path or size, or to turn the cache back on after a prior :meth:disable call.

Reconfiguring a live cache (different path or max_bytes) closes the previous handle and opens a new one. Existing entries at the new path become available as cache hits.

An explicit path that can't be opened (permission denied, read-only filesystem, ...) raises so the caller knows their request didn't take. The default-path open does not raise — see :meth:SiftClient._get_disk_cache for the silent fall-back.

PARAMETER	DESCRIPTION
`path`	Directory to persist to. `None` (the default) uses the cache's :attr:`DEFAULT_DISK_PATH`. TYPE: `str \| PathLike[str] \| None` DEFAULT: `None`
`max_bytes`	Byte cap on disk usage. `None` uses the cache's :attr:`DEFAULT_DISK_MAX_BYTES` (4 GiB). When the bound is reached, `diskcache`'s LRU eviction takes over. TYPE: `int \| None` DEFAULT: `None`

Example

client.cache.enable(path="/data/sift-cache") client.cache.enable(max_bytes=1024 ** 3) # 1 GiB

disable ¶

disable() -> None

Opt out of on-disk caching (no reads or writes).

Caching is on by default; call this when you don't want any cached data written to or read from disk. Closes any open cache file handle. The on-disk directory is NOT deleted — use :meth:clear to wipe it.

stats ¶

stats() -> CacheStats

Return a snapshot of the current cache state.

Calling this triggers the lazy disk-handle open if it hasn't happened yet (so a stats call on a fresh client doesn't mis-report as disabled just because no resource has touched the store). After the open it's read-only — no mutation or migration.

Channel-specific counts come from walking the keyspace once and counting keys under the channel adapter's namespace prefix. If a second cache-aware resource grows its own key prefix later, extend this method to surface per-adapter counts; for now there's only one adapter so the dedicated field stays flat.

Example

print(client.cache.stats()) Sift cache: path: /tmp/sift-data-cache used: 142.3 MiB / 4.0 GiB (3.5%) channels: 12 buckets, 487 segments entries: 499 total

clear ¶

clear(path: str | PathLike[str] | None = None) -> None

Delete a previously-persisted on-disk cache directory.

Drops stale caches from previous sessions, recovers from a corrupt cache, or reclaims disk space. Removes the directory entirely; if disk caching is on, the next access re-opens an empty cache at the same path.

PARAMETER	DESCRIPTION
`path`	Directory of the cache to clear. `None` (the default) targets the cache's :attr:`~sift_client._internal.disk_cache.DiskCache.DEFAULT_DISK_PATH`. TYPE: `str \| PathLike[str] \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`ValueError`	If `path` exists but does not look like a sift data cache directory.

CacheStats `dataclass` ¶

CacheStats(
    enabled: bool,
    path: str | None,
    max_bytes: int | None,
    size_bytes: int,
    entry_count: int,
    channel_buckets: int,
    channel_segments: int,
)

Snapshot of the shared on-disk cache at call time.

Returned by :meth:CacheNamespace.stats. Frozen dataclass so it plays well with logging, snapshot tests, and "compare two readings" diagnostics without surprise mutation.

Field semantics:

enabled — whether the disk handle is open. When False, all the size/count fields are zero regardless of on-disk state.
path — directory the cache is open against, or None when disabled. Useful for "where does this cache actually live?".
max_bytes — configured byte cap on disk usage, or None when disabled. diskcache's LRU evicts once usage approaches this.
size_bytes — current on-disk usage including SQLite overhead. Tends to trend slightly higher than the sum of per-entry size_bytes the resources hand to the store.
entry_count — total cache keys across all adapter prefixes (channel index + segment rows, plus any future foreign-adapter rows).
channel_buckets — number of distinct (channel_id, run_id) channel buckets currently cached. Counted by walking the channel adapter's index keys; one index per bucket regardless of how many segments live under it.
channel_segments — total cached segment frames across every bucket. Each put_segment call adds one; diskcache LRU evictions can drop them independently of their parent index, so this can be lower than the sum of segments the adapter has written over the session.

str(stats) prints a multi-line summary suitable for notebook/REPL display; the structured fields are available for programmatic checks.

ATTRIBUTE	DESCRIPTION
`enabled`	TYPE: `bool`
`path`	TYPE: `str \| None`
`max_bytes`	TYPE: `int \| None`
`size_bytes`	TYPE: `int`
`entry_count`	TYPE: `int`
`channel_buckets`	TYPE: `int`
`channel_segments`	TYPE: `int`

enabled `instance-attribute` ¶

enabled: bool

path `instance-attribute` ¶

path: str | None

max_bytes `instance-attribute` ¶

max_bytes: int | None

size_bytes `instance-attribute` ¶

size_bytes: int

entry_count `instance-attribute` ¶

entry_count: int

channel_buckets `instance-attribute` ¶

channel_buckets: int

channel_segments `instance-attribute` ¶

channel_segments: int

sift_client ¶

Overview¶

Installation¶

Quick Start¶

Initialize the Client¶

Basic Operations¶

Async Usage¶

Key Components¶

Resources¶

Types¶

Examples¶

Connection Configuration¶

Best Practices¶

SiftClient ¶

ping instance-attribute ¶

assets instance-attribute ¶

calculated_channels instance-attribute ¶

channels instance-attribute ¶

file_attachments instance-attribute ¶

ingestion instance-attribute ¶

jobs instance-attribute ¶

reports instance-attribute ¶

rules instance-attribute ¶

runs instance-attribute ¶

access_control instance-attribute ¶

tags instance-attribute ¶

test_results instance-attribute ¶

users instance-attribute ¶

data_export instance-attribute ¶

data_import instance-attribute ¶

cache instance-attribute ¶

async_ instance-attribute ¶

grpc_client property ¶

is_loop_running property ¶

rest_client property ¶

app_url property ¶

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

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