diff options
Diffstat (limited to 'lib/sqlalchemy/schema.py')
| -rw-r--r-- | lib/sqlalchemy/schema.py | 70 |
1 files changed, 55 insertions, 15 deletions
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index 1da43c6b1..8b9f1b1fd 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -89,9 +89,14 @@ class Table(SchemaItem, expression.TableClause): Column('value', String(50)) ) - The Table object constructs a unique instance of itself based on its - name within the given MetaData object. Constructor - arguments are as follows: + The :class:`.Table` object constructs a unique instance of itself based on its + name and optionl 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. + + Constructor arguments are as follows: :param name: The name of this table as represented in the database. @@ -127,6 +132,14 @@ class Table(SchemaItem, expression.TableClause): or Connection instance to be used for the table reflection. If ``None``, the underlying MetaData's bound connectable will be used. + :param extend_existing: When ``True``, indicates that if this Table is already + present in the given :class:`.MetaData`, apply further arguments within + the constructor to the existing :class:`.Table`. + + If extend_existing or keep_existing are not set, an error is + raised if additional table modifiers are specified when + the given :class:`.Table` is already present in the :class:`.MetaData`. + :param implicit_returning: True by default - indicates that RETURNING can be used by default to fetch newly inserted primary key values, for backends which support this. Note that @@ -141,6 +154,20 @@ class Table(SchemaItem, expression.TableClause): :param info: A dictionary which defaults to ``{}``. A space to store application specific data. This must be a dictionary. + :param keep_existing: When ``True``, indicates that if this Table + is already present in the given :class:`.MetaData`, ignore + further arguments within the constructor to the existing + :class:`.Table`, and return the :class:`.Table` object as + originally created. This is to allow a function that wishes + to define a new :class:`.Table` on first call, but on + subsequent calls will return the same :class:`.Table`, + without any of the declarations (particularly constraints) + being applied a second time. Also see extend_existing. + + If extend_existing or keep_existing are not set, an error is + raised if additional table modifiers are specified when + the given :class:`.Table` is already present in the :class:`.MetaData`. + :param listeners: A list of tuples of the form ``(<eventname>, <fn>)`` which will be passed to :func:`.event.listen` upon construction. This alternate hook to :func:`.event.listen` allows the establishment @@ -149,6 +176,7 @@ class Table(SchemaItem, expression.TableClause): the :meth:`.events.column_reflect` event:: def listen_for_reflect(table, column_info): + "handle the column reflection event" # ... t = Table( @@ -159,7 +187,8 @@ class Table(SchemaItem, expression.TableClause): ]) :param mustexist: When ``True``, indicates that this Table must already - be present in the given :class:`.MetaData`` collection. + be present in the given :class:`.MetaData`` collection, else + an exception is raised. :param prefixes: A list of strings to insert after CREATE in the CREATE TABLE @@ -178,12 +207,8 @@ class Table(SchemaItem, expression.TableClause): :param schema: The *schema name* for this table, which is required if the table resides in a schema other than the default selected schema for the engine's database connection. Defaults to ``None``. - - :param useexisting: When ``True``, indicates that if this Table is already - present in the given :class:`.MetaData`, apply further arguments within - the constructor to the existing :class:`.Table`. If this flag is not - set, an error is raised when the parameters of an existing - :class:`.Table` are overwritten. + + :param useexisting: Deprecated. Use extend_existing. """ @@ -200,17 +225,32 @@ class Table(SchemaItem, expression.TableClause): raise TypeError("Table() takes at least two arguments") schema = kw.get('schema', None) - useexisting = kw.pop('useexisting', False) + keep_existing = kw.pop('keep_existing', False) + extend_existing = kw.pop('extend_existing', False) + if 'useexisting' in kw: + util.warn_deprecated("useexisting is deprecated. Use extend_existing.") + if extend_existing: + raise exc.ArgumentError("useexisting is synonymous " + "with extend_existing.") + extend_existing = kw.pop('useexisting', False) + + if keep_existing and extend_existing: + raise exc.ArgumentError("keep_existing and extend_existing " + "are mutually exclusive.") + mustexist = kw.pop('mustexist', False) key = _get_table_key(name, schema) if key in metadata.tables: - if not useexisting and bool(args): + if not keep_existing and not extend_existing and bool(args): raise exc.InvalidRequestError( "Table '%s' is already defined for this MetaData " - "instance. Specify 'useexisting=True' to redefine " - "options and columns on an existing Table object." % key) + "instance. Specify 'extend_existing=True' " + "to redefine " + "options and columns on an " + "existing Table object." % key) table = metadata.tables[key] - table._init_existing(*args, **kw) + if extend_existing: + table._init_existing(*args, **kw) return table else: if mustexist: |