Results & Streaming¶

Structured result types returned by plan() / apply() and the streaming helpers. Import them from the package root:

from libterraform import (
    ApplyResult,
    ChangeSummary,
    OutputChange,
    PlanResult,
    ResourceChange,
    TerraformStream,
)

Result types¶

plan() returns a PlanResult and apply() / destroy() return an ApplyResult. Both subclass CommandResult, so .retcode, .value and .error are unchanged, and add lazily-parsed structured views over the -json output (empty when json=False).

libterraform.cli.PlanResult ¶

Bases: CommandResult

Result of plan().

Adds structured, lazily-parsed views over the -json output. The structured properties are empty when json=False was used. value still holds the raw parsed events, exactly like a plain CommandResult.

PlanResult adds: changes (list[ResourceChange]), drift (list[ResourceChange], resources changed outside Terraform), summary (ChangeSummary) and outputs (list[OutputChange]).

libterraform.cli.ApplyResult ¶

Bases: CommandResult

Result of apply() and destroy().

Adds structured, lazily-parsed views over the -json output. The structured properties are empty when json=False was used.

ApplyResult adds: changes (list[ResourceChange]), summary (ChangeSummary) and outputs (list[OutputChange]).

Models¶

The structured properties return these dataclasses.

libterraform.models.ResourceChange `dataclass` ¶

A single resource that Terraform plans to change or has changed.

action is Terraform's own verb, one of create, update, delete, read, replace, import, move, forget or no-op.

Field	Type	Description
`address`	`str`	Resource address, e.g. `module.app.aws_instance.web`.
`action`	`str`	Terraform action: `create`, `update`, `delete`, `replace`, `read`, `import`, `move`, `forget` or `no-op`.
`resource_type`	`str`	Resource type, e.g. `aws_instance`.
`name`	`str`	Resource name.
`module`	`str`	Module path (empty for the root module).
`provider`	`Optional[str]`	Implied provider.

libterraform.models.ChangeSummary `dataclass` ¶

Counts from a Terraform change_summary event.

import_ carries the import count (import is a Python keyword).

Field	Type	Description
`add`	`int`	Resources to add.
`change`	`int`	Resources to change.
`remove`	`int`	Resources to remove.
`import_`	`int`	Resources to import (`import` is a Python keyword).
`operation`	`str`	`plan` or `apply`.

libterraform.models.OutputChange `dataclass` ¶

A planned or applied change to a root module output value.

Field	Type	Description
`name`	`str`	Output name.
`action`	`str`	Change action for the output.
`sensitive`	`bool`	Whether the output is sensitive.

Streaming¶

The stream() / plan_stream() / apply_stream() methods return a TerraformStream. Iterating it yields parsed -json events (or text lines when json=False); after iteration, retcode and stderr are set. Use it as a context manager (or call close()) to stop early, and cancel() to request cooperative cancellation.

libterraform.cli.TerraformStream ¶

Streaming view over a running Terraform command.

Iterating yields output as the command produces it: parsed -json events when json=True (the default), or raw text lines otherwise. The command runs in a background thread, so the event loop / caller sees output live instead of waiting for the command to finish.

After iteration completes, retcode and stderr are populated. If check=True and the command failed, iteration raises TerraformCommandError at the end. Use it as a context manager (or call close()) to stop a long-running command early; cancel() requests cooperative cancellation explicitly.