1453 lines
53 KiB
Python
1453 lines
53 KiB
Python
import _jpype
|
|
from . import _jinit
|
|
from . import _jcustomizer
|
|
from . import types as _jtypes
|
|
import typing
|
|
import _jpype
|
|
import time
|
|
import threading
|
|
import datetime
|
|
|
|
# TODO
|
|
# - Callable procedures
|
|
# - Isolation levels
|
|
# - Default adaptors
|
|
# - A complete testbench
|
|
# - Testbench with more than one DB
|
|
# - Documentation
|
|
|
|
# This a generic implementation of PEP-249
|
|
__all__ = ['ARRAY', 'ASCII_STREAM', 'BIGINT', 'BINARY', 'BINARY_STREAM', 'BIT',
|
|
'BLOB', 'BOOLEAN', 'Binary', 'CHAR', 'CHARACTER_STREAM', 'CLOB',
|
|
'Connection', 'Cursor', 'DATE', 'DATETIME', 'DECIMAL', 'DOUBLE',
|
|
'DataError', 'DatabaseError', 'Date', 'DateFromTicks', 'Error',
|
|
'FLOAT', 'GETTERS_BY_NAME', 'GETTERS_BY_TYPE', 'INTEGER',
|
|
'IntegrityError', 'InterfaceError', 'InternalError', 'JDBCType',
|
|
'LONGNVARCHAR', 'LONGVARBINARY', 'LONGVARCHAR', 'NCHAR',
|
|
'NCHARACTER_STREAM', 'NCLOB', 'NULL', 'NUMBER', 'NUMERIC', 'NVARCHAR',
|
|
'NotSupportedError', 'OBJECT', 'OTHER', 'OperationalError',
|
|
'ProgrammingError', 'REAL', 'REF', 'RESULTSET', 'ROWID',
|
|
'SETTERS_BY_META', 'SETTERS_BY_TYPE', 'SMALLINT', 'SQLXML', 'STRING',
|
|
'TEXT', 'TIME', 'TIMESTAMP', 'TIMESTAMP_WITH_TIMEZONE',
|
|
'TIME_WITH_TIMEZONE', 'TINYINT', 'Time', 'TimeFromTicks', 'Timestamp',
|
|
'TimestampFromTicks', 'URL', 'VARBINARY', 'VARCHAR', 'Warning',
|
|
'apilevel', 'connect', 'paramstyle', 'threadsafety']
|
|
|
|
apilevel = "2.0"
|
|
threadsafety = 2
|
|
paramstyle = 'qmark'
|
|
|
|
_SQLException = None
|
|
_SQLTimeoutException = None
|
|
_registry = {}
|
|
_types = []
|
|
|
|
|
|
def _nop(x):
|
|
return x
|
|
|
|
###############################################################################
|
|
# Types
|
|
|
|
|
|
class JDBCType(object):
|
|
def __init__(self, name, code=None, getter=None, setter=None):
|
|
""" (internal) Create a new JDBC type. """
|
|
if isinstance(name, (str, type(None))):
|
|
self._name = name
|
|
self._values = [name]
|
|
else:
|
|
self._name = name[0]
|
|
self._values = name
|
|
self._code = code
|
|
self._getter = getter
|
|
self._setter = setter
|
|
if code is not None:
|
|
_registry[code] = self
|
|
if name is not None:
|
|
_registry[self._name.upper()] = self
|
|
_types.append(self)
|
|
if _jpype.isStarted():
|
|
java = _jpype._JPackage("java")
|
|
self._initialize(java.sql.CallableStatement, java.sql.PreparedStatement, java.sql.ResultSet)
|
|
|
|
def _initialize(self, cs, ps, rs):
|
|
""" Called after the JVM starts initialize Java resources """
|
|
if self._getter is None:
|
|
self._getter = "getObject"
|
|
self._rsget = getattr(rs, self._getter)
|
|
self._csget = getattr(cs, self._getter, None)
|
|
if self._setter is None:
|
|
self._setter = "setObject"
|
|
self._psset = getattr(ps, self._setter)
|
|
|
|
def get(self, rs, column, st):
|
|
""" A method to retrieve a specific JDBC type.
|
|
|
|
To use a getter add the fetch method to the JDBC type matching the
|
|
column type to be pulled. For example, to set the getter for FLOAT to
|
|
use the OBJECT getter, use ``cx.getter[FLOAT] = OBJECT.get``.
|
|
|
|
Not all getters are available on all database drivers. Consult the
|
|
database driver documentation for details.
|
|
"""
|
|
try:
|
|
if st:
|
|
return self._csget(rs, column)
|
|
return self._rsget(rs, column)
|
|
except _SQLException as ex:
|
|
raise InterfaceError("Unable to get '%s' using '%s'" % (self._name, self._getter)) from ex
|
|
|
|
def set(self, ps, column, value):
|
|
""" A method used to set a parameter to a query.
|
|
|
|
To use a setter place the set method in the setter dict corresponding.
|
|
For example, if the database supports Blob types, the default handler
|
|
for BLOB can be changed from OBJECT to BLOB with
|
|
``cx.setter[BLOB] = BLOB.set``.
|
|
|
|
Not all setters are available on all database drivers. Consult the
|
|
database driver documentation for details.
|
|
"""
|
|
# Set the column with the specialized method
|
|
try:
|
|
if self._psset._matches(ps, column, value):
|
|
return self._psset(ps, column, value)
|
|
# Otherwise, try to set with the generic method
|
|
return ps.setObject(column, value)
|
|
except TypeError as ex:
|
|
raise InterfaceError("Unable to convert '%s' into '%s'" % (type(value).__name__, self._name)) from ex
|
|
except OverflowError as ex:
|
|
raise InterfaceError("Unable to convert '%s' into '%s' calling '%s'" % (type(value).__name__, self._name, self._setter)) from ex
|
|
|
|
def __repr__(self):
|
|
if self._name is None:
|
|
return ""
|
|
return self._name
|
|
|
|
def __eq__(self, other):
|
|
return other in self._values
|
|
|
|
def __hash__(self):
|
|
return hash(self._name)
|
|
|
|
|
|
class _JDBCTypePrimitive(JDBCType):
|
|
def get(self, rs, column, st):
|
|
try:
|
|
if st:
|
|
rc = self._csget(rs, column)
|
|
else:
|
|
rc = self._rsget(rs, column)
|
|
if rc == 0 and rs.wasNull():
|
|
return None
|
|
return rc
|
|
except _SQLException as ex:
|
|
raise InterfaceError("Unable to get '%s' using '%s'" % (self._name, self._getter)) from ex
|
|
|
|
|
|
# From https://www.cis.upenn.edu/~bcpierce/courses/629/jdkdocs/guide/jdbc/getstart/mapping.doc.html
|
|
# DATALINK = JDBCType('DATALINK',70)
|
|
# DISTINCT= JDBCType('DISTINCT',2001)
|
|
# REF_CURSOR = JDBCType('REF_CURSOR',2012)
|
|
# STRUCT = JDBCType('STRUCT',2002)
|
|
ARRAY = JDBCType('ARRAY', 2003, 'getArray', 'setArray')
|
|
BIGINT = _JDBCTypePrimitive('BIGINT', -5, 'getLong', 'setLong')
|
|
BIT = JDBCType('BIT', -7, 'getBoolean', 'setBoolean')
|
|
BLOB = JDBCType('BLOB', 2004, 'getBlob', 'setBlob')
|
|
BOOLEAN = _JDBCTypePrimitive('BOOLEAN', 16, 'getBoolean', 'setBoolean')
|
|
CHAR = JDBCType('CHAR', 1, 'getString', 'setString')
|
|
CLOB = JDBCType('CLOB', 2005, 'getClob', 'setClob')
|
|
DATE = JDBCType('DATE', 91, 'getDate', 'setDate')
|
|
DOUBLE = _JDBCTypePrimitive('DOUBLE', 8, 'getDouble', 'setDouble')
|
|
INTEGER = _JDBCTypePrimitive('INTEGER', 4, 'getInt', 'setInt')
|
|
OBJECT = JDBCType('OBJECT', 2000)
|
|
LONGNVARCHAR = JDBCType('LONGNVARCHAR', -16, 'getString', 'setString')
|
|
LONGVARBINARY = JDBCType('LONGVARBINARY', -4, 'getBytes', 'setBytes')
|
|
LONGVARCHAR = JDBCType('LONGVARCHAR', -1, 'getString', 'setString')
|
|
NCHAR = JDBCType('NCHAR', -15, 'getString', 'setString')
|
|
NCLOB = JDBCType('NCLOB', 2011, 'getNClob', 'setNClob')
|
|
NULL = JDBCType('NULL', 0)
|
|
NUMERIC = JDBCType('NUMERIC', 2, 'getBigDecimal', 'setBigDecimal')
|
|
NVARCHAR = JDBCType('NVARCHAR', -9, 'getClob', 'setClob')
|
|
OTHER = JDBCType('OTHER', 1111)
|
|
REAL = _JDBCTypePrimitive('REAL', 7, 'getFloat', 'setFloat')
|
|
REF = JDBCType('REF', 2006, 'getRef', 'setRef')
|
|
ROWID = JDBCType('ROWID', -8, 'getRowId', 'setRowId')
|
|
RESULTSET = JDBCType('RESULTSET', -10, 'getObject', 'setObject')
|
|
SMALLINT = _JDBCTypePrimitive('SMALLINT', 5, 'getShort', 'setShort')
|
|
SQLXML = JDBCType('SQLXML', 2009, 'getSQLXML', 'setSQLXML')
|
|
TIME = JDBCType('TIME', 92, 'getTime', 'setTime')
|
|
TIME_WITH_TIMEZONE = JDBCType('TIME_WITH_TIMEZONE', 2013, 'getTime', 'setTime')
|
|
TIMESTAMP = JDBCType('TIMESTAMP', 93, 'getTimestamp', 'setTimestamp')
|
|
TIMESTAMP_WITH_TIMEZONE = JDBCType('TIMESTAMP_WITH_TIMEZONE', 2014, 'getTimestamp', 'setTimestamp')
|
|
TINYINT = _JDBCTypePrimitive('TINYINT', -6, 'getShort', 'setShort')
|
|
VARBINARY = JDBCType('VARBINARY', -3, 'getBytes', 'setBytes')
|
|
VARCHAR = JDBCType('VARCHAR', 12, 'getString', 'setString')
|
|
|
|
# Aliases required by DBAPI2
|
|
STRING = JDBCType(['STRING', 'CHAR', 'NCHAR', 'NVARCHAR', 'VARCHAR', 'OTHER'], None,
|
|
'getString', 'setString')
|
|
TEXT = JDBCType(['TEXT', 'CLOB', 'LONGVARCHAR', 'LONGNVARCHAR', 'NCLOB', 'SQLXML'], None,
|
|
'getString', 'setString')
|
|
BINARY = JDBCType(['BINARY', 'BLOB', 'LONGVARBINARY', 'VARBINARY'], -2,
|
|
'getBytes', 'setBytes')
|
|
NUMBER = JDBCType(['NUMBER', 'BOOLEAN', 'BIGINT', 'BIT', 'INTEGER', 'SMALLINT', 'TINYINT'], None,
|
|
'getObject', 'setObject')
|
|
FLOAT = _JDBCTypePrimitive(['FLOAT', 'REAL', 'DOUBLE'], 6,
|
|
'getDouble', 'setDouble')
|
|
DECIMAL = JDBCType(['DECIMAL', 'NUMERIC'], 3,
|
|
'getBigDecimal', 'setBigDecimal')
|
|
DATETIME = TIMESTAMP
|
|
|
|
# Special types
|
|
ASCII_STREAM = JDBCType(None, None, 'getAsciiStream', 'setAsciiStream')
|
|
BINARY_STREAM = JDBCType(None, None, 'getBinaryStream', 'setBinaryStream')
|
|
CHARACTER_STREAM = JDBCType(None, None, 'getCharacterStream', 'setCharacterStream')
|
|
NCHARACTER_STREAM = JDBCType(None, None, 'getNCharacterStream', 'setNCharacterStream')
|
|
URL = JDBCType(None, None, 'getURL', 'setURL')
|
|
|
|
# The converters are defined in a customizer
|
|
|
|
|
|
def _asPython(x):
|
|
return x._py()
|
|
|
|
|
|
# This maps the types reported by the columns to the type used for the getter
|
|
# and converter
|
|
_default_map = {ARRAY: OBJECT, OBJECT: OBJECT, NULL: OBJECT,
|
|
REF: OBJECT, ROWID: OBJECT, RESULTSET: OBJECT,
|
|
TIME_WITH_TIMEZONE: OBJECT, TIMESTAMP_WITH_TIMEZONE: OBJECT,
|
|
NVARCHAR: STRING, CHAR: STRING,
|
|
NCHAR: STRING, VARCHAR: STRING, BINARY: BINARY,
|
|
BLOB: BINARY, LONGVARBINARY: BINARY, VARBINARY: BINARY,
|
|
NUMBER: NUMBER, BOOLEAN: BOOLEAN, BIGINT: BIGINT,
|
|
BIT: BIT, INTEGER: INTEGER, SMALLINT: SMALLINT,
|
|
TINYINT: TINYINT, FLOAT: FLOAT, REAL: REAL,
|
|
DECIMAL: DECIMAL, NUMERIC: NUMERIC,
|
|
DATE: DATE, TIMESTAMP: TIMESTAMP, TIME: TIME,
|
|
CLOB: STRING, NCLOB: STRING, STRING: STRING,
|
|
TEXT: STRING, SQLXML: STRING, LONGVARCHAR: STRING,
|
|
LONGNVARCHAR: STRING, DOUBLE: DOUBLE, OTHER: OBJECT
|
|
}
|
|
|
|
_default_setters = {} # type: ignore[var-annotated]
|
|
|
|
_default_converters = {} # type: ignore[var-annotated]
|
|
|
|
_default_adapters = {} # type: ignore[var-annotated]
|
|
|
|
|
|
# Setters take (connection, meta, col, type) -> JDBCTYPE
|
|
def SETTERS_BY_META(cx, meta, col, ptype):
|
|
""" Option for setters to use the metadata of the parameters.
|
|
|
|
On some databases this option is useless as they do not track parameter
|
|
types. This method can be cached for faster performance when lots of
|
|
parameters. Usually types can only be determined accurately on inserts
|
|
into defined columns.
|
|
"""
|
|
return _default_map[_registry[meta.getParameterType(col + 1)]]
|
|
|
|
|
|
SETTERS_BY_META._cachable = True # type: ignore[attr-defined]
|
|
|
|
|
|
def SETTERS_BY_TYPE(cx, meta, col, ptype):
|
|
""" Option for setters to use the type of the object passed.
|
|
|
|
This option looks at the type of the parameter being passed
|
|
from Python after adapters have been applied to determine the
|
|
best setter.
|
|
"""
|
|
return _default_setters.get(ptype, None)
|
|
|
|
|
|
# Getters take (connection, meta, col) -> JDBCTYPE
|
|
def GETTERS_BY_TYPE(cx, meta, idx):
|
|
""" Option for getters to determine column type by the JDBC type.
|
|
|
|
This option is the default option that uses the type code supplied in
|
|
the meta data. On some databases it is better to use the name.
|
|
If the type code is OTHER, it will attempt to find a type by name.
|
|
New types can be created with JDBCType for database specific types.
|
|
"""
|
|
tp = _registry[meta.getColumnType(idx + 1)]
|
|
if tp == OTHER:
|
|
# Other may be found by name
|
|
name = str(meta.getColumnTypeName(idx + 1)).upper()
|
|
return _registry.get(name, tp)
|
|
return _default_map[tp]
|
|
|
|
|
|
def GETTERS_BY_NAME(cx, meta, idx):
|
|
""" Option to getters to determine column type by the column name.
|
|
|
|
This option uses the column name to select the type. It looks up
|
|
the column type name, converts it to uppercase, and then searches
|
|
for a matchine type. It falls back to the type code meta information if
|
|
the typename can not be found in the registery. New types can be created
|
|
using JDBCType for database specific types such as ``JSON``.
|
|
"""
|
|
name = str(meta.getColumnTypeName(idx + 1)).upper()
|
|
tp = _registry.get(name, None)
|
|
if tp is None:
|
|
tp = _registry[meta.getColumnType(idx + 1)]
|
|
return _default_map.get(tp, tp)
|
|
|
|
|
|
###############################################################################
|
|
# Exceptions
|
|
|
|
|
|
class Warning(Exception):
|
|
"""Exception raised for important warnings like data truncations while
|
|
inserting, etc. """
|
|
pass
|
|
|
|
|
|
class Error(Exception):
|
|
"""Exception that is the base class of all other error exceptions. You can use
|
|
this to catch all errors with one single except statement. Warnings are not
|
|
considered errors and thus should not use this class as base.
|
|
"""
|
|
pass
|
|
|
|
|
|
class InterfaceError(Error, TypeError):
|
|
""" Exception raised for errors that are related to the database interface
|
|
rather than the database itself."""
|
|
pass
|
|
|
|
|
|
class DatabaseError(Error):
|
|
""" Exception raised for errors that are related to the database."""
|
|
pass
|
|
|
|
|
|
class DataError(DatabaseError):
|
|
""" Exception raised for errors that are due to problems with the processed
|
|
data like division by zero, numeric value out of range, etc."""
|
|
pass
|
|
|
|
|
|
class OperationalError(DatabaseError):
|
|
""" Exception raised for errors that are related to the database's operation
|
|
and not necessarily under the control of the programmer, e.g. an unexpected
|
|
disconnect occurs, the data source name is not found, a transaction could not
|
|
be processed, a memory allocation error occurred during processing, etc."""
|
|
pass
|
|
|
|
|
|
class IntegrityError(DatabaseError):
|
|
""" Exception raised when the relational integrity of the database is affected,
|
|
e.g. a foreign key check fails."""
|
|
pass
|
|
|
|
|
|
class InternalError(DatabaseError):
|
|
""" Exception raised when the database encounters an internal error, e.g. the
|
|
cursor is not valid anymore, the transaction is out of sync, etc."""
|
|
pass
|
|
|
|
|
|
class ProgrammingError(DatabaseError):
|
|
""" Exception raised for programming errors, e.g. table not found or already
|
|
exists, syntax error in the SQL statement, wrong number of parameters
|
|
specified, etc."""
|
|
pass
|
|
|
|
|
|
class NotSupportedError(DatabaseError):
|
|
""" Exception raised in case a method or database API was used which is not
|
|
supported by the database, e.g. requesting a .rollback() on a connection that
|
|
does not support transaction or has transactions turned off.
|
|
"""
|
|
pass
|
|
|
|
|
|
class _UnsupportedTypeError(InterfaceError, TypeError):
|
|
pass
|
|
|
|
|
|
###############################################################################
|
|
# Connection
|
|
|
|
_default = object()
|
|
|
|
|
|
def connect(dsn, *, driver=None, driver_args=None,
|
|
adapters=_default, converters=_default,
|
|
getters=GETTERS_BY_TYPE, setters=SETTERS_BY_TYPE, **kwargs):
|
|
""" Create a connection to a database.
|
|
|
|
Arguments to the driver depend on the database type.
|
|
|
|
Args:
|
|
dsn (str): The database connection string for JDBC.
|
|
driver (str, optional): A JDBC driver to load.
|
|
driver_args: Arguments to the driver. This may either be a dict,
|
|
java.util.Properties. If not supplied, kwargs are used as as the
|
|
parameters for the JDBC connection.
|
|
*kwargs: Arguments to the driver if not supplied as
|
|
driver_args.
|
|
|
|
Raises:
|
|
Error if the connection cannot be established.
|
|
|
|
Returns:
|
|
A new connection if successful.
|
|
"""
|
|
Properties = _jpype.JClass("java.util.Properties")
|
|
if driver:
|
|
_jpype.JClass('java.lang.Class').forName(driver).newInstance()
|
|
DM = _jpype.JClass('java.sql.DriverManager')
|
|
|
|
# User is supplying Java properties
|
|
if isinstance(driver_args, Properties):
|
|
connection = DM.getConnection(dsn, driver_args)
|
|
|
|
# User is supplying a mapping that can be converted Properties
|
|
elif isinstance(driver_args, typing.Mapping):
|
|
info = Properties()
|
|
for k, v in driver_args.items():
|
|
info.setProperty(k, v)
|
|
connection = DM.getConnection(dsn, info)
|
|
|
|
# User supplied nothing
|
|
elif driver_args is None:
|
|
connection = DM.getConnection(dsn)
|
|
|
|
# Otherwise use the kwargs
|
|
else:
|
|
info = Properties()
|
|
for k, v in kwargs.items():
|
|
info.setProperty(k, v)
|
|
connection = DM.getConnection(url, info)
|
|
|
|
return Connection(connection, adapters, converters, setters, getters)
|
|
|
|
|
|
class Connection(object):
|
|
""" Connection provides access to a JDBC database.
|
|
|
|
Connections are managed and can be as part of a Python with statement.
|
|
Connections close automatically when they are garbage collected, at the
|
|
end of a with statement scope, or when manually closed. Once a connection
|
|
is closed all operations using the database will raise an Error.
|
|
"""
|
|
Error = Error
|
|
Warning = Warning
|
|
InterfaceError = InterfaceError
|
|
DatabaseError = DatabaseError
|
|
InternalError = InternalError
|
|
OperationalError = OperationalError
|
|
ProgrammingError = ProgrammingError
|
|
IntegrityError = IntegrityError
|
|
DataError = DataError
|
|
NotSupportedError = NotSupportedError
|
|
|
|
def __init__(self, jconnection, adapters, converters, setters, getters):
|
|
self._jcx = jconnection
|
|
# Required by PEP 249
|
|
# https://www.python.org/dev/peps/pep-0249/#commit
|
|
try:
|
|
# Some driver do not support this feature.
|
|
# https://github.com/jpype-project/jpype/issues/1003
|
|
self._jcx.setAutoCommit(False)
|
|
except Exception as ex:
|
|
if ex.getClass().getSimpleName() != 'SQLFeatureNotSupportedException':
|
|
raise ex
|
|
|
|
# Handle defaults
|
|
if adapters is _default:
|
|
adapters = dict(_default_adapters)
|
|
if adapters is None:
|
|
adapters = {}
|
|
if converters is _default:
|
|
converters = dict(_default_converters)
|
|
if converters is None:
|
|
converters = {}
|
|
|
|
self._closed = False
|
|
self._batch = jconnection.getMetaData().supportsBatchUpdates()
|
|
self._adapters = adapters
|
|
self._converters = converters
|
|
self._getters = getters
|
|
self._setters = setters
|
|
|
|
@property
|
|
def adapters(self):
|
|
""" Adapters are used to convert Python types into JDBC types.
|
|
|
|
Adaptors are stored in a mapping from incoming type to an adapter
|
|
function. Adapters set on a connection apply only to that connection.
|
|
Adapters can be overriden when calling the ``.execute*()`` method.
|
|
|
|
Adapters can also be set on the JDBC types directly.
|
|
"""
|
|
return self._adapters
|
|
|
|
@adapters.setter
|
|
def adapters(self, v):
|
|
if v is None:
|
|
v = {}
|
|
if not isinstance(v, typing.Mapping):
|
|
raise _UnsupportedTypeError("Mapping is required")
|
|
self._adapters = v
|
|
|
|
@property
|
|
def converters(self):
|
|
""" Converters are applied when retrieving a JDBC type from the database.
|
|
|
|
"""
|
|
return self._converters
|
|
|
|
@converters.setter
|
|
def converters(self, v):
|
|
if v is None:
|
|
v = {}
|
|
if not isinstance(v, typing.Mapping):
|
|
raise _UnsupportedTypeError("Mapping is required")
|
|
self._converters = v
|
|
|
|
@property
|
|
def getters(self):
|
|
""" Getters are used to retrieve JDBC types from the database following
|
|
a ``.fetch*()``.
|
|
|
|
Getters should be a function taking (connection, meta, col) -> JDBCTYPE
|
|
"""
|
|
return self._getters
|
|
|
|
# Setters take (connection, meta, col, type) -> JDBCTYPE
|
|
@getters.setter
|
|
def getters(self, v):
|
|
self._getters = v
|
|
|
|
@property
|
|
def setters(self):
|
|
""" Setter are used to set parameters to ``.execute*()`` methods.
|
|
|
|
Setters should be a function taking (connection, meta, col, type) -> JDBCTYPE
|
|
"""
|
|
return self._setters
|
|
|
|
@setters.setter
|
|
def setters(self, v):
|
|
self._setters = v
|
|
|
|
def __setattr__(self, name, value):
|
|
if isinstance(vars(type(self)).get(name, None), property):
|
|
return object.__setattr__(self, name, value)
|
|
if not name.startswith("_"):
|
|
raise AttributeError("'%s' cannot be set" % name)
|
|
object.__setattr__(self, name, value)
|
|
|
|
def _close(self):
|
|
if self._closed or not _jpype.isStarted():
|
|
return
|
|
if not self._jcx.isClosed():
|
|
self._jcx.close()
|
|
self._closed = True
|
|
|
|
def __enter__(self):
|
|
return self
|
|
|
|
def __exit__(self, exception_type, exception_value, traceback):
|
|
self._close()
|
|
|
|
def __del__(self):
|
|
try:
|
|
self._close()
|
|
except Exception: # pragma: no cover
|
|
pass
|
|
|
|
def close(self):
|
|
""" Close the connection immediately (rather than whenever .__del__() is called).
|
|
|
|
The connection will be unusable from this point forward; an Error (or
|
|
subclass) exception will be raised if any operation is attempted with
|
|
the connection. The same applies to all cursor objects trying to use
|
|
the connection. Note that closing a connection without committing the
|
|
changes first will cause an implicit rollback to be performed. """
|
|
self._validate()
|
|
self._close()
|
|
|
|
def commit(self):
|
|
"""Commit any pending transaction to the database.
|
|
|
|
Calling commit on a cooonection that does not support the operation
|
|
will raise NotSupportedError.
|
|
"""
|
|
self._validate()
|
|
if self._jcx.getAutoCommit():
|
|
raise NotSupportedError("Autocommit is enabled")
|
|
try:
|
|
self._jcx.commit()
|
|
except Exception as ex: # pragma: no cover
|
|
raise OperationalError(ex.message()) from ex
|
|
|
|
def rollback(self):
|
|
"""Rollback the transaction.
|
|
|
|
This method is optional since not all databases provide transaction
|
|
support. Calling rollback on a cooonection that does not support will
|
|
raise NotSupportedError.
|
|
|
|
In case a database does provide transactions this method causes the
|
|
database to roll back to the start of any pending transaction. Closing
|
|
a connection without committing the changes first will cause an
|
|
implicit rollback to be performed.
|
|
"""
|
|
self._validate()
|
|
if self._jcx.getAutoCommit():
|
|
raise NotSupportedError("Autocommit is enabled", self.autocommit)
|
|
try:
|
|
self._jcx.rollback()
|
|
except Exception as ex: # pragma: no cover
|
|
raise OperationalError(ex.message()) from ex
|
|
|
|
def cursor(self):
|
|
""" Return a new Cursor Object using the connection. """
|
|
self._validate()
|
|
return Cursor(self)
|
|
|
|
def _validate(self):
|
|
if self._closed or self._jcx.isClosed():
|
|
raise ProgrammingError
|
|
|
|
@property
|
|
def connection(self):
|
|
""" Get the JDBC connection that is backing this Python
|
|
Connection object.
|
|
|
|
This can be used to retrieve additional metadata and other features
|
|
that are outside of the scope of the DBAPI driver.
|
|
"""
|
|
return self._jcx
|
|
|
|
@property
|
|
def autocommit(self):
|
|
""" bool: Property controlling autocommit behavior.
|
|
|
|
By default connects are not autocommit. Setting autocommit
|
|
will result in commit and rollback producing a ProgrammingError.
|
|
"""
|
|
self._validate()
|
|
return self._jcx.getAutoCommit()
|
|
|
|
@autocommit.setter
|
|
def autocommit(self, enabled):
|
|
self._validate()
|
|
self._jcx.setAutoCommit(enabled)
|
|
|
|
@property
|
|
def typeinfo(self):
|
|
""" list: The list of types that are supported by this driver.
|
|
|
|
This is useful to find out the capabilities of the driver.
|
|
"""
|
|
self._validate()
|
|
out = {}
|
|
metadata = self._jcx.getMetaData()
|
|
with metadata.getTypeInfo() as resultSet:
|
|
while (resultSet.next()):
|
|
try:
|
|
key = str(resultSet.getString("TYPE_NAME"))
|
|
out[key] = _registry[resultSet.getInt("DATA_TYPE")]
|
|
except KeyError as ex: # pragma: no cover
|
|
raise DatabaseError("Unknown data type '%s'" % key) from ex
|
|
return out
|
|
|
|
|
|
###############################################################################
|
|
# Cursor
|
|
|
|
|
|
class Cursor(object):
|
|
""" Cursors are used to execute queries and retrieve results.
|
|
|
|
Part PreparedStatement, part ResultSet, Cursors are a mixture of
|
|
both. The native resultSet can be accessed with ``resultSet``.
|
|
|
|
Cursors are managed and can be as part of a Python with statement.
|
|
Cursors close automatically when they are garbage collected, at the
|
|
end of a with statement scope, or when manually closed. Once a cursor
|
|
is closed all operations using the database will raise an Error.
|
|
"""
|
|
|
|
def __init__(self, connection):
|
|
if not isinstance(connection, Connection):
|
|
raise TypeError
|
|
self._connection = connection
|
|
self._jcx = connection._jcx
|
|
self._resultSet = None
|
|
self._statement = None
|
|
self._rowcount = -1
|
|
self._arraysize = 1
|
|
self._description = None
|
|
self._closed = False
|
|
self._resultGetters = None
|
|
self._thread = threading.get_ident()
|
|
self._last = None
|
|
|
|
def _close(self):
|
|
if self._closed or not _jpype.isStarted():
|
|
return
|
|
self._finish()
|
|
self._closed = True
|
|
|
|
def _setParams(self, params):
|
|
cx = self._connection
|
|
meta = self._statement.getParameterMetaData()
|
|
count = meta.getParameterCount()
|
|
types = self._parameterTypes
|
|
if types is None:
|
|
types = [None] * count
|
|
if isinstance(params, str):
|
|
raise _UnsupportedTypeError("parameters must be a sequence of values")
|
|
if isinstance(params, typing.Sequence):
|
|
if count != len(params):
|
|
raise ProgrammingError("incorrect number of parameters (%d!=%d)"
|
|
% (count, len(params)))
|
|
for i in range(len(params)):
|
|
p = params[i]
|
|
|
|
# Find and apply the adapter
|
|
a = cx._adapters.get(type(p), None)
|
|
if a is not None:
|
|
p = a(p)
|
|
|
|
# Find the setter
|
|
if types[i] is None:
|
|
s = cx._setters(cx, meta, i, type(p))
|
|
types[i] = s
|
|
if s is None:
|
|
raise _UnsupportedTypeError("no setter found for '%s'" % type(p).__name__)
|
|
s.set(self._statement, i + 1, p)
|
|
# Cache
|
|
if hasattr(cx._setters, "_cachable"):
|
|
self._parameterTypes = types
|
|
elif isinstance(params, typing.Mapping):
|
|
raise _UnsupportedTypeError("mapping parameters not supported")
|
|
elif isinstance(params, typing.Iterable):
|
|
for i, p in enumerate(params):
|
|
if i >= count:
|
|
raise ProgrammingError("incorrect number of parameters (%d!=%d)" % (count, i + 1))
|
|
|
|
# Find and apply the adapter
|
|
a = cx._adapters.get(type(p), None)
|
|
if a is not None:
|
|
p = a(p)
|
|
|
|
# Find the setter
|
|
if types[i] is None:
|
|
s = cx._setters(cx, meta, i, type(p))
|
|
types[i] = s
|
|
if s is None:
|
|
raise _UnsupportedTypeError("no setter found for '%s'" % type(p).__name__)
|
|
s.set(self._statement, i + 1, p)
|
|
if count != i + 1:
|
|
raise ProgrammingError("incorrect number of parameters (%d!=%d)" % (count, i + 1))
|
|
# Cache
|
|
if hasattr(cx._setters, "_cachable"):
|
|
self._parameterTypes = types
|
|
else:
|
|
raise _UnsupportedTypeError("'%s' parameters not supported" % (type(params).__name__)) # pragma: no cover
|
|
|
|
def _onResultSet(self, rs):
|
|
meta = rs.getMetaData()
|
|
self._resultSet = rs
|
|
self._resultSetMeta = meta
|
|
self._resultSetCount = meta.getColumnCount()
|
|
self._columnTypes = None
|
|
|
|
def _fetchRow(self, converters):
|
|
cx = self._connection
|
|
count = self._resultSetCount
|
|
meta = self._resultSetMeta
|
|
|
|
byPosition = False
|
|
if converters is _default:
|
|
converters = cx._converters
|
|
if isinstance(converters, typing.Sequence):
|
|
if len(converters) != count:
|
|
raise ProgrammingError("converter list size incorrect")
|
|
byPosition = True
|
|
|
|
# Get all the column types
|
|
if self._columnTypes is None:
|
|
gk = cx._getters
|
|
# We need the type information for the columns
|
|
self._columnTypes = [gk(cx, meta, i) for i in range(count)]
|
|
if len(self._columnTypes) != count:
|
|
raise ProgrammingError("incorrect number of columns")
|
|
try:
|
|
row = []
|
|
for idx in range(count):
|
|
tp = self._columnTypes[idx]
|
|
# Fetch the value
|
|
value = tp.get(self._resultSet, idx + 1, False)
|
|
if value is None or converters is None:
|
|
row.append(value)
|
|
elif byPosition:
|
|
# find the column converter by type
|
|
converter = converters[idx]
|
|
row.append(converter(value))
|
|
else:
|
|
# find the column converter by type
|
|
converter = cx._converters.get(type(value), _nop)
|
|
row.append(converter(value))
|
|
return row
|
|
except TypeError as ex:
|
|
raise _UnsupportedTypeError(str(ex)) from ex
|
|
|
|
def _validate(self):
|
|
""" Called before any method that requires the statement to be open. """
|
|
if self._closed or self._jcx.isClosed():
|
|
raise ProgrammingError("Cursor is closed")
|
|
if threading.get_ident() != self._thread:
|
|
raise ProgrammingError("Threading error")
|
|
|
|
def _check_executed(self):
|
|
""" Called before any method that requires the resultSet to be open. """
|
|
if self._closed or self._jcx.isClosed() or threading.get_ident() != self._thread:
|
|
raise ProgrammingError("Cursor is closed")
|
|
if self._resultSet is None:
|
|
raise ProgrammingError("execute() first")
|
|
|
|
def _finish(self):
|
|
if self._resultSet is not None:
|
|
self._resultSet.close()
|
|
self._resultSet = None
|
|
if self._statement is not None:
|
|
self._statement.close()
|
|
self._statement = None
|
|
self._rowcount = -1
|
|
self._description = None
|
|
self._last = None
|
|
|
|
@property
|
|
def resultSet(self):
|
|
""" Get the Java result set if available.
|
|
|
|
The object will be closed on the next call to ``.execute*()``.
|
|
"""
|
|
return self._resultSet
|
|
|
|
@property
|
|
def parameters(self):
|
|
""" (extension) Parameters is read-only attribute is a sequence of
|
|
6-item sequences.
|
|
|
|
Each of these sequences contains information describing one result
|
|
column:
|
|
|
|
- type_name
|
|
- jdbc_type
|
|
- parameter_mode (1=in, 2=in/out, 4=out)
|
|
- precision
|
|
- scale
|
|
- null_ok
|
|
|
|
This can only be used after execute or callproc.
|
|
"""
|
|
desc = []
|
|
if not self._statement:
|
|
raise ProgrammingError("No statement")
|
|
meta = self._statement.getParameterMetaData()
|
|
for i in range(1, meta.getParameterCount() + 1):
|
|
desc.append((str(meta.getParameterTypeName(i)),
|
|
_registry[meta.getParameterType(i)],
|
|
meta.getParameterMode(i),
|
|
meta.getPrecision(i),
|
|
meta.getScale(i),
|
|
meta.isNullable(i),))
|
|
return desc
|
|
|
|
@property
|
|
def description(self):
|
|
""" Description is read-only attribute is a sequence of 7-item
|
|
sequences.
|
|
|
|
Each of these sequences contains information describing one result
|
|
column:
|
|
|
|
- name
|
|
- type_code
|
|
- display_size
|
|
- internal_size
|
|
- precision
|
|
- scale
|
|
- null_ok
|
|
|
|
This can only be used if the last query produced a result set.
|
|
"""
|
|
if self._description is not None:
|
|
return self._description
|
|
desc = []
|
|
if not self._resultSet:
|
|
return None
|
|
meta = self._resultSet.getMetaData()
|
|
for i in range(1, meta.getColumnCount() + 1):
|
|
size = meta.getColumnDisplaySize(i)
|
|
desc.append((str(meta.getColumnName(i)),
|
|
str(meta.getColumnTypeName(i)),
|
|
size,
|
|
size,
|
|
meta.getPrecision(i),
|
|
meta.getScale(i),
|
|
meta.isNullable(i),))
|
|
self._description = desc
|
|
return desc
|
|
|
|
@property
|
|
def rowcount(self):
|
|
""" This read-only attribute specifies the number of rows that the last
|
|
.execute*() affected (for DML statements like UPDATE or INSERT).
|
|
|
|
The attribute is -1 in case no .execute*() has been performed on the
|
|
cursor or the rowcount of the last operation is cannot be determined by
|
|
the interface. JDBC does not support getting the number of rows
|
|
returned from SELECT, so for most drivers rowcount will be -1 after a
|
|
SELECT statement.
|
|
"""
|
|
return self._rowcount
|
|
|
|
def close(self):
|
|
""" Close the cursor now (rather than whenever __del__ is called).
|
|
|
|
The cursor will be unusable from this point forward; an Error (or
|
|
subclass) exception will be raised if any operation is attempted with
|
|
the cursor.
|
|
"""
|
|
self._validate()
|
|
self._close()
|
|
|
|
def callproc(self, procname, parameters=(), *, types=None):
|
|
""" Call a stored procedure.
|
|
|
|
(Not all JDBC drivers support this method)
|
|
|
|
Call a stored database procedure with the given name. The sequence of
|
|
parameters must contain one entry for each argument that the procedure
|
|
expects. The result of the call is returned as modified copy of the
|
|
input sequence. Input parameters are left untouched, output and
|
|
input/output parameters replaced with possibly new values.
|
|
|
|
For type output and input/output arguments, it is best to use
|
|
types keyword argument to select the appropriate getters for the
|
|
returned arguments. Converters are applied to output parameters.
|
|
|
|
The procedure may also provide a result set as output. This must then
|
|
be made available through the standard .fetch*() methods.
|
|
"""
|
|
try:
|
|
self._validate()
|
|
self._finish()
|
|
if not isinstance(procname, str):
|
|
raise _UnsupportedTypeError("procname must be str, not '%s'" % type(procname).__name__)
|
|
if not isinstance(parameters, typing.Sequence):
|
|
raise _UnsupportedTypeError("parameters must be sequence, not '%s'" % type(procname).__name__)
|
|
query = "{CALL %s(%s)}" % (procname, ",".join("?" * len(parameters)))
|
|
try:
|
|
self._statement = self._jcx.prepareCall(query)
|
|
except _SQLException as ex:
|
|
raise ProgrammingError(ex.message()) from ex
|
|
|
|
# This is a special one as we need to deal with in and out arguments
|
|
out = list(parameters)
|
|
cx = self._connection
|
|
meta = self._statement.getParameterMetaData()
|
|
count = meta.getParameterCount()
|
|
if types is None:
|
|
types = [None] * count
|
|
else:
|
|
if len(types) != count:
|
|
raise ProgrammingError("expected '%d' types, got '%d'" % (count, len(types)))
|
|
for i in range(count):
|
|
# Lookup the JDBC Type
|
|
p = parameters[i]
|
|
a = cx._adapters.get(type(p), None)
|
|
if a is not None:
|
|
p = a(p)
|
|
|
|
if types[i] is None:
|
|
types[i] = cx._setters(cx, meta, i, type(p))
|
|
jdbcType = types[i]
|
|
if jdbcType is None:
|
|
raise _UnsupportedTypeError("no setter found for '%s'" % type(p).__name__)
|
|
|
|
mode = meta.getParameterMode(i + 1)
|
|
if mode == 1:
|
|
jdbcType.set(self._statement, i + 1, p)
|
|
types[i] = None
|
|
if mode == 2:
|
|
jdbcType.set(self._statement, i + 1, p)
|
|
self.registerOutParameter(i + 1, jdbcType._code)
|
|
if mode == 4:
|
|
self.registerOutParameter(i + 1, jdbcType._code)
|
|
|
|
if self._statement.execute():
|
|
self._onResultSet(self._statement.getResultSet())
|
|
self._rowcount = self._statement.getUpdateCount()
|
|
|
|
for i, t in enumerate(types):
|
|
if t is None:
|
|
continue
|
|
|
|
# Find the converter to apply to the column
|
|
value = t.get(self._statement, i + 1, True)
|
|
# FIXME how do we get a converv
|
|
converter = cx._converters[type(value)]
|
|
out[i] = converter(value)
|
|
|
|
return out
|
|
|
|
# Restore the defaults
|
|
except Exception as ex:
|
|
self._converters = self._connection._converters
|
|
self._getters = self._connection._getters
|
|
raise ex
|
|
finally:
|
|
self._adapters = self._connection._adapters
|
|
self._setters = self._connection._setters
|
|
|
|
def execute(self, operation, parameters=None, *, types=None, keys=False):
|
|
"""
|
|
Prepare and execute a database operation (query or command).
|
|
|
|
Parameters may be provided as sequence and will be bound to variables
|
|
in the operation. Variables are specified in a qmark notation. JDBC
|
|
does not support mapping style parameters.
|
|
|
|
After executing a statement, the rowcount will be updated. If the
|
|
statement has no result set then the rowcount will be -1. A statement
|
|
can produce multiple result sets. Use ``.nextset()`` to traverse the
|
|
sets.
|
|
|
|
Parameters:
|
|
operation (str): A statement to be executed.
|
|
parameters (list, optional): A list of parameters for the statement.
|
|
The number of parameters much match the number required by the
|
|
statement or an Error will be raised.
|
|
keys (bool, optional): Specify if the keys should be available to
|
|
retrieve. (Default False)
|
|
|
|
Returns:
|
|
This cursor.
|
|
"""
|
|
self._last = None
|
|
self._parameterTypes = types
|
|
self._validate()
|
|
self._finish()
|
|
if parameters is None:
|
|
parameters = ()
|
|
if not isinstance(parameters, (typing.Sequence, typing.Iterable, typing.Iterator)):
|
|
raise _UnsupportedTypeError("parameters are of unsupported type '%s'" % type(parameters).__name__)
|
|
# complete the previous operation
|
|
try:
|
|
if keys:
|
|
self._statement = self._jcx.prepareStatement(operation, 1)
|
|
else:
|
|
self._statement = self._jcx.prepareStatement(operation)
|
|
except TypeError as ex:
|
|
raise _UnsupportedTypeError(str(ex))
|
|
except _SQLException as ex:
|
|
raise ProgrammingError(ex.message()) from ex
|
|
self._executeone(parameters)
|
|
return self
|
|
|
|
def _executeone(self, params):
|
|
self._setParams(params)
|
|
if self._statement.execute():
|
|
self._onResultSet(self._statement.getResultSet())
|
|
self._rowcount = self._statement.getUpdateCount()
|
|
return self._rowcount
|
|
|
|
def executemany(self, operation, seq_of_parameters, *, types=None, keys=False):
|
|
"""
|
|
Prepare a database operation (query or command) and then execute it
|
|
against all parameter sequences or mappings found in the sequence
|
|
seq_of_parameters.
|
|
|
|
Modules are free to implement this method using multiple calls to the
|
|
.execute() method or by using array operations to have the database
|
|
process the sequence as a whole in one call.
|
|
|
|
Use of this method for an operation which produces one or more result
|
|
sets constitutes undefined behavior, and the implementation is
|
|
permitted (but not required) to raise an exception when it detects that
|
|
a result set has been created by an invocation of the operation.
|
|
|
|
The same comments as for .execute() also apply accordingly to this
|
|
method.
|
|
|
|
Args:
|
|
operation (str): A statement to be executed.
|
|
seq_of_parameters (list, optional): A list of lists of parameters
|
|
for the statement. The number of parameters much match the number
|
|
required by the statement or an Error will be raised.
|
|
keys (bool, optional): Specify if the keys should be available to
|
|
retrieve. (Default False) For drivers that do not support
|
|
batch updates only that last key will be returned.
|
|
|
|
Returns:
|
|
This cursor.
|
|
"""
|
|
self._last = None
|
|
self._parameterTypes = types
|
|
self._validate()
|
|
if seq_of_parameters is None:
|
|
seq_of_parameters = ()
|
|
# complete the previous operation
|
|
self._finish()
|
|
try:
|
|
if keys:
|
|
self._statement = self._jcx.prepareStatement(operation, 1)
|
|
else:
|
|
self._statement = self._jcx.prepareStatement(operation)
|
|
except TypeError as ex:
|
|
raise _UnsupportedTypeError(str(ex))
|
|
except _SQLException as ex:
|
|
raise ProgrammingError("Failed to prepare '%s'" % operation) from ex
|
|
if self._connection._batch:
|
|
return self._executeBatch(seq_of_parameters)
|
|
else: # pragma: no cover
|
|
return self._executeRepeat(seq_of_parameters)
|
|
|
|
def _executeBatch(self, seq_of_parameters):
|
|
if isinstance(seq_of_parameters, typing.Iterable):
|
|
for params in seq_of_parameters:
|
|
self._setParams(params)
|
|
self._statement.addBatch()
|
|
else:
|
|
raise _UnsupportedTypeError("'%s' is not supported" % type(seq_of_parameters).__name__)
|
|
try:
|
|
counts = self._statement.executeBatch()
|
|
except _SQLException as ex: # pragma: no cover
|
|
raise ProgrammingError(ex.message()) from ex
|
|
self._rowcount = sum(counts)
|
|
if self._rowcount < 0: # pragma: no cover
|
|
self._rowcount = -1
|
|
return self
|
|
|
|
def _executeRepeat(self, seq_of_parameters): # pragma: no cover
|
|
counts = []
|
|
if isinstance(seq_of_parameters, typing.Iterable):
|
|
for params in seq_of_parameters:
|
|
counts.append(self._executeone(params))
|
|
elif isinstance(seq_of_parameters, typing.Iterator):
|
|
while True:
|
|
try:
|
|
params = next(seq_of_parameters)
|
|
counts.append(self._executeone(params))
|
|
except StopIteration:
|
|
break
|
|
else:
|
|
raise _UnsupportedTypeError("'%s' is not supported" % str(type(seq_of_parameters)))
|
|
self._rowcount = sum(counts)
|
|
if self._rowcount < 0:
|
|
self._rowcount = -1
|
|
return self
|
|
|
|
def fetchone(self, *, types=None, converters=_default):
|
|
"""
|
|
Fetch the next row of a query result set, returning a single
|
|
sequence, or None when no more data is available.
|
|
|
|
An Error (or subclass) exception is raised if the previous call to
|
|
.execute*() did not produce any result set or no call was issued yet.
|
|
"""
|
|
self._check_executed()
|
|
if not self._resultSet.next():
|
|
return None
|
|
if types is not None:
|
|
self._columnTypes = types
|
|
return self._fetchRow(converters)
|
|
|
|
def fetchmany(self, size=None, *, types=None, converters=_default):
|
|
""" Fetch multiple results.
|
|
|
|
Fetch the next set of rows of a query result, returning a sequence of
|
|
sequences (e.g. a list of tuples). An empty sequence is returned when
|
|
no more rows are available.
|
|
|
|
The number of rows to fetch per call is specified by the parameter. If it
|
|
is not given, the cursor's arraysize determines the number of rows to be
|
|
fetched. The method should try to fetch as many rows as indicated by the
|
|
size parameter. If this is not possible due to the specified number of rows
|
|
not being available, fewer rows may be returned.
|
|
|
|
An Error (or subclass) exception is raised if the previous call to
|
|
``.execute*()`` did not produce any result set or no call was issued yet.
|
|
|
|
Note there are performance considerations involved with the size parameter.
|
|
For optimal performance, it is usually best to use the .arraysize
|
|
attribute. If the size parameter is used, then it is best for it to retain
|
|
the same value from one ``.fetchmany()`` call to the next.
|
|
"""
|
|
self._check_executed()
|
|
if size is None:
|
|
size = self._arraysize
|
|
# Set a fetch size
|
|
self._resultSet.setFetchSize(size)
|
|
rows = []
|
|
if types is not None:
|
|
self._columnTypes = types
|
|
for i in range(size):
|
|
if not self._resultSet.next():
|
|
break
|
|
row = self._fetchRow(converters)
|
|
rows.append(row)
|
|
# Restore the default fetch size
|
|
self._resultSet.setFetchSize(0)
|
|
return rows
|
|
|
|
def fetchall(self, *, types=None, converters=_default):
|
|
""" Fetch all (remaining) rows of a query result, returning them as
|
|
a sequence of sequences (e.g. a list of tuples). Note that the cursor's
|
|
arraysize attribute can affect the performance of this operation.
|
|
|
|
An Error (or subclass) exception is raised if the previous call to
|
|
``.execute*()`` did not produce any result set or no call was issued yet.
|
|
"""
|
|
self._check_executed()
|
|
# Set a fetch size
|
|
rows = []
|
|
if types is not None:
|
|
self._columnTypes = types
|
|
while self._resultSet.next():
|
|
row = self._fetchRow(converters)
|
|
rows.append(row)
|
|
return rows
|
|
|
|
def __iter__(self):
|
|
""" (extension) Iterate through a cursor one record at a time.
|
|
"""
|
|
self._check_executed()
|
|
# Set a fetch size
|
|
while self._resultSet.next():
|
|
yield self._fetchRow(_default)
|
|
|
|
def nextset(self):
|
|
""" Get the next result set in this cursor.
|
|
|
|
Not all databases support multiple result sets.
|
|
|
|
This method will make the cursor skip to the next available set, discarding
|
|
any remaining rows from the current set.
|
|
|
|
If there are no more sets, the method returns None. Otherwise, it returns a
|
|
true value and subsequent calls to the ``.fetch*()`` methods will return rows
|
|
from the next result set.
|
|
|
|
An Error (or subclass) exception is raised if the previous call to
|
|
``.execute*()`` did not produce any result set or no call was issued yet.
|
|
"""
|
|
self._resultSet.close()
|
|
if self._statement.getMoreResults(): # pragma: no cover
|
|
self._onResultSet(_statement.getResultSet())
|
|
return True
|
|
else:
|
|
self._rowcount = self._statement.getUpdateCount()
|
|
return None
|
|
|
|
@property
|
|
def arraysize(self):
|
|
"""
|
|
Specify the number of rows to fetch with ``.fetchmany()``.
|
|
|
|
This read/write attribute specifies the number of rows to fetch
|
|
at a time with ``.fetchmany()``. It defaults to 1 meaning to fetch a single row
|
|
at a time.
|
|
"""
|
|
return self._arraysize
|
|
|
|
@arraysize.setter
|
|
def arraysize(self, sz):
|
|
self._arraysize = sz
|
|
|
|
@property
|
|
def lastrowid(self):
|
|
""" Get the id of the last row inserted.
|
|
|
|
This is not supported on all JDBC drivers. The ``.execute*()`` must have
|
|
been executed with keys set to True.
|
|
|
|
Returns:
|
|
None if there is no rowid, the rowid if only one row was inserted,
|
|
or a list of row ids if multiple rows were inserted.
|
|
"""
|
|
if self._last is not None:
|
|
return self._last
|
|
with self._statement.getGeneratedKeys() as rs:
|
|
if rs.isClosed():
|
|
return self._last
|
|
last = []
|
|
while rs.next():
|
|
last.append(rs.getLong(1))
|
|
if len(last) == 0:
|
|
return None
|
|
if len(last) == 1:
|
|
self._last = last[0]
|
|
return last[0]
|
|
self._last = last
|
|
return last
|
|
|
|
def setinputsizes(self, sizes):
|
|
""" This can be used before a call to .execute*() to
|
|
predefine memory areas for the operation's parameters.
|
|
|
|
sizes is specified as a sequence — one item for each input parameter. The
|
|
item should be a Type Object that corresponds to the input that will be
|
|
used, or it should be an integer specifying the maximum length of a string
|
|
parameter. If the item is None, then no predefined memory area will be
|
|
reserved for that column (this is useful to avoid predefined areas for
|
|
large inputs).
|
|
|
|
This method would be used before the .execute*() method is invoked.
|
|
|
|
(not implemented)
|
|
"""
|
|
pass
|
|
|
|
def setoutputsize(self, size, column=None):
|
|
"""
|
|
Set a column buffer size for fetches of large columns (e.g. LONGs, BLOBs, etc.).
|
|
|
|
The column is specified as an index into the result sequence. Not
|
|
specifying the column will set the default size for all large columns
|
|
in the cursor.
|
|
|
|
(not implemented)
|
|
"""
|
|
pass
|
|
|
|
def __del__(self):
|
|
try:
|
|
self._close()
|
|
except Exception: # pragma: no cover
|
|
pass
|
|
|
|
def __enter__(self):
|
|
return self
|
|
|
|
def __exit__(self, exception_type, exception_value, traceback):
|
|
self._close()
|
|
|
|
###############################################################################
|
|
# Factories
|
|
|
|
|
|
def Date(year, month, day):
|
|
""" This function constructs an object holding a date value. """
|
|
return _jpype.JClass('java.sql.Date')(year - 1900, month - 1, day)
|
|
|
|
|
|
def Time(hour, minute, second):
|
|
""" This function constructs an object holding a time value. """
|
|
return _jpype.JClass('java.sql.Time')(hour, minute, second)
|
|
|
|
|
|
def Timestamp(year, month, day, hour, minute, second, nano=0):
|
|
""" This function constructs an object holding a time stamp value. """
|
|
return _jpype.JClass('java.sql.Timestamp')(year - 1900, month - 1, day, hour, minute, second, nano)
|
|
|
|
|
|
def DateFromTicks(ticks):
|
|
"""
|
|
This function constructs an object holding a date value from the given
|
|
ticks value (number of seconds since the epoch; see the documentation of
|
|
the standard Python time module for details).
|
|
"""
|
|
return Date(*time.localtime(ticks)[:3])
|
|
|
|
|
|
def TimeFromTicks(ticks):
|
|
"""
|
|
|
|
This function constructs an object holding a time value from the given
|
|
ticks value (number of seconds since the epoch; see the documentation of
|
|
the standard Python time module for details).
|
|
"""
|
|
return Time(*time.localtime(ticks)[3:6])
|
|
|
|
|
|
def TimestampFromTicks(ticks):
|
|
"""
|
|
This function constructs an object holding a time stamp value from the
|
|
given ticks value (number of seconds since the epoch; see the documentation
|
|
of the standard Python time module for details).
|
|
"""
|
|
return Timestamp(*time.localtime(ticks)[:6])
|
|
|
|
|
|
def Binary(data):
|
|
"""
|
|
This function constructs an object capable of holding a binary (long)
|
|
string value.
|
|
"""
|
|
return _jtypes.JArray(_jtypes.JByte)(data)
|
|
|
|
|
|
# SQL NULL values are represented by the Python None singleton on input and output.
|
|
_accepted = set(["exact", "implicit"])
|
|
|
|
|
|
def _populateTypes():
|
|
global _SQLException, _SQLTimeoutException
|
|
_SQLException = _jpype.JClass("java.sql.SQLException")
|
|
_SQLTimeoutException = _jpype.JClass("java.sql.SQLTimeoutException")
|
|
cs = _jpype.JClass("java.sql.CallableStatement")
|
|
ps = _jpype.JClass("java.sql.PreparedStatement")
|
|
rs = _jpype.JClass("java.sql.ResultSet")
|
|
for v in _types:
|
|
v._initialize(cs, ps, rs)
|
|
|
|
java = _jpype._JPackage("java")
|
|
|
|
byteArray = _jpype.JArray(_jtypes.JByte)
|
|
_default_setters[java.lang.String] = STRING
|
|
_default_setters[java.sql.Date] = DATE
|
|
_default_setters[java.sql.Time] = TIME
|
|
_default_setters[java.sql.Timestamp] = TIMESTAMP
|
|
_default_setters[byteArray] = BINARY
|
|
_default_setters[java.math.BigDecimal] = DECIMAL
|
|
_default_setters[_jtypes.JFloat] = REAL
|
|
_default_setters[_jtypes.JDouble] = DOUBLE
|
|
_default_setters[_jtypes.JBoolean] = BOOLEAN
|
|
_default_setters[_jtypes.JShort] = INTEGER
|
|
_default_setters[_jtypes.JInt] = INTEGER
|
|
_default_setters[_jtypes.JLong] = BIGINT
|
|
_default_setters[bool] = BOOLEAN
|
|
_default_setters[int] = BIGINT
|
|
_default_setters[float] = DOUBLE
|
|
_default_setters[str] = STRING
|
|
_default_setters[memoryview] = BINARY
|
|
_default_setters[bytes] = BINARY
|
|
_default_setters[bytearray] = BINARY
|
|
_default_setters[type(None)] = OBJECT
|
|
_default_setters[java.sql.Clob] = CLOB
|
|
_default_setters[java.sql.Blob] = BLOB
|
|
_default_setters[datetime.datetime] = TIMESTAMP
|
|
_default_setters[datetime.date] = DATE
|
|
_default_setters[datetime.time] = TIME
|
|
|
|
_default_converters[java.lang.String] = str
|
|
_default_converters[java.sql.Date] = _asPython
|
|
_default_converters[java.sql.Time] = _asPython
|
|
_default_converters[java.sql.Timestamp] = _asPython
|
|
_default_converters[java.math.BigDecimal] = _asPython
|
|
_default_converters[byteArray] = bytes
|
|
_default_converters[type(None)] = _nop
|
|
# Adaptors can be installed after the JVM is started
|
|
# JByteArray = _jpype.JArray(_jtypes.JByte)
|
|
# VARCHAR.adapters[memoryview] = JByteArray
|
|
|
|
|
|
_jcustomizer.getClassHints("java.sql.SQLException").registerClassBase(Error)
|
|
_jinit.registerJVMInitializer(_populateTypes)
|