aadict

=================================
(Yet Another) Auto-Attribute Dict
=================================

An ``aadict`` is a python dict sub-class that allows attribute-style
access to dict items, e.g. ``d.foo`` is equivalent to ``d['foo']``.
``aadict`` also provides a few other helpful methods, such as ``pick``
and ``omit`` methods. Also, an ``aadict`` is more call chaining
friendly (e.g. methods such as `update` return ``self``) and is
pickle'able.


Project
=======

* Homepage: https://github.com/metagriffin/aadict
* Bugs: https://github.com/metagriffin/aadict/issues


TL;DR
=====

Install:

.. code-block:: bash

  $ pip install aadict

Use:

.. code-block:: python

  from aadict import aadict

  # attribute access
  d = aadict(foo='bar', zig=87)
  assert d.foo == d['foo'] == 'bar'

  # helper methods
  assert d.pick('foo') == {'foo': 'bar'}
  assert d.omit('foo') == {'zig': 87}

  # method chaining
  d2 = aadict(x='y').update(d).omit('zig')
  assert d2.x == 'y' and d2.foo == 'bar' and d2.zig is None

  # converting a dict to an aadict recursively
  d3 = aadict.d2ar(dict(foo=dict(bar='zig')))
  assert d3.foo.bar == 'zig'


Details
=======

The aadict module provides the following functionality:


aadict
------

An `aadict` object is basically identical to a `dict` object, with the
exception that attributes, if not reserved for other purposes, map to
the dict's items. For example, if a dict ``d`` has an item ``'foo'``,
then a request for ``d.foo`` will return that item lookup. aadicts
also have several helper methods, for example ``aadict.pick``. To
fetch the value of an item that has the same name as one of the helper
methods you need to reference it by item lookup,
i.e. ``d['pick']``. The helper methods are:

* **aadict.pick** instance method:

  Returns a new aadict, reduced to only include the specified
  keys. Example:

  .. code-block:: python

    d = aadict(foo='bar', zig=87, zag=['a', 'b'])
    assert d.pick('foo', 'zag') == {'foo': 'bar', 'zag': ['a', 'b']}

* **aadict.omit** instance method:

  Identical to the ``aadict.pick`` method, but returns the complement,
  i.e. all of those keys that are *not* specified. Example:

  .. code-block:: python

    d = aadict(foo='bar', zig=87, zag=['a', 'b'])
    assert d.omit('foo', 'zag') == {'zig': 87}

* **aadict.d2ar** class method:

  Recursively converts the supplied `dict` to an `aadict`, including
  all sub-list and sub-dict types. Due to being recursive, but only
  copying dict-types, this is effectively a hybrid of a shallow and
  a deep clone. Example:

  .. code-block:: python

    d = aadict.d2ar(dict(foo=dict(bar='zig')))
    assert d.foo.bar == 'zig'

  Without the recursive walking, the ``.bar`` attribute syntax
  would yield an AttributeError exception because d.foo would
  reference a `dict` type, not an `aadict`.

* **aadict.d2a** class method:

  Converts the supplied `dict` to an `aadict`. Example:

  .. code-block:: python

    d = aadict.d2a(dict(foo='bar'))
    assert d.foo == d['foo'] == 'bar'

  Note that this is identical to just using the constructor,
  but is provided as a symmetry to the ``aadict.d2ar`` class
  method, e.g.:

  .. code-block:: python

    d = aadict(dict(foo='bar'))
    assert d.foo == d['foo'] == 'bar'