> [!WARNING]
> This library is still in active development and is not yet ready for production use. The number of supported authentication, pagination, and interaction methods is limited and likely does not cover all use cases. The library is subject to change and may not be stable.
>
> I am very open to feedback and considering others use cases, so please open an issue if you have any suggestions, requests, or issues!
# Table of Contents
- [Table of Contents](#table-of-contents)
- [ClientForge](#clientforge)
- [Features](#features)
- [Installation](#installation)
- [Overview](#overview)
- [Components](#components)
- [Creation](#creation)
- [Model Definitions](#model-definitions)
- [Client Definition](#client-definition)
- [Simple Usage](#simple-usage)
- [Advanced Usage](#advanced-usage)
- [Selecting Data](#selecting-data)
- [Querying Data](#querying-data)
- [Filtering Data](#filtering-data)
- [Changelog](#changelog)
- [License](#license)
- [Contact](#contact)
# ClientForge
ClientForge is a Python library designed to simplify interactions with REST APIs from Python. It supports a variety of authentication and pagination methods, and provides a robust framework for building and managing Python REST API clients.
It also allows quick and easy handling of results, permitting a variety of filtering and sorting options.
## Features
## Installation
To install ClientForge, use pip:
```sh
pip install clientforge
```
## Overview
ClientForge is designed to make it easy to create Python interfaces for REST APIs. It provides a simple and consistent interface for making requests, handling authentication, and paginating results. The library is built on top of the `httpx` HTTP library, and provides both synchronous and asynchronous clients.
### Components
A ClientForge client consists of the following components:
- **Client**: The main client object that is used to make requests to the server (sync or async).
- **Auth**: An authentication object that handles the authentication process for the client (ex: OAuth2, API key).
- **Paginator**: A paginator object that handles pagination of results from the server (ex: offset/page pagination).
- **Model**: A series of user-defined model classes that represent the data returned by the REST API.
- **Result**: A generic result class that encapsulates the response data and metadata.
- **Method Definitions**: User-defined methods that make define how the client interacts with the API endpoint.
## Creation
> [!NOTE]
> This section provides an overview of how to create a ClientForge client with examples from the Kroger API. This project is in no way associated with Kroger, and the examples are for illustrative purposes only.
>
> Similarly, the examples are not complete to keep the code concise.
### Model Definitions
The core of response/model mapping is handled by the fantastic [dataclass wizard](https://github.com/rnag/dataclass-wizard) by Ritvik Nag. Almost all of the features of dataclass wizard are supported, including nested dataclasses, aliases, loading and dumping, etc.. Please refer to the dataclass wizard documentation for more information on complex model definitions.
In order to define a model, you need to create a class that inherits from `ForgeModel`.
`models.py`:
```python
from clientforge import ForgeModel
class AisleLocation(ForgeModel):
bay_number: int
description: str
class Product(ForgeModel):
product_id: str
aisle_locations: list[AisleLocation]
brand: str
categories: list[str]
description: str
```
### Client Definition
With a simple model created, you need to define a client. There are two types of clients: synchronous and asynchronous. Generally, the synchronous client is going to be enough for most use cases so we will focus on that, but the process is nearly identical for the asynchronous client, with the exception of using `AsyncForgeClient` instead of `ForgeClient` and all methods being `async`.
In order to define a client, you need to create a class that inherits from `ForgeClient` and implement the necessary methods:
`client.py`:
```python
from clientforge import (
AsyncForgeClient,
ClientCredentialsOAuth2Auth,
OffsetPaginator,
Result,
)
from models import Product
class KrogerClient(AsyncForgeClient):
def __init__(
self,
client_id: str,
client_secret: str,
scopes: list | None = None,
limit: int = 10,
):
# The details of how to interact with the REST API are provided to the
# init method of the ForgeClient class
super().__init__(
"https://api.kroger.com/v1/{endpoint}", # Define the base URL for the Kroger API
auth=ClientCredentialsOAuth2Auth( # Authenticate with the Kroger API using OAuth2
"https://api.kroger.com/v1/connect/oauth2/token",
client_id=client_id,
client_secret=client_secret,
scopes=scopes,
),
paginator=OffsetPaginator( # Use offset pagination to handle large result sets
page_size=10,
page_size_param="filter.limit",
path_to_data="data",
page_offset_param="filter.start",
path_to_total="meta.pagination.total",
),
)
if limit <= 0 or limit > 50:
raise ValueError("Limit must be between 1 and 50")
def search_products(
self,
terms: list[str] | None = None,
brand: str | None = None,
fulfillment: str | None = None,
location_id: str | None = None,
product_id: str | None = None,
top_n: int = 10,
) -> Result[Product]:
# A method definition will accept Python-friendly parameters, and return a Result object
# that contains the Model that the user has defined
if terms and len(terms) > 8:
raise ValueError("Number of search terms must be less than or equal to 8")
params = {
"filter.term": " ".join(terms) if terms else None,
"filter.brand": brand,
"filter.fulfillment": fulfillment,
"filter.locationId": location_id,
"filter.productId": product_id,
}
# The _model_request method is a helper method that handles the request and response
# to the REST API, and returns a Result
# Read the docstring for more information on the parameters
return self._model_request(
"GET",
"products", # The endpoint to interact with
Product, # The model to coerce the response into
model_key="data",
params=params,
top_n=top_n,
)
def get_product(self, product_id: str) -> Result[Product]:
# It also works for endpoints that return a single object
return self._model_request(
"GET",
f"products/{product_id}",
Product,
model_key="data",
)
```
## Simple Usage
```python
from client import KrogerClient
client = KrogerClient(
client_id="<YOUR_CLIENT_ID>",
client_secret="<YOUR_CLIENT_SECRET>",
scopes=["product.compact"],
)
result = client.search_products(terms=["milk"], top_n=5)
print(result)
# Result([Product(<data>), Product(<data>), ...])
result = client.get_product("0001111000000")
print(result[0])
# Product(<data>)
```
## Advanced Usage
> [!WARNING]
> The following features are still in development and may not work as expected. They are subject to change. They are designed to provide a more robust and flexible interface for interacting with the results, but may return inconsistent results or errors.
### Selecting Data
Data can be selected and returned into a dictionary or list of dictionaries using the `select` method. The `select` method accepts a list of keys to select from the data, and returns a list of dictionaries with the selected keys. Each key can be a simple key, or a JSONPath expression.
```python
result = client.search_products(terms=["milk"], top_n=5)
print(result.select("product_id", "brand"))
# [{'product_id': '0001111000000', 'brand': 'Kroger'}, ...]
print(result.select("product_id, brand"))
# [{'product_id, brand': ['0001111000000', 'Kroger'], ...]
print(result.select("product_id", item_price="items[*].price.regular"))
# [{'product_id': '0001111000000', 'item_price': [1.99, 2.99, ...], ...]
```
### Querying Data
Data can be filtered using JSONPath syntax using the `query` method. The `query` method accepts a JSONPath expression and returns a Result object containing the filtered data. Note that this does not return a list of the original data, but a Result object containing the filtered data.
```python
print(result.query("items[?(price.regular > 2.00)]")) # Get all items with a regular price greater than $2.00
# Result([Item(<data>), Item(<data>), ...]) (note that the result is not Product objects, but Item objects)
print(products.query("items[*].price.regular"))
# Result(1.99, 2.99, ...)
print(products.query("items[*].price.regular + 10"))
# Result(11.99, 12.99, ...)
```
### Filtering Data
Data can be filtered using the `filter` method. The `filter` method accepts a series of properties and conditionals from the defined model, and returns a Result object containing the filtered data.
> [!NOTE]
> This feature is still in heavy development and may not work as expected. It is styled after the SQLAlchemy ORM, and is intended to provide a similar experience.
```python
print(products.filter(Product.product_id == "0003400029105"))
# Result([Product(<data>)])
print(products.filter(Product.brand == "Kroger"))
# Result([Product(<data>), Product(<data>), ...])
print(products.filter(Product.items.where.any(Item.price.regular > 0)))
# Result([Product(<data>), Product(<data>), ...])
print(products.filter(Product.items.length == 1))
# Result([Product(<data>), Product(<data>), ...])
```
## Changelog
See the CHANGELOG.md for details on changes and updates.
## License
This project is licensed under the terms of the license found in the LICENSE file.
## Contact
For any inquiries or issues, please open an issue on GitHub.
Raw data
{
"_id": null,
"home_page": null,
"name": "clientforge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "api, client, http, httpx, json, jsonpath, oauth, oauth2, oauthlib, rest",
"author": null,
"author_email": "Steven Hogue <steven.d.hogue@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/63/c530d915fb7fb96527f90ec84d85eabee8b109352a60947b733db7fa9514/clientforge-0.7.0.tar.gz",
"platform": null,
"description": "> [!WARNING]\n> This library is still in active development and is not yet ready for production use. The number of supported authentication, pagination, and interaction methods is limited and likely does not cover all use cases. The library is subject to change and may not be stable.\n>\n> I am very open to feedback and considering others use cases, so please open an issue if you have any suggestions, requests, or issues!\n\n# Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [ClientForge](#clientforge)\n - [Features](#features)\n - [Installation](#installation)\n - [Overview](#overview)\n - [Components](#components)\n - [Creation](#creation)\n - [Model Definitions](#model-definitions)\n - [Client Definition](#client-definition)\n - [Simple Usage](#simple-usage)\n - [Advanced Usage](#advanced-usage)\n - [Selecting Data](#selecting-data)\n - [Querying Data](#querying-data)\n - [Filtering Data](#filtering-data)\n - [Changelog](#changelog)\n - [License](#license)\n - [Contact](#contact)\n\n# ClientForge\n\nClientForge is a Python library designed to simplify interactions with REST APIs from Python. It supports a variety of authentication and pagination methods, and provides a robust framework for building and managing Python REST API clients.\n\nIt also allows quick and easy handling of results, permitting a variety of filtering and sorting options.\n\n## Features\n\n\n## Installation\n\nTo install ClientForge, use pip:\n\n```sh\npip install clientforge\n```\n\n## Overview\n\nClientForge is designed to make it easy to create Python interfaces for REST APIs. It provides a simple and consistent interface for making requests, handling authentication, and paginating results. The library is built on top of the `httpx` HTTP library, and provides both synchronous and asynchronous clients.\n\n### Components\n\nA ClientForge client consists of the following components:\n\n- **Client**: The main client object that is used to make requests to the server (sync or async).\n- **Auth**: An authentication object that handles the authentication process for the client (ex: OAuth2, API key).\n- **Paginator**: A paginator object that handles pagination of results from the server (ex: offset/page pagination).\n- **Model**: A series of user-defined model classes that represent the data returned by the REST API.\n- **Result**: A generic result class that encapsulates the response data and metadata.\n- **Method Definitions**: User-defined methods that make define how the client interacts with the API endpoint.\n\n## Creation\n\n> [!NOTE]\n> This section provides an overview of how to create a ClientForge client with examples from the Kroger API. This project is in no way associated with Kroger, and the examples are for illustrative purposes only.\n>\n> Similarly, the examples are not complete to keep the code concise.\n\n### Model Definitions\n\nThe core of response/model mapping is handled by the fantastic [dataclass wizard](https://github.com/rnag/dataclass-wizard) by Ritvik Nag. Almost all of the features of dataclass wizard are supported, including nested dataclasses, aliases, loading and dumping, etc.. Please refer to the dataclass wizard documentation for more information on complex model definitions.\n\nIn order to define a model, you need to create a class that inherits from `ForgeModel`.\n\n`models.py`:\n```python\nfrom clientforge import ForgeModel\nclass AisleLocation(ForgeModel):\n bay_number: int\n description: str\n\nclass Product(ForgeModel):\n product_id: str\n aisle_locations: list[AisleLocation]\n brand: str\n categories: list[str]\n description: str\n```\n\n### Client Definition\n\nWith a simple model created, you need to define a client. There are two types of clients: synchronous and asynchronous. Generally, the synchronous client is going to be enough for most use cases so we will focus on that, but the process is nearly identical for the asynchronous client, with the exception of using `AsyncForgeClient` instead of `ForgeClient` and all methods being `async`.\n\nIn order to define a client, you need to create a class that inherits from `ForgeClient` and implement the necessary methods:\n\n`client.py`:\n```python\nfrom clientforge import (\n AsyncForgeClient,\n ClientCredentialsOAuth2Auth,\n OffsetPaginator,\n Result,\n)\n\nfrom models import Product\n\n\nclass KrogerClient(AsyncForgeClient):\n def __init__(\n self,\n client_id: str,\n client_secret: str,\n scopes: list | None = None,\n limit: int = 10,\n ):\n # The details of how to interact with the REST API are provided to the\n # init method of the ForgeClient class\n super().__init__(\n \"https://api.kroger.com/v1/{endpoint}\", # Define the base URL for the Kroger API\n auth=ClientCredentialsOAuth2Auth( # Authenticate with the Kroger API using OAuth2\n \"https://api.kroger.com/v1/connect/oauth2/token\",\n client_id=client_id,\n client_secret=client_secret,\n scopes=scopes,\n ),\n paginator=OffsetPaginator( # Use offset pagination to handle large result sets\n page_size=10,\n page_size_param=\"filter.limit\",\n path_to_data=\"data\",\n page_offset_param=\"filter.start\",\n path_to_total=\"meta.pagination.total\",\n ),\n )\n\n if limit <= 0 or limit > 50:\n raise ValueError(\"Limit must be between 1 and 50\")\n\n def search_products(\n self,\n terms: list[str] | None = None,\n brand: str | None = None,\n fulfillment: str | None = None,\n location_id: str | None = None,\n product_id: str | None = None,\n top_n: int = 10,\n ) -> Result[Product]:\n # A method definition will accept Python-friendly parameters, and return a Result object\n # that contains the Model that the user has defined\n if terms and len(terms) > 8:\n raise ValueError(\"Number of search terms must be less than or equal to 8\")\n\n params = {\n \"filter.term\": \" \".join(terms) if terms else None,\n \"filter.brand\": brand,\n \"filter.fulfillment\": fulfillment,\n \"filter.locationId\": location_id,\n \"filter.productId\": product_id,\n }\n # The _model_request method is a helper method that handles the request and response\n # to the REST API, and returns a Result\n # Read the docstring for more information on the parameters\n return self._model_request(\n \"GET\",\n \"products\", # The endpoint to interact with\n Product, # The model to coerce the response into\n model_key=\"data\",\n params=params,\n top_n=top_n,\n )\n\n def get_product(self, product_id: str) -> Result[Product]:\n # It also works for endpoints that return a single object\n return self._model_request(\n \"GET\",\n f\"products/{product_id}\",\n Product,\n model_key=\"data\",\n )\n```\n\n## Simple Usage\n\n```python\nfrom client import KrogerClient\n\nclient = KrogerClient(\n client_id=\"<YOUR_CLIENT_ID>\",\n client_secret=\"<YOUR_CLIENT_SECRET>\",\n scopes=[\"product.compact\"],\n)\n\nresult = client.search_products(terms=[\"milk\"], top_n=5)\nprint(result)\n# Result([Product(<data>), Product(<data>), ...])\n\nresult = client.get_product(\"0001111000000\")\nprint(result[0])\n# Product(<data>)\n```\n\n## Advanced Usage\n\n> [!WARNING]\n> The following features are still in development and may not work as expected. They are subject to change. They are designed to provide a more robust and flexible interface for interacting with the results, but may return inconsistent results or errors.\n\n### Selecting Data\n\nData can be selected and returned into a dictionary or list of dictionaries using the `select` method. The `select` method accepts a list of keys to select from the data, and returns a list of dictionaries with the selected keys. Each key can be a simple key, or a JSONPath expression.\n\n```python\nresult = client.search_products(terms=[\"milk\"], top_n=5)\n\nprint(result.select(\"product_id\", \"brand\"))\n# [{'product_id': '0001111000000', 'brand': 'Kroger'}, ...]\n\nprint(result.select(\"product_id, brand\"))\n# [{'product_id, brand': ['0001111000000', 'Kroger'], ...]\n\nprint(result.select(\"product_id\", item_price=\"items[*].price.regular\"))\n# [{'product_id': '0001111000000', 'item_price': [1.99, 2.99, ...], ...]\n```\n\n### Querying Data\n\nData can be filtered using JSONPath syntax using the `query` method. The `query` method accepts a JSONPath expression and returns a Result object containing the filtered data. Note that this does not return a list of the original data, but a Result object containing the filtered data.\n\n```python\nprint(result.query(\"items[?(price.regular > 2.00)]\")) # Get all items with a regular price greater than $2.00\n# Result([Item(<data>), Item(<data>), ...]) (note that the result is not Product objects, but Item objects)\n\nprint(products.query(\"items[*].price.regular\"))\n# Result(1.99, 2.99, ...)\n\nprint(products.query(\"items[*].price.regular + 10\"))\n# Result(11.99, 12.99, ...)\n```\n\n### Filtering Data\n\nData can be filtered using the `filter` method. The `filter` method accepts a series of properties and conditionals from the defined model, and returns a Result object containing the filtered data.\n\n> [!NOTE]\n> This feature is still in heavy development and may not work as expected. It is styled after the SQLAlchemy ORM, and is intended to provide a similar experience.\n\n```python\nprint(products.filter(Product.product_id == \"0003400029105\"))\n# Result([Product(<data>)])\n\nprint(products.filter(Product.brand == \"Kroger\"))\n# Result([Product(<data>), Product(<data>), ...])\n\nprint(products.filter(Product.items.where.any(Item.price.regular > 0)))\n# Result([Product(<data>), Product(<data>), ...])\n\nprint(products.filter(Product.items.length == 1))\n# Result([Product(<data>), Product(<data>), ...])\n```\n\n\n## Changelog\n\nSee the CHANGELOG.md for details on changes and updates.\n\n## License\n\nThis project is licensed under the terms of the license found in the LICENSE file.\n\n## Contact\n\nFor any inquiries or issues, please open an issue on GitHub.\n",
"bugtrack_url": null,
"license": null,
"summary": "A set of tools and building blocks to allow simple and easy creation of clients for RESTful APIs.",
"version": "0.7.0",
"project_urls": {
"changelog": "https://github.com/Steven-Hogue/clientforge/CHANGELOG.md",
"homepage": "https://github.com/Steven-Hogue/clientforge",
"repository": "https://github.com/Steven-Hogue/clientforge"
},
"split_keywords": [
"api",
" client",
" http",
" httpx",
" json",
" jsonpath",
" oauth",
" oauth2",
" oauthlib",
" rest"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9493d4640d718ea8b9c38931fb2a96014628c10182cddb0bc42f6686ac32b9a0",
"md5": "875aa632ac712689b73f4a39cafb1bbe",
"sha256": "20ae56e8e4d76771072ed577c153521ca944f1735de4c876d32c882cc3eb7ab5"
},
"downloads": -1,
"filename": "clientforge-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "875aa632ac712689b73f4a39cafb1bbe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 23342,
"upload_time": "2025-02-10T07:56:35",
"upload_time_iso_8601": "2025-02-10T07:56:35.499527Z",
"url": "https://files.pythonhosted.org/packages/94/93/d4640d718ea8b9c38931fb2a96014628c10182cddb0bc42f6686ac32b9a0/clientforge-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2f63c530d915fb7fb96527f90ec84d85eabee8b109352a60947b733db7fa9514",
"md5": "3f83e54adf08d92ad8f4e5125ec9d073",
"sha256": "d53a0827da8603acce0be0b98d8b4024aaef9b19854f858879e5422932701e32"
},
"downloads": -1,
"filename": "clientforge-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "3f83e54adf08d92ad8f4e5125ec9d073",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 46093,
"upload_time": "2025-02-10T07:56:37",
"upload_time_iso_8601": "2025-02-10T07:56:37.849495Z",
"url": "https://files.pythonhosted.org/packages/2f/63/c530d915fb7fb96527f90ec84d85eabee8b109352a60947b733db7fa9514/clientforge-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-10 07:56:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Steven-Hogue",
"github_project": "clientforge",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "clientforge"
}
JSON
