Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/alex-ber/AlexBerUtils/llms.txt

Use this file to discover all available pages before exploring further.

This module requires optional dependencies. Install them with:
python -m pip install alex-ber-utils[yml]
The init_app_conf module is the primary high-level API for application configuration. It merges command-line system arguments with hierarchical YAML configuration files using profile-based overrides.

​
conf

Namespace class holding configuration key constants used throughout the module. 
from alexber.utils.init_app_conf import conf

print(conf.GENERAL_KEY)   # 'general'
print(conf.PROFILES_KEY)  # 'profiles'

​
Constants

ConstantValueDescription
GENERAL_KEY'general'Top-level key for general config section.
PROFILES_KEY'profiles'Key for the active profile list.
WHITE_LIST_KEY'whiteListSysOverride'Key controlling which keys may be overridden from system args.
LIST_ENSURE_KEY'listEnsure'Key listing flat keys that must be treated as comma-delimited lists.
CONFIG_KEY'config'Sub-key under general holding config metadata.
FILE_LEY'file'Key under general.config storing the resolved config file path.

​
AppConfParser

Low-level parser class. In most cases you should use the module-level functions (parse_config, mask_value, etc.) rather than instantiating this class directly. 
from alexber.utils.init_app_conf import AppConfParser

parser = AppConfParser(implicit_convert=True)

​
__init__

​
implicit_convert
bool
required
If True, string values parsed from system args are automatically converted to their Python type (int, float, bool, etc.). Cannot be None.

​
mask_value

Converts a string value to its appropriate Python type when implicit_convert=True, otherwise returns the value unchanged. 
parser = AppConfParser(implicit_convert=True)
parser.mask_value('true')   # True
parser.mask_value('42')     # 42
parser.mask_value('hello')  # 'hello'
​
value
str
required
The string value to convert.
Returns: The converted value (bool, int, float, or str depending on content) when implicit_convert=True, or the original string when False.

​
to_convex_map

Converts a flat dot-notation dictionary into a nested OrderedDict. 
parser = AppConfParser(implicit_convert=True)
flat = {'general.profiles': 'dev,local', 'db.host': 'localhost'}
nested = parser.to_convex_map(flat)
# {'general': {'profiles': 'dev,local'}, 'db': {'host': 'localhost'}}
​
d
dict
required
Dictionary with flat dot-separated keys.
​
white_list_flat_keys
list
If provided, only keys that start with one of these prefixes are included in the output.
Returns: OrderedDict — nested dictionary.

​
merge_list_value_in_dicts

Merges a list value from a flat dictionary and a nested dictionary. The flat dictionary value takes precedence when non-empty.
​
flat_d
dict
required
Flat dictionary, typically from parsed system args. Cannot be None.
​
d
dict
required
Nested dictionary, typically from a parsed YAML file. Cannot be None.
​
main_key
str
required
Top-level key in d (e.g. 'general').
​
sub_key
str
required
Second-level key in d[main_key] (e.g. 'profiles').
Returns: The merged list value — from flat_d if non-empty, otherwise from d[main_key][sub_key].

​
parse_config

Full parse cycle: reads system args, loads YAML files with profile layering, and returns the merged config dict.
​
argumentParser
ArgumentParser
Optional argparse.ArgumentParser instance to extend with additional arguments before parsing.
​
args
list
If provided, suppresses sys.argv and uses this list as the argument source.
Returns: OrderedDict — fully merged configuration.

​
mask_value

Module-level convenience wrapper around AppConfParser.mask_value. 
from alexber.utils.init_app_conf import mask_value

mask_value('true')           # True
mask_value('3.14')           # 3.14
mask_value('hello', implicit_convert=False)  # 'hello'
​
value
str
required
The string value to convert.
​
implicit_convert
bool
If None (default), uses the value set in initConfig() (default True). If True, attempts type conversion. If False, returns value as-is.
Returns: The converted Python value.

​
to_convex_map

Module-level convenience wrapper around AppConfParser.to_convex_map. 
from alexber.utils.init_app_conf import to_convex_map

flat = {'general.profiles': 'dev', 'server.port': '8080'}
nested = to_convex_map(flat)
# OrderedDict([('general', OrderedDict([('profiles', 'dev')])),
#              ('server', OrderedDict([('port', 8080)]))])
​
d
dict
required
Dictionary with flat dot-separated keys.
​
white_list_flat_keys
list
If provided, only entries whose keys start with one of these prefixes are included.
​
implicit_convert
bool
If None (default), uses the value from initConfig(). If True, converts values to their Python types. If False, keeps values as strings.
Returns: OrderedDict — nested dictionary.

​
merge_list_value_in_dicts

Module-level convenience wrapper around AppConfParser.merge_list_value_in_dicts. 
from alexber.utils.init_app_conf import merge_list_value_in_dicts

flat_d = {'general.profiles': 'dev,local'}
yml_d  = {'general': {'profiles': ['staging']}}

result = merge_list_value_in_dicts(flat_d, yml_d, 'general', 'profiles')
# ['dev', 'local']   (flat_d value wins because it is non-empty)
​
flat_d
dict
required
Flat dictionary, usually from parsing system args.
​
d
dict
required
Nested dictionary, usually from parsing a YAML file.
​
main_key
str
required
Top-level key in d.
​
sub_key
str
required
Second-level key in d[main_key].
​
implicit_convert
bool
Applied only to flat_d values. If None, uses the value from initConfig().
Returns: Merged list — from flat_d when non-empty, otherwise from d[main_key][sub_key].

​
parse_config

The main function of the module. Parses command-line arguments, loads YAML configuration files with profile-based layering, and returns a single merged dictionary. 
from alexber.utils import ymlparsers
from alexber.utils.init_app_conf import parse_config

# Must be called before parse_config
ymlparsers.initConfig()

config = parse_config()
# config['general']['config']['file']  -> resolved path to config.yml
# config['general']['profiles']        -> active profiles list

​
How it works

  1. System args of the form --key=value are parsed.
  2. --general.config.file (default: config.yml) identifies the base YAML file.
  3. The base YAML is loaded to discover profiles and the white-list override policy.
  4. Profile files (config-dev.yml, config-local.yml, …) are layered on top.
  5. System args override the merged YAML result.
​
argumentParser
ArgumentParser
Optional argparse.ArgumentParser to extend before parsing.
​
args
list
If provided, suppresses sys.argv and uses this list as the argument source.
​
implicit_convert
bool
If None (default), uses the value from initConfig() (default True). Controls type conversion of system-arg values only; YAML values are always converted on a best-effort basis.
Returns: OrderedDict — fully merged configuration dictionary.

​
initConfig

Optional initialization function. Call this once at startup (in the main thread) to customise the default parser class and its kwargs. The module calls it automatically with defaults on import. 
from alexber.utils.init_app_conf import initConfig

initConfig(
    default_parser_cls='mypackage.MyConfParser',
    default_parser_kwargs={'implicit_convert': False},
)
​
default_parser_cls
str | type
Class (or fully-qualified string name) to use as the default parser. Defaults to AppConfParser.
​
default_parser_kwargs
dict
Default keyword arguments passed to default_parser_cls.__init__(). Merged on top of {'implicit_convert': True}.
Returns: None. This function is idempotent.

Build docs developers (and LLMs) love

Get started for freeTalk to us