air_sdk.endpoints.node_instructions | DSX Air Documentation

Stub file for node instructions endpoint type hints.

Classes

Name	Description
`ShellData`	Data structure for shell executor type (input for create).
`_FileDataRequired`	Required fields for FileData.
`FileData`	Data structure for file executor type (input for create).
`InitData`	Data structure for init executor type (input for create).
`ShellDataResponse`	Data structure for shell executor type (returned from API).
`FileDataResponse`	Data structure for file executor type (returned from API).
`InitDataResponse`	Data structure for init executor type (returned from API).
`NodeInstruction`	Node instruction model representing an automation instruction for a node.
`NodeInstructionEndpointAPI`	API client for node instructions endpoints.

Module Contents

class air_sdk.endpoints.node_instructions.ShellData

Bases: typing.TypedDict

Data structure for shell executor type (input for create).

commands: list[str]

class air_sdk.endpoints.node_instructions._FileDataRequired

Bases: typing.TypedDict

Required fields for FileData.

files: list[dict[str, str]]

class air_sdk.endpoints.node_instructions.FileData

Bases: air_sdk.endpoints.node_instructions._FileDataRequired

Data structure for file executor type (input for create).

Required: files - List of file dicts, each with ‘path’ and ‘content’ keys. Optional: post_commands - Shell commands to run after creating files.

post_commands: list[str]

class air_sdk.endpoints.node_instructions.InitData

Bases: typing.TypedDict

Data structure for init executor type (input for create).

hostname: str

class air_sdk.endpoints.node_instructions.ShellDataResponse

Bases: air_sdk.endpoints.node_instructions.ShellData

Data structure for shell executor type (returned from API).

executor: Literal[shell]

class air_sdk.endpoints.node_instructions.FileDataResponse

Bases: air_sdk.endpoints.node_instructions._FileDataRequired

Data structure for file executor type (returned from API).

Required: files - List of file dicts, each with ‘path’ and ‘content’ keys. Optional: post_commands - Shell commands to run after creating files. Optional: executor - Executor type (added by API).

post_commands: list[str]

executor: Literal[file]

class air_sdk.endpoints.node_instructions.InitDataResponse

Bases: air_sdk.endpoints.node_instructions.InitData

Data structure for init executor type (returned from API).

executor: Literal[init]

class air_sdk.endpoints.node_instructions.NodeInstruction

Bases: air_sdk.air_model.AirModel

Node instruction model representing an automation instruction for a node.

Node instructions are commands or automation scripts that can be executed on simulation nodes. They support various executors and can be configured to run again on rebuild.

id: str

Unique identifier for the node instruction

name: str

Human-readable name of the node instruction

node: Node

Node this instruction belongs to

data: ShellDataResponse | FileDataResponse | InitDataResponse

Instruction data (ShellData, FileData, or InitData)

created: datetime.datetime

Timestamp when the node instruction was created

modified: datetime.datetime

Timestamp when the node instruction was last modified

state: str

Execution state (e.g., ‘pending’, ‘running’, ‘completed’, ‘failed’)

run_again_on_rebuild: bool

Whether to re-run this instruction on simulation rebuild

get_model_api() -> type[NodeInstructionEndpointAPI]

model_api: NodeInstructionEndpointAPI

update(
    *,
    name: str | None = ...,
    run_again_on_rebuild: bool | None = ...
) -> None

Update the node instruction’s properties.

Parameters:

name – New name for the node instruction
run_again_on_rebuild – Whether to re-run the instruction on simulation rebuild

Example:

>>> instruction = api.node_instructions.get('instruction-id')
>>> instruction.update(name='New Name', run_again_on_rebuild=True)

delete() -> None

Delete this instruction.

Example:

>>> instruction = api.node_instructions.get('instruction-id')
>>> instruction.delete()

class air_sdk.endpoints.node_instructions.NodeInstructionEndpointAPI

Bases: air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.node_instructions.NodeInstruction]

API client for node instructions endpoints.

API_PATH: str

model: type[NodeInstruction]

create(
    *,
    node: str | PrimaryKey,
    executor: Literal[shell, init, file],
    data: ShellData | FileData | InitData,
    name: str | None = ...,
    run_again_on_rebuild: bool | None = ...
) -> NodeInstruction

Create a new node instruction.

Parameters:

node – Node object or ID to execute the instruction on
name – Name for the instruction
executor – Type of executor (‘shell’, ‘init’, ‘file’)
data – Instruction data/payload (executor-specific): ShellData - For ‘shell’ executor Contains: ‘commands’ (list of shell commands) FileData - For ‘file’ executor Contains: ‘files’ (list of dicts with ‘path’ and ‘content’) Optional: ‘post_commands’ (shell commands to run after creating files) InitData - For ‘init’ executor Contains: ‘hostname’ (hostname to set for the node)
run_again_on_rebuild – Optional whether to run instruction again on rebuild

Returns:

The created NodeInstruction instance

Example:

>>> # Create shell instruction
>>> instruction = api.node_instructions.create(
...     name='Setup Script',
...     node='node-id',
...     executor='shell',
...     data=ShellData(commands=['#!/bin/bash\necho "Hello"']),
...     run_again_on_rebuild=True,
... )
>>> # Create file instruction
>>> instruction = api.node_instructions.create(
...     name='Install Package',
...     node='node-id',
...     executor='file',
...     data=FileData(
...         files=[{'path': 'package.txt', 'content': 'package=1.0.0'}],
...         post_commands=['#!/bin/bash\necho "Hello"'],
...     ),
...     run_again_on_rebuild=True,
... )
>>> # Create init instruction
>>> instruction = api.node_instructions.create(
...     name='Initialize Environment',
...     node='node-id',
...     executor='init',
...     data=InitData(hostname='my-node'),
...     run_again_on_rebuild=True,
... )

list(
    *,
    created_by_client: bool = ...,
    executor: Literal[shell, init, file] = ...,
    name: str = ...,
    node: str = ...,
    run_again_on_rebuild: bool = ...,
    simulation: str = ...,
    state: str = ...,
    search: str = ...,
    ordering: str = ...,
    limit: int = ...,
    offset: int = ...
) -> Iterator[NodeInstruction]

List all node instructions.

Parameters:

created_by_client – Filter by created by client
executor – Filter by executor (‘shell’, ‘init’, ‘file’)
name – Filter by name
node – Filter by node
run_again_on_rebuild – Filter by run_again_on_rebuild
simulation – Filter by simulation
state – Filter by state
search – Search by name
ordering – Order by field
limit – Limit the number of results
offset – Offset the results

Returns:

Iterator of NodeInstruction instances

Example:

>>> # List all instructions for a node
>>> for instruction in api.node_instructions.list(node='node-id'):
...     print(instruction.name)
>>> # List with multiple filters
>>> for instruction in api.node_instructions.list(
...     simulation='sim-id',
...     executor='shell',
...     state='complete',
...     ordering='-created',
... ):
...     print(instruction.name, instruction.state)

get(pk: PrimaryKey) -> NodeInstruction

Get a specific node instruction by ID.

Parameters:

pk – The node instruction ID (string or UUID)

Returns:

The NodeInstruction instance

Example:

>>> instruction = api.node_instructions.get('instruction-id')
>>> print(instruction.name)

patch(
    *,
    pk: PrimaryKey,
    name: str | None | dataclasses._MISSING_TYPE = ...,
    run_again_on_rebuild: bool | None | dataclasses._MISSING_TYPE = ...
) -> NodeInstruction

Partially update a node instruction.

Parameters:

pk – The node instruction ID
name – New name for the instruction
run_again_on_rebuild – Whether to run again on rebuild

Returns:

The updated NodeInstruction instance

Example:

>>> instruction = api.node_instructions.patch(
...     'instruction-id',
...     name='Updated Name',
...     run_again_on_rebuild=True
... )

delete(pk: PrimaryKey) -> None

Delete a node instruction.

Parameters:

pk – The node instruction ID

Example:

>>> api.node_instructions.delete('instruction-id')