From: Mike Bayer Date: Sun, 7 Aug 2011 23:44:39 +0000 (-0400) Subject: some core cross linkage X-Git-Tag: rel_0_7_3~78 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2105032261fcaadd8f30c208e4def95a593bc4be;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git some core cross linkage --- diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst index 1ddf494bb1..78fa6ee9c7 100644 --- a/doc/build/core/schema.rst +++ b/doc/build/core/schema.rst @@ -148,9 +148,6 @@ table include:: # get the table related by a foreign key list(employees.c.employee_dept.foreign_keys)[0].column.table -.. _metadata_binding: - - Creating and Dropping Database Tables ------------------------------------- @@ -253,6 +250,7 @@ To enable the "check first for the table existing" logic, add the employees.create(engine, checkfirst=True) employees.drop(engine, checkfirst=False) +.. _metadata_binding: Binding MetaData to an Engine or Connection -------------------------------------------- diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index dbac1c2fd6..c615167d6d 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -188,6 +188,8 @@ each table first before creating, so it's safe to call multiple times: TABLE statements on a particular set of backends with more stringent requirements. +.. _coretutorial_insert_expressions: + Insert Expressions ================== @@ -385,6 +387,8 @@ attached: Detailed examples of connectionless and implicit execution are available in the "Engines" chapter: :ref:`dbengine_implicit`. +.. _coretutorial_selecting: + Selecting ========== diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index 25c7e30a20..7b5b3ab70c 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -92,12 +92,16 @@ class Table(SchemaItem, expression.TableClause): ) The :class:`.Table` object constructs a unique instance of itself based on its - name and optionl schema name within the given :class:`.MetaData` object. + name and optional schema name within the given :class:`.MetaData` object. Calling the :class:`.Table` constructor with the same name and same :class:`.MetaData` argument a second time will return the *same* :class:`.Table` object - in this way the :class:`.Table` constructor acts as a registry function. + See also: + + :ref:`metadata_describing` - Introduction to database metadata + Constructor arguments are as follows: :param name: The name of this table as represented in the database. @@ -2180,14 +2184,15 @@ class Index(ColumnCollectionMixin, SchemaItem): (self.unique and ', unique=True') or '') class MetaData(SchemaItem): - """A collection of Tables and their associated schema constructs. + """A collection of :class:`.Table` objects and their associated schema constructs. - Holds a collection of Tables and an optional binding to an ``Engine`` or - ``Connection``. If bound, the :class:`~sqlalchemy.schema.Table` objects + Holds a collection of :class:`.Table` objects as well as + an optional binding to an :class:`.Engine` or + :class:`.Connection`. If bound, the :class:`.Table` objects in the collection and their columns may participate in implicit SQL execution. - The `Table` objects themselves are stored in the `metadata.tables` + The :class:`.Table` objects themselves are stored in the ``metadata.tables`` dictionary. The ``bind`` property may be assigned to dynamically. A common pattern is @@ -2202,6 +2207,12 @@ class MetaData(SchemaItem): MetaData is a thread-safe object after tables have been explicitly defined or loaded via reflection. + + See also: + + :ref:`metadata_describing` - Introduction to database metadata + + :ref:`metadata_binding` - Information on binding connectables to :class:`.MetaData` .. index:: single: thread safety; MetaData diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py index fa0586e2d4..dc87143714 100644 --- a/lib/sqlalchemy/sql/expression.py +++ b/lib/sqlalchemy/sql/expression.py @@ -170,6 +170,10 @@ def select(columns=None, whereclause=None, from_obj=[], **kwargs): string arguments, which will be converted as appropriate into either :func:`text()` or :func:`literal_column()` constructs. + See also: + + :ref:`coretutorial_selecting` - Core Tutorial description of :func:`.select`. + :param columns: A list of :class:`.ClauseElement` objects, typically :class:`.ColumnElement` objects or subclasses, which will form the @@ -309,8 +313,12 @@ def subquery(alias, *args, **kwargs): def insert(table, values=None, inline=False, **kwargs): """Return an :class:`.Insert` clause element. - Similar functionality is available via the :func:`insert()` method on - :class:`~sqlalchemy.schema.Table`. + Similar functionality is available via the :meth:`~.schema.Table.insert` method on + :class:`~.schema.Table`. + + See also: + + :ref:`coretutorial_insert_expressions` - Core Tutorial description of the :func:`.insert` construct. :param table: The table to be inserted into. @@ -4063,7 +4071,7 @@ class _SelectBase(Executable, FromClause): """return a 'scalar' representation of this selectable, embedded as a subquery with a label. - See also ``as_scalar()``. + See also :meth:`~._SelectBase.as_scalar`. """ return self.as_scalar().label(name) @@ -4282,8 +4290,11 @@ class CompoundSelect(_SelectBase): class Select(_SelectBase): """Represents a ``SELECT`` statement. - Select statements support appendable clauses, as well as the - ability to execute themselves and return a result set. + See also: + + :func:`~.expression.select` - the function which creates a :class:`.Select` object. + + :ref:`coretutorial_selecting` - Core Tutorial description of :func:`.select`. """ @@ -4861,13 +4872,21 @@ class ValuesBase(UpdateBase): """specify the VALUES clause for an INSERT statement, or the SET clause for an UPDATE. - \**kwargs - key= arguments + :param \**kwargs: key value pairs representing the string key + of a :class:`.Column` mapped to the value to be rendered into the + VALUES or SET clause:: - \*args - A single dictionary can be sent as the first positional - argument. This allows non-string based keys, such as Column - objects, to be used. + users.insert().values(name="some name") + + users.update().where(users.c.id==5).values(name="some name") + + :param \*args: A single dictionary can be sent as the first positional + argument. This allows non-string based keys, such as Column + objects, to be used:: + + users.insert().values({users.c.name : "some name"}) + + users.update().where(users.c.id==5).values({users.c.name : "some name"}) """ if args: @@ -4886,7 +4905,11 @@ class ValuesBase(UpdateBase): class Insert(ValuesBase): """Represent an INSERT construct. - The :class:`.Insert` object is created using the :func:`insert()` function. + The :class:`.Insert` object is created using the :func:`~.expression.insert()` function. + + See also: + + :ref:`coretutorial_insert_expressions` """ __visit_name__ = 'insert'