API Reference

Sphinx extension for literalizer.

Provides the literalizer and literalizer-call directives, which read data files and render them as 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:
   :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
   :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

: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, Callable[[str], Any]] | None] = {'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>, '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>>, 'input-format': <function <lambda>>, 'integer-format': <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>, '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>, '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>, '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.

run() → list[Node]

Read the data file and produce function call expressions.

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:
   :date-format: python
   :datetime-format: python
   :variable-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
   :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
   :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, Callable[[str], Any]] | None] = {'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>, 'float-format': <function _make_format_validator.<locals>.validator>, 'heterogeneous-strategy': <function _heterogeneous_strategy_validator>, 'include-delimiters': <function flag>, 'include-preamble': <function flag>, 'indent': <function nonnegative_int>, 'indent-char': <function <lambda>>, 'input-format': <function <lambda>>, 'integer-format': <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>, '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>, '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>, 'trailing-comma': <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.

run() → list[Node]

Read the data file and produce a literal block.

sphinx_literalizer.setup(app: Sphinx) → ExtensionMetadata

Register the extension with Sphinx.