API Reference

Sphinx extension for literalizer.

Provides literal, call, and native invocation directives, which read data files and render combined native language code blocks.

class sphinx_literalizer.LiteralizerCallDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive that converts a data file to function call expressions.

Usage:

.. literalizer-call:: path/to/data.json
   :language: python
   :target-function: my_func
   :parameter-names: flag,count,name
   :per-element:
   :call-style: keyword
   :call-transform: print($call)  # $call ($0), $index, $zipped
   :zip-file: expected.json
   :zip-input-format: json
   :comment-file: comments.txt
   :input-format: json
   :indent: 4
   :indent-char: spaces
   :include-preamble:
   :preamble-only:
   :omit-code:
   :ref-case: camel
   :ref-key: $reference
   :module-name: MyModule
   :record-struct-name-prefix: Record
   :record-shape-names: x,y=Point; a,b,c=Vec3
   :heterogeneous-value-name: Value
   :consumable-refs: my_var,other_var
   :collection-layout: multiline
   :heterogeneous-strategy: auto
   :skip-if-unrepresentable:
   :variable-name: my_data
   :existing-variable:
   :modifiers: public,static

.. literalizer-call:: path/to/no_args.yaml
   :language: rust
   :constructor-class: Widget
   :per-element:
   :variable-name: widget

:input-root-key: selects call input from a mapping entry before rendering, using Literalizer’s parser so comments and source metadata are retained. This supports TOML tables such as calls = [["Ada"], ["Grace"]] with :input-root-key: calls. With :per-element:, each selected row becomes a call; without it, the selected value supplies the arguments to one call.

:call-transform: substitutes these placeholders in the template: $call (and the $0 alias) for the rendered call expression, $index for the zero-based call position, and $zipped for the matching :zip-file: element rendered as a native literal (empty when no :zip-file: is given).

Use exactly one of :target-function: and :constructor-class:. :constructor-class: formats a language-specific zero-argument constructor target and then renders through the same call machinery as :target-function:.

:comment-file: is a text file with one line per generated call; each non-blank line is emitted as a trailing source comment after that call (using the target language’s comment syntax), and a blank line emits no comment. The line count must match the number of generated calls.

An empty (or omitted) :parameter-names: means the call takes no arguments. Combined with :per-element: over a single-element source (e.g. - []) and :variable-name:, this renders a no-argument constructor bound to a variable – p1 = Playlist() / let p1 = Playlist::new(); / auto p1 = Playlist(); – in the target language’s idiom.

option_spec: ClassVar[dict[str, _OptionValidator] | None] = {'annotation-evaluation': <function _make_format_validator.<locals>.validator>, 'bool-format': <function _make_format_validator.<locals>.validator>, 'bytes-format': <function _make_format_validator.<locals>.validator>, 'call-style': <function _make_format_validator.<locals>.validator>, 'call-transform': <function unchanged_required>, 'collection-layout': <function <lambda>>, 'comment-file': <function unchanged_required>, 'comment-format': <function _make_format_validator.<locals>.validator>, 'constructor-class': <function unchanged_required>, 'consumable-refs': <function unchanged>, 'date-format': <function _make_format_validator.<locals>.validator>, 'datetime-format': <function _make_format_validator.<locals>.validator>, 'declaration-style': <function _make_format_validator.<locals>.validator>, 'default-dict-key-type': <function unchanged>, 'default-dict-value-type': <function unchanged>, 'default-ordered-map-value-type': <function unchanged>, 'default-sequence-element-type': <function unchanged>, 'default-set-element-type': <function unchanged>, 'dict-entry-style': <function _make_format_validator.<locals>.validator>, 'dict-format': <function _make_format_validator.<locals>.validator>, 'empty-dict-key': <function _make_format_validator.<locals>.validator>, 'existing-variable': <function flag>, 'expand-call-stubs': <function _boolean_option>, 'float-format': <function _make_format_validator.<locals>.validator>, 'heterogeneous-strategy': <function _heterogeneous_strategy_validator>, 'heterogeneous-value-name': <function unchanged_required>, 'include-preamble': <function flag>, 'indent': <function nonnegative_int>, 'indent-char': <function <lambda>>, 'indent-file-body': <function _boolean_option>, 'initial-column': <function nonnegative_int>, 'input-format': <function <lambda>>, 'input-root-key': <function unchanged_required>, 'integer-format': <function _make_format_validator.<locals>.validator>, 'json-rendering': <function _make_format_validator.<locals>.validator>, 'json-type': <function _make_format_validator.<locals>.validator>, 'language': <function <lambda>>, 'language-version': <function _make_format_validator.<locals>.validator>, 'modifiers': <function unchanged>, 'module-name': <function unchanged>, 'multiline-raw-string-delimiter-base': <function unchanged_required>, 'native-align-selectors': <function _boolean_option>, 'native-argument-layout': <function _make_format_validator.<locals>.validator>, 'native-collection-layout': <function _make_format_validator.<locals>.validator>, 'native-column-limit': <function positive_int>, 'native-continuation-indent': <function nonnegative_int>, 'numeric-literal-suffix': <function _make_format_validator.<locals>.validator>, 'numeric-separator': <function _make_format_validator.<locals>.validator>, 'numeric-style': <function _make_format_validator.<locals>.validator>, 'omit-code': <function flag>, 'parameter-names': <function unchanged>, 'per-element': <function flag>, 'pre-indent-level': <function nonnegative_int>, 'preamble-only': <function flag>, 'record-map-value-typing': <function _make_format_validator.<locals>.validator>, 'record-shape-names': <function unchanged_required>, 'record-struct-name-prefix': <function unchanged_required>, 'ref-case': <function <lambda>>, 'ref-key': <function unchanged_required>, 'sequence-format': <function _make_format_validator.<locals>.validator>, 'set-format': <function _make_format_validator.<locals>.validator>, 'skip-if-unrepresentable': <function flag>, 'string-format': <function _make_format_validator.<locals>.validator>, 'target-function': <function unchanged_required>, 'trailing-comma': <function _make_format_validator.<locals>.validator>, 'union-format': <function _make_format_validator.<locals>.validator>, 'variable-name': <function unchanged>, 'variable-type-hints': <function _make_format_validator.<locals>.validator>, 'wrap-in-file': <function flag>, 'zip-file': <function unchanged_required>, 'zip-input-format': <function LiteralizerCallDirective.<lambda>>}

Mapping of option names to validator functions.

class sphinx_literalizer.LiteralizerDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive that converts a data file to a native literal block.

Usage:

.. literalizer:: path/to/data.json
   :language: python
   :input-format: json
   :pre-indent-level: 2
   :indent: 4
   :indent-char: spaces
   :include-delimiters:
   :include-preamble:
   :preamble-only:
   :date-format: python
   :datetime-format: python
   :variable-name: my_var
   :reference-name: my_var
   :existing-variable:
   :both-variable-forms:
   :sequence-format: list
   :set-format: frozenset
   :bytes-format: python
   :comment-format: block
   :variable-type-hints: always
   :declaration-style: const
   :dict-entry-style: rocket
   :dict-format: object
   :float-format: repr
   :integer-format: decimal
   :numeric-literal-suffix: none
   :numeric-separator: none
   :numeric-style: overloaded
   :string-format: double
   :trailing-comma: yes
   :language-version: py39
   :empty-dict-key: positional
   :heterogeneous-strategy: auto
   :json-type: serde_json_value
   :json-rendering: inline_document
   :record-map-value-typing: wide
   :bool-format: json_pp_ref
   :default-set-element-type: String
   :default-sequence-element-type: String
   :default-dict-key-type: String
   :default-dict-value-type: String
   :default-ordered-map-value-type: any
   :modifiers: public,static,final
   :module-name: MyModule
   :record-struct-name-prefix: Record
   :record-shape-names: x,y=Point; a,b,c=Vec3
   :heterogeneous-value-name: Value
   :record-null-substitutions: {"id": -1, "assignee": ""}
   :skip-if-unrepresentable:
   :wrap-in-file:
   :ref-case: camel
   :ref-key: $reference
   :collection-layout: multiline

:heterogeneous-strategy: auto renders the input with its natural representation and, only if that raises because the data is heterogeneous, retries with each strategy the target language supports in the order configured by the literalizer_heterogeneous_strategy_precedence configuration value (default: record, tuple, tagged_enum, object_variant, variant, union_type, interface). This keeps homogeneous and genuinely map-shaped data in its native form while still representing record-shaped or mixed-scalar inputs.

:skip-if-unrepresentable: makes the directive emit no node at all (instead of failing the build) when the input cannot be represented in the target language – including after auto exhausts its precedence – so a per-language loop can skip the languages a given input does not fit without leaking data-shape concerns into prose.

option_spec: ClassVar[dict[str, _OptionValidator] | None] = {'annotation-evaluation': <function _make_format_validator.<locals>.validator>, 'bool-format': <function _make_format_validator.<locals>.validator>, 'both-variable-forms': <function flag>, 'bytes-format': <function _make_format_validator.<locals>.validator>, 'call-style': <function _make_format_validator.<locals>.validator>, 'collection-layout': <function <lambda>>, 'comment-format': <function _make_format_validator.<locals>.validator>, 'date-format': <function _make_format_validator.<locals>.validator>, 'datetime-format': <function _make_format_validator.<locals>.validator>, 'declaration-style': <function _make_format_validator.<locals>.validator>, 'default-dict-key-type': <function unchanged>, 'default-dict-value-type': <function unchanged>, 'default-ordered-map-value-type': <function unchanged>, 'default-sequence-element-type': <function unchanged>, 'default-set-element-type': <function unchanged>, 'dict-entry-style': <function _make_format_validator.<locals>.validator>, 'dict-format': <function _make_format_validator.<locals>.validator>, 'empty-dict-key': <function _make_format_validator.<locals>.validator>, 'existing-variable': <function flag>, 'expand-call-stubs': <function _boolean_option>, 'float-format': <function _make_format_validator.<locals>.validator>, 'heterogeneous-strategy': <function _heterogeneous_strategy_validator>, 'heterogeneous-value-name': <function unchanged_required>, 'include-delimiters': <function flag>, 'include-preamble': <function flag>, 'indent': <function nonnegative_int>, 'indent-char': <function <lambda>>, 'indent-file-body': <function _boolean_option>, 'initial-column': <function nonnegative_int>, 'input-format': <function <lambda>>, 'integer-format': <function _make_format_validator.<locals>.validator>, 'json-rendering': <function _make_format_validator.<locals>.validator>, 'json-type': <function _make_format_validator.<locals>.validator>, 'language': <function <lambda>>, 'language-version': <function _make_format_validator.<locals>.validator>, 'modifiers': <function unchanged>, 'module-name': <function unchanged>, 'multiline-raw-string-delimiter-base': <function unchanged_required>, 'native-align-selectors': <function _boolean_option>, 'native-argument-layout': <function _make_format_validator.<locals>.validator>, 'native-collection-layout': <function _make_format_validator.<locals>.validator>, 'native-column-limit': <function positive_int>, 'native-continuation-indent': <function nonnegative_int>, 'numeric-literal-suffix': <function _make_format_validator.<locals>.validator>, 'numeric-separator': <function _make_format_validator.<locals>.validator>, 'numeric-style': <function _make_format_validator.<locals>.validator>, 'pre-indent-level': <function nonnegative_int>, 'preamble-only': <function flag>, 'record-map-value-typing': <function _make_format_validator.<locals>.validator>, 'record-null-substitutions': <function unchanged_required>, 'record-shape-names': <function unchanged_required>, 'record-struct-name-prefix': <function unchanged_required>, 'ref-case': <function <lambda>>, 'ref-key': <function unchanged_required>, 'reference-name': <function unchanged_required>, 'sequence-format': <function _make_format_validator.<locals>.validator>, 'set-format': <function _make_format_validator.<locals>.validator>, 'skip-if-unrepresentable': <function flag>, 'string-format': <function _make_format_validator.<locals>.validator>, 'trailing-comma': <function _make_format_validator.<locals>.validator>, 'union-format': <function _make_format_validator.<locals>.validator>, 'variable-name': <function unchanged>, 'variable-type-hints': <function _make_format_validator.<locals>.validator>, 'wrap-in-file': <function flag>}

Mapping of option names to validator functions.

class sphinx_literalizer.LiteralizerGroupDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Hoist requested preambles before a group of code fragments.

The argument is the Pygments language of the nested code blocks. Repeated generated entries are removed as whole entries, never as individual lines inside a helper declaration.

:share-references: additionally supplies earlier generated declarations’ source values to calls in this group. No names are inferred from handwritten code or shared with other groups.

has_content = True

May the directive have content?

option_spec: ClassVar[dict[str, _OptionValidator] | None] = {'share-references': <function flag>}

Mapping of option names to validator functions.

required_arguments = 1

Number of required directive arguments.

run() → list[Node]

Parse the children and gather their generated preambles.

class sphinx_literalizer.LiteralizerInvocationDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Render source rows with a structured, typed invocation recipe.

option_spec: ClassVar[dict[str, _OptionValidator] | None] = {'annotation-evaluation': <function _make_format_validator.<locals>.validator>, 'bool-format': <function _make_format_validator.<locals>.validator>, 'bytes-format': <function _make_format_validator.<locals>.validator>, 'call-style': <function _make_format_validator.<locals>.validator>, 'comment-format': <function _make_format_validator.<locals>.validator>, 'date-format': <function _make_format_validator.<locals>.validator>, 'datetime-format': <function _make_format_validator.<locals>.validator>, 'declaration-style': <function _make_format_validator.<locals>.validator>, 'dict-entry-style': <function _make_format_validator.<locals>.validator>, 'dict-format': <function _make_format_validator.<locals>.validator>, 'empty-dict-key': <function _make_format_validator.<locals>.validator>, 'existing-variable': <function flag>, 'expand-call-stubs': <function _boolean_option>, 'float-format': <function _make_format_validator.<locals>.validator>, 'heterogeneous-strategy': <function _heterogeneous_strategy_validator>, 'include-preamble': <function flag>, 'indent': <function nonnegative_int>, 'indent-char': <function <lambda>>, 'indent-file-body': <function _boolean_option>, 'initial-column': <function nonnegative_int>, 'input-format': <function <lambda>>, 'integer-format': <function _make_format_validator.<locals>.validator>, 'invocation-file': <function unchanged_required>, 'json-rendering': <function _make_format_validator.<locals>.validator>, 'json-type': <function _make_format_validator.<locals>.validator>, 'language': <function <lambda>>, 'language-version': <function _make_format_validator.<locals>.validator>, 'native-align-selectors': <function _boolean_option>, 'native-argument-layout': <function _make_format_validator.<locals>.validator>, 'native-collection-layout': <function _make_format_validator.<locals>.validator>, 'native-column-limit': <function positive_int>, 'native-continuation-indent': <function nonnegative_int>, 'numeric-literal-suffix': <function _make_format_validator.<locals>.validator>, 'numeric-separator': <function _make_format_validator.<locals>.validator>, 'numeric-style': <function _make_format_validator.<locals>.validator>, 'per-element': <function flag>, 'pre-indent-level': <function nonnegative_int>, 'preamble-only': <function flag>, 'record-map-value-typing': <function _make_format_validator.<locals>.validator>, 'sequence-format': <function _make_format_validator.<locals>.validator>, 'set-format': <function _make_format_validator.<locals>.validator>, 'skip-if-unrepresentable': <function flag>, 'string-format': <function _make_format_validator.<locals>.validator>, 'trailing-comma': <function _make_format_validator.<locals>.validator>, 'union-format': <function _make_format_validator.<locals>.validator>, 'variable-name': <function unchanged_required>, 'variable-type-hints': <function _make_format_validator.<locals>.validator>, 'zip-file': <function unchanged_required>, 'zip-input-format': <function unchanged_required>}

Mapping of option names to validator functions.

supports_initial_column: ClassVar[bool] = True
sphinx_literalizer.setup(app: Sphinx) → ExtensionMetadata

Register the extension with Sphinx.