From: Mike Bayer Date: Sun, 7 Dec 2008 06:30:00 +0000 (+0000) Subject: - re-documented Table and Column constructors, fixed case sensitivity description... X-Git-Tag: rel_0_5_0~135 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ee7fcf311068ca233de43eaec241ccc965c626a2;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - re-documented Table and Column constructors, fixed case sensitivity description [ticket:1231] - turned on autoclass_content="both". Need to specify __init__ docstring with a newline after the """. - other docs --- diff --git a/doc/build/conf.py b/doc/build/conf.py index 320b5e604b..da6d8d6634 100644 --- a/doc/build/conf.py +++ b/doc/build/conf.py @@ -157,6 +157,7 @@ html_use_modindex = False # Output file base name for HTML help builder. htmlhelp_basename = 'FooBardoc' +autoclass_content = 'both' # Options for LaTeX output # ------------------------ diff --git a/doc/build/index.rst b/doc/build/index.rst index 031d579c61..ed33dfbe59 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -21,4 +21,3 @@ Indices and tables * :ref:`genindex` * :ref:`search` - diff --git a/doc/build/reference/sqlalchemy/schema.rst b/doc/build/reference/sqlalchemy/schema.rst index df9ac522e6..bc3260be3e 100644 --- a/doc/build/reference/sqlalchemy/schema.rst +++ b/doc/build/reference/sqlalchemy/schema.rst @@ -5,4 +5,4 @@ Database Schema :members: :undoc-members: :inherited-members: - :show-inheritance: \ No newline at end of file + :show-inheritance: diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 97624280e6..3a0c1af182 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -10,8 +10,13 @@ Defines the basic components used to interface DB-API modules with higher-level statement-construction, connection-management, execution and result contexts. + """ +__all__ = ['BufferedColumnResultProxy', 'BufferedColumnRow', 'BufferedRowResultProxy', 'Compiled', 'Connectable', + 'Connection', 'DefaultRunner', 'Dialect', 'Engine', 'ExecutionContext', 'NestedTransaction', 'ResultProxy', + 'RootTransaction', 'RowProxy', 'SchemaIterator', 'StringIO', 'Transaction', 'TwoPhaseTransaction', 'connection_memoize'] + import inspect, StringIO from sqlalchemy import exc, schema, util, types, log from sqlalchemy.sql import expression @@ -467,7 +472,12 @@ class Compiled(object): class Connectable(object): - """Interface for an object that can provide an Engine and a Connection object which correponds to that Engine.""" + """Interface for an object which supports execution of SQL constructs. + + The two implementations of ``Connectable`` are :class:`Connection` and + :class:`Engine`. + + """ def contextual_connect(self): """Return a Connection object which may be part of an ongoing context.""" diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index 481a462ae5..9664f60564 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -37,7 +37,7 @@ __all__ = ['SchemaItem', 'Table', 'Column', 'ForeignKey', 'Sequence', 'Index', 'ForeignKeyConstraint', 'PrimaryKeyConstraint', 'CheckConstraint', 'UniqueConstraint', 'DefaultGenerator', 'Constraint', 'MetaData', 'ThreadLocalMetaData', 'SchemaVisitor', 'PassiveDefault', - 'DefaulClause', 'FetchedValue', 'ColumnDefault', 'DDL'] + 'DefaultClause', 'FetchedValue', 'ColumnDefault', 'DDL'] __all__.sort() class SchemaItem(visitors.Visitable): @@ -117,88 +117,85 @@ class _TableSingleton(visitors.VisitableType): class Table(SchemaItem, expression.TableClause): - """Represent a relational database table.""" + """Represent a table in a database.""" __metaclass__ = _TableSingleton ddl_events = ('before-create', 'after-create', 'before-drop', 'after-drop') def __init__(self, name, metadata, *args, **kwargs): - """Construct a Table. - - Table objects can be constructed directly. Arguments are: - - name - The name of this table, exactly as it appears, or will appear, in - the database. - - This property, along with the *schema*, indicates the *singleton - identity* of this table. - - Further tables constructed with the same name/schema combination - will return the same Table instance. - - \*args - Should contain a listing of the Column objects for this table. - - \**kwargs - kwargs include: - - 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``. - - autoload - Defaults to False: the Columns for this table should be reflected + """ + Construct a Table. + + :param name: The name of this table as represented in the database. + + This property, along with the *schema*, indicates the *singleton + identity* of this table in relation to its parent :class:`MetaData`. + Additional calls to :class:`Table` with the same name, metadata, + and schema name will return the same :class:`Table` object. + + Names which contain no upper case characters + will be treated as case insensitive names, and will not be quoted + unless they are a reserved word. Names with any number of upper + case characters will be quoted and sent exactly. Note that this + behavior applies even for databases which standardize upper + case names as case insensitive such as Oracle. + + :param metadata: a :class:`MetaData` object which will contain this + table. The metadata is used as a point of association of this table + with other tables which are referenced via foreign key. It also + may be used to associate this table with a particular + :class:`~sqlalchemy.engine.base.Connectable`. + + :param \*args: Additional positional arguments are used primarily + to add the list of :class:`Column` objects contained within this table. + Similar to the style of a CREATE TABLE statement, other :class:`SchemaItem` + constructs may be added here, including :class:`PrimaryKeyConstraint`, + and :class:`ForeignKeyConstraint`. + + :param autoload: Defaults to False: the Columns for this table should be reflected from the database. Usually there will be no Column objects in the constructor if this property is set. - autoload_with - if autoload==True, this is an optional Engine or Connection + :param autoload_with: If autoload==True, this is an optional Engine or Connection instance to be used for the table reflection. If ``None``, the underlying MetaData's bound connectable will be used. - include_columns - A list of strings indicating a subset of columns to be loaded via + :param include_columns: A list of strings indicating a subset of columns to be loaded via the ``autoload`` operation; table columns who aren't present in this list will not be represented on the resulting ``Table`` object. Defaults to ``None`` which indicates all columns should be reflected. - info - Defaults to {}: A space to store application specific data; this - must be a dictionary. + :param info: A dictionary which defaults to ``{}``. A space to store application + specific data. This must be a dictionary. - mustexist - Defaults to False: indicates that this Table must already have - been defined elsewhere in the application, else an exception is - raised. + :param mustexist: When ``True``, indicates that this Table must already + be present in the given :class:`MetaData`` collection. - prefixes + :param prefixes: A list of strings to insert after CREATE in the CREATE TABLE statement. They will be separated by spaces. - useexisting - Defaults to False: indicates that if this Table was already - defined elsewhere in the application, disregard the rest of the - constructor arguments. + :param quote: Force quoting of this table's name on or off, corresponding + to ``True`` or ``False``. When left at its default of ``None``, + the column identifier will be quoted according to whether the name is + case sensitive (identifiers with at least one upper case character are + treated as case sensitive), or if it's a reserved word. This flag + is only needed to force quoting of a reserved word which is not known + by the SQLAlchemy dialect. - owner - Deprecated; this is an oracle-only argument - "schema" should - be used in its place. + :param quote_schema: same as 'quote' but applies to the schema identifier. - quote - Force quoting of the identifier on or off, based on `True` or - `False`. Defaults to `None`. This flag is rarely needed, - as quoting is normally applied - automatically for known reserved words, as well as for - "case sensitive" identifiers. An identifier is "case sensitive" - if it contains non-lowercase letters, otherwise it's - considered to be "case insensitive". + :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``. - quote_schema - same as 'quote' but applies to the schema identifier. + :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. """ super(Table, self).__init__(name) @@ -409,127 +406,134 @@ class Table(SchemaItem, expression.TableClause): return Table(self.name, metadata, schema=schema, *args) class Column(SchemaItem, expression.ColumnClause): - """Represent a column in a database table. - - This is a subclass of ``expression.ColumnClause`` and represents an actual - existing table in the database, in a similar fashion as - ``TableClause``/``Table``. - """ + """Represents a column in a database table.""" def __init__(self, *args, **kwargs): - """Construct a new ``Column`` object. - - Arguments are: + """ + Construct a new ``Column`` object. + + :param name: The name of this column as represented in the database. + This argument may be the first positional argument, or specified + via keyword. + + Names which contain no upper case characters + will be treated as case insensitive names, and will not be quoted + unless they are a reserved word. Names with any number of upper + case characters will be quoted and sent exactly. Note that this + behavior applies even for databases which standardize upper + case names as case insensitive such as Oracle. + + The name field may be omitted at construction time and applied + later, at any time before the Column is associated with a + :class:`Table`. This is to support convenient + usage within the :mod:`~sqlalchemy.ext.declarative` extension. + + :param type\_: The column's type, indicated using an instance which + subclasses :class:`~sqlalchemy.types.AbstractType`. If no arguments + are required for the type, the class of the type can be sent + as well, e.g.:: + + # use a type with arguments + Column('data', String(50)) + + # use no arguments + Column('level', Integer) + + The ``type`` argument may be the second positional argument + or specified by keyword. - name - The name of this column. This should be the identical name as it - appears, or will appear, in the database. Name may be omitted at - construction time but must be assigned before adding a Column - instance to a Table. - - type\_ - The ``TypeEngine`` for this column. This can be any subclass of - ``types.AbstractType``, including the database-agnostic types - defined in the types module, database-specific types defined within - specific database modules, or user-defined types. If the column - contains a ForeignKey, the type can also be None, in which case the + If this column also contains a :class:`ForeignKey`, + the type argument may be left as ``None`` in which case the type assigned will be that of the referenced column. - \*args - Constraint, ForeignKey, ColumnDefault and Sequence objects should be - added as list values. - - \**kwargs - Keyword arguments include: - - key - Defaults to the column name: a Python-only *alias name* for this - column. - - The column will then be identified everywhere in an application, - including the column list on its Table, by this key, and not the - given name. Generated SQL, however, will still reference the - column by its actual name. - - primary_key - Defaults to False: True if this column is a primary key column. - Multiple columns can have this flag set to specify composite - primary keys. As an alternative, the primary key of a Table can - be specified via an explicit ``PrimaryKeyConstraint`` instance - appended to the Table's list of objects. - - nullable - Defaults to True : True if this column should allow nulls. True is - the default unless this column is a primary key column. - - default - Defaults to None: a scalar, Python callable, or ``ClauseElement`` - representing the *default value* for this column, which will be - invoked upon insert if this column is not present in the insert - list or is given a value of None. The default expression will be - converted into a ``ColumnDefault`` object upon initialization. - - server_default - Defaults to None: A FetchedValue instance, str, Unicode or - sqlalchemy.text() string representing the DDL DEFAULT value for - the column. - - String types will be emitted as-is, surrounded by single quotes:: + :param \*args: Additional positional arguments include various + :class:`SchemaItem` derived constructs which will be applied + as options to the column. These include instances of + :class:`Constraint`, :class:`ForeignKey`, :class:`ColumnDefault`, + and :class:`Sequence`. In some cases an equivalent keyword + argument is available such as ``server_default``, ``default`` + and ``unique``. + + :param autoincrement: This flag may be set to ``False`` to disable + SQLAlchemy indicating at the DDL level that an integer primary + key column should have autoincrementing behavior. This + is an oft misunderstood flag and has no effect whatsoever unless + all of the following conditions are met: + + * The column is of the :class:`~sqlalchemy.types.Integer` datatype. + * The column has the ``primary_key`` flag set, or is otherwise + a member of a :class:`PrimaryKeyConstraint` on this table. + * a CREATE TABLE statement is being issued via :meth:`create()` + or :meth:`create_all()`. The flag has no relevance at any + other time. + * The database supports autoincrementing behavior, such as + Postgres or MySQL, and this behavior can be disabled (which does + not include SQLite). + + :param default: A scalar, Python callable, or :class:`~sqlalchemy.sql.expression.ClauseElement` + representing the *default value* for this column, which will be + invoked upon insert if this column is not present in the insert + list or is given a value of None. Contrast this argument + to ``server_default`` which creates a default generator on the + database side. + + :param key: An optional string identifier which will identify this ``Column`` + object on the :class:`Table`. When a key is provided, this is the + only identifier referencing the ``Column`` within the application, + including ORM attribute mapping; the ``name`` field is used only + when rendering SQL. + + :param index: When ``True``, indicates that the column is indexed. + This is a shortcut for using a :class:`Index` construct on the table. + To specify indexes with explicit names or indexes that contain multiple + columns, use the :class:`Index` construct instead. + + :param info: A dictionary which defaults to ``{}``. A space to store application + specific data. This must be a dictionary. + + :param nullable: If set to the default of ``True``, indicates the column + will be rendered as allowing NULL, else it's rendered as NOT NULL. + This parameter is only used when issuing CREATE TABLE statements. + + :param primary_key: If ``True``, marks this column as a primary key + column. Multiple columns can have this flag set to specify composite + primary keys. As an alternative, the primary key of a :class:`Table` can + be specified via an explicit :class:`PrimaryKeyConstraint` object. + + :param server_default: A :class:`FetchedValue` instance, str, Unicode or + :func:`~sqlalchemy.sql.expression.text` construct representing + the DDL DEFAULT value for the column. + + String types will be emitted as-is, surrounded by single quotes:: Column('x', Text, server_default="val") x TEXT DEFAULT 'val' - A sqlalchemy.text() expression will be rendered as-is, without - quotes:: + A :func:`~sqlalchemy.sql.expression.text` expression will be + rendered as-is, without quotes:: Column('y', DateTime, server_default=text('NOW()'))0 y DATETIME DEFAULT NOW() - Strings and text() will be converted into a ``DefaultClause`` - object upon initialization. - - index - Defaults to False: indicates that this column is indexed. The name - of the index is autogenerated. to specify indexes with explicit - names or indexes that contain multiple columns, use the ``Index`` - construct instead. + Strings and text() will be converted into a :class:`DefaultClause` + object upon initialization. - info - Defaults to {}: A space to store application specific data; this - must be a dictionary. + :param quote: Force quoting of this column's name on or off, corresponding + to ``True`` or ``False``. When left at its default of ``None``, + the column identifier will be quoted according to whether the name is + case sensitive (identifiers with at least one upper case character are + treated as case sensitive), or if it's a reserved word. This flag + is only needed to force quoting of a reserved word which is not known + by the SQLAlchemy dialect. - unique - Defaults to False: indicates that this column contains a unique - constraint, or if `index` is True as well, indicates that the - Index should be created with the unique flag. To specify multiple + :param unique: When ``True``, indicates that this column contains a unique + constraint, or if ``index`` is ``True`` as well, indicates that the + :class:`Index` should be created with the unique flag. To specify multiple columns in the constraint/index or to specify an explicit name, - use the ``UniqueConstraint`` or ``Index`` constructs instead. - - autoincrement - Defaults to True: indicates that integer-based primary key columns - should have autoincrementing behavior, if supported by the - underlying database. This will affect ``CREATE TABLE`` statements - such that they will use the databases *auto-incrementing* keyword - (such as ``SERIAL`` for Postgres, ``AUTO_INCREMENT`` for Mysql) - and will also affect the behavior of some dialects during - ``INSERT`` statement execution such that they will assume primary - key values are created in this manner. If a ``Column`` has an - explicit ``ColumnDefault`` object (such as via the `default` - keyword, or a ``Sequence`` or ``DefaultClause``), then the value - of `autoincrement` is ignored and is assumed to be False. - `autoincrement` value is only significant for a column with a type - or subtype of Integer. - - quote - Force quoting of the identifier on or off, based on `True` or - `False`. Defaults to `None`. This flag is rarely needed, - as quoting is normally applied - automatically for known reserved words, as well as for - "case sensitive" identifiers. An identifier is "case sensitive" - if it contains non-lowercase letters, otherwise it's - considered to be "case insensitive". + use the :class:`UniqueConstraint` or :class:`Index` constructs explicitly. + """ name = kwargs.pop('name', None) @@ -1572,7 +1576,7 @@ class MetaData(SchemaItem): in this ``MetaData`` no longer exists in the database. bind - A ``Connectable`` used to access the database; if None, uses the + A :class:`~sqlalchemy.engine.base.Connectable` used to access the database; if None, uses the existing bind on this ``MetaData``, if any. schema @@ -1670,7 +1674,7 @@ class MetaData(SchemaItem): present in the target database. bind - A ``Connectable`` used to access the database; if None, uses the + A :class:`~sqlalchemy.engine.base.Connectable` used to access the database; if None, uses the existing bind on this ``MetaData``, if any. tables @@ -1697,7 +1701,7 @@ class MetaData(SchemaItem): the target database. bind - A ``Connectable`` used to access the database; if None, uses + A :class:`~sqlalchemy.engine.base.Connectable` used to access the database; if None, uses the existing bind on this ``MetaData``, if any. tables @@ -1877,8 +1881,9 @@ class DDL(object): available for use in string substitutions on the DDL statement. bind - Optional. A ``Connectable``, used by default when ``execute()`` + Optional. A :class:`~sqlalchemy.engine.base.Connectable`, used by default when ``execute()`` is invoked without a bind argument. + """ if not isinstance(statement, basestring): @@ -1900,13 +1905,13 @@ class DDL(object): """Execute this DDL immediately. Executes the DDL statement in isolation using the supplied - ``Connectable`` or ``Connectable`` assigned to the ``.bind`` property, + :class:`~sqlalchemy.engine.base.Connectable` or :class:`~sqlalchemy.engine.base.Connectable` assigned to the ``.bind`` property, if not supplied. If the DDL has a conditional ``on`` criteria, it will be invoked with None as the event. bind Optional, an ``Engine`` or ``Connection``. If not supplied, a - valid ``Connectable`` must be present in the ``.bind`` property. + valid :class:`~sqlalchemy.engine.base.Connectable` must be present in the ``.bind`` property. schema_item Optional, defaults to None. Will be passed to the ``on`` callable