Extending with new protocols

This advanced section explains how to extend configoose by defining your own protocol.

We illustrate this by an example showing how to define a protocol yourmodule.TomlProtocol to handle configuration written in toml language.

To do so, you need to create a subclass of configoose.protocol.abc.Protocol with a run() method and optionally a template() method.

Here is the content of yourmodule.py

# file yourmodule.py
from configoose.protocol import abc
import tomllib # python >= 3.11

class TomlProtocol(abc.Protocol):

    def run(self, ap, preamble, text, mediator):
        # parse the toml configuration file
        data = tomllib.loads(text)

        # if the client code defines a handler,
        # call that handler with the parsed data
        if handler := ap.kwargs.get("handler", None):
            handler(ap, preamble, data, mediator))

The arguments received by the run() method are an object ap which members ap.args and ap.kwargs are the arguments given by client code to the add_protocol() method, an object preamble containing the data read in the configuration’s file preamble, the text following the preamble in the configuration file and a mediator which is the object through which the configuration data was found. The mediator’s system_path() method returns the location where the configuration file was found in the file system, if it was found in such a location.