wsql package — WSQL 1.2.1 documentation

# wsql package

## Subpackages

- wsql.cluster package
  - Submodules
  - wsql.cluster.cluster module
    - WSQL
      - An asynchronous DB API v2.0 compatible interface to MySQL
  - wsql.cluster.functional module
    - WSQL
      - An asynchronous DB API v2.0 compatible interface to MySQL
  - wsql.cluster.pool module
    - WSQL
      - An asynchronous DB API v2.0 compatible interface to MySQL
  - wsql.cluster.upstream module
    - WSQL
      - An asynchronous DB API v2.0 compatible interface to MySQL
  - Module contents
    - WSQL
      - An asynchronous DB API v2.0 compatible interface to MySQL

## Submodules

## wsql.connections module

### WSQL

#### An asynchronous DB API v2.0 compatible interface to MySQL

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

`wsql.connections.` `connect`(*args, loop=<object object>, **kwargs)

  Create a connection to the database. It is strongly recommended that you only use keyword parameters. Consult the MySQL C API documentation for more information.

  Parameters: | host (str) – the hostname user (str) – user to connect as password (str) – password to use database (str) – database to use port (int) – TCP/IP port to connect to socket_name (str) – the UNIX socket name to use for connections to “localhost” under UNIX or the pipe name for named pipe connections under Windows. decoders (list|tuple) – SQL decoder stack encoders (list|tuple) – SQL encoder stack row_formatter – the function to format row connect_timeout (number) – number of seconds to wait before the connection attempt fails. compress (bool) – if set, compression is enabled init_command (str) – command which is run once the connection is created read_default_file (str) – file from which default client values are read read_default_group (str) – configuration group to use from the default file charset (str) – If supplied, the connection character set will be changed to this character set (MySQL-4.1 and newer). This implies use_unicode=True. sql_mode (int) – If supplied, the session SQL mode will be changed to this setting (MySQL-4.1 and newer). For more details and legal values, see the MySQL documentation. client_flag – flags to use or 0 (see MySQL docs or constants.CLIENT_*) ssl (dict|mapping) – dictionary or mapping, contains SSL connection parameters; see the MySQL documentation for more details (mysql_ssl_set()). If this is set, and the client does not support SSL, NotSupportedError will be raised. local_infile (bool) – integer, non-zero enables LOAD LOCAL INFILE; zero disables loop – the event-loop, if specified the asynchronous connection will be created defer_warnings (bool) – if True, the warnings will be ignored use_result (bool) – store results on server or use buffered results
  Returns: | new coroutine in nonblocking mode and connection otherwise

## wsql.converters module

### WSQL

#### An asynchronous DB API v2.0 compatible interface to MySQL

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

`wsql.converters.` `any_to_sql`(connection, obj)

  Convert any object to sql literal.

`wsql.converters.` `bit_or_None_if_NULL`(value)

`wsql.converters.` `bool_to_sql`(_, value)

  Convert a Python bool to an SQL literal.

`wsql.converters.` `bytes_or_None_if_NULL`(value)

`wsql.converters.` `bytes_to_sql`(connection, value)

  Convert a bytes object to a sql string literal

`wsql.converters.` `character_decoder`(connection, field)

  convert value of mysql string type to python associated python type

`wsql.converters.` `date_or_None_if_NULL`(value)

`wsql.converters.` `datetime_or_None_if_NULL`(value)

`wsql.converters.` `datetime_to_sql`(_, obj)

  Convert a datetime to a SQL literal

`wsql.converters.` `decimal_or_None_if_NULL`(value)

`wsql.converters.` `decimal_to_sql`(_, value)

  Convert Decimal to sql literal

`wsql.converters.` `default_decoder`(*_)

  by default, convert to bytes

`wsql.converters.` `default_encoder`(_, value)

  Convert an Instance to a string representation. If the __str__() method produces acceptable output, then you don’t need to add the class to conversions; it will be handled by the default converter. If the exact class is not found in conv, it will use the first class it can find for which obj is an instance.

`wsql.converters.` `default_row_formatter`(decoders, names, row)

  convert mysql row to tuple :param decoders: the row decoder :param names: the field names :param row: the raw row” :return the formatted row list :rtype: tuple

`wsql.converters.` `dict_row_decoder`(decoders, names, row)

  decode row as dict :param decoders: the row decoder :param names: field names :param row: the formatted row :return: the dict :rtype: dict

`wsql.converters.` `float_or_None_if_NULL`(value)

`wsql.converters.` `float_to_sql`(_, value)

  Convert float to sql literal

`wsql.converters.` `get_codec`(connection, field, codecs)

  select codec :param connection: the connection object :param field: the value to convert :param codecs: the list of codecs :return: the function to convert specified field :raises: connection.NotSupportedError if there is no known converted to field

`wsql.converters.` `int_or_None_if_NULL`(value)

`wsql.converters.` `int_to_sql`(_, value)

  Convert a bytes object to a sql int literal

`wsql.converters.` `iter_row_decoder`(decoders, _, row)

  convert mysql row to iterable object :param decoders: the row decoder :param row: the raw row” :return the formatted row with delayed eval :rtype: generator

`wsql.converters.` `none_if_null`(func)

  decorator, call function only if value is not None, otherwise return None

`wsql.converters.` `none_to_sql`(*_)

  Convert None to NULL.

`wsql.converters.` `set_to_sql`(connection, value)

  Convert a Python set to an SQL literal.

`wsql.converters.` `simple_decoder`(_, field)

  convert according to predefined rules

`wsql.converters.` `simple_encoder`(_, value)

  convert according to predefined rules

`wsql.converters.` `sql_to_bit`(value)

  Returns BIT columntype as integer

`wsql.converters.` `sql_to_date`(obj)

  Convert a SQL literal to date

`wsql.converters.` `sql_to_datetime`(obj)

  Convert a SQL literal to datetime

`wsql.converters.` `sql_to_decimal`(value)

  Convert SQL literal to Decimal

`wsql.converters.` `sql_to_timedelta`(obj)

  Convert a SQL literal to timedelta

`wsql.converters.` `str_to_sql`(connection, value)

  Convert a string object to a sql string literal by using connection encoding.

`wsql.converters.` `timedelta_or_None_if_NULL`(value)

`wsql.converters.` `timedelta_to_sql`(_, obj)

  Convert timedelta to a SQL literal

`wsql.converters.` `tuple_row_decoder`(decoders, names, row)

  convert mysql row to tuple :param decoders: the row decoder :param names: the field names :param row: the raw row” :return the formatted row list :rtype: tuple

## wsql.cursors module

### WSQL

#### An asynchronous DB API v2.0 compatible interface to MySQL

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

class `wsql.cursors.` `AsyncCursor`(connection, encoders, decoders, row_formatter)

  Bases: `wsql.cursors.CursorBase`

  Asynchronous cursor implementation

  `NET_ASYNC_COMPLETE` = 20100
  `callproc`(procname, args=())

    Execute stored procedure procname with args

    Parameters: | procname – string, name of procedure to execute on server args – Sequence of parameters to use with procedure

    :return the original args. (update args for inout parameters additional performance penalty, skip it)

  `close`()

    close cursor and free resources

  `execute`(query, args=None)

    Execute a query. :param query: query to execute on server :param args: optional sequence or mapping, parameters to use with query. Note! If args is a sequence, then %s must be used as the parameter placeholder in the query. If a mapping is used, %(key)s must be used as the placeholder.

  `executemany`(query, args)

    Execute a multi-row query. This method improves performance on multiple-row INSERT and REPLACE. Otherwise it is equivalent to looping over args with execute().

    Parameters: | query – query to execute on server args – Sequence of sequences or mappings, parameters to use with query.

  `fetchall`()

    Fetches all available rows from the cursor.

  `fetchmany`(size=None)

    Fetch up to size rows from the cursor. Result set may be smaller than size. If size is not defined, cursor.arraysize is used.

  `fetchone`()

    Fetches a single row from the cursor. None indicates that no more rows are available. :return formatted row or None if there is no more rows

  `fetchxall`()

    Same as self.nextset(), self.fetchall() Not standard

  `nextset`()

    Advance to the next result set. Returns False if there are no more result sets.

  `rowcount`

    number of row in current result, always return -1

  `scroll`(offset, mode='relative')

    Scroll the cursor in the result set to a new position according to mode. If mode is ‘relative’ (default), value is taken as offset to the current position in the result set, if set to ‘absolute’, value states an absolute target position. Not supported yet

  `warning_check`()

    Check for warnings, and report via the warnings module.

class `wsql.cursors.` `Cursor`(connection, encoders, decoders, row_formatter)

  Bases: `wsql.cursors.CursorBase`

  `callproc`(procname, args=())

    Execute stored procedure procname with args

    Parameters: | procname – string, name of procedure to execute on server args – Sequence of parameters to use with procedure

    :return the original args. (update args for inout parameters additional performance penalty, skip it)

  `close`()

    close cursor and release resources

  `execute`(query, args=None)

    Execute a query. :param query: string, query to execute on server :param args: optional sequence or mapping, parameters to use with query. Note! If args is a sequence, then %s must be used as the parameter placeholder in the query. If a mapping is used, %(key)s must be used as the placeholder.

  `executemany`(query, args)

    Execute a multi-row query. This method improves performance on multiple-row INSERT and REPLACE. Otherwise it is equivalent to looping over args with execute().

    Parameters: | query – string, query to execute on server args – Sequence of sequences or mappings, parameters to use with query.

  `fetchall`()

    Fetches all available rows from the cursor.

  `fetchmany`(size=None)

    Fetch up to size rows from the cursor. Result set may be smaller than size. If size is not defined, cursor.arraysize is used.

  `fetchone`()

    Fetches a single row from the cursor. None indicates that no more rows are available. :return formatted row or None if there is no more rows

  `fetchxall`()

    Same as self.fetchall(), self.next() Not standard

  `nextset`()

    Advance to the next result set. Returns False if there are no more result sets.

  `scroll`(offset, mode='relative')

    Scroll the cursor in the result set to a new position according to mode. If mode is ‘relative’ (default), value is taken as offset to the current position in the result set, if set to ‘absolute’, value states an absolute target position. Not supported yet

  `warning_check`()

    Check for warnings, and report via the warnings module.

class `wsql.cursors.` `CursorBase`(connection, encoders, decoders, row_formatter)

  Bases: `object`

  A base for Cursor classes.

  exception `NotSupportedError`

    Bases: `_wsql.exceptions.DatabaseError`

    Exception raised in case a method or database API was usedwhich is not supported by the database, e.g. requesting a.rollback() on a connection that does not support transaction orhas transactions turned off.

  exception `CursorBase.` `ProgrammingError`

    Bases: `_wsql.exceptions.DatabaseError`

    Exception raised for programming errors, e.g. table not foundor already exists, syntax error in the SQL statement, wrong numberof parameters specified, etc.

  exception `CursorBase.` `StandardError`

    Bases: `Exception`

    Exception related to operation with MySQL.

  `CursorBase.` `connection`

    Get the database connection. Raises ProgrammingError if the connection has been closed.

  `CursorBase.` `description`

    This read-only attribute is a sequence of 7-item sequences. Each of these sequences contains information describing one result column.

  `CursorBase.` `errorhandler`(error)

    default error handler

  `CursorBase.` `lastrowid`

    Returns: | rowid of the last modified row (most databases return a rowid only when a single INSERT operation is performed). If the operation does not set a rowid or if the database does not support rowids, this attribute should be set to None.

  `CursorBase.` `rowcount`

    Returns: | the number of rows that the last .execute*() produced (for DQL statements like SELECT) or affected (for DML statements like UPDATE or INSERT)

  `CursorBase.` `rownumber`

    Not supported yet :return: the current 0-based index of the cursor in the result set or None if the index cannot be determined.

  static `CursorBase.` `setinputsizes`(*args)

    Does nothing, required by DB API.

  static `CursorBase.` `setoutputsizes`(*args)

    Does nothing, required by DB API.

## wsql.exceptions module

### WSQL

#### An asynchronous DB API v2.0 compatible interface to MySQL

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

exception `wsql.exceptions.` `Warning`

  Bases: `Warning`, `_wsql.exceptions.StandardError`

  Exception raised for important warnings like data truncations while inserting, etc.

exception `wsql.exceptions.` `Error`

  Bases: `_wsql.exceptions.StandardError`

  Exception that is the base class of all other error exceptions (not Warning).

exception `wsql.exceptions.` `InterfaceError`

  Bases: `_wsql.exceptions.Error`

  Exception raised for errors that are related to the database interface rather than the database itself.

exception `wsql.exceptions.` `DatabaseError`

  Bases: `_wsql.exceptions.Error`

  Exception raised for errors that are related to the database.

exception `wsql.exceptions.` `DataError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.

exception `wsql.exceptions.` `OperationalError`

  Bases: `_wsql.exceptions.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 notfound, a transaction could not be processed, a memory allocationerror occurred during processing, etc.

exception `wsql.exceptions.` `IntegrityError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised when the relational integrity of the databaseis affected, e.g. a foreign key check fails, duplicate key, etc.

exception `wsql.exceptions.` `InternalError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised when the database encounters an internalerror, e.g. the cursor is not valid anymore, the transaction is out of sync, etc.

exception `wsql.exceptions.` `ProgrammingError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised for programming errors, e.g. table not foundor already exists, syntax error in the SQL statement, wrong numberof parameters specified, etc.

exception `wsql.exceptions.` `NotSupportedError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised in case a method or database API was usedwhich is not supported by the database, e.g. requesting a.rollback() on a connection that does not support transaction orhas transactions turned off.

exception `wsql.exceptions.` `StandardError`

  Bases: `Exception`

  Exception related to operation with MySQL.

exception `wsql.exceptions.` `UserError`(code, message)

  Bases: `_wsql.exceptions.ProgrammingError`

  base class for all user defined exceptions

`wsql.exceptions.` `handle_error`(exceptions, error, sep=';')

  handle exceptions from SQL procedures according to format <classname><sep><message> :param exceptions: the module with all user defined exceptions :param error: sql error :param sep: (optional), the class, message separator

## wsql.times module

### WSQL

#### An asynchronous DB API v2.0 compatible interface to MySQL

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

`wsql.times.` `Date`

  alias of `date`

`wsql.times.` `Time`

  alias of `time`

`wsql.times.` `TimeDelta`

  alias of `timedelta`

`wsql.times.` `Timestamp`

  alias of `datetime`

`wsql.times.` `DateFromTicks`(ticks)

  Convert UNIX ticks into a date instance. >>> date_from_ticks(1172466380) datetime.date(2007, 2, 26) >>> date_from_ticks(0) datetime.date(1970, 1, 1) >>> date_from_ticks(2 ** 31 - 1) datetime.date(2038, 1, 19)

  This is a standard DB-API constructor.

`wsql.times.` `TimeFromTicks`(ticks)

  Convert UNIX ticks into a time instance.

      >>> time_from_ticks(1172466380)
      datetime.time(8, 6, 20)
      >>> time_from_ticks(0)
      datetime.time(3, 0)
      >>> time_from_ticks(2 ** 31 - 1)
      datetime.time(6, 14, 7)

  This is a standard DB-API constructor.

`wsql.times.` `TimestampFromTicks`(ticks)

  Convert UNIX ticks into a datetime instance.

      >>> timestamp_from_ticks(1172466380)
      datetime.datetime(2007, 2, 26, 8, 6, 20)
      >>> timestamp_from_ticks(0)
      datetime.datetime(1970, 1, 1, 3, 0)
      >>> timestamp_from_ticks(2 ** 31 - 1)
      datetime.datetime(2038, 1, 19, 6, 14, 7)

  This is a standard DB-API constructor.

## Module contents

### WSQL

#### An asynchronous DB API v2.0 compatible interface to MySQL

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

`wsql.` `connect`(*args, loop=<object object>, **kwargs)

  Create a connection to the database. It is strongly recommended that you only use keyword parameters. Consult the MySQL C API documentation for more information.

  Parameters: | host (str) – the hostname user (str) – user to connect as password (str) – password to use database (str) – database to use port (int) – TCP/IP port to connect to socket_name (str) – the UNIX socket name to use for connections to “localhost” under UNIX or the pipe name for named pipe connections under Windows. decoders (list|tuple) – SQL decoder stack encoders (list|tuple) – SQL encoder stack row_formatter – the function to format row connect_timeout (number) – number of seconds to wait before the connection attempt fails. compress (bool) – if set, compression is enabled init_command (str) – command which is run once the connection is created read_default_file (str) – file from which default client values are read read_default_group (str) – configuration group to use from the default file charset (str) – If supplied, the connection character set will be changed to this character set (MySQL-4.1 and newer). This implies use_unicode=True. sql_mode (int) – If supplied, the session SQL mode will be changed to this setting (MySQL-4.1 and newer). For more details and legal values, see the MySQL documentation. client_flag – flags to use or 0 (see MySQL docs or constants.CLIENT_*) ssl (dict|mapping) – dictionary or mapping, contains SSL connection parameters; see the MySQL documentation for more details (mysql_ssl_set()). If this is set, and the client does not support SSL, NotSupportedError will be raised. local_infile (bool) – integer, non-zero enables LOAD LOCAL INFILE; zero disables loop – the event-loop, if specified the asynchronous connection will be created defer_warnings (bool) – if True, the warnings will be ignored use_result (bool) – store results on server or use buffered results
  Returns: | new coroutine in nonblocking mode and connection otherwise

exception `wsql.` `Warning`

  Bases: `Warning`, `_wsql.exceptions.StandardError`

  Exception raised for important warnings like data truncations while inserting, etc.

exception `wsql.` `Error`

  Bases: `_wsql.exceptions.StandardError`

  Exception that is the base class of all other error exceptions (not Warning).

exception `wsql.` `InterfaceError`

  Bases: `_wsql.exceptions.Error`

  Exception raised for errors that are related to the database interface rather than the database itself.

exception `wsql.` `DatabaseError`

  Bases: `_wsql.exceptions.Error`

  Exception raised for errors that are related to the database.

exception `wsql.` `DataError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.

exception `wsql.` `OperationalError`

  Bases: `_wsql.exceptions.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 notfound, a transaction could not be processed, a memory allocationerror occurred during processing, etc.

exception `wsql.` `IntegrityError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised when the relational integrity of the databaseis affected, e.g. a foreign key check fails, duplicate key, etc.

exception `wsql.` `InternalError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised when the database encounters an internalerror, e.g. the cursor is not valid anymore, the transaction is out of sync, etc.

exception `wsql.` `ProgrammingError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised for programming errors, e.g. table not foundor already exists, syntax error in the SQL statement, wrong numberof parameters specified, etc.

exception `wsql.` `NotSupportedError`

  Bases: `_wsql.exceptions.DatabaseError`

  Exception raised in case a method or database API was usedwhich is not supported by the database, e.g. requesting a.rollback() on a connection that does not support transaction orhas transactions turned off.

exception `wsql.` `StandardError`

  Bases: `Exception`

  Exception related to operation with MySQL.

`wsql.` `Date`

  alias of `date`

`wsql.` `Time`

  alias of `time`

`wsql.` `Timestamp`

  alias of `datetime`

`wsql.` `DateFromTicks`(ticks)

  Convert UNIX ticks into a date instance. >>> date_from_ticks(1172466380) datetime.date(2007, 2, 26) >>> date_from_ticks(0) datetime.date(1970, 1, 1) >>> date_from_ticks(2 ** 31 - 1) datetime.date(2038, 1, 19)

  This is a standard DB-API constructor.

`wsql.` `TimeFromTicks`(ticks)

  Convert UNIX ticks into a time instance.

      >>> time_from_ticks(1172466380)
      datetime.time(8, 6, 20)
      >>> time_from_ticks(0)
      datetime.time(3, 0)
      >>> time_from_ticks(2 ** 31 - 1)
      datetime.time(6, 14, 7)

  This is a standard DB-API constructor.

`wsql.` `TimestampFromTicks`(ticks)

  Convert UNIX ticks into a datetime instance.

      >>> timestamp_from_ticks(1172466380)
      datetime.datetime(2007, 2, 26, 8, 6, 20)
      >>> timestamp_from_ticks(0)
      datetime.datetime(1970, 1, 1, 3, 0)
      >>> timestamp_from_ticks(2 ** 31 - 1)
      datetime.datetime(2038, 1, 19, 6, 14, 7)

  This is a standard DB-API constructor.

`wsql.` `Binary`

  alias of `bytes`