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.Boolean(*args, **kwargs)

_holds: bool

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

_regex_pattern: 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.PathField(default_value: Path | str | _NoDefaultValueT = NoDefaultValue, /, path_type: PathField.PathType = PathField.directory_or_file, path_validator: PathField.PathValidator = PathValidator.agnostic, **kwargs)

Parameters:

default_value (Path | str | _NoDefaultValueT) – The default for this field.
path_type (PathField.PathType) – Whether you want to only accept files, directories, or both
path_validator (PathField.PathValidator) – Determines how it should validate the path string.

_holds: Path

_path_type: PathField.PathType

_path_validator: PathField.PathValidator

class comprehensiveconfig.spec.PathField.PathType

This is an enum representing the types of paths we would like to support in this field.

directory: We only want paths to point to directories!

file: We only want paths to point to files!

directory_or_file: Disables specific checks for what the paths are pointing to.

class comprehensiveconfig.spec.PathField.PathValidator

This is an enum representing the different path validators defined in comprehensiveconfig.validators

windows: Paths should only be valid Windows paths.

unix: Paths should only be valid Unix Paths

agnostic: Checks for validity on Unix or Windows (only one needs to be valid).

current_system: Uses the validator corresponding to the current current system.

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

class comprehensiveconfig.spec.ConfigObjectType[T](Protocol)

A protocol that describes exactly what any serializable object must contain.

classmethod from_config(config_value: Any)

Parameters:: ConfigValue (Any) – The incoming value when we want to construct an object of T from a configuration file being loaded.

class comprehensiveconfig.spec.ConfigObject[T: ConfigObjectType](_type: Type[T], default_value: T | _NoDefaultValueT = NoDefaultValue, /, *args, **kwargs)

Parameters:

_type (Type[T]) – The class of the enum we want to represent in this field.
default_value (T | NoDefaultValue) – Default value of our field

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

Important

Objects must be supported by the specific writer (comprehensiveconfig.configio.ConfigurationWriter) or must implement any necessary magic methods required to have them work generically in an existing config-writer.

This (by default) includes:

def __write_toml_value__(self, field, value) -> str (writing a regular toml-parsable value as a string)
def __write_toml_full__(self, field, value) -> str (Directly write line(s) of toml when encountering this object)
def __write_json_value__(self, field, value) -> int | float | datetime | str | None (When encountering this object- convert it to a json serializable format)

_holds: T

_Type: Type[T]