Factor out _some to back one and one_or_zero

This changes the name of the NotFound exception to OutOfBounds, which is
actually backwards incompatible with our documented interface. Fudgin'
it. :/

Author: chadwhitacre

postgres.py

@@ -194,14 +194,25 @@ def url_to_dsn(url):
 # Exceptions
 # ==========
 
-class NotOne(Exception):
-    def __init__(self, rowcount):
-        self.rowcount = rowcount
+class OutOfBounds(Exception):
+
+    def __init__(self, n, lo, hi):
+        self.n = n
+        self.lo = lo
+        self.hi = hi
+
     def __str__(self):
-        return "Got {0} rows instead of 1.".format(self.rowcount)
+        msg = "Got {n} rows; expecting "
+        if self.lo == self.hi:
+            msg += "exactly {lo}."
+        elif self.hi - self.lo == 1:
+            msg += "{lo} or {hi}."
+        else:
+            msg += "between {lo} and {hi} (inclusive)."
+        return msg.format(**self.__dict__)
 
-class TooFew(NotOne): pass
-class TooMany(NotOne): pass
+class TooFew(OutOfBounds): pass
+class TooMany(OutOfBounds): pass
 
 
 # The Main Event
@@ -335,7 +346,7 @@ def one(self, sql, parameters=None, strict=None):
         By default, :py:attr:`strict` ends up evaluating to :py:class:`True`,
         in which case we raise :py:exc:`postgres.TooFew` or
         :py:exc:`postgres.TooMany` if the number of rows returned isn't exactly
-        one (both are subclasses of :py:exc:`postgres.NotOne`). You can
+        one (both are subclasses of :py:exc:`postgres.OutOfBounds`). You can
         override this behavior per-call with the :py:attr:`strict` argument
         here, or globally by passing :py:attr:`strict_one` to the
         :py:class:`~postgres.Postgres` constructor. If you use both, the
@@ -357,16 +368,14 @@ def one(self, sql, parameters=None, strict=None):
             else:
                 strict = self.strict_one    # user default
 
-        with self.get_cursor() as cursor:
-            cursor.execute(sql, parameters)
-
-            if strict:
-                if cursor.rowcount < 1:
-                    raise TooFew(cursor.rowcount)
-                elif cursor.rowcount > 1:
-                    raise TooMany(cursor.rowcount)
+        if strict:
+            out = self._some(sql, parameters, 1, 1)
+        else:
+            with self.get_cursor() as cursor:
+                cursor.execute(sql, parameters)
+                out = cursor.fetchone()
+        return out
 
-            return cursor.fetchone()
 
     def one_or_zero(self, sql, parameters=None):
         """Execute a query and return a single result or :py:class:`None`.
@@ -387,15 +396,24 @@ def one_or_zero(self, sql, parameters=None):
         No blam yet.
 
         """
-        with self.get_cursor() as cursor:
-            cursor.execute(sql, parameters)
+        return self._some(sql, parameters, 0, 1)
+
+
+    def _some(self, sql, parameters=None, lo=0, hi=1):
+
+        # This is undocumented (and largely untested) because I think it's a
+        # rare case where this is wanted directly. It's here to make one and
+        # one_or_zero DRY. Help yourself to it now that you've found it. :^)
+
+        with self.get_cursor() as txn:
+            txn.execute(sql, parameters)
 
-            if cursor.rowcount < 0:
-                raise TooFew(cursor.rowcount)
-            elif cursor.rowcount > 1:
-                raise TooMany(cursor.rowcount)
+            if txn.rowcount < lo:
+                raise TooFew(txn.rowcount, lo, hi)
+            elif txn.rowcount > hi:
+                raise TooMany(txn.rowcount, lo, hi)
 
-            return cursor.fetchone()
+            return txn.fetchone()
 
 
     def get_cursor(self, *a, **kw):

tests.py

@@ -6,7 +6,7 @@
 
 from postgres import Postgres, TooFew, TooMany
 from psycopg2.extras import NamedTupleCursor
-from psycopg2 import InterfaceError
+from psycopg2 import InterfaceError, ProgrammingError
 
 
 DATABASE_URL = os.environ['DATABASE_URL']
@@ -89,14 +89,24 @@ def test_TooFew_message_is_helpful(self):
             self.db.one("SELECT * FROM foo WHERE bar='blah'", strict=True)
         except TooFew as exc:
             actual = str(exc)
-            assert actual == "Got 0 rows instead of 1."
+            assert actual == "Got 0 rows; expecting exactly 1."
 
-    def test_TooMany_message_is_helpful(self):
+    def test_TooMany_message_is_helpful_for_two_options(self):
         try:
-            self.db.one("SELECT * FROM foo", strict=True)
+            self.db.one_or_zero("SELECT * FROM foo")
         except TooMany as exc:
             actual = str(exc)
-            assert actual == "Got 2 rows instead of 1."
+            assert actual == "Got 2 rows; expecting 0 or 1."
+
+    def test_TooMany_message_is_helpful_for_a_range(self):
+        self.db.run("INSERT INTO foo VALUES ('blam')")
+        self.db.run("INSERT INTO foo VALUES ('blim')")
+        try:
+            self.db._some("SELECT * FROM foo", lo=1, hi=3)
+        except TooMany as exc:
+            actual = str(exc)
+            assert actual == \
+                           "Got 4 rows; expecting between 1 and 3 (inclusive)."
 
 
 class TestOne(WithData):