A blazing fast dict subclass that enables dot access notation via Python attribute style. Nested dict and list values are automatically transformed as well.

• Documentation: https://dotwiz.readthedocs.io.

Assume you have a simple dict object, with dynamic keys:

>>> my_dict = {'this': {'dict': {'has': [{'nested': {'data': True}}]}}}

If the goal is to access a nested value, you could do it like this:

>>> my_dict['this']['dict']['has'][0]['nested']['data']
True

Or, using DotWiz:

>>> from dotwiz import DotWiz
>>> dw = DotWiz(my_dict)
>>> dw.this.dict.has[0].nested.data
True

Note: This library can also make inaccessible keys safe -- check out an example with DotWizPlus.

$ pip install dotwiz

Here is an example of how to create and use a DotWiz object:

from dotwiz import DotWiz

dw = DotWiz({'this': {'works': {'for': [{'nested': {'values': True}}]}}},
            the_answer_to_life=42)

print(dw)
# >  ✫(this=✫(works=✫(for=[✫(nested=✫(values=True))])),
#      the_answer_to_life=42)

assert dw.this.works['for'][0].nested.values  # True
assert dw.the_answer_to_life == 42

print(dw.to_dict())
# >  {'this': {'works': {'for': [{'nested': {'values': True}}]}},
#     'the_answer_to_life': 42}

Using make_dot_wiz allows you to pass in an iterable object when creating a DotWiz object:

from dotwiz import make_dot_wiz

dw = make_dot_wiz([('hello, world!', 123), ('easy: as~ pie?', True)],
                  AnyKey='value')

print(dw)
#> ✫(AnyKey='value', hello, world!=123, easy: as~ pie?=True)

assert dw['hello, world!'] == 123
assert dw['easy: as~ pie?']
assert dw.AnyKey == 'value'

DotWiz enables you to turn special-cased keys, such as names with spaces, into valid snake_case words in Python, as shown below. Also see the note on Issues with Invalid Characters below.

from dotwiz import DotWizPlus

my_dict = {'THIS': {'1': {'is': [{'For': {'AllOf': {'My !@ Fans!': True}}}]}}}
dw = DotWizPlus(my_dict)

print(dw)
#> ✪(this=✪(_1=✪(is_=[✪(for_=✪(all_of=✪(my_fans=True)))])))

# True
assert dw.this._1.is_[0].for_.all_of.my_fans

# alternatively, you can access it like a dict with the original keys:
assert dw['THIS']['1']['is'][0]['For']['AllOf']['My !@ Fans!']

print(dw.to_dict())
# {'THIS': {'1': {'is': [{'For': {'AllOf': {'My !@ Fans!': True}}}]}}}

print(dw.to_attr_dict())
# {'this': {'_1': {'is_': [{'for_': {'all_of': {'my_fans': True}}}]}}}

A key name in the scope of the DotWizPlus implementation must be:

• a valid, lower- and snake- cased identifier in python.
• not a reserved keyword, such as for or class.
• not override dict method declarations, such as items, get, or values.

In the case where your key name does not conform, the library will mutate your key to a safe, snake-cased format.

Spaces and invalid characters are replaced with _. In the case of a key beginning with an int, a leading _ is added. In the case of a keyword or a dict method name, a trailing _ is added. Keys that appear in different cases, such as myKey or My-Key, will all be converted to a snake case variant, my_key in this example.

Finally, check out this example which brings home all that was discussed above.

• TODO

Check out the Benchmarks section in the docs for more info.

Using a dot-access approach such as DotWiz can be up to 100x faster than with make_dataclass from the dataclasses module.

It's also about 5x faster to create a DotWiz from a dict object as compared to other libraries such as prodict -- or close to 15x faster than creating a Box -- and up to 10x faster in general to access keys by dot notation -- or almost 30x faster than accessing keys from a DotMap.

Contributions are welcome! Open a pull request to fix a bug, or open an issue to discuss a new feature or change.

Check out the Contributing section in the docs for more info.

This package was created with Cookiecutter and the rnag/cookiecutter-pypackage project template.