API Reference¶

This page contains the complete API reference for the mappingtools library.

Collectors¶

`AutoMapper` ¶

Bases: Mapping

A Mapping that automatically generates and assigns unique, minified strings for any new keys accessed. The minified keys are generated using the specified alphabet.

Parameters:

Name	Type	Description	Default
`alphabet`	`str`	str - The alphabet to use for generating minified keys. Default is uppercase ASCII letters (A-Z).	`ascii_uppercase`

Example

from mappingtools.collectors import AutoMapper auto_mapper = AutoMapper() auto_mapper['example_key'] 'A' auto_mapper['another_key'] 'B' auto_mapper['example_key'] 'A' auto_mapper

`CategoryCollector` ¶

Bases: defaultdict[str, MappingCollector[Category, VT_co]]

`init(aggregation=Aggregation.ALL, **kwargs)` ¶

Initialize the CategoryCollector with the specified aggregation mode.

Parameters:

Name	Type	Description	Default
`aggregation`	`Aggregation`	The mode for collecting mappings.	`ALL`

`add(data, **categories)` ¶

Add a single value to the appropriate category in the collector.

Parameters:

Name	Type	Description	Default
`data`	`VT_co`	The value to be added to the mapping.	required
`**categories`	`Category \| Callable[[VT_co], Category]`	Keyword arguments where keys are category names and values are either category values or callables that return category values.	`{}`

Returns:

Type	Description
	None

`collect(iterable, **categories)` ¶

Collect values from the given iterable and add them to the appropriate categories in the collector.

Parameters:

Name	Type	Description	Default
`iterable`	`Iterable[VT_co]`	An iterable containing values to collect.	required
`**categories`	`Category \| Callable[[Iterable[VT_co]], Category]`	Keyword arguments where keys are category names and values are either category values or callables that return category values.	`{}`

Returns:

Type	Description
	None

`CategoryCounter` ¶

Bases: CategoryCollector

`init(**kwargs)` ¶

Initialize the CategoryCounter.

`add(data, **categories)` ¶

Add a single value to the appropriate category in the collector.

Parameters:

Name	Type	Description	Default
`data`	`VT_co`	The value to be added to the mapping.	required
`**categories`	`Category \| Callable[[VT_co], Category]`	Keyword arguments where keys are category names and values are either category values or callables that return category values.	`{}`

Returns:

Type	Description
	None

`collect(iterable, **categories)` ¶

Collect values from the given iterable and add them to the appropriate categories in the collector.

Parameters:

Name	Type	Description	Default
`iterable`	`Iterable[VT_co]`	An iterable containing values to collect.	required
`**categories`	`Category \| Callable[[Iterable[VT_co]], Category]`	Keyword arguments where keys are category names and values are either category values or callables that return category values.	`{}`

Returns:

Type	Description
	None

`DictOperation` ¶

Bases: Flag

An enumeration class for tracking categories.

`MappingCollector` ¶

Bases: Generic[KT, VT_co]

`mapping` `property` ¶

Return a shallow copy of the internal mapping.

Returns:

Type	Description
`dict[KT, VT_co]`	dict[KT, VT_co]: A shallow copy of the internal mapping.

`init(aggregation=Aggregation.ALL, **kwargs)` ¶

Initialize the MappingCollector with the specified mode.

Parameters:

Name	Type	Description	Default
`aggregation`	`Aggregation`	The mode for collecting mappings.	`ALL`
`*args`		Variable positional arguments used to initialize the internal mapping.	required
`**kwargs`		Variable keyword arguments used to initialize the internal mapping.	`{}`

`add(key, *values)` ¶

Add one or more values to the internal mapping based on the specified mode.

Parameters:

Name	Type	Description	Default
`key`	`KT`	The key to be added to the mapping.	required
`*values`	`VT`	The values corresponding to the key.	`()`

Returns:

Type	Description
	None

`collect(iterable)` ¶

Collect key-value pairs from the given iterable and add them to the internal mapping based on the specified mode.

Parameters:

Name	Type	Description	Default
`iterable`	`Iterable[tuple[KT, VT]]`	An iterable containing key-value pairs to collect.	required

Returns:

Type	Description
	None

`MeteredDict` ¶

Bases: dict[KT, VT_co]

A dictionary that tracks access and modification statistics for its keys.

`operations` `cached` `property` ¶

Returns the list of active operations being tracked.

`count(key, operations=None)` ¶

Returns the number of times a key has been accessed.

Parameters:

Name	Type	Description	Default
`key`	`KT`	The key to check access count for.	required
`operations`	`DictOperation`	The operation of tracking to check.	`None`

`counts(operations=None)` ¶

Returns a summary of access counts for all keys in the dictionary.

Returns:

Type	Description
`dict[KT, dict[str, int]]`	dict[KT, dict[str, int]]: A dictionary containing access counts for each key.

`frequencies(operations=None)` ¶

Returns a summary of access frequencies for all keys in the dictionary.

Returns:

Type	Description
`dict[KT, dict[str, float]]`	dict[KT, dict[str, float]]: A dictionary containing access frequencies for each key.

`frequency(key, operations=None)` ¶

Returns the frequency of access for a key.

Parameters:

Name	Type	Description	Default
`key`	`KT`	The key to check access frequency for.	required
`operations`	`DictOperation \| None`	The operation to check. If None, checks all operations.	`None`

Returns:

Name	Type	Description
`float`	`dict[str, float]`	The frequency of access for the key.

`get(key, default=None)` ¶

Returns the value for the specified key if it exists, otherwise returns the default value. If the key does not exist, it increments the default access count.

`reset(key=None, operations=None)` ¶

Resets the tracking information for the specified operation and key.

Parameters:

Name	Type	Description	Default
`key`	`KT \| None`	The key to reset tracking information for (default is None, which resets all keys).	`None`
`operations`	`DictOperation \| None`	The operations to reset (default is None, which resets all).	`None`

Returns:

Type	Description
	None

`setdefault(key, default=None)` ¶

Returns the value for the specified key if it exists, otherwise sets it to the default value. If the key does not exist, it increments the default access count.

`summaries(operations=None)` ¶

Returns a summary of access information for all keys in the dictionary.

Returns:

Type	Description
`dict[KT, dict[str, Any]]`	dict[KT, dict[str, Any]]: A dictionary containing access information for each key.

`summary(key, operations=None)` ¶

Returns a summary of access information for each k in the dictionary.

Returns:

Type	Description
`dict[str, Any]`	dict[KT, dict[str, Any]]: A dictionary containing access information for each k.

`unused_keys(operations=None)` ¶

Returns a list of keys that have never been accessed.

Parameters:

Name	Type	Description	Default
`operations`	`DictOperation \| None`	The operation to check. If None, checks all operations.	`None`

Returns:

Type	Description
`list[KT]`	list[KT]: A list of keys that have never been accessed.

`used_keys(min_count=0, max_count=float('inf'), min_frequency=0.0, max_frequency=float('inf'), before=None, after=None, operations=None)` ¶

Returns a list of keys that have been accessed at least once.

Parameters:

Name	Type	Description	Default
`min_count`	`int`	Minimum number of accesses for the key to be included (default is 0).	`0`
`max_count`	`int`	Maximum number of accesses for the key to be included (default is float('inf')).	`float('inf')`
`min_frequency`	`float`	Minimum frequency of access for the key to be included (default is 0.0).	`0.0`
`max_frequency`	`float`	Maximum frequency of access for the key to be included (default is float('inf')).	`float('inf')`
`before`	`datetime \| None`	If specified, only keys accessed before this datetime will be included (default is None).	`None`
`after`	`datetime \| None`	If specified, only keys accessed after this datetime will be included (default is None).	`None`
`operations`	`DictOperation \| None`	The operation to check. If None, checks all operations.	`None`

Returns:

Type	Description
`list[KT]`	list[KT]: A list of keys that have been accessed.

`nested_defaultdict(nesting_depth=0, default_factory=None, **kwargs)` ¶

Return a nested defaultdict with the specified nesting depth and default factory. A nested_defaultdict with nesting_depth=0 is equivalent to builtin 'collections.defaultdict'. For each increment in nesting_depth an additional item accessor is added.

Parameters:

Name	Type	Description	Default
`nesting_depth`	`int`	The depth of nesting for the defaultdict (default is 0);	`0`
`default_factory`	`Callable`	The default factory function for the defaultdict (default is None).	`None`
`**kwargs`		Additional keyword arguments to initialize the most nested defaultdict.	`{}`

Returns:

Name	Type	Description
`defaultdict`	`defaultdict`	A nested defaultdict based on the specified parameters.

Operators¶

`distinct(key, *mappings)` ¶

Yield distinct values for the specified key across multiple mappings.

Parameters:

Name	Type	Description	Default
`key`	`K`	The key to extract distinct values from the mappings.	required
`*mappings`	`Mapping[K, Any]`	Variable number of mappings to search for distinct values.	`()`

Yields:

Type	Description
`Any`	Generator[K, Any, None]: A generator of distinct values extracted from the mappings.

`flatten(mapping, delimiter=None)` ¶

Flatten a nested mapping structure into a single-level dictionary.

Parameters:

Name	Type	Description	Default
`mapping`	`Mapping[Any, Any]`	The nested mapping to flatten.	required
`delimiter`	`str \| None`	Uses this delimiter to join the path parts. If None then return path tuple.	`None`

Returns:

Type	Description
`dict[tuple \| str, Any]`	dict

`inverse(mapping)` ¶

Return a new dictionary with keys and values swapped from the input mapping.

Parameters:

Name	Type	Description	Default
`mapping`	`Mapping[Any, set]`	The input mapping to invert.	required

Returns:

Name	Type	Description
`Mapping`	`Mapping[Any, set]`	A new Mapping with values as keys and keys as values.

`pivot(iterable, *, index, columns, values, aggregation=Aggregation.LAST)` ¶

Reshape data (produce a "pivot" table) based on column values.

Parameters:

Name	Type	Description	Default
`iterable`	`Iterable[Mapping]`	An iterable of mappings (e.g., list of dicts).	required
`index`	`str`	The key to use for the row labels.	required
`columns`	`str`	The key to use for the column labels.	required
`values`	`str`	The key to use for the values.	required
`aggregation`	`Aggregation`	The aggregation mode to use for values. Defaults to Aggregation.LAST.	`LAST`

Returns:

Type	Description
`dict[Any, dict[Any, Any]]`	A nested dictionary: {index_value: {column_value: aggregated_value}}.

`rekey(mapping, key_factory, *, aggregation=Aggregation.LAST)` ¶

Transform keys of a mapping based on a factory function of (key, value).

This allows "re-indexing" a mapping where the new key depends on the content of the value or a combination of the old key and value. Collisions are handled according to the specified aggregation.

Parameters:

Name	Type	Description	Default
`mapping`	`Mapping[Any, Any]`	The source mapping.	required
`key_factory`	`Callable[[Any, Any], K]`	A callable that takes (key, value) and returns the new key.	required
`aggregation`	`Aggregation`	How to handle key collisions. Defaults to Aggregation.LAST.	`LAST`

Returns:

Type	Description
`dict[K, Any]`	A new dictionary with keys generated by the factory and aggregated values.

`rename(mapping, mapper, *, aggregation=Aggregation.LAST)` ¶

Rename keys in a mapping based on a mapper (Mapping or Callable).

This operator creates a new dictionary with renamed keys. If a key is not present in the mapper, it remains unchanged. Collisions (when multiple original keys map to the same new key) are handled according to the specified aggregation.

Parameters:

Name	Type	Description	Default
`mapping`	`Mapping[K, Any]`	The source mapping.	required
`mapper`	`Mapping[K, K] \| Callable[[K], K]`	A dictionary mapping old keys to new keys, or a function that transforms keys.	required
`aggregation`	`Aggregation`	How to handle key collisions. Defaults to Aggregation.LAST.	`LAST`

Returns:

Type	Description
`dict[K, Any]`	A new dictionary with renamed keys and aggregated values.

`reshape(iterable, keys, value, aggregation=Aggregation.LAST)` ¶

Reshape a stream of mappings into a nested dictionary (tensor) of arbitrary depth.

This is a generalization of pivot that supports N-dimensional nesting.

Parameters:

Name	Type	Description	Default
`iterable`	`Iterable[Mapping]`	An iterable of mappings (records).	required
`keys`	`Sequence[str \| Callable[[Mapping], Any]]`	A sequence of keys (or callables) to use for the nesting hierarchy.	required
`value`	`str \| Callable[[Mapping], Any]`	The key (or callable) to use for the leaf values.	required
`aggregation`	`Aggregation`	The aggregation mode to use for collisions at the leaf.	`LAST`

Returns:

Type	Description
`dict[Any, Any]`	A nested dictionary where the depth equals len(keys).

Optics¶

`Lens` ¶

Bases: Generic[T, U]

A functional optic that focuses on a specific part of a data structure.

Lenses allow you to get, set, and modify deeply nested data in an immutable way. They are composable using the / operator, similar to pathlib.

Example

data = {"user": {"profile": {"name": "Alice"}}}

Path-like composition with auto-inference for keys/indices¶

name_lens = Lens.key("user") / "profile" / "name" name_lens.get(data) 'Alice'

Lenses are callable (alias for get)¶

name_lens(data) 'Alice' new_data = name_lens.set(data, "Bob") new_data["user"]["profile"]["name"] 'Bob' data["user"]["profile"]["name"] # Original is unchanged 'Alice'

`call(source)` ¶

Alias for get(). Allows the lens to be used as a function.

`rtruediv(other)` ¶

Allows composition when the left operand is not a Lens. Example: "users" / Lens.key("name")

`truediv(other)` ¶

Composes this lens with another lens using the / operator. If 'other' is not a Lens, it is treated as a key/index item.

`attr(name)` `staticmethod` ¶

Creates a lens that focuses on an object attribute.

`get(source)` ¶

Extracts the focus value from the source.

`index(i)` `staticmethod` ¶

Creates a lens that focuses on a list index.

`item(k)` `staticmethod` ¶

Creates a smart lens that focuses on an item (key or index). It detects the container type at runtime to ensure correct immutable setting.

`key(k)` `staticmethod` ¶

Creates a lens that focuses on a dictionary key.

`modify(source, func)` ¶

Modifies the focus value using a function.

`path(*segments)` `staticmethod` ¶

Creates a lens from a sequence of keys/indices. Example: Lens.path("users", 0, "name")

`set(source, value)` ¶

Sets the focus value, returning a new source object (if supported).

`patch(data, changes)` ¶

Applies a set of changes to a data structure immutably.

Parameters:

Name	Type	Description	Default
`data`	`T`	The source data structure.	required
`changes`	`Mapping[str \| Lens, Any]`	A mapping of paths (dot-separated strings or Lenses) to new values.	required

Returns:

Type	Description
`T`	A new data structure with the changes applied.

`project(data, schema)` ¶

Projects a data structure into a new dictionary shape based on a schema.

Parameters:

Name	Type	Description	Default
`data`	`Any`	The source data structure.	required
`schema`	`Mapping[str, str \| Lens]`	A mapping of output keys to source paths (dot-separated strings or Lenses).	required

Returns:

Type	Description
`dict[str, Any]`	A new dictionary containing the projected values.

Example

data = {"user": {"name": "Alice", "version": 1}} project(data, {"username": "user.name", "v": "user.version"})

Structures¶

`Dictifier` ¶

Bases: dict[str, T], Generic[T]

A dict-like object that proxies attribute access to its values.

This class requires an explicit type to be provided, either through generic type hinting (e.g., Dictifier[MyClass]) or by using the @dictify decorator. It will not infer the type from its contents.

Method Chaining and Type Safety

When you call a proxied method, it attempts to determine the return type from the method's type hints. If successful, it returns a new strict Dictifier. If not, it falls back to an AutoDictifier to allow chaining via type inference.

For a version that always infers types, see AutoDictifier.

`getattr(name)` ¶

Proxies attribute access to the contained objects.

`auto(source)` `classmethod` ¶

Creates a Dictifier that automatically infers types from its contents.

`of(target_class)` `classmethod` ¶

Creates a specialized Dictifier subclass for the given target class.

This method inspects the target class and pre-compiles proxy methods for all its public methods and properties. This provides significantly better performance than the standard dynamic Dictifier.

Parameters:

Name	Type	Description	Default
`target_class`	`type[T]`	The class to wrap.	required

Returns:

Type	Description
`type[Dictifier[T]]`	A new class that inherits from Dictifier and has specialized proxies.

`LazyDictifier` ¶

Bases: Mapping[str, T], Generic[T]

A dict-like object that lazily proxies attribute access to its values.

Operations (method calls, attribute access) are not executed immediately. Instead, they build up a pipeline of operations. The pipeline is only executed for a specific key when that key is accessed.

`call(*args, **kwargs)` ¶

Adds a method call operation to the chain.

`getattr(name)` ¶

Adds a new operation to the chain.

`getitem(key)` ¶

Executes the operation chain for a specific key.

`iter()` ¶

Iterates over the keys of the original source.

`len()` ¶

Returns the length of the original source.

`map_objects(source, *, lazy=False, type_hint=None)` ¶

map_objects(source: Mapping[str, T], *, lazy: bool = False, type_hint: type[T]) -> Dictifier[T]

map_objects(source: Mapping[str, T], *, lazy: bool = True, type_hint: type[T] | None = None) -> LazyDictifier[T]

map_objects(source: Mapping[str, T], *, lazy: bool = False, type_hint: None = None) -> Dictifier[T]

Creates a proxy mapping for a collection of objects.

This factory function provides a unified entry point for creating Dictifier or LazyDictifier instances based on the desired behavior.

Parameters:

Name	Type	Description	Default
`source`	`Mapping[str, T]`	The source mapping of objects (e.g., a dict).	required
`lazy`	`bool`	If True, returns a LazyDictifier that defers execution. If False (default), returns an eager Dictifier.	`False`
`type_hint`	`type[T] \| None`	Optional class type of the objects in the source. If provided, returns a strict Dictifier. If None, returns a Dictifier in auto-inference mode.	`None`

Returns:

Type	Description
`Mapping[str, T]`	A Mapping that proxies attribute access to the contained objects.

Transformers¶

`Transformer` ¶

A class to transform objects recursively based on their type.

`call(obj)` ¶

Transform the given object using the appropriate handler.

Parameters:

Name	Type	Description	Default
`obj`	`Any`	The object to transform.	required

Returns:

Name	Type	Description
`Any`	`Tree[Any]`	The transformed object.

`init(mapping_handler=None, iterable_handler=None, class_handler=None, default_handler=None, *args, **kwargs)` ¶

Initialize the Transformer with optional handlers for different types of objects.

Parameters:

Name	Type	Description	Default
`mapping_handler`	`Optional[Callable]`	Handler for mapping objects.	`None`
`Iterable_handler`	`Optional[Callable]`	Handler for iterable objects.	required
`Class_handler`	`Optional[Callable]`	Handler for class instances.	required
`Default_handler`	`Optional[Callable]`	Default handler for other objects.	required
`*args`		Additional positional arguments for handlers.	`()`
`**kwargs`		Additional keyword arguments for handlers.	`{}`

API Reference¶

Collectors¶

AutoMapper ¶

CategoryCollector ¶

__init__(aggregation=Aggregation.ALL, **kwargs) ¶

add(data, **categories) ¶

collect(iterable, **categories) ¶

CategoryCounter ¶

__init__(**kwargs) ¶

add(data, **categories) ¶

collect(iterable, **categories) ¶

DictOperation ¶

MappingCollector ¶

mapping property ¶

__init__(aggregation=Aggregation.ALL, **kwargs) ¶

add(key, *values) ¶

collect(iterable) ¶

MeteredDict ¶

operations cached property ¶

count(key, operations=None) ¶

counts(operations=None) ¶

frequencies(operations=None) ¶

frequency(key, operations=None) ¶

get(key, default=None) ¶

reset(key=None, operations=None) ¶

setdefault(key, default=None) ¶

summaries(operations=None) ¶

summary(key, operations=None) ¶

unused_keys(operations=None) ¶

used_keys(min_count=0, max_count=float('inf'), min_frequency=0.0, max_frequency=float('inf'), before=None, after=None, operations=None) ¶

nested_defaultdict(nesting_depth=0, default_factory=None, **kwargs) ¶

Operators¶

distinct(key, *mappings) ¶

flatten(mapping, delimiter=None) ¶

inverse(mapping) ¶

pivot(iterable, *, index, columns, values, aggregation=Aggregation.LAST) ¶

rekey(mapping, key_factory, *, aggregation=Aggregation.LAST) ¶

rename(mapping, mapper, *, aggregation=Aggregation.LAST) ¶

reshape(iterable, keys, value, aggregation=Aggregation.LAST) ¶

Optics¶

Lens ¶

Path-like composition with auto-inference for keys/indices¶

Lenses are callable (alias for get)¶

__call__(source) ¶

__rtruediv__(other) ¶

__truediv__(other) ¶

attr(name) staticmethod ¶

get(source) ¶

index(i) staticmethod ¶

item(k) staticmethod ¶

key(k) staticmethod ¶

modify(source, func) ¶

path(*segments) staticmethod ¶

set(source, value) ¶

patch(data, changes) ¶

project(data, schema) ¶

Structures¶

Dictifier ¶

__getattr__(name) ¶

auto(source) classmethod ¶

of(target_class) classmethod ¶

LazyDictifier ¶

__call__(*args, **kwargs) ¶

__getattr__(name) ¶

__getitem__(key) ¶

__iter__() ¶

__len__() ¶

map_objects(source, *, lazy=False, type_hint=None) ¶

Transformers¶

Transformer ¶

__call__(obj) ¶

__init__(mapping_handler=None, iterable_handler=None, class_handler=None, default_handler=None, *args, **kwargs) ¶

`AutoMapper` ¶

`CategoryCollector` ¶

`init(aggregation=Aggregation.ALL, **kwargs)` ¶

`add(data, **categories)` ¶

`collect(iterable, **categories)` ¶

`CategoryCounter` ¶

`init(**kwargs)` ¶

`add(data, **categories)` ¶

`collect(iterable, **categories)` ¶

`DictOperation` ¶

`MappingCollector` ¶

`mapping` `property` ¶

`init(aggregation=Aggregation.ALL, **kwargs)` ¶

`add(key, *values)` ¶

`collect(iterable)` ¶

`MeteredDict` ¶

`operations` `cached` `property` ¶

`count(key, operations=None)` ¶

`counts(operations=None)` ¶

`frequencies(operations=None)` ¶

`frequency(key, operations=None)` ¶

`get(key, default=None)` ¶

`reset(key=None, operations=None)` ¶

`setdefault(key, default=None)` ¶

`summaries(operations=None)` ¶

`summary(key, operations=None)` ¶

`unused_keys(operations=None)` ¶

`used_keys(min_count=0, max_count=float('inf'), min_frequency=0.0, max_frequency=float('inf'), before=None, after=None, operations=None)` ¶

`nested_defaultdict(nesting_depth=0, default_factory=None, **kwargs)` ¶

`distinct(key, *mappings)` ¶

`flatten(mapping, delimiter=None)` ¶

`inverse(mapping)` ¶

`pivot(iterable, *, index, columns, values, aggregation=Aggregation.LAST)` ¶

`rekey(mapping, key_factory, *, aggregation=Aggregation.LAST)` ¶

`rename(mapping, mapper, *, aggregation=Aggregation.LAST)` ¶

`reshape(iterable, keys, value, aggregation=Aggregation.LAST)` ¶

`Lens` ¶

`call(source)` ¶

`rtruediv(other)` ¶

`truediv(other)` ¶

`attr(name)` `staticmethod` ¶

`get(source)` ¶

`index(i)` `staticmethod` ¶

`item(k)` `staticmethod` ¶

`key(k)` `staticmethod` ¶

`modify(source, func)` ¶

`path(*segments)` `staticmethod` ¶

`set(source, value)` ¶

`patch(data, changes)` ¶

`project(data, schema)` ¶

`Dictifier` ¶

`getattr(name)` ¶

`auto(source)` `classmethod` ¶

`of(target_class)` `classmethod` ¶

`LazyDictifier` ¶

`call(*args, **kwargs)` ¶

`getattr(name)` ¶

`getitem(key)` ¶

`iter()` ¶

`len()` ¶

`map_objects(source, *, lazy=False, type_hint=None)` ¶

`Transformer` ¶

`call(obj)` ¶

`init(mapping_handler=None, iterable_handler=None, class_handler=None, default_handler=None, *args, **kwargs)` ¶