From: Federico Caselli Date: Sat, 26 Sep 2020 14:02:05 +0000 (+0200) Subject: Improve some documentations X-Git-Tag: rel_1_4_0b1~58^2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=50fb226903ff8b1af62a787a100f03928d1c4e06;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Improve some documentations Change-Id: Ibcb0da3166b94aa58fa92d544c3e5cf75844546e --- diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index 17dd85abd7..fe49036502 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -1290,8 +1290,9 @@ agnostic of the ORM**. To achieve this, the vast majority of logic from ORM-specific compiler plugins receive the :class:`_sql.Select` construct and interpret its contents in terms of an ORM-style query, before passing off to the core-level compiler in order to -create a SQL string. With the advent of the new `SQL compilation caching -system `, the majority of this ORM logic is also cached. +create a SQL string. With the advent of the new +`SQL compilation caching system `, +the majority of this ORM logic is also cached. .. seealso:: @@ -1654,7 +1655,7 @@ As is the case described at :ref:`migration_20_query_from_self`, the subquery = session.query(User).filter(User.id == 5).subquery() - ua = aliased(user, subquery) + ua = aliased(User, subquery) user = session.query(ua).first() @@ -1664,7 +1665,7 @@ Using :term:`2.0 style`:: subquery = select(User).where(User.id == 5).subquery() - ua = aliased(user, subquery) + ua = aliased(User, subquery) user = session.execute(select(ua)).scalars().first() @@ -1710,7 +1711,7 @@ while still maintaining explicitness:: # statement will raise if unique() is not used, due to joinedload() # of a collection. in all other cases, unique() is not needed - rows = session.invoke(stmt).unique().execute().all() + rows = session.execute(stmt).unique().execute().all() **Discussion** diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index 8b9b413c46..cb452ac737 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -677,7 +677,30 @@ class ResultInternal(InPlaceGenerative): return uniques, strategy -class Result(ResultInternal): +class _WithKeys(object): + # used mainly to share documentation on the keys method. + # py2k does not allow overriding the __doc__ attribute. + def keys(self): + """Return an iterable view which yields the string keys that would + be represented by each :class:`.Row`. + + The keys can represent the labels of the columns returned by a core + statement or the names of the orm classes returned by an orm + execution. + + The view also can be tested for key containment using the Python + ``in`` operator, which will test both for the string keys represented + in the view, as well as for alternate keys such as column objects. + + .. versionchanged:: 1.4 a key view object is returned rather than a + plain list. + + + """ + return self._metadata.keys + + +class Result(_WithKeys, ResultInternal): """Represent a set of database results. .. versionadded:: 1.4 The :class:`.Result` object provides a completely @@ -705,21 +728,6 @@ class Result(ResultInternal): def _soft_close(self, hard=False): raise NotImplementedError() - def keys(self): - """Return an iterable view which yields the string keys that would - be represented by each :class:`.Row`. - - The view also can be tested for key containment using the Python - ``in`` operator, which will test both for the string keys represented - in the view, as well as for alternate keys such as column objects. - - .. versionchanged:: 1.4 a key view object is returned rather than a - plain list. - - - """ - return self._metadata.keys - @_generative def yield_per(self, num): """Configure the row-fetching strategy to fetch num rows at a time. @@ -949,7 +957,7 @@ class Result(ResultInternal): :paramref:`.Connection.execution_options.stream_results` execution option is used indicating that the driver should not pre-buffer results, if possible. Not all drivers support this option and - the option is silently ignored for those who do. + the option is silently ignored for those who do not. .. versionadded:: 1.4 @@ -1361,7 +1369,7 @@ class ScalarResult(FilterResult): return self._only_one_row(True, True, False) -class MappingResult(FilterResult): +class MappingResult(_WithKeys, FilterResult): """A wrapper for a :class:`_engine.Result` that returns dictionary values rather than :class:`_engine.Row` values. @@ -1381,21 +1389,6 @@ class MappingResult(FilterResult): if result._source_supports_scalars: self._metadata = self._metadata._reduce([0]) - def keys(self): - """Return an iterable view which yields the string keys that would - be represented by each :class:`.Row`. - - The view also can be tested for key containment using the Python - ``in`` operator, which will test both for the string keys represented - in the view, as well as for alternate keys such as column objects. - - .. versionchanged:: 1.4 a key view object is returned rather than a - plain list. - - - """ - return self._metadata.keys - def unique(self, strategy=None): # type: () -> MappingResult """Apply unique filtering to the objects returned by this diff --git a/lib/sqlalchemy/engine/row.py b/lib/sqlalchemy/engine/row.py index fe6831e307..288f08e295 100644 --- a/lib/sqlalchemy/engine/row.py +++ b/lib/sqlalchemy/engine/row.py @@ -276,6 +276,10 @@ class Row(BaseRow, collections_abc.Sequence): """Return the list of keys as strings represented by this :class:`.Row`. + The keys can represent the labels of the columns returned by a core + statement or the names of the orm classes returned by an orm + execution. + This method is analogous to the Python dictionary ``.keys()`` method, except that it returns a list, not an iterator. @@ -293,6 +297,10 @@ class Row(BaseRow, collections_abc.Sequence): """Return a tuple of string keys as represented by this :class:`.Row`. + The keys can represent the labels of the columns returned by a core + statement or the names of the orm classes returned by an orm + execution. + This attribute is analogous to the Python named tuple ``._fields`` attribute. diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 0e7fd2fc31..0d131c0864 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -1019,7 +1019,6 @@ class Query( """ self.load_options += {"_invoke_all_eagers": value} - # TODO: removed in 2.0, use with_parent standalone in filter @util.deprecated_20( ":meth:`_orm.Query.with_parent`", alternative="Use the :func:`_orm.with_parent` standalone construct.", diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index e96da0e249..50d7d1f5b8 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -215,7 +215,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause): The autoload parameter is deprecated and will be removed in version 2.0. Please use the - :paramref:`_schema.Table`autoload_with` parameter, passing an + :paramref:`_schema.Table.autoload_with` parameter, passing an engine or connection. .. seealso::