diff --git a/HISTORY.rst b/HISTORY.rst index f5254e3..9228edd 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -2,24 +2,25 @@ History ======= -0.1.9 (2017-05-04) +0.1.9 (2017-05-06) ------------------ Changed -+++++++ +^^^^^^^ * __getitem__ will call __missing__ method if key does not exist Added -+++++ +^^^^^ * __missing__ method which returns None +* full documentation of dotty_dict usage 0.1.8 (2017-05-03) ------------------ Changed -+++++++ +^^^^^^^ * Travis YAML configuration compatible with TOX @@ -27,6 +28,6 @@ Changed ------------------ Added -+++++ +^^^^^ * First release on PyPI. diff --git a/README.rst b/README.rst index 6a373fb..a975494 100644 --- a/README.rst +++ b/README.rst @@ -38,9 +38,12 @@ Features **TODO** -* Escape dot char for dictionary keys with dot: dotty_dict['strange\.key'] -* Check if key exists in deeply nested dictionary: 'deeply.nested' in dotty_dict -* Delete deeply nested keys: del dotty_dict['deeply.nested'] +* Escape dot char for dictionary keys with dot: **dotty_dict['key\.key']** +* Delete deeply nested keys: **del dotty_dict['key.key']** +* Check if key exists in deeply nested dictionary: **key.key.key in dotty_dict** +* Check if key does not exist in deeply nested dictionary: **deeply.nested not in dotty_dict** +* Pop nested key: **pop( key.key.key[, default] )** +* Set default bug fix Credits ------- diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.rst b/docs/index.rst index 54e7b48..b13bfd8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,7 +10,8 @@ Contents: installation usage contributing - authorshistory + authors + history Indices and tables ================== diff --git a/docs/usage.rst b/docs/usage.rst index 7195880..7b2be87 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -2,12 +2,22 @@ Usage ===== -**Dotty** dictionary follows dict interfaces and all rules applied to dictionaries. -`Read more in Python documentation `_ +**Dotty_dict** follows dict interfaces and all rules applied to dictionaries. +Dotty can be created by placing a standard dictionary with comma-separated +list of key: value pairs within Dotty constructor. -**Dotty** can be created by placing a standard dictionary with comma-separated list of key: value pairs -within **Dotty** constructor, for example:: +Overview +-------- + +Import and create dotty_dict on various way using Dotty() class. +| *class* **Dotty(**kwarg)** +| *class* **Dotty(mapping, **kwarg)** +| *class* **Dotty(iterable, **kwarg)** + +.. code:: python + + >>> from dotty_dict import Dotty >>> Dotty() {} >>> Dotty({'foo': 4098, 'bar': 4127}) @@ -21,33 +31,50 @@ within **Dotty** constructor, for example:: >>> Dotty([('foo.bar.baz', 4098), ('foo.bar.fizz', 4127)]) {'foo': {'bar': {'baz': 4098, 'fizz': 4127}}} -Overview --------- -To use **Dotty** in a project:: +Deeply nested keys in action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - >>> from dotty_dict import Dotty +Use dotty_dict as normal dictionary but with special power of dot notation keys. +.. code:: python + + >>> from dotty_dict import Dotty >>> dotty = Dotty({'first': {'second': {'deep': 'i am here!'}}}) >>> dotty['first.second.deeper.better.faster.stronger'] = 'ohh!' >>> dotty {'first': {'second': {'deep': 'i am here!', 'deeper': {'better': {'faster': {'stronger': 'ohh!'}}}}}} -Operations ----------- +.. note:: -**len(d)** + Dotty dictionaries compare equal if and only if they have the same (key, value) pairs. + Order comparisons (‘<’, ‘<=’, ‘>=’, ‘>’) raise TypeError. -Return the number of items in the **Dotty** dictionary *d*. +Methods and operations +---------------------- -**d[** *'key.key.key'* **]** +Dotty dict supports all dictionary method and operations for single, not nested keys. + +.. seealso:: + + Python `mapping-types-dict `_ + generic documentation + and `types.MappingProxyType `_ + which can be used to create a read-only view of a dotty_dict. + +**len(** *dotty* **)** +^^^^^^^^^^^^^^^^^^^^^^ + +Return the number of items in the *dotty* dictionary. + +**dotty[** *key.key.key* **]** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Return the item of d with dot notation key. Returns None if key is not in the map. -:: +.. code:: python >>> from dotty_dict import Dotty - >>> dotty = Dotty({'foo.bar': 'baz'}) >>> dotty['foo.bar'] += ' & fizz' >>> dotty @@ -55,11 +82,12 @@ Return the item of d with dot notation key. Returns None if key is not in the ma >>> dotty['foo.bar'] 'baz & fizz' -**d[** *'key.key.key'* **] = value** +**dotty[** *key* **] = value** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Set deeply nested *key.key.key* to value +Set deeply nested *dotty[key.key.key]* to value. -:: +.. code:: python >>> from dotty_dict import Dotty >>> dotty = Dotty() @@ -67,13 +95,82 @@ Set deeply nested *key.key.key* to value >>> dotty {'foo': {'bar': 'baz'}} -**.get(** *'key.key.key'* **[,** *default* **])** +**del dotty[** *key* **]** +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Remove *dotty[key]* from dotty dict. Raises a +`KeyError `_ if key is not in the map. + +.. warning:: + + Nested keys are not supported yet. + +**k in dotty** +^^^^^^^^^^^^^^ -If deeply nested key is in dictionary return it's value, -but if key doesn't exist or it's value is None then return optional default value, -default defaults to None. +Return *True* if d has a key key, else *False*. -:: +.. warning:: + + Nested keys are not supported yet. + +**key not in dotty** +^^^^^^^^^^^^^^^^^^^^ + +Equivalent to *not key in dotty*. + +.. warning:: + + Nested keys are not supported yet. + +**iter(** *dotty* **)** +^^^^^^^^^^^^^^^^^^^^^^^ + +Return an iterator over the keys of the dictionary. +This is a shortcut for iter(dotty.keys()). + +**clear()** +^^^^^^^^^^^ + +Remove all items from *dotty* dict. + +**copy()** +^^^^^^^^^^ + +Return a shallow copy of the dictionary. + +*classmethod* **fromkeys(** *seq[, value]* **)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Create a new dictionary with keys from seq and values set to value. +`fromkeys() `_ +is a class method that returns a new dictionary. value defaults to None. + +**From keys with default value set to** *None* + +.. code:: python + + >>> from dotty_dict import Dotty + >>> dotty = Dotty.fromkeys(['foo.bar', 'foo.baz', 'foo.fizz']) + >>> dotty + {'foo': {'bar': None, 'baz': None, 'fizz': None}} + +**From keys with default value set to** *"buzz"* + +.. code:: python + + >>> from dotty_dict import Dotty + >>> dotty = Dotty.fromkeys(['foo.bar', 'foo.baz', 'foo.fizz'], 'buzz') + >>> dotty + {'foo': {'bar': 'buzz', 'baz': 'buzz', 'fizz': 'buzz'}} + +**get(** *key.key.key[, default]* **)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Return the value for deeply nested key if key is in the dotty dictionary, else default. +If default is not given, it defaults to None. + +.. code:: python >>> from dotty_dict import Dotty >>> dotty = Dotty() @@ -85,10 +182,91 @@ default defaults to None. >>> value 'foo' -**.clear()** +**items()** +^^^^^^^^^^^ -Removes all items from **Dotty** dict +Return a new view of the dictionary’s items ((*key*, *value*) pairs). -**.copy()** +.. seealso:: -Return a shallow copy of the dictionary. + See the documentation of `view objects `_ + +**keys()** +^^^^^^^^^^ + +Return a new view of the dictionary’s keys. See the documentation of view objects. + +.. seealso:: + + See the documentation of `view objects `_ + +**pop(** *key[, default]* **)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If key is in the dictionary, remove it and return its value, else return default. +If default is not given and key is not in the dictionary, a +`KeyError `_ is raised. + +.. warning:: + + Nested keys are not supported yet. + +**popitem()** +^^^^^^^^^^^^^ + +Remove and return an arbitrary (*key*, *value*) pair from the dictionary. +`popitem() `_ +is useful to destructively iterate over a dictionary, as often used in set algorithms. +If the dictionary is empty, calling `popitem() `_ +raises a `KeyError `_. + +.. code:: python + + >>> from dotty_dict import Dotty + >>> dotty = Dotty({'foo.bar.baz': 'fizz'}) + >>> dotty + {'foo': {'bar': {'baz': 'fizz'}}} + >>> dotty.popitem() + ('foo', {'bar': {'baz': 'fizz'}}) + >>> dotty + {} + +**setdefault(** *key[, default]* **)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If key is in the dictionary, return its value. If not, insert key with a value of +default and return default. default defaults to None. + +.. warning:: + + This method is available and IDE shows it as valid and working method, + but there is known bug which always returns None even when default is set to other value. + +**update(** *[other]* **)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Update the dictionary with the key/value pairs from other, overwriting existing keys. Return *None*. +`update() `_ accepts either +another dictionary object or an iterable of key/value pairs +(as tuples or other iterables of length two). If keyword arguments are specified, +the dictionary is then updated with those key/value pairs: dotty.update(red=1, blue=2). + +.. code:: + + >>> from dotty_dict import Dotty + >>> dotty = Dotty({'foo.bar': 'baz'}) + >>> dotty.update({'foo.fizz': 'buzz'}) + >>> dotty + {'foo': {'bar': 'baz', 'fizz': 'buzz'}} + >>> dotty.update(red=1, blue=2) + >>> dotty + {'blue': 2, 'foo': {'bar': 'baz', 'fizz': 'buzz'}, 'red': 1} + +**values()** +^^^^^^^^^^^^ + +Return a new view of the dictionary’s values. + +.. seealso:: + + See the `documentation of view objects `_.