Skip to content

Commit 442a45a

Browse files
anand2312anand2312
authored
Add documentation (#111)
* deps: add furo * docs: document public classes * docs: setup sphinx + furo * docs: fix bullet point * fix: remove test file * tests: check if params purged after execute * fix: remove the `asyncio` mark from sync tests * docs: add project version * docs: add rtd config
1 parent 9ddc6f5 commit 442a45a

25 files changed

+685
-101
lines changed

‎.readthedocs.yaml

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
version: 2
2+
3+
build:
4+
os: ubuntu-20.04
5+
tools:
6+
python: "3.9"
7+
8+
sphinx:
9+
configuration: docs/conf.py
10+
11+
python:
12+
install:
13+
- requirements: docs/requirements.txt

‎README.md

+3-7
Original file line numberDiff line numberDiff line change
@@ -54,12 +54,12 @@ pip install postgrest-py
5454

5555
```py
5656
import asyncio
57-
from postgrest_py import PostgrestClient
57+
from postgrest_py import AsyncPostgrestClient
5858

5959
async def main():
60-
async with PostgrestClient("http://localhost:3000") as client:
60+
async with AsyncPostgrestClient("http://localhost:3000") as client:
6161
r = await client.from_("countries").select("*").execute()
62-
countries = r.json()
62+
countries = r.data
6363

6464
asyncio.run(main())
6565
```
@@ -112,10 +112,6 @@ poetry run pytest
112112

113113
Read more [here](https://github.com/supabase/postgrest-py/blob/master/CHANGELOG.md).
114114

115-
## TODO
116-
117-
Read more [here](https://github.com/supabase/postgrest-py/blob/master/TODO.md).
118-
119115
## SPONSORS
120116

121117
We are building the features of Firebase using enterprise-grade, open source products. We support existing communities wherever possible, and if the products don’t exist we build them and open source them ourselves. Thanks to these sponsors who are making the OSS ecosystem better for everyone.

‎docs/Makefile

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/api/client.rst

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Client
2+
======
3+
4+
To run any queries, the first step is to construct a client.
5+
6+
The library offers both synchronous and asynchronous clients.
7+
8+
.. autoclass:: postgrest_py.AsyncPostgrestClient
9+
:members:
10+
:inherited-members:
11+
12+
.. autoclass:: postgrest_py.SyncPostgrestClient
13+
:members:
14+
:inherited-members:

‎docs/api/exceptions.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Exceptions
2+
==========
3+
4+
.. autoexception:: postgrest_py.APIError
5+
:members:

‎docs/api/filters.rst

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Filter Builder
2+
==============
3+
4+
This is a kind of `request builder <Request Builders>`_. It contains all the methods used to
5+
filter data during queries.
6+
7+
.. note::
8+
In the source code, there are separate AsyncFilterRequestBuilders and SyncFilterRequestBuilders.
9+
These classes are otherwise exactly the same, and provide the same interface.
10+
11+
.. warning::
12+
These classes are not meant to be constructed by the user.
13+
14+
.. tip::
15+
The full list of supported filter operators are on the `PostgREST documentation <https://postgrest.org/en/stable/api.html#operators>`_
16+
17+
.. tip::
18+
All the filter methods return a modified instance of the filter builder, allowing fluent chaining of filters.
19+
20+
21+
.. autoclass:: postgrest_py.AsyncFilterRequestBuilder
22+
:members:
23+
:inherited-members:
24+
25+
.. autoclass:: postgrest_py.SyncFilterRequestBuilder
26+
:members:
27+
:inherited-members:

‎docs/api/index.rst

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
API Reference
2+
=============
3+
4+
The library offers both synchronous and asynchronous clients.
5+
Note that the synchronous and asynchronous classes all provide the exact same interface.
6+
7+
.. toctree::
8+
:maxdepth: 3
9+
:caption: Contents:
10+
11+
Client <client>
12+
Request Builders <request_builders>
13+
Filters <filters>
14+
Responses <responses>
15+
Types <types>
16+
Exceptions <exceptions>

‎docs/api/request_builders.rst

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
Request Builders
2+
================
3+
4+
.. note::
5+
In the source code, there are separate synchronous and asynchronous request builder classes.
6+
These classes are otherwise exactly the same, and provide the same interfaces.
7+
8+
.. warning::
9+
These classes are not meant to be constructed by the user.
10+
11+
.. autoclass:: postgrest_py.AsyncRequestBuilder
12+
:members:
13+
:inherited-members:
14+
15+
.. autoclass:: postgrest_py.AsyncSelectRequestBuilder
16+
:members:
17+
:inherited-members:
18+
19+
.. autoclass:: postgrest_py.AsyncQueryRequestBuilder
20+
:members:
21+
:inherited-members:
22+
23+
.. autoclass:: postgrest_py.SyncRequestBuilder
24+
:members:
25+
:inherited-members:
26+
27+
.. autoclass:: postgrest_py.SyncSelectRequestBuilder
28+
:members:
29+
:inherited-members:
30+
31+
.. autoclass:: postgrest_py.SyncQueryRequestBuilder
32+
:members:
33+
:inherited-members:

‎docs/api/responses.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Responses
2+
=========
3+
4+
Once a query is run, the postgrest_py parses the server's response into an APIResponse object.
5+
6+
.. autoclass:: postgrest_py.APIResponse
7+
:members:

‎docs/api/types.rst

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Types
2+
=====
3+
4+
Some type aliases and enums used in the library.
5+
6+
.. autoclass:: postgrest_py.types.CountMethod
7+
:members:
8+
9+
.. autoclass:: postgrest_py.types.Filters
10+
:members:
11+
12+
.. autoclass:: postgrest_py.types.RequestMethod
13+
:members:
14+
15+
.. autoclass:: postgrest_py.types.ReturnMethod
16+
:members:

‎docs/conf.py

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
# import os
14+
# import sys
15+
# sys.path.insert(0, os.path.abspath('.'))
16+
17+
18+
# -- Project information -----------------------------------------------------
19+
import postgrest_py
20+
21+
project = "postgrest-py"
22+
version = postgrest_py.__version__
23+
release = version
24+
copyright = (
25+
"2022, Anand Krishna, Daniel Reinón García, Joel Lee, Leynier Gutiérrez González"
26+
)
27+
author = "Anand Krishna, Daniel Reinón García, Joel Lee, Leynier Gutiérrez González"
28+
29+
30+
# -- General configuration ---------------------------------------------------
31+
32+
# Add any Sphinx extension module names here, as strings. They can be
33+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
34+
# ones.
35+
extensions = [
36+
"sphinx.ext.autodoc",
37+
"sphinx.ext.napoleon",
38+
"sphinx.ext.extlinks",
39+
]
40+
41+
# Napolean config
42+
napoleon_google_docstring = True
43+
44+
# autodoc config
45+
autodoc_member_order = "bysource"
46+
autodoc_class_signature = "separated"
47+
48+
# Add any paths that contain templates here, relative to this directory.
49+
templates_path = ["_templates"]
50+
51+
# List of patterns, relative to source directory, that match files and
52+
# directories to ignore when looking for source files.
53+
# This pattern also affects html_static_path and html_extra_path.
54+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
55+
56+
57+
# -- Options for HTML output -------------------------------------------------
58+
59+
# The theme to use for HTML and HTML Help pages. See the documentation for
60+
# a list of builtin themes.
61+
#
62+
html_theme = "furo"
63+
64+
# Add any paths that contain custom static files (such as style sheets) here,
65+
# relative to this directory. They are copied after the builtin static files,
66+
# so a file named "default.css" will overwrite the builtin "default.css".
67+
html_static_path = ["_static"]

‎docs/examples/index.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Examples
2+
========
3+
4+
Stay tuned! Examples are coming soon.

‎docs/index.rst

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Welcome to postgrest-py's documentation!
2+
========================================
3+
4+
`PostgREST <https://postgrest.org>`_ client library for Python. This library provides an ORM interface to PostgREST.
5+
6+
.. attention::
7+
This library is currently unstable. If you find any bugs, please file an `issue <https://github.com/supabase-community/postgrest-py/issues/>`_.
8+
9+
Installation
10+
============
11+
Requirements:
12+
13+
- Python >= 3.7
14+
15+
**With pip:**
16+
pip install postgrest-py
17+
18+
**With poetry:**
19+
poetry add postgrest-py
20+
21+
22+
.. toctree::
23+
:maxdepth: 3
24+
:caption: Contents:
25+
26+
API Reference </api/index>
27+
Examples </examples/index>

‎docs/make.bat

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.https://www.sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
furo >= 2022.4.7

0 commit comments

Comments
 (0)