Decode

RConf decoding module.

rconf.decode.BaseHandler implements a decoder for a specific language, and rconf.decode.DecoderDirector decides which rconf.decode.BaseHandler to use based on the Media Type or URL.

rconf.decode.build_decoder(*handlers, fallback=None, mime_types=None)

Build a rconf.decode.DecoderDirector with default handlers.

rconf.decode.JSONHandler is chosen as the default fallback (no media type specified or unknown extension) because of its ubiquity and because TOML is a config file format for humans, who tend to use file extensions.

Parameters:

• handlers (type[BaseHandler] | BaseHandler) – rconf.decode.BaseHandler s to choose from.

• fallback (type[BaseHandler] | BaseHandler | str | None) – The fallback rconf.decode.BaseHandler. If missing, rconf.decode.JSONHandler will be the fallback handler.

• mime_types (MimeTypes | None) – mimetypes.MimeTypes object used to guess a configuration’s media type from a URL.

Return type:

DecoderDirector

BaseHandler

class rconf.decode.BaseHandler

Base class for a configuration language decoder.

Holds the media types used for registration and the rconf.pointer.Pointer type.

__init__(*media_types, pointer_type=<class 'rconf.pointer.JSONPointer'>)

Build a rconf.decode.BaseHandler.

Parameters:

• media_types (str | tuple[str, str] | list[str]) – The media type name, or (name, extension) tuple for those not registered in mimetypes.MimeTypes.

• pointer_type (type[rconf.pointer.Pointer]) – The decoder-specific Pointer type.

Return type:

None

load(fp, url=None, **kwargs)

Decode a read-supporting binary file.

Parameters:

• fp (BinaryIO) – read-supporting binary file.

• url (str | None) – Configuration URL.

• kwargs – The decoder-specific keyword arguments.

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

loads(s, url=None, **kwargs)

Decode a str configuration document.

Parameters:

• s (str) – Configuration document.

• url (str | None) – Configuration URL.

• kwargs – The decoder-specific keyword arguments.

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

class rconf.decode.DecoderDirector

Load configurations from string or file.

The rconf.decode.BaseHandler is selected using a configuration’s media type, explicitly given or derived from the URL using mimetypes.MimeTypes.

__init__(*handlers, fallback=None, mime_types=None)

Build a rconf.decode.DecoderDirector.

Parameters:

• handlers (type[BaseHandler] | BaseHandler) – rconf.decode.BaseHandler s to choose from.

• fallback (type[BaseHandler] | BaseHandler | str | None) – The fallback rconf.decode.BaseHandler. If missing, the first handler will be the fallback handler.

• mime_types (MimeTypes | None) – mimetypes.MimeTypes object used to guess a configuration’s media type from a URL.

Return type:

None

add_handler(handler, *media_types)

Add a handler.

The handler added first will be the fallback handler.

Parameters:

• media_types (str | tuple[str, str] | list[str]) – Add media types by name, or (name, extension) tuple for those not registered in mimetypes.MimeTypes. If missing, those listed in the BaseHandler are used.

• handler (type[BaseHandler] | BaseHandler) –

Returns:

The inserted handler.

Raises:

rconf.decode.DecodeValueError.

Return type:

BaseHandler

get_handler(media_type=None, url=None)

Get a matching handler.

Unknown media type or unknown URL-derived media type results in the fallback handler.

Parameters:

• media_type (str | None) – Assumed media type, overrides URL-derived media type. It can also be a filename extension.

• url (str | None) – Configuration URL.

Return type:

BaseHandler

load(fp, media_type=None, url=None, **kwargs)

Decode a read-supporting binary file.

Parameters:

• fp (BinaryIO) – read-supporting binary file.

• media_type (str | None) – Assumed media type, overrides URL-derived media type. It can also be a filename extension.

• url (str | None) – Configuration URL.

• kwargs – Forwarded to language-specific rconf.decode.BaseHandler.

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

loads(s, media_type=None, url=None, **kwargs)

Decode a str configuration document.

Parameters:

• s (str) – Configuration document.

• media_type (str | None) – Assumed media type, overrides URL-derived media type. It can also be a filename extension.

• url (str | None) – Configuration URL.

• kwargs – Forwarded to language-specific rconf.decode.BaseHandler.

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

Language-specific handlers

class rconf.decode.JSONHandler

Handler for JSON.

Uses Python’s json.

__init__(*media_types, pointer_type=<class 'rconf.pointer.JSONPointer'>, **kwargs)

Create a JSON Handler.

Parameters:

• kwargs – Forwarded to json.load() and :func`json.loads`.

• media_types (str) –

• pointer_type (type[rconf.pointer.Pointer]) –

Return type:

None

load(fp, url=None, **kwargs)

Decode a read-supporting binary file.

Returns json.load().

Parameters:

• fp (BinaryIO) – read-supporting binary file.

• kwargs – Forwarded to json.load(). Overrides JSONHandler.__init__() kwargs.

• url (str | None) –

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

loads(s, url=None, **kwargs)

Decode a str configuration document.

Returns json.loads().

Parameters:

• s (str) – Configuration document.

• kwargs – Forwarded to json.load(). Overrides JSONHandler.__init__() kwargs.

• url (str | None) –

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

class rconf.decode.TOMLHandler

Handler for TOML.

Uses Python’s tomllib for Python>=3.11, or tomli (github) below.

__init__(*media_types, pointer_type=<class 'rconf.pointer.TOMLPointer'>, **kwargs)

Create a TOML Handler.

Only valid tomllib.load() and tomllib.loads() keyword arguments are forwarded.

Parameters:

• kwargs – Forwarded to tomllib.load() and :func`tomllib.loads`.

• media_types (str) –

• pointer_type (type[rconf.pointer.Pointer]) –

Return type:

None

load(fp, url=None, **kwargs)

Decode a read-supporting binary file.

Returns tomllib.load().

Only valid tomllib.load() keyword arguments are forwarded.

Parameters:

• fp (BinaryIO) – read-supporting binary file.

• kwargs – Forwarded to tomllib.load(). Overrides TOMLHandler.__init__() kwargs.

• url (str | None) –

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

loads(s, url=None, **kwargs)

Decode a str configuration document.

Returns tomllib.loads().

Only valid tomllib.loads() keyword arguments are forwarded.

Parameters:

• s (str) – Configuration document.

• kwargs – Forwarded to tomllib.loads(). Overrides TOMLHandler.__init__() kwargs.

• url (str | None) –

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

class rconf.decode.INIHandler

Handler for configparser.

All configparser keyword arguments are forwarded to support the same configuration language dialects.

__init__(*media_types, encoding='utf-8', errors='strict', pointer_type=<class 'rconf.pointer.TOMLPointer'>, **kwargs)

Create a configparser Handler.

Only valid configparser.ConfigParser() keyword arguments are forwarded.

Parameters:

• encoding (str) – Forwarded to bytes.decode().

• errors (str) – Forwarded to bytes.decode().

• kwargs – Forwarded to configparser.ConfigParser.

• media_types (str) –

• pointer_type (type[rconf.pointer.Pointer]) –

Return type:

None

load(fp, url=None, *, encoding=None, errors=None, **kwargs)

Decode a read-supporting binary file.

Uses configparser.ConfigParser.read_string() and translates the result to a rconf.Value.

Only valid configparser.ConfigParser() keyword arguments are forwarded.

Parameters:

• fp (BinaryIO) – read-supporting binary file.

• encoding (str | None) – Forwarded to bytes.decode(). Overrides INIHandler.__init__() encoding.

• errors (str | None) – Forwarded to bytes.decode(). Overrides INIHandler.__init__() errors.

• kwargs – Forwarded to configparser.ConfigParser. Overrides INIHandler.__init__() kwargs.

• url (str | None) –

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

loads(s, url=None, **kwargs)

Decode a str configuration document.

Uses configparser.ConfigParser.read_string() and translates the result to a rconf.Value.

Only valid configparser.ConfigParser() keyword arguments are forwarded.

Parameters:

• s (str) – Configuration document.

• kwargs – Forwarded to configparser.ConfigParser. Overrides INIHandler.__init__() kwargs.

• url (str | None) –

Raises:

rconf.decode.DecodeError in case of decode errors.

Return type:

rconf.Value

Exceptions

class rconf.decode.DecodeError

An error raised if a document is not valid.

__new__(**kwargs)

__init__(*args, **kwargs)

class rconf.decode.DecodeFileError

An error raised if a document loaded from file is not valid.

__new__(**kwargs)

__init__()

Return type:

None

class rconf.decode.DecodeStringError

An error raised if a document loaded from string is not valid.

__new__(**kwargs)

__init__()

Return type:

None

class rconf.decode.DecodeValueError

Raised if an argument is not valid.

__new__(**kwargs)

__init__(*args, **kwargs)