FLM Feature flm.feature.floats

Provides floating environments (figures, tables, and custom float types) with automatic numbering, captions, labels, and cross-reference integration. Float content is validated by pluggable content handlers such as FloatContentIncludeGraphics and FloatContentCells.

class flm.feature.floats.FloatContentHandlerBase

Bases: object

Base class for float content handlers that validate and optionally post-process the content nodes inside a float environment.

float_content_set_extra_definitions(extend_latex_context)

Register additional LaTeX context definitions needed by this handler.

Called during float environment body parsing to inject extra macros or environments (e.g. \includegraphics, \begin{cells}).

Parameters:

extend_latex_context – A mutable dict with keys 'macros', 'environments', 'specials'; append definitions to the relevant lists.

float_handle_content_nodes(float_node, content_nodes)

Validate and optionally post-process a float’s content nodes.

Subclasses must reimplement this method. Return a (possibly post-processed) node list to use in place of content_nodes if the content is accepted. Raise LatexWalkerLocatedError if the content is invalid for this handler.

Parameters:

• float_node – The parsed float environment node.

• content_nodes – A LatexNodeList of the float body nodes (excluding \caption and \label).

Returns:

A LatexNodeList to use as the float content.

Raises:

RuntimeError – Always, in this base implementation.

class flm.feature.floats.FloatContentAnyContent

Bases: FloatContentHandlerBase

float_handle_content_nodes(float_node, content_nodes)

class flm.feature.floats.FloatContentIncludeGraphics

Bases: FloatContentHandlerBase

float_content_set_extra_definitions(extend_latex_context)

float_handle_content_nodes(float_node, content_nodes)

class flm.feature.floats.FloatContentCells

Bases: FloatContentHandlerBase

float_content_set_extra_definitions(extend_latex_context)

float_handle_content_nodes(float_node, content_nodes)

class flm.feature.floats.FloatEnvironment(float_type, content_handlers=None)

Bases: FLMEnvironmentSpecBase

Environment spec for a single float type (e.g. figure, table).

Parses the environment body for \label, \caption, and content nodes, delegates content validation to FloatContentHandlerBase instances, and registers the float with the floats render manager during rendering. By default the float is rendered in-place.

is_block_level: bool | None = True

If this flag is set to True, then elements of this type are always parsed as separate block-level elements (e.g., a section heading, an enumeration list, etc.)

If this flag is None, then the spec does not commit as to whether the node produces a block-level or inline-level element. It is strongly recommended you then manually set the flm_is_block_level attribute on the node object to True or False, since the default implementation of finalize_node() won’t be able to do it.

float_content_is_block_level = True

float_content_render_at_environment_node_location = True

By default (True), the float will be rendered exactly where the float environment was positioned (making it actually not a float). If you set False here, the float is not rendered, and it is up to you (a custom float feature render manager, for instance), to actually render the float somewhere.

allowed_in_standalone_mode: bool = False

Whether or not this node is allowed in standalone mode, i.e., whether or not this node can be rendered independently of any document object.

make_body_parser(token, nodeargd, arg_parsing_state_delta)

postprocess_parsed_node(node)

render(node, render_context)

render_float(float_instance, node, render_context)

recompose_pure_latex(node, recomposer)

class flm.feature.floats.FloatInstance(*, float_type=None, float_type_info=None, counter_value=None, counter_numprefix=None, formatted_counter_value_flm=None, ref_label_prefix=None, ref_label=None, target_id=None, caption_nodelist=None, content_nodelist=None)

Bases: object

Data object representing a single registered float (figure, table, etc.).

Created by FeatureFloats.RenderManager.register_float() during rendering. Carries all information needed to render the float: its type, counter value, formatted label, caption, and content nodes.

asdict()

class flm.feature.floats.FloatType(float_type: str, float_caption_name: None | str = None, counter_formatter: None | TypeCounterFormatter | Literal['alph', 'Alph', 'roman', 'Roman', 'arabic', 'fnsymbol', 'unicodesuperscript', 'unicodesubscript'] | TypeFormatNumTemplate | TypeCounterFormatterSpecDict = None, content_handlers: Sequence[str] | None = None)

Bases: object

asdict()

class flm.feature.floats.FeatureFloats(float_types: Sequence[TypeFloatTypeDef] | None = None)

Bases: Feature

Feature plugin for floating elements such as figures and tables. Registers one environment per configured FloatType, each supporting \includegraphics, \caption, and \label commands. Numbered floats are automatically registered with the refs feature for cross-referencing.

feature_name: str | None = 'floats'

A name that should uniquely identify this feature.

feature_title: str | None = 'Floating elements (figures & tables)'

Descriptive name or title for this feature.

feature_optional_dependencies: Set[str] | Sequence[str] | None = ['refs', 'numbering']

If non-None, then this is a list (or set) of feature names that may enhance the functionality of the present feature. If these features are activated, they will be initialized prior to the present feature.

make_float_environment_spec(float_type)

add_latex_context_definitions()

class RenderManager(feature_document_manager, render_context, **kwargs)

Bases: FeatureRenderManagerBase

initialize()

register_float(float_type, *, node, numbered=True, ref_label_prefix=None, ref_label=None, caption_nodelist=None, content_nodelist=None)

get_formatted_ref_flm_text(float_instance)

feature_flm_doc()

add_flm_doc_latex_context_definitions(base_feature_definitions)

These definitions won’t be used in the real world. This method will only be queried by flm.docgen to generate comprehensive documentation that includes these commands.

flm.feature.floats.FeatureClass = <class 'flm.feature.floats.FeatureFloats'>

Feature plugin for floating elements such as figures and tables. Registers one environment per configured FloatType, each supporting \includegraphics, \caption, and \label commands. Numbered floats are automatically registered with the refs feature for cross-referencing.