diff options
Diffstat (limited to 'lib/sqlalchemy/engine/result.py')
| -rw-r--r-- | lib/sqlalchemy/engine/result.py | 113 |
1 files changed, 75 insertions, 38 deletions
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index c2f976aa0..13738cb46 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -129,9 +129,12 @@ except ImportError: class Row(BaseRow, collections_abc.Sequence): """Represent a single result row. + The :class:`.Row` object is retrieved from a database result, from the + :class:`.ResultProxy` object using methods like + :meth:`.ResultProxy.fetchall`. + The :class:`.Row` object seeks to act mostly like a Python named - tuple, but also provides for mapping-oriented access via the - :attr:`.Row._mapping` attribute. + tuple, but also provides some Python dictionary behaviors at the same time. .. seealso:: @@ -189,7 +192,22 @@ class Row(BaseRow, collections_abc.Sequence): return repr(sql_util._repr_row(self)) def has_key(self, key): - """Return True if this Row contains the given key.""" + """Return True if this :class:`.Row` contains the given key. + + Through the SQLAlchemy 1.x series, the ``__contains__()`` method + of :class:`.Row` also links to :meth:`.Row.has_key`, in that + an expression such as :: + + "some_col" in row + + Will return True if the row contains a column named ``"some_col"``, + in the way that a Python mapping works. + + However, it is planned that the 2.0 series of SQLAlchemy will reverse + this behavior so that ``__contains__()`` will refer to a value being + present in the row, in the way that a Python tuple works. + + """ return self._parent._has_key(key) @@ -197,23 +215,52 @@ class Row(BaseRow, collections_abc.Sequence): return self._get_by_key_impl(key) def items(self): - """Return a list of tuples, each tuple containing a key/value pair.""" - # TODO: no coverage here + """Return a list of tuples, each tuple containing a key/value pair. + + This method is analogous to the Python dictionary ``.items()`` method, + except that it returns a list, not an iterator. + + """ + return [(key, self[key]) for key in self.keys()] def keys(self): - """Return the list of keys as strings represented by this Row.""" + """Return the list of keys as strings represented by this + :class:`.Row`. + + This method is analogous to the Python dictionary ``.keys()`` method, + except that it returns a list, not an iterator. + + """ return [k for k in self._parent.keys if k is not None] def iterkeys(self): + """Return a an iterator against the :meth:`.Row.keys` method. + + This method is analogous to the Python-2-only dictionary + ``.iterkeys()`` method. + + """ return iter(self._parent.keys) def itervalues(self): + """Return a an iterator against the :meth:`.Row.values` method. + + This method is analogous to the Python-2-only dictionary + ``.itervalues()`` method. + + """ return iter(self) def values(self): - """Return the values represented by this Row as a list.""" + """Return the values represented by this :class:`.Row` as a list. + + This method is analogous to the Python dictionary ``.values()`` method, + except that it returns a list, not an iterator. + + """ + return self._values_impl() @@ -827,23 +874,16 @@ class ResultMetaData(object): class ResultProxy(object): - """Wraps a DB-API cursor object to provide easier access to row columns. - - Individual columns may be accessed by their integer position, - case-insensitive column name, or by ``schema.Column`` - object. e.g.:: - - row = fetchone() - - col1 = row[0] # access via integer position + """A facade around a DBAPI cursor object. - col2 = row['col2'] # access via name + Returns database rows via the :class:`.Row` class, which provides + additional API features and behaviors on top of the raw data returned + by the DBAPI. - col3 = row[mytable.c.mycol] # access via Column object. + .. seealso:: - ``ResultProxy`` also handles post-processing of result column - data using ``TypeEngine`` objects, which are referenced from - the originating SQL statement that produced this result set. + :ref:`coretutorial_selecting` - introductory material for accessing + :class:`.ResultProxy` and :class:`.Row` objects. """ @@ -912,7 +952,9 @@ class ResultProxy(object): ) def keys(self): - """Return the current set of string keys for rows.""" + """Return the list of string keys that would represented by each + :class:`.Row`.""" + if self._metadata: return self._metadata.keys else: @@ -1085,8 +1127,6 @@ class ResultProxy(object): :ref:`connections_toplevel` - :meth:`.ResultProxy._soft_close` - """ if not self.closed: @@ -1104,7 +1144,10 @@ class ResultProxy(object): yield row def __next__(self): - """Implement the next() protocol. + """Implement the Python next() protocol. + + This method, mirrored as both ``.next()`` and ``.__next__()``, is part + of Python's API for producing iterator-like behavior. .. versionadded:: 1.2 @@ -1358,9 +1401,7 @@ class ResultProxy(object): an empty list. After the :meth:`.ResultProxy.close` method is called, the method will raise :class:`.ResourceClosedError`. - .. versionchanged:: 1.0.0 - Added "soft close" behavior which - allows the result to be used in an "exhausted" state prior to - calling the :meth:`.ResultProxy.close` method. + :return: a list of :class:`.Row` objects """ @@ -1386,9 +1427,7 @@ class ResultProxy(object): an empty list. After the :meth:`.ResultProxy.close` method is called, the method will raise :class:`.ResourceClosedError`. - .. versionchanged:: 1.0.0 - Added "soft close" behavior which - allows the result to be used in an "exhausted" state prior to - calling the :meth:`.ResultProxy.close` method. + :return: a list of :class:`.Row` objects """ @@ -1414,9 +1453,7 @@ class ResultProxy(object): After the :meth:`.ResultProxy.close` method is called, the method will raise :class:`.ResourceClosedError`. - .. versionchanged:: 1.0.0 - Added "soft close" behavior which - allows the result to be used in an "exhausted" state prior to - calling the :meth:`.ResultProxy.close` method. + :return: a :class:`.Row` object, or None if no rows remain """ try: @@ -1434,11 +1471,11 @@ class ResultProxy(object): def first(self): """Fetch the first row and then close the result set unconditionally. - Returns None if no row is present. - After calling this method, the object is fully closed, e.g. the :meth:`.ResultProxy.close` method will have been called. + :return: a :class:`.Row` object, or None if no rows remain + """ if self._metadata is None: return self._non_result(None) @@ -1461,11 +1498,11 @@ class ResultProxy(object): def scalar(self): """Fetch the first column of the first row, and close the result set. - Returns None if no row is present. - After calling this method, the object is fully closed, e.g. the :meth:`.ResultProxy.close` method will have been called. + :return: a Python scalar value , or None if no rows remain + """ row = self.first() if row is not None: |