Skip to main content

struct

The struct function creates a record with named fields. Use it to group related values and read them with dot syntax, such as service.name or service.port.

Usage​

service = struct(name="api", port=8080)
print(service.name)  # api
output = service    # {"name":"api","port":8080}

Arguments​

Any number of keyword arguments. Each keyword becomes a field with the supplied value. Positional arguments are rejected. struct() creates an empty record; struct(**fields) creates one from a dictionary of string keys.

Returns​

A value of type struct. Fields can hold any Starlark value, including other structs and functions. Use dir(record) to list field names, and getattr or hasattr for dynamic field access.

Fields cannot be reassigned, added, or deleted. Collections stored in fields remain mutable until frozen by module loading or parallel execution:

record = struct(names=[])
record.names.append("api")  # allowed before the record is frozen

For a library's functions, use module.load to create a namespace directly from a file without listing its functions again.

JSON and output​

Data-only structs encode as JSON objects through json.encode and the output global. Every field must be JSON-encodable. A struct containing a function fails encoding, just as a dictionary containing a function does.

Errors​

  • Positional arguments fail with struct: unexpected positional arguments.
  • Reading a field that does not exist fails with a missing-attribute error.
  • Assigning a field fails; construct a new record instead.
  • Mutating a nested collection after freezing fails with a frozen-value error.

struct is available in automation scripts and their loaded files, including standalone tools, script steps, and hooks. It is not available in YAML !starlark expressions or policy predicates.

Related​