dotmap

library1.3.30pypypi✓ verified 25d ago

Dotmap is a Python library that provides a dot-access dictionary, allowing dictionary keys to be accessed as object attributes (e.g., `m.key` instead of `m['key']`). It supports dynamic hierarchy creation, ordered iteration, and can be initialized from or converted back to standard Python dictionaries. The current stable version is 1.3.30, and it maintains an active release cadence with regular updates.

serialization

pip install dotmap

github ↗package ↗

INSTALL

IMPORT

SIG · DOTMAP

dotmap

serializationpythonv1.3.30

Install

1.5s avg

Import

43ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.30 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.046s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.040s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DotMap

✓ from dotmap import DotMap

This example demonstrates how to initialize a DotMap, assign values using dot notation, dynamically create nested dictionaries and lists, and convert the DotMap instance back to a standard Python dictionary.

from dotmap import DotMap # Initialize an empty DotMap m = DotMap() # Assign values using dot notation m.name = 'Joe' # Dynamically create nested structures m.people.john.age = 32 m.people.john.job = 'coder' # Append to lists (dynamically created) m.list.append(1) m.list.append(2) m.list.append(3) # Access values print(f"Name: {m.name}") print(f"John's Age: {m.people.john.age}") print(f"List: {m.list}") # Convert back to a standard dictionary regular_dict = m.toDict() print(f"Converted to dict: {regular_dict}")

Debug

Known issues

gotchaAccessing a non-existent key in a DotMap (e.g., `m.non_existent_key`) will dynamically create an empty DotMap for that key, rather than raising a KeyError or returning None. This is a core feature for dynamic expansion but can be unexpected if you intend to check for key existence without modification.

fix

To check for key existence without creating a new DotMap, use `key in dotmap_instance` or `dotmap_instance.get('key_name', default_value)` methods, similar to a regular dictionary.

affects: All versions

gotchaWhen converting a DotMap initialized from a nested dictionary back to a regular dictionary using `toDict()`, some internal DotMap instances might persist as values, or unexpected 'size'/'shape' keys might be added if they were implicitly created or managed by DotMap's internal mechanisms, leading to inconsistencies.

fix

Ensure you explicitly remove any unwanted keys after `toDict()` if they interfere with downstream processes. Always inspect the output of `toDict()` to confirm it matches expectations. For deeply nested structures, consider a custom deep-copy or serialization approach if `toDict()` causes issues.

affects: Versions prior to 1.3.x (and potentially some newer versions based on GitHub issues)

gotchaDictionary keys that conflict with Python's reserved keywords or built-in object attributes (e.g., 'items', 'keys', 'values', 'clear', 'copy', or leading with special characters) can lead to unexpected behavior or errors when accessed via dot notation. For instance, `m.items` would access the DotMap's `items()` method, not a key named 'items'.

fix

Avoid using Python keywords or built-in dictionary method names as keys if you plan to access them via dot notation. If such keys are unavoidable, access them using standard dictionary bracket notation: `m['key_name']`.

affects: All versions

gotchaWhen subclassing `DotMap`, initializing `super().__init__(...)` with nested dictionaries might not always behave as expected, sometimes failing to properly convert nested dictionaries into DotMap instances within the subclass.

fix

If subclassing, be cautious with `super().__init__()` and nested dicts. You might need to manually convert nested dictionaries to `DotMap` instances within your subclass's `__init__` or rely on `DotMap`'s dynamic creation for subsequent assignments rather than initial bulk population.

affects: All versions, specifically noted in issue #77

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'dotmap'

The 'dotmap' package has not been installed in the current Python environment.

fix

pip install dotmap

RecursionError: maximum recursion depth exceeded while calling a Python object

This typically occurs when converting a DotMap to a dictionary that contains self-referential or deeply nested structures, especially with older dotmap versions.

fix

Upgrade dotmap to the latest version using `pip install --upgrade dotmap`. If the data structure is truly recursive, you may need to manually manage the conversion or redesign the data to avoid infinite recursion.

ImportError: cannot import name 'MutableMapping' from 'collections'

This error occurs in Python 3.10 and newer versions because `MutableMapping` (and other abstract base classes) were moved from the `collections` module to `collections.abc` in these Python versions. An older version of dotmap is being used that is not compatible.

fix

Upgrade the dotmap library to a compatible version (1.3.9 or newer) using `pip install --upgrade dotmap`.

AttributeError: 'DotMap' object has no attribute 'some_key'

Attempting to access a key using dot notation (e.g., `m.some_key`) when that key does not exist in the DotMap and dynamic creation is either explicitly disabled (`_dynamic=False`) or the access occurs in a context (like an IDE debugger) that probes for existing attributes rather than triggering dynamic creation.

fix

Ensure the key exists before accessing it (e.g., `if 'some_key' in m:`) or initialize the DotMap without `_dynamic=False` if you intend for non-existent keys to be dynamically created. If it's a debugger-related 'shape' error, it's often benign, or you can disable dynamic creation if unwanted: `m = DotMap(_dynamic=False)`.

Upgrade

Version history

1.3.30latest on PyPI · released Apr 6, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/drgrib/dotmap ↗

packagehttps://pypi.org/project/dotmap/ ↗