documentation

docs/API-Documentation/exceptions.md

@@ -0,0 +1,49 @@
+# exceptions
+exceptions are only raised in `scalar` requests, when we convert graphql
+response to python objects it make sense to convert graphql errors to python exceptions.
+
+graphql errors are always the same, if it returned an error you have a problem
+with your query.
+
+## ql.QLErrorResponseException
+an exception class that is raised when scalar function
+gets error response from graphql
+```py
+QLErrorResponseException(errors: list[QueryErrorDict])
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `errors` | `list[QueryErrorDict]` | list of graphql errors |
+
+```py title="example.py"
+import ql
+
+try:
+  _ = ql.scalar_query_response({
+    "errors": [
+      {"message": "example for error", "locations": {"line": 0, "column": 0}},
+      {"message": "I have another error in my query!", "locations": {"line": 0, "column": 0}},
+    ],
+    "data": None
+  })
+except ql.QLErrorResponseException:
+  print("damn... my graphql query failed...")
+```
+
+### error_details `property`
+returns a list of `QLErrorDetails`.
+
+
+## ql.QLErrorDetails
+class used to map each error detail to python object
+```py
+QLErrorDetails(message: str, locations: list[QueryErrorLocationDict])
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `message` | `str` | the message field from the graphql error
+| `locations` | `list[QueryErrorLocationDict]` | list of locations where the error occurse
+
+

docs/API-Documentation/http.md

@@ -0,0 +1,43 @@
+# http
+this library does not implement http communication with graphql server since API can be
+different from implementation to implementation. the library http client accept a `request` function
+that takes a graphql query string, and returns the json response parsed as dict, this allows 
+the flexability to implement error handlers in the passed request function instead
+of wrapping each `query` request with `try...except`.
+
+
+##  ql.http.set_request_func
+set request function for the `ql` client
+```py
+def set_request_func(request_func: GraphqlRequestFunc) -> None:
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `request_func` | `GraphqlRequestFunc` | callable function that accepts a string and returns dict |
+
+```py title="example.py"
+import ql
+import requests
+
+def request_graphql(query: str) -> dict:
+  response = requests.post("...", json={"query": query})
+  response.raise_for_status()  # can handle errors here in one place
+  return response.json()
+
+ql.http.set_request_func(request_graphql)
+```
+
+---
+
+## ql.http.request
+send request query with given request function
+```py
+def request(self, query: str) -> QueryResponseDict:
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `query` | `str` | the query request that will be passed to the function |
+
+

docs/API-Documentation/index.md

@@ -0,0 +1,4 @@
+# API
+the `ql` api is small and simple, you don't need to import anything 
+from inside the module, just import the module and use the exported functionality
+

docs/API-documentation/query.md → docs/API-Documentation/query.md

@@ -1,4 +1,4 @@
-# Query
+# query
 reading data from apis is the most common operation we do, that's why `ql` makes it 
 easy to query data from your graphql endpoint and provide variety of query methods.
 
@@ -15,7 +15,7 @@ def query(
 
 | Name | Type | Description |
 |------|------|-------------|
-| `query_models` |  `*_QueryModelType`          | python ql structured query |
+| `query_models` | `*_QueryModelType` | python ql structured query |
 | `fragments` | `Optional[_QueryFragmentType]` | dict mapping between `ql.fragment` to the python ql structured query |
 | `include_typename` | `bool` | if include `__typename` field when querying sub types |
 

docs/examples/index.md

@@ -1,4 +1,4 @@
-# examples
+# EXAMPLES
 it is easier to brief though the examples and see what this
 library can provide and most importantly, how it provides the functionalities.
 

docs/examples/query.md

@@ -1,5 +1,4 @@
 # Query
-querying should be expected and simple
 
 ## raw query
 ```py

docs/index.md

@@ -1,2 +1,45 @@
-# ql
-light and fast graphql library wrapped around pydantic
+---
+title: "Welcome"
+---
+# Home
+welcome to `ql`! a simple, light, fast and easy way to implement graphql client
+in python with the help of [`pydantic`](https://docs.pydantic.dev/latest/).
+
+the library is not intrusive, which means you won't find unexpected attributes
+and functions attached to you pydantic model, and doesn't change the model behaviour.
+
+!!! note
+    the library does attach methods and properties to your model, but they always in the format of
+    `__ql_<..>__`, so it is not expected you will ever call them accidentally.
+
+
+```py title="simple like it should be"
+import ql
+from pydantic import BaseModel
+
+@ql.model
+class Person(BaseModel):
+  first_name: str
+  last_name: str
+  age: int
+
+response = ql.raw_query_response_scalar("""
+query {
+  Person(first_name: "foo") {
+    first_name
+    last_name
+    age
+    __typename  # required for scalar
+  }
+}
+""")
+# {"person": Person(first_name="foo", last_name="oof", age=99)}
+```
+
+---
+
+# install
+just `pip` install the package and start using it
+```console
+pip3 install pydantic-graphql
+```

mkdocs.yml

@@ -21,6 +21,7 @@ theme:
     - media: "(prefers-color-scheme: light)"
       scheme: default 
       primary: pink
+      accent: pink
       accent: teal
       toggle:
         icon: material/brightness-7
@@ -29,7 +30,8 @@ theme:
     # Palette toggle for dark mode
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
-      primary: black
+      primary: pink
+      accent: teal
       toggle:
         icon: material/brightness-4
         name: Switch to system preference