_dbi_sqlite - Private database interface for SQLite — dbilib - v0.5.0 Documentation

# _dbi_sqlite - Private database interface for SQLite

Purpose:

  This module contains the library’s SQLite database methods and attribute accessors; which are a specialised version of the `_dbi_base._DBIBase` class methods.

Platform:

  Linux/Windows | Python 3.10+

Developer:

  J Berendt

Email:

  support@s3dev.uk

Comments:

  n/a

Example:

  For class-specific usage examples, please refer to the docstring for the following classes:

  > - `_DBISQLite`

class _DBISQLite(connstr: str)

  Bases: `_DBIBase`

  This private class holds the methods and properties which are used for accessing SQLite databases.

  Note

  This class is not designed to be interacted with directly.

  Rather, please use the `database.DBInterface` class instead, as the proper interface class has an automatic switch for database interfaces, based on the `sqlalchemy.Engine` object which is created from the connection string.

  Parameters:

    connstr (str) – The database-specific SQLAlchemy connection string.

  Example Use:

    This low-level generalised class is designed to be inherited by the calling/wrapping class as:

        >>> from dbilib.database import DBInterface

        class MyDB(DBInterface):

            def __init__(self, connstr: str):
                super().__init__(connstr=('sqlite:////path/to/database.db'))

  table_exists(table_name: str, verbose: bool = False) → bool

    Using the `engine` object, test if the given table exists.

    Parameters:

      - table_name (str) – Name of the table to test.

      - verbose (bool, optional) – Print a message if the table does not exist. Defaults to False.

    Returns:

      True if the given table exists, otherwise False.

    Return type:

      bool

  _verify_db_exists()

    Verify the database file exists.

    Raises:

      - FileNotFoundError – Raised if the database file passed via the

      - connection string does not exist. –

  _create_engine() → sqlalchemy.engine.base.Engine

    Create a database engine using the provided environment.

    Returns:

      A sqlalchemy database engine object.

    Return type:

      sqlalchemy.engine.base.Engine

  static _is_dangerous(stmt: str) → bool

    Perform a dirty security check for injection attempts.

    Parameters:

      stmt (str) – SQL statement to be potentially executed.

    Raises:

      SecurityWarning – If there are multiple semi-colons (`;`) in the statement, or any comment delimiters (`--`).

    Returns:

      False if the checks pass.

    Return type:

      bool

  _report_sa_error(msg: str, error: sqlalchemy.exc.SQLAlchemyError)

    Report SQLAlchemy error to the terminal.

    Parameters:

      - msg (str) – Additional error to be displayed. This message will be automatically prefixed with ‘[DatabaseError]: ‘

      - error (sqlalchemy.exc.SQLAlchemyError) – Caught error object from the try/except block.

  static _result_to_df__cursor(result: sqlalchemy.engine.cursor.CursorResult) → DataFrame

    Convert a `CursorResult` object to a DataFrame.

    If the cursor did not return results, an empty DataFrame containing the column names only, is returned.

    Parameters:

      result (sqlalchemy.engine.cursor.CursorResult) – Object to be converted.

    Returns:

      A `pandas.DataFrame` object containing the cursor’s data.

    Return type:

      pd.DataFrame

  static _result_to_df__stored(result: object) → DataFrame

    Convert a `MySQLCursor.stored_results` object to a DataFrame.

    Parameters:

      - result (object) – The `cursor.stored_results()` object from

      - call. (a sqlalchemy or mysql.connector procedure)

    Returns:

      A DataFrame containing the results from the procedure call.

    Return type:

      pd.DataFrame

  property database_name

    Accessor to the database name used by the `engine` object.

  property engine

    Accessor to the `sqlalchemy.engine.base.Engine` object.

  execute_query(stmt: str, params: dict = None, *, raw: bool = True, flat: bool = False, commit: bool = True, ignore_unsafe: bool = False) → list | DataFrame | None

    Execute a query statement.

    Important

    The following are not allowed to be executed by this method:

    > - Statements containing multiple semi-colons (`;`).

    > - Statements containing a comment delimiter (`--`).

    If found, a `SecurityWarning` will be raised by the `_is_dangerous()` method.

    Parameters:

      - stmt (str) – Statement to be executed. The parameter bindings are to be written in colon format.

      - params (dict, optional) – Parameter key/value bindings as a dictionary, if applicable. Defaults to None.

      - raw (bool, optional) – Return the data in ‘raw’ (tuple) format rather than as a formatted DataFrame. Defaults to True for efficiency.

      - flat (bool, optional) – Flatten the response. This is useful if the expected response is a collection of single elements. If True, this will return a flattened tuple of elements, rather than a list of tuples, as is the default behaviour. Note (1): If true, and the return is a list of multi-value tuples, only the first element in each tuple will be returned. Note (2): This argument should only be used if `raw=True`. Defaults to False.

      - commit (bool, optional) – Call COMMIT after the transaction is complete. Defaults to True (for backwards compatibility).

      - ignore_unsafe (bool, optional) –

        Bypass the ‘is dangerous’ check and the run query anyway. This may be required if a script contains multiple statements. Defaults to False.

        WARNING: HC SVNT DRACONES

    If the query did not return results and the `raw` argument is False, an empty DataFrame containing the column names only, is returned.

    Note

    In the SQL query, the bind parameters are specified by name, using the format `:bind_name`. The `params` dictionary argument must contain the associated parameter name/value bindings.

    Warning

    1. Generally, whatever statement is passed into this method will be executed, and may have destructive implications.

    2. This method contains a `commit` call, and the option to disable the COMMIT.

    If a statement is passed into this method, and the user has the appropriate permissions - the change will be committed.

    … HC SVNT DRACONES.

    Returns:

      If the `raw` parameter is True, a list of tuples containing values is returned. Otherwise, a `pandas.DataFrame` object containing the returned data is returned.

      If this method is called with a script which does not return results, for example a CREATE script, None is returned; regardless of the value passed to the `raw` parameter.

    Return type:

      list | pd.DataFrame | None