adodbapi package¶

Todo

Create docstrings for remaining module members

adodbapi ¶

adodbapi - A python DB API 2.0 (PEP 249) interface to Microsoft ADO

adodbapi.Binary(aString)¶: This function constructs an object capable of holding a binary (long) string value.

adodbapi.Date(year, month, day)¶: This function constructs an object holding a date value.

adodbapi.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).

adodbapi.Time(hour, minute, second)¶: This function constructs an object holding a time value.

adodbapi.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).

adodbapi.Timestamp(year, month, day, hour, minute, second)¶: This function constructs an object holding a time stamp value.

adodbapi.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).

adodbapi.ado_consts ¶

adodbapi.ado_consts.ado_direction_name(ado_dir)¶

adodbapi.ado_consts.ado_type_name(ado_type)¶

adodbapi.Connection ¶

class adodbapi.Connection¶

Bases: object

A Connection object holds an ADO connection in its .connector attribute.

A Connection object is usually created using the standard api constructor.

Internally, it creates an empty Connection object, fills in the attributes needed, and then call its connect() method (which calls the ADO Open method).

Connection methods¶

Connection.close()¶

Close the connection now (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.

Connection.commit()¶

Commit any pending transaction to the database.

Note that if the database supports an auto-commit feature, this must be initially off. An interface method may be provided to turn it back on. Database modules that do not support transactions should implement this method with void functionality.

Connection._rollback()¶

In case a database does provide transactions this method causes the 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.

If the database does not support the functionality required by the method, the interface should throw an exception in case the method is used. The preferred approach is to not implement the method and thus have Python generate an AttributeError in case the method is requested. This allows the programmer to check for database capabilities using the standard hasattr() function.

For some dynamically configured interfaces it may not be appropriate to require dynamically making the method available. These interfaces should then raise a NotSupportedError to indicate the non-ability to perform the roll back when the method is invoked.

Connection.cursor()¶

Return a new Cursor Object using the connection.

returns an adodbapi.adodbapi.Cursor

Connection methods (non-standard)¶

Connection.__enter__()¶: The connection is a context manager for transactions.

Connection.__exit__(exc_type, exc_val, exc_tb)¶: If no errors occurred, commit(), otherwise _rollback()

Connection.get_table_names()¶: Returns a list of table names in your database. (schema)

Connection attributes¶

property Connection.dbapi¶

Return a reference to the DBAPI module for this Connection.

references the module defining the connection. (A proposed db-api V3 extension.) This is a way for higher level code to reach module-level attributes.

Todo

autodoc fails to generate .messages, variantConversions, and .timeout
These are all private attributes. Should they be converted to properties?

Connection.errorhandler¶: (standard extension. See PEP.) (does not work on remote)

Connection.connector¶: (Internal) the ADO connection object

Connection.paramstyle¶

can be altered by the programmer to change the paramstyle in use. The supported values are 'qmark' (the default), 'format', and 'named'. Values of 'pyformat', and 'dynamic' are also accepted (see below).

The connection string keyword paramstyle will set the default for the class for future connections.

Connection.connection_string¶: the complete connection string which was used to start ADO.

Connection.dbms_name¶: string identifying the actual database engine from the connection.

Connection.dbms_version¶: string identifying the version of the db engine.

Connection.supportsTransactions¶: (bool) this driver is capable of commit()/rollback().

adodbapi.Cursor ¶

class adodbapi.Cursor(connection)¶: Bases: object

Attributes¶

Note

.description is created/accessed only via __getattr__. Is a list[tuple]

Cursor._description¶: as defined by PEP 249, a sequence of 7-item sequences

Cursor.rowcount¶

type is / returns int

-1 means “not known”. Will be ADO recordset.RecordCount (if it works), otherwise, the count returned by the last ADO Execute operation.

Attributes (standard extensions)¶

Cursor.connection¶: back-link to the adodbapi.adodbapi.Connection

Cursor.errorhandler¶: (see PEP 249 - a function to process exceptions.)

Cursor.messages¶: (see PEP 249)

Cursor.arraysize¶: (=:code:1) # the default number of rows to fetch in fetchmany()

Attributes (non-standard)¶

Note

autodoc fails to generate .returnValue

Cursor.paramstyle¶: can be altered by the user to change paramstyle processing. (default taken from connection.) (see below)

Cursor.rs¶: the internal ADO recordset (local) or raw unpickled data (remote)

Cursor.converters¶: a list of input-conversion functions, one per column. (not available on remote)

Cursor.columnNames¶: a dictionary of: (lower-cased) column name : (column number).

Cursor.numberOfColumns¶: number of columns in present record set.

Cursor.command¶: the last raw SQL command sent to the query (before any reformatting)

property Cursor.query¶

returns the last query executed

the text of last operation, as converted by reformatting

Methods (standard)¶

Cursor.callproc(procname, parameters=None)¶

Call a stored database procedure with the given name. The sequence of parameters must contain one entry for each argument that the sproc 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.

The sproc may also provide a result set as output, which is available through the standard .fetch*() methods. Extension: A “return_value” property may be set on the cursor if the sproc defines an integer return value.

execute a stored procedure, returning parameter values. A “returned value” (not an “out” parameter) will be in crsr.returnValue -> returns the (modified) parameter list

Cursor.close(dont_tell_me=False)¶

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.

close the cursor, free the recordset

Note

non-standard: in adodbapi, it is NOT an error to re-close a closed cursor

Cursor.execute(operation, parameters=None)¶

Prepare and execute a database operation (query or command).

Parameters may be provided as sequence or mapping and will be bound to variables in the operation. Variables are specified in a database-specific notation (see the module’s paramstyle attribute for details). [5] A reference to the operation will be retained by the cursor. If the same operation object is passed in again, then the cursor can optimize its behavior. This is most effective for algorithms where the same operation is used, but different parameters are bound to it (many times).

For maximum efficiency when reusing an operation, it is best to use the setinputsizes() method to specify the parameter types and sizes ahead of time. It is legal for a parameter to not match the predefined information; the implementation should compensate, possibly with a loss of efficiency.

The parameters may also be specified as list of tuples to e.g. insert multiple rows in a single operation, but this kind of usage is depreciated: executemany() should be used instead.

Return value is not defined.

[5] The module will use the __getitem__ method of the parameters object to map either positions (integers) or names (strings) to parameter values. This allows for both sequences and mappings to be used as input. The term “bound” refers to the process of binding an input value to a database execution buffer. In practical terms, this means that the input value is directly used as a value in the operation. The client should not be required to “escape” the value so that it can be used – the value should be equal to the actual database value.

operation: str¶: the text of the SQL.

adodbapi.parameters: list = None¶: parameters for the query or command…

execute a query or command…

does not return anything / returns None

Cursor.executemany(operation, seq_of_parameters)¶

Prepare a database operation (query or command) and then execute it against all parameter sequences or mappings found in the sequence seq_of_parameters.

Return values are not defined.

runs the SQL operation several times, once for each group of parameters in sequence-of-parameters.

Cursor.fetchone()¶

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 executeXXX() did not produce any result set or no call was issued yet.

returns adodbapi.apibase.SQLrow get the next row from the result set. Calls ADO recordset.GetRows(1)

Cursor.fetchmany(size=None)¶

Fetch the next set of rows of a query result, returning 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 executeXXX() 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.

returns adodbapi.apibase.SQLrows

get a size sequence of rows. Calls ADO recordset.GetRows(size)

Cursor.fetchall()¶

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 executeXXX() did not produce any result set or no call was issued yet.

attempt to retrieve all remaining rows in the result set. Calls ADO recordset.GetRows() using a local cursor so may use a great deal of memory if the query set is large.

Cursor.nextset()¶

Skip to the next available recordset, discarding any remaining rows from the current recordset.

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 executeXXX() did not produce any result set or no call was issued yet.

If an operation (such as a stored procedure call) has produced multiple result sets, skip to the next available result set.

Cursor.setinputsizes(sizes)¶

Cursor.setoutputsize(size, column=None)¶

Methods (extensions)¶

Cursor.prepare(operation)¶

initiate an SQL prepared statement.

This method actually does very little, and the use of it may not speed up your program very much, if at all. It does store the SQL statement you pass (operation) in the cursor’s self.command attribute, and sends the appropriate flag to ADO. It will cache converted paramstyle operation strings. Calling .execute() with any other string, or calling .prepare() again will invalidate the preparation.

For example: cursor.executemany() is programmed internally like:
def executemany(self, operation, sequence_of_parameter_sequences):
    self.prepare(operation)
    for params in sequence_of_parameter_sequences:
        self.execute(self.command, params)

Cursor.get_returned_parameters()¶

with some providers, returned parameters and the .return_value are not available until after the last recordset has been read. In that case, you must coll nextset() until it returns None, then call this method to get your returned information.

some providers will not return the (modified) parameter list, nor the return_value, until after the last recordset is closed. This method can be called (_after_ calling nextset() until it returns None) to get those values.

Cursor.__next__()¶: The cursor can be used as an iterator, each iteration does fetchone()

Cursor.__iter__()¶

Cursor.__enter__()¶

Allow database cursors to be used with context managers.

the cursor is a context manager which will auto-close

Cursor.__exit__(exc_type, exc_val, exc_tb)¶: Allow database cursors to be used with context managers.

connect¶

adodbapi.connect(*args, **kwargs)¶

Connect to a database.

call using: :connection_string – An ADODB formatted connection string, see: * http://www.connectionstrings.com * http://www.asp101.com/articles/john/connstring/default.asp :timeout – A command timeout value, in seconds (default 30 seconds)

returns adodbapi.adodbapi.Connection

adodbapi.apibase ¶

adodbapi.apibase - A python DB API 2.0 (PEP 249) interface to Microsoft ADO

adodbapi.apibase.BINARY = <adodbapi.apibase.DBAPITypeObject object>¶: This type object is used to describe numeric columns in a database.

adodbapi.apibase.DATETIME = <adodbapi.apibase.DBAPITypeObject object>¶: This type object is used to describe the “Row ID” column in a database.

class adodbapi.apibase.DBAPITypeObject(valuesTuple)¶: Bases: object

exception adodbapi.apibase.DataError¶: Bases: DatabaseError

exception adodbapi.apibase.DatabaseError¶: Bases: Error

exception adodbapi.apibase.Error¶: Bases: Exception

exception adodbapi.apibase.FetchFailedError¶

Bases: OperationalError

Error is used by RawStoredProcedureQuerySet to determine when a fetch failed due to a connection being closed or there is no record set returned. (Non-standard, added especially for django)

exception adodbapi.apibase.IntegrityError¶: Bases: DatabaseError

exception adodbapi.apibase.InterfaceError¶: Bases: Error

exception adodbapi.apibase.InternalError¶: Bases: DatabaseError

class adodbapi.apibase.MultiMap(aDict)¶

Bases: dict

A dictionary of ado.type : function – but you can set multiple items by passing a sequence of keys

adodbapi.apibase.NUMBER = <adodbapi.apibase.DBAPITypeObject object>¶: This type object is used to describe date/time columns in a database.

exception adodbapi.apibase.NotSupportedError¶: Bases: DatabaseError

exception adodbapi.apibase.OperationalError¶: Bases: DatabaseError

exception adodbapi.apibase.ProgrammingError¶: Bases: DatabaseError

class adodbapi.apibase.SQLrow(rows, index)¶: Bases: object

class adodbapi.apibase.SQLrows(ado_results, numberOfRows, cursor)¶: Bases: object

adodbapi.apibase.STRING = <adodbapi.apibase.DBAPITypeObject object>¶: This type object is used to describe (long) binary columns in a database (e.g. LONG, RAW, BLOBs).

class adodbapi.apibase.TimeConverter¶

Bases: object

COMDate(obj)¶: Returns a ComDate from a date-time

ComDateFromTuple(t, microseconds=0)¶

Date(year, month, day)¶: This function constructs an object holding a date value.

DateObjectFromCOMDate(comDate)¶: Returns an object of the wanted type from a ComDate

DateObjectToIsoFormatString(obj)¶: This function should return a string in the format ‘YYYY-MM-dd HH:MM:SS:ms’ (ms optional)

Time(hour, minute, second)¶: This function constructs an object holding a time value.

Timestamp(year, month, day, hour, minute, second)¶: This function constructs an object holding a time stamp value.

exception adodbapi.apibase.Warning¶: Bases: Exception

adodbapi.apibase.changeFormatToQmark(op)¶

adodbapi.apibase.changeNamedToQmark(op)¶

adodbapi.apibase.convert_to_python(variant, func)¶

adodbapi.apibase.cvtBuffer(variant)¶

adodbapi.apibase.cvtDecimal(variant)¶

adodbapi.apibase.cvtFloat(variant)¶

adodbapi.apibase.cvtInt(variant)¶

adodbapi.apibase.cvtLong(variant)¶

adodbapi.apibase.cvtNumeric(variant)¶

adodbapi.apibase.cvtString(variant)¶

adodbapi.apibase.cvtUnicode(variant)¶

adodbapi.apibase.cvtUnusual(variant)¶

adodbapi.apibase.identity(x)¶

class adodbapi.apibase.mxDateTimeConverter¶: Bases: TimeConverter

adodbapi.apibase.pyTypeToADOType(d)¶

class adodbapi.apibase.pythonDateTimeConverter¶

Bases: TimeConverter

Date(year, month, day)¶: This function constructs an object holding a date value.

DateObjectFromCOMDate(comDate)¶: Returns an object of the wanted type from a ComDate

Time(hour, minute, second)¶: This function constructs an object holding a time value.

Timestamp(year, month, day, hour, minute, second)¶: This function constructs an object holding a time stamp value.

class adodbapi.apibase.pythonTimeConverter¶

Bases: TimeConverter

Date(year, month, day)¶: This function constructs an object holding a date value.

DateObjectFromCOMDate(comDate)¶: Returns ticks since 1970

Time(hour, minute, second)¶: This function constructs an object holding a time value.

Timestamp(year, month, day, hour, minute, second)¶: This function constructs an object holding a time stamp value.

adodbapi.apibase.standardErrorHandler(connection, cursor, errorclass, errorvalue)¶

adodbapi.apibase.variantConvertDate(v)¶

adodbapi.is64bit ¶

is64bit.Python() –> boolean value of detected Python word size. is64bit.os() –> os build version

adodbapi.is64bit.Python()¶

adodbapi.is64bit.os()¶

adodbapi.process_connect_string ¶

a clumsy attempt at a macro language to let the programmer execute code on the server (ex: determine 64bit)

adodbapi.process_connect_string.macro_call(macro_name, args, kwargs)¶

allow the programmer to perform limited processing on the server by passing macro names and args

:new_key - the key name the macro will create :args[0] - macro name :args[1:] - any arguments :code - the value of the keyword item :kwargs - the connection keyword dictionary. ??key has been removed –> the value to put in for kwargs[‘name’] = value

adodbapi.process_connect_string.process(args, kwargs, expand_macros=False)¶

attempts to inject arguments into a connection string using Python “%” operator for strings

co: adodbapi connection object args: positional parameters from the .connect() call kvargs: keyword arguments from the .connect() call

adodbapi.schema_table ¶

call using an open ADO connection –> list of table names

adodbapi.schema_table.names(connection_object)¶

adodbapi package¶

adodbapi ¶

adodbapi.ado_consts ¶

adodbapi.Connection ¶

Connection methods¶

Connection methods (non-standard)¶

Connection attributes¶

adodbapi.Cursor ¶

Attributes¶

Attributes (standard extensions)¶

Attributes (non-standard)¶

Methods (standard)¶

Methods (extensions)¶

connect¶

adodbapi.apibase ¶

adodbapi.is64bit ¶

adodbapi.process_connect_string ¶

adodbapi.schema_table ¶

pywin32

Navigation