configoose.database package

Module contents

class configoose.database.Db(*marinas)

Bases: Mapping[str, Mediator]

The Db class is the type of configoose’s main database. It maps abstract configuration addresses (strings) to mediators giving access to configuration content.

It is built upon a sequence of marinas, creating a single view of this sequence.

The underlying marinas are stored in a list. That list is public and can be accessed or updated using the path attribute. There is no other state.

Lookups search the underlying marinas successively until a key is found. This is conceptually similar to a collections.ChainMap except that the values found are deserialized before return: lookups return Mediator instances instead of serialized mediators which are stored into marinas.

clear = None
get(k[, d]) → D[k] if k in D, else d.  d defaults to None.
pop = None
popitem = None
class configoose.database.FileInOsMediator(path)

Bases: Mediator

A class of mediators pointing to configuration files stored as regular files in the file system.

Parameters:

path – the path to the underlying file

read_bytes()

Read configuration content as bytes

read_text()

Read configuration content as a unicode string. The default implementation uses read_bytes()

Parameters:

encoding (str) – unicode encoding, defaults to utf8

classmethod schema_type()

This required classmethod returns a subclass of marshmallow.Schema which is used to serialize instances of this class.

Instances of Mediator are serialized to be stored as values in Marina objects and deserialized during lookups in Db objects.

system_path()

Return the path to the underlying file of this mediator

class configoose.database.FileInOsSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool = False, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Bases: Schema

A subclass of marshmallow.Schema used to serialized instances of FileInOsMediator

opts: SchemaOpts = <marshmallow.schema.SchemaOpts object>
postload(obj, **kwargs)
class configoose.database.Marina(tags=())

Bases: MutableMapping[str, str]

This is the base class of marina objects. They are mutable mappings that map strings to strings. They are used to associate abstract configuration addresses to serialized Mediator instances.

Parameters:

tags – A set of strings used to identify marinas

is_valid_key(key: str, keyerror: bool = False) → bool

Indicates whether a given key is valid for this marina type.

Parameters:

  • key (str) – a configuration address

  • keyerror (bool) – if set, the function raises KeyError for invalid keys instead of returning False. Defaults to False (don’t raise KeyError)

Returns:

a boolean indicating if the key is valid

Return type:

bool

In the base class Marina, this function always returns True but concrete subclasses may whish to exclude some keys.

class configoose.database.MarinaDict(tags=())

Bases: dict, Marina

Subclass of Marina built on a dict instance. As these marinas are not persistent, they can only be used temporarily in a single process.

Parameters:

tags – A set of strings used to identify marinas

class configoose.database.MarinaDirInOs(path: Path, tags=())

Bases: Marina

Subclass of Marina built on a file system directory. Pairs (key, value) are stored in the directory as a file name and a file content.

As a consequence, not every key is allowed in such a marina, for example spam/ham is not a valid filename in a directory in Linux, but spam-ham is.

Parameters:

  • path (pathlib.Path) – The path to the underlying directory

  • tags – A set of strings used to identify marinas

is_valid_key(key, keyerror=False)

Indicates whether a given key is valid for this marina type.

Parameters:

  • key (str) – a configuration address

  • keyerror (bool) – if set, the function raises KeyError for invalid keys instead of returning False. Defaults to False (don’t raise KeyError)

Returns:

a boolean indicating if the key is valid

Return type:

bool

In the base class Marina, this function always returns True but concrete subclasses may whish to exclude some keys.

keys() → a set-like object providing a view on D's keys
class configoose.database.Mediator

Bases: ABC

This is the base class of mediator objects which can be seen as smart pointers giving access to configuration content. Mediators have two main features:

  • They give access to configuration content through their read_text() or read_bytes() methods.

  • They can be serialized to strings that are stored as values in Marina mappings.

Subclasses of Mediator implement concrete access to configuration content in specific storage.

abstract read_bytes() → bytes

Read configuration content as bytes

read_text(encoding: str = 'utf8') → str

Read configuration content as a unicode string. The default implementation uses read_bytes()

Parameters:

encoding (str) – unicode encoding, defaults to utf8

abstract classmethod schema_type()

This required classmethod returns a subclass of marshmallow.Schema which is used to serialize instances of this class.

Instances of Mediator are serialized to be stored as values in Marina objects and deserialized during lookups in Db objects.

system_path()

Return a system path of this mediator if available, else None

class configoose.database.MediatorSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool = False, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Bases: Schema

A subclass of marshmallow.Schema used internally to serialize all instances of Mediator.

Don’t use this class directly. Use instead the functions mediator_dumps() and mediator_loads()

opts: SchemaOpts = <marshmallow.schema.SchemaOpts object>
postload(obj, **kwargs)
predump(obj, **kwargs)
configoose.database.ilen(iterable)

Utility function returning the length of an iterable

configoose.database.mediator_dumps(med: Mediator) → str

Serialize a mediator as a string

configoose.database.mediator_loads(s: str) → Mediator

Deserialize a string as a mediator