# engine/__init__.py
# Copyright (C) 2005,2006 Michael Bayer mike_mp@zzzcomputing.com
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
from sqlalchemy import databases
from sqlalchemy.engine.base import *
from sqlalchemy.engine import strategies
import re
def engine_descriptors():
"""provides a listing of all the database implementations supported. this data
is provided as a list of dictionaries, where each dictionary contains the following
key/value pairs:
name : the name of the engine, suitable for use in the create_engine function
description: a plain description of the engine.
arguments : a dictionary describing the name and description of each parameter
used to connect to this engine's underlying DBAPI.
This function is meant for usage in automated configuration tools that wish to
query the user for database and connection information.
"""
result = []
#for module in sqlalchemy.databases.__all__:
for module in ['sqlite', 'postgres', 'mysql']:
module = getattr(__import__('sqlalchemy.databases.%s' % module).databases, module)
result.append(module.descriptor())
return result
default_strategy = 'plain'
def create_engine(*args, **kwargs):
"""creates a new Engine instance. Using the given strategy name,
locates that strategy and invokes its create() method to produce the Engine.
The strategies themselves are instances of EngineStrategy, and the built in
ones are present in the sqlalchemy.engine.strategies module. 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 DBAPI 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
connection and transaction without the need for explicit passing of a Connection object.
The standard method of specifying the engine is via URL as the first positional
argument, to indicate the appropriate database dialect and connection arguments, with additional
keyword arguments sent as options to the dialect and resulting Engine.
The URL is in the form <dialect>://opt1=val1&opt2=val2.
Where <dialect> is a name such as "mysql", "oracle", "postgres", and the options indicate
username, password, database, etc. Supported keynames include "username", "user", "password",
"pw", "db", "database", "host", "filename".
**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:
pool=None : 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). If None,
a default DBProxy will be created using the engine's own database module with the given
arguments.
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. 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=None : a file-like object where logging output can be sent, if echo is set to True.
This defaults to sys.stdout.
encoding='utf-8' : the encoding to be used when encoding/decoding Unicode strings
convert_unicode=False : True if unicode conversion should be applied to all str types
module=None : used by Oracle and Postgres, this is a reference to a DBAPI2 module to be used
instead of the engine's default module. For Postgres, the default is psycopg2, or psycopg1 if
2 cannot be found. For Oracle, its cx_Oracle. For mysql, MySQLdb.
use_ansi=True : used only by Oracle; when False, the Oracle driver attempts to support a
particular "quirk" of some Oracle databases, that the LEFT OUTER JOIN SQL syntax is not
supported, and the "Oracle join" syntax of using <column1>(+)=<column2> must be used
in order to achieve a LEFT OUTER JOIN. Its advised that the Oracle database be configured to
have full ANSI support instead of using this feature.
"""
strategy = kwargs.pop('strategy', default_strategy)
strategy = strategies.strategies[strategy]
return strategy.create(*args, **kwargs)
|