# Configuration fields in CONFspirator

CONFspirator supports multiple different fields for configuration, ranging from simple strings and ints, all the way to dictionaries and lists, with some special cases like ports, hostnames, and uri’s.

## Options for all fields

These options are supported for all config fields in addition to the specific ones the field might have.

### Options

#### name

The config field’s name. It is always the first parameter when defining a config field.

#### help_text

An explanation of how the option is used or what it is for.

#### default

The default value of the option.

#### required

If a value must be supplied for this option and cannot be empty or blank.

#### test_default

A default for when running in test mode.

#### sample_default

A default for sample config files.

#### unsafe_default (unused currently)

If the default value must be overridden.

Once implemented will warn or raise an error when a certain flag is given if the default value hasn’t been overridden.

#### secret (unused currently)

If the value should be obfuscated in log output.

Once implemented will be used to help provide information about what values to obfuscated in logs.

#### deprecated_location

Deprecated dot separated location. Acts like an alias to where the config used to be. e.g. ‘service.group1.old_name’

#### deprecated_for_removal

Indicates whether this opt is planned for removal in a future release.

#### deprecated_reason

Indicates why this opt is planned for removal in a future release. Silently ignored if deprecated_for_removal is False.

#### deprecated_since

indicates which release this opt was deprecated in. Accepts any string, though valid version strings are encouraged. Silently ignored if deprecated_for_removal is False

#### advanced (unused currently)

A bool True/False value if this option has advanced usage and is not normally used by the majority of users.

## StrConfig

Simple string based config.

### Options

#### name

The config’s name.

#### choices (optional)

Optional sequence of either valid values or tuples of valid values with descriptions.

#### quotes (optional)

If True and string is enclosed with single or double quotes, will strip those quotes.

#### regex (optional)

Optional regular expression (string or compiled regex) that the value must match on an unanchored search.

#### ignore_case (optional)

If True case differences (uppercase vs. lowercase) between ‘choices’ or ‘regex’ will be ignored.

#### max_length (optional)

If positive integer, the value must be less than or equal to this parameter.

### Example usage

    config_group.register_child_config(
        fields.StrConfig(
            "my_string_config",
            help_text="Some useful help text.",
            required=True,
            default="stuff",
        )
    )

## BoolConfig

Simple boolean based config.

### Options

#### name

The config’s name.

### Example usage

    config_group.register_child_config(
        fields.BoolConfig(
            "my_boolean_config",
            help_text="Some useful help text.",
            required=True,
            default=False,
        )
    )

## IntConfig

Simple int based config.

### Options

#### name

The config’s name.

#### min (optional)

Minimum value the integer can take.

#### max (optional)

Maximum value the integer can take.

### Example usage

    config_group.register_child_config(
        fields.IntConfig(
            "my_int_config",
            help_text="Some useful help text.",
            required=True,
            default=6,
            min=1,
            max=10,
        )
    )

## FloatConfig

Simple float based config.

### Options

#### name

The config’s name.

#### min (optional)

Minimum value the float can take.

#### max (optional)

Maximum value the float can take.

### Example usage

    config_group.register_child_config(
        fields.FloatConfig(
            "my_float_config",
            help_text="Some useful help text.",
            required=True,
            default=6.4,
            min=1.2,
            max=10.9,
        )
    )

## ListConfig

A list config, with a configurable type for items.

### Options

#### name

The config’s name.

#### item_type (optional)

Type of items in the list (see `confspirator.types`). If not set will default to a list of strings.

### Example usage

    config_group.register_child_config(
        fields.ListConfig(
            "my_list_config",
            help_text="Some useful help text.",
            required=True,
            default=["stuff", "things"],
        )
    )

## DictConfig

A dict config, with a configurable type for values.

### Options

#### name

The config’s name.

#### value_type (optional)

Type of values in the dict (see `confspirator.types`). If not set will default to strings.

#### check_value_type (optional)

If value is already dict, should we check value type.

#### is_json (optional)

If True and value is string, will parse as json.

### Example usage

    config_group.register_child_config(
        fields.DictConfig(
            "my_dict_config",
            help_text="Some useful help text.",
            required=True,
            default={"stuff": "things"},
        )
    )

## IPConfig

IP address config.

### Options

#### name

The config’s name.

#### version (optional)

One of either `4`, `6`, or `None` to specify either version.

### Example usage

    config_group.register_child_config(
        fields.IPConfig(
            "my_ip_config",
            help_text="Some useful help text.",
            required=True,
            default=0.0.0.0,
            version=4,
        )
    )

## PortConfig

Config for a TCP/IP port number. Ports can range from 0 to 65535.

### Options

#### name

The config’s name.

#### min (optional)

Minimum value the port can take.

#### max (optional)

Maximum value the port can take.

#### choices (optional)

Sequence of valid values.

### Example usage

    config_group.register_child_config(
        fields.PortConfig(
            "my_port_config",
            help_text="Some useful help text.",
            required=True,
            default=222,
            min=2000,
            max=9999,
        )
    )

## HostNameConfig

Config for a hostname. Only accepts valid hostnames.

### Options

#### name

The config’s name.

### Example usage

    config_group.register_child_config(
        fields.HostNameConfig(
            "my_hostname_config",
            help_text="Some useful help text.",
            required=True,
            default="prod.cluster.thing.net",
        )
    )

## HostAddressConfig

Option for either an IP or a hostname.

### Options

#### name

The config’s name.

#### version (optional)

One of either `4`, `6`, or `None` to specify either version.

### Example usage

    config_group.register_child_config(
        fields.HostAddressConfig(
            "my_hostaddress_config",
            help_text="Some useful help text.",
            required=True,
            default="prod.cluster.thing.net",
        )
    )

## URIConfig

Option for either a URI.

### Options

#### name

The config’s name.

#### max_length (optional)

If positive integer, the value must be less than or equal to this parameter.

#### schemes (optional)

List of valid URI schemes, e.g. ‘https’, ‘ftp’, ‘git’.

### Example usage

    config_group.register_child_config(
        fields.URIConfig(
            "my_url_config",
            help_text="Some useful help text.",
            required=True,
            default="https://example.com",
            schemes["https", "http"]
        )
    )