Release 1.0.0

README.rst

@@ -19,7 +19,7 @@ Dot Wiz
         :alt: Updates
 
 
-A `blazing fast`_ ``dict`` subclass that enables *dot access* notation via Python
+A `blazing fast`_ ``dict`` wrapper that enables *dot access* notation via Python
 attribute style. Nested ``dict`` and ``list`` values are automatically
 transformed as well.
 
@@ -97,6 +97,9 @@ creating a ``DotWiz`` object:
     assert dw['easy: as~ pie?']
     assert dw.AnyKey == 'value'
 
+    print(dw.to_json())
+    #> {"AnyKey": "value", "hello, world!": 123, "easy: as~ pie?": true}
+
 ``DotWizPlus``
 ~~~~~~~~~~~~~~
 
@@ -112,7 +115,7 @@ on `Issues with Invalid Characters`_ below.
     dw = DotWizPlus(my_dict)
 
     print(dw)
-    #> ✪(this=✪(_1=✪(is_=[✪(for_=✪(all_of=✪(my_fans=True)))])))
+    # >  ✪(this=✪(_1=✪(is_=[✪(for_=✪(all_of=✪(my_fans=True)))])))
 
     # True
     assert dw.this._1.is_[0].for_.all_of.my_fans
@@ -121,10 +124,13 @@ on `Issues with Invalid Characters`_ below.
     assert dw['THIS']['1']['is'][0]['For']['AllOf']['My !@ Fans!']
 
     print(dw.to_dict())
-    # {'THIS': {'1': {'is': [{'For': {'AllOf': {'My !@ Fans!': True}}}]}}}
+    # >  {'THIS': {'1': {'is': [{'For': {'AllOf': {'My !@ Fans!': True}}}]}}}
 
     print(dw.to_attr_dict())
-    # {'this': {'_1': {'is_': [{'for_': {'all_of': {'my_fans': True}}}]}}}
+    # >  {'this': {'_1': {'is_': [{'for_': {'all_of': {'my_fans': True}}}]}}
+
+    print(dw.to_json(snake=True))
+    # >  {"this": {"1": {"is": [{"for": {"all_of": {"my_fans": true}}}]}}}
 
 Issues with Invalid Characters
 ******************************
@@ -166,6 +172,16 @@ 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`_.
 
+Type Hints and Auto Completion
+------------------------------
+
+For better code quality and to keep IDEs happy, it is possible to achieve auto-completion of key or attribute names,
+as well as provide type hinting and auto-suggestion of ``str`` methods for example.
+
+Check out the `Usage`_ section in the docs for more details.
+
+.. _Usage: https://dotwiz.readthedocs.io/en/latest/usage.html#type-hints-and-auto-completion
+
 Contributing
 ------------
 

benchmarks/conftest.py

@@ -0,0 +1,41 @@
+from types import SimpleNamespace
+
+import pytest
+
+
+@pytest.fixture
+def parse_to_ns():
+    """
+    Return a helper function to parse a (nested) `dict` object
+    and return a `SimpleNamespace` object.
+    """
+
+    def parse(d):
+        ns = SimpleNamespace()
+
+        for k, v in d.items():
+            setattr(ns, k,
+                    parse(v) if isinstance(v, dict)
+                    else [parse(e) for e in v] if isinstance(v, list)
+                    else v)
+
+        return ns
+
+    return parse
+
+
+@pytest.fixture
+def ns_to_dict():
+    """
+    Return a helper function to convert a `SimpleNamespace` object to
+    a `dict`.
+    """
+
+    def to_dict(ns):
+        """Recursively converts a `SimpleNamespace` object to a `dict`."""
+        return {k: to_dict(v) if isinstance(v, SimpleNamespace)
+                else [to_dict(e) for e in v] if isinstance(v, list)
+                else v
+                for k, v in vars(ns).items()}
+
+    return to_dict

benchmarks/test_create.py

@@ -1,6 +1,7 @@
 import dataclasses
 
 import addict
+import attrdict
 import box
 import dict2dot
 import dotmap
@@ -18,6 +19,7 @@
 
 
 # Mark all benchmarks in this module, and assign them to the specified group.
+#   use with: `pytest benchmarks -m create`
 pytestmark = [pytest.mark.create,
               pytest.mark.benchmark(group='create')]
 
@@ -77,6 +79,28 @@ def test_dotwiz(benchmark, my_data):
     assert result.c.bb[0].x == 77
 
 
+def test_dotwiz_without_check_lists(benchmark, my_data):
+    result = benchmark(dotwiz.DotWiz, my_data, _check_lists=False)
+    # print(result)
+
+    # now similar to `dict2dot`, `dict`s nested within `lists` won't work
+    # assert result.c.bb[0].x == 77
+
+    # instead, dict access should work fine:
+    assert result.c.bb[0]['x'] == 77
+
+
+def test_dotwiz_without_check_types(benchmark, my_data):
+    result = benchmark(dotwiz.DotWiz, my_data, _check_types=False)
+    # print(result)
+
+    # now, `dict`s and `lists` nested within the input `dict` won't work
+    # assert result.c.bb[0].x == 77
+
+    # instead, dict access should work fine:
+    assert result.c['bb'][0]['x'] == 77
+
+
 def test_make_dot_wiz(benchmark, my_data):
     result = benchmark(dotwiz.make_dot_wiz, my_data)
     # print(result)
@@ -91,6 +115,17 @@ def test_dotwiz_plus(benchmark, my_data):
     assert result.c.bb[0].x == 77
 
 
+def test_dotwiz_plus_without_check_lists(benchmark, my_data):
+    result = benchmark(dotwiz.DotWizPlus, my_data, _check_lists=False)
+    # print(result)
+
+    # now similar to `dict2dot`, `dict`s nested within `lists` won't work
+    # assert result.c.bb[0].x == 77
+
+    # instead, dict access should work fine:
+    assert result.c.bb[0]['x'] == 77
+
+
 def test_make_dot_wiz_plus(benchmark, my_data):
     result = benchmark(dotwiz.make_dot_wiz_plus, my_data)
     # print(result)
@@ -152,6 +187,13 @@ def test_addict(benchmark, my_data):
     assert result.c.bb[0].x == 77
 
 
+def test_attrdict(benchmark, my_data):
+    result = benchmark(attrdict.AttrDict, my_data)
+    # print(result)
+
+    assert result.c.bb[0].x == 77
+
+
 def test_metadict(benchmark, my_data):
     result = benchmark(metadict.MetaDict, my_data)
     # print(result)
@@ -183,3 +225,10 @@ def test_scalpl(benchmark, my_data):
     # print(result)
 
     assert result['c.bb[0].x'] == 77
+
+
+def test_simple_namespace(benchmark, my_data, parse_to_ns):
+    result = benchmark(parse_to_ns, my_data)
+    # print(result)
+
+    assert result.c.bb[0].x == 77

benchmarks/test_create_special_keys.py

@@ -1,6 +1,7 @@
 import dataclasses
 
 import addict
+import attrdict
 import box
 import dict2dot
 import dotmap
@@ -19,7 +20,11 @@
 
 
 # Mark all benchmarks in this module, and assign them to the specified group.
+#   use with: `pytest benchmarks -m create_with_special_keys`
+#   use with: `pytest benchmarks -m create_sp`
 pytestmark = [pytest.mark.create_with_special_keys,
+              # alias, for easier typing
+              pytest.mark.create_sp,
               pytest.mark.benchmark(group='create_with_special_keys')]
 
 
@@ -78,14 +83,19 @@ def assert_eq2(result):
     assert result['Some  r@ndom#$(*#@ Key##$# here   !!!'] == 'T'
 
 
-def assert_eq3(result):
+def assert_eq3(result, nested_in_dict=True, nested_in_list=True):
     assert result.camel_case == 1
     assert result.snake_case == 2
     assert result.pascal_case == 3
     assert result.spinal_case3 == 4
     assert result.hello_how_s_it_going == 5
     assert result._3d == 6
-    assert result.for_._1nfinity[0].and_.beyond == 8
+    if nested_in_list:
+        assert result.for_._1nfinity[0].and_.beyond == 8
+    elif nested_in_dict:
+        assert result.for_._1nfinity[0]['and']['Beyond!'] == 8
+    else:
+        assert result.for_['1nfinity'][0]['and']['Beyond!'] == 8
     assert result.some_r_ndom_key_here == 'T'
 
 
@@ -124,6 +134,21 @@ def assert_eq6(result: MyClassSpecialCased):
     assert result.some_random_key_here == 'T'
 
 
+def assert_eq7(result, ns_to_dict):
+    """For testing with a `types.SimpleNamespace` object, primarily"""
+    assert result.camelCase == 1
+    assert result.Snake_Case == 2
+    assert result.PascalCase == 3
+
+    result_dict = ns_to_dict(result)
+
+    assert result_dict['spinal-case3'] == 4
+    assert result_dict['Hello, how\'s it going?'] == 5
+    assert result_dict['3D'] == 6
+    assert result_dict['for']['1nfinity'][0]['and']['Beyond!'] == 8
+    assert result_dict['Some  r@ndom#$(*#@ Key##$# here   !!!'] == 'T'
+
+
 @pytest.mark.xfail(reason='some key names are not valid identifiers')
 def test_make_dataclass(benchmark, my_data):
     # noinspection PyPep8Naming
@@ -161,6 +186,20 @@ def test_dotwiz(benchmark, my_data):
     assert_eq2(result)
 
 
+def test_dotwiz_without_check_lists(benchmark, my_data):
+    result = benchmark(dotwiz.DotWiz, my_data, _check_lists=False)
+    # print(result)
+
+    assert_eq2(result)
+
+
+def test_dotwiz_without_check_types(benchmark, my_data):
+    result = benchmark(dotwiz.DotWiz, my_data, _check_types=False)
+    # print(result)
+
+    assert_eq2(result)
+
+
 def test_make_dot_wiz(benchmark, my_data):
     result = benchmark(dotwiz.make_dot_wiz, my_data)
     # print(result)
@@ -175,6 +214,20 @@ def test_dotwiz_plus(benchmark, my_data):
     assert_eq3(result)
 
 
+def test_dotwiz_plus_without_check_lists(benchmark, my_data):
+    result = benchmark(dotwiz.DotWizPlus, my_data, _check_lists=False)
+    # print(result)
+
+    assert_eq3(result, nested_in_list=False)
+
+
+def test_dotwiz_plus_without_check_types(benchmark, my_data):
+    result = benchmark(dotwiz.DotWizPlus, my_data, _check_types=False)
+    # print(result)
+
+    assert_eq3(result, nested_in_list=False, nested_in_dict=False)
+
+
 def test_make_dot_wiz_plus(benchmark, my_data):
     result = benchmark(dotwiz.make_dot_wiz_plus, my_data)
     # print(result)
@@ -234,6 +287,13 @@ def test_addict(benchmark, my_data):
     assert_eq2(result)
 
 
+def test_attrdict(benchmark, my_data):
+    result = benchmark(attrdict.AttrDict, my_data)
+    # print(result)
+
+    assert_eq2(result)
+
+
 def test_metadict(benchmark, my_data):
     result = benchmark(metadict.MetaDict, my_data)
     # print(result)
@@ -259,3 +319,10 @@ def test_scalpl(benchmark, my_data):
     # print(result)
 
     assert_eq5(result, subscript_list=True)
+
+
+def test_simple_namespace(benchmark, my_data, parse_to_ns, ns_to_dict):
+    result = benchmark(parse_to_ns, my_data)
+    # print(result)
+
+    assert_eq7(result, ns_to_dict)

benchmarks/test_getattr.py

@@ -1,6 +1,7 @@
 import dataclasses
 
 import addict
+import attrdict
 import box
 import dict2dot
 import dotmap
@@ -19,6 +20,7 @@
 
 
 # Mark all benchmarks in this module, and assign them to the specified group.
+#   use with: `pytest benchmarks -m getattr`
 pytestmark = [pytest.mark.getattr,
               pytest.mark.benchmark(group='getattr')]
 
@@ -72,6 +74,14 @@ def test_dotwiz(benchmark, my_data):
     assert result == 77
 
 
+def test_dotwiz_getitem(benchmark, my_data):
+    o = dotwiz.DotWiz(my_data)
+    # print(o)
+
+    result = benchmark(lambda: o['c']['bb'][0]['x'])
+    assert result == 77
+
+
 def test_dotwiz_plus(benchmark, my_data):
     o = dotwiz.DotWizPlus(my_data)
     # print(o)
@@ -141,6 +151,14 @@ def test_addict(benchmark, my_data):
     assert result == 77
 
 
+def test_attrdict(benchmark, my_data):
+    o = attrdict.AttrDict(my_data)
+    # print(o)
+
+    result = benchmark(lambda: o.c.bb[0].x)
+    assert result == 77
+
+
 def test_glom(benchmark, my_data):
     o = my_data
     # print(o)
@@ -179,3 +197,11 @@ def test_scalpl(benchmark, my_data):
 
     result = benchmark(lambda: o['c.bb[0].x'])
     assert result == 77
+
+
+def test_simple_namespace(benchmark, my_data, parse_to_ns):
+    o = parse_to_ns(my_data)
+    # print(o)
+
+    result = benchmark(lambda: o.c.bb[0].x)
+    assert result == 77