Skip to content

Commit b4d82ef

Browse files
grigigrigi
authored
Typing & Docs (tortoise#209)
* Improve type annotation of Model & QuerySet so that we get better auto-completion and type checking for all user apps. * Improve doc type matching by using custom sphinx_autodoc_typehints (Plan to upstream it at a later stage) * Fixed many small issues picked up by linters. * Added Examples to docs
1 parent d6bf2e7 commit b4d82ef

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+1028
-309
lines changed

‎CHANGELOG.rst‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,20 @@ Changelog
44
=========
55
0.14.0
66
------
7-
.. warning::
7+
.. caution::
88
**This release drops support of Python 3.5:**
99

1010
Tortoise ORM now requires a minimum of CPython 3.6 or PyPy3.6-7.1
1111

12-
New Features:
12+
Enhancements:
1313
^^^^^^^^^^^^^
14+
- Models, Fields & QuerySets have significant type annotation improvements,
15+
leading to better IDE integration and more comprehensive static analysis.
1416
- Fetching records from the DB is now up to 25% faster.
1517

1618
Bugfixes:
1719
^^^^^^^^^
20+
- The generated index name now has significantly lower chance of collision.
1821

1922
Breaking Changes:
2023
^^^^^^^^^^^^^^^^^

‎Makefile‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,13 @@ endif
4747
python setup.py check -mrs
4848

4949
test: deps
50-
-$(py_warn) TORTOISE_TEST_DB=sqlite://:memory: py.test -q
50+
$(py_warn) TORTOISE_TEST_DB=sqlite://:memory: py.test
5151

5252
_testall:
53-
-$(py_warn) TORTOISE_TEST_DB=sqlite://:memory: py.test -q --cov-report=
54-
-python -V | grep PyPy || $(py_warn) TORTOISE_TEST_DB=postgres://postgres:@127.0.0.1:5432/test_\{\} py.test -q --cov-append --cov-report=
55-
-$(py_warn) TORTOISE_TEST_DB="mysql://root:@127.0.0.1:3306/test_\{\}?storage_engine=MYISAM" py.test -q --cov-append --cov-report=
56-
-$(py_warn) TORTOISE_TEST_DB="mysql://root:@127.0.0.1:3306/test_\{\}" py.test -q --cov-append
53+
$(py_warn) TORTOISE_TEST_DB=sqlite://:memory: py.test --cov-report=
54+
python -V | grep PyPy || $(py_warn) TORTOISE_TEST_DB=postgres://postgres:@127.0.0.1:5432/test_\{\} py.test --cov-append --cov-report=
55+
$(py_warn) TORTOISE_TEST_DB="mysql://root:@127.0.0.1:3306/test_\{\}?storage_engine=MYISAM" py.test --cov-append --cov-report=
56+
$(py_warn) TORTOISE_TEST_DB="mysql://root:@127.0.0.1:3306/test_\{\}" py.test --cov-append
5757

5858
testall: deps _testall
5959

‎README.rst‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,20 @@
22
Tortoise ORM
33
============
44

5-
.. image:: https://badges.gitter.im/tortoise/community.svg
5+
.. image:: https://badges.gitter.im/tortoise/community.png
66
:target: https://gitter.im/tortoise/community
7+
.. image:: https://img.shields.io/pypi/v/tortoise-orm.svg?style=flat
8+
:target: https://pypi.python.org/pypi/tortoise-orm
9+
.. image:: https://readthedocs.org/projects/tortoise-orm/badge/?version=latest
10+
:target: http://tortoise-orm.readthedocs.io/en/latest/
11+
.. image:: https://pepy.tech/badge/tortoise-orm/month
12+
:target: https://pepy.tech/project/tortoise-orm/month
713
.. image:: https://travis-ci.com/tortoise/tortoise-orm.svg?branch=master
814
:target: https://travis-ci.com/tortoise/tortoise-orm
915
.. image:: https://coveralls.io/repos/github/tortoise/tortoise-orm/badge.svg
1016
:target: https://coveralls.io/github/tortoise/tortoise-orm
1117
.. image:: https://api.codacy.com/project/badge/Grade/b5b77021ba284e4a9e0c033a4611b046
1218
:target: https://app.codacy.com/app/Tortoise/tortoise-orm
13-
.. image:: https://readthedocs.org/projects/tortoise-orm/badge/?version=latest
14-
:target: http://tortoise-orm.readthedocs.io/en/latest/
15-
.. image:: https://img.shields.io/pypi/v/tortoise-orm.svg?style=flat
16-
:target: https://pypi.python.org/pypi/tortoise-orm
17-
1819

1920
Introduction
2021
============
@@ -46,7 +47,7 @@ Tortoise ORM is designed to be functional, yet familiar, to ease the migration o
4647

4748
It also performs well when compared to other Python ORMs, only losing to Pony ORM:
4849

49-
.. image:: docs/ORM_Perf.png
50+
.. image:: https://raw.githubusercontent.com/tortoise/tortoise-orm/develop/docs/ORM_Perf.png
5051
:target: https://github.com/tortoise/orm-benchmarks
5152

5253
How is an ORM useful?

‎docs/conf.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,9 @@ def __getattr__(cls, name):
4343
# -- Project information -----------------------------------------------------
4444

4545

46-
project = 'Tortoise'
47-
copyright = '2018, Andrey Bondar' # pylint: disable=W0622
48-
author = 'Andrey Bondar'
46+
project = 'Tortoise ORM'
47+
copyright = '2018-2019, Andrey Bondar & Nickolas Grigoriadis' # pylint: disable=W0622
48+
author = 'Andrey Bondar & Nickolas Grigoriadis'
4949

5050

5151
def get_version():

‎docs/contrib/quart.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _contrib_quart:
2+
13
==============================
24
Tortoise-ORM Quart integration
35
==============================
@@ -6,6 +8,8 @@ We have a lightweight integration util ``tortoise.contrib.quart`` which has a si
68

79
Note that the modules path can not be ``__main__`` as that changes depending on the launch point. One wants to be able to launch a Quart service from the ASGI runner directly, so all paths need to be explicit.
810

11+
See the :ref:`example_quart`
12+
913
Usage
1014
=====
1115

‎docs/contrib/sanic.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
1+
.. _contrib_sanic:
2+
13
==============================
24
Tortoise-ORM Sanic integration
35
==============================
46

57
We have a lightweight integration util ``tortoise.contrib.sanic`` which has a single function ``register_tortoise`` which sets up Tortoise-ORM on startup and cleans up on teardown.
68

9+
See the :ref:`example_sanic`
10+
711
Reference
812
=========
913

‎docs/contrib/starlette.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
1+
.. _contrib_starlette:
2+
13
==================================
24
Tortoise-ORM Starlette integration
35
==================================
46

57
We have a lightweight integration util ``tortoise.contrib.starlette`` which has a single function ``register_tortoise`` which sets up Tortoise-ORM on startup and cleans up on teardown.
68

9+
See the :ref:`example_starlette`
10+
711
Reference
812
=========
913

‎docs/examples.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.. _examples:
2+
3+
========
4+
Examples
5+
========
6+
7+
.. toctree::
8+
:maxdepth: 3
9+
10+
examples/basic
11+
examples/quart
12+
examples/sanic
13+
examples/starlette

‎docs/examples/basic.rst‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
.. _examples_simple:
2+
3+
===============
4+
Simple Examples
5+
===============
6+
7+
.. rst-class:: html-toggle
8+
9+
.. _example_basic:
10+
11+
Basic
12+
=====
13+
.. literalinclude:: ../../examples/basic.py
14+
15+
16+
.. rst-class:: html-toggle
17+
18+
.. _example_basic_comments:
19+
20+
Comments
21+
========
22+
.. literalinclude:: ../../examples/basic_comments.py
23+
24+
25+
.. rst-class:: html-toggle
26+
27+
.. _example_prefetching:
28+
29+
Prefetching
30+
===========
31+
.. literalinclude:: ../../examples/complex_prefetching.py
32+
33+
34+
.. rst-class:: html-toggle
35+
36+
.. _example_transactions:
37+
38+
Transactions
39+
============
40+
.. literalinclude:: ../../examples/transactions.py
41+
42+
43+
.. rst-class:: html-toggle
44+
45+
.. _example_aggregation:
46+
47+
Aggregation
48+
===========
49+
.. literalinclude:: ../../examples/aggregation.py
50+
51+
52+
.. rst-class:: html-toggle
53+
54+
.. _example_schema_create:
55+
56+
Schema creation
57+
===============
58+
.. literalinclude:: ../../examples/schema_create.py
59+
60+
61+
.. rst-class:: html-toggle
62+
63+
.. _example_two_databases:
64+
65+
Two Databases
66+
=============
67+
.. literalinclude:: ../../examples/two_databases.py
68+
69+
70+
.. rst-class:: html-toggle
71+
72+
.. _example_filtering:
73+
74+
Filtering
75+
=========
76+
.. literalinclude:: ../../examples/complex_filtering.py
77+
78+
79+
.. rst-class:: html-toggle
80+
81+
.. _example_relations:
82+
83+
Relations
84+
=========
85+
.. literalinclude:: ../../examples/relations.py
86+
87+
88+
.. rst-class:: html-toggle
89+
90+
.. _example_relations_recursive:
91+
92+
Recursive Relations
93+
===================
94+
.. literalinclude:: ../../examples/relations_recursive.py
95+

‎docs/examples/quart.rst‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. _example_quart:
2+
3+
=============
4+
Quart Example
5+
=============
6+
7+
This is an example of the :ref:`contrib_quart`
8+
9+
**Usage:**
10+
11+
.. code-block:: sh
12+
13+
QUART_APP=main quart
14+
...
15+
Commands:
16+
generate-schemas Populate DB with Tortoise-ORM schemas.
17+
run Start and run a development server.
18+
shell Open a shell within the app context.
19+
20+
# To generate schemas
21+
QUART_APP=main quart generate-schemas
22+
23+
# To run
24+
QUART_APP=main quart run
25+
26+
27+
models.py
28+
=========
29+
.. literalinclude:: ../../examples/quart/models.py
30+
31+
main.py
32+
=======
33+
.. literalinclude:: ../../examples/quart/main.py
34+
35+

0 commit comments

Comments
 (0)