pyfcstm.utils

Utility helpers package for pyfcstm.

This package provides a consolidated import location for frequently used utility functions, interfaces, and exceptions within pyfcstm. The exported symbols cover binary detection, decoding utilities, documentation formatting, Jinja2 environment configuration, JSON/YAML serialization interfaces, safe string handling, text normalization, value parsing, and validation helpers.

The package exposes the following main components:

  • is_binary_file() - Detect whether a file is binary by inspecting its bytes

  • auto_decode() - Decode bytes by trying multiple encodings

  • format_multiline_comment() - Normalize multiline comments from parsers

  • add_builtins_to_env() - Register Python built-ins in a Jinja2 environment

  • add_settings_for_env() - Apply common filters and globals to Jinja2

  • IJsonOp - Interface for JSON/YAML serialization

  • sequence_safe() - Build a safe underscore-separated identifier

  • normalize() - Normalize text to identifier-friendly form

  • to_identifier() - Convert text to a valid identifier format

  • parse_value() - Parse string values to appropriate Python types

  • parse_key_value_pairs() - Parse multiple key=value pairs into a dictionary

  • ValidationError - Base validation error exception

  • ModelValidationError - Aggregated validation error exception

  • IValidatable - Interface for objects with validation rules

Note

This package re-exports utilities from internal modules to provide a unified import path. The implementations reside in submodules such as pyfcstm.utils.text and pyfcstm.utils.validate.

Example:

>>> from pyfcstm.utils import normalize, IJsonOp, parse_value
>>> normalize("Hello World!")
'Hello_World'
>>> parse_value('42')
42