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]
Required packages: jinja2, hiyapyco >= 0.4.16.
The ymlparsers module is the low-level API used by init_app_conf, deploys, and optionally emails. It wraps HiYaPyCo to provide hierarchical YAML merging with Jinja2 templating, while avoiding global package-level state in HiYaPyCo itself.

​
HiYaPyCo

Extended subclass of hiyapyco.HiYaPyCo. Holds the Jinja2 context and lock used by all load/dump operations in this module. 
from alexber.utils.ymlparsers import HiYaPyCo

# Set after initConfig() is called:
HiYaPyCo.jinja2ctx   # Jinja2 Environment instance
HiYaPyCo.jinja2Lock  # threading.RLock instance

​
Class attributes

AttributeTypeDescription
jinja2ctxjinja2.Environment | NoneJinja2 environment used for variable interpolation. Set by initConfig().
jinja2Lockthreading.RLock | NoneReentrant lock protecting jinja2ctx access across threads. Set by initConfig().

​
safe_dump

Serialises a Python data structure to YAML and writes it to a stream. 
import io
from alexber.utils import ymlparsers

ymlparsers.initConfig()

buf = io.StringIO()
ymlparsers.safe_dump({'key': 'value', 'count': 3}, buf)
print(buf.getvalue())
​
data
any
required
Python data structure to serialise. Supports primitives, lists, dict, and collections.OrderedDict.
​
stream
IO
Stream to write the YAML representation to. If None, the result is returned as a string.
​
**kwds
dict
Additional keyword arguments forwarded to yaml.dump_all(). Override the defaults set in initConfig().
Returns: str representation of the data.

​
load

Loads and merges one or more hierarchical YAML files (and/or in-memory YAML strings). 
from alexber.utils import ymlparsers

ymlparsers.initConfig()

config = ymlparsers.load(['config.yml', 'config-dev.yml'])
To load without Jinja2 variable substitution: 
with ymlparsers.DisableVarSubst():
    config = ymlparsers.load(['config.yml'])
​
*args
str | list
required
One or more YAML file paths or in-memory YAML strings to load and merge.
​
method
int
Merge strategy. One of hiyapyco.METHOD_SIMPLE, hiyapyco.METHOD_MERGE, or hiyapyco.METHOD_SUBSTITUTE. Default: METHOD_SUBSTITUTE.
​
mergelists
bool
Whether to merge lists across files. Default: False (lists are replaced).
​
interpolate
bool
Whether to apply Jinja2 variable substitution. Default: True.
​
castinterpolated
bool
Whether to cast interpolated string values to their Python types. Default: True.
​
encoding
str
File encoding. Default: 'utf-8'.
​
failonmissingfiles
bool
Raise an error if a specified file does not exist. Default: True.
Returns: OrderedDict — merged configuration.

​
as_str

Returns the YAML string representation of a data structure. 
from alexber.utils import ymlparsers

ymlparsers.initConfig()

yaml_text = ymlparsers.as_str({'server': {'host': 'localhost', 'port': 8080}})
print(yaml_text)
​
data
any
required
Python data structure to serialise. Supports primitives, lists, dict, and collections.OrderedDict.
​
**kwds
dict
Additional keyword arguments forwarded to safe_dump().
Returns: str — YAML representation prefixed with a newline.

​
DisableVarSubst

Context manager that temporarily disables Jinja2 variable substitution during load() calls. Use this when loading the base configuration file to read raw (un-interpolated) values such as profile names. 
from alexber.utils import ymlparsers

ymlparsers.initConfig()

with ymlparsers.DisableVarSubst():
    raw_config = ymlparsers.load(['config.yml'])

# raw_config contains literal '{{ variable }}' strings
Providing a custom Jinja2 context: 
from threading import RLock
from jinja2 import Environment, DebugUndefined

custom_ctx = Environment(undefined=DebugUndefined)
custom_lock = RLock()

with ymlparsers.DisableVarSubst(jinja2ctx=custom_ctx, jinja2Lock=custom_lock):
    raw_config = ymlparsers.load(['config.yml'])
​
jinja2ctx
jinja2.Environment
Jinja2 environment to use. If not provided, HiYaPyCo.jinja2ctx is used. Must be provided together with jinja2Lock if supplied.
​
jinja2Lock
threading.RLock
Lock for synchronisation. Must be provided together with jinja2ctx if supplied.
Yields: The Jinja2 environment with substitution delimiters replaced by non-matching sentinels.

​
initConfig

Initialises the module. Must be called before load(), safe_dump(), as_str(), or DisableVarSubst(). Call once in the main thread at application startup. 
from alexber.utils import ymlparsers

ymlparsers.initConfig(
    jinja2ctx={
        'globals': {'app_version': '1.0.0'},
    },
    load={
        'mergelists': True,
    },
    safe_dump={
        'sort_keys': True,
    },
)
​
jinja2Lock
threading.RLock
Lock used for synchronisation inside DisableVarSubst and load(). If not supplied, a new threading.RLock is created.
​
jinja2ctx
dict
Keyword arguments forwarded to jinja2.Environment(undefined=DebugUndefined, ...). A special 'globals' key is extracted and passed to Environment.globals.update(). Default global: {'uname': platform.uname}.
​
load
dict
Overrides for load() defaults. Merged on top of: {'method': METHOD_SUBSTITUTE, 'mergelists': False, 'interpolate': True, 'castinterpolated': True}.
​
safe_dump
dict
Overrides for safe_dump() defaults. Merged on top of: {'default_flow_style': False, 'sort_keys': False}.
Returns: None. Idempotent when called from the main thread.

Build docs developers (and LLMs) love

Get started for freeTalk to us