raise
def __init__(self, *args, **kw):
+ """Constructor for :class:`~.schema.Table`.
+
+ This method is a no-op. See the top-level
+ documentation for :class:`~.schema.Table`
+ for constructor arguments.
+
+ """
# __init__ is overridden to prevent __new__ from
# calling the superclass constructor.
- pass
def _init(self, name, metadata, *args, **kwargs):
super(Table, self).__init__(name)
self._extra_dependencies.add(table)
def append_column(self, column):
- """Append a ``Column`` to this ``Table``."""
+ """Append a :class:`~.schema.Column` to this :class:`~.schema.Table`.
+
+ The "key" of the newly added :class:`~.schema.Column`, i.e. the
+ value of its ``.key`` attribute, will then be available
+ in the ``.c`` collection of this :class:`~.schema.Table`, and the
+ column definition will be included in any CREATE TABLE, SELECT,
+ UPDATE, etc. statements generated from this :class:`~.schema.Table`
+ construct.
+
+ Note that this does **not** change the definition of the table
+ as it exists within any underlying database, assuming that
+ table has already been created in the database. Relational
+ databases support the addition of columns to existing tables
+ using the SQL ALTER command, which would need to be
+ emitted for an already-existing table that doesn't contain
+ the newly added column.
+
+ """
column._set_parent_with_dispatch(self)
def append_constraint(self, constraint):
- """Append a ``Constraint`` to this ``Table``."""
+ """Append a :class:`~.schema.Constraint` to this :class:`~.schema.Table`.
+
+ This has the effect of the constraint being included in any
+ future CREATE TABLE statement, assuming specific DDL creation
+ events have not been associated with the given :class:`~.schema.Constraint`
+ object.
+
+ Note that this does **not** produce the constraint within the
+ relational database automatically, for a table that already exists
+ in the database. To add a constraint to an
+ existing relational database table, the SQL ALTER command must
+ be used. SQLAlchemy also provides the :class:`.AddConstraint` construct
+ which can produce this SQL when invoked as an executable clause.
+
+ """
constraint._set_parent_with_dispatch(self)
"""Return a textual column clause, as would be in the columns clause of a
``SELECT`` statement.
- The object returned is an instance of
- :class:`.ColumnClause`, which represents the
- "syntactical" portion of the schema-level
- :class:`~sqlalchemy.schema.Column` object.
+ The object returned is an instance of :class:`.ColumnClause`, which
+ represents the "syntactical" portion of the schema-level
+ :class:`~sqlalchemy.schema.Column` object. It is often used directly
+ within :func:`~.expression.select` constructs or with lightweight :func:`~.expression.table`
+ constructs.
+
+ Note that the :func:`~.expression.column` function is not part of
+ the ``sqlalchemy`` namespace. It must be imported from the ``sql`` package::
+
+ from sqlalchemy.sql import table, column
- text
- the name of the column. Quoting rules will be applied to the
- clause like any other column name. For textual column
- constructs that are not to be quoted, use the
- :func:`literal_column` function.
+ :param text: the name of the column. Quoting rules will be applied
+ to the clause like any other column name. For textual column constructs
+ that are not to be quoted, use the :func:`literal_column` function.
- type\_
- an optional :class:`~sqlalchemy.types.TypeEngine` object which will
- provide result-set translation for this column.
+ :param type\_: an optional :class:`~sqlalchemy.types.TypeEngine` object
+ which will provide result-set translation for this column.
+
+ See :class:`.ColumnClause` for further examples.
"""
return ColumnClause(text, type_=type_)
(such as, '+' means string concatenation or numerical addition based on
the type).
- text
- the text of the expression; can be any SQL expression. Quoting rules
- will not be applied. To specify a column-name expression which should
- be subject to quoting rules, use the
- :func:`column` function.
+ :param text: the text of the expression; can be any SQL expression.
+ Quoting rules will not be applied. To specify a column-name expression
+ which should be subject to quoting rules, use the :func:`column`
+ function.
- type\_
- an optional :class:`~sqlalchemy.types.TypeEngine` object which will
+ :param type\_: an optional :class:`~sqlalchemy.types.TypeEngine` object which will
provide result-set translation and additional expression semantics for
this column. If left as None the type will be NullType.
return ColumnClause(text, type_=type_, is_literal=True)
def table(name, *columns):
- """Return a :class:`.TableClause` object.
-
- This is a primitive version of the :class:`~sqlalchemy.schema.Table` object,
- which is a subclass of this object.
+ """Represent a textual table clause.
+ The object returned is an instance of :class:`.TableClause`, which represents the
+ "syntactical" portion of the schema-level :class:`~.schema.Table` object.
+ It may be used to construct lightweight table constructs.
+
+ Note that the :func:`~.expression.table` function is not part of
+ the ``sqlalchemy`` namespace. It must be imported from the ``sql`` package::
+
+ from sqlalchemy.sql import table, column
+
+ :param name: Name of the table.
+
+ :param columns: A collection of :func:`~.expression.column` constructs.
+
+ See :class:`.TableClause` for further examples.
+
"""
return TableClause(name, *columns)
This includes columns associated with tables, aliases and select
statements, but also any arbitrary text. May or may not be bound
- to an underlying :class:`.Selectable`. :class:`.ColumnClause` is usually
- created publically via the :func:`column()` function or the
- :func:`literal_column()` function.
+ to an underlying :class:`.Selectable`.
+
+ :class:`.ColumnClause` is constructed by itself typically via
+ the :func:`~.expression.column` function. It may be placed directly
+ into constructs such as :func:`.select` constructs::
+
+ from sqlalchemy.sql import column, select
+
+ c1, c2 = column("c1"), column("c2")
+ s = select([c1, c2]).where(c1==5)
+
+ There is also a variant on :func:`~.expression.column` known
+ as :func:`~.expression.literal_column` - the difference is that
+ in the latter case, the string value is assumed to be an exact
+ expression, rather than a column name, so that no quoting rules
+ or similar are applied::
+
+ from sqlalchemy.sql import literal_column, select
+
+ s = select([literal_column("5 + 7")])
+
+ :class:`.ColumnClause` can also be used in a table-like
+ fashion by combining the :func:`~.expression.column` function
+ with the :func:`~.expression.table` function, to produce
+ a "lightweight" form of table metadata::
+
+ from sqlalchemy.sql import table, column
+
+ user = table("user",
+ column("id"),
+ column("name"),
+ column("description"),
+ )
+
+ The above construct can be created in an ad-hoc fashion and is
+ not associated with any :class:`.schema.MetaData`, unlike it's
+ more full fledged :class:`.schema.Table` counterpart.
- text
- the text of the element.
+ :param text: the text of the element.
- selectable
- parent selectable.
+ :param selectable: parent selectable.
- type
- ``TypeEngine`` object which can associate this :class:`.ColumnClause`
- with a type.
+ :param type: :class:`.types.TypeEngine` object which can associate
+ this :class:`.ColumnClause` with a type.
- is_literal
- if True, the :class:`.ColumnClause` is assumed to be an exact
- expression that will be delivered to the output with no quoting
- rules applied regardless of case sensitive settings. the
+ :param is_literal: if True, the :class:`.ColumnClause` is assumed to
+ be an exact expression that will be delivered to the output with no
+ quoting rules applied regardless of case sensitive settings. the
:func:`literal_column()` function is usually used to create such a
:class:`.ColumnClause`.
return c
class TableClause(_Immutable, FromClause):
- """Represents a "table" construct.
-
- Note that this represents tables only as another syntactical
- construct within SQL expressions; it does not provide schema-level
- functionality.
+ """Represents a minimal "table" construct.
+
+ The constructor for :class:`.TableClause` is the
+ :func:`~.expression.table` function. This produces
+ a lightweight table object that has only a name and a
+ collection of columns, which are typically produced
+ by the :func:`~.expression.column` function::
+
+ from sqlalchemy.sql import table, column
+
+ user = table("user",
+ column("id"),
+ column("name"),
+ column("description"),
+ )
+
+ The :class:`.TableClause` construct serves as the base for
+ the more commonly used :class:`~.schema.Table` object, providing
+ the usual set of :class:`~.expression.FromClause` services including
+ the ``.c.`` collection and statement generation methods.
+
+ It does **not** provide all the additional schema-level services
+ of :class:`~.schema.Table`, including constraints, references to other
+ tables, or support for :class:`.MetaData`-level services. It's useful
+ on its own as an ad-hoc construct used to generate quick SQL
+ statements when a more fully fledged :class:`~.schema.Table` is not on hand.
"""
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
