[WIP] Sample Quart integration (#121)

Fixes #119

docs/conf.py

@@ -25,7 +25,7 @@ class Mock(MagicMock):
     def __getattr__(cls, name):
         return MagicMock()
 
-MOCK_MODULES = ['aiosqlite', 'astroid', 'asyncpg', 'aiomysql']
+MOCK_MODULES = ['aiosqlite', 'astroid', 'asyncpg', 'aiomysql', 'quart']
 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
 

docs/contrib.rst

@@ -1,147 +1,12 @@
-=======
 Contrib
 =======
 
-.. _pylint:
-
-PyLint plugin
-=============
-
-Since Tortoise ORM uses MetaClasses to build the Model objects, PyLint will often not understand how the Models behave. We provided a `tortoise.pylint` plugin that enhances PyLints understanding of Models and Fields.
-
-Usage
------
-
-In your projects ``.pylintrc`` file, ensure the following is set:
-
-.. code-block:: ini
-
-    load-plugins=tortoise.contrib.pylint
-
-
-.. _unittest:
-
-.. rst-class:: emphasize-children
-
-UnitTest support
-================
-
-Tortoise ORM includes its own helper utilities to assist in unit tests.
-
-Usage
------
-
-.. code-block:: python3
-
-    from tortoise.contrib import test
-
-    class TestSomething(test.TestCase):
-        def test_something(self):
-            ...
-
-        async def test_something_async(self):
-            ...
-
-        @test.skip('Skip this')
-        def test_skip(self):
-            ...
-
-        @test.expectedFailure
-        def test_something(self):
-            ...
-
-
-To get ``test.TestCase`` to work as expected, you need to configure your test environment setup and teardown to call the following:
-
-.. code-block:: python3
-
-    from tortoise.contrib.test import initializer, finalizer
-
-    # In setup
-    initializer(['module.a', 'module.b.c'])
-    # With optional db_url and loop parameters
-    initializer(['module.a', 'module.b.c'], db_url='...', loop=loop)
-    # Or env-var driven → See Green test runner section below.
-    env_initializer()
-
-    # In teardown
-    finalizer()
-
-
-On the DB_URL it should follow the following standard:
-
-    TORTOISE_TEST_DB=sqlite:///tmp/test-{}.sqlite
-    TORTOISE_TEST_DB=postgres://postgres:@127.0.0.1:5432/test_{}
-
-
-The ``{}`` is a string-replacement parameter, that will create a randomised database name.
-This is currently required for ``test.IsolatedTestCase`` to function.
-If you don't use ``test.IsolatedTestCase`` then you can give an absolute address.
-The SQLite in-memory ``:memory:`` database will always work, and is the default.
-
-Test Runners
-------------
-
-Green
-^^^^^
-
-In your ``.green`` file:
-
-.. code-block:: ini
-
-    initializer = tortoise.contrib.test.env_initializer
-    finalizer = tortoise.contrib.test.finalizer
-
-And then define the ``TORTOISE_TEST_MODULES`` environment variable with a comma separated list of module paths.
-
-Furthermore, you mayset the database configuration parameter as an environment variable (defaults to ``sqlite://:memory:``):
-
-    TORTOISE_TEST_DB=sqlite:///tmp/test-{}.sqlite
-    TORTOISE_TEST_DB=postgres://postgres:@127.0.0.1:5432/test_{}
-
-
-Py.test
-^^^^^^^
-
-Run the initializer and finalizer in your ``conftest.py`` file:
-
-.. code-block:: python3
-
-    from tortoise.contrib.test import finalizer, initializer
-
-    def pytest_runtest_setup(item):
-        initializer(['tortoise.tests.testmodels'], db_url='sqlite://:memory:')
-
-    def pytest_runtest_teardown(item, nextitem):
-        finalizer()
-
-
-Nose2
-^^^^^
-
-Load the plugin ``tortoise.contrib.test.nose2`` either via command line::
-
-    nose2 --plugin tortoise.contrib.test.nose2 --db-module tortoise.tests.testmodels
-
-Or via the config file:
-
-.. code-block:: ini
-
-    [unittest]
-    plugins = tortoise.contrib.test.nose2
+.. toctree::
+   :maxdepth: 3
 
-    [tortoise]
-    # Must specify at least one module path
-    db-module =
-        tortoise.tests.testmodels
-    # You can optionally override the db_url here
-    db-url = sqlite://testdb-{}.sqlite
+   contrib/linters
+   contrib/unittest
+   contrib/quart
 
 
-Reference
----------
 
-.. automodule:: tortoise.contrib.test
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/contrib/linters.rst

@@ -0,0 +1,21 @@
+=======
+Linters
+=======
+
+.. _pylint:
+
+PyLint plugin
+=============
+
+Since Tortoise ORM uses MetaClasses to build the Model objects, PyLint will often not understand how the Models behave. We provided a `tortoise.pylint` plugin that enhances PyLints understanding of Models and Fields.
+
+Usage
+-----
+
+In your projects ``.pylintrc`` file, ensure the following is set:
+
+.. code-block:: ini
+
+    load-plugins=tortoise.contrib.pylint
+
+

docs/contrib/quart.rst

@@ -0,0 +1,34 @@
+==============================
+Tortoise-ORM Quart integration
+==============================
+
+We have a lightweight integration util ``tortoise.contrib.quart`` which has a single function ``register_tortoise`` which sets up Tortoise-ORM on startup and cleans up on teardown.
+
+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.
+
+Usage
+=====
+
+.. code-block:: sh
+
+    QUART_APP=main quart
+        ...
+        Commands:
+          generate-schemas  Populate DB with Tortoise-ORM schemas.
+          run               Start and run a development server.
+          shell             Open a shell within the app context.
+
+    # To generate schemas
+    QUART_APP=main quart generate-schemas
+
+    # To run
+    QUART_APP=main quart run
+
+
+Reference
+=========
+
+.. automodule:: tortoise.contrib.quart
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/contrib/unittest.rst

@@ -0,0 +1,127 @@
+.. _unittest:
+
+================
+UnitTest support
+================
+
+Tortoise ORM includes its own helper utilities to assist in unit tests.
+
+Usage
+=====
+
+.. code-block:: python3
+
+    from tortoise.contrib import test
+
+    class TestSomething(test.TestCase):
+        def test_something(self):
+            ...
+
+        async def test_something_async(self):
+            ...
+
+        @test.skip('Skip this')
+        def test_skip(self):
+            ...
+
+        @test.expectedFailure
+        def test_something(self):
+            ...
+
+
+To get ``test.TestCase`` to work as expected, you need to configure your test environment setup and teardown to call the following:
+
+.. code-block:: python3
+
+    from tortoise.contrib.test import initializer, finalizer
+
+    # In setup
+    initializer(['module.a', 'module.b.c'])
+    # With optional db_url and loop parameters
+    initializer(['module.a', 'module.b.c'], db_url='...', loop=loop)
+    # Or env-var driven → See Green test runner section below.
+    env_initializer()
+
+    # In teardown
+    finalizer()
+
+
+On the DB_URL it should follow the following standard:
+
+    TORTOISE_TEST_DB=sqlite:///tmp/test-{}.sqlite
+    TORTOISE_TEST_DB=postgres://postgres:@127.0.0.1:5432/test_{}
+
+
+The ``{}`` is a string-replacement parameter, that will create a randomised database name.
+This is currently required for ``test.IsolatedTestCase`` to function.
+If you don't use ``test.IsolatedTestCase`` then you can give an absolute address.
+The SQLite in-memory ``:memory:`` database will always work, and is the default.
+
+.. rst-class:: emphasize-children
+
+Test Runners
+============
+
+Green
+-----
+
+In your ``.green`` file:
+
+.. code-block:: ini
+
+    initializer = tortoise.contrib.test.env_initializer
+    finalizer = tortoise.contrib.test.finalizer
+
+And then define the ``TORTOISE_TEST_MODULES`` environment variable with a comma separated list of module paths.
+
+Furthermore, you mayset the database configuration parameter as an environment variable (defaults to ``sqlite://:memory:``):
+
+    TORTOISE_TEST_DB=sqlite:///tmp/test-{}.sqlite
+    TORTOISE_TEST_DB=postgres://postgres:@127.0.0.1:5432/test_{}
+
+
+Py.test
+-------
+
+Run the initializer and finalizer in your ``conftest.py`` file:
+
+.. code-block:: python3
+
+    from tortoise.contrib.test import finalizer, initializer
+
+    def pytest_runtest_setup(item):
+        initializer(['tortoise.tests.testmodels'], db_url='sqlite://:memory:')
+
+    def pytest_runtest_teardown(item, nextitem):
+        finalizer()
+
+
+Nose2
+-----
+
+Load the plugin ``tortoise.contrib.test.nose2`` either via command line::
+
+    nose2 --plugin tortoise.contrib.test.nose2 --db-module tortoise.tests.testmodels
+
+Or via the config file:
+
+.. code-block:: ini
+
+    [unittest]
+    plugins = tortoise.contrib.test.nose2
+
+    [tortoise]
+    # Must specify at least one module path
+    db-module =
+        tortoise.tests.testmodels
+    # You can optionally override the db_url here
+    db-url = sqlite://testdb-{}.sqlite
+
+
+Reference
+=========
+
+.. automodule:: tortoise.contrib.test
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/roadmap.rst

@@ -9,9 +9,15 @@ Our short term goal is to ship the current implementation as MVP, just somewhat
 
 For ``v1.0`` that involves:
 
-* Comprehensive test suite
+* Schema discovery
+* Timezone support
 * Clear and concise examples
 * Refactored Fields Schema generation
+* DB transaction isolation
+* Connection pooling
+* Robust connection handling
+* Change to all-parametrized queries for safety
+
 
 Mid-term
 ========
@@ -26,13 +32,10 @@ Here we have all the features that is slightly further out, in no particular ord
 * Convenience/Ease-Of-Use work:
     * Make ``DELETE`` honour ``limit`` and ``offset``
     * ``.filter(field=None)`` to work as expected
-    * Enable the use of a primary key that is not ``IntField``
-    * Enable to call the primary key something that isn't ``id``
 
 * Expand in the ``init`` framework:
     * Ability to have Management Commands
     * Ability to define Management Commands
-    * Make it simple to control ``init`` from another system
     * Make it simple to inspect Models and Management Commands without using private APIs.
 
 * Better Aggregate functions