ChainMap

Key lookup on a sequence of maps.

Attributes

Attribute	Type	Description
key_t	callable = None	A callable used to transform or normalize keys before they are used for lookups, insertions, or deletions.
changes	Mapping = None	The primary mapping where all updates, insertions, and deletions are applied.
defaults	list of Mappings = None	A list of fallback mappings searched in order if a key is not found in the changes mapping.
maps	list of Mappings = None	The complete sequence of mappings, including the changes mapping and all default mappings, used for sequential key lookups.

---

Constructor

Signature

def ChainMap(
    *maps: Mapping,
    **kwargs: Any
) - > None

Parameters

Name	Type	Description
*maps	Mapping	A variable number of mapping objects to be searched in order.
**kwargs	Any	Keyword arguments, specifically supporting 'key_t' for key transformation logic.

---

Methods

---

add_defaults()

@classmethod
def add_defaults(
    d: Mapping
) - > null

Inserts a new mapping into the chain as a default source. This mapping is placed immediately after the primary changes mapping, making it a secondary source for lookups.

Parameters

Name	Type	Description
d	Mapping	The mapping object to be added to the chain of defaults

Returns

Type	Description
null

---

pop()

@classmethod
def pop(
    key: Any,
    default: Any
) - > Any

Removes and returns a key from the first mapping in the chain. Raises a KeyError if the key is not found in the primary mapping, even if it exists in defaults.

Parameters

Name	Type	Description
key	Any	The key to remove from the primary mapping
default	Any	An optional value to return if the key is not found, preventing a KeyError

Returns

Type	Description
Any	The value associated with the removed key from the first mapping

---

clear()

@classmethod
def clear() - > null

Removes all items from the first mapping in the chain. This clears local changes while leaving default mappings intact.

Returns

Type	Description
null

---

get()

@classmethod
def get(
    key: Any,
    default: Any
) - > Any

Attempts to retrieve a value for a key, returning a default value if the key is not found in any mapping. This provides a safe way to perform lookups without handling KeyErrors.

Parameters

Name	Type	Description
key	Any	The key to search for in the chain
default	Any	The value to return if the key is not found in any mapping

Returns

Type	Description
Any	The value found for the key, or the provided default value if the key is missing

---

setdefault()

@classmethod
def setdefault(
    key: Any,
    default: Any
) - > null

Sets a default value for a key if it does not already exist in any of the mappings. If the key is found, no action is taken.

Parameters

Name	Type	Description
key	Any	The key to check and potentially set
default	Any	The value to assign if the key is missing

Returns

Type	Description
null

---

update()

@classmethod
def update(
    args: Any,
    kwargs: Any
) - > Any

Updates the primary mapping with key-value pairs from the provided arguments and notifies all registered observers. This method triggers side effects by calling all functions in the _observers list.

Parameters

Name	Type	Description
args	Any	Positional arguments containing mapping data to merge
kwargs	Any	Keyword arguments representing key-value pairs to merge

Returns

Type	Description
Any	The result of the update operation on the primary mapping

---

fromkeys()

@classmethod
def fromkeys(
    iterable: Iterable,
    args: Any
) - > [ChainMap](chainmap.md?sid=celery_utils_collections_chainmap)

Create a ChainMap with a single dict created from the iterable.

Parameters

Name	Type	Description
iterable	Iterable	A collection of keys to initialize the dictionary
args	Any	Optional value to assign to all keys in the new dictionary

Returns

Type	Description
[ChainMap](chainmap.md?sid=celery_utils_collections_chainmap)	A new ChainMap instance containing a single dictionary initialized with the provided keys

---

copy()

@classmethod
def copy() - > [ChainMap](chainmap.md?sid=celery_utils_collections_chainmap)

Creates a shallow copy of the ChainMap, including a copy of the primary mapping.

Returns

Type	Description
[ChainMap](chainmap.md?sid=celery_utils_collections_chainmap)	A new ChainMap instance with a copied primary map and shared default maps

---

bind_to()

@classmethod
def bind_to(
    callback: Callable
) - > null

Registers a callback function to be notified whenever the ChainMap is updated. The callback will be executed during the update() method call.

Parameters

Name	Type	Description
callback	Callable	A function to be added to the observers list and called on updates

Returns

Type	Description
null

---