diff --git a/docs/examples/python-requests-jwt.md b/docs/examples/python-requests-jwt.md new file mode 100644 index 000000000..a0a5f291b --- /dev/null +++ b/docs/examples/python-requests-jwt.md @@ -0,0 +1,40 @@ +## Python Client for PostgREST API + +### Setup PostgreSQL + +This code relies on setting up the PostgreSQL auth functions and grants correctly first. Follow [these instructions](http://postgrest.com/examples/users/). + +After completing the PostgreSQL configuration, be sure to create a user with email, password, role, and verified flag. We'll use that user to login in the code below. + +### Setup PostgREST + +Next, setup PostgREST according to the documentation [http://postgrest.com/install/server/](here). + +### Setup Python Client + +Finally, we'll install and configure the python client. Follow the instructions in the [README](https://github.com/davidthewatson/postgrest_python_requests_client/blob/master/README.md). Be sure to set the [credentials](https://github.com/davidthewatson/postgrest_python_requests_client/blob/master/config.in#L3-L5) and [urls](https://github.com/davidthewatson/postgrest_python_requests_client/blob/master/config.in#L7-L9) in config.py. + +### Python Client Functions + +There are four primary functions to the python client: + +* login +* construct_jwt_auth +* get_result_size +* get_range + +The *login* and *construct_jwt_auth* functions will be required for any REST client using a PostgREST server, since a JWT auth instance is presumed. + +The *get_result_size* and *get_range* functions are designed specifically for result sets where pagination is required. You can certainly use them for a single page result set that does not require pagination, but that may be overkill. + +### Login +The [login function](https://github.com/davidthewatson/postgrest_python_requests_client/blob/master/client.py#L12-L17) takes email and password strings (credentials.email and credentials.password, respectively from the config.py) and return the response. + +### Construct JWT Auth +The [construct_jwt_auth](https://github.com/davidthewatson/postgrest_python_requests_client/blob/master/client.py#L20-L23) function takes the auth response returned by the login function, retrieves the token in the response, and returns a JWT auth instance to the caller. The JWT auth instance can then be used for successive calls to the same PostgREST service. + +### Get Result Size +The [get_result_size](https://github.com/davidthewatson/postgrest_python_requests_client/blob/master/client.py#L26-L30) function takes a JWT auth instance calls the URL at urls.data, extracts the size of the result set from the response object and returns the size. + +### Get Range +The [get_range](https://github.com/davidthewatson/postgrest_python_requests_client/blob/master/client.py#L26-L30) function takes a beginning range, ending range, page size, and JWT auth instance, gets only that range of the available result set and returns JSON for that result set. diff --git a/docs/install/ecosystem.md b/docs/install/ecosystem.md index 4e153f201..b927f2871 100644 --- a/docs/install/ecosystem.md +++ b/docs/install/ecosystem.md @@ -5,6 +5,7 @@ * [mithril.postgrest](https://github.com/catarse/mithril.postgrest) - Mithril plugin to create and authenticate requests * [lewisjared/postgrest-request](https://github.com/lewisjared/postgrest-request) - node interface to postgrest instances * [JarvusInnovations/jarvus-postgrest-apikit](https://github.com/JarvusInnovations/jarvus-postgrest-apikit) - Sencha framework package for binding models/stores/proxies to PostgREST tables +* [davidthewatson/postgrest_python_requests_client](https://github.com/davidthewatson/postgrest_python_requests_client) - python client featuring JWT auth and pagination of result sets ### Extensions diff --git a/mkdocs.yml b/mkdocs.yml index e012d5156..8eaaf5b5a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,3 +25,4 @@ pages: - User Management: examples/users.md - External Authentication: examples/external_auth.md - Multi-Tenant Blog: examples/blog.md + - Python Client: examples/python-requests-jwt.md