Commits

Mike Bayer committed 14046e7

a crapload of doc tweaks including [ticket:1666], thanks Toby !

Comments (0)

Files changed (6)

doc/build/core/expression_api.rst

 
 .. autofunction:: cast
 
-.. autofunction:: column
+.. autofunction:: sqlalchemy.sql.expression.column
 
 .. autofunction:: collate
 
 
 .. autofunction:: subquery
 
-.. autofunction:: table
+.. autofunction:: sqlalchemy.sql.expression.table
 
 .. autofunction:: text
 

doc/build/core/tutorial.rst

            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
 ==================
 

doc/build/orm/tutorial.rst

            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

lib/sqlalchemy/orm/session.py

         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

lib/sqlalchemy/schema.py

                 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)
 

lib/sqlalchemy/sql/expression.py

     """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.
-
-    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.
+    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
+
+    :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.
+
+    :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.
-
-    type\_
-      an optional :class:`~sqlalchemy.types.TypeEngine` object which will
+    :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.
+
+    :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.
-
-    text
-      the text of the element.
-
-    selectable
-      parent selectable.
-
-    type
-      ``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
+    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.
+
+    :param text: the text of the element.
+
+    :param selectable: parent selectable.
+
+    :param type: :class:`.types.TypeEngine` object which can associate 
+      this :class:`.ColumnClause` with a type.
+
+    :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.
 
     """