Merge pull request piccolo-orm#74 from piccolo-orm/connection_pool_typo

fixing typo with start_connection_pool and close_connection_pool

Author: dantownsend

docs/src/piccolo/engines/postgres_engine.rst

@@ -47,13 +47,13 @@ pool in the shutdown event handler.
     @app.on_event('startup')
     async def open_database_connection_pool():
         engine = engine_finder()
-        await engine.start_connnection_pool()
+        await engine.start_connection_pool()
 
 
     @app.on_event('shutdown')
     async def close_database_connection_pool():
         engine = engine_finder()
-        await engine.close_connnection_pool()
+        await engine.close_connection_pool()
 
 .. hint:: Using a connection pool helps with performance, since connections
     are reused instead of being created for each query.
@@ -74,7 +74,7 @@ adapter. Here's an example:
 .. code-block:: python
 
     # To increase the number of connections available:
-    await engine.start_connnection_pool(max_size=20)
+    await engine.start_connection_pool(max_size=20)
 
 -------------------------------------------------------------------------------
 

piccolo/apps/asgi/commands/templates/starlette/_fastapi_app.py.jinja

@@ -77,10 +77,10 @@ async def delete_task(task_id: int):
 @app.on_event("startup")
 async def open_database_connection_pool():
     engine = engine_finder()
-    await engine.start_connnection_pool()
+    await engine.start_connection_pool()
 
 
 @app.on_event("shutdown")
 async def close_database_connection_pool():
     engine = engine_finder()
-    await engine.close_connnection_pool()
+    await engine.close_connection_pool()

piccolo/apps/asgi/commands/templates/starlette/_starlette_app.py.jinja

@@ -30,10 +30,10 @@ app = Starlette(
 @app.on_event("startup")
 async def open_database_connection_pool():
     engine = engine_finder()
-    await engine.start_connnection_pool()
+    await engine.start_connection_pool()
 
 
 @app.on_event("shutdown")
 async def close_database_connection_pool():
     engine = engine_finder()
-    await engine.close_connnection_pool()
+    await engine.close_connection_pool()

piccolo/engine/postgres.py

@@ -2,7 +2,6 @@
 import contextvars
 from dataclasses import dataclass
 import typing as t
-import warnings
 
 import asyncpg  # type: ignore
 from asyncpg.connection import Connection  # type: ignore
@@ -287,24 +286,44 @@ async def prep_database(self):
                 )
 
     ###########################################################################
+    # These typos existed in the codebase for a while, so leaving these proxy
+    # methods for now to ensure backwards compatility.
 
     async def start_connnection_pool(self, **kwargs) -> None:
+        colored_warning(
+            "`start_connnection_pool` is a typo - please change it to "
+            "`start_connection_pool`.",
+            category=DeprecationWarning,
+        )
+        return await self.start_connection_pool()
+
+    async def close_connnection_pool(self, **kwargs) -> None:
+        colored_warning(
+            "`close_connnection_pool` is a typo - please change it to "
+            "`close_connection_pool`.",
+            category=DeprecationWarning,
+        )
+        return await self.close_connection_pool()
+
+    ###########################################################################
+
+    async def start_connection_pool(self, **kwargs) -> None:
         if self.pool:
-            warnings.warn(
+            colored_warning(
                 "A pool already exists - close it first if you want to create "
-                "a new pool."
+                "a new pool.",
             )
         else:
             config = dict(self.config)
             config.update(**kwargs)
             self.pool = await asyncpg.create_pool(**config)
 
-    async def close_connnection_pool(self) -> None:
+    async def close_connection_pool(self) -> None:
         if self.pool:
             await self.pool.close()
             self.pool = None
         else:
-            warnings.warn("No pool is running.")
+            colored_warning("No pool is running.")
 
     ###########################################################################
 

piccolo/utils/warnings.py

@@ -1,4 +1,6 @@
+from __future__ import annotations
 from enum import Enum
+import typing as t
 import warnings
 
 import colorama  # type: ignore
@@ -14,7 +16,25 @@ class Level(Enum):
 
 
 def colored_warning(
-    message: str, stacklevel: int = 3, level: Level = Level.medium
+    message: str,
+    category: t.Type[Warning] = Warning,
+    stacklevel: int = 3,
+    level: Level = Level.medium,
 ):
+    """
+    A wrapper around the stdlib's `warnings.warn`, which colours the output.
+
+    :param message:
+        The message to display to the user
+    :category:
+        `Warning` has several subclasses which may be more appropriate, for
+        example `DeprecationWarning`.
+    :stacklevel:
+        Used to determine there the source of the error within the source code.
+        See the Python docs for more detail.
+        https://docs.python.org/3/library/warnings.html#warnings.warn
+    :level:
+        Used to determine the colour of the text displayed to the user.
+    """
     colored_message = level.value + message + colorama.Fore.RESET
-    warnings.warn(colored_message, stacklevel=stacklevel)
+    warnings.warn(colored_message, category=category, stacklevel=stacklevel)

tests/engine/test_pool.py

@@ -1,26 +1,33 @@
 import asyncio
 
+from piccolo.engine.postgres import PostgresEngine
+
 from ..base import DBTestCase, postgres_only
 from ..example_app.tables import Manager
 
 
 @postgres_only
 class TestPool(DBTestCase):
     async def _create_pool(self):
-        await Manager._meta.db.start_connnection_pool()
-        await Manager._meta.db.close_connnection_pool()
+        engine: PostgresEngine = Manager._meta.db
+
+        await engine.start_connection_pool()
+        assert engine.pool is not None
+
+        await engine.close_connection_pool()
+        assert engine.pool is None
 
     async def _make_query(self):
-        await Manager._meta.db.start_connnection_pool()
+        await Manager._meta.db.start_connection_pool()
 
         await Manager(name="Bob").save().run()
         response = await Manager.select().run()
         self.assertTrue("Bob" in [i["name"] for i in response])
 
-        await Manager._meta.db.close_connnection_pool()
+        await Manager._meta.db.close_connection_pool()
 
     async def _make_many_queries(self):
-        await Manager._meta.db.start_connnection_pool()
+        await Manager._meta.db.start_connection_pool()
 
         await Manager(name="Bob").save().run()
 
@@ -30,7 +37,7 @@ async def get_data():
 
         await asyncio.gather(*[get_data() for _ in range(500)])
 
-        await Manager._meta.db.close_connnection_pool()
+        await Manager._meta.db.close_connection_pool()
 
     def test_creation(self):
         """
@@ -50,3 +57,24 @@ def test_many_queries(self):
         exceed a connection limit - queries should queue, then succeed.
         """
         asyncio.run(self._make_many_queries())
+
+
+@postgres_only
+class TestPoolProxyMethods(DBTestCase):
+    async def _create_pool(self):
+        engine: PostgresEngine = Manager._meta.db
+
+        # Deliberate typo ('nnn'):
+        await engine.start_connnection_pool()
+        assert engine.pool is not None
+
+        # Deliberate typo ('nnn'):
+        await engine.close_connnection_pool()
+        assert engine.pool is None
+
+    def test_proxy_methods(self):
+        """
+        There are some proxy methods, due to some old typos. Make sure they
+        work, to ensure backwards compatibility.
+        """
+        asyncio.run(self._create_pool())