docs: add docs for new features

README.md

@@ -11,19 +11,6 @@
 
 `dotty-dictionary` is a fork of [pawelzny/dotty_dict](https://github.com/pawelzny/dotty_dict) that provides additional features and improvements.
 
-## Features
-
-- Simple wrapper around python dictionary and dict like objects
-- Two wrappers with the same dict are considered equal
-- Access to deeply nested keys with dot notation: dot['deeply.nested.key']
-- Create, read, update and delete nested keys of any length
-- Expose all dictionary methods like .get, .pop, .keys and other
-- Access dicts in lists by index dot['parents.0.first_name']
-- Support for setting value in multidimensional lists
-- Support for accessing lists with slices
-- Support for flattening nested dictionary keys from a dotty dictionary and vice versa
-- Support for iteration over nested dictionary keys (e.g. `for key in dotty_dict_instance`)
-
 ## Installation
 
 ```bash
@@ -33,44 +20,82 @@ pip install dotty-dictionary
 - Package: <https://pypi.org/project/dotty-dictionary>
 - Source: <https://github.com/01Joseph-Hwang10/dotty-dictionary>
 
-## Quick Example
+## Features
 
-Create new dotty using factory function.
+### Provides dot notation acccess to dictionary objects
+
+It provides a simple wrapper around python dictionary and dict like `Mapping` objects. 
+You can access deeply nested keys with dot notation.
 
 ```py
 from dotty_dictionary import dotty
-dot = dotty({'plain': {'old': {'python': 'dictionary'}}})
-dot['plain.old']
-{'python': 'dictionary'}
+dot = dotty({"deeply": {"nested": {"key": "value"}}})
+dot['deeply.nested.key']
+'value'
 ```
 
-You can start with empty dotty
+### Exposes all dictionary methods (`.get`, `.pop`, `.keys`, ...)
+
+You can use all dictionary methods like `.get`, `.pop`, `.keys` and other.
 
 ```py
 from dotty_dictionary import dotty
-dot = dotty() # Alias: `Dotty.empty()`
-dot['very.deeply.nested.thing'] = 'spam'
-dot
-Dotty(dictionary={'very': {'deeply': {'nested': {'thing': 'spam'}}}}, separator='.', esc_char='\\')
+dot = dotty({"deeply": {"nested": {"key": "value"}}})
 
-dot['very.deeply.spam'] = 'indeed'
-dot
-Dotty(dictionary={'very': {'deeply': {'nested': {'thing': 'spam'}, 'spam': 'indeed'}}}, separator='.', esc_char='\\')
+# View methods
+list(dot.keys()) # ["deeply"]
+list(dot.values()) # [{"nested": {"key": "value"}}]
+list(dot.items()) #[("deeply", {"nested": {"key": "value"}})]
 
-del dot['very.deeply.nested']
+# `.update`
+dot.update({"other": "value"})
 dot
-Dotty(dictionary={'very': {'deeply': {'spam': 'indeed'}}}, separator='.', esc_char='\\')
+Dot(dictionary={'deeply': {'nested': {'key': 'value'}}, 'other': 'value'}, separator='.', esc_char='\\')
 
-dot.get('very.not_existing.key')
-None
+# `.pop`: Pops nested keys
+dot.pop("deeply.nested.key")
+"value"
+
+# `.copy`
+dot is not dot.copy()
+True
 ```
 
-More examples can be found in the [examples](https://github.com/01Joseph-Hwang10/dotty-dictionary/tree/master/examples) directory.
+### Dot notation access support for list objects
+
+You can access dicts in lists by index like: `dot['parents.0.first_name']`.
+It also supports multidimensional lists.
+
+```py
+from dotty_dictionary import dotty
+dot = dotty({"parents": [{"first_name": "John"}, {"first_name": "Jane"}]})
+dot['parents.0.first_name']
+'John'
+
+dot = dotty({"matrix": [[1, 2, 3], [4, 5, 6], [7, 8, 9]]})
+dot['matrix.1.1']
+5
+```
 
 > [!NOTE]\
 > Using integer in dictionary keys will be treated as embedded list index.
 
-## Flattening and Unflattening
+
+### Support for accessing lists with slices
+
+You can access lists with slices like: `dot['parents.0:2']`.
+
+```py
+from dotty_dictionary import dotty
+dot = dotty({"parents": [{"first_name": "John"}, {"first_name": "Jane"}, {"first_name": "Doe"}]})
+dot['parents.0:2']
+[{"first_name": "John"}, {"first_name": "Jane"}]
+
+dot['parents.:']
+[{"first_name": "John"}, {"first_name": "Jane"}, {"first_name": "Doe"}]
+```
+
+### Flattening and Unflattening
 
 You can utilize `to_flat_dict` and `from_flat_dict` to convert dotty to and from flat dictionary.
 
@@ -84,7 +109,7 @@ dot.to_flat_dict()
 {'very.deeply.nested.thing': 'spam', 'very.deeply.spam': 'indeed'}
 ```
 
-## Custom Types && Encoders
+### Custom Types && Encoders
 
 By default, `dotty-dictionary` only considers `dict` as a mapping type, and `list` as a sequence type and will provide a dot notation access for them. However, you can also provide custom types to be considered as mapping or sequence types.
 
@@ -133,6 +158,39 @@ dot["h.age"]
 
 Full example can be found on [tests/test_dotty_custom_types.py](https://github.com/01Joseph-Hwang10/dotty-dictionary/tree/master/tests/test_dotty_custom_types.py)
 
+## Quick Examples
+
+Create new dotty using factory function.
+
+```py
+from dotty_dictionary import dotty
+dot = dotty({'plain': {'old': {'python': 'dictionary'}}})
+dot['plain.old']
+{'python': 'dictionary'}
+```
+
+You can start with empty dotty
+
+```py
+from dotty_dictionary import dotty
+dot = dotty()
+dot['very.deeply.nested.thing'] = 'spam'
+dot
+Dotty(dictionary={'very': {'deeply': {'nested': {'thing': 'spam'}}}}, separator='.', esc_char='\\')
+
+dot['very.deeply.spam'] = 'indeed'
+dot
+Dotty(dictionary={'very': {'deeply': {'nested': {'thing': 'spam'}, 'spam': 'indeed'}}}, separator='.', esc_char='\\')
+
+del dot['very.deeply.nested']
+dot
+Dotty(dictionary={'very': {'deeply': {'spam': 'indeed'}}}, separator='.', esc_char='\\')
+
+dot.get('very.not_existing.key')
+None
+```
+
+More examples can be found in the [examples](https://github.com/01Joseph-Hwang10/dotty-dictionary/tree/master/examples) directory.
 
 ## Contributing