Code for Command-Line Usage Extensions and Workflows

These modules implement the internals of the flm command-line tool, including configuration loading and merging, template rendering, and workflow orchestration.

Module flm.main.configmerger

class flm.main.configmerger.ListProperty

Sentinel class used as a marker in property_path lists to indicate that the current level of config traversal is inside a list (as opposed to a dictionary key).

class flm.main.configmerger.PresetKeepMarker(marker)

Preset handler that copies a $-prefixed key and its value into the merged object under a renamed key. Used for internal markers such as $_cwd.

Parameters:

marker – The destination key name to store the preset argument value under.

class flm.main.configmerger.PresetDefaults(defaults_additional_sources=None)

Preset handler for the $defaults directive. When encountered in a config list, appends the remaining objects in the merge chain (plus any additional default sources) as recursively merged defaults.

Parameters:

defaults_additional_sources – Optional sequence of additional default-providing objects whose fetch_defaults(property_path) method will be called to obtain extra defaults.

class flm.main.configmerger.PresetMergeConfig

Preset handler for the $merge-config directive. Locates an existing item in the accumulated list result by its name field and recursively merges additional config into that item’s config dictionary.

class flm.main.configmerger.PresetRemoveItem

Preset handler for the $remove-item directive. Removes an item from the accumulated list result by matching its name field against the preset argument string.

class flm.main.configmerger.PresetImport

Preset handler for the $import directive. Fetches external configuration from a file path, a pkg: URI (Python module attribute), or an HTTP(S) URL, then merges the imported data into the current config object or list.

flm.main.configmerger.get_default_presets(defaults_additional_sources=None)

Return the default preset handlers dictionary used by ConfigMerger.

Includes handlers for $defaults, $merge-config, $remove-item, $import, and $_cwd.

Parameters:

defaults_additional_sources – Forwarded to the PresetDefaults constructor.

Returns:

A dict mapping preset key strings to handler instances.

class flm.main.configmerger.ConfigMerger(presets=None, defaults_additional_sources=None)

Recursively merges a chain of configuration dictionaries, applying $-prefixed preset directives ($defaults, $merge-config, $remove-item, $import, $_cwd) during traversal.

Scalar values are taken from the first object in the chain that provides them. Nested dictionaries and lists are merged recursively. A $no-merge flag in a dictionary prevents further merging from subsequent chain entries.

Parameters:

• presets – Custom preset handlers dictionary. When None, get_default_presets() is called.

• defaults_additional_sources – Forwarded to get_default_presets() when presets is None.

recursive_assign_defaults(obj_list)

Merge a list of configuration dictionaries, applying defaults from later entries and processing any preset directives.

This is a convenience entry point that delegates to recursive_assign_defaults_dict() with an empty property path.

Parameters:

obj_list – Ordered list of configuration dictionaries. Earlier entries take priority over later ones for scalar values.

Returns:

The merged configuration dictionary.

Module flm.main.template

class flm.main.template.TemplateEngineBase(template_info_path, template_info_file, flm_run_info, document_template, template_engine_config)

Abstract base class for template engines used to render final output documents from FLM-rendered content.

Subclasses must implement render_template() to produce the final output string from a merged configuration dictionary. Optionally override initialize() to perform setup using template_engine_config keys.

Parameters:

• template_info_path – Base folder path for the template.

• template_info_file – Filename of the template descriptor (.yaml file).

• flm_run_info – The run-info dictionary carrying resource accessor, output format, and other run-time state.

• document_template – The owning DocumentTemplate instance.

• template_engine_config – Dictionary of engine-specific configuration options (passed as keyword arguments to initialize()).

Module flm.main.feature_graphics_collection

Graphics collection feature for the FLM command-line pipeline.

Provides FeatureGraphicsCollection, a feature that scans FLM documents for graphics resources, optionally collects them into an output folder, and applies format-conversion rules (e.g. SVG to PDF, PDF to PNG) using pluggable converter backends (CairoSvgConverter, GhostscriptConverter, PdfToCairoCmdlConverter, MagickConverter).

class flm.main.feature_graphics_collection.GraphicsFormatConversionRule(rule)

Specify a rule to convert one graphics format to another using specific transformation requirements and options.

The rule can be constructed using a string, a dictionary, or another GraphicsFormatConversionRule instance.

• If the argument is a string, it should be in the form ‘from_format:to_format’ (e.g. ‘.svg:.pdf’). In this case, via and options are set to an empty list and None, respectively.

• If the argument is a dictionary, it should have the following structure:

  { 'from': [..list of extensions..],
    'to': [..list of extensions..],
    'via': [..list of converter names..],
    'options': <dict or None> }
  

Built-in converter names are: ‘cairosvg’, ‘gs’, ‘pdftocairo’, ‘magick’. If you specify a list of converter names, these are meant to be acceptable converters to use to perform the transformation. The rule will pick the first one that can perform the conversion. (There is currently no way of specifying a conversion chain through multiple converters with intermediate formats.)

Example rule in YAML:

collect_format_conversion_rules:
  - from: '.pdf'
    to: '.png'
    options:
      dpi: 192

get_converter_or_none(ext)

class flm.main.feature_graphics_collection.GraphicsConverter

Abstract base class for graphics format converters.

Subclasses must set name to a unique string identifier, implement can_convert() as a classmethod, and provide a convert() method that performs the actual conversion.

name = None

Unique converter name used to match via entries in conversion rules.

classmethod get_instance()

Return a lazily-created singleton instance of this converter class.

Return type:

GraphicsConverter

read_input(source_type, src_url, binary=True)

Read the source graphics data from a file path or URL.

Parameters:

• source_type (str) – 'file' for local files, or any other value to fetch via HTTP.

• src_url (str) – File path or URL to read from.

• binary (bool) – If True, return raw bytes; otherwise decode as UTF-8.

Returns:

The file contents as bytes (if binary) or str.

class flm.main.feature_graphics_collection.FeatureGraphicsCollection(allow_unknown_graphics: bool = False, collect_graphics_to_output_folder: None | Literal[False] | str = False, collect_graphics_relative_output_folder: None | Literal[False] | str = False, collect_graphics_filename_template: None | str = 'gr${counter}${ext}', collect_format_conversion_rules: None | Sequence[TypeGraphicsFormatConversionRuleDict | GraphicsFormatConversionRule | str] = None, graphics_search_path: None | Sequence[str] = None)

Bases: Feature

feature_name: str | None = 'graphics_resource_provider'

A name that should uniquely identify this feature.

feature_title: str | None = 'Process a collection of graphics that can be included in FLM content'

Descriptive name or title for this feature.

feature_flm_doc = '\n    Collect input graphics files into a specific output folder, while applying a series\n    of custom transformation rules to convert between chosen formats.\n    '

class DocumentManager(feature, doc, **kwargs)

Bases: FeatureDocumentManagerBase

initialize()

flm_main_scan_fragment(fragment, document_parts_fragments=None, **kwargs)

Scan a parsed FLM fragment (and optional additional document-part fragments) for graphics resource references.

Sets up input/output reference directories from document metadata, then uses ResourcesScanner to walk the node trees and inspect each discovered graphics resource.

Parameters:

• fragment – The primary FLM fragment to scan.

• document_parts_fragments (list or None) – Optional additional fragments (e.g. from document parts) to scan for resources.

• kwargs – Additional keyword arguments; if flm_run_info is present, it is used to determine the output directory.

get_source_info(graphics_path, resource_info)

Return a tuple (source_type, source_url, source_key, source_resolved) where source_type is ‘file’ or ‘url’ and where source_key is the internal key to use for cache purposes, unique across all source types. The source_url is the relative path for ‘file’ source types, and is the full url for ‘url’ source types. For ‘file’ types, the source_resolved is a tule (file_path, file_name, full_file_path) where file_path is the path in graphics_search_path where the file was found and file_name is the corresponding relative path and full_file_path is both parts concatenated. For ‘url’ types, source_resolved is None.

inspect_add_graphics_resource(resource)

add_graphics(source_key, source_info, graphics_resource)

class RenderManager(feature_document_manager, render_context, **kwargs)

Bases: FeatureRenderManagerBase

initialize(allow_unknown_graphics: None | bool = None, collect_graphics_to_output_folder: None | Literal[False] | str = None, collect_graphics_relative_output_folder: None | Literal[False] | str = None, collect_graphics_filename_template: None | str = None, collect_format_conversion_rules: None | Sequence[TypeGraphicsFormatConversionRuleDict | GraphicsFormatConversionRule | str] = None, use_graphics_cache_file: bool = True)

Set up the render manager for a specific rendering pass.

Each parameter defaults to None, meaning the corresponding value from the parent FeatureGraphicsCollection instance is used. When the output format has entries in default_rules_by_format, those rules are applied automatically if no explicit conversion rules are provided.

Parameters:

• allow_unknown_graphics (None | bool) – Whether to permit get_graphics_resource() calls for graphics paths that were not found during the scan phase. None defers to the feature-level setting.

• collect_graphics_to_output_folder (None | Literal[False] | str) – Folder (relative to output dir) into which graphics files are collected. False disables collection; None defers to the feature-level setting.

• collect_graphics_relative_output_folder (None | Literal[False] | str) – Path used in rendered output to reference collected graphics. Falls back to collect_graphics_to_output_folder when None or False.

• collect_graphics_filename_template (None | str) – A string.Template pattern for naming collected files. Available substitution keys: basename, basenoext, ext, counter, hash, hash6.

• collect_format_conversion_rules (None | Sequence[TypeGraphicsFormatConversionRule]) – Rules governing format conversions applied when collecting. Each element is coerced to a GraphicsFormatConversionRule.

• use_graphics_cache_file (bool) – Whether to read/write a cache file to skip re-converting unchanged graphics. Automatically disabled when collection is turned off.

prepare_collect_graphics_get_converter(source_info, resolved_src_url, ext)

prepare_collect_graphics(source_info, resolved_src_url, counter)

collect_graphics(source_key, collect_info, *, cache_info)

get_graphics_resource(graphics_path, resource_info)

Resolve a graphics path to a GraphicsResource.

Looks up graphics_path in the document manager’s pre-scanned collection. If the path is not in the collection and allow_unknown_graphics is True, a bare GraphicsResource is returned.

When graphics collection is active, the returned resource’s src_url points to the collected (and possibly converted) file. Otherwise src_url is made relative to the output directory.

Parameters:

• graphics_path (str) – The graphics path as it appears in the FLM source (may be a relative file path or a URL).

• resource_info – Provenance information from the originating latex walker, used to resolve search paths.

Returns:

A GraphicsResource with the appropriate src_url for the current render output.

Return type:

GraphicsResource

Raises:

LatexWalkerError – If the path is unknown and allow_unknown_graphics is False.

get_unknown_graphics_resource(graphics_path, source_info, resource_info)

postprocess(value)

collect_all_graphics()

inspect_graphics_file(file_path, fp)

Module flm.main.workflow

class flm.main.workflow.RenderWorkflow(workflow_config, flm_run_info, fragment_renderer_information, fragment_renderer)

Bases: object

Abstract base class for render workflows.

A workflow orchestrates the full rendering pipeline: it selects the fragment renderer, renders document fragments (with optional endnotes), and performs any post-processing (e.g. template wrapping, running external tools).

Subclasses override static configuration hooks and the postprocess_rendered_document() method to implement format-specific behavior.

binary_output = False

Subclasses should set this attribute to True if the workflow produces binary (non-text) output. If the workflow leaves this attribute as False, then the workflow produces text output.

static get_workflow_default_config(flm_run_info, config) → dict

Return workflow-specific default configuration entries that will be merged into the run configuration.

Parameters:

• flm_run_info – The run-info dictionary.

• config – The current configuration dictionary.

Returns:

A dictionary of default config values (empty by default).

static get_fragment_renderer_name(outputformat, flm_run_info, run_config) → str | None

Optionally override which fragment renderer is used for this workflow.

Return a renderer name string to force a specific renderer, or None to let the output format determine the renderer (the default).

Parameters:

• outputformat – The requested output format string.

• flm_run_info – The run-info dictionary.

• run_config – The current run configuration.

Returns:

A renderer name string, or None.

static get_default_main_config(flm_run_info, run_config) → None | dict

Return workflow-specific overrides for the main FLM configuration, or None to use defaults.

static requires_temporary_directory_output(flm_run_info, run_config) → bool

Return True if this workflow needs a temporary output directory (e.g. for multi-file LaTeX builds). Defaults to False.

TypeWorkflowConfigDict

alias of dict

render_document(document, content_parts_infos=None, **kwargs)

Render a document and post-process the result.

Calls render_document_fragments() to obtain the rendered content and render context, then passes the result through postprocess_rendered_document().

Parameters:

• document – The FLMDocument to render.

• content_parts_infos – Optional content-parts metadata.

Returns:

The final post-processed output.

render_document_fragments(document)

Render the document fragments via render().

Parameters:

document – The FLMDocument.

Returns:

A tuple (rendered_result, render_context).

render_document_fragment_callback(fragment, render_context, content_parts_infos, **kwargs)

Render callback suitable for passing to make_document().

Renders the main fragment, any additional content parts, and (if enabled) endnotes.

Parameters:

• fragment – The main FLMFragment.

• render_context – The active render context.

• content_parts_infos – Dict with optional 'parts' key listing additional fragment parts to render.

Returns:

The rendered output string.

postprocess_rendered_document(rendered_content, document, render_context)

Post-process the rendered document output.

Subclasses override this to apply template wrapping, run external tools, or perform other transformations. The default implementation returns rendered_content unchanged.

Parameters:

• rendered_content – The raw rendered output string.

• document – The FLMDocument.

• render_context – The render context from the render pass.

Returns:

The final output (string or bytes if binary_output is True).

Module flm.main.workflow.flmlatex

class flm.main.workflow.flmlatex.FlmLatexWorkflow(workflow_config, flm_run_info, fragment_renderer_information, fragment_renderer)

Workflow that uses flm.flmrecomposer.purelatex to recompose a document into LaTeX code that mirrors the original FLM’s document structure.

class TypeWorkflowConfigDict

recomposer_options: dict

skip_packages: list[str]

add_bibliography: str | Literal[False]

static get_workflow_default_config(flm_run_info, config)

static get_fragment_renderer_name(outputformat, flm_run_info, run_config)

get_wstyle_information()

recompose_fragment(recomposer, fragment)

render_document(document, content_parts_infos, **kwargs)

flm.main.workflow.flmlatex.RenderWorkflowClass

Module attribute that declares this module as a module that defines an FLM workflow.

Module flm.main.workflow.runlatexpdf

class flm.main.workflow.runlatexpdf.RunPdfLatexRenderWorkflow(*args, **kwargs)

Workflow that uses a standard latex-output rendering pipeline with a template and then compiles the document to PDF using latexmk. Assumes a LaTeX distribution is installed (e.g. TeXLive).

binary_output = True

Subclasses should set this attribute to True if the workflow produces binary (non-text) output. If the workflow leaves this attribute as False, then the workflow produces text output.

static get_fragment_renderer_name(req_outputformat, flm_run_info, run_config)

static get_default_main_config(flm_run_info, run_config)

static requires_temporary_directory_output(flm_run_info, run_config)

postprocess_rendered_document(rendered_content, document, render_context)

flm.main.workflow.runlatexpdf.RenderWorkflowClass

Module attribute that declares this module as a module that defines an FLM workflow.

Module flm.main.workflow.templatebasedworkflow

class flm.main.workflow.templatebasedworkflow.TemplateBasedRenderWorkflow(workflow_config, flm_run_info, fragment_renderer_information, fragment_renderer)

This workflow works by simply reimplementing postprocess_rendered_document() to include the document contents in a suitable template (defined by the run info, output format, and relevant config items).

This class offers the method render_templated_document(), for the use of any other workflows or scripts can render documents based on templates in a similar way as a subroutine (e.g. to render PDF based on templated HTML output).

static get_workflow_default_config(flm_run_info, config)

static get_fragment_renderer_name(outputformat, flm_run_info, run_config)

class TypeWorkflowConfigDict

use_output_format_name: str | None

template_config_workflow_defaults: dict

postprocess_actions_fn: Callable[[Any, Any, Any], Any]

use_output_format_name = None

template_config_workflow_defaults = {}

postprocess_actions_fn = None

get_wstyle_information()

get_use_output_format_name()

get_use_template_name(use_output_format_name)

get_merged_template_config_with_prefix(use_output_format_name, use_template_name)

render_templated_document(rendered_content, document, render_context, *, add_context=None)

Take the raw rendered document content rendered_content and place it in a document based on a suitable template. The argument document is the FLMDocument instance that was rendered with the render context render_context.

postprocess_rendered_document(rendered_content, document, render_context)

flm.main.workflow.templatebasedworkflow.RenderWorkflowClass

Module attribute that declares this module as a module that defines an FLM workflow.