Method columns

lib/sqlalchemy/sql/elements.py:2401–2540

r"""Turn this :class:`_expression.AbstractTextClause` object into a :class:`_expression.TextualSelect` object that serves the same role as a SELECT statement. The :class:`_expression.TextualSelect` is part of the :class:`_expression.SelectBase` hierar

(
        self,
        *cols: _OnlyColumnArgument[Any],
        **types: _TypeEngineArgument[Any],
    )

    @util.preload_module("sqlalchemy.sql.selectable")
    def columns(
        self,
        *cols: _OnlyColumnArgument[Any],
        **types: _TypeEngineArgument[Any],
    ) -> TextualSelect:
        r"""Turn this :class:`_expression.AbstractTextClause` object into a
        :class:`_expression.TextualSelect`
        object that serves the same role as a SELECT
        statement.

        The :class:`_expression.TextualSelect` is part of the
        :class:`_expression.SelectBase`
        hierarchy and can be embedded into another statement by using the
        :meth:`_expression.TextualSelect.subquery` method to produce a
        :class:`.Subquery`
        object, which can then be SELECTed from.

        This function essentially bridges the gap between an entirely
        textual SELECT statement and the SQL expression language concept
        of a "selectable"::

            from sqlalchemy.sql import column, text

            stmt = text("SELECT id, name FROM some_table")
            stmt = stmt.columns(column("id"), column("name")).subquery("st")

            stmt = (
                select(mytable)
                .select_from(mytable.join(stmt, mytable.c.name == stmt.c.name))
                .where(stmt.c.id > 5)
            )

        Above, we pass a series of :func:`_expression.column` elements to the
        :meth:`_expression.AbstractTextClause.columns` method positionally.
        These :func:`_expression.column` elements now become first class
        elements upon the :attr:`_expression.TextualSelect.selected_columns`
        column collection, which then become part of the :attr:`.Subquery.c`
        collection after :meth:`_expression.TextualSelect.subquery` is invoked.

        The column expressions we pass to
        :meth:`_expression.AbstractTextClause.columns` may also be typed; when
        we do so, these :class:`.TypeEngine` objects become the effective
        return type of the column, so that SQLAlchemy's result-set-processing
        systems may be used on the return values. This is often needed for
        types such as date or boolean types, as well as for unicode processing
        on some dialect configurations::

            stmt = text("SELECT id, name, timestamp FROM some_table")
            stmt = stmt.columns(
                column("id", Integer),
                column("name", Unicode),
                column("timestamp", DateTime),
            )

            for id, name, timestamp in connection.execute(stmt):
                print(id, name, timestamp)

        As a shortcut to the above syntax, keyword arguments referring to