listappendx

Listappendx is a utility function in software libraries designed to extend lists with enhanced control over how elements are appended. It builds on the standard append and extend operations by supporting batch insertion, optional filtering, and constraints that help manage duplicates, length, and identity during mutation.

Typical signature resembles listappendx(target, items, *, unique=False, max_size=None, key=None, ignore_none=True). The function accepts a target list, an iterable of items, and a set of optional keyword arguments that govern its behavior.

Behavior: The function mutates the target list in place, appending elements from items according to the options provided. If unique is True, it will skip elements whose identity matches a previously present item, as determined by key or by value. If max_size is not None, the final length is capped and any excess items are ignored. If ignore_none is True, None values are omitted.

Return value and edge cases: It returns the number of elements appended. If items is empty or all items are ignored, it returns 0. It is designed to be safe with respect to non-hashable elements only if a suitable key function is supplied.

Example: lst = [1, 2, 3]; listappendx(lst, [3, 4, 5], unique=True) yields [1, 2, 3, 4, 5] and returns 2.

See also: append, extend, itertools.chain.