----------------------------------------------------------------------
This is the API documentation for the gdtest_docstring_notes library.
----------------------------------------------------------------------


## Functions

Public functions


merge_dicts(a: dict, b: dict) -> dict

Merge two dictionaries into a new dictionary.

Creates a new dictionary containing all key-value pairs from
both ``a`` and ``b``. When keys overlap, values from ``b``
take precedence.

Parameters
----------
a
    The base dictionary.
b
    The dictionary whose values take priority on conflict.

Returns
-------
dict
    A new dictionary containing the merged key-value pairs.

Notes
-----
The merge algorithm works in two phases. First, a shallow copy
of ``a`` is created using ``dict.copy()``. Then, all entries
from ``b`` are inserted into the copy using ``dict.update()``.

This means that the original dictionaries ``a`` and ``b`` are
never modified. However, because only a shallow copy is made,
mutable values (such as lists or nested dicts) are shared
between the original and the merged result.

If you need a deep merge where nested structures are also
merged recursively, consider using ``copy.deepcopy()`` on the
result or implementing a custom recursive merge function.

The time complexity is ``O(len(a) + len(b))`` since both
the copy and update operations are linear.

Examples
--------
>>> merge_dicts({"x": 1}, {"y": 2})
{'x': 1, 'y': 2}

>>> merge_dicts({"x": 1}, {"x": 99})
{'x': 99}

flatten_list(nested: list) -> list

Flatten an arbitrarily nested list into a single flat list.

Recursively traverses the input list and collects all
non-list elements into a single flat list.

Parameters
----------
nested
    A potentially nested list of values.

Returns
-------
list
    A flat list containing all leaf elements.

Notes
-----
The function uses recursion to handle arbitrarily deep nesting.
For each element in the input, it checks whether the element
is itself a ``list``. If so, it recurses into that sublist.
Otherwise, the element is appended to the result.

Because Python has a default recursion limit of 1000, this
function will raise a ``RecursionError`` for lists nested
deeper than approximately 500 levels (accounting for the
two-frame overhead per recursive call).

The implementation allocates a new list and extends it with
each recursive result. The overall time complexity is
``O(n)`` where ``n`` is the total number of leaf elements,
but the constant factor depends on the nesting depth due
to intermediate list allocations.

Examples
--------
>>> flatten_list([1, [2, [3, 4], 5], 6])
[1, 2, 3, 4, 5, 6]

>>> flatten_list([[["deep"]]])
['deep']