Improve README.md

Author: RamonGiovane

README.md

@@ -1,28 +1,34 @@
 ![example workflow](https://github.com/RamonGiovane/py-data-digger/actions/workflows/python-app.yml/badge.svg?branch=main)
 
 # py-data-digger
-Safely navigate through unsafe data: dicts, tuples, lists, strings and objects
 
-Inspired on Ruby's [dig](https://www.rubydoc.info/stdlib/core/Hash:dig).
+Safely navigate through unsafe data structures: dictionaries, tuples, lists, strings, and even custom objects.
 
-```
+Inspired by Ruby’s [`dig`](https://www.rubydoc.info/stdlib/core/Hash:dig).
+
+```bash
 pip install py-data-digger
 ```
 
-## Why?
-### TLDR: 
-Sometimes you don't want to deal with Python exceptions when accessing lists and dicts. If the data you need isn't there, you just want to **move on**...
+---
 
-**No ifs, no try-excepts!**
+## 💡 Why?
+### TL;DR:
+Sometimes, you just don’t want to deal with Python exceptions when accessing nested lists and dictionaries.  
+If the data isn’t there, you just want to **move on** — no `if`s, no `try`-`except`s!
 
 ```python
 from py_data_digger import dig
 
 components: list | None = dig(nasty_dict, "machines", 0, "engine", "components")
 ```
 
-### Detailed explanation
-In some occasions (like when web scrapping) you need to grab some data from a deeply nested structure like this:
+---
+
+### 🧠 A more detailed example
+
+When web scraping or working with APIs, you often deal with deeply nested structures like this:
+
 ```python
 nasty_dict = {
     "machines": [
@@ -42,82 +48,111 @@ nasty_dict = {
 }
 ```
 
-Suppose we want to take the list of components of the engine of a machine (the only present).
+Let’s say we want to extract the list of engine components.
+
+---
+
+### 🚨 The unsafe way:
 
-### 🚨 The unsafe strategy:
 ```python
-components: list = nasty_dict["machines"][0]["engine"]["components"]
+components = nasty_dict["machines"][0]["engine"]["components"]
 ```
 
-This is unsafe because it is highly prone to raise `IndexError`, `KeyError`, `TypeError` if you use the wrong key/index or if the data just isn't there.
+This can raise `KeyError`, `IndexError`, or `TypeError` if any part of the structure is missing or malformed.
+
+---
+
+### 😴 The safe (but verbose) way:
 
-### 😴 The safe (but boring) strategy:
 ```python
-machines: list | None = nasty_dict.get("machines")
-machine: dict | None = next(iter(machines), None) if machines else None
-engine: dict | None = machine.get("engine") if machine is not None else None
-components: list | None: engine.get("components") if engine is not None else None
-  
+machines = nasty_dict.get("machines")
+machine = next(iter(machines), None) if machines else None
+engine = machine.get("engine") if machine else None
+components = engine.get("components") if engine else None
 ```
 
-This is not only tedious but labourious!
-At least, it's safe. We would not raise errors to break our code.
+Safe, yes — but tedious and hard to read.
 
+---
 
-## Introducing `dig`
-With this tool we may quickly and securely navigate through all sorts of nested data.
+## ✅ Enter `dig()`
+
+With `dig()`, you can safely access deeply nested data in a concise and readable way:
 
-Let's consider the `nasty_dict` from the past section and that we also want to access the list of components.
 ```python
 from py_data_digger import dig
 
-components: list | None = dig(nasty_dict, "machines", 0, "engine", "components")
+components = dig(nasty_dict, "machines", 0, "engine", "components")
 ```
 
-That's it! All the access problems are solved. If the data you want isn't there, it returns `None` and you can just **move on**!
+If any part of the path is missing, `dig()` returns `None` — and you move on:
+
 ```python
-components: list | None = dig(nasty_dict, "machines", 0, "engine_2", "components")
+components = dig(nasty_dict, "machines", 0, "engine_2", "components")
 if components is None:
-  return None
+    return None
 ```
 
-## Introducing `seek`
-Not satisfied with `None` returns?
+---
+
+## 🚀 Need strict behavior? Use `seek()`
 
-The `seek` function works just like `dig`, but it will raise an error if the path informed could not be found.
+If you want stricter error handling, use `seek()`. It behaves like `dig()`, but **raises an error** if the path doesn’t exist.
 
 ```python
 from py_data_digger import seek
 
+components = seek(nasty_dict, "machines", 0, "engine_2", "components")
+```
 
-components: list = seek(nasty_dict, "machines", 0, "engine_2", "components")
->>> SeekError: Data digger can't go any further: KeyError
+```text
+SeekError: Data digger can't go any further: KeyError
 Path traveled: dict -> machines -> 0 -> engine_2
 ```
 
-The cool thing is, you would need to handle just one exception (`SeekError`). It also shows where it failed to seek 😎
+No more dealing with multiple exception types — just catch `SeekError`.
+
+---
+
+## 🔍 Accessing object attributes
+
+You can also dig through **custom object attributes**, such as `dataclasses`, Pydantic models, or any plain Python objects.
+
+Use the `dig_objects=True` or `seek_objects=True` flag:
 
-## Seeking/digging objects
-And there is more!
-If you also want to look inside object attributes, you may do it by passing a special flag.
-This way it will be compatible with any nested objects like **Pydantic** models and **dataclasses**!
 ```python
-  person = Person(name='John Doe')
-  my_dict = {
-  'item_with_object': person
-  }
+from py_data_digger import dig, seek
+
+person = Person(name='John Doe')
+my_dict = {
+    'item_with_object': person
+}
+
+dig(my_dict, 'item_with_object', 'name', dig_objects=True)
+# → 'John Doe'
 
-  dig(my_dict, 'item_with_object', 'name', dig_objects=True)
-  >>> 'John Doe'
+dig(my_dict, 'item_with_object', 'age', dig_objects=True)
+# → None
 
-  dig(my_dict, 'item_with_object', 'age', dig_objects=True)
-  >>> None
+seek(my_dict, 'item_with_object', 'name', seek_objects=True)
+# → 'John Doe'
 
-  seek(my_dict, 'item_with_object', 'name', seek_objects=True)
-  >>> 'John Doe'
+seek(my_dict, 'item_with_object', 'age', seek_objects=True)
+# → SeekError
+```
+
+⚠️ Note: Use the object-access flags with caution, as attribute names may conflict with dictionary keys.
+
+---
+
+## 📦 Installation
 
-  seek(my_dict, 'item_with_object', 'age', seek_objects=True)
-  >>> SeekError
+```bash
+pip install py-data-digger
 ```
 
-⚠️ The special flag is required because attribute names may conflict with other mapped keys. Use with caution.
+---
+
+## 🙌 Contributions
+
+Feel free to open issues or pull requests. Feedback is always welcome!