API Reference

Use this reference to explore the Python modules that make up the scaffolder. Narrative explanations live in Architecture; this section links to the code-level API for each component.

Entry Points

octopus_widget_scaffolder

Command-line driver that normalises arguments, parses JSON payloads, and invokes scaffolder.generator.scaffold_widget. Handles both inline GraphQL operations and external files through mutually exclusive CLI flags.

octopus_widget_scaffolder.py - CLI entry point for the widget scaffolder.

octopus_widget_scaffolder.to_pascal(name)[source]
Parameters:

name (str)

Return type:

str

octopus_widget_scaffolder.main(argv=None)[source]
Parameters:

argv (list[str] | None)

Return type:

None

app

FastAPI application powering the browser UI. Streams progress updates over chunked HTTP responses so the frontend can update the activity log in real time. Includes endpoints for health checks, widget generation, and zip downloads.

FastAPI front-end for the Octopus widget scaffolder.

app.to_pascal(name)[source]
Parameters:

name (str)

Return type:

str

async app.index(request)[source]
Parameters:

request (Request)

Return type:

HTMLResponse

async app.generate(pascal=Form(), app_id=Form(), ops=Form(), features=Form())[source]
Parameters:
Return type:

Response

async app.download(filename)[source]
Parameters:

filename (str)

Return type:

FileResponse

Generators

scaffolder.generator

Coordinates name transformations, GraphQL preparation, template rendering, and archive creation. Extensible via dependency injection for custom template folders.

scaffolder/generator.py - now only supports ‘widget’ kind 2025-06-22 (fixed header/variable injection per-operation)

scaffolder.generator.to_pascal(name)[source]
Parameters:

name (str)

Return type:

str

scaffolder.generator.normalize_feature_flags(raw)[source]
Parameters:

raw (dict | None)

Return type:

dict[str, bool]

scaffolder.generator.build_feature_schema_parts(flags)[source]
Parameters:

flags (dict[str, bool])

Return type:

tuple[dict[str, object], dict[str, str], dict[str, str], str]

scaffolder.generator.scaffold_widget(pascal, kind, *, operations, var_defaults, var_types, app_id, feature_flags=None)[source]
Parameters:

scaffolder.widget_generator

Owns the React component rendering logic. Builds TypeScript that imports only the required Octopus SDK hooks, wires up mutations, and exposes typed configuration props.

scaffolder/widget_generator.py - Generates the default <Widget>.tsx file

scaffolder.widget_generator.generate_widget(pascal, camel, var_defaults, var_types, operations, dest, *, feature_flags=None, extra_props=None, widget_options=None)[source]
Parameters:
Return type:

None

scaffolder.utils

Shared helpers for naming, GraphQL manipulation, JSON schema generation, and filesystem writes. Used by both CLI and UI flows.

scaffolder/utils.py - Utility functions for scaffolder/generator.py

scaffolder.utils.ensure_dir_permissions(path)[source]
Parameters:

path (Path)

Return type:

None

scaffolder.utils.ensure_file_permissions(path)[source]
Parameters:

path (Path)

Return type:

None

scaffolder.utils.ensure_dir_chain_permissions(path)[source]
Parameters:

path (Path)

Return type:

None

scaffolder.utils.pascal_to_kebab(n)[source]
Parameters:

n (str)

Return type:

str

scaffolder.utils.pascal_to_camel(n)[source]
Parameters:

n (str)

Return type:

str

scaffolder.utils.js_lit(v)[source]
scaffolder.utils.gql_to_json_type(gql_type)[source]
Parameters:

gql_type (str)

Return type:

str

Tests and Fixtures

The unit tests live under tests/ and double as usage examples. Refer to tests/test_templates.py for assertions that guard template coverage and placeholder substitution. Updating templates usually requires extending these fixtures.