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. Nested-capable parsers accept one-level nested mappings.

  • **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 dictionary containing scalar values or one-level nested mappings.

Raises:

NotImplementedError – Always raised by the base class.

Concrete Parsers#

class confease.Yaml#

YAML parser using PyYAML.

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

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

Write mapping data as YAML.

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)#

Write mapping data as formatted 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 parser using tomllib and tomli-w.

TOML naturally supports one-level sections as tables.

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

Write mapping data as TOML.

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 ConfigParser sections for one-level nesting.

Top-level values are stored in DEFAULT. Section values are stored as ordinary INI sections. Individual values are serialized as YAML scalar text so booleans, numbers, nulls, and simple lists can round-trip as Python values.

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

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

Raises:

ValueError – If nested mappings exceed one level.

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 one-level 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 nested mappings exceed one level.

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 simple Python values can round-trip.

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

Write mapping data as CSV, flattening nested sections.

Raises:

ValueError – If nested mappings exceed one level.

Parameters:

  • path (str | Path)

  • data (Mapping[str, Any])

static load(path, **kwargs)#

Read CSV data and parse each value from YAML scalar text.

Raises:

ValueError – If the header is not exactly key,value or a row is malformed.

Return type:

dict[str, Any]

Parameters:

path (str | Path)