diff options
| author | Mike Bayer <mike_mp@zzzcomputing.com> | 2008-12-06 16:59:48 +0000 |
|---|---|---|
| committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2008-12-06 16:59:48 +0000 |
| commit | 1c329624a5e4b9122b047c93cd64fbeb217d8682 (patch) | |
| tree | df09d6ddd169bd37c3c105273c057dba079279c5 /lib/sqlalchemy | |
| parent | 6eca02a31f9fdbc7d039a89f6f8ea212fe5121d9 (diff) | |
| download | sqlalchemy-1c329624a5e4b9122b047c93cd64fbeb217d8682.tar.gz | |
- merged -r5338:5429 of sphinx branch.
- Documentation has been converted to Sphinx.
In particular, the generated API documentation
has been constructed into a full blown
"API Reference" section which organizes
editorial documentation combined with
generated docstrings. Cross linking between
sections and API docs are vastly improved,
a javascript-powered search feature is
provided, and a full index of all
classes, functions and members is provided.
Diffstat (limited to 'lib/sqlalchemy')
| -rw-r--r-- | lib/sqlalchemy/databases/mysql.py | 796 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/__init__.py | 162 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/base.py | 39 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/strategies.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/threadlocal.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/url.py | 55 | ||||
| -rw-r--r-- | lib/sqlalchemy/exc.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/ext/declarative.py | 4 | ||||
| -rw-r--r-- | lib/sqlalchemy/ext/orderinglist.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/interfaces.py | 10 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/__init__.py | 520 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/interfaces.py | 11 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/mapper.py | 12 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/query.py | 44 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/session.py | 14 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/util.py | 13 | ||||
| -rw-r--r-- | lib/sqlalchemy/pool.py | 279 | ||||
| -rw-r--r-- | lib/sqlalchemy/schema.py | 18 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/compiler.py | 8 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/expression.py | 146 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/functions.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/types.py | 374 |
22 files changed, 1481 insertions, 1034 deletions
diff --git a/lib/sqlalchemy/databases/mysql.py b/lib/sqlalchemy/databases/mysql.py index 3dbb1797d..6a01b789b 100644 --- a/lib/sqlalchemy/databases/mysql.py +++ b/lib/sqlalchemy/databases/mysql.py @@ -1,3 +1,4 @@ +# -*- fill-column: 78 -*- # mysql.py # Copyright (C) 2005, 2006, 2007, 2008 Michael Bayer mike_mp@zzzcomputing.com # @@ -6,13 +7,41 @@ """Support for the MySQL database. +Overview +-------- + +For normal SQLAlchemy usage, importing this module is unnecessary. It will be +loaded on-demand when a MySQL connection is needed. The generic column types +like :class:`~sqlalchemy.String` and :class:`~sqlalchemy.Integer` will +automatically be adapted to the optimal matching MySQL column type. + +But if you would like to use one of the MySQL-specific or enhanced column +types when creating tables with your :class:`~sqlalchemy.Table` definitions, +then you will need to import them from this module:: + + from sqlalchemy.databases import mysql + + Table('mytable', metadata, + Column('id', Integer, primary_key=True), + Column('ittybittyblob', mysql.MSTinyBlob), + Column('biggy', mysql.MSBigInteger(unsigned=True))) + +All standard MySQL column types are supported. The OpenGIS types are +available for use via table reflection but have no special support or mapping +to Python classes. If you're using these types and have opinions about how +OpenGIS can be smartly integrated into SQLAlchemy please join the mailing +list! + +Supported Versions and Features +------------------------------- + SQLAlchemy supports 6 major MySQL versions: 3.23, 4.0, 4.1, 5.0, 5.1 and 6.0, -with capablities increasing with more modern servers. +with capabilities increasing with more modern servers. Versions 4.1 and higher support the basic SQL functionality that SQLAlchemy -uses in the ORM and SQL expressions. These versions pass the applicable -tests in the suite 100%. No heroic measures are taken to work around major -missing SQL features- if your server version does not support sub-selects, for +uses in the ORM and SQL expressions. These versions pass the applicable tests +in the suite 100%. No heroic measures are taken to work around major missing +SQL features- if your server version does not support sub-selects, for example, they won't work in SQLAlchemy either. Currently, the only DB-API driver supported is `MySQL-Python` (also referred to @@ -35,51 +64,81 @@ Nested Transactions 5.0.3 See the official MySQL documentation for detailed information about features supported in any given server release. +Character Sets +-------------- + Many MySQL server installations default to a ``latin1`` encoding for client -connections. All data sent through the connection will be converted -into ``latin1``, even if you have ``utf8`` or another character set on your -tables and columns. With versions 4.1 and higher, you can change the -connection character set either through server configuration or by passing -the ``charset`` parameter to ``create_engine``. The ``charset`` option is -passed through to MySQL-Python and has the side-effect of also enabling -``use_unicode`` in the driver by default. For regular encoded strings, also -pass ``use_unicode=0`` in the connection arguments. - -Most MySQL server installations have a default table type of `MyISAM`, a -non-transactional table type. During a transaction, non-transactional -storage engines do not participate and continue to store table changes in -autocommit mode. For fully atomic transactions, all participating tables -must use a transactional engine such as `InnoDB`, `Falcon`, `SolidDB`, -`PBXT`, etc. Storage engines can be elected when creating tables in -SQLAlchemy by supplying a ``mysql_engine='whatever'`` to the ``Table`` -constructor. Any MySQL table creation option can be specified in this syntax. - -Not all MySQL storage engines support foreign keys. For `MyISAM` and similar -engines, the information loaded by table reflection will not include foreign -keys. For these tables, you may supply ``ForeignKeyConstraints`` at reflection -time:: - - Table('mytable', metadata, autoload=True, - ForeignKeyConstraint(['other_id'], ['othertable.other_id'])) - -When creating tables, SQLAlchemy will automatically set AUTO_INCREMENT on an -integer primary key column:: +connections. All data sent through the connection will be converted into +``latin1``, even if you have ``utf8`` or another character set on your tables +and columns. With versions 4.1 and higher, you can change the connection +character set either through server configuration or by including the +``charset`` parameter in the URL used for ``create_engine``. The ``charset`` +option is passed through to MySQL-Python and has the side-effect of also +enabling ``use_unicode`` in the driver by default. For regular encoded +strings, also pass ``use_unicode=0`` in the connection arguments:: + + # set client encoding to utf8; all strings come back as unicode + create_engine('mysql:///mydb?charset=utf8') + + # set client encoding to utf8; all strings come back as utf8 str + create_engine('mysql:///mydb?charset=utf8&use_unicode=0') + +Storage Engines +--------------- + +Most MySQL server installations have a default table type of ``MyISAM``, a +non-transactional table type. During a transaction, non-transactional storage +engines do not participate and continue to store table changes in autocommit +mode. For fully atomic transactions, all participating tables must use a +transactional engine such as ``InnoDB``, ``Falcon``, ``SolidDB``, `PBXT`, etc. + +Storage engines can be elected when creating tables in SQLAlchemy by supplying +a ``mysql_engine='whatever'`` to the ``Table`` constructor. Any MySQL table +creation option can be specified in this syntax:: + + Table('mytable', metadata, + Column('data', String(32)), + mysql_engine='InnoDB', + mysql_charset='utf8' + ) + +Keys +---- + +Not all MySQL storage engines support foreign keys. For ``MyISAM`` and +similar engines, the information loaded by table reflection will not include +foreign keys. For these tables, you may supply a +:class:`~sqlalchemy.ForeignKeyConstraint` at reflection time:: + + Table('mytable', metadata, + ForeignKeyConstraint(['other_id'], ['othertable.other_id']), + autoload=True + ) + +When creating tables, SQLAlchemy will automatically set ``AUTO_INCREMENT``` on +an integer primary key column:: >>> t = Table('mytable', metadata, - ... Column('mytable_id', Integer, primary_key=True)) + ... Column('mytable_id', Integer, primary_key=True) + ... ) >>> t.create() CREATE TABLE mytable ( id INTEGER NOT NULL AUTO_INCREMENT, PRIMARY KEY (id) ) -You can disable this behavior by supplying ``autoincrement=False`` in addition. -This can also be used to enable auto-increment on a secondary column in a -multi-column key for some storage engines:: +You can disable this behavior by supplying ``autoincrement=False`` to the +:class:`~sqlalchemy.Column`. This flag can also be used to enable +auto-increment on a secondary column in a multi-column key for some storage +engines:: Table('mytable', metadata, Column('gid', Integer, primary_key=True, autoincrement=False), - Column('id', Integer, primary_key=True)) + Column('id', Integer, primary_key=True) + ) + +SQL Mode +-------- MySQL SQL modes are supported. Modes that enable ``ANSI_QUOTES`` (such as ``ANSI``) require an engine option to modify SQLAlchemy's quoting style. @@ -89,43 +148,24 @@ creating your ``Engine``:: create_engine('mysql://localhost/test', use_ansiquotes=True) This is an engine-wide option and is not toggleable on a per-connection basis. -SQLAlchemy does not presume to ``SET sql_mode`` for you with this option. -For the best performance, set the quoting style server-wide in ``my.cnf`` or -by supplying ``--sql-mode`` to ``mysqld``. You can also use a ``Pool`` hook -to issue a ``SET SESSION sql_mode='...'`` on connect to configure each -connection. +SQLAlchemy does not presume to ``SET sql_mode`` for you with this option. For +the best performance, set the quoting style server-wide in ``my.cnf`` or by +supplying ``--sql-mode`` to ``mysqld``. You can also use a +:class:`sqlalchemy.pool.Pool` listener hook to issue a ``SET SESSION +sql_mode='...'`` on connect to configure each connection. -If you do not specify 'use_ansiquotes', the regular MySQL quoting style is -used by default. Table reflection operations will query the server +If you do not specify ``use_ansiquotes``, the regular MySQL quoting style is +used by default. -If you do issue a 'SET sql_mode' through SQLAlchemy, the dialect must be +If you do issue a ``SET sql_mode`` through SQLAlchemy, the dialect must be updated if the quoting style is changed. Again, this change will affect all connections:: connection.execute('SET sql_mode="ansi"') connection.dialect.use_ansiquotes = True -For normal SQLAlchemy usage, loading this module is unnescesary. It will be -loaded on-demand when a MySQL connection is needed. The generic column types -like ``String`` and ``Integer`` will automatically be adapted to the optimal -matching MySQL column type. - -But if you would like to use one of the MySQL-specific or enhanced column -types when creating tables with your ``Table`` definitions, then you will -need to import them from this module:: - - from sqlalchemy.databases import mysql - - Table('mytable', metadata, - Column('id', Integer, primary_key=True), - Column('ittybittyblob', mysql.MSTinyBlob), - Column('biggy', mysql.MSBigInteger(unsigned=True))) - -All standard MySQL column types are supported. The OpenGIS types are -available for use via table reflection but have no special support or -mapping to Python classes. If you're using these types and have opinions -about how OpenGIS can be smartly integrated into SQLAlchemy please join -the mailing list! +MySQL SQL Extensions +-------------------- Many of the MySQL SQL extensions are handled through SQLAlchemy's generic function and operator support:: @@ -133,10 +173,9 @@ function and operator support:: table.select(table.c.password==func.md5('plaintext')) table.select(table.c.username.op('regexp')('^[a-d]')) -And of course any valid statement can be executed as a string rather than -through the SQL expression language. +And of course any valid MySQL statement can be executed as a string as well. -Some limited support for MySQL extensions to SQL expressions is currently +Some limited direct support for MySQL extensions to SQL is currently available. * SELECT pragma:: @@ -147,10 +186,14 @@ available. update(..., mysql_limit=10) +Troubleshooting +--------------- + If you have problems that seem server related, first check that you are using the most recent stable MySQL-Python package available. The Database Notes page on the wiki at http://www.sqlalchemy.org is a good resource for timely information affecting MySQL in SQLAlchemy. + """ import datetime, decimal, inspect, re, sys @@ -304,22 +347,19 @@ class MSNumeric(sqltypes.Numeric, _NumericType): def __init__(self, precision=10, scale=2, asdecimal=True, **kw): """Construct a NUMERIC. - precision - Total digits in this number. If scale and precision are both - None, values are stored to limits allowed by the server. + :param precision: Total digits in this number. If scale and precision + are both None, values are stored to limits allowed by the server. - scale - The number of digits after the decimal point. + :param scale: The number of digits after the decimal point. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ _NumericType.__init__(self, kw) sqltypes.Numeric.__init__(self, precision, scale, asdecimal=asdecimal, **kw) @@ -350,22 +390,19 @@ class MSDecimal(MSNumeric): def __init__(self, precision=10, scale=2, asdecimal=True, **kw): """Construct a DECIMAL. - precision - Total digits in this number. If scale and precision are both None, - values are stored to limits allowed by the server. + :param precision: Total digits in this number. If scale and precision + are both None, values are stored to limits allowed by the server. - scale - The number of digits after the decimal point. + :param scale: The number of digits after the decimal point. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ super(MSDecimal, self).__init__(precision, scale, asdecimal=asdecimal, **kw) def get_col_spec(self): @@ -383,22 +420,19 @@ class MSDouble(sqltypes.Float, _NumericType): def __init__(self, precision=None, scale=None, asdecimal=True, **kw): """Construct a DOUBLE. - precision - Total digits in this number. If scale and precision are both None, - values are stored to limits allowed by the server. + :param precision: Total digits in this number. If scale and precision + are both None, values are stored to limits allowed by the server. - scale - The number of digits after the decimal point. + :param scale: The number of digits after the decimal point. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ if ((precision is None and scale is not None) or (precision is not None and scale is None)): raise exc.ArgumentError( @@ -425,20 +459,18 @@ class MSReal(MSDouble): def __init__(self, precision=None, scale=None, asdecimal=True, **kw): """Construct a REAL. - precision - Total digits in this number. If scale and precision are both None, - values are stored to limits allowed by the server. + :param precision: Total digits in this number. If scale and precision + are both None, values are stored to limits allowed by the server. - scale - The number of digits after the decimal point. + :param scale: The number of digits after the decimal point. - unsigned - Optional. + :param unsigned: a boolean, optional. + + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. """ MSDouble.__init__(self, precision, scale, asdecimal, **kw) @@ -457,22 +489,19 @@ class MSFloat(sqltypes.Float, _NumericType): def __init__(self, precision=None, scale=None, asdecimal=False, **kw): """Construct a FLOAT. - precision - Total digits in this number. If scale and precision are both None, - values are stored to limits allowed by the server. + :param precision: Total digits in this number. If scale and precision + are both None, values are stored to limits allowed by the server. - scale - The number of digits after the decimal point. + :param scale: The number of digits after the decimal point. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ _NumericType.__init__(self, kw) sqltypes.Float.__init__(self, asdecimal=asdecimal, **kw) self.scale = scale @@ -496,18 +525,16 @@ class MSInteger(sqltypes.Integer, _NumericType): def __init__(self, display_width=None, **kw): """Construct an INTEGER. - display_width - Optional, maximum display width for this number. + :param display_width: Optional, maximum display width for this number. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ if 'length' in kw: util.warn_deprecated("'length' is deprecated for MSInteger and subclasses. Use 'display_width'.") self.display_width = kw.pop('length') @@ -529,18 +556,16 @@ class MSBigInteger(MSInteger): def __init__(self, display_width=None, **kw): """Construct a BIGINTEGER. - display_width - Optional, maximum display width for this number. + :param display_width: Optional, maximum display width for this number. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ super(MSBigInteger, self).__init__(display_width, **kw) def get_col_spec(self): @@ -549,24 +574,23 @@ class MSBigInteger(MSInteger): else: return self._extend("BIGINT") + class MSMediumInteger(MSInteger): """MySQL MEDIUMINTEGER type.""" def __init__(self, display_width=None, **kw): """Construct a MEDIUMINTEGER - display_width - Optional, maximum display width for this number. + :param display_width: Optional, maximum display width for this number. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ super(MSMediumInteger, self).__init__(display_width, **kw) def get_col_spec(self): @@ -587,18 +611,16 @@ class MSTinyInteger(MSInteger): reflected during Table(..., autoload=True) are treated as Boolean columns. - display_width - Optional, maximum display width for this number. + :param display_width: Optional, maximum display width for this number. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ super(MSTinyInteger, self).__init__(display_width, **kw) def get_col_spec(self): @@ -614,18 +636,16 @@ class MSSmallInteger(sqltypes.Smallinteger, MSInteger): def __init__(self, display_width=None, **kw): """Construct a SMALLINTEGER. - display_width - Optional, maximum display width for this number. + :param display_width: Optional, maximum display width for this number. - unsigned - Optional. + :param unsigned: a boolean, optional. - zerofill - Optional. If true, values will be stored as strings left-padded with - zeros. Note that this does not effect the values returned by the - underlying database API, which continue to be numeric. - """ + :param zerofill: Optional. If true, values will be stored as strings + left-padded with zeros. Note that this does not effect the values + returned by the underlying database API, which continue to be + numeric. + """ self.display_width = display_width _NumericType.__init__(self, kw) sqltypes.SmallInteger.__init__(self, **kw) @@ -641,11 +661,17 @@ class MSBit(sqltypes.TypeEngine): """MySQL BIT type. This type is for MySQL 5.0.3 or greater for MyISAM, and 5.0.5 or greater for - MyISAM, MEMORY, InnoDB and BDB. For older versions, use a MSTinyInteger(1) + MyISAM, MEMORY, InnoDB and BDB. For older versions, use a MSTinyInteger() type. + """ def __init__(self, length=None): + """Construct a BIT. + + :param length: Optional, number of bits. + + """ self.length = length def result_processor(self, dialect): @@ -698,19 +724,22 @@ class MSTime(sqltypes.Time): class MSTimeStamp(sqltypes.TIMESTAMP): """MySQL TIMESTAMP type. - To signal the orm to automatically re-select modified rows to retrieve - the updated timestamp, add a DefaultClause to your column specification:: + To signal the orm to automatically re-select modified rows to retrieve the + updated timestamp, add a ``server_default`` to your + :class:`~sqlalchemy.Column` specification:: from sqlalchemy.databases import mysql Column('updated', mysql.MSTimeStamp, - server_default=sql.text('CURRENT_TIMESTAMP')) + server_default=sql.text('CURRENT_TIMESTAMP') + ) The full range of MySQL 4.1+ TIMESTAMP defaults can be specified in - the the default: + the the default:: server_default=sql.text('CURRENT TIMESTAMP ON UPDATE CURRENT_TIMESTAMP') """ + def get_col_spec(self): return "TIMESTAMP" @@ -733,38 +762,31 @@ class MSText(_StringType, sqltypes.Text): def __init__(self, length=None, **kwargs): """Construct a TEXT. - length - Optional, if provided the server may optimize storage by - subsitituting the smallest TEXT type sufficient to store + :param length: Optional, if provided the server may optimize storage + by substituting the smallest TEXT type sufficient to store ``length`` characters. - charset - Optional, a column-level character set for this string - value. Takes precendence to 'ascii' or 'unicode' short-hand. - - collation - Optional, a column-level collation for this string value. - Takes precedence to 'binary' short-hand. - - ascii - Defaults to False: short-hand for the ``latin1`` character set, - generates ASCII in schema. - - unicode - Defaults to False: short-hand for the ``ucs2`` character set, - generates UNICODE in schema. - - national - Optional. If true, use the server's configured national - character set. - - binary - Defaults to False: short-hand, pick the binary collation type - that matches the column's character set. Generates BINARY in - schema. This does not affect the type of data stored, only the - collation of character data. - """ + :param charset: Optional, a column-level character set for this string + value. Takes precedence to 'ascii' or 'unicode' short-hand. + + :param collation: Optional, a column-level collation for this string + value. Takes precedence to 'binary' short-hand. + + :param ascii: Defaults to False: short-hand for the ``latin1`` + character set, generates ASCII in schema. + + :param unicode: Defaults to False: short-hand for the ``ucs2`` + character set, generates UNICODE in schema. + + :param national: Optional. If true, use the server's configured + national character set. + + :param binary: Defaults to False: short-hand, pick the binary + collation type that matches the column's character set. Generates + BINARY in schema. This does not affect the type of data stored, + only the collation of character data. + """ _StringType.__init__(self, **kwargs) sqltypes.Text.__init__(self, length, kwargs.get('convert_unicode', False), kwargs.get('assert_unicode', None)) @@ -782,31 +804,26 @@ class MSTinyText(MSText): def __init__(self, **kwargs): """Construct a TINYTEXT. - charset - Optional, a column-level character set for this string - value. Takes precendence to 'ascii' or 'unicode' short-hand. - - collation - Optional, a column-level collation for this string value. - Takes precedence to 'binary' short-hand. - - ascii - Defaults to False: short-hand for the ``latin1`` character set, - generates ASCII in schema. - - unicode - Defaults to False: short-hand for the ``ucs2`` character set, - generates UNICODE in schema. - - national - Optional. If true, use the server's configured national - character set. - - binary - Defaults to False: short-hand, pick the binary collation type - that matches the column's character set. Generates BINARY in - schema. This does not affect the type of data stored, only the - collation of character data. + :param charset: Optional, a column-level character set for this string + value. Takes precedence to 'ascii' or 'unicode' short-hand. + + :param collation: Optional, a column-level collation for this string + value. Takes precedence to 'binary' short-hand. + + :param ascii: Defaults to False: short-hand for the ``latin1`` + character set, generates ASCII in schema. + + :param unicode: Defaults to False: short-hand for the ``ucs2`` + character set, generates UNICODE in schema. + + :param national: Optional. If true, use the server's configured + national character set. + + :param binary: Defaults to False: short-hand, pick the binary + collation type that matches the column's character set. Generates + BINARY in schema. This does not affect the type of data stored, + only the collation of character data. + """ super(MSTinyText, self).__init__(**kwargs) @@ -821,33 +838,27 @@ class MSMediumText(MSText): def __init__(self, **kwargs): """Construct a MEDIUMTEXT. - charset - Optional, a column-level character set for this string - value. Takes precendence to 'ascii' or 'unicode' short-hand. - - collation - Optional, a column-level collation for this string value. - Takes precedence to 'binary' short-hand. - - ascii - Defaults to False: short-hand for the ``latin1`` character set, - generates ASCII in schema. - - unicode - Defaults to False: short-hand for the ``ucs2`` character set, - generates UNICODE in schema. - - national - Optional. If true, use the server's configured national - character set. - - binary - Defaults to False: short-hand, pick the binary collation type - that matches the column's character set. Generates BINARY in - schema. This does not affect the type of data stored, only the - collation of character data. - """ + :param charset: Optional, a column-level character set for this string + value. Takes precedence to 'ascii' or 'unicode' short-hand. + + :param collation: Optional, a column-level collation for this string + value. Takes precedence to 'binary' short-hand. + + :param ascii: Defaults to False: short-hand for the ``latin1`` + character set, generates ASCII in schema. + + :param unicode: Defaults to False: short-hand for the ``ucs2`` + character set, generates UNICODE in schema. + + :param national: Optional. If true, use the server's configured + national character set. + :param binary: Defaults to False: short-hand, pick the binary + collation type that matches the column's character set. Generates + BINARY in schema. This does not affect the type of data stored, + only the collation of character data. + + """ super(MSMediumText, self).__init__(**kwargs) def get_col_spec(self): @@ -860,33 +871,27 @@ class MSLongText(MSText): def __init__(self, **kwargs): """Construct a LONGTEXT. - charset - Optional, a column-level character set for this string - value. Takes precendence to 'ascii' or 'unicode' short-hand. - - collation - Optional, a column-level collation for this string value. - Takes precedence to 'binary' short-hand. - - ascii - Defaults to False: short-hand for the ``latin1`` character set, - generates ASCII in schema. - - unicode - Defaults to False: short-hand for the ``ucs2`` character set, - generates UNICODE in schema. - - national - Optional. If true, use the server's configured national - character set. - - binary - Defaults to False: short-hand, pick the binary collation type - that matches the column's character set. Generates BINARY in - schema. This does not affect the type of data stored, only the - collation of character data. - """ + :param charset: Optional, a column-level character set for this string + value. Takes precedence to 'ascii' or 'unicode' short-hand. + :param collation: Optional, a column-level collation for this string + value. Takes precedence to 'binary' short-hand. + + :param ascii: Defaults to False: short-hand for the ``latin1`` + character set, generates ASCII in schema. + + :param unicode: Defaults to False: short-hand for the ``ucs2`` + character set, generates UNICODE in schema. + + :param national: Optional. If true, use the server's configured + national character set. + + :param binary: Defaults to False: short-hand, pick the binary + collation type that matches the column's character set. Generates + BINARY in schema. This does not affect the type of data stored, + only the collation of character data. + + """ super(MSLongText, self).__init__(**kwargs) def get_col_spec(self): @@ -899,36 +904,27 @@ class MSString(_StringType, sqltypes.String): def __init__(self, length=None, **kwargs): """Construct a VARCHAR. - length - Maximum data length, in characters. + :param charset: Optional, a column-level character set for this string + value. Takes precedence to 'ascii' or 'unicode' short-hand. - charset - Optional, a column-level character set for this string - value. Takes precendence to 'ascii' or 'unicode' short-hand. - - collation - Optional, a column-level collation for this string value. - Takes precedence to 'binary' short-hand. - - ascii - Defaults to False: short-hand for the ``latin1`` character set, - generates ASCII in schema. - - unicode - Defaults to False: short-hand for the ``ucs2`` character set, - generates UNICODE in schema. - - national - Optional. If true, use the server's configured national - character set. - - binary - Defaults to False: short-hand, pick the binary collation type - that matches the column's character set. Generates BINARY in - schema. This does not affect the type of data stored, only the - collation of character data. - """ + :param collation: Optional, a column-level collation for this string + value. Takes precedence to 'binary' short-hand. + + :param ascii: Defaults to False: short-hand for the ``latin1`` + character set, generates ASCII in schema. + + :param unicode: Defaults to False: short-hand for the ``ucs2`` + character set, generates UNICODE in schema. + + :param national: Optional. If true, use the server's configured + national character set. + + :param binary: Defaults to False: short-hand, pick the binary + collation type that matches the column's character set. Generates + BINARY in schema. This does not affect the type of data stored, + only the collation of character data. + """ _StringType.__init__(self, **kwargs) sqltypes.String.__init__(self, length, kwargs.get('convert_unicode', False), kwargs.get('assert_unicode', None)) @@ -946,17 +942,15 @@ class MSChar(_StringType, sqltypes.CHAR): def __init__(self, length, **kwargs): """Construct an NCHAR. - length - Maximum data length, in characters. + :param length: Maximum data length, in characters. + + :param binary: Optional, use the default binary collation for the + national character set. This does not affect the type of data + stored, use a BINARY type for binary data. - binary - Optional, use the default binary collation for the national character - set. This does not affect the type of data stored, use a BINARY - type for binary data. + :param collation: Optional, request a particular collation. Must be + compatible with the national character set. - collation - Optional, request a particular collation. Must be compatibile - with the national character set. """ _StringType.__init__(self, **kwargs) sqltypes.CHAR.__init__(self, length, @@ -976,19 +970,16 @@ class MSNVarChar(_StringType, sqltypes.String): def __init__(self, length=None, **kwargs): """Construct an NVARCHAR. - length - Maximum data length, in characters. + :param length: Maximum data length, in characters. - binary - Optional, use the default binary collation for the national character - set. This does not affect the type of data stored, use a VARBINARY - type for binary data. + :param binary: Optional, use the default binary collation for the + national character set. This does not affect the type of data + stored, use a BINARY type for binary data. - collation - Optional, request a particular collation. Must be compatibile - with the national character set. - """ + :param collation: Optional, request a particular collation. Must be + compatible with the national character set. + """ kwargs['national'] = True _StringType.__init__(self, **kwargs) sqltypes.String.__init__(self, length, @@ -1010,18 +1001,16 @@ class MSNChar(_StringType, sqltypes.CHAR): def __init__(self, length=None, **kwargs): """Construct an NCHAR. Arguments are: - length - Maximum data length, in characters. + :param length: Maximum data length, in characters. - binary - Optional, request the default binary collation for the - national character set. + :param binary: Optional, use the default binary collation for the + national character set. This does not affect the type of data + stored, use a BINARY type for binary data. - collation - Optional, request a particular collation. Must be compatibile - with the national character set. - """ + :param collation: Optional, request a particular collation. Must be + compatible with the national character set. + """ kwargs['national'] = True _StringType.__init__(self, **kwargs) sqltypes.CHAR.__init__(self, length, @@ -1054,8 +1043,8 @@ class MSVarBinary(_BinaryType): def __init__(self, length=None, **kw): """Construct a VARBINARY. Arguments are: - length - Maximum data length, in bytes. + :param length: Maximum data length, in characters. + """ super(MSVarBinary, self).__init__(length, **kw) @@ -1070,15 +1059,15 @@ class MSBinary(_BinaryType): """MySQL BINARY type, for fixed length binary data""" def __init__(self, length=None, **kw): - """Construct a BINARY. This is a fixed length type, and short - values will be right-padded with a server-version-specific - pad value. + """Construct a BINARY. - length - Maximum data length, in bytes. If length is not specified, this - will generate a BLOB. This usage is deprecated. - """ + This is a fixed length type, and short values will be right-padded + with a server-version-specific pad value. + + :param length: Maximum data length, in bytes. If length is not + specified, this will generate a BLOB. This usage is deprecated. + """ super(MSBinary, self).__init__(length, **kw) def get_col_spec(self): @@ -1101,12 +1090,11 @@ class MSBlob(_BinaryType): def __init__(self, length=None, **kw): """Construct a BLOB. Arguments are: - length - Optional, if provided the server may optimize storage by - subsitituting the smallest TEXT type sufficient to store + :param length: Optional, if provided the server may optimize storage + by substituting the smallest TEXT type sufficient to store ``length`` characters. - """ + """ super(MSBlob, self).__init__(length, **kw) def get_col_spec(self): @@ -1160,44 +1148,36 @@ class MSEnum(MSString): Arguments are: - enums - The range of valid values for this ENUM. Values will be quoted - when generating the schema according to the quoting flag (see + :param enums: The range of valid values for this ENUM. Values will be + quoted when generating the schema according to the quoting flag (see below). - strict - Defaults to False: ensure that a given value is in this ENUM's - range of permissible values when inserting or updating rows. - Note that MySQL will not raise a fatal error if you attempt to - store an out of range value- an alternate value will be stored - instead. (See MySQL ENUM documentation.) + :param strict: Defaults to False: ensure that a given value is in this + ENUM's range of permissible values when inserting or updating rows. + Note that MySQL will not raise a fatal error if you attempt to store + an out of range value- an alternate value will be stored instead. + (See MySQL ENUM documentation.) - charset - Optional, a column-level character set for this string - value. Takes precendence to 'ascii' or 'unicode' short-hand. + :param charset: Optional, a column-level character set for this string + value. Takes precedence to 'ascii' or 'unicode' short-hand. - collation - Optional, a column-level collation for this string value. - Takes precedence to 'binary' short-hand. + :param collation: Optional, a column-level collation for this string + value. Takes precedence to 'binary' short-hand. - ascii - Defaults to False: short-hand for the ``latin1`` character set, - generates ASCII in schema. + :param ascii: Defaults to False: short-hand for the ``latin1`` + character set, generates ASCII in schema. - unicode - Defaults to False: short-hand for the ``ucs2`` character set, - generates UNICODE in schema. + :param unicode: Defaults to False: short-hand for the ``ucs2`` + character set, generates UNICODE in schema. - binary - Defaults to False: short-hand, pick the binary collation type - that matches the column's character set. Generates BINARY in - schema. This does not affect the type of data stored, only the - collation of character data. + :param binary: Defaults to False: short-hand, pick the binary + collation type that matches the column's character set. Generates + BINARY in schema. This does not affect the type of data stored, + only the collation of character data. - quoting - Defaults to 'auto': automatically determine enum value quoting. If - all enum values are surrounded by the same quoting character, then - use 'quoted' mode. Otherwise, use 'unquoted' mode. + :param quoting: Defaults to 'auto': automatically determine enum value + quoting. If all enum values are surrounded by the same quoting + character, then use 'quoted' mode. Otherwise, use 'unquoted' mode. 'quoted': values in enums are already quoted, they will be used directly when generating the schema. @@ -1277,36 +1257,30 @@ class MSSet(MSString): Arguments are: - values - The range of valid values for this SET. Values will be used - exactly as they appear when generating schemas. Strings must - be quoted, as in the example above. Single-quotes are suggested - for ANSI compatability and are required for portability to servers - with ANSI_QUOTES enabled. + :param values: The range of valid values for this SET. Values will be + used exactly as they appear when generating schemas. Strings must + be quoted, as in the example above. Single-quotes are suggested for + ANSI compatibility and are required for portability to servers with + ANSI_QUOTES enabled. - charset - Optional, a column-level character set for this string - value. Takes precendence to 'ascii' or 'unicode' short-hand. - - collation - Optional, a column-level collation for this string value. - Takes precedence to 'binary' short-hand. - - ascii - Defaults to False: short-hand for the ``latin1`` character set, - generates ASCII in schema. - - unicode - Defaults to False: short-hand for the ``ucs2`` character set, - generates UNICODE in schema. - - binary - Defaults to False: short-hand, pick the binary collation type - that matches the column's character set. Generates BINARY in - schema. This does not affect the type of data stored, only the - collation of character data. - """ + :param charset: Optional, a column-level character set for this string + value. Takes precedence to 'ascii' or 'unicode' short-hand. + + :param collation: Optional, a column-level collation for this string + value. Takes precedence to 'binary' short-hand. + + :param ascii: Defaults to False: short-hand for the ``latin1`` + character set, generates ASCII in schema. + :param unicode: Defaults to False: short-hand for the ``ucs2`` + character set, generates UNICODE in schema. + + :param binary: Defaults to False: short-hand, pick the binary + collation type that matches the column's character set. Generates + BINARY in schema. This does not affect the type of data stored, + only the collation of character data. + + """ self.__ddl_values = values strip_values = [] diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index f22987976..6dde7a330 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -110,62 +110,112 @@ def create_engine(*args, **kwargs): ``dialect://user:password@host/dbname[?key=value..]``, where ``dialect`` is a name such as ``mysql``, ``oracle``, ``postgres``, etc. Alternatively, the URL can be an instance of - ``sqlalchemy.engine.url.URL``. - - `**kwargs` represents options to be sent to the Engine itself as - well as the components of the Engine, including the Dialect, the - ConnectionProvider, and the Pool. A list of common options is as - follows: - - poolclass - a subclass of ``sqlalchemy.pool.Pool`` which will be used to - instantiate a connection pool. - - pool - an instance of ``sqlalchemy.pool.DBProxy`` or - ``sqlalchemy.pool.Pool`` to be used as the underlying source for - connections (DBProxy/Pool is described in the previous section). - This argument supercedes "poolclass". - - echo - defaults to False: if True, the Engine will log all statements - as well as a repr() of their parameter lists to the engines - logger, which defaults to ``sys.stdout``. A Engine instances' - `echo` data member can be modified at any time to turn logging - on and off. If set to the string 'debug', result rows will be - printed to the standard output as well. - - logger - defaults to None: a file-like object where logging output can be - sent, if `echo` is set to True. This defaults to - ``sys.stdout``. - - encoding - defaults to 'utf-8': the encoding to be used when - encoding/decoding Unicode strings. - - convert_unicode - defaults to False: true if unicode conversion should be applied - to all str types. - - module - defaults to None: this is a reference to a DB-API 2.0 module to - be used instead of the dialect's default module. - - strategy - allows alternate Engine implementations to take effect. Current - implementations include ``plain`` and ``threadlocal``. The - default used by this function is ``plain``. - - ``plain`` provides support for a Connection object which can be - used to execute SQL queries with a specific underlying DB-API - connection. - - ``threadlocal`` is similar to ``plain`` except that it adds - support for a thread-local connection and transaction context, - which allows a group of engine operations to participate using - the same underlying connection and transaction without the need - for explicitly passing a single Connection. + :class:`~sqlalchemy.engine.url.URL`. + + `**kwargs` takes a wide variety of options which are routed + towards their appropriate components. Arguments may be + specific to the Engine, the underlying Dialect, as well as the + Pool. Specific dialects also accept keyword arguments that + are unique to that dialect. Here, we describe the parameters + that are common to most ``create_engine()`` usage. + + :param assert_unicode=False: When set to ``True`` alongside + convert_unicode=``True``, asserts that incoming string bind + parameters are instances of ``unicode``, otherwise raises an + error. Only takes effect when ``convert_unicode==True``. This + flag is also available on the ``String`` type and its + descendants. New in 0.4.2. + + :param connect_args: a dictionary of options which will be + passed directly to the DBAPI's ``connect()`` method as + additional keyword arguments. + + :param convert_unicode=False: if set to True, all + String/character based types will convert Unicode values to raw + byte values going into the database, and all raw byte values to + Python Unicode coming out in result sets. This is an + engine-wide method to provide unicode conversion across the + board. For unicode conversion on a column-by-column level, use + the ``Unicode`` column type instead, described in `types`. + + :param creator: a callable which returns a DBAPI connection. + This creation function will be passed to the underlying + connection pool and will be used to create all new database + connections. Usage of this function causes connection + parameters specified in the URL argument to be bypassed. + + :param echo=False: if True, the Engine will log all statements + as well as a repr() of their parameter lists to the engines + logger, which defaults to sys.stdout. The ``echo`` attribute of + ``Engine`` can be modified at any time to turn logging on and + off. If set to the string ``"debug"``, result rows will be + printed to the standard output as well. This flag ultimately + controls a Python logger; see `dbengine_logging` at the end of + this chapter for information on how to configure logging + directly. + + :param echo_pool=False: if True, the connection pool will log + all checkouts/checkins to the logging stream, which defaults to + sys.stdout. This flag ultimately controls a Python logger; see + `dbengine_logging` for information on how to configure logging + directly. + + :param encoding='utf-8': the encoding to use for all Unicode + translations, both by engine-wide unicode conversion as well as + the ``Unicode`` type object. + + :param label_length=None: optional integer value which limits + the size of dynamically generated column labels to that many + characters. If less than 6, labels are generated as + "_(counter)". If ``None``, the value of + ``dialect.max_identifier_length`` is used instead. + + :param module=None: used by database implementations which + support multiple DBAPI modules, this is a reference to a DBAPI2 + module to be used instead of the engine's default module. For + Postgres, the default is psycopg2. For Oracle, it's cx_Oracle. + + :param pool=None: an already-constructed instance of + :class:`~sqlalchemy.pool.Pool`, such as a + :class:`~sqlalchemy.pool.QueuePool` instance. If non-None, this + pool will be used directly as the underlying connection pool + for the engine, bypassing whatever connection parameters are + present in the URL argument. For information on constructing + connection pools manually, see `pooling`. + + :param poolclass=None: a :class:`~sqlalchemy.pool.Pool` + subclass, which will be used to create a connection pool + instance using the connection parameters given in the URL. Note + this differs from ``pool`` in that you don't actually + instantiate the pool in this case, you just indicate what type + of pool to be used. + + :param max_overflow=10: the number of connections to allow in + connection pool "overflow", that is connections that can be + opened above and beyond the pool_size setting, which defaults + to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`. + + :param pool_size=5: the number of connections to keep open + inside the connection pool. This used with :class:`~sqlalchemy.pool.QueuePool` as + well as :class:`~sqlalchemy.pool.SingletonThreadPool`. + + :param pool_recycle=-1: this setting causes the pool to recycle + connections after the given number of seconds has passed. It + defaults to -1, or no timeout. For example, setting to 3600 + means connections will be recycled after one hour. Note that + MySQL in particular will ``disconnect automatically`` if no + activity is detected on a connection for eight hours (although + this is configurable with the MySQLDB connection itself and the + server configuration as well). + + :param pool_timeout=30: number of seconds to wait before giving + up on getting a connection from the pool. This is only used + with :class:`~sqlalchemy.pool.QueuePool`. + + :param strategy='plain': used to invoke alternate :class:`~sqlalchemy.engine.base.Engine.` + implementations. Currently available is the ``threadlocal`` + strategy, which is described in :ref:`threadlocal_strategy`. + """ strategy = kwargs.pop('strategy', default_strategy) diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index d22e21cfe..97624280e 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -47,22 +47,22 @@ class Dialect(object): 'utf-8'. schemagenerator - a [sqlalchemy.schema#SchemaVisitor] class which generates + a :class:`~sqlalchemy.schema.SchemaVisitor` class which generates schemas. schemadropper - a [sqlalchemy.schema#SchemaVisitor] class which drops schemas. + a :class:`~sqlalchemy.schema.SchemaVisitor` class which drops schemas. defaultrunner - a [sqlalchemy.schema#SchemaVisitor] class which executes + a :class:`~sqlalchemy.schema.SchemaVisitor` class which executes defaults. statement_compiler - a [sqlalchemy.engine.base#Compiled] class used to compile SQL + a :class:`~sqlalchemy.engine.base.Compiled` class used to compile SQL statements preparer - a [sqlalchemy.sql.compiler#IdentifierPreparer] class used to + a :class:`~sqlalchemy.sql.compiler.IdentifierPreparer` class used to quote identifiers. supports_alter @@ -107,7 +107,7 @@ class Dialect(object): def create_connect_args(self, url): """Build DB-API compatible connection arguments. - Given a [sqlalchemy.engine.url#URL] object, returns a tuple + Given a :class:`~sqlalchemy.engine.url.URL` object, returns a tuple consisting of a `*args`/`**kwargs` suitable to send directly to the dbapi's connect function. """ @@ -118,11 +118,11 @@ class Dialect(object): def type_descriptor(self, typeobj): """Transform a generic type to a database-specific type. - Transforms the given [sqlalchemy.types#TypeEngine] instance + Transforms the given :class:`~sqlalchemy.types.TypeEngine` instance from generic to database-specific. Subclasses will usually use the - [sqlalchemy.types#adapt_type()] method in the types module to + :func:`~sqlalchemy.types.adapt_type` method in the types module to make this job easy. """ @@ -137,8 +137,8 @@ class Dialect(object): def reflecttable(self, connection, table, include_columns=None): """Load table description from the database. - Given a [sqlalchemy.engine#Connection] and a - [sqlalchemy.schema#Table] object, reflect its columns and + Given a :class:`~sqlalchemy.engine.Connection` and a + :class:`~sqlalchemy.schema.Table` object, reflect its columns and properties from the database. If include_columns (a list or set) is specified, limit the autoload to the given column names. @@ -149,7 +149,7 @@ class Dialect(object): def has_table(self, connection, table_name, schema=None): """Check the existence of a particular table in the database. - Given a [sqlalchemy.engine#Connection] object and a string + Given a :class:`~sqlalchemy.engine.Connection` object and a string `table_name`, return True if the given table (possibly within the specified `schema`) exists in the database, False otherwise. @@ -160,7 +160,7 @@ class Dialect(object): def has_sequence(self, connection, sequence_name, schema=None): """Check the existence of a particular sequence in the database. - Given a [sqlalchemy.engine#Connection] object and a string + Given a :class:`~sqlalchemy.engine.Connection` object and a string `sequence_name`, return True if the given sequence exists in the database, False otherwise. """ @@ -168,12 +168,12 @@ class Dialect(object): raise NotImplementedError() def get_default_schema_name(self, connection): - """Return the string name of the currently selected schema given a [sqlalchemy.engine#Connection].""" + """Return the string name of the currently selected schema given a :class:`~sqlalchemy.engine.Connection`.""" raise NotImplementedError() def create_execution_context(self, connection, compiled=None, compiled_parameters=None, statement=None, parameters=None): - """Return a new [sqlalchemy.engine#ExecutionContext] object.""" + """Return a new :class:`~sqlalchemy.engine.ExecutionContext` object.""" raise NotImplementedError() @@ -506,7 +506,7 @@ class Connection(Connectable): """Construct a new Connection. Connection objects are typically constructed by an - [sqlalchemy.engine#Engine], see the ``connect()`` and + :class:`~sqlalchemy.engine.Engine`, see the ``connect()`` and ``contextual_connect()`` methods of Engine. """ @@ -630,7 +630,7 @@ class Connection(Connectable): This method can be used to insulate the rest of an application from a modified state on a connection (such as a transaction isolation level or similar). Also see - [sqlalchemy.interfaces#PoolListener] for a mechanism to modify + :class:`~sqlalchemy.interfaces.PoolListener` for a mechanism to modify connection state when connections leave and return to their connection pool. @@ -1064,8 +1064,9 @@ class TwoPhaseTransaction(Transaction): class Engine(Connectable): """ - Connects a Pool, a Dialect and a CompilerFactory together to - provide a default implementation of SchemaEngine. + Connects a :class:`~sqlalchemy.pool.Pool` and :class:`~sqlalchemy.engine.base.Dialect` + together to provide a source of database connectivity and behavior. + """ def __init__(self, pool, dialect, url, echo=None, proxy=None): @@ -1082,7 +1083,7 @@ class Engine(Connectable): @property def name(self): - "String name of the [sqlalchemy.engine#Dialect] in use by this ``Engine``." + "String name of the :class:`~sqlalchemy.engine.Dialect` in use by this ``Engine``." return self.dialect.name diff --git a/lib/sqlalchemy/engine/strategies.py b/lib/sqlalchemy/engine/strategies.py index 62a4b9bb8..fa608df65 100644 --- a/lib/sqlalchemy/engine/strategies.py +++ b/lib/sqlalchemy/engine/strategies.py @@ -2,7 +2,7 @@ These are semi-private implementation classes which provide the underlying behavior for the "strategy" keyword argument available on -[sqlalchemy.engine#create_engine()]. Current available options are +:func:`~sqlalchemy.engine.create_engine`. Current available options are ``plain``, ``threadlocal``, and ``mock``. New strategies can be added via new ``EngineStrategy`` classes. diff --git a/lib/sqlalchemy/engine/threadlocal.py b/lib/sqlalchemy/engine/threadlocal.py index e0dae8de3..23c9cd0c1 100644 --- a/lib/sqlalchemy/engine/threadlocal.py +++ b/lib/sqlalchemy/engine/threadlocal.py @@ -1,7 +1,7 @@ """Provides a thread-local transactional wrapper around the root Engine class. The ``threadlocal`` module is invoked when using the ``strategy="threadlocal"`` flag -with [sqlalchemy.engine#create_engine()]. This module is semi-private and is +with :func:`~sqlalchemy.engine.create_engine`. This module is semi-private and is invoked automatically when the threadlocal engine strategy is used. """ diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py index b81a91d59..e00efd6c0 100644 --- a/lib/sqlalchemy/engine/url.py +++ b/lib/sqlalchemy/engine/url.py @@ -1,7 +1,7 @@ -"""Provides the [sqlalchemy.engine.url#URL] class which encapsulates +"""Provides the :class:`~sqlalchemy.engine.url.URL` class which encapsulates information about a database connection specification. -The URL object is created automatically when [sqlalchemy.engine#create_engine()] is called +The URL object is created automatically when :func:`~sqlalchemy.engine.create_engine` is called with a string argument; alternatively, the URL is a public-facing construct which can be used directly and is also accepted directly by ``create_engine()``. """ @@ -18,30 +18,25 @@ class URL(object): string by the ``module-level make_url()`` function. the string format of the URL is an RFC-1738-style string. - Attributes on URL include: - - drivername - the name of the database backend. This name will correspond to - a module in sqlalchemy/databases or a third party plug-in. + All initialization parameters are available as public attributes. + + :param drivername: the name of the database backend. + This name will correspond to a module in sqlalchemy/databases + or a third party plug-in. - username - The user name for the connection. + :param username: The user name. - password - database password. + :param password: database password. - host - The name of the host. + :param host: The name of the host. - port - The port number. + :param port: The port number. - database - The database. + :param database: The database name. - query - A dictionary containing key/value pairs representing the URL's - query string. + :param query: A dictionary of options to be passed to the + dialect and/or the DBAPI upon connect. + """ def __init__(self, drivername, username=None, password=None, host=None, port=None, database=None, query=None): @@ -107,18 +102,18 @@ class URL(object): used as the keys by default. Unset or false attributes are omitted from the final dictionary. - \**kw - Optional, alternate key names for url attributes:: + :param \**kw: Optional, alternate key names for url + attributes:: - # return 'username' as 'user' - username='user' + # return 'username' as 'user' + username='user' - # omit 'database' - database=None - - names - Deprecated. A list of key names. Equivalent to the keyword - usage, must be provided in the order above. + # omit 'database' + database=None + + :param names: Deprecated. Same purpose as the keyword-based alternate names, + but correlates the name to the original positionally. + """ translated = {} diff --git a/lib/sqlalchemy/exc.py b/lib/sqlalchemy/exc.py index f82c632f6..774401ee4 100644 --- a/lib/sqlalchemy/exc.py +++ b/lib/sqlalchemy/exc.py @@ -7,7 +7,7 @@ The base exception class is SQLAlchemyError. Exceptions which are raised as a result of DBAPI exceptions are all subclasses of -[sqlalchemy.exc#DBAPIError]. +:class:`~sqlalchemy.exc.DBAPIError`. """ diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py index a26156844..37fa98d78 100644 --- a/lib/sqlalchemy/ext/declarative.py +++ b/lib/sqlalchemy/ext/declarative.py @@ -408,7 +408,7 @@ def _deferred_relation(cls, prop): def synonym_for(name, map_column=False): """Decorator, make a Python @property a query synonym for a column. - A decorator version of [sqlalchemy.orm#synonym()]. The function being + A decorator version of :func:`~sqlalchemy.orm.synonym`. The function being decorated is the 'descriptor', otherwise passes its arguments through to synonym():: @@ -430,7 +430,7 @@ def synonym_for(name, map_column=False): def comparable_using(comparator_factory): """Decorator, allow a Python @property to be used in query criteria. - A decorator front end to [sqlalchemy.orm#comparable_property()], passes + A decorator front end to :func:`~sqlalchemy.orm.comparable_property`, passes through the comparator_factory and the function being decorated:: @comparable_using(MyComparatorType) diff --git a/lib/sqlalchemy/ext/orderinglist.py b/lib/sqlalchemy/ext/orderinglist.py index b53a57cbe..e59b577e3 100644 --- a/lib/sqlalchemy/ext/orderinglist.py +++ b/lib/sqlalchemy/ext/orderinglist.py @@ -60,7 +60,7 @@ Numbering and serialization are both highly configurable. See the docstrings in this module and the main SQLAlchemy documentation for more information and examples. -The [sqlalchemy.ext.orderinglist#ordering_list] factory function is the +The :class:`~sqlalchemy.ext.orderinglist.ordering_list` factory function is the ORM-compatible constructor for `OrderingList` instances. """ diff --git a/lib/sqlalchemy/interfaces.py b/lib/sqlalchemy/interfaces.py index ae92dc50d..f9c21d246 100644 --- a/lib/sqlalchemy/interfaces.py +++ b/lib/sqlalchemy/interfaces.py @@ -12,6 +12,11 @@ class PoolListener(object): Usage:: + class MyListener(PoolListener): + def connect(self, dbapi_con, con_record): + '''perform connect operations''' + # etc. + # create a new pool with a listener p = QueuePool(..., listeners=[MyListener()]) @@ -19,10 +24,9 @@ class PoolListener(object): p.add_listener(MyListener()) # usage with create_engine() - e = create_engine("url://", ...) - e.pool.add_listener(MyListener()) + e = create_engine("url://", listeners=[MyListener()]) - All of the standard connection [sqlalchemy.pool#Pool] types can + All of the standard connection :class:`~sqlalchemy.pool.Pool` types can accept event listeners for key connection lifecycle events: creation, pool check-out and check-in. There are no events fired when a connection closes. diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index ad19d7969..2f1a423f3 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -101,8 +101,16 @@ __all__ = ( def scoped_session(session_factory, scopefunc=None): """Provides thread-local management of Sessions. - This is a front-end function to the [sqlalchemy.orm.scoping#ScopedSession] - class. + This is a front-end function to + :class:`~sqlalchemy.orm.scoping.ScopedSession`. + + :param session_factory: a callable function that produces + :class:`Session` instances, such as :func:`sessionmaker` or + :func:`create_session`. + + :param scopefunc: optional, TODO + + :returns: an :class:`~sqlalchemy.orm.scoping.ScopedSession` instance Usage:: @@ -130,18 +138,31 @@ def scoped_session(session_factory, scopefunc=None): return ScopedSession(session_factory, scopefunc=scopefunc) def create_session(bind=None, **kwargs): - """create a new [sqlalchemy.orm.session#Session]. - - The defaults of create_session() are the opposite of - that of sessionmaker(); autoflush and expire_on_commit - are false, autocommit is True. - In this sense the session acts more like the "classic" - SQLAlchemy 0.3 session with these defaults. - - It is recommended to use the [sqlalchemy.orm#sessionmaker()] function - instead of create_session(). - """ + """Create a new :class:`~sqlalchemy.orm.session.Session`. + + :param bind: optional, a single Connectable to use for all + database access in the created + :class:`~sqlalchemy.orm.session.Session`. + + :param \*\*kwargs: optional, passed through to the + :class:`Session` constructor. + + :returns: an :class:`~sqlalchemy.orm.session.Session` instance + + The defaults of create_session() are the opposite of that of + :func:`sessionmaker`; ``autoflush`` and ``expire_on_commit`` are + False, ``autocommit`` is True. In this sense the session acts + more like the "classic" SQLAlchemy 0.3 session with these. + + Usage:: + + >>> from sqlalchemy.orm import create_session + >>> session = create_session() + + It is recommended to use :func:`sessionmaker` instead of + create_session(). + """ if 'transactional' in kwargs: sa_util.warn_deprecated( "The 'transactional' argument to sessionmaker() is deprecated; " @@ -159,209 +180,224 @@ def relation(argument, secondary=None, **kwargs): """Provide a relationship of a primary Mapper to a secondary Mapper. This corresponds to a parent-child or associative table relationship. The - constructed class is an instance of - [sqlalchemy.orm.properties#RelationProperty]. - - argument - a class or Mapper instance, representing the target of the relation. - - secondary - for a many-to-many relationship, specifies the intermediary table. The - ``secondary`` keyword argument should generally only be used for a - table that is not otherwise expressed in any class mapping. In - particular, using the Association Object Pattern is generally mutually - exclusive against using the ``secondary`` keyword argument. - - \**kwargs follow: - - backref - indicates the name of a property to be placed on the related mapper's - class that will handle this relationship in the other direction, - including synchronizing the object attributes on both sides of the - relation. Can also point to a ``backref()`` construct for more - configurability. - - cascade - a comma-separated list of cascade rules which determines how Session - operations should be "cascaded" from parent to child. This defaults - to "False", which means the default cascade should be used. - The default value is "save-update, merge". - Available cascades are: - - save-update - cascade the "add()" operation - (formerly known as save() and update()) - - merge - cascade the "merge()" operation - - expunge - cascade the "expunge()" operation - - delete - cascade the "delete()" operation - - delete-orphan - if an item of the child's type with no parent is detected, - mark it for deletion. Note that this option prevents a pending item - of the child's class from being persisted without a parent - present. - - refresh-expire - cascade the expire() and refresh() operations - - all - shorthand for "save-update,merge, refresh-expire, expunge, delete" - - collection_class - a class or function that returns a new list-holding object. will be - used in place of a plain list for storing elements. - - comparator_factory - a class which extends ``sqlalchemy.orm.properties.RelationProperty.Comparator`` - which provides custom SQL clause generation for comparison operations. - - extension - an [sqlalchemy.orm.interfaces#AttributeExtension] instance, - or list of extensions, which will be prepended to the list of - attribute listeners for the resulting descriptor placed on the class. - These listeners will receive append and set events before the - operation proceeds, and may be used to halt (via exception throw) - or change the value used in the operation. - - foreign_keys - a list of columns which are to be used as "foreign key" columns. - this parameter should be used in conjunction with explicit - ``primaryjoin`` and ``secondaryjoin`` (if needed) arguments, and the - columns within the ``foreign_keys`` list should be present within - those join conditions. Normally, ``relation()`` will inspect the - columns within the join conditions to determine which columns are - the "foreign key" columns, based on information in the ``Table`` - metadata. Use this argument when no ForeignKey's are present in the - join condition, or to override the table-defined foreign keys. - - join_depth=None - when non-``None``, an integer value indicating how many levels deep - eagerload joins should be constructed on a self-referring or - cyclical relationship. The number counts how many times the same - Mapper shall be present in the loading condition along a particular - join branch. When left at its default of ``None``, eager loads will - automatically stop chaining joins when they encounter a mapper which - is already higher up in the chain. - - lazy=(True|False|None|'dynamic') - specifies how the related items should be loaded. Values include: - - True - items should be loaded lazily when the property is first - accessed. - - False - items should be loaded "eagerly" in the same query as that - of the parent, using a JOIN or LEFT OUTER JOIN. - - None - no loading should occur at any time. This is to support - "write-only" attributes, or attributes which are populated - in some manner specific to the application. - - 'dynamic' - a ``DynaLoader`` will be attached, which returns a - ``Query`` object for all read operations. The - dynamic- collection supports only ``append()`` and - ``remove()`` for write operations; changes to the - dynamic property will not be visible until the data is - flushed to the database. - - order_by - indicates the ordering that should be applied when loading these - items. - - passive_deletes=False - Indicates loading behavior during delete operations. - - A value of True indicates that unloaded child items should not be - loaded during a delete operation on the parent. Normally, when a - parent item is deleted, all child items are loaded so that they can - either be marked as deleted, or have their foreign key to the parent - set to NULL. Marking this flag as True usually implies an ON DELETE - <CASCADE|SET NULL> rule is in place which will handle - updating/deleting child rows on the database side. - - Additionally, setting the flag to the string value 'all' will - disable the "nulling out" of the child foreign keys, when there is - no delete or delete-orphan cascade enabled. This is typically used - when a triggering or error raise scenario is in place on the - database side. Note that the foreign key attributes on in-session - child objects will not be changed after a flush occurs so this is a - very special use-case setting. - - passive_updates=True - Indicates loading and INSERT/UPDATE/DELETE behavior when the source - of a foreign key value changes (i.e. an "on update" cascade), which - are typically the primary key columns of the source row. - - When True, it is assumed that ON UPDATE CASCADE is configured on the - foreign key in the database, and that the database will handle - propagation of an UPDATE from a source column to dependent rows. - Note that with databases which enforce referential integrity - (i.e. Postgres, MySQL with InnoDB tables), ON UPDATE CASCADE is - required for this operation. The relation() will update the value - of the attribute on related items which are locally present in the - session during a flush. - - When False, it is assumed that the database does not enforce - referential integrity and will not be issuing its own CASCADE - operation for an update. The relation() will issue the appropriate - UPDATE statements to the database in response to the change of a - referenced key, and items locally present in the session during a - flush will also be refreshed. - - This flag should probably be set to False if primary key changes are - expected and the database in use doesn't support CASCADE - (i.e. SQLite, MySQL MyISAM tables). - - post_update - this indicates that the relationship should be handled by a second - UPDATE statement after an INSERT or before a DELETE. Currently, it - also will issue an UPDATE after the instance was UPDATEd as well, - although this technically should be improved. This flag is used to - handle saving bi-directional dependencies between two individual - rows (i.e. each row references the other), where it would otherwise - be impossible to INSERT or DELETE both rows fully since one row - exists before the other. Use this flag when a particular mapping - arrangement will incur two rows that are dependent on each other, - such as a table that has a one-to-many relationship to a set of - child rows, and also has a column that references a single child row - within that list (i.e. both tables contain a foreign key to each - other). If a ``flush()`` operation returns an error that a "cyclical - dependency" was detected, this is a cue that you might want to use - ``post_update`` to "break" the cycle. - - primaryjoin - a ClauseElement that will be used as the primary join of this child - object against the parent object, or in a many-to-many relationship - the join of the primary object to the association table. By default, - this value is computed based on the foreign key relationships of the - parent and child tables (or association table). - - remote_side - used for self-referential relationships, indicates the column or - list of columns that form the "remote side" of the relationship. - - secondaryjoin - a ClauseElement that will be used as the join of an association - table to the child object. By default, this value is computed based - on the foreign key relationships of the association and child - tables. - - uselist=(True|False) - a boolean that indicates if this property should be loaded as a list - or a scalar. In most cases, this value is determined automatically - by ``relation()``, based on the type and direction of the - relationship - one to many forms a list, many to one forms a scalar, - many to many is a list. If a scalar is desired where normally a list - would be present, such as a bi-directional one-to-one relationship, - set uselist to False. - - viewonly=False - when set to True, the relation is used only for loading objects - within the relationship, and has no effect on the unit-of-work flush - process. Relations with viewonly can specify any kind of join - conditions to provide additional views of related objects onto a - parent object. Note that the functionality of a viewonly - relationship has its limits - complicated join conditions may not - compile into eager or lazy loaders properly. If this is the case, - use an alternative method. + constructed class is an instance of :class:`RelationProperty`. + + A typical :func:`relation`:: + + mapper(Parent, properties={ + 'children': relation(Children) + }) + + :param argument: + a class or :class:`Mapper` instance, representing the target of + the relation. + + :param secondary: + for a many-to-many relationship, specifies the intermediary + table. The *secondary* keyword argument should generally only + be used for a table that is not otherwise expressed in any class + mapping. In particular, using the Association Object Pattern is + generally mutually exclusive with the use of the *secondary* + keyword argument. + + :param backref: + indicates the name of a property to be placed on the related + mapper's class that will handle this relationship in the other + direction, including synchronizing the object attributes on both + sides of the relation. Can also point to a :func:`backref` for + more configurability. + + :param cascade: + a comma-separated list of cascade rules which determines how + Session operations should be "cascaded" from parent to child. + This defaults to ``False``, which means the default cascade + should be used. The default value is ``"save-update, merge"``. + + Available cascades are: + + ``save-update`` - cascade the "add()" operation (formerly + known as save() and update()) + + ``merge`` - cascade the "merge()" operation + + ``expunge`` - cascade the "expunge()" operation + + ``delete`` - cascade the "delete()" operation + + ``delete-orphan`` - if an item of the child's type with no + parent is detected, mark it for deletion. Note that this + option prevents a pending item of the child's class from being + persisted without a parent present. + + ``refresh-expire`` - cascade the expire() and refresh() + operations + + ``all`` - shorthand for "save-update,merge, refresh-expire, + expunge, delete" + + :param collection_class: + a class or callable that returns a new list-holding object. will + be used in place of a plain list for storing elements. + + :param comparator_factory: + a class which extends :class:`RelationProperty.Comparator` which + provides custom SQL clause generation for comparison operations. + + :param extension: + an :class:`AttributeExtension` instance, or list of extensions, + which will be prepended to the list of attribute listeners for + the resulting descriptor placed on the class. These listeners + will receive append and set events before the operation + proceeds, and may be used to halt (via exception throw) or + change the value used in the operation. + + :param foreign_keys: + + a list of columns which are to be used as "foreign key" columns. + this parameter should be used in conjunction with explicit + ``primaryjoin`` and ``secondaryjoin`` (if needed) arguments, and + the columns within the ``foreign_keys`` list should be present + within those join conditions. Normally, ``relation()`` will + inspect the columns within the join conditions to determine + which columns are the "foreign key" columns, based on + information in the ``Table`` metadata. Use this argument when no + ForeignKey's are present in the join condition, or to override + the table-defined foreign keys. + + :param join_depth: + when non-``None``, an integer value indicating how many levels + deep eagerload joins should be constructed on a self-referring + or cyclical relationship. The number counts how many times the + same Mapper shall be present in the loading condition along a + particular join branch. When left at its default of ``None``, + eager loads will automatically stop chaining joins when they + encounter a mapper which is already higher up in the chain. + + :param lazy=(True|False|None|'dynamic'): + specifies how the related items should be loaded. Values include: + + True - items should be loaded lazily when the property is first + accessed. + + False - items should be loaded "eagerly" in the same query as + that of the parent, using a JOIN or LEFT OUTER JOIN. + + None - no loading should occur at any time. This is to support + "write-only" attributes, or attributes which are + populated in some manner specific to the application. + + 'dynamic' - a ``DynaLoader`` will be attached, which returns a + ``Query`` object for all read operations. The + dynamic- collection supports only ``append()`` and + ``remove()`` for write operations; changes to the + dynamic property will not be visible until the data + is flushed to the database. + + :param order_by: + indicates the ordering that should be applied when loading these + items. + + :param passive_deletes=False: + Indicates loading behavior during delete operations. + + A value of True indicates that unloaded child items should not + be loaded during a delete operation on the parent. Normally, + when a parent item is deleted, all child items are loaded so + that they can either be marked as deleted, or have their + foreign key to the parent set to NULL. Marking this flag as + True usually implies an ON DELETE <CASCADE|SET NULL> rule is in + place which will handle updating/deleting child rows on the + database side. + + Additionally, setting the flag to the string value 'all' will + disable the "nulling out" of the child foreign keys, when there + is no delete or delete-orphan cascade enabled. This is + typically used when a triggering or error raise scenario is in + place on the database side. Note that the foreign key + attributes on in-session child objects will not be changed + after a flush occurs so this is a very special use-case + setting. + + :param passive_updates=True: + Indicates loading and INSERT/UPDATE/DELETE behavior when the + source of a foreign key value changes (i.e. an "on update" + cascade), which are typically the primary key columns of the + source row. + + When True, it is assumed that ON UPDATE CASCADE is configured on + the foreign key in the database, and that the database will + handle propagation of an UPDATE from a source column to + dependent rows. Note that with databases which enforce + referential integrity (i.e. Postgres, MySQL with InnoDB tables), + ON UPDATE CASCADE is required for this operation. The + relation() will update the value of the attribute on related + items which are locally present in the session during a flush. + + When False, it is assumed that the database does not enforce + referential integrity and will not be issuing its own CASCADE + operation for an update. The relation() will issue the + appropriate UPDATE statements to the database in response to the + change of a referenced key, and items locally present in the + session during a flush will also be refreshed. + + This flag should probably be set to False if primary key changes + are expected and the database in use doesn't support CASCADE + (i.e. SQLite, MySQL MyISAM tables). + + :param post_update: + this indicates that the relationship should be handled by a + second UPDATE statement after an INSERT or before a + DELETE. Currently, it also will issue an UPDATE after the + instance was UPDATEd as well, although this technically should + be improved. This flag is used to handle saving bi-directional + dependencies between two individual rows (i.e. each row + references the other), where it would otherwise be impossible to + INSERT or DELETE both rows fully since one row exists before the + other. Use this flag when a particular mapping arrangement will + incur two rows that are dependent on each other, such as a table + that has a one-to-many relationship to a set of child rows, and + also has a column that references a single child row within that + list (i.e. both tables contain a foreign key to each other). If + a ``flush()`` operation returns an error that a "cyclical + dependency" was detected, this is a cue that you might want to + use ``post_update`` to "break" the cycle. + + :param primaryjoin: + a ClauseElement that will be used as the primary join of this + child object against the parent object, or in a many-to-many + relationship the join of the primary object to the association + table. By default, this value is computed based on the foreign + key relationships of the parent and child tables (or association + table). + + :param remote_side: + used for self-referential relationships, indicates the column or + list of columns that form the "remote side" of the relationship. + + :param secondaryjoin: + a ClauseElement that will be used as the join of an association + table to the child object. By default, this value is computed + based on the foreign key relationships of the association and + child tables. + + :param uselist=(True|False): + a boolean that indicates if this property should be loaded as a + list or a scalar. In most cases, this value is determined + automatically by ``relation()``, based on the type and direction + of the relationship - one to many forms a list, many to one + forms a scalar, many to many is a list. If a scalar is desired + where normally a list would be present, such as a bi-directional + one-to-one relationship, set uselist to False. + + :param viewonly=False: + when set to True, the relation is used only for loading objects + within the relationship, and has no effect on the unit-of-work + flush process. Relations with viewonly can specify any kind of + join conditions to provide additional views of related objects + onto a parent object. Note that the functionality of a viewonly + relationship has its limits - complicated join conditions may + not compile into eager or lazy loaders properly. If this is the + case, use an alternative method. """ return RelationProperty(argument, secondary=secondary, **kwargs) @@ -371,13 +407,29 @@ def dynamic_loader(argument, secondary=None, primaryjoin=None, secondaryjoin=Non passive_deletes=False, order_by=None, comparator_factory=None): """Construct a dynamically-loading mapper property. - This property is similar to relation(), except read operations return an - active Query object, which reads from the database in all cases. Items - may be appended to the attribute via append(), or removed via remove(); - changes will be persisted to the database during a flush(). However, no - other list mutation operations are available. + This property is similar to :func:`relation`, except read + operations return an active :class:`Query` object which reads from + the database when accessed. Items may be appended to the + attribute via ``append()``, or removed via ``remove()``; changes + will be persisted to the database during a :meth:`Sesion.flush`. + However, no other Python list or collection mutation operations + are available. + + A subset of arguments available to :func:`relation` are available + here. + + :param argument: + a class or :class:`Mapper` instance, representing the target of + the relation. + + :param secondary: + for a many-to-many relationship, specifies the intermediary + table. The *secondary* keyword argument should generally only + be used for a table that is not otherwise expressed in any class + mapping. In particular, using the Association Object Pattern is + generally mutually exclusive with the use of the *secondary* + keyword argument. - A subset of arguments available to relation() are available here. """ from sqlalchemy.orm.dynamic import DynaLoader @@ -414,10 +466,10 @@ def column_property(*args, **kwargs): when True, the column property is "deferred", meaning that it does not load immediately, and is instead loaded when the attribute is first accessed on an instance. See also - [sqlalchemy.orm#deferred()]. + :func:`~sqlalchemy.orm.deferred`. extension - an [sqlalchemy.orm.interfaces#AttributeExtension] instance, + an :class:`~sqlalchemy.orm.interfaces.AttributeExtension` instance, or list of extensions, which will be prepended to the list of attribute listeners for the resulting descriptor placed on the class. These listeners will receive append and set events before the @@ -449,14 +501,14 @@ def composite(class_, *cols, **kwargs): return self.x, self.y def __eq__(self, other): return other is not None and self.x == other.x and self.y == other.y - + # and then in the mapping: ... composite(Point, mytable.c.x, mytable.c.y) ... The composite object may have its attributes populated based on the names of the mapped columns. To override the way internal state is set, - additionally implement ``__set_composite_values__``: - + additionally implement ``__set_composite_values__``:: + class Point(object): def __init__(self, x, y): self.some_x = x @@ -483,14 +535,14 @@ def composite(class_, *cols, **kwargs): deferred When True, the column property is "deferred", meaning that it does not load immediately, and is instead loaded when the attribute is first - accessed on an instance. See also [sqlalchemy.orm#deferred()]. + accessed on an instance. See also :func:`~sqlalchemy.orm.deferred`. comparator_factory a class which extends ``sqlalchemy.orm.properties.CompositeProperty.Comparator`` which provides custom SQL clause generation for comparison operations. extension - an [sqlalchemy.orm.interfaces#AttributeExtension] instance, + an :class:`~sqlalchemy.orm.interfaces.AttributeExtension` instance, or list of extensions, which will be prepended to the list of attribute listeners for the resulting descriptor placed on the class. These listeners will receive append and set events before the @@ -522,7 +574,7 @@ def deferred(*columns, **kwargs): return ColumnProperty(deferred=True, *columns, **kwargs) def mapper(class_, local_table=None, *args, **params): - """Return a new [sqlalchemy.orm#Mapper] object. + """Return a new :class:`~sqlalchemy.orm.Mapper` object. class\_ The class to be mapped. @@ -537,7 +589,7 @@ def mapper(class_, local_table=None, *args, **params): erasing any in-memory changes with whatever information was loaded from the database. Usage of this flag is highly discouraged; as an alternative, see the method `populate_existing()` on - [sqlalchemy.orm.query#Query]. + :class:`~sqlalchemy.orm.query.Query`. allow_column_override If True, allows the usage of a ``relation()`` which has the @@ -568,7 +620,7 @@ def mapper(class_, local_table=None, *args, **params): with its parent mapper. extension - A [sqlalchemy.orm#MapperExtension] instance or list of + A :class:`~sqlalchemy.orm.MapperExtension` instance or list of ``MapperExtension`` instances which will be applied to all operations by this ``Mapper``. @@ -681,7 +733,7 @@ def mapper(class_, local_table=None, *args, **params): def synonym(name, map_column=False, descriptor=None, comparator_factory=None, proxy=False): """Set up `name` as a synonym to another mapped property. - Used with the ``properties`` dictionary sent to [sqlalchemy.orm#mapper()]. + Used with the ``properties`` dictionary sent to :func:`~sqlalchemy.orm.mapper`. Any existing attributes on the class which map the key name sent to the ``properties`` dictionary will be used by the synonym to provide @@ -743,7 +795,7 @@ def comparable_property(comparator_factory, descriptor=None): mapper(MyClass, mytable, properties=dict( 'myprop': comparable_property(MyComparator))) - Used with the ``properties`` dictionary sent to [sqlalchemy.orm#mapper()]. + Used with the ``properties`` dictionary sent to :func:`~sqlalchemy.orm.mapper`. comparator_factory A PropComparator subclass or factory that defines operator behavior diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py index 609ed0ca1..25664f258 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -6,12 +6,11 @@ """ -Semi-private implementation objects which form the basis of ORM-mapped -attributes, query options and mapper extension. +Semi-private module containing various base classes used throughout the ORM. -Defines the [sqlalchemy.orm.interfaces#MapperExtension] class, which can be -end-user subclassed to add event-based functionality to mappers. The -remainder of this module is generally private to the ORM. +Defines the extension classes :class:`MapperExtension`, +:class:`SessionExtension`, and :class:`AttributeExtension` as +well as other user-subclassable extension objects. """ @@ -135,7 +134,7 @@ class MapperExtension(object): \**flags extra information about the row, same as criterion in - ``create_row_processor()`` method of [sqlalchemy.orm.interfaces#MapperProperty] + ``create_row_processor()`` method of :class:`~sqlalchemy.orm.interfaces.MapperProperty` """ return EXT_CONTINUE diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 9c62cadd9..cc3517f75 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -6,11 +6,11 @@ """Logic to map Python classes to and from selectables. -Defines the [sqlalchemy.orm.mapper#Mapper] class, the central configurational +Defines the :class:`~sqlalchemy.orm.mapper.Mapper` class, the central configurational unit which associates a class with a database table. This is a semi-private module; the main configurational API of the ORM is -available in [sqlalchemy.orm#]. +available in :class:`~sqlalchemy.orm.`. """ @@ -66,7 +66,7 @@ class Mapper(object): columns. Instances of this class should be constructed via the - [sqlalchemy.orm#mapper()] function. + :func:`~sqlalchemy.orm.mapper` function. """ def __init__(self, @@ -97,7 +97,7 @@ class Mapper(object): eager_defaults=False): """Construct a new mapper. - Mappers are normally constructed via the [sqlalchemy.orm#mapper()] + Mappers are normally constructed via the :func:`~sqlalchemy.orm.mapper` function. See for details. """ @@ -1141,11 +1141,11 @@ class Mapper(object): """Iterate each element and its mapper in an object graph, for all relations that meet the given cascade rule. - type\_ + ``type\_``: The name of the cascade rule (i.e. save-update, delete, etc.) - state + ``state``: The lead InstanceState. child items will be processed per the relations defined for this object's mapper. diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 88357f34c..291837dfa 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -6,11 +6,11 @@ """The Query class and support. -Defines the [sqlalchemy.orm.query#Query] class, the central construct used by +Defines the :class:`~sqlalchemy.orm.query.Query` class, the central construct used by the ORM to construct database queries. The ``Query`` class should not be confused with the -[sqlalchemy.sql.expression#Select] class, which defines database SELECT +:class:`~sqlalchemy.sql.expression.Select` class, which defines database SELECT operations at the SQL (non-ORM) level. ``Query`` differs from ``Select`` in that it returns ORM-mapped objects and interacts with an ORM session, whereas the ``Select`` construct interacts directly with the database to return @@ -367,26 +367,26 @@ class Query(object): instances will also have those columns already loaded so that no "post fetch" of those columns will be required. - :param cls_or_mappers: - a single class or mapper, or list of class/mappers, - which inherit from this Query's mapper. Alternatively, it - may also be the string ``'*'``, in which case all descending - mappers will be added to the FROM clause. - - :param selectable: - a table or select() statement that will - be used in place of the generated FROM clause. This argument - is required if any of the desired mappers use concrete table - inheritance, since SQLAlchemy currently cannot generate UNIONs - among tables automatically. If used, the ``selectable`` - argument must represent the full set of tables and columns mapped - by every desired mapper. Otherwise, the unaccounted mapped columns - will result in their table being appended directly to the FROM - clause which will usually lead to incorrect results. - - :param discriminator: - a column to be used as the "discriminator" - column for the given selectable. If not given, the polymorphic_on - attribute of the mapper will be used, if any. This is useful - for mappers that don't have polymorphic loading behavior by default, - such as concrete table mappers. + :param cls_or_mappers: a single class or mapper, or list of class/mappers, + which inherit from this Query's mapper. Alternatively, it + may also be the string ``'*'``, in which case all descending + mappers will be added to the FROM clause. + + :param selectable: a table or select() statement that will + be used in place of the generated FROM clause. This argument + is required if any of the desired mappers use concrete table + inheritance, since SQLAlchemy currently cannot generate UNIONs + among tables automatically. If used, the ``selectable`` + argument must represent the full set of tables and columns mapped + by every desired mapper. Otherwise, the unaccounted mapped columns + will result in their table being appended directly to the FROM + clause which will usually lead to incorrect results. + + :param discriminator: a column to be used as the "discriminator" + column for the given selectable. If not given, the polymorphic_on + attribute of the mapper will be used, if any. This is useful + for mappers that don't have polymorphic loading behavior by default, + such as concrete table mappers. """ entity = self._generate_mapper_zero() diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index b2764def4..86ce3de94 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -28,7 +28,7 @@ __all__ = ['Session', 'SessionTransaction', 'SessionExtension'] def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False, expire_on_commit=True, **kwargs): - """Generate a custom-configured [sqlalchemy.orm.session#Session] class. + """Generate a custom-configured :class:`~sqlalchemy.orm.session.Session` class. The returned object is a subclass of ``Session``, which, when instantiated with no arguments, uses the keyword arguments configured here as its @@ -139,7 +139,7 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False, transaction will load from the most recent database state. extension - An optional [sqlalchemy.orm.session#SessionExtension] instance, or + An optional :class:`~sqlalchemy.orm.session.SessionExtension` instance, or a list of such instances, which will receive pre- and post- commit and flush events, as well as a post-rollback event. User- defined code may be placed within these @@ -147,11 +147,11 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False, query_cls Class which should be used to create new Query objects, as returned - by the ``query()`` method. Defaults to [sqlalchemy.orm.query#Query]. + by the ``query()`` method. Defaults to :class:`~sqlalchemy.orm.query.Query`. twophase When ``True``, all transactions will be started using - [sqlalchemy.engine_TwoPhaseTransaction]. During a ``commit()``, after + :mod:~sqlalchemy.engine_TwoPhaseTransaction. During a ``commit()``, after ``flush()`` has been issued for all attached databases, the ``prepare()`` method on each database's ``TwoPhaseTransaction`` will be called. This allows each database to roll back the entire transaction, @@ -207,7 +207,7 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False, class SessionTransaction(object): """A Session-level transaction. - This corresponds to one or more [sqlalchemy.engine#Transaction] + This corresponds to one or more :class:`~sqlalchemy.engine.Transaction` instances behind the scenes, with one ``Transaction`` per ``Engine`` in use. @@ -515,7 +515,7 @@ class Session(object): is either to use mutexes to limit concurrent access to one thread at a time, or more commonly to establish a unique session for every thread, using a threadlocal variable. SQLAlchemy provides a thread-managed - Session adapter, provided by the [sqlalchemy.orm#scoped_session()] + Session adapter, provided by the :func:`~sqlalchemy.orm.scoped_session` function. """ @@ -534,7 +534,7 @@ class Session(object): """Construct a new Session. Arguments to ``Session`` are described using the - [sqlalchemy.orm#sessionmaker()] function. + :func:`~sqlalchemy.orm.sessionmaker` function. """ diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index 405acda15..0615f4136 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -48,7 +48,12 @@ class CascadeOptions(object): class Validator(AttributeExtension): - """Runs a validation method on an attribute value to be set or appended.""" + """Runs a validation method on an attribute value to be set or appended. + + The Validator class is used by the :func:`~sqlalchemy.orm.validates` + decorator, and direct access is usually not needed. + + """ def __init__(self, key, validator): """Construct a new Validator. @@ -260,7 +265,7 @@ class ORMAdapter(sql_util.ColumnAdapter): class AliasedClass(object): """Represents an 'alias'ed form of a mapped class for usage with Query. - The ORM equivalent of a sqlalchemy.sql.expression.Alias + The ORM equivalent of a :class:`~sqlalchemy.sql.expression.Alias` object, this object mimics the mapped class using a __getattr__ scheme and maintains a reference to a real Alias object. It indicates to Query that the @@ -404,7 +409,7 @@ def join(left, right, onclause=None, isouter=False): """Produce an inner join between left and right clauses. In addition to the interface provided by - sqlalchemy.sql.join(), left and right may be mapped + :func:`~sqlalchemy.sql.expression.join()`, left and right may be mapped classes or AliasedClass instances. The onclause may be a string name of a relation(), or a class-bound descriptor representing a relation. @@ -416,7 +421,7 @@ def outerjoin(left, right, onclause=None): """Produce a left outer join between left and right clauses. In addition to the interface provided by - sqlalchemy.sql.outerjoin(), left and right may be mapped + :func:`~sqlalchemy.sql.expression.outerjoin()`, left and right may be mapped classes or AliasedClass instances. The onclause may be a string name of a relation(), or a class-bound descriptor representing a relation. diff --git a/lib/sqlalchemy/pool.py b/lib/sqlalchemy/pool.py index 46307d19a..cd5ef800b 100644 --- a/lib/sqlalchemy/pool.py +++ b/lib/sqlalchemy/pool.py @@ -32,16 +32,13 @@ def manage(module, **params): creating new connection pools for each distinct set of connection arguments sent to the decorated module's connect() function. - Arguments: + :param module: a DB-API 2.0 database module - module - A DB-API 2.0 database module. + :param poolclass: the class used by the pool module to provide + pooling. Defaults to :class:`QueuePool`. - poolclass - The class used by the pool module to provide pooling. Defaults - to ``QueuePool``. + :param \*\*params: will be passed through to *poolclass* - See the ``Pool`` class for options. """ try: return proxies[module] @@ -59,65 +56,48 @@ def clear_managers(): proxies.clear() class Pool(object): - """Base class for connection pools. - - This is an abstract class, implemented by various subclasses - including: - - QueuePool - Pools multiple connections using ``Queue.Queue``. - - SingletonThreadPool - Stores a single connection per execution thread. - - NullPool - Doesn't do any pooling; opens and closes connections. - - AssertionPool - Stores only one connection, and asserts that only one connection - is checked out at a time. - - The main argument, `creator`, is a callable function that returns - a newly connected DB-API connection object. - - Options that are understood by Pool are: - - echo - If set to True, connections being pulled and retrieved from/to - the pool will be logged to the standard output, as well as pool - sizing information. Echoing can also be achieved by enabling - logging for the "sqlalchemy.pool" namespace. Defaults to False. - - use_threadlocal - If set to True, repeated calls to ``connect()`` within the same - application thread will be guaranteed to return the same - connection object, if one has already been retrieved from the - pool and has not been returned yet. This allows code to retrieve - a connection from the pool, and then while still holding on to - that connection, to call other functions which also ask the pool - for a connection of the same arguments; those functions will act - upon the same connection that the calling method is using. - Defaults to False. - - recycle - If set to non -1, a number of seconds between connection - recycling, which means upon checkout, if this timeout is - surpassed the connection will be closed and replaced with a - newly opened connection. Defaults to -1. - - listeners - A list of ``PoolListener``-like objects or dictionaries of callables - that receive events when DB-API connections are created, checked out and - checked in to the pool. - - reset_on_return - Defaults to True. Reset the database state of connections returned to - the pool. This is typically a ROLLBACK to release locks and transaction - resources. Disable at your own peril. + """Abstract base class for connection pools.""" - """ def __init__(self, creator, recycle=-1, echo=None, use_threadlocal=False, reset_on_return=True, listeners=None): + """Construct a Pool. + + :param creator: a callable function that returns a DB-API + connection object. The function will be called with + parameters. + + :param recycle: If set to non -1, number of seconds between + connection recycling, which means upon checkout, if this + timeout is surpassed the connection will be closed and + replaced with a newly opened connection. Defaults to -1. + + :param echo: If True, connections being pulled and retrieved + from the pool will be logged to the standard output, as well + as pool sizing information. Echoing can also be achieved by + enabling logging for the "sqlalchemy.pool" + namespace. Defaults to False. + + :param use_threadlocal: If set to True, repeated calls to + :meth:`connect` within the same application thread will be + guaranteed to return the same connection object, if one has + already been retrieved from the pool and has not been + returned yet. Offers a slight performance advantage at the + cost of individual transactions by default. The + :meth:`unique_connection` method is provided to bypass the + threadlocal behavior installed into :meth:`connect`. + + :param reset_on_return: If true, reset the database state of + connections returned to the pool. This is typically a + ROLLBACK to release locks and transaction resources. + Disable at your own peril. Defaults to True. + + :param listeners: A list of + :class:`~sqlalchemy.interfaces.PoolListener`-like objects or + dictionaries of callables that receive events when DB-API + connections are created, checked out and checked in to the + pool. + + """ self.logger = log.instance_logger(self, echoflag=echo) self._threadconns = threading.local() self._creator = creator @@ -545,37 +525,70 @@ class SingletonThreadPool(Pool): return c class QueuePool(Pool): - """A Pool that imposes a limit on the number of open connections. - - Arguments include all those used by the base Pool class, as well - as: - - pool_size - The size of the pool to be maintained. This is the largest - number of connections that will be kept persistently in the - pool. Note that the pool begins with no connections; once this - number of connections is requested, that number of connections - will remain. Defaults to 5. - - max_overflow - The maximum overflow size of the pool. When the number of - checked-out connections reaches the size set in pool_size, - additional connections will be returned up to this limit. When - those additional connections are returned to the pool, they are - disconnected and discarded. It follows then that the total - number of simultaneous connections the pool will allow is - pool_size + `max_overflow`, and the total number of "sleeping" - connections the pool will allow is pool_size. `max_overflow` can - be set to -1 to indicate no overflow limit; no limit will be - placed on the total number of concurrent connections. Defaults - to 10. - - timeout - The number of seconds to wait before giving up on returning a - connection. Defaults to 30. - """ + """A Pool that imposes a limit on the number of open connections.""" + + def __init__(self, creator, pool_size=5, max_overflow=10, timeout=30, + **params): + """Construct a QueuePool. + + :param creator: a callable function that returns a DB-API + connection object. The function will be called with + parameters. + + :param pool_size: The size of the pool to be maintained. This + is the largest number of connections that will be kept + persistently in the pool. Note that the pool begins with no + connections; once this number of connections is requested, + that number of connections will remain. Defaults to 5. + + :param max_overflow: The maximum overflow size of the + pool. When the number of checked-out connections reaches the + size set in pool_size, additional connections will be + returned up to this limit. When those additional connections + are returned to the pool, they are disconnected and + discarded. It follows then that the total number of + simultaneous connections the pool will allow is pool_size + + `max_overflow`, and the total number of "sleeping" + connections the pool will allow is pool_size. `max_overflow` + can be set to -1 to indicate no overflow limit; no limit + will be placed on the total number of concurrent + connections. Defaults to 10. + + :param timeout: The number of seconds to wait before giving up + on returning a connection. Defaults to 30. + + :param recycle: If set to non -1, number of seconds between + connection recycling, which means upon checkout, if this + timeout is surpassed the connection will be closed and + replaced with a newly opened connection. Defaults to -1. + + :param echo: If True, connections being pulled and retrieved + from the pool will be logged to the standard output, as well + as pool sizing information. Echoing can also be achieved by + enabling logging for the "sqlalchemy.pool" + namespace. Defaults to False. + + :param use_threadlocal: If set to True, repeated calls to + :meth:`connect` within the same application thread will be + guaranteed to return the same connection object, if one has + already been retrieved from the pool and has not been + returned yet. Offers a slight performance advantage at the + cost of individual transactions by default. The + :meth:`unique_connection` method is provided to bypass the + threadlocal behavior installed into :meth:`connect`. + + :param reset_on_return: If true, reset the database state of + connections returned to the pool. This is typically a + ROLLBACK to release locks and transaction resources. + Disable at your own peril. Defaults to True. + + :param listeners: A list of + :class:`~sqlalchemy.interfaces.PoolListener`-like objects or + dictionaries of callables that receive events when DB-API + connections are created, checked out and checked in to the + pool. - def __init__(self, creator, pool_size = 5, max_overflow = 10, timeout=30, **params): + """ Pool.__init__(self, creator, **params) self._pool = Queue.Queue(pool_size) self._overflow = 0 - pool_size @@ -660,6 +673,7 @@ class NullPool(Pool): Instead it literally opens and closes the underlying DB-API connection per each connection open/close. + """ def status(self): @@ -678,6 +692,44 @@ class StaticPool(Pool): """A Pool of exactly one connection, used for all requests.""" def __init__(self, creator, **params): + """Construct a StaticPool. + + :param creator: a callable function that returns a DB-API + connection object. The function will be called with + parameters. + + :param recycle: If set to non -1, number of seconds between + connection recycling, which means upon checkout, if this + timeout is surpassed the connection will be closed and + replaced with a newly opened connection. Defaults to -1. + + :param echo: If True, connections being pulled and retrieved + from the pool will be logged to the standard output, as well + as pool sizing information. Echoing can also be achieved by + enabling logging for the "sqlalchemy.pool" + namespace. Defaults to False. + + :param use_threadlocal: If set to True, repeated calls to + :meth:`connect` within the same application thread will be + guaranteed to return the same connection object, if one has + already been retrieved from the pool and has not been + returned yet. Offers a slight performance advantage at the + cost of individual transactions by default. The + :meth:`unique_connection` method is provided to bypass the + threadlocal behavior installed into :meth:`connect`. + + :param reset_on_return: If true, reset the database state of + connections returned to the pool. This is typically a + ROLLBACK to release locks and transaction resources. + Disable at your own peril. Defaults to True. + + :param listeners: A list of + :class:`~sqlalchemy.interfaces.PoolListener`-like objects or + dictionaries of callables that receive events when DB-API + connections are created, checked out and checked in to the + pool. + + """ Pool.__init__(self, creator, **params) self._conn = creator() self.connection = _ConnectionRecord(self) @@ -688,7 +740,7 @@ class StaticPool(Pool): def dispose(self): self._conn.close() self._conn = None - + def create_connection(self): return self._conn @@ -708,11 +760,50 @@ class AssertionPool(Pool): This will raise an exception if more than one connection is checked out at a time. Useful for debugging code that is using more connections than desired. + """ ## TODO: modify this to handle an arbitrary connection count. def __init__(self, creator, **params): + """Construct an AssertionPool. + + :param creator: a callable function that returns a DB-API + connection object. The function will be called with + parameters. + + :param recycle: If set to non -1, number of seconds between + connection recycling, which means upon checkout, if this + timeout is surpassed the connection will be closed and + replaced with a newly opened connection. Defaults to -1. + + :param echo: If True, connections being pulled and retrieved + from the pool will be logged to the standard output, as well + as pool sizing information. Echoing can also be achieved by + enabling logging for the "sqlalchemy.pool" + namespace. Defaults to False. + + :param use_threadlocal: If set to True, repeated calls to + :meth:`connect` within the same application thread will be + guaranteed to return the same connection object, if one has + already been retrieved from the pool and has not been + returned yet. Offers a slight performance advantage at the + cost of individual transactions by default. The + :meth:`unique_connection` method is provided to bypass the + threadlocal behavior installed into :meth:`connect`. + + :param reset_on_return: If true, reset the database state of + connections returned to the pool. This is typically a + ROLLBACK to release locks and transaction resources. + Disable at your own peril. Defaults to True. + + :param listeners: A list of + :class:`~sqlalchemy.interfaces.PoolListener`-like objects or + dictionaries of callables that receive events when DB-API + connections are created, checked out and checked in to the + pool. + + """ Pool.__init__(self, creator, **params) self.connection = _ConnectionRecord(self) self._conn = self.connection diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index e9e49ba0e..481a462ae 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -10,19 +10,19 @@ Each element within this module describes a database entity which can be created and dropped, or is otherwise part of such an entity. Examples include tables, columns, sequences, and indexes. -All entities are subclasses of [sqlalchemy.schema#SchemaItem], and as defined +All entities are subclasses of :class:`~sqlalchemy.schema.SchemaItem`, and as defined in this module they are intended to be agnostic of any vendor-specific constructs. A collection of entities are grouped into a unit called -[sqlalchemy.schema#MetaData]. MetaData serves as a logical grouping of schema +:class:`~sqlalchemy.schema.MetaData`. MetaData serves as a logical grouping of schema elements, and can also be associated with an actual database connection such that operations involving the contained elements can contact the database as needed. Two of the elements here also build upon their "syntactic" counterparts, which -are defined in [sqlalchemy.sql.expression#], specifically -[sqlalchemy.schema#Table] and [sqlalchemy.schema#Column]. Since these objects +are defined in :class:`~sqlalchemy.sql.expression.`, specifically +:class:`~sqlalchemy.schema.Table` and :class:`~sqlalchemy.schema.Column`. Since these objects are part of the SQL expression language, they are usable as components in SQL expressions. @@ -38,7 +38,7 @@ __all__ = ['SchemaItem', 'Table', 'Column', 'ForeignKey', 'Sequence', 'Index', 'UniqueConstraint', 'DefaultGenerator', 'Constraint', 'MetaData', 'ThreadLocalMetaData', 'SchemaVisitor', 'PassiveDefault', 'DefaulClause', 'FetchedValue', 'ColumnDefault', 'DDL'] - +__all__.sort() class SchemaItem(visitors.Visitable): """Base class for items that define a database schema.""" @@ -408,7 +408,7 @@ class Table(SchemaItem, expression.TableClause): args.append(c.copy(schema=schema)) return Table(self.name, metadata, schema=schema, *args) -class Column(SchemaItem, expression._ColumnClause): +class Column(SchemaItem, expression.ColumnClause): """Represent a column in a database table. This is a subclass of ``expression.ColumnClause`` and represents an actual @@ -719,7 +719,7 @@ class Column(SchemaItem, expression._ColumnClause): return [x for x in (self.default, self.onupdate) if x is not None] + \ list(self.foreign_keys) + list(self.constraints) else: - return expression._ColumnClause.get_children(self, **kwargs) + return expression.ColumnClause.get_children(self, **kwargs) class ForeignKey(SchemaItem): @@ -1416,7 +1416,7 @@ class MetaData(SchemaItem): """A collection of Tables and their associated schema constructs. Holds a collection of Tables and an optional binding to an ``Engine`` or - ``Connection``. If bound, the [sqlalchemy.schema#Table] objects in the + ``Connection``. If bound, the :class:`~sqlalchemy.schema.Table` objects in the collection and their columns may participate in implicit SQL execution. The `Table` objects themselves are stored in the `metadata.tables` @@ -1729,8 +1729,6 @@ class ThreadLocalMetaData(MetaData): ``connect()``. You can also re-bind dynamically multiple times per thread, just like a regular ``MetaData``. - Use this type of MetaData when your tables are present in more than one - database and you need to address them simultanesouly. """ __visit_name__ = 'metadata' diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py index b83c9ab20..747978e76 100644 --- a/lib/sqlalchemy/sql/compiler.py +++ b/lib/sqlalchemy/sql/compiler.py @@ -6,13 +6,13 @@ """Base SQL and DDL compiler implementations. -Provides the [sqlalchemy.sql.compiler#DefaultCompiler] class, which is +Provides the :class:`~sqlalchemy.sql.compiler.DefaultCompiler` class, which is responsible for generating all SQL query strings, as well as -[sqlalchemy.sql.compiler#SchemaGenerator] and [sqlalchemy.sql.compiler#SchemaDropper] +:class:`~sqlalchemy.sql.compiler.SchemaGenerator` and :class:`~sqlalchemy.sql.compiler.SchemaDropper` which issue CREATE and DROP DDL for tables, sequences, and indexes. The elements in this module are used by public-facing constructs like -[sqlalchemy.sql.expression#ClauseElement] and [sqlalchemy.engine#Engine]. +:class:`~sqlalchemy.sql.expression.ClauseElement` and :class:`~sqlalchemy.engine.Engine`. While dialect authors will want to be familiar with this module for the purpose of creating database-specific compilers and schema generators, the module is otherwise internal to SQLAlchemy. @@ -455,7 +455,7 @@ class DefaultCompiler(engine.Compiled): if \ asfrom and \ - isinstance(column, sql._ColumnClause) and \ + isinstance(column, sql.ColumnClause) and \ not column.is_literal and \ column.table is not None and \ not isinstance(column.table, sql.Select): diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py index 0bc7e6a49..4a1fab166 100644 --- a/lib/sqlalchemy/sql/expression.py +++ b/lib/sqlalchemy/sql/expression.py @@ -7,7 +7,7 @@ """Defines the base components of SQL expression trees. All components are derived from a common base class -[sqlalchemy.sql.expression#ClauseElement]. Common behaviors are organized +:class:`~sqlalchemy.sql.expression.ClauseElement`. Common behaviors are organized based on class hierarchies, in some cases via mixins. All object construction from this package occurs via functions which @@ -74,10 +74,10 @@ def asc(column): def outerjoin(left, right, onclause=None): """Return an ``OUTER JOIN`` clause element. - The returned object is an instance of [sqlalchemy.sql.expression#Join]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.Join`. Similar functionality is also available via the ``outerjoin()`` - method on any [sqlalchemy.sql.expression#FromClause]. + method on any :class:`~sqlalchemy.sql.expression.FromClause`. left The left side of the join. @@ -99,10 +99,10 @@ def outerjoin(left, right, onclause=None): def join(left, right, onclause=None, isouter=False): """Return a ``JOIN`` clause element (regular inner join). - The returned object is an instance of [sqlalchemy.sql.expression#Join]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.Join`. Similar functionality is also available via the ``join()`` method - on any [sqlalchemy.sql.expression#FromClause]. + on any :class:`~sqlalchemy.sql.expression.FromClause`. left The left side of the join. @@ -125,9 +125,9 @@ def select(columns=None, whereclause=None, from_obj=[], **kwargs): """Returns a ``SELECT`` clause element. Similar functionality is also available via the ``select()`` - method on any [sqlalchemy.sql.expression#FromClause]. + method on any :class:`~sqlalchemy.sql.expression.FromClause`. - The returned object is an instance of [sqlalchemy.sql.expression#Select]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.Select`. All arguments which accept ``ClauseElement`` arguments also accept string arguments, which will be converted as appropriate into @@ -249,24 +249,24 @@ def select(columns=None, whereclause=None, from_obj=[], **kwargs): return s def subquery(alias, *args, **kwargs): - """Return an [sqlalchemy.sql.expression#Alias] object derived from a [sqlalchemy.sql.expression#Select]. + """Return an :class:`~sqlalchemy.sql.expression.Alias` object derived from a :class:`~sqlalchemy.sql.expression.Select`. name alias name \*args, \**kwargs - all other arguments are delivered to the [sqlalchemy.sql.expression#select()] + all other arguments are delivered to the :func:`~sqlalchemy.sql.expression.select` function. """ return Select(*args, **kwargs).alias(alias) def insert(table, values=None, inline=False, **kwargs): - """Return an [sqlalchemy.sql.expression#Insert] clause element. + """Return an :class:`~sqlalchemy.sql.expression.Insert` clause element. Similar functionality is available via the ``insert()`` method on - [sqlalchemy.schema#Table]. + :class:`~sqlalchemy.schema.Table`. table The table to be inserted into. @@ -307,10 +307,10 @@ def insert(table, values=None, inline=False, **kwargs): return Insert(table, values, inline=inline, **kwargs) def update(table, whereclause=None, values=None, inline=False, **kwargs): - """Return an [sqlalchemy.sql.expression#Update] clause element. + """Return an :class:`~sqlalchemy.sql.expression.Update` clause element. Similar functionality is available via the ``update()`` method on - [sqlalchemy.schema#Table]. + :class:`~sqlalchemy.schema.Table`. table The table to be updated. @@ -352,10 +352,10 @@ def update(table, whereclause=None, values=None, inline=False, **kwargs): return Update(table, whereclause=whereclause, values=values, inline=inline, **kwargs) def delete(table, whereclause = None, **kwargs): - """Return a [sqlalchemy.sql.expression#Delete] clause element. + """Return a :class:`~sqlalchemy.sql.expression.Delete` clause element. Similar functionality is available via the ``delete()`` method on - [sqlalchemy.schema#Table]. + :class:`~sqlalchemy.schema.Table`. table The table to be updated. @@ -371,7 +371,7 @@ def and_(*clauses): """Join a list of clauses together using the ``AND`` operator. The ``&`` operator is also overloaded on all - [sqlalchemy.sql.expression#_CompareMixin] subclasses to produce the same + :class:`~sqlalchemy.sql.expression._CompareMixin` subclasses to produce the same result. """ @@ -383,7 +383,7 @@ def or_(*clauses): """Join a list of clauses together using the ``OR`` operator. The ``|`` operator is also overloaded on all - [sqlalchemy.sql.expression#_CompareMixin] subclasses to produce the same + :class:`~sqlalchemy.sql.expression._CompareMixin` subclasses to produce the same result. """ @@ -395,7 +395,7 @@ def not_(clause): """Return a negation of the given clause, i.e. ``NOT(clause)``. The ``~`` operator is also overloaded on all - [sqlalchemy.sql.expression#_CompareMixin] subclasses to produce the same + :class:`~sqlalchemy.sql.expression._CompareMixin` subclasses to produce the same result. """ @@ -411,7 +411,7 @@ def between(ctest, cleft, cright): Equivalent of SQL ``clausetest BETWEEN clauseleft AND clauseright``. - The ``between()`` method on all [sqlalchemy.sql.expression#_CompareMixin] subclasses + The ``between()`` method on all :class:`~sqlalchemy.sql.expression._CompareMixin` subclasses provides similar functionality. """ @@ -491,7 +491,7 @@ def cast(clause, totype, **kwargs): Equivalent of SQL ``CAST(clause AS totype)``. - Use with a [sqlalchemy.types#TypeEngine] subclass, i.e:: + Use with a :class:`~sqlalchemy.types.TypeEngine` subclass, i.e:: cast(table.c.unit_price * table.c.qty, Numeric(10,4)) @@ -517,7 +517,7 @@ def collate(expression, collation): operator=operators.collate, group=False) def exists(*args, **kwargs): - """Return an ``EXISTS`` clause as applied to a [sqlalchemy.sql.expression#Select] object. + """Return an ``EXISTS`` clause as applied to a :class:`~sqlalchemy.sql.expression.Select` object. Calling styles are of the following forms:: @@ -538,17 +538,17 @@ def exists(*args, **kwargs): def union(*selects, **kwargs): """Return a ``UNION`` of multiple selectables. - The returned object is an instance of [sqlalchemy.sql.expression#CompoundSelect]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.CompoundSelect`. A similar ``union()`` method is available on all - [sqlalchemy.sql.expression#FromClause] subclasses. + :class:`~sqlalchemy.sql.expression.FromClause` subclasses. \*selects - a list of [sqlalchemy.sql.expression#Select] instances. + a list of :class:`~sqlalchemy.sql.expression.Select` instances. \**kwargs available keyword arguments are the same as those of - [sqlalchemy.sql.expression#select()]. + :func:`~sqlalchemy.sql.expression.select`. """ return _compound_select('UNION', *selects, **kwargs) @@ -556,17 +556,17 @@ def union(*selects, **kwargs): def union_all(*selects, **kwargs): """Return a ``UNION ALL`` of multiple selectables. - The returned object is an instance of [sqlalchemy.sql.expression#CompoundSelect]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.CompoundSelect`. A similar ``union_all()`` method is available on all - [sqlalchemy.sql.expression#FromClause] subclasses. + :class:`~sqlalchemy.sql.expression.FromClause` subclasses. \*selects - a list of [sqlalchemy.sql.expression#Select] instances. + a list of :class:`~sqlalchemy.sql.expression.Select` instances. \**kwargs available keyword arguments are the same as those of - [sqlalchemy.sql.expression#select()]. + :func:`~sqlalchemy.sql.expression.select`. """ return _compound_select('UNION ALL', *selects, **kwargs) @@ -574,14 +574,14 @@ def union_all(*selects, **kwargs): def except_(*selects, **kwargs): """Return an ``EXCEPT`` of multiple selectables. - The returned object is an instance of [sqlalchemy.sql.expression#CompoundSelect]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.CompoundSelect`. \*selects - a list of [sqlalchemy.sql.expression#Select] instances. + a list of :class:`~sqlalchemy.sql.expression.Select` instances. \**kwargs available keyword arguments are the same as those of - [sqlalchemy.sql.expression#select()]. + :func:`~sqlalchemy.sql.expression.select`. """ return _compound_select('EXCEPT', *selects, **kwargs) @@ -589,14 +589,14 @@ def except_(*selects, **kwargs): def except_all(*selects, **kwargs): """Return an ``EXCEPT ALL`` of multiple selectables. - The returned object is an instance of [sqlalchemy.sql.expression#CompoundSelect]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.CompoundSelect`. \*selects - a list of [sqlalchemy.sql.expression#Select] instances. + a list of :class:`~sqlalchemy.sql.expression.Select` instances. \**kwargs available keyword arguments are the same as those of - [sqlalchemy.sql.expression#select()]. + :func:`~sqlalchemy.sql.expression.select`. """ return _compound_select('EXCEPT ALL', *selects, **kwargs) @@ -604,14 +604,14 @@ def except_all(*selects, **kwargs): def intersect(*selects, **kwargs): """Return an ``INTERSECT`` of multiple selectables. - The returned object is an instance of [sqlalchemy.sql.expression#CompoundSelect]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.CompoundSelect`. \*selects - a list of [sqlalchemy.sql.expression#Select] instances. + a list of :class:`~sqlalchemy.sql.expression.Select` instances. \**kwargs available keyword arguments are the same as those of - [sqlalchemy.sql.expression#select()]. + :func:`~sqlalchemy.sql.expression.select`. """ return _compound_select('INTERSECT', *selects, **kwargs) @@ -619,22 +619,22 @@ def intersect(*selects, **kwargs): def intersect_all(*selects, **kwargs): """Return an ``INTERSECT ALL`` of multiple selectables. - The returned object is an instance of [sqlalchemy.sql.expression#CompoundSelect]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression.CompoundSelect`. \*selects - a list of [sqlalchemy.sql.expression#Select] instances. + a list of :class:`~sqlalchemy.sql.expression.Select` instances. \**kwargs available keyword arguments are the same as those of - [sqlalchemy.sql.expression#select()]. + :func:`~sqlalchemy.sql.expression.select`. """ return _compound_select('INTERSECT ALL', *selects, **kwargs) def alias(selectable, alias=None): - """Return an [sqlalchemy.sql.expression#Alias] object. + """Return an :class:`~sqlalchemy.sql.expression.Alias` object. - An ``Alias`` represents any [sqlalchemy.sql.expression#FromClause] with + An ``Alias`` represents any :class:`~sqlalchemy.sql.expression.FromClause` with an alternate name assigned within SQL, typically using the ``AS`` clause when generated, e.g. ``SELECT * FROM table AS aliasname``. @@ -659,10 +659,10 @@ def literal(value, type_=None): Literal clauses are created automatically when non- ``ClauseElement`` objects (such as strings, ints, dates, etc.) are used in a comparison operation with a - [sqlalchemy.sql.expression#_CompareMixin] subclass, such as a ``Column`` + :class:`~sqlalchemy.sql.expression._CompareMixin` subclass, such as a ``Column`` object. Use this function to force the generation of a literal clause, which will be created as a - [sqlalchemy.sql.expression#_BindParamClause] with a bound value. + :class:`~sqlalchemy.sql.expression._BindParamClause` with a bound value. value the value to be bound. Can be any Python object supported by @@ -670,14 +670,14 @@ def literal(value, type_=None): argument. type\_ - an optional [sqlalchemy.types#TypeEngine] which will provide + an optional :class:`~sqlalchemy.types.TypeEngine` which will provide bind-parameter translation for this literal. """ return _BindParamClause(None, value, type_=type_, unique=True) def label(name, obj): - """Return a [sqlalchemy.sql.expression#_Label] object for the given [sqlalchemy.sql.expression#ColumnElement]. + """Return a :class:`~sqlalchemy.sql.expression._Label` object for the given :class:`~sqlalchemy.sql.expression.ColumnElement`. A label changes the name of an element in the columns clause of a ``SELECT`` statement, typically via the ``AS`` SQL keyword. @@ -697,22 +697,22 @@ def label(name, obj): 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 [sqlalchemy.sql.expression#_ColumnClause], + The object returned is an instance of :class:`~sqlalchemy.sql.expression.ColumnClause`, which represents the "syntactical" portion of the schema-level - [sqlalchemy.schema#Column] object. + :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 - [sqlalchemy.sql.expression#literal_column()] function. + :func:`~sqlalchemy.sql.expression.literal_column` function. type\_ - an optional [sqlalchemy.types#TypeEngine] object which will + an optional :class:`~sqlalchemy.types.TypeEngine` object which will provide result-set translation for this column. """ - return _ColumnClause(text, type_=type_) + return ColumnClause(text, type_=type_) def literal_column(text, type_=None): """Return a textual column expression, as would be in the columns @@ -728,20 +728,20 @@ def literal_column(text, type_=None): 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 - [sqlalchemy.sql.expression#column()] function. + :func:`~sqlalchemy.sql.expression.column` function. type\_ - an optional [sqlalchemy.types#TypeEngine] object which will provide + 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) + return ColumnClause(text, type_=type_, is_literal=True) def table(name, *columns): - """Return a [sqlalchemy.sql.expression#Table] object. + """Return a :class:`~sqlalchemy.sql.expression.Table` object. - This is a primitive version of the [sqlalchemy.schema#Table] object, + This is a primitive version of the :class:`~sqlalchemy.schema.Table` object, which is a subclass of this object. """ @@ -767,7 +767,7 @@ def bindparam(key, value=None, shortname=None, type_=None, unique=False): mostly useful with value-based bind params. """ - if isinstance(key, _ColumnClause): + if isinstance(key, ColumnClause): return _BindParamClause(key.name, value, type_=key.type, unique=unique, shortname=shortname) else: return _BindParamClause(key, value, type_=type_, unique=unique, shortname=shortname) @@ -777,7 +777,7 @@ def outparam(key, type_=None): The ``outparam`` can be used like a regular function parameter. The "output" value will be available from the - [sqlalchemy.engine#ResultProxy] object via its ``out_parameters`` + :class:`~sqlalchemy.engine.ResultProxy` object via its ``out_parameters`` attribute, which returns a dictionary containing the values. """ @@ -1136,7 +1136,7 @@ class ClauseElement(Visitable): def compile(self, bind=None, column_keys=None, compiler=None, dialect=None, inline=False): """Compile this SQL expression. - The return value is a [sqlalchemy.engine#Compiled] object. + The return value is a :class:`~sqlalchemy.engine.Compiled` object. Calling `str()` or `unicode()` on the returned value will yield a string representation of the result. The ``Compiled`` object also can return a dictionary of bind parameter names and @@ -1605,10 +1605,10 @@ class ColumnElement(ClauseElement, _CompareMixin): """ if name: - co = _ColumnClause(name, selectable, type_=getattr(self, 'type', None)) + co = ColumnClause(name, selectable, type_=getattr(self, 'type', None)) else: name = str(self) - co = _ColumnClause(self.anon_label, selectable, type_=getattr(self, 'type', None)) + co = ColumnClause(self.anon_label, selectable, type_=getattr(self, 'type', None)) co.proxies = [self] selectable.columns[name] = co @@ -2706,12 +2706,12 @@ class _Label(ColumnElement): e.proxies.append(self) return e -class _ColumnClause(_Immutable, ColumnElement): +class ColumnClause(_Immutable, ColumnElement): """Represents a generic column expression from any textual string. This includes columns associated with tables, aliases and select statements, but also any arbitrary text. May or may not be bound - to an underlying ``Selectable``. ``_ColumnClause`` is usually + to an underlying ``Selectable``. ``ColumnClause`` is usually created publically via the ``column()`` function or the ``literal_column()`` function. @@ -2722,15 +2722,15 @@ class _ColumnClause(_Immutable, ColumnElement): parent selectable. type - ``TypeEngine`` object which can associate this ``_ColumnClause`` + ``TypeEngine`` object which can associate this ``ColumnClause`` with a type. is_literal - if True, the ``_ColumnClause`` is assumed to be an exact + if True, the ``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 ``literal_column()`` function is usually used to create such a - ``_ColumnClause``. + ``ColumnClause``. """ def __init__(self, text, selectable=None, type_=None, is_literal=False): @@ -2771,7 +2771,7 @@ class _ColumnClause(_Immutable, ColumnElement): if name is None: return self else: - return super(_ColumnClause, self).label(name) + return super(ColumnClause, self).label(name) @property def _from_objects(self): @@ -2787,7 +2787,7 @@ class _ColumnClause(_Immutable, ColumnElement): # propagate the "is_literal" flag only if we are keeping our name, # otherwise its considered to be a label is_literal = self.is_literal and (name is None or name == self.name) - c = _ColumnClause(name or self.name, selectable=selectable, type_=self.type, is_literal=is_literal) + c = ColumnClause(name or self.name, selectable=selectable, type_=self.type, is_literal=is_literal) c.proxies = [self] if attach: selectable.columns[c.name] = c @@ -2892,7 +2892,7 @@ class _SelectBaseMixin(object): Typically, a select statement which has only one column in its columns clause is eligible to be used as a scalar expression. - The returned object is an instance of [sqlalchemy.sql.expression#_ScalarSelect]. + The returned object is an instance of :class:`~sqlalchemy.sql.expression._ScalarSelect`. """ return _ScalarSelect(self) @@ -3016,6 +3016,8 @@ class _ScalarSelect(_Grouping): return list(self.inner_columns)[0]._make_proxy(selectable, name) class CompoundSelect(_SelectBaseMixin, FromClause): + """Forms the basis of ``UNION``, ``UNION ALL``, and other SELECT-based set operations.""" + def __init__(self, keyword, *selects, **kwargs): self._should_correlate = kwargs.pop('correlate', False) self.keyword = keyword @@ -3087,11 +3089,11 @@ class Select(_SelectBaseMixin, FromClause): """Construct a Select object. The public constructor for Select is the - [sqlalchemy.sql.expression#select()] function; see that function for + :func:`~sqlalchemy.sql.expression.select` function; see that function for argument descriptions. Additional generative and mutator methods are available on the - [sqlalchemy.sql.expression#_SelectBaseMixin] superclass. + :class:`~sqlalchemy.sql.expression._SelectBaseMixin` superclass. """ self._should_correlate = correlate diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py index 87901b266..8b62910ac 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -75,7 +75,7 @@ class random(GenericFunction): GenericFunction.__init__(self, args=args, **kwargs) class count(GenericFunction): - """The ANSI COUNT aggregate function. With no arguments, emits COUNT *.""" + """The ANSI COUNT aggregate function. With no arguments, emits COUNT \*.""" __return_type__ = sqltypes.Integer diff --git a/lib/sqlalchemy/types.py b/lib/sqlalchemy/types.py index 084ec5117..0ca251eb1 100644 --- a/lib/sqlalchemy/types.py +++ b/lib/sqlalchemy/types.py @@ -5,7 +5,7 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """defines genericized SQL types, each represented by a subclass of -[sqlalchemy.types#AbstractType]. Dialects define further subclasses of these +:class:`~sqlalchemy.types.AbstractType`. Dialects define further subclasses of these types. For more information see the SQLAlchemy documentation on types. @@ -49,17 +49,22 @@ class AbstractType(object): return None def compare_values(self, x, y): - """compare two values for equality.""" + """Compare two values for equality.""" return x == y def is_mutable(self): - """return True if the target Python type is 'mutable'. + """Return True if the target Python type is 'mutable'. - This allows systems like the ORM to know if an object - can be considered 'not changed' by identity alone. - """ + This allows systems like the ORM to know if a column value can + be considered 'not changed' by comparing the identity of + objects alone. + + Use the :class:`MutableType` mixin or override this method to + return True in custom types that hold mutable values such as + ``dict``, ``list`` and custom objects. + """ return False def get_dbapi_type(self, dbapi): @@ -67,14 +72,14 @@ class AbstractType(object): This can be useful for calling ``setinputsizes()``, for example. """ - return None def adapt_operator(self, op): - """given an operator from the sqlalchemy.sql.operators package, + """Given an operator from the sqlalchemy.sql.operators package, translate it to a new operator based on the semantics of this type. - By default, returns the operator unchanged.""" + By default, returns the operator unchanged. + """ return op def __repr__(self): @@ -84,6 +89,38 @@ class AbstractType(object): for k in inspect.getargspec(self.__init__)[0][1:])) class TypeEngine(AbstractType): + """Base for built-in types. + + May be sub-classed to create entirely new types. Example:: + + import sqlalchemy.types as types + + class MyType(types.TypeEngine): + def __init__(self, precision = 8): + self.precision = precision + + def get_col_spec(self): + return "MYTYPE(%s)" % self.precision + + def bind_processor(self, dialect): + def process(value): + return value + return process + + def result_processor(self, dialect): + def process(value): + return value + return process + + Once the type is made, it's immediately usable:: + + table = Table('foo', meta, + Column('id', Integer, primary_key=True), + Column('data', MyType(16)) + ) + + """ + def dialect_impl(self, dialect, **kwargs): try: return self._impl_dict[dialect] @@ -99,12 +136,31 @@ class TypeEngine(AbstractType): return d def get_col_spec(self): + """Return the DDL representation for this type.""" raise NotImplementedError() def bind_processor(self, dialect): + """Return a conversion function for processing bind values. + + Returns a callable which will receive a bind parameter value + as the sole positional argument and will return a value to + send to the DB-API. + + If processing is not necessary, the method should return ``None``. + + """ return None def result_processor(self, dialect): + """Return a conversion function for processing result row values. + + Returns a callable which will receive a result row column + value as the sole positional argument and will return a value + to return to the user. + + If processing is not necessary, the method should return ``None``. + + """ return None def adapt(self, cls): @@ -120,25 +176,44 @@ class TypeEngine(AbstractType): class TypeDecorator(AbstractType): """Allows the creation of types which add additional functionality - to an existing type. Typical usage:: - - class MyCustomType(TypeDecorator): - impl = String - + to an existing type. + + Typical usage:: + + import sqlalchemy.types as types + + class MyType(types.TypeDecorator): + # Prefixes Unicode values with "PREFIX:" on the way in and + # strips it off on the way out. + + impl = types.Unicode + def process_bind_param(self, value, dialect): - return value + "incoming string" - + return "PREFIX:" + value + def process_result_value(self, value, dialect): - return value[0:-16] - + return value[7:] + + def copy(self): + return MyType(self.impl.length) + The class-level "impl" variable is required, and can reference any - TypeEngine class. Alternatively, the load_dialect_impl() method can - be used to provide different type classes based on the dialect given; - in this case, the "impl" variable can reference ``TypeEngine`` as a - placeholder. - + TypeEngine class. Alternatively, the load_dialect_impl() method + can be used to provide different type classes based on the dialect + given; in this case, the "impl" variable can reference + ``TypeEngine`` as a placeholder. + + The reason that type behavior is modified using class decoration + instead of subclassing is due to the way dialect specific types + are used. Such as with the example above, when using the mysql + dialect, the actual type in use will be a + ``sqlalchemy.databases.mysql.MSString`` instance. + ``TypeDecorator`` handles the mechanics of passing the values + between user-defined ``process_`` methods and the current + dialect-specific type in use. + """ - + def __init__(self, *args, **kwargs): if not hasattr(self.__class__, 'impl'): raise AssertionError("TypeDecorator implementations require a class-level variable 'impl' which refers to the class of type being decorated") @@ -162,7 +237,7 @@ class TypeDecorator(AbstractType): return tt def load_dialect_impl(self, dialect): - """loads the dialect-specific implementation of this type. + """Loads the dialect-specific implementation of this type. by default calls dialect.type_descriptor(self.impl), but can be overridden to provide different behavior. @@ -233,15 +308,23 @@ class TypeDecorator(AbstractType): return self.impl.is_mutable() class MutableType(object): - """A mixin that marks a Type as holding a mutable object.""" + """A mixin that marks a Type as holding a mutable object. + + :meth:`copy_value` and :meth:`compare_values` should be customized + as needed to match the needs of the object. + + """ def is_mutable(self): + """Return True, mutable.""" return True def copy_value(self, value): + """Unimplemented.""" raise NotImplementedError() def compare_values(self, x, y): + """Compare *x* == *y*.""" return x == y def to_instance(typeobj): @@ -275,14 +358,29 @@ def adapt_type(typeobj, colspecs): return typeobj.adapt(impltype) class NullType(TypeEngine): + """An unknown type. + + NullTypes will stand in if :class:`~sqlalchemy.Table` reflection + encounters a column data type unknown to SQLAlchemy. The + resulting columns are nearly fully usable: the DB-API adapter will + handle all translation to and from the database data type. + + NullType does not have sufficient information to particpate in a + ``CREATE TABLE`` statement and will raise an exception if + encountered during a :meth:`~sqlalchemy.Table.create` operation. + + """ + def get_col_spec(self): raise NotImplementedError() NullTypeEngine = NullType class Concatenable(object): - """marks a type as supporting 'concatenation'""" + """A mixin that marks a type as supporting 'concatenation', typically strings.""" + def adapt_operator(self, op): + """Converts an add operator to concat.""" from sqlalchemy.sql import operators if op == operators.add: return operators.concat_op @@ -290,18 +388,51 @@ class Concatenable(object): return op class String(Concatenable, TypeEngine): - """A sized string type. + """The base for all string and character types. In SQL, corresponds to VARCHAR. Can also take Python unicode objects and encode to the database's encoding in bind params (and the reverse for result sets.) - The `length` field is usually required when the `String` type is used within a - CREATE TABLE statement, since VARCHAR requires a length on most databases. - Currently SQLite is an exception to this. - + The `length` field is usually required when the `String` type is + used within a CREATE TABLE statement, as VARCHAR requires a length + on most databases. + """ + def __init__(self, length=None, convert_unicode=False, assert_unicode=None): + """Create a string-holding type. + + :param length: optional, a length for the column for use in + DDL statements. May be safely omitted if no ``CREATE + TABLE`` will be issued. Certain databases may require a + *length* for use in DDL, and will raise an exception when + the ``CREATE TABLE`` DDL is issued. Whether the value is + interpreted as bytes or characters is database specific. + + :param convert_unicode: defaults to False. If True, convert + ``unicode`` data sent to the database to a ``str`` + bytestring, and convert bytestrings coming back from the + database into ``unicode``. + + Bytestrings are encoded using the dialect's + :attr:`~sqlalchemy.engine.base.Dialect.encoding`, which + defaults to `utf-8`. + + If False, may be overridden by + :attr:`sqlalchemy.engine.base.Dialect.convert_unicode`. + + :param assert_unicode: + + If None (the default), no assertion will take place unless + overridden by :attr:`sqlalchemy.engine.base.Dialect.assert_unicode`. + + If 'warn', will issue a runtime warning if a ``str`` + instance is used as a bind value. + + If true, will raise an :exc:`sqlalchemy.exc.InvalidRequestError`. + + """ self.length = length self.convert_unicode = convert_unicode self.assert_unicode = assert_unicode @@ -346,13 +477,56 @@ class String(Concatenable, TypeEngine): return dbapi.STRING class Text(String): + """A variably sized string type. + + In SQL, usually corresponds to CLOB or TEXT. Can also take Python + unicode objects and encode to the database's encoding in bind + params (and the reverse for result sets.) + + """ def dialect_impl(self, dialect, **kwargs): return TypeEngine.dialect_impl(self, dialect, **kwargs) class Unicode(String): - """A synonym for String(length, convert_unicode=True, assert_unicode='warn').""" + """A variable length Unicode string. + + The ``Unicode`` type is a :class:`String` which converts Python + ``unicode`` objects (i.e., strings that are defined as + ``u'somevalue'``) into encoded bytestrings when passing the value + to the database driver, and similarly decodes values from the + database back into Python ``unicode`` objects. + + When using the ``Unicode`` type, it is only appropriate to pass + Python ``unicode`` objects, and not plain ``str``. If a + bytestring (``str``) is passed, a runtime warning is issued. If + you notice your application raising these warnings but you're not + sure where, the Python ``warnings`` filter can be used to turn + these warnings into exceptions which will illustrate a stack + trace:: + + import warnings + warnings.simplefilter('error') + + Bytestrings sent to and received from the database are encoded + using the dialect's + :attr:`~sqlalchemy.engine.base.Dialect.encoding`, which defaults + to `utf-8`. + + A synonym for String(length, convert_unicode=True, assert_unicode='warn'). + + """ def __init__(self, length=None, **kwargs): + """Create a Unicode-converting String type. + + :param length: optional, a length for the column for use in + DDL statements. May be safely omitted if no ``CREATE + TABLE`` will be issued. Certain databases may require a + *length* for use in DDL, and will raise an exception when + the ``CREATE TABLE`` DDL is issued. Whether the value is + interpreted as bytes or characters is database specific. + + """ kwargs.setdefault('convert_unicode', True) kwargs.setdefault('assert_unicode', 'warn') super(Unicode, self).__init__(length=length, **kwargs) @@ -361,25 +535,59 @@ class UnicodeText(Text): """A synonym for Text(convert_unicode=True, assert_unicode='warn').""" def __init__(self, length=None, **kwargs): + """Create a Unicode-converting Text type. + + :param length: optional, a length for the column for use in + DDL statements. May be safely omitted if no ``CREATE + TABLE`` will be issued. Certain databases may require a + *length* for use in DDL, and will raise an exception when + the ``CREATE TABLE`` DDL is issued. Whether the value is + interpreted as bytes or characters is database specific. + + """ kwargs.setdefault('convert_unicode', True) kwargs.setdefault('assert_unicode', 'warn') super(UnicodeText, self).__init__(length=length, **kwargs) + class Integer(TypeEngine): - """Integer datatype.""" + """A type for ``int`` integers.""" def get_dbapi_type(self, dbapi): return dbapi.NUMBER + class SmallInteger(Integer): - """Smallint datatype.""" + """A type for smaller ``int`` integers. + + Typically generates a ``SMALLINT`` in DDL, and otherwise acts like + a normal :class:`Integer` on the Python side. + + """ Smallinteger = SmallInteger class Numeric(TypeEngine): - """Numeric datatype, usually resolves to DECIMAL or NUMERIC.""" + """A type for fixed precision numbers. + + Typically generates DECIMAL or NUMERIC. Returns + ``decimal.Decimal`` objects by default. + + """ def __init__(self, precision=10, scale=2, asdecimal=True, length=None): + """Construct a Numeric. + + :param precision: the numeric precision for use in DDL ``CREATE TABLE``. + + :param scale: the numeric scale for use in DDL ``CREATE TABLE``. + + :param asdecimal: default True. If False, values will be + returned as-is from the DB-API, and may be either + ``Decimal`` or ``float`` types depending on the DB-API in + use. + + """ if length: util.warn_deprecated("'length' is deprecated for Numeric. Use 'scale'.") scale = length @@ -412,16 +620,33 @@ class Numeric(TypeEngine): else: return None + class Float(Numeric): - def __init__(self, precision = 10, asdecimal=False, **kwargs): + """A type for ``float`` numbers.""" + + def __init__(self, precision=10, asdecimal=False, **kwargs): + """Construct a Float. + + :param precision: the numeric precision for use in DDL ``CREATE TABLE``. + + """ self.precision = precision self.asdecimal = asdecimal def adapt(self, impltype): return impltype(precision=self.precision, asdecimal=self.asdecimal) + class DateTime(TypeEngine): - """Implement a type for ``datetime.datetime()`` objects.""" + """A type for ``datetime.datetime()`` objects. + + Date and time types return objects from the Python ``datetime`` + module. Most DBAPIs have built in support for the datetime + module, with the noted exception of SQLite. In the case of + SQLite, date and time types are stored as strings which are then + converted back to datetime objects when rows are returned. + + """ def __init__(self, timezone=False): self.timezone = timezone @@ -432,14 +657,16 @@ class DateTime(TypeEngine): def get_dbapi_type(self, dbapi): return dbapi.DATETIME + class Date(TypeEngine): - """Implement a type for ``datetime.date()`` objects.""" + """A type for ``datetime.date()`` objects.""" def get_dbapi_type(self, dbapi): return dbapi.DATETIME + class Time(TypeEngine): - """Implement a type for ``datetime.time()`` objects.""" + """A type for ``datetime.time()`` objects.""" def __init__(self, timezone=False): self.timezone = timezone @@ -450,8 +677,26 @@ class Time(TypeEngine): def get_dbapi_type(self, dbapi): return dbapi.DATETIME + class Binary(TypeEngine): + """A type for binary byte data. + + The Binary type generates BLOB or BYTEA when tables are created, + and also converts incoming values using the ``Binary`` callable + provided by each DB-API. + + """ + def __init__(self, length=None): + """Construct a Binary type. + + :param length: optional, a length for the column for use in + DDL statements. May be safely omitted if no ``CREATE + TABLE`` will be issued. Certain databases may require a + *length* for use in DDL, and will raise an exception when + the ``CREATE TABLE`` DDL is issued. + + """ self.length = length def bind_processor(self, dialect): @@ -469,10 +714,37 @@ class Binary(TypeEngine): def get_dbapi_type(self, dbapi): return dbapi.BINARY + class PickleType(MutableType, TypeDecorator): + """Holds Python objects. + + PickleType builds upon the Binary type to apply Python's + ``pickle.dumps()`` to incoming objects, and ``pickle.loads()`` on + the way out, allowing any pickleable Python object to be stored as + a serialized binary field. + + """ + impl = Binary def __init__(self, protocol=pickle.HIGHEST_PROTOCOL, pickler=None, mutable=True, comparator=None): + """Construct a PickleType. + + :param protocol: defaults to ``pickle.HIGHEST_PROTOCOL``. + + :param pickler: defaults to cPickle.pickle or pickle.pickle if + cPickle is not available. May be any object with + pickle-compatible ``dumps` and ``loads`` methods. + + :param mutable: defaults to True; implements + :meth:`AbstractType.is_mutable`. + + :param comparator: optional. a 2-arg callable predicate used + to compare values of this type. Defaults to equality if + *mutable* is False or ``pickler.dumps()`` equality if + *mutable* is True. + + """ self.protocol = protocol self.pickler = pickler or pickle self.mutable = mutable @@ -509,20 +781,24 @@ class PickleType(MutableType, TypeDecorator): def is_mutable(self): return self.mutable + class Boolean(TypeEngine): - pass + """A bool datatype. + + Boolean typically uses BOOLEAN or SMALLINT on the DDL side, and on + the Python side deals in ``True`` or ``False``. + + """ + class Interval(TypeDecorator): - """Type to be used in Column statements to store python timedeltas. + """A type for ``datetime.timedelta()`` objects. - If it's possible it uses native engine features to store timedeltas - (now it's only PostgreSQL Interval type), if there is no such it - fallbacks to DateTime storage with converting from/to timedelta on the fly + The Interval type deals with ``datetime.timedelta`` objects. In + PostgreSQL, the native ``INTERVAL`` type is used; for others, the + value is stored as a date which is relative to the "epoch" + (Jan. 1, 1970). - Converting is very simple - just use epoch(zero timestamp, 01.01.1970) as - base, so if we need to store timedelta = 1 day (24 hours) in database it - will be stored as DateTime = '2nd Jan 1970 00:00', see bind_processor - and result_processor to actual conversion code """ impl = TypeEngine |