Types

This page documents every type alias, protocol, and Literal union exported by the SDK. You use these when type-annotating your own code or when reading signature documentation.

JSONValue

from optixlog import JSONValue

Definition

JSONValue = dict[str, Any] | list[Any] | str | int | float | bool | None

A recursive type alias for any JSON-serialisable value. Used for:

• The return type of IngestibleNode.to_payload().
• Fields typed as json / object / array in the codegen schema.
• WorkflowNode.properties values after deserialisation.

Order

from optixlog import Order

Definition

Order = Literal["asc", "desc"]

Sort direction accepted by every .list() and .iter() call. See Pagination for usage examples.

IngestibleNode protocol

from optixlog.pipeline import IngestibleNode

Definition

class IngestibleNode(Protocol):
    def to_payload(self) -> dict[str, JSONValue]: ...

Any class that implements to_payload() satisfies this protocol. Generated node classes (SimulationNode, MeasurementNode, etc.) satisfy it automatically. You can also write a custom class:

from optixlog import JSONValue
from optixlog.pipeline import IngestibleNode

class MyCustomNode:
    def to_payload(self) -> dict[str, JSONValue]:
        return {"field": "value"}

# MyCustomNode satisfies IngestibleNode — no explicit inheritance needed

The class name (type(data).__name__) is sent to the server as the node_type field. The server resolves this against the project's registered labels.

Management API Literal types

All of the following are importable from optixlog.management.

TeamInclude

TeamInclude = Literal["counts"]

Pass include=["counts"] to TeamCollection.get(), list(), iter(), one(), or first() to populate Team.member_count.

MembershipInclude

MembershipInclude = Literal["user", "team"]

Pass to TeamMembershipCollection methods:

• "user" — populate TeamMembership.user with a full User object.
• "team" — populate TeamMembership.team with a full Team object.

WorkflowNodeInclude

WorkflowNodeInclude = Literal["label", "properties", "attachments", "parents", "children"]

Pass to WorkflowNodeCollection methods to populate optional fields on WorkflowNode:

• "label" → WorkflowNode.label_ref
• "properties" → WorkflowNode.properties
• "attachments" → WorkflowNode.attachments
• "parents" → WorkflowNode.parent_refs
• "children" → WorkflowNode.child_refs

AuditLevel

AuditLevel = Literal["debug", "info", "warn", "error"]

Filter parameter for AuditEventCollection. Pass as level= to restrict results to a single severity level.

AuditTargetType

AuditTargetType = Literal[
    "organization",
    "project",
    "team",
    "user",
    "workflow_node",
    "file",
    "invitation",
    "permission_group",
]

Filter parameter for AuditEventCollection. Pass as target_type= to fetch only events that affect a particular entity type.

OrderBy Literal types

These control the sort field for each collection's .list() and .iter() calls.

TeamOrderBy

TeamOrderBy = Literal["name", "created_at", "updated_at", "category"]

Default: "name".

MembershipOrderBy

MembershipOrderBy = Literal["joined_at", "role", "user_name"]

Default: "joined_at".

MemberOrderBy

MemberOrderBy = Literal["name", "email", "created_at", "updated_at"]

Default: "name". Used by ManagementProject.get_all_members().

WorkflowNodeOrderBy

WorkflowNodeOrderBy = Literal["created_at", "updated_at", "display_name", "label"]

Default: "created_at" with order="desc" (newest-first).

LabelOrderBy

LabelOrderBy = Literal["name", "id"]

Default: "name". Used by WorkflowNodeLabelCollection.

AuditOrderBy

AuditOrderBy = Literal["timestamp", "action", "level"]

Default: "timestamp" with order="desc" (most-recent-first).

Quick reference: all type imports

# Core types
from optixlog import JSONValue, Order, Page, EntityRef, ProjectRef

# Protocol
from optixlog.pipeline import IngestibleNode

# Include literals
from optixlog.management import (
    TeamInclude,
    MembershipInclude,
    WorkflowNodeInclude,
    AuditLevel,
    AuditTargetType,
)

# OrderBy literals
from optixlog.management import (
    TeamOrderBy,
    MembershipOrderBy,
    MemberOrderBy,
    WorkflowNodeOrderBy,
    LabelOrderBy,
    AuditOrderBy,
)