Implement one() and one_or_none()

Author: ilai-deutel

docs/engine.rst

@@ -384,9 +384,11 @@ Executing Queries
 -----------------
 
 Once you have a :class:`~gino.engine.GinoConnection` instance, you can start
-executing queries with it. There are 4 variants of the execute method:
+executing queries with it. There are 6 variants of the execute method:
 :meth:`~gino.engine.GinoConnection.all`,
 :meth:`~gino.engine.GinoConnection.first`,
+:meth:`~gino.engine.GinoConnection.one`,
+:meth:`~gino.engine.GinoConnection.one_or_none`,
 :meth:`~gino.engine.GinoConnection.scalar` and
 :meth:`~gino.engine.GinoConnection.status`. They are basically the same:
 accepting the same parameters, calling the same underlying methods. The
@@ -399,6 +401,11 @@ difference is how they treat the results:
   or ``None`` if there is no result at all. There is usually some optimization
   behind the scene to efficiently get only the first result, instead of loading
   the full result set into memory.
+* :meth:`~gino.engine.GinoConnection.one` returns exactly one result. If there
+  is no result at all or if there are multiple results, an exception is raised.
+* :meth:`~gino.engine.GinoConnection.one_or_none` is similar to
+  :meth:`~gino.engine.GinoConnection.one`, but it returns ``None`` if there is
+  no result instead or raising an exception.
 * :meth:`~gino.engine.GinoConnection.scalar` is similar to
   :meth:`~gino.engine.GinoConnection.first`, it returns the first value of the
   first result. Quite convenient to just retrieve a scalar value from database,

docs/schema.rst

@@ -79,6 +79,10 @@ but return a bit differently. There are also other similar query APIs:
   :class:`~sqlalchemy.engine.RowProxy`
 * :meth:`~gino.engine.GinoConnection.first` returns one
   :class:`~sqlalchemy.engine.RowProxy`, or ``None``
+* :meth:`~gino.engine.GinoConnection.one` returns one
+  :class:`~sqlalchemy.engine.RowProxy`
+* :meth:`~gino.engine.GinoConnection.one_or_none` returns one
+  :class:`~sqlalchemy.engine.RowProxy`, or ``None``
 * :meth:`~gino.engine.GinoConnection.scalar` returns a single value, or
   ``None``
 * :meth:`~gino.engine.GinoConnection.iterate` returns an asynchronous iterator

gino/api.py

@@ -25,8 +25,9 @@ class GinoExecutor:
         await User.query.gino.first()
 
     This allows GINO to add the asynchronous query APIs (:meth:`all`,
-    :meth:`first`, :meth:`scalar`, :meth:`status`, :meth:`iterate`) to
-    SQLAlchemy query clauses without messing up with existing synchronous ones.
+    :meth:`first`, :meth:`one`, :meth:`one_or_none`, :meth:`scalar`,
+    :meth:`status`, :meth:`iterate`) to SQLAlchemy query clauses without
+    messing up with existing synchronous ones.
     Calling these asynchronous query APIs has the same restriction - the
     relevant metadata (the :class:`Gino` instance) must be bound to an engine,
     or an :exc:`AttributeError` will be raised.
@@ -135,6 +136,28 @@ async def first(self, *multiparams, **params):
         return await self._query.bind.first(self._query, *multiparams,
                                             **params)
 
+    async def one_or_none(self, *multiparams, **params):
+        """
+        Returns :meth:`engine.one_or_none() <.engine.GinoEngine.one_or_none>`
+        with this query as the first argument, and other arguments followed,
+        where ``engine`` is the :class:`~.engine.GinoEngine` to which the
+        metadata (:class:`Gino`) is bound, while metadata is found in this
+        query.
+
+        """
+        return await self._query.bind.one_or_none(self._query, *multiparams,
+                                                  **params)
+
+    async def one(self, *multiparams, **params):
+        """
+        Returns :meth:`engine.one() <.engine.GinoEngine.one>` with this query
+        as the first argument, and other arguments followed, where ``engine``
+        is the :class:`~.engine.GinoEngine` to which the metadata
+        (:class:`Gino`) is bound, while metadata is found in this query.
+
+        """
+        return await self._query.bind.one(self._query, *multiparams, **params)
+
     async def scalar(self, *multiparams, **params):
         """
         Returns :meth:`engine.scalar() <.engine.GinoEngine.scalar>` with this
@@ -451,6 +474,21 @@ async def first(self, clause, *multiparams, **params):
         """
         return await self.bind.first(clause, *multiparams, **params)
 
+    async def one_or_none(self, clause, *multiparams, **params):
+        """
+        A delegate of :meth:`GinoEngine.one_or_none()
+        <.engine.GinoEngine.one_or_none>`.
+
+        """
+        return await self.bind.one_or_none(clause, *multiparams, **params)
+
+    async def one(self, clause, *multiparams, **params):
+        """
+        A delegate of :meth:`GinoEngine.one() <.engine.GinoEngine.first>`.
+
+        """
+        return await self.bind.one(clause, *multiparams, **params)
+
     async def scalar(self, clause, *multiparams, **params):
         """
         A delegate of :meth:`GinoEngine.scalar() <.engine.GinoEngine.scalar>`.

gino/engine.py

@@ -8,6 +8,7 @@
 from sqlalchemy.engine import Engine, Connection
 from sqlalchemy.sql import schema
 
+from .exceptions import MultipleResultsFound, NoResultFound
 from .transaction import GinoTransaction
 
 
@@ -179,8 +180,8 @@ class GinoConnection:
     Represents an actual database connection.
 
     This is the root of all query API like :meth:`all`, :meth:`first`,
-    :meth:`scalar` or :meth:`status`, those on engine or query are simply
-    wrappers of methods in this class.
+    :meth:`one`, :meth:`one_or_none`, :meth:`scalar` or :meth:`status`,
+    those on engine or query are simply wrappers of methods in this class.
 
     Usually instances of this class are created by :meth:`.GinoEngine.acquire`.
 
@@ -323,6 +324,50 @@ async def first(self, clause, *multiparams, **params):
         result = self._execute(clause, multiparams, params)
         return await result.execute(one=True)
 
+    async def one_or_none(self, clause, *multiparams, **params):
+        """
+        Runs the given query in database, returns at most one result.
+
+        If the query returns no result, this method will return ``None``.
+        If the query returns multiple results, this method will raise
+        :class:`~gino.exceptions.MultipleResultsFound`.
+
+        See :meth:`all` for common query comments.
+
+        """
+        result = self._execute(clause, multiparams, params)
+        ret = await result.execute()
+
+        if ret is None or len(ret) == 0:
+            return None
+
+        if len(ret) == 1:
+            return ret[0]
+
+        raise MultipleResultsFound('Multiple rows found for one_or_none().')
+
+    async def one(self, clause, *multiparams, **params):
+        """
+        Runs the given query in database, returns exactly one result.
+
+        If the query returns no result, this method will raise
+        :class:`~gino.exceptions.NoResultFound`.
+        If the query returns multiple results, this method will raise
+        :class:`~gino.exceptions.MultipleResultsFound`.
+
+        See :meth:`all` for common query comments.
+
+        """
+        try:
+            ret = await self.one_or_none(clause, *multiparams, **params)
+        except MultipleResultsFound:
+            raise MultipleResultsFound('Multiple rows found for one().')
+
+        if ret is None:
+            raise NoResultFound('No row was found for one().')
+
+        return ret
+
     async def scalar(self, clause, *multiparams, **params):
         """
         Runs the given query in database, returns the first result.
@@ -696,6 +741,22 @@ async def first(self, clause, *multiparams, **params):
         async with self.acquire(reuse=True) as conn:
             return await conn.first(clause, *multiparams, **params)
 
+    async def one_or_none(self, clause, *multiparams, **params):
+        """
+        Runs :meth:`~.GinoConnection.one_or_none`, See :meth:`.all`.
+
+        """
+        async with self.acquire(reuse=True) as conn:
+            return await conn.one_or_none(clause, *multiparams, **params)
+
+    async def one(self, clause, *multiparams, **params):
+        """
+        Runs :meth:`~.GinoConnection.one`, See :meth:`.all`.
+
+        """
+        async with self.acquire(reuse=True) as conn:
+            return await conn.one(clause, *multiparams, **params)
+
     async def scalar(self, clause, *multiparams, **params):
         """
         Runs :meth:`~.GinoConnection.scalar`, See :meth:`.all`.

gino/exceptions.py

@@ -12,3 +12,11 @@ class UninitializedError(GinoException):
 
 class UnknownJSONPropertyError(GinoException):
     pass
+
+
+class MultipleResultsFound(GinoException):
+    pass
+
+
+class NoResultFound(GinoException):
+    pass

tests/test_engine.py

@@ -23,6 +23,8 @@ async def test_basic(engine):
     assert isinstance(await engine.scalar(sa.text('select now()')), datetime)
     assert isinstance((await engine.first('select now()'))[0], datetime)
     assert isinstance((await engine.all('select now()'))[0][0], datetime)
+    assert isinstance((await engine.one('select now()'))[0], datetime)
+    assert isinstance((await engine.one_or_none('select now()'))[0], datetime)
     status, result = await engine.status('select now()')
     assert status == 'SELECT 1'
     assert isinstance(result[0][0], datetime)

tests/test_executemany.py

@@ -1,5 +1,6 @@
 import pytest
 
+from gino import MultipleResultsFound, NoResultFound
 from .models import db, User
 
 pytestmark = pytest.mark.asyncio
@@ -51,6 +52,65 @@ async def test_first(bind):
     assert set(u.nickname for u in rows) == {'1', '2', '3', '4'}
 
 
+# noinspection PyUnusedLocal
+async def test_one_or_none(bind):
+    row = await User.query.gino.one_or_none()
+    assert row is None
+
+    await User.create(nickname='0')
+    row = await User.query.gino.one_or_none()
+    assert row.nickname == '0'
+
+    result = await User.insert().returning(User.nickname).gino.one_or_none(
+        dict(name='1'), dict(name='2'))
+    assert result is None
+    rows = await User.query.gino.all()
+    assert len(await User.query.gino.all()) == 3
+    assert set(u.nickname for u in rows) == {'0', '1', '2'}
+
+    with pytest.raises(MultipleResultsFound):
+        row = await User.query.gino.one_or_none()
+
+    result = await User.insert().gino.one_or_none(
+        dict(name='3'), dict(name='4'))
+    assert result is None
+    rows = await User.query.gino.all()
+    assert len(rows) == 5
+    assert set(u.nickname for u in rows) == {'0', '1', '2', '3', '4'}
+
+    with pytest.raises(MultipleResultsFound):
+        row = await User.query.gino.one_or_none()
+
+
+# noinspection PyUnusedLocal
+async def test_one(bind):
+    with pytest.raises(NoResultFound):
+        row = await User.query.gino.one()
+
+    await User.create(nickname='0')
+    row = await User.query.gino.one()
+    assert row.nickname == '0'
+
+    with pytest.raises(NoResultFound):
+        await User.insert().returning(User.nickname).gino.one(
+            dict(name='1'), dict(name='2'))
+    rows = await User.query.gino.all()
+    assert len(await User.query.gino.all()) == 3
+    assert set(u.nickname for u in rows) == {'0', '1', '2'}
+
+    with pytest.raises(MultipleResultsFound):
+        row = await User.query.gino.one()
+
+    with pytest.raises(NoResultFound):
+        await User.insert().gino.one(dict(name='3'), dict(name='4'))
+    rows = await User.query.gino.all()
+    assert len(rows) == 5
+    assert set(u.nickname for u in rows) == {'0', '1', '2', '3', '4'}
+
+    with pytest.raises(MultipleResultsFound):
+        row = await User.query.gino.one()
+
+
 # noinspection PyUnusedLocal
 async def test_scalar(bind):
     result = await User.insert().returning(User.nickname).gino.scalar(

tests/test_loader.py

@@ -45,6 +45,25 @@ async def test_scalar(user):
     assert user.nickname == name
 
 
+async def test_one_or_none(user):
+    name = await User.query.gino.load(User.nickname).one_or_none()
+    assert user.nickname == name
+
+    uid, name = await (User.query.gino.load((User.id, User.nickname))
+                       .one_or_none())
+    assert user.id == uid
+    assert user.nickname == name
+
+
+async def test_one(user):
+    name = await User.query.gino.load(User.nickname).one()
+    assert user.nickname == name
+
+    uid, name = await User.query.gino.load((User.id, User.nickname)).one()
+    assert user.id == uid
+    assert user.nickname == name
+
+
 async def test_model_load(user):
     u = await User.query.gino.load(User.load('nickname', User.team_id)).first()
     assert isinstance(u, User)