mo-dots: Dot-Access to Python Dictionaries

Common errors

• TypeError: Object of type Data is not JSON serializable

  cause `json.dumps()` was called directly on a `mo_dots.Data` object without a custom default serializer.
  fix Import `from_data` and pass it to the `default` argument of `json.dumps()`: `json.dumps(my_data, default=from_data)`.

• KeyError: 'some_missing_key'

  cause Attempting to access a non-existent key on a `mo_dots.Data` object using standard dictionary bracket notation, but `mo-dots` usually returns `Null` for missing keys accessed via dot notation or path strings, and handles some bracket accesses differently.
  fix For `Data` objects, non-existent keys accessed via dot notation (e.g., `data.some_missing_key`) or path strings (e.g., `data['a.b.c']`) will return `Null`. If you are explicitly trying to catch `KeyError`, ensure you are using standard dicts or adapt to `mo-dots`'s null-safe behavior. If you are getting this with `data[key]`, check if `key` actually exists or use `data.get(key)`.

• AttributeError: 'Null' object has no attribute 'some_method'

  cause A chained dot access or an operation was attempted on a `Null` value, which was returned by `mo-dots` for a non-existent path.
  fix Always check if a path exists or returns `Null` before performing further operations on it. For example, `if data.path and data.path.attribute: ...` or `value = data.get('path.attribute', None); if value is not None: ...`

Warnings

• gotcha The standard Python `json` library does not natively recognize `mo_dots.Data` objects for serialization, leading to `TypeError`.
  Fix: When serializing `Data` objects to JSON, use `json.dumps(data_object, default=from_data)` to convert `Data` structures into Python primitives.
• gotcha Accessing a non-existent key or attribute on a `Data` object using dot notation (`data.non_existent`) or bracket notation (`data['non.existent']`) will return `Null` instead of raising a `KeyError` or `AttributeError`.
  Fix: Always check for `Null` when accessing potentially non-existent paths, or use `data.get('path', default_value)` for explicit default handling if `Null` is not desired. Be aware that subsequent operations on a `Null` value will raise `AttributeError`.
• gotcha The `+=` operator on a non-existent path (`data.new_path += value`) has special behavior: for numerical types, `new_path` is initialized to `0` before adding `value`; for list types, `new_path` is initialized to `[]` before appending `value`.
  Fix: Understand this automatic initialization. If you require different default behavior for new paths or explicit control over type initialization, initialize the path yourself (e.g., `data.new_path = 0` or `data.new_path = []`) before using `+=`.

Install

• pip install mo-dots Install latest version

Imports

• Data
  wrong:

  import mo_dots.Data

  correct:

  from mo_dots import Data

  The primary class for dot-accessible data is 'Data' and it's intended for direct import.
• to_data

  from mo_dots import to_data

  Used to convert existing dicts to Data objects.
• from_data

  from mo_dots import from_data

  Essential for serializing Data objects to standard JSON.

Quickstart

This quickstart demonstrates how to create `Data` objects, access nested properties using dot notation and path strings, perform path assignments, and handle the specialized path accumulation with `+=`. It also highlights the crucial step for JSON serialization using `from_data`.

import json
from mo_dots import Data, to_data, from_data

# Create a Data object directly
d = Data(a=1, b={'c': 2, 'd': [3, 4]})
print(f"Initial Data object: {d}")

# Access with dot notation (null-safe)
print(f"d.a: {d.a}")
print(f"d.b.c: {d.b.c}")
print(f"d.b.e: {d.b.e} (returns Null, not KeyError)")

# Path assignment
d['x.y.z'] = 99
print(f"After path assignment: {d}")

# Path accumulation with +=
d.stats.count += 1 # Initializes to 0 then adds 1
d.stats.items += ['apple'] # Initializes to [] then appends
d.stats.items += ['banana']
print(f"After path accumulation: {d}")

# Convert an existing dictionary
my_dict = {'user': {'name': 'Alice', 'id': 123}}
data_from_dict = to_data(my_dict)
print(f"Data from dict: {data_from_dict.user.name}")

# Serialize to JSON (requires from_data)
try:
    json.dumps(d) # This will raise TypeError without default=from_data
except TypeError as e:
    print(f"Caught expected TypeError during direct JSON serialization: {e}")

json_output = json.dumps(d, default=from_data)
print(f"JSON output: {json_output}")
assert json.loads(json_output) == {'a': 1, 'b': {'c': 2, 'd': [3, 4]}, 'x': {'y': {'z': 99}}, 'stats': {'count': 1, 'items': ['apple', 'banana']}}