Structured API

Define a bare structured API, useful for interfaces that don't need to be portable across multiple platforms. E.G. embedded applications targeting a single architecture.

Installation

pipx install struct-writer

Usage

Basic Usage

Define the API in TOML or another markup language.

[file]
brief = 'Command set for a thermostat'
description = 'Provides basic debug commands for a thermostat.  Allows for both imperial and metric units.'

[commands]
description = "Debug commands for thermostat"
display_name = "Thermostat command"
type = "group"

[cmd_reset]
description = "Request a software reset"
display_name = "reset request"
size = 0
type = "structure"
groups.commands = { value = 1, name = "reset" }

[cmd_temperature_set]
description = "Request a change in temperature"
display_name = "Request temperature change"
members = [
  { name = "temperature", size = 2, type = 'int', description = 'Desired temperature' },
  { name = "units", size = 1, type = 'temperature_units', description = 'Selected temperature unit' },
]
size = 3
type = "structure"
groups.commands = { value = 2, name = "temperature_set" }

This will generate code that looks like this for c by default

/**
 * @file
 * @brief Command set for a thermostat
 *
 * Provides basic debug commands for a thermostat.  Allows for both imperial and
 * metric units.
 *
 * @note This file is autogenerated using structured_api
 */
#ifndef STRUCTURES_H_
#define STRUCTURES_H_
#ifdef __cplusplus
extern "C" {
#endif

#include <static_assert.h>
#include <stdint.h>

/// commands tag
/// Enumeration for commands tag
typedef enum commands_tag_e {
    /// @see cmd_reset_t
    commands_tag_reset = 0x1,
    /// @see cmd_temperature_set_t
    commands_tag_temperature_set = 0x2,
} commands_tag_t;
STATIC_ASSERT_TYPE_SIZE(commands_tag_t, 1);

/// reset request
/// Request a software reset
typedef struct cmd_reset_s {
    /// Structure is intentionally empty (zero sized)
    uint8_t empty[0];
} cmd_reset_t;
STATIC_ASSERT_TYPE_SIZE(cmd_reset_t, 0);

/// Request temperature change
/// Request a change in temperature
typedef struct cmd_temperature_set_s {
    /// Desired temperature
    int16_t temperature;
    /// Selected temperature unit
    temperature_units_t units;
} cmd_temperature_set_t;
STATIC_ASSERT_TYPE_SIZE(cmd_temperature_set_t, 3);

/// Thermostat command
/// Debug commands for thermostat
typedef struct commands_u_s {
    /// commands tag
    commands_tag_t tag;
    union {
        /// Request a software reset
        cmd_reset_t reset;
        /// Request a change in temperature
        cmd_temperature_set_t temperature_set;
    } value;
} commands_u_t;
STATIC_ASSERT_TYPE_SIZE(commands_u_t, 4);

#ifdef __cplusplus
}
#endif
#endif // STRUCTURES_H_

An example is given in the examples folder:

struct-writer --input-definition examples/structures.toml --output-file examples/output/structures.h

Customizable templates

Code generation is customizable using templates. If no templates are provided, we use the default C template.

The default template is shown in the examples folder.

struct-writer --input-definition examples/structures.toml --output-file examples/output/structures.h --template-file examples/template_c.toml

Multiple templates

Chain templates together to more tightly specify certain files in a project. For example if a certain file needs specific includes.

struct-writer --input-definition examples/structures.toml --output-file examples/output/structures.h --template-file examples/template_c.toml --template-file examples/packed_templates.toml

development

watchexec.exe --clear --restart  --debounce 500 --exts py,toml "isort . && black . && pytest && struct-writer --input-definition examples/structures.toml --template-files examples/template.toml --output-file examples/output/structures.h && pylint ."

Metadata

Release files for struct_writer 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for struct_writer 0.10.1
File	Size	Uploaded
struct_writer-0.10.1.tar.gz	93.2 kB	Jul 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for struct_writer 0.10.1
File	Interpreter	ABI	Platform	Reset
struct_writer-0.10.1-py3-none-any.whl 32.5 kB Jul 20, 2026	Python 3	none	any	Details

Total release size: 125.7 kB

Release files / struct_writer-0.10.1.tar.gz

Download URL	struct_writer-0.10.1.tar.gz
Size	93.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`fa48edbd419b669388d1563c81940b06904506fa00ca84736a960ed4c52a466c`
BLAKE2b-256 checksum How to use checksums	`d81c9dd6f7cad7708a77c2f80431ccdbd6d5417c4c8e212b690d22e664f96ab5`
Upload date	Jul 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.27 {"installer":{"name":"uv","version":"0.9.27","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.2","id":"zara","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / struct_writer-0.10.1-py3-none-any.whl

Download URL	struct_writer-0.10.1-py3-none-any.whl
Size	32.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9454176ed9092d63be63de57884c7e71d2fe68395cdaba51053b2d951193f2cf`
BLAKE2b-256 checksum How to use checksums	`56c1086b9ba92222c121c338a5130d41bd87201b7388d4404f77ad581b7a0816`
Upload date	Jul 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.27 {"installer":{"name":"uv","version":"0.9.27","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.2","id":"zara","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`