From 9df3c3d53f55d54c36c78648c3b3945435f46fc8 Mon Sep 17 00:00:00 2001
From: Damian Czajkowski <d0.czajkowski@gmail.com>
Date: Wed, 17 Jul 2024 15:17:05 +0200
Subject: [PATCH] update readme with custom operation builder section

---
 README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 88 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e02bbc2..8b13b05 100644
--- a/README.md
+++ b/README.md
@@ -53,7 +53,7 @@ queries_path = "queries.graphql"
 
 Required settings:
 
-- `queries_path` - path to file/directory with queries
+- `queries_path` - path to file/directory with queries (Can be optional if `enable_custom_operations` is used)
 
 One of the following 2 parameters is required, in case of providing both of them `schema_path` is prioritized:
 
@@ -81,6 +81,93 @@ Optional settings:
 - `opentelemetry_client` (defaults to `false`) - default base clients don't support any performance tracing. Change this option to `true` to use the base client with Open Telemetry support.
 - `files_to_include` (defaults to `[]`) - list of files which will be copied into generated package
 - `plugins` (defaults to `[]`) - list of plugins to use during generation
+- `enable_custom_operations` (defaults to `false`) - enables building custom operations. Generates additional files that contains all the classes and methods for generation.
+
+
+## Custom operation builder
+
+The custom operation builder allows you to create complex GraphQL queries in a structured and intuitive way. 
+
+### Example Code
+
+```python
+import asyncio
+from graphql_client import Client
+from graphql_client.custom_fields import (
+    ProductFields,
+    ProductTranslatableContentFields,
+    ProductTranslationFields,
+    TranslatableItemConnectionFields,
+    TranslatableItemEdgeFields,
+)
+from graphql_client.custom_queries import Query
+from graphql_client.enums import LanguageCodeEnum, TranslatableKinds
+
+
+async def get_products():
+    # Create a client instance with the specified URL and headers
+    client = Client(
+        url="https://saleor.cloud/graphql/",
+        headers={"authorization": "bearer ..."},
+    )
+
+    # Build the queries
+    product_query = Query.product(id="...", channel="channel-uk").fields(
+        ProductFields.id,
+        ProductFields.name,
+    )
+
+    translation_query = Query.translations(kind=TranslatableKinds.PRODUCT, first=10).fields(
+        TranslatableItemConnectionFields.edges().alias("aliased_edges").fields(
+            TranslatableItemEdgeFields.node.on(
+                "ProductTranslatableContent",
+                ProductTranslatableContentFields.id,
+                ProductTranslatableContentFields.product_id,
+                ProductTranslatableContentFields.name,
+            )
+        )
+    )
+
+    # Execute the queries with an operation name
+    response = await client.query(
+        product_query,
+        translation_query,
+        operation_name="get_products",
+    )
+
+    print(response)
+
+# Run the async function
+asyncio.run(get_products())
+```
+
+### Explanation
+
+
+1. Building the Product Query:
+   1. The Query.product(id="...", channel="channel-uk") initiates a query for a product with the specified ID and channel.
+   2. .fields(ProductFields.id, ProductFields.name) specifies the fields to retrieve for the product: id and name.
+2. Building the Translation Query:
+   1. The Query.translations(kind=TranslatableKinds.PRODUCT, first=10) initiates a query for product translations.
+   2. .fields(...) specifies the fields to retrieve for the translations.
+   3. .alias("aliased_edges") renames the edges field to aliased_edges.
+   4. .on("ProductTranslatableContent", ...) specifies the fields to retrieve if the node is of type ProductTranslatableContent: id, product_id, and name.
+3. Executing the Queries:
+   1. The client.query(...) method is called with the built queries and an operation name "get_products".   
+   2. This method sends the queries to the server and retrieves the response.
+
+
+### Example pyproject.toml configuration. 
+
+`Note: queries_path is optional when enable_custom_operations is set to true`
+
+```toml
+[tool.ariadne-codegen]
+schema_path = "schema.graphql"
+include_comments = "none"
+target_package_name = "example_client"
+enable_custom_operations = true
+```
 
 
 ## Plugins