support¶

cincoconfig.make_type(schema, name, module=None, key_filename=None)¶

Create a new type that wraps this schema. This method should only be called once per schema object.

Use this method when to create reusable configuration objects that can be used multiple times in code in a more traditional Pythonic manner. For example, consider the following:

item_schema = Schema()
item_schema.url = UrlField()
item_schema.verify_ssl = BoolField(default=True)

schema = Schema()
schema.endpoints = ListField(item_schema)

config = schema()

# to create new web hook items
item = webhook_schema()
item.url = 'https://google.com'
item.verify_ssl = False

config.endpoints.append(item)

This is a cumbersome design when creating these objects within code. make_type will dynamically create a new class that can be used in a more Pythonic way:

# same schema as above
config = schema()
Item = make_type(item_schema, 'Item')

item = Item(url='https://google.com', verify_ssl=False)
config.endpoints.append(item)

The new class inherits from Config.

Parameters

name (str) – the new class name
module (Optional[str]) – the owning module
key_filename (Optional[str]) – the key file name passed to each new config object,
validator – config validator callback method

Return type

Type[ConfigType]

Returns

the new type

cincoconfig.generate_argparse_parser(schema, **parser_kwargs)¶

Generate a argparse.ArgumentParser based on the schema. This method generates --long-arguments for each field that stores a string, integer, float, or bool (based on the field’s storage_type). Boolean fields have two long arguments created, one to store a True value and another, --no-[x], to disable it.

Parameters: kwargs – keyword arguments to pass to the generated ArgumentParser constructor
Return type: ArgumentParser
Returns: the generated argument parser

cincoconfig.validator(field)¶

Decorator to register a new validator with the schema or field. All validators will be run against the configuration whenever the configuration is loaded from disk. Multiple validators can be registered by using the decorator multiple times. Subconfigs can also be validated by using the decorator on the sub schema.

schema = Schema()
schema.x = IntField()
schema.y = IntField()
schema.db.username = StringField()
schema.db.password = StringField()

@validator(schema)
def validate_x_lt_y(cfg):
    if cfg.x and cfg.y and cfg.x >= cfg.y:
        raise ValueError('x must be less-than y')

@validator(schema.db)
def validate_db_credentials(cfg):
    if cfg.username and not db.password:
        raise ValueError('db.password is required when username is specified')

config = schema()
config.load('config.json', format='json')  # will call the above validators
# .....

The validator function needs to raise an exception, preferably a ValueError, if the validation fails.

Parameters: func – validator function that accepts a single argument: Config.
Return type: Callable
Returns: func

cincoconfig.get_all_fields(schema)¶

Get all the fields and nested fields of the schema or config, including the nested schemas/configs.

>>> schema = Schema()
>>> schema.x = IntField()
>>> schema.y.z = StringField()
>>> schema.z = StringField()
>>> get_all_fields(schema)
[
    ('x', schema, schema.x),
    ('y.z', schema.y, schema.y.z),
    ('z', schema, schema.z)
]

The returned list of tuples have three values:

path - the full path to the field.
schema - the schema that the field belongs to.
field - the field.

The order of the fields will be the same order in which the fields were added to the schema.

Return type: List[Tuple[str, Schema, BaseField]]
Returns: all the fields as a list of tuples: (path, schema, field)

cincoconfig.cmdline_args_override(config, args, ignore=None)¶

Override configuration setting based on command line arguments, parsed from the argparse module. This method is useful when loading a configuration but allowing the user the option to override or extend the configuration via command line arguments.

parser = argparse.ArgumentParser()
parser.add_argument('-d', '--debug', action='store_const', const='debug', dest='mode')
parser.add_argument('-p', '--port', action='store', dest='http.port')
parser.add_argument('-H', '--host', action='store', dest='http.address')
parser.add_argument('-c', '--config', action='store')

args = parser.parse_args()
if args.config:
    config.load(args.config, format='json')

config.cmdline_args_override(args, ignore=['config'])

# cmdline_args_override() is equivalent to doing:

if args.mode:
    config.mode = args.mode
if getattr(args, 'http.port'):
    config.http.port = getattr(args, 'http.port')
if getattr(args, 'http.address'):
    config.http.address = getattr(args, 'http.address')

This method is compatible with manually created argument parser and an autogenerated one from the Schema generate_argparse_parser() method.

Parameters

args (Namespace) – parsed command line arguments from parse_args()
ignore (Union[str, List[str], None]) – list of arguments to ignore and not process

Return type

None

cincoconfig.item_ref_path(item)¶

Get the full reference path to a field or configuration.

Parameters: item (Union[BaseField, Config]) – field, schema, or configuration
Return type: str
Returns: full reference path to the item

cincoconfig.get_fields(schema, types=None)¶

Get all fields within a configuration or schema. This method does not recurse into nested schemas/configs, unlike get_all_fields(). The return value is a list of fields as tuples (key, field).

Parameters

schema (Union[Config, Schema]) – schema or configuration object
types (Union[Type, Tuple[Type], None]) – only return fields of a specific type

Return type

List[Tuple[str, BaseField]]

Returns

the list of fields

cincoconfig.asdict(config, virtual=False)¶

Converts the configuration object to a dict. Whereas to_tree() converts the configuration to a basic value tree suitable for saving to disk, the asdict method converts the configuration, and all nested configuration objects, to a dict, preserving each value as-is.

Parameters

config (Config) – the configuration to convert to a dict
virtual (bool) – include virtual field values in the dict

Return type

dict

Returns

the converted configuration dict

cincoconfig.is_value_defined(config, key)¶

Check if the given field has been set by the user through either loading a configuration file or using the API to set the field value.

Parameters

config (Config) – configuration object
key (str) – field key

Return type

bool

Returns

the field is set by the user

cincoconfig.reset_value(config, key)¶

Reset a config value back to the default.

Parameters

config (Config) – configuration object
key (str) – field key

Return type

None