Fields

Fields are the most basic unit in Comprehensive Config. They are used to define named values in your configuration file.

For example- in toml:

x = "foo"

Module

comprehensiveconfig.spec.NoDefaultValue: _NoDefaultValueT: A sentinel value representing that no default value has been provided to some field

class comprehensiveconfig.spec._NoDefaultValueT: Non instantiable type for NoDefaultValue

class comprehensiveconfig.spec.ConfigurationFieldMeta

__or__[S, T](value: Type[T] | T) → S | Type[T]: Overwrite default type union behavior

abstract class comprehensiveconfig.spec.BaseConfigurationField

Abstract base class for all configuration fields

abstractmethod _validate_value(value: Any, name: str | None = None, /): The in-built validator for a given field.

abstract class comprehensiveconfig.spec.ConfigurationField[T](default_value: T | _NoDefaultValueT = NoDefaultValue, /, name: str | None = None, nullable: bool = False, doc: None | str = None, inline_doc: bool = True)

Parameters:

default_value (T | _NoDefaultValueT) – The default value used for this configuration file
name (str) – The name of the field in our configuration file
nullable (bool) – Defines if the value of the field can be None
doc (str | None) – The documentation/comment for this field (only exported in config formats that support comments)
inline_doc (bool) – Defines if the doc comment is on the same line as the field

Abstract base class for all configuration fields

abstractmethod _validate_value(value: Any, name: str | None = None, /)

Parameters:

value – The value we are validating
name – The transformed name of the field (used in error messages)

The in-built validator for a given field.

_holds: T: The type of data this field holds (used purely for annotation and IDE static type checking)

_name: str: The actual name used inside of your configuration file

_default_value: T | NoDefaultValue: The actual name used inside of your configuration file

_has_default: bool

_nullable: bool

doc: str | None = None: A doc comment added for configuration formats that support it

inline_doc: bool = True: Whether a doc comment should be rendered on the same line as the field (on formats that support comments)

class comprehensiveconfig.spec.Integer(*args, **kwargs)

_holds: int

class comprehensiveconfig.spec.Float(*args, **kwargs)

_holds: float | int

class comprehensiveconfig.spec.Text(*args, regex: str = '.*', **kwargs)

Parameters:: regex (str) – Defines a regex pattern to validate against. Useful for email fields, ips, and other structured data.

_holds: str

class comprehensiveconfig.spec.List[T](default_value: list[T] = [], /, inner_type: AnyConfigField | None = None, **kwargs)

Parameters:

default_value (list[T]) – The default value of the field. This always default to an empty list (required for static type checking)
inner_type (AnyConfigField | None) – The inner type used in the list. This is any field in the spec. This allows you to further validate the inner data.

_holds: list[T]

Note

Might require manual annotation if your default value remains an empty list

class comprehensiveconfig.spec.Table[K, V](default_value: dict[K, V] = {}, /, key_type: AnyConfigField | None = None, value_type: AnyConfigField | None = None, **kwargs)

Parameters:

default_value (dict[K, V]) – The default value of the field. This always default to an empty dict (required for static type checking)
key_type (AnyConfigField | None) – The type of the keys used in the dict. This is any field in the spec. This allows you to further validate the inner data.
value_type (AnyConfigField | None) – The type of the values used in the dict. This is any field in the spec. This allows you to further validate the inner data.

_holds: dict[K, V]

Note

Might require manual annotation if your default value remains an empty dict

class comprehensiveconfig.spec.TableSpec(cls, name: str | None = None, **kwargs)

Important

This is meant to only be used as a baseclass. The arguments provided above are for subclassing usage:

class MySpec(TableSpec, name="Something"):
    '''Instantiate to create a field'''
    pass

__init__(default_value: dict | NoDefaultValue = NoDefaultValue, /, *args, **kwargs)

Parameters:: default_value (dict | NoDefaultValue) – Default Value for a field of this type.

class comprehensiveconfig.spec.Section(cls, name: str | None = None, **kwargs)

Important

This is meant to only be used as a baseclass. The arguments provided above are for subclassing usage:

class SomeSection(Section, name="Something"):
    pass

_FIELDS: dict[str, AnyConfigField]

_SECTIONS: dict[str, Type]

_ALL_FIELDS: dict[str, AnyConfigField | Type]

_FIELD_NAME_MAP: dict[str, str]

_FIELD_VAR_MAP: dict[str, str]

_cls_name: str

_instance_name: str

_has_default: bool

_default_value: dict[str, Any] | _NoDefaultValueT

_parent: SectionParent

_instance_parent: AnyConfigField | None

_cls_parent: AnyConfigField | None

class comprehensiveconfig.spec.ConfigUnion[L, R](left_type: AnyConfigField | Type, right_type: AnyConfigField | Type, *args, **kwargs)

Important

This should not be instantiated directly! Instead do the following:

Integer() | Text(regex="...")

Also important to note that validation is done Left-to-Right. That means it will always try to match against the left-most types first

_holds: L | R

class comprehensiveconfig.spec.ConfigEnum[T](enum_type: Type[T], default_value: T | _NoDefaultValueT = NoDefaultValue, /, *args, by_name=False, **kwargs)

Parameters:

enum_type (Type[T]) – The class of the enum we want to represent in this field.
default_value (T | NoDefaultValue) – Default value of our field
by_name (bool) – Choose whether or not we should have variants use their value’s or their name’s when we validate configuration.

This is a way to use an existing python enum (enum.Enum) as a validated field.

_holds: T

_enum_type: Type[T]

_enum_members_reversed: dict[Any, T]: A reversed mapping of values and enum variants (instances) in the enumeration type