docs: add customization and usage sections

AndreyMarkinPPC · AndreyMarkinPPC · commit e15f11d0604d · 2025-09-19T21:09:35.000+04:00
diff --git a/docs/development/create-api-client.md b/docs/development/create-api-client.md
@@ -0,0 +1,44 @@
+# Create API client for garf
+
+ApiClient is responsible for sending request to an API based on the query.
+
+## Define ApiClient class
+
+Creating an API client is the easiest way of developing with `garf`.
+
+
+`garf-core` library has a `BaseClient` which one mandatory method you need to implement `get_response`.
+
+Your implementation should take an instance of `garf_core.query_editor.BaseQueryElements` class and return `garf_core.api_clients.GarfApiResponse`.
+
+* `BaseQueryElements` contains various elements parsed from the query such as fields, sorts, filters, and resource to get data from.
+* `GarfApiReponse` contains `results` property that should be a list of dictionary-like objects.
+
+
+Let see and example implementation of `MyApiClient`.
+
+```python
+from garf_core import api_clients, query_editor
+
+class MyApiClient(api_clients.BaseClient):
+
+  def get_response(
+    request: query_editor.BaseQueryElements,
+    **kwargs: str
+  ) -> api_clients.GarfApiResponse:
+    results = ... # get results from your API somehow
+    return api_clients.GarfApiResponse(results=results)
+```
+
+## Use with ApiReportFetcher
+
+Once your ApiClient class is defined, you can use with built-in `ApiReportFetcher`.
+
+```python
+from garf_core import ApiReportFetcher
+
+api_client = MyClient()
+report_fetcher = ApiReportFetcher(api_client=api_client)
+```
+!!! note
+    [Learn more](../usage/fetcher.md) about using `ApiReportFetcher`.
diff --git a/docs/development/create-api-response-parser.md b/docs/development/create-api-response-parser.md
@@ -0,0 +1,28 @@
+If your API client returns lists of structures that are not similar to dictionaries,
+you might need to implement a custom parser based on `garf_core.parsers.BaseParser`.
+
+
+## Define Parser class
+
+The only method you need to implement is `parse_row`.
+
+```python
+from garf_core.parsers import BaseParser
+
+class MyParser(BaseParser):
+
+  def parse_row(row):
+    # Your parsing logic here
+```
+
+## Use with ApiReportFetcher
+
+Once your Parser class is defined, you can use with built-in `ApiReportFetcher`.
+
+```python
+from garf_core import ApiReportFetcher
+
+report_fetcher = ApiReportFetcher(api_client, parser=MyParser)
+```
+!!! note
+    [Learn more](../usage/fetcher.md) about using `ApiReportFetcher`.
diff --git a/docs/development/create-garf-library.md b/docs/development/create-garf-library.md
@@ -1,9 +1,9 @@
 # How to create your own garf-based library
 
 
-In order to create your own library follow the steps below:
+In order to create your own library follow the steps.
 
-## Project setup
+## Setup project
 * Create a folder `<YOUR-LIBRARY>` folder with a subfolder `garf_<YOUR_LIBRARY>_api` name.
 
 * Create `pyproject.toml` of the following structure:
@@ -42,7 +42,7 @@ classifiers = [
     your-api = "your_library.report_fetcher"
     ```
 
-## Mandatory classes
+## Implement classes
 
 Go to `garf_<YOUR_LIBRARY>_api` folder and create `report_fetcher.py` file.
 
@@ -89,7 +89,7 @@ class MyLibraryApiReportFetcher(report_fetcher.ApiReportFetcher):
 ```
 
 
-## Installing
+## Install
 
 To test your project install is as an editable package.
 ```bash
@@ -100,7 +100,7 @@ pip install -e .
 !!! note
     If you thing others will benefit from your package you can now upload your project to pypi.
 
-## Running
+## Run
 
 Once you installed the package you can run it with `garf` utility:
 
diff --git a/docs/development/overview.md b/docs/development/overview.md
@@ -0,0 +1,7 @@
+# Build on top of garf
+
+You can create on top of `garf` you can have a couple of options:
+
+* [Create an API client](create-api-client.md) to be used with `ApiReportFetcher` class
+* [Create an API response parser](create-api-response-parser.md) to be customize how `ApiReportFetcher` parses response from API
+* [Create a library](create-garf-library.md) and expose it as `garf` plugin.
diff --git a/docs/index.md b/docs/index.md
@@ -5,7 +5,8 @@
 `garf` is a framework for building various connectors to reporting API that provides
 users with a SQL-like interface to specify what needs to be extracted from the API.
 
-It allows you to define SQL-like queries alongside aliases and custom extractors and specify where the results of such query should be stored.\
+It allows you to define SQL-like queries alongside aliases and custom extractors
+and specify where the results of such query should be stored.
 Based on a query `garf` builds the correct request to a reporting API, parses response
 and transform it into a structure suitable for writing data.
 
diff --git a/docs/usage/api-client.md b/docs/usage/api-client.md
@@ -0,0 +1,54 @@
+# API clients
+
+ApiClient is responsible for sending request to an API based on the query.
+
+## Built-in API clients
+
+### Fake
+
+`FakeApiClient` is ideal for prototyping and test.
+
+It allows you to specify sample response from an API as JSON or a dictionary.
+
+```python
+from garf_core.api_clients import FakeApiClient
+
+fake_data = [
+  {'field1': {'subfield': 1}, 'field2': 2},
+  {'field1': {'subfield': 10}, 'field2': 2},
+]
+api_client = FakeApiClient(results=fake_data)
+```
+
+Instead of providing data as a variable you can read them from JSON or CSV.
+
+```python
+from garf_core.api_clients import FakeApiClient
+
+api_client = FakeApiClient.from_json('path/to/json')
+api_client = FakeApiClient.from_csv('path/to/csv')
+```
+!!! note
+    You can simplify fetching fake data with [`FakeApiReportFetcher`](fetcher.md#fake).
+
+
+### REST
+
+REST API client is useful when you have a REST API available. Provide endpoint
+to get data from.
+
+```python
+from garf_core.api_clients import RestApiClient
+
+endpoint= 'https://api.restful-api.dev'
+api_client = RestApiClient(endpoint=endpoint)
+```
+
+!!! note
+    You can simplify fetching from REST API with [`RestApiReportFetcher`](fetcher.md#rest).
+
+## Create API client
+
+If you want to get reports from different APIs you need to implement new API Client.
+
+Please refer to [development docs](../development/create-api-client.md) to learn more.
diff --git a/docs/usage/fetcher.md b/docs/usage/fetcher.md
@@ -0,0 +1,172 @@
+# ApiReportFetcher
+
+## Initialization
+
+### Api Client
+To initialize `ApiReportFetcher` you need an instance of an API client to
+interact with an API. You can choose from [built-in](api-client.md) API clients
+or [create](../development/create-api-client.md) your own.
+```python
+from garf_core import ApiReportFetcher
+
+report_fetcher = ApiReportFetcher(api_client)
+```
+
+
+### Parser
+
+Under the hood `ApiReportFetcher` fetches data from an API as list of
+dictionaries and tries to access elements in each dictionary via `DictParser`.
+
+You can overwrite this behaviour by using one of [built-in parsers](parsers.md)
+or [implementing](../development/create-api-response-parser.md) your own.
+
+Suppose you want to use `NumericConverterDictParser` to automatically convert
+strings to int/float whenever possible.
+
+
+```python
+from garf_core import ApiReportFetcher
+from garf_core.parsers import NumericConverterDictParser
+
+report_fetcher = ApiReportFetcher(
+  api_client=api_client,
+  parser=NumericConverterDictParser
+)
+```
+
+
+### Built-in queries
+
+Some queries for a particular API can be quite common so you want to create one
+or several [built-in queries](queries.md#built-in-queries).
+
+You can specified them in `builtin_queries` parameters during `ApiReportFetcher`
+initialization.
+
+```python
+from garf_core import ApiReportFetcher
+from garf_core.report import GarfReport
+from garf_core.parsers import NumericConverterDictParser
+
+def builtin_query(fetcher: ApiReportFetcher) -> GarfReport:
+  return fetcher.fetch('SELECT field FROM resource')
+
+
+builtin_queries = {'my_query': builtin_query}
+
+report_fetcher = ApiReportFetcher(
+  api_client=api_client,
+  builtin_queries=builtin_queries
+)
+```
+
+
+## Fetching
+To fetch data from an API use `fetch` method.
+
+```python
+from garf_core import ApiReportFetcher
+
+report_fetcher = ApiReportFetcher(api_client)
+query = 'SELECT metric FROM resource'
+report = report_fetcher.fetch(query)
+```
+
+`fetch` method returns `GarfReport` which can be [processed](reports.md)  in Python
+or [written](writers.md) to local / remote storage.
+
+### Parametrization
+
+If your query contains [macros](queries.md/#macros)  or [templates](queries.md#templates), you need to pass values for them via `args` parameters.
+
+```python
+from garf_core import ApiReportFetcher
+from garf_core.query_editor import GarfQueryParameters
+
+report_fetcher = ApiReportFetcher(api_client)
+
+query = 'SELECT metric FROM resource WHERE dimension={dimension}'
+
+query_parameters = GarfQueryParameters(
+  macro={'dimension': 'value'},
+  template={'dimension': 'value'},
+)
+
+report = report_fetcher.fetch(query, args=query_parameters)
+```
+
+!!! note
+    You can pass a dictionary instead of `GarfQueryParameters`.
+
+    ```python
+
+    query_parameters = {
+      'macro': {
+        'dimension': 'value',
+      },
+      'template': {
+        'dimension': 'value',
+      }
+    }
+
+    report = report_fetcher.fetch(query, args=query_parameters)
+    ```
+
+
+## Built-in report fetchers
+
+To simplify testing and working with REST APIs `garf` has two built-in report fetchers:
+
+* `FakeApiReportFetcher` - simulates API response based on provided data
+* `RestApiReportFetcher` - interacts with APIs with REST interface.
+
+### Fake
+
+`FakeApiReportFetcher` is based on [`FakeApiClient`](api-client.md#fake).
+
+It's ideal for prototyping and testing APIs without interacting with them directly.
+
+```python
+from garf_core.fetchers import FakeApiReportFetcher
+
+fake_data = [
+  {'field1': {'subfield': 1}, 'field2': 2},
+  {'field1': {'subfield': 10}, 'field2': 2},
+]
+report_fetcher = FakeApiReportFetcher.from_data(fake_data)
+
+query = 'SELECT field1.subfield AS column FROM resource'
+report = report_fetcher.fetch(query)
+```
+
+!!!note
+    Instead providing data directly you can use helper methods - `from_json` and `from_csv`:
+
+    ```python
+    report_fetcher = FakeApiReportFetcher.from_json('path/to/json')
+    report_fetcher = FakeApiReportFetcher.from_csv('path/to/csv')
+
+    ```
+
+### Rest
+
+`RestApiReportFetcher` is based on [`RestApiClient`](api-client.md#rest).
+
+It's can be used with any API that provides REST interface.
+
+You need to provide `endpoint` parameter which specifies root level address where
+API exists.
+
+When writing queries specify relative address of the resource you want to fetch from
+(i.e. `customers/1/orders`).
+
+```python
+from garf_core.fetchers import RestApiReportFetcher
+
+endpoint= 'https://api.restful-api.dev'
+report_fetcher = RestApiReportFetcher.from_endpoint(endpoint)
+
+query = 'SELECT id FROM objects'
+report = report_fetcher.fetch(query)
+```
diff --git a/docs/usage/parsers.md b/docs/usage/parsers.md
@@ -0,0 +1,19 @@
+# API Response parsers
+
+Once ApiClient returns response from an API it's Parser's job to convert it to
+the format consumable by `GarfReport`.
+
+## Built-in parsers
+
+* `DictParser` - return an element from API following the attribute path.
+* `NumericConverterDictParser` - subclass of `DictParser` but tries to convert strings to int/float if possible.
+
+!!! important
+    If Parser fails to find an element if returns `None`.
+
+## Create parsers
+
+If response from your API is in the format not supported by built-in parsers you
+can build you own parser.
+
+Please refer to [development docs](../development/create-api-response-parser.md) to learn more.
diff --git a/docs/usage/queries.md b/docs/usage/queries.md
@@ -292,7 +292,6 @@ query = Campaigns(status='DISABLED')
 
 ```python
 from garf_core.base_query import BaseQuery
-from garf_io import reader
 
 class Campaigns(BaseQuery):
   query_text  = """
diff --git a/docs/usage/reports.md b/docs/usage/reports.md
diff --git a/mkdocs.yml b/mkdocs.yml
