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.

The parsers module provides low-level utilities for parsing command-line arguments, converting string values to Python types, and checking for empty values. It is the foundation used by init_app_conf.parse_config(). No optional dependencies are required — this module is available in the base install: 
pip install alex-ber-utils

​
Parsing CLI arguments

​
parse_sys_args(argumentParser=None, args=None)

Parses --key=value style CLI arguments and returns them as a flat OrderedDict.
​
argumentParser
ArgumentParser
An argparse.ArgumentParser instance. If None, a new one is created automatically.
​
args
list[str]
Explicit argument list. If None, reads from sys.argv[1:]. Pass a list to suppress sys.argv — useful in tests.
Returns: A tuple (params, sys_d) where:
  • params is the argparse.Namespace with known arguments (notably params.config_file)
  • sys_d is an OrderedDict of unknown --key=value arguments with -- stripped
from alexber.utils.parsers import parse_sys_args

args = [
    '--general.profiles=dev',
    '--general.log.root.level=20',
    '--app.inner_host_name=yahoo.com',
    '--app.white_list=gamma,alpha,betha',
]

params, sys_d = parse_sys_args(args=args)

# params.config_file => 'config.yml'  (default)
# sys_d =>
# {
#   'general.profiles': 'dev',
#   'general.log.root.level': '20',
#   'app.inner_host_name': 'yahoo.com',
#   'app.white_list': 'gamma,alpha,betha',
# }
The built-in recognized argument is --general.config.file (maps to params.config_file, default 'config.yml'). All other --key=value arguments become entries in sys_d. Arguments without = are parsed as keys with None as their value: 
params, sys_d = parse_sys_args(args=['--flag', '--key=value'])
# sys_d => {'flag': None, 'key': 'value'}
If the same key appears multiple times, the last value wins.

​
ArgumentParser

parsers.ArgumentParser is the standard argparse.ArgumentParser extended with an as_dict() method:

​
ArgumentParser.as_dict(args=None)

Parses --key=value arguments and returns them as an OrderedDict. Strips the -- prefix from keys. 
from alexber.utils.parsers import ArgumentParser

parser = ArgumentParser()

# From explicit args:
d = parser.as_dict(args=['--key=value', '--single'])
# => {'key': 'value', 'single': None}

# From sys.argv (when args=None):
d = parser.as_dict()
Note: all values in the returned dict are strings (or None). Use safe_eval() or mask_value() from init_app_conf to convert types.

​
Type conversion

​
safe_eval(value)

Converts a string to a Python number type (int or float) using ast.literal_eval. Returns the original string if conversion is not possible — it never raises. 
from alexber.utils.parsers import safe_eval

safe_eval('1000')   # => 1000   (int)
safe_eval('0.1')    # => 0.1   (float)
safe_eval('-5')     # => -5    (int)
safe_eval('John')   # => 'John' (str, unchanged)
safe_eval('%(message)s')  # => '%(message)s' (str, unchanged)
Supported conversions:
Input stringOutput
'1000'1000 (int)
'0.1'0.1 (float)
'-5'-5 (int)
'John''John' (str)
'%(message)s''%(message)s' (str)
Not supported: decimal.Decimal, datetime.datetime, numpy types.

​
parse_boolean(value)

Converts a value to a Python bool. String comparison is case-insensitive.
​
value
str | bool | None
The value to convert.
Returns: True, False, or None. Raises: ValueError for unrecognized strings. 
from alexber.utils.parsers import parse_boolean

parse_boolean('True')   # => True
parse_boolean('FALSE')  # => False
parse_boolean('tRuE')   # => True
parse_boolean(True)     # => True   (pass-through)
parse_boolean(None)     # => None

# Raises ValueError:
parse_boolean('yes')    # ValueError: unknown string for bool: 'yes'
parse_boolean('1')      # ValueError
Recognized strings (case-insensitive): 'true' → True, 'false' → False. All other strings raise ValueError.

​
Checking for empty values

​
is_empty(value)

Returns True if the value is None or an empty iterable (empty string, empty list, etc.). 
from alexber.utils.parsers import is_empty

is_empty(None)        # => True
is_empty('')          # => True
is_empty([])          # => True
is_empty('hello')     # => False
is_empty([None])      # => False  (list with one element)
is_empty(0)           # => True   (falsy, treated as empty)
is_empty(0.0)         # => True
is_empty(False)       # => True
is_empty(True)        # => False
For non-iterable numeric values, is_empty uses Python truthiness — 0 and 0.0 return True. This is by design for the configuration parsing use case but may be surprising in other contexts.

​
Integration with init_app_conf

parse_sys_args() is called internally by init_app_conf.parse_config(). The flow is:
1

parse_sys_args is called

Reads --key=value arguments from sys.argv (or the explicit args list). The --general.config.file argument is extracted into params.config_file.
2

Flat dict is white-listed

Only keys that match general.whiteListSysOverride entries are kept.
3

List keys are expanded

Keys listed in general.listEnsure are split on commas into Python lists.
4

to_convex_map is applied

The flat {'general.profiles': 'dev', 'app.host_name': 'yahoo.com'} dict is converted to nested OrderedDicts via to_convex_map().
5

YAML files are merged

The nested CLI dict is merged on top of the loaded YAML hierarchy.
You can call parse_sys_args() directly if you only need the raw flat argument dict without YAML loading: 
from alexber.utils.parsers import parse_sys_args

params, sys_d = parse_sys_args()
# sys_d is a flat OrderedDict of all --key=value CLI args
config_file = params.config_file  # e.g. 'config.yml'

Build docs developers (and LLMs) love

Get started for freeTalk to us