Parser API#

Parser classes implement a small static interface for loading and saving mapping data. Confease uses these classes directly and can infer one from a path suffix when parser=None is passed.

Format Constants#

confease.YAML#

.yaml suffix constant.

confease.YML#

.yml suffix constant.

confease.JSON#

.json suffix constant.

confease.TOML#

.toml suffix constant.

confease.INI#

.ini suffix constant.

confease.CFG#

.cfg suffix constant.

confease.CONF#

.conf suffix constant.

confease.CONFIG#

.config suffix constant.

confease.XML#

.xml suffix constant.

confease.CSV#

.csv suffix constant.

confease.PARSERS#

List of supported parser suffixes.

confease.PARSER_CLASSES#

Mapping from supported suffixes to parser classes.

Base Parser#

class confease.Parser#

Base parser interface for file-format implementations.

Parser classes expose static save() and load() methods. Confease calls parser classes directly and can infer a parser from PARSER_CLASSES when parser=None is used.

static save(path, data, **kwargs)#

Save mapping data to a path.

Parameters:

  • path (str | Path) – Destination file path.

  • data (Mapping[str, Any]) – Mapping to serialize, with arbitrary-depth mappings, dotted paths, empty mappings, and format-supported terminal values.

  • **kwargs – Reserved for parser-specific options.

Raises:

NotImplementedError – Always raised by the base class.

static load(path, **kwargs)#

Load mapping data from a path.

Parameters:

  • path (str | Path) – Source file path.

  • **kwargs – Reserved for parser-specific options.

Return type:

dict[str, Any]

Returns:

A canonical nested dictionary. Dotted file paths are reconstructed into hierarchy, including CSV row keys and INI section names.

Raises:

NotImplementedError – Always raised by the base class.

Concrete Parsers#

class confease.Yaml#

YAML semantic loader with comment-preserving round-trip writes.

YAML files must contain a top-level mapping. Empty files load as an empty mapping.

static save(path, data, **kwargs)#

Write validated YAML while preserving existing comments.

Parameters:

  • path (str | Path)

  • data (Mapping[str, Any])

static load(path, **kwargs)#

Read YAML data and require a top-level mapping.

Raises:

ValueError – If the file does not contain a top-level mapping.

Return type:

dict[str, Any]

Parameters:

path (str | Path)

class confease.Json#

JSON parser using the Python standard library.

JSON files must contain a top-level object. Files are written with stable key order and two-space indentation.

static save(path, data, **kwargs)#

Replace the file with complete validated JSON.

Parameters:

  • path (str | Path)

  • data (Mapping[str, Any])

static load(path, **kwargs)#

Read JSON data and require a top-level mapping.

Raises:

ValueError – If the file does not contain a top-level object.

Return type:

dict[str, Any]

Parameters:

path (str | Path)

class confease.Toml#

TOML semantic loader with tomlkit round-trip writes.

TOML supports arbitrary-depth native tables. Unsupported values such as None raise on save rather than being coerced or marker-encoded.

static save(path, data, **kwargs)#

Write validated TOML while preserving existing comments.

Parameters:

  • path (str | Path)

  • data (Mapping[str, Any])

static load(path, **kwargs)#

Read TOML mapping data.

Return type:

dict[str, Any]

Parameters:

path (str | Path)

class confease.Ini#

INI-family parser using dotted section names for arbitrary nesting.

Top-level values are stored in DEFAULT. Section values are stored as ordinary INI sections named by their full parent path. Individual values use YAML text so booleans, numbers, nulls, lists containing mappings, and empty mappings can round-trip. Loading merges section paths into a tree.

static save(path, data, **kwargs)#

Write mapping data as INI, storing values as YAML scalar text.

Raises:

ValueError – If paths conflict or emitted values cannot round-trip.

Parameters:

  • path (str | Path)

  • data (Mapping[str, Any])

static load(path, **kwargs)#

Read INI data and parse values from YAML scalar text.

Return type:

dict[str, Any]

Parameters:

path (str | Path)

class confease.Cfg#

Compatibility alias for INI-style parsing.

class confease.Xml#

XML parser using entry leaves and recursive section elements.

XML files use a <config> root. Entry text is serialized as YAML scalar text so supported scalar values can round-trip as Python values.

static save(path, data, **kwargs)#

Write mapping data as XML with YAML-typed entry text.

Raises:

ValueError – If paths conflict or emitted values cannot round-trip.

Parameters:

  • path (str | Path)

  • data (Mapping[str, Any])

static load(path, **kwargs)#

Read XML data and validate the supported config shape.

Raises:

ValueError – If the XML root, element names, required attributes, or duplicate keys do not match the supported configuration shape.

Return type:

dict[str, Any]

Parameters:

path (str | Path)

class confease.Csv#

CSV parser with a key,value header and flat dotted keys.

CSV stores every value as a flat row. Nested sections are written as dotted keys such as database.host. Values are serialized as YAML scalar text so supported Python values, including lists and empty mappings, can round-trip. Loading returns reconstructed nested dictionaries, not flat row keys.

static save(path, data, **kwargs)#

Write mapping data as CSV, flattening nested sections.

Raises:

ValueError – If paths conflict or emitted values cannot round-trip.

Parameters:

  • path (str | Path)

  • data (Mapping[str, Any])

static load(path, **kwargs)#

Read YAML-typed rows and reconstruct their dotted paths into a tree.

Raises:

ValueError – If the header is not exactly key,value or a row is malformed, duplicates a logical path, or conflicts with a section.

Return type:

dict[str, Any]

Parameters:

path (str | Path)