Rename rows to all; #16

Author: chadwhitacre

postgres.py

@@ -35,9 +35,9 @@
     {'bar': 'baz'}
 
 
-Use :py:meth:`~postgres.Postgres.rows` to fetch all results:
+Use :py:meth:`~postgres.Postgres.all` to fetch all results:
 
-    >>> db.rows("SELECT * FROM foo ORDER BY bar")
+    >>> db.all("SELECT * FROM foo ORDER BY bar")
     [{'bar': 'baz'}, {'bar': 'buz'}]
 
 
@@ -64,7 +64,7 @@
 
 Eighty percent of your database usage should be covered by the simple
 :py:meth:`~postgres.Postgres.run`, :py:meth:`~postgres.Postgres.one`,
-:py:meth:`~postgres.Postgres.rows` API introduced above. For the other 20%,
+:py:meth:`~postgres.Postgres.all` API introduced above. For the other 20%,
 :py:mod:`postgres` provides context managers for working at increasingly lower
 levels of abstraction. The lowest level of abstraction in :py:mod:`postgres` is
 a :py:mod:`psycopg2` `connection pool
@@ -100,10 +100,10 @@
 
     >>> with db.get_transaction() as txn:
     ...     txn.execute("INSERT INTO foo VALUES ('blam')")
-    ...     db.rows("SELECT * FROM foo ORDER BY bar")
+    ...     db.all("SELECT * FROM foo ORDER BY bar")
     ...
     [{'bar': 'baz'}, {'bar': 'buz'}]
-    >>> db.rows("SELECT * FROM foo ORDER BY bar")
+    >>> db.all("SELECT * FROM foo ORDER BY bar")
     [{'bar': 'baz'}, {'bar': 'blam'}, {'bar': 'buz'}]
 
 The :py:func:`~postgres.Postgres.get_transaction` manager gives you a cursor
@@ -237,7 +237,7 @@ class Postgres(object):
     :py:class:`NamedTupleCursor`.
 
     The names in our simple API, :py:meth:`~postgres.Postgres.run`,
-    :py:meth:`~postgres.Postgres.one`, and :py:meth:`~postgres.Postgres.rows`,
+    :py:meth:`~postgres.Postgres.one`, and :py:meth:`~postgres.Postgres.all`,
     were chosen to be short and memorable, and to not conflict with the DB-API
     2.0 :py:meth:`execute`, :py:meth:`fetchone`, and :py:meth:`fetchall`
     methods, which have slightly different semantics (under DB-API 2.0 you call
@@ -249,7 +249,7 @@ class Postgres(object):
     Note that when working inside a block under one of the context managers,
     you're using DB-API 2.0 (:py:meth:`execute` + :py:meth:`fetch*`), not our
     simple API (:py:meth:`~postgres.Postgres.run` /
-    :py:meth:`~postgres.Postgres.one` / :py:meth:`~postgres.Postgres.rows`).
+    :py:meth:`~postgres.Postgres.one` / :py:meth:`~postgres.Postgres.all`).
 
     .. _this ticket: https://github.com/gittip/postgres.py/issues/16
 
@@ -332,15 +332,15 @@ def one(self, sql, parameters=None, strict=None):
 
             return cursor.fetchone()
 
-    def rows(self, sql, parameters=None):
+    def all(self, sql, parameters=None):
         """Execute a query and return all resulting rows.
 
         :param unicode sql: the SQL statement to execute
         :param parameters: the bind parameters for the SQL statement
         :type parameters: dict or tuple
         :returns: :py:class:`list` of rows
 
-        >>> for row in db.rows("SELECT bar FROM foo"):
+        >>> for row in db.all("SELECT bar FROM foo"):
         ...     print(row["bar"])
         ...
         baz
@@ -351,13 +351,21 @@ def rows(self, sql, parameters=None):
             cursor.execute(sql, parameters)
             return cursor.fetchall()
 
+    def rows(self, *a, **kw):
+
+        # This is for backwards compatibility, see #16. It is stubbed instead
+        # of aliased to avoid showing up in our docs via sphinx autodoc.
+
+        return self.all(*a, **kw)
+
+
     def get_cursor(self, *a, **kw):
         """Return a :py:class:`~postgres.CursorContextManager` that uses our
         connection pool.
 
         This is what :py:meth:`~postgres.Postgres.run`,
         :py:meth:`~postgres.Postgres.one`, and
-        :py:meth:`~postgres.Postgres.rows` use under the hood. You might
+        :py:meth:`~postgres.Postgres.all` use under the hood. You might
         use it if you want to access `cursor attributes
         <http://initd.org/psycopg/docs/cursor.html>`_, for example.
 

tests.py

@@ -42,8 +42,8 @@ class TestRun(WithSchema):
 
     def test_run_runs(self):
         self.db.run("CREATE TABLE foo (bar text)")
-        actual = self.db.rows("SELECT tablename FROM pg_tables "
-                              "WHERE schemaname='public'")
+        actual = self.db.all("SELECT tablename FROM pg_tables "
+                             "WHERE schemaname='public'")
         assert actual == [{"tablename": "foo"}]
 
     def test_run_inserts(self):
@@ -168,22 +168,22 @@ def test_one_raises_TooMany(self):
         self.assertRaises(TooMany, self.db.one, "SELECT * FROM foo")
 
 
-# db.rows
-# =======
+# db.all
+# ======
 
 class TestRows(WithData):
 
     def test_rows_fetches_all_rows(self):
-        actual = self.db.rows("SELECT * FROM foo ORDER BY bar")
+        actual = self.db.all("SELECT * FROM foo ORDER BY bar")
         assert actual == [{"bar": "baz"}, {"bar": "buz"}]
 
     def test_bind_parameters_as_dict_work(self):
         params = {"bar": "baz"}
-        actual = self.db.rows("SELECT * FROM foo WHERE bar=%(bar)s", params)
+        actual = self.db.all("SELECT * FROM foo WHERE bar=%(bar)s", params)
         assert actual == [{"bar": "baz"}]
 
     def test_bind_parameters_as_tuple_work(self):
-        actual = self.db.rows("SELECT * FROM foo WHERE bar=%s", ("baz",))
+        actual = self.db.all("SELECT * FROM foo WHERE bar=%s", ("baz",))
         assert actual == [{"bar": "baz"}]
 
 
@@ -227,14 +227,14 @@ def test_transaction_is_isolated(self):
         with self.db.get_transaction() as txn:
             txn.execute("INSERT INTO foo VALUES ('blam')")
             txn.execute("SELECT * FROM foo ORDER BY bar")
-            actual = self.db.rows("SELECT * FROM foo ORDER BY bar")
+            actual = self.db.all("SELECT * FROM foo ORDER BY bar")
         assert actual == [{"bar": "baz"}, {"bar": "buz"}]
 
     def test_transaction_commits_on_success(self):
         with self.db.get_transaction() as txn:
             txn.execute("INSERT INTO foo VALUES ('blam')")
             txn.execute("SELECT * FROM foo ORDER BY bar")
-        actual = self.db.rows("SELECT * FROM foo ORDER BY bar")
+        actual = self.db.all("SELECT * FROM foo ORDER BY bar")
         assert actual == [{"bar": "baz"}, {"bar": "blam"}, {"bar": "buz"}]
 
     def test_transaction_rolls_back_on_failure(self):
@@ -246,7 +246,7 @@ class Heck(Exception): pass
                 raise Heck
         except Heck:
             pass
-        actual = self.db.rows("SELECT * FROM foo ORDER BY bar")
+        actual = self.db.all("SELECT * FROM foo ORDER BY bar")
         assert actual == [{"bar": "baz"}, {"bar": "buz"}]
 
 
@@ -279,11 +279,11 @@ def setUp(self):                    # override
     def test_NamedDictCursor_results_in_namedtuples(self):
         Record = namedtuple("Record", ["bar"])
         expected = [Record(bar="baz"), Record(bar="buz")]
-        actual = self.db.rows("SELECT * FROM foo ORDER BY bar")
+        actual = self.db.all("SELECT * FROM foo ORDER BY bar")
         assert actual == expected
 
     def test_NamedDictCursor_results_in_namedtuples(self):
         Record = namedtuple("Record", ["bar"])
         expected = [Record(bar="baz"), Record(bar="buz")]
-        actual = self.db.rows("SELECT * FROM foo ORDER BY bar")
+        actual = self.db.all("SELECT * FROM foo ORDER BY bar")
         assert actual == expected