Merge pull request #27 from qlient-org/develop

Release 0.2.0-beta

Author: dfseifert

docs/examples/combination_of_fields_and_field.py

@@ -0,0 +1,26 @@
+from qlient import Fields, Field, Directive
+
+my_home_world_selection = Fields(
+    "id",
+    "name",
+    "population"
+)
+
+my_person_selection = Fields(
+    "id",  # will be converted to Field("id")
+    Field("name"),
+    Field("height", _alias="my_height"),
+    Field("homeworld", _sub_fields=my_home_world_selection, _directive=Directive("include", **{"if": True}))
+)
+
+# Every variable name used in a Field or Directive is automatically generated and therefore unique.
+# {
+#     id
+#     name
+#     my_height: height
+#     homeworld @include(if: $include_123456789_if) {
+#         id
+#         name
+#         population
+#     }
+# }

docs/examples/fields_addition_operator.py

@@ -0,0 +1,8 @@
+from qlient import Fields, Field
+
+name_fields = Fields("first_name", "last_name")
+age_field = Field("age")
+
+person_fields = name_fields + age_field
+
+# { first_name last_name age }

docs/examples/sending_custom_queries.py

@@ -0,0 +1,22 @@
+from qlient import Client
+
+my_client = Client("https://...")
+
+my_query = """
+query {
+    user1: user(id: "1234") {
+        ...userInformation
+    }
+    user2: user(id: "5678") {
+        ...userInformation
+    }
+}
+
+fragment userInformation on user {
+    username
+    firstname
+    lastname
+}
+"""
+
+response = my_client.query(query=my_query)

docs/examples/simple_proxy_example.py

@@ -2,9 +2,9 @@
 
 client = Client("https://my-graphql-api.com/")
 
-# query is a QueryService object (Inherits from OperationProxy). It will check if there
+# query is a QueryServiceProxy object (Inherits from OperationServiceProxy). It will check if there
 # is an operation with the name `X` defined in the binding
-# and if that is the case it will return a callable Operation object
+# and if that is the case it will return a callable OperationProxy object
 client.query.X()
 
 # The operation can also be called via an __getitem__ call.

docs/examples/usage_client_simple.py

@@ -20,17 +20,29 @@ class Book:
     author: str
 
 
-def get_books():
-    return [Book(title='The Great Gatsby', author='F. Scott Fitzgerald', )]
+my_books = [
+    Book(title="The Great Gatsby", author="F. Scott Fitzgerald")
+]
 
 
 @strawberry.type
 class Query:
-    books: List[Book] = strawberry.field(resolver=get_books)
+    @strawberry.field
+    def get_books(self) -> List[Book]:
+        return my_books
+
+
+@strawberry.type
+class Mutation:
+    @strawberry.mutation
+    def add_book(self, title: str, author: str) -> Book:
+        book = Book(title=title, author=author)
+        my_books.append(book)
+        return book
 
 
 # this line creates the strawberry schema
-my_book_schema = strawberry.Schema(query=Query)
+my_book_schema = strawberry.Schema(query=Query, mutation=Mutation)
 
 
 # now this is the important part
@@ -67,6 +79,34 @@ def cache_key(self) -> str:
 
 client = Client(StrawberryBackend(my_book_schema))
 
-response: GraphQLResponse = client.query.books(_fields=["title", "author"])
+# note that the operation is now named "getBooks"
+# instead of the actual method "get_books"
+# This is due to the automatic camel case conversation in strawberry
+# https://strawberry.rocks/docs/types/schema-configurations
+response: GraphQLResponse = client.query.getBooks(_fields=["title", "author"])
+
+print(response.data)  # {"getBooks": [{"title": "The Great Gatsby", "author": "F. Scott Fitzgerald"}]}
+
+response: GraphQLResponse = client.mutation.addBook(
+    title="1984",
+    author="George Orwell",
+    _fields=["title", "author"]
+)
 
-print(response.data)  # {'books': [{'title': 'The Great Gatsby', 'author': 'F. Scott Fitzgerald'}]}
+print(response.data)
+# {
+#   "addBook": {
+#       "title": "1984",
+#       "author": "George Orwell"
+#   }
+# }
+
+response: GraphQLResponse = client.query.getBooks(_fields=["title", "author"])
+
+print(response.data)
+# {
+#     "getBooks": [
+#         {"title": "The Great Gatsby", "author": "F. Scott Fitzgerald"},
+#         {"title": "1984", "author": "George Orwell"}
+#     ]
+# }

docs/examples/using_custom_backends.py

@@ -0,0 +1,24 @@
+from qlient import Field, Directive
+
+my_field = Field(
+    # Mandatory, the name of the field
+    "repository",
+
+    # Schema Field specific inputs
+    # say we want the last 5 repositories where the name matches abc
+    last=5,
+    name="*abc*",
+
+    # Qlient Field specific arguments start with a `_`
+    # These arguments are Optional and can be left empty
+    # Optional, the alias of the field
+    _alias="my_repo",
+    # Optional, a field directive
+    _directive=Directive("include", **{"if": True}),
+)
+
+# This results in a field like so:
+
+# {
+#   my_repo: repository(last: $repository_1234_last name: $repository_1234_name) @include(if: $include_5678_if)
+# }

docs/examples/using_field_class.py

@@ -0,0 +1,21 @@
+from qlient import Fields
+
+nested_fields = Fields(
+    "first_name",  # will be converted to Field("first_name")
+    "last_name",  # will be converted to Field("first_name")
+
+    # This will be converted to
+    # Field(
+    #   "hobby",
+    #   _sub_fields=Fields(
+    #       Field("name"),
+    #       Field("club", _sub_fields=Fields(Field("name")))
+    #   )
+    # )
+    hobby=Fields(
+        "name",
+        club="name"
+    )
+)
+
+# last_name first_name hobby { name club { name } }

docs/examples/using_fields_class.py

@@ -42,4 +42,8 @@ Say for the example above, you'd also like to have information about the rocket.
 
 {% include "../examples/script_legend.md" %}
 
-For more details on the `Fields` class, have a look at the [fields documentation](./fields.md)
+For more details on the `Fields` class, have a look at the [fields documentation](./fields.md)
+
+## Sending custom queries
+
+Please have a look at the [proxy documentation](./proxy.md)

docs/usage/client.md

@@ -1,108 +1,40 @@
-# Fields
+# Field and Fields
 
-The `Fields` class is a powerful class for making nested or pre-configured field selections.
+The `Fields` class is a powerful class for making nested or pre-configured field selections. In combination with
+the `Field` class you can create every query you need.
 
-## Nested Fields selection
+## Using the Field Class
 
-```python
-from qlient import Fields
+The Field class supports all major graphql features ranging from name, alias to directives and field inputs.
 
-nested_fields = Fields(
-    "first_name",
-    "last_name",
-    hobby="name"
-)
-
-print(nested_fields)
-```
-
-```text
-last_name first_name hobby { name }
-```
-
-{% include "../examples/script_legend.md" %}
-
-The `hobby` selection can be changed from a single item to a `list`:
-
-```python
-from qlient import Fields
-
-nested_fields = Fields(
-    "first_name",
-    "last_name",
-    hobby=["name", "description"]
-)
-
-print(nested_fields)
-```
-
-```text
-last_name first_name hobby { name description }
+```python 
+{% include "../examples/using_field_class.py" %}
 ```
 
 {% include "../examples/script_legend.md" %}
 
-or even another `Fields` instance for even deeper selection.
-
-```python
-from qlient import Fields
-
-nested_fields = Fields(
-    "first_name",
-    "last_name",
-    hobby=Fields(
-        "name",
-        club="name"
-    )
-)
+## Using the Fields Class
 
-print(nested_fields)
-```
-
-```text
-last_name first_name hobby { name club { name } }
+```python 
+{% include "../examples/using_fields_class.py" %}
 ```
 
 {% include "../examples/script_legend.md" %}
 
 ## Supported Operators
 
-The `Fields` class supports two operators: addition and subtraction.
+Both, the `Field` and `Fields` class currently support the following operators:
 
 ### Addition
 
-```python
-from qlient import Fields
-
-name = Fields("first_name", "last_name")
-age = Fields("age")
-
-added = name + age
-
-print(added)
-```
-
-```text
-first_name last_name age
+```python 
+{% include "../examples/fields_addition_operator.py" %}
 ```
 
 {% include "../examples/script_legend.md" %}
 
-### Subtraction
-
-```python
-from qlient import Fields
-
-full_name = Fields("first_name", "last_name")
-last_name = Fields("last_name")
-
-subtracted = full_name - last_name
-
-print(subtracted)
-```
-
-```text
-first_name
-```
+## Combination of Fields and Field
 
-{% include "../examples/script_legend.md" %}
+```python 
+{% include "../examples/combination_of_fields_and_field.py" %}
+```