From: Mike Bayer Date: Sat, 16 Apr 2011 16:04:54 +0000 (-0400) Subject: a crapload of doc tweaks including [ticket:1666], thanks Toby ! X-Git-Tag: rel_0_7b4~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4f6f0edd7843939c055bcfb7c2ff47ae7eec58f8;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git a crapload of doc tweaks including [ticket:1666], thanks Toby ! --- diff --git a/doc/build/core/expression_api.rst b/doc/build/core/expression_api.rst index decd2ba60b..48dc503944 100644 --- a/doc/build/core/expression_api.rst +++ b/doc/build/core/expression_api.rst @@ -27,7 +27,7 @@ The expression package uses functions to construct SQL expressions. The return .. autofunction:: cast -.. autofunction:: column +.. autofunction:: sqlalchemy.sql.expression.column .. autofunction:: collate @@ -77,7 +77,7 @@ The expression package uses functions to construct SQL expressions. The return .. autofunction:: subquery -.. autofunction:: table +.. autofunction:: sqlalchemy.sql.expression.table .. autofunction:: text diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index b52990b6db..ba1491c9eb 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -156,6 +156,12 @@ Next, to tell the :class:`~sqlalchemy.schema.MetaData` we'd actually like to cre Column('password', String(12)) ) + We include this more verbose :class:`~.schema.Table` construct separately + to highlight the difference between a minimal construct geared primarily + towards in-Python usage only, versus one that will be used to emit CREATE + TABLE statements on a particular set of backends with more stringent + requirements. + Insert Expressions ================== diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 2dedf70496..f77225c400 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -122,6 +122,12 @@ Next, we can issue CREATE TABLE statements derived from our table metadata, by c Column('password', String(12)) ) + We include this more verbose :class:`~.schema.Table` construct separately + to highlight the difference between a minimal construct geared primarily + towards in-Python usage only, versus one that will be used to emit CREATE + TABLE statements on a particular set of backends with more stringent + requirements. + Define a Python Class to be Mapped =================================== While the :class:`~sqlalchemy.schema.Table` object defines information about diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index baf3b6d428..8f8770a3b9 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -1435,9 +1435,10 @@ class Session(object): solver.. Database operations will be issued in the current transactional - context and do not affect the state of the transaction. You may - flush() as often as you like within a transaction to move changes from - Python to the database's transaction buffer. + context and do not affect the state of the transaction, unless an + error occurs, in which case the entire transaction is rolled back. + You may flush() as often as you like within a transaction to move + changes from Python to the database's transaction buffer. For ``autocommit`` Sessions with no active manual transaction, flush() will create a transaction on the fly that surrounds the entire set of diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index 8b9f1b1fd4..af2c9f7721 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -268,9 +268,15 @@ class Table(SchemaItem, expression.TableClause): 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) @@ -425,12 +431,43 @@ class Table(SchemaItem, expression.TableClause): 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) diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py index c9647e1bd9..b7e543850d 100644 --- a/lib/sqlalchemy/sql/expression.py +++ b/lib/sqlalchemy/sql/expression.py @@ -793,20 +793,25 @@ def column(text, type_=None): """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_) @@ -821,14 +826,12 @@ def literal_column(text, type_=None): (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. @@ -836,11 +839,23 @@ def literal_column(text, type_=None): 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) @@ -3786,24 +3801,54 @@ class ColumnClause(_Immutable, ColumnElement): 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`. @@ -3891,11 +3936,32 @@ class ColumnClause(_Immutable, ColumnElement): 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. """