From cae232b65cd4e99788242a7c9b3874bfa0fdf02e Mon Sep 17 00:00:00 2001
From: Enrique Soria <me@enriquesoria.com>
Date: Thu, 4 Jan 2024 22:27:58 +0100
Subject: [PATCH] docs: Improve advanced section

---
 docs/advanced/base-url.md              |  2 ++
 docs/advanced/data-parsers.md          | 25 +++++++++++++++++++++++++
 docs/advanced/exception-handlers.md    | 22 ++++++++++++++++++++++
 docs/advanced/{index.md => logging.md} |  9 +--------
 mkdocs.yml                             |  6 +++++-
 5 files changed, 55 insertions(+), 9 deletions(-)
 create mode 100644 docs/advanced/base-url.md
 create mode 100644 docs/advanced/data-parsers.md
 create mode 100644 docs/advanced/exception-handlers.md
 rename docs/advanced/{index.md => logging.md} (54%)

diff --git a/docs/advanced/base-url.md b/docs/advanced/base-url.md
new file mode 100644
index 0000000..3d6acdc
--- /dev/null
+++ b/docs/advanced/base-url.md
@@ -0,0 +1,2 @@
+### Define a base URL for all your endpoints only once
+...using `BaseUrlSession` from [requests_toolbelt](https://toolbelt.readthedocs.io/) package
diff --git a/docs/advanced/data-parsers.md b/docs/advanced/data-parsers.md
new file mode 100644
index 0000000..ebcbddd
--- /dev/null
+++ b/docs/advanced/data-parsers.md
@@ -0,0 +1,25 @@
+# Create your own data parser
+
+To convert your payloads and responses to your favourite format. A typical use case for this could be to deserialize
+responses as python classes. It may be a good place to convert from snake case and camelCase (and viceversa).
+
+In this library we have a basic example using NamedTuples: `NamedTupleParser`.
+
+```python
+from api_client_framework.protocols import Parser
+from typing import Type, NamedTuple, Any
+
+
+class NamedTupleParser(Parser):
+    def __init__(self, named_tuple_class: Type[NamedTuple]):
+        self.named_tuple_class = named_tuple_class
+
+    def to_dict(self, instance: NamedTuple) -> dict:
+        try:
+            return instance._asdict()
+        except AttributeError:
+            return instance
+
+    def to_class(self, dictionary: dict) -> Any:
+        return self.named_tuple_class(**dictionary)
+```
\ No newline at end of file
diff --git a/docs/advanced/exception-handlers.md b/docs/advanced/exception-handlers.md
new file mode 100644
index 0000000..6e3d745
--- /dev/null
+++ b/docs/advanced/exception-handlers.md
@@ -0,0 +1,22 @@
+### Convert HTTP exceptions in your custom exceptions
+
+Usually it's a good idea to hide implementation details between layers. We can convert `requests` exceptions
+to our custom exceptions by creating an `ExceptionHandler`.
+
+```python
+from api_client_framework.protocols import ExceptionHandler
+
+
+class MyCustomPermissionDenied(Exception):
+    ...
+
+
+class CustomExceptionHandler(ExceptionHandler):
+    def handle_exception(self, exception, response):
+        # Convert this specific error to our custom error
+        if exception.status_code == 400 and response.data["error_code"] == "permission_denied":
+            raise MyCustomPermissionDenied()
+        
+        # Keep other exceptions untouched
+        raise exception
+```
\ No newline at end of file
diff --git a/docs/advanced/index.md b/docs/advanced/logging.md
similarity index 54%
rename from docs/advanced/index.md
rename to docs/advanced/logging.md
index 3e8b5cc..20eb045 100644
--- a/docs/advanced/index.md
+++ b/docs/advanced/logging.md
@@ -1,11 +1,4 @@
-### Create your own data parsers
-...using `Parser` protocol.
 
-### Convert HTTP exceptions in your custom exceptions
-...by creating your own `exception_handler`
-
-### Define a base URL for all your endpoints only once
-...using `BaseUrlSession` from [requests_toolbelt](https://toolbelt.readthedocs.io/) package
 
 ### Log responses
 ...by adding [a hook](https://requests.readthedocs.io/en/latest/user/advanced.html#event-hooks) in your `requests.Session` instance
@@ -19,4 +12,4 @@ def print_response(response, *args, **kwargs):
 session = requests.Session()
 session.hooks.setdefault("response", [])
 session.hooks["response"].append(print_response)
-```
+```
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 0c4ce2e..1cdef4e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -43,4 +43,8 @@ nav:
   - Geting started:
       - 'getting-started/describe-endpoints.md'
       - 'getting-started/create-client.md'
-  - Advanced: 'advanced/index.md'
\ No newline at end of file
+  - Advanced:
+      - 'advanced/data-parsers.md'
+      - 'advanced/exception-handlers.md'
+      - 'advanced/base-url.md'
+      - 'advanced/logging.md'
\ No newline at end of file