parsers

Low-level parsing utilities for command-line arguments, configuration files, type coercion, and emptiness checks.

The parsers module provides the foundational parsing primitives used by init_app_conf and other modules. It also monkey-patches configparser.ConfigParser and argparse.ArgumentParser with convenience as_dict() methods.

safe_eval

Converts a string representation of a Python number to its correct built-in numeric type.

from alexber.utils.parsers import safe_eval

safe_eval('42')      # 42   (int)
safe_eval('3.14')    # 3.14 (float)
safe_eval('hello')   # 'hello' (unchanged)
safe_eval('[1, 2]')  # [1, 2]

value · str · required

String to evaluate. Processed with ast.literal_eval; if that raises SyntaxError or ValueError, the original string is returned unchanged.

Returns: int, float, or the original value when conversion is not possible. Does not support decimal.Decimal, datetime, or NumPy types.

---

is_empty

Checks whether a value is None or an empty iterable.

from alexber.utils.parsers import is_empty

is_empty(None)   # True
is_empty('')     # True
is_empty([])     # True
is_empty('hi')   # False
is_empty([1])    # False

value · any · required

Value to check. Behaviour is undefined for non-iterable, non-None values.

Returns: bool — True if the value is None or an empty iterable, False otherwise.

---

parse_boolean

Converts a value to bool with case-insensitive string matching.

from alexber.utils.parsers import parse_boolean

parse_boolean(None)    # None
parse_boolean(True)    # True
parse_boolean(False)   # False
parse_boolean('True')  # True
parse_boolean('false') # False
parse_boolean('yes')   # raises ValueError

value · bool | str | None · required

Value to convert. A bool is returned as-is. A str equal to 'true' or 'false' (case-insensitive) returns the corresponding bool. Any other string raises ValueError.

Returns: bool | None — True, False, or None when the input is None.

Raises: ValueError — when the string cannot be interpreted as a boolean.

---

parse_sys_args

Parses command-line arguments and returns both typed params and a raw flat dictionary of unknown arguments.

from alexber.utils.parsers import parse_sys_args

# With explicit args list (suppresses sys.argv)
params, sys_d = parse_sys_args(
    args=['--general.config.file=myconfig.yml', '--db.host=localhost']
)

params.config_file  # 'myconfig.yml'
sys_d               # {'db.host': 'localhost'}

argumentParser · ArgumentParser

Optional argparse.ArgumentParser instance. If not supplied, a new one is created. The function adds --general.config.file to it before parsing.

args · list

If not None, suppresses sys.argv and uses this list as the argument source.

Returns: Tuple (params, sys_d) — params is the argparse.Namespace (with .config_file populated), sys_d is an OrderedDict of remaining --key=value arguments.

---

ConfigParser.as_dict

Monkey-patched method added to configparser.ConfigParser. Converts all sections and their key/value pairs into an OrderedDict of OrderedDicts.

from configparser import ConfigParser
from alexber.utils import parsers  # activates the monkey-patch

parser = ConfigParser()
parser.read('settings.ini')
d = parser.as_dict()
# {'section1': {'key1': 'value1', ...}, ...}

Returns: OrderedDict[str, OrderedDict[str, str]] — all sections with their string key/value pairs.

---

ArgumentParser.as_dict

Monkey-patched method added to argparse.ArgumentParser. Parses arguments of the form --key=value and returns them as a flat OrderedDict, stripping the -- prefix.

from argparse import ArgumentParser
from alexber.utils import parsers  # activates the monkey-patch

parser = ArgumentParser()
d = parser.as_dict(args=['--host=localhost', '--port=5432'])
# OrderedDict([('host', 'localhost'), ('port', '5432')])

args · list

Argument list to parse. If None, sys.argv[1:] is used (note: sys.argv[0] is always ignored).

Returns: OrderedDict[str, str | None] — keys without the -- prefix; value is None for bare flags with no =.