From 919b588abefde64c6073e8f9d2b9e8d9e1606bda Mon Sep 17 00:00:00 2001 From: Pedro Werneck Date: Fri, 8 Dec 2023 05:44:36 -0300 Subject: [PATCH] Update README.md --- README.md | 44 ++++++++++++++++++++------------------------ 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index fe8514c..d0ebbab 100644 --- a/README.md +++ b/README.md @@ -2,61 +2,57 @@ [![Build Status](https://github.com/pjwerneck/rqlalchemy/actions/workflows/pytest.yml/badge.svg?branch=develop)](https://github.com/pjwerneck/rqlalchemy/actions/workflows/pytest.yml) -Resource Query Language extension for SQLAlchemy +## Resource Query Language extension for SQLAlchemy -## Overview +**Overview** Resource Query Language (RQL) is a query language designed for use in URIs, with object-style data structures. -rqlalchemy is an RQL extension for SQLAlchemy. It easily allows exposing SQLAlchemy tables or models as an HTTP API endpoint and performing complex queries using only querystring parameters. +`rqlalchemy` is an RQL extension for SQLAlchemy, making it easy to expose SQLAlchemy tables or models as an HTTP API endpoint and perform complex queries using only query string parameters. -## Installing +**Installing** -``` +```bash pip install rqlalchemy ``` -## Usage - -RQL queries can be supported by an application by using the `select()` construct provided by RQLAlchemy. +**Usage** -Once the selectable is created, use the `rql()` method to apply the RQL querystring, and the `execute()` method with the session to retrieve the results. +Support RQL queries in your application by using the `select()` construct provided by RQLAlchemy. After creating the selectable, use the `rql()` method to apply the RQL query string, and then use the `execute()` method with the session to retrieve the results. -For example, if you have a Flask HTTP API with an users collection endpoint querying your `User` model: +For example, in a Flask HTTP API with a users collection endpoint querying the `User` model: ```python from urllib.parse import unquote - from flask import request @app.route('/users') def get_users_collection(): - qs = unquote(request.query_string.decode(request.charset)) + qs = unquote(request.query_string.decode(request.charset)) users = select(User).rql(qs).execute(session) return render_response(users) ``` -The `.execute()` method handles the session and adjusts the results accordingly, returning scalars, lists of dicts, or a single scalar result when appropriate. There's no need to use `session.execute()` or `session.scalars()` directly, unless you want to handle the results yourself. +The `.execute()` method handles the session and adjusts the results accordingly, returning scalars, lists of dicts, or a single scalar result when appropriate. There's no need to use `session.execute()` or `session.scalars()` directly unless you want to handle the results yourself. -### Pagination +**Pagination** -RQLAlchemy offers limit/offset pagination with the `rql_paginate()` method, which returns the requested page, the RQL expressions for previous and next pages if available, and the total number of items. +RQLAlchemy offers limit/offset pagination with the `rql_paginate()` method, returning the requested page, RQL expressions for previous and next pages if available, and the total number of items. ```python from urllib.parse import unquote - from flask import request @app.route('/users') def get_users_collection(): qs = unquote(request.query_string.decode(request.charset)) - page, previous_page, next_page, total = select(query.rql_paginate() res = select(User).rql(qs).rql_paginate(session) - response = {"data": res.page, - "total": res.total, - } + response = { + "data": res.page, + "total": res.total, + } if res.previous_page: response["previous"] = '/users?' + res.previous_page @@ -67,12 +63,11 @@ def get_users_collection(): return render_response(response) ``` -Pagination requires a limit, as a `RQLSelect._rql_default_limit` value, a querystring `limit(x)`, or the `limit` parameter to the `rql()` method. Calling `rql_paginate()` without a limit will raise `RQLQueryError`. - +Pagination requires a limit, as a `RQLSelect._rql_default_limit` value, a query string `limit(x)`, or the `limit` parameter to the `rql()` method. Calling `rql_paginate()` without a limit will raise `RQLQueryError`. -## Reference Table +**Reference Table** -| RQL | SQLAlchemy equivalent | Obs. | +| RQL | SQLAlchemy equivalent | Observation | |-------------------------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| | QUERYING | | | | select(a,b,c,...) | select(Model.a, Model.b, Model.c,...) | | @@ -103,3 +98,4 @@ Pagination requires a limit, as a `RQLSelect._rql_default_limit` value, a querys | max(attr) | select(func.max(Model.attr)) | | | min(attr) | select(func.min(Model.attr)) | | | count() | select(func.count()) | | +