caller
======

.. py:module:: caller

.. autoapi-nested-parse::

   This module uses sqlalchemy and the user's database credentials to make calls
   directly to the database.

   This module requires two environment variables to be set:
   - USER_DB_USERNAME: The user's username for the database.
   - USER_DB_PASSWORD: The user's password for the database.



Exceptions
----------

.. autoapisummary::

   caller.DatabaseCallerException


Classes
-------

.. autoapisummary::

   caller.DatabaseCaller


Module Contents
---------------

.. py:exception:: DatabaseCallerException

   Bases: :py:obj:`Exception`


   Common base class for all non-exit exceptions.


.. py:class:: DatabaseCaller(username: Optional[str] = None, password: Optional[str] = None, db_url: Optional[str] = None, db_read_only_url: Optional[str] = None, db_name: Optional[str] = 'platform')

   Makes calls to the database using the user's credentials.


   .. py:method:: execute_sql_statement(statement: str | sqlalchemy.TextClause) -> sqlalchemy.Result

      Executes a SQL statement.

      :param statement: The SQL statement to execute. Can be either a string
                        or sqlalchemy TextClause.

      :returns:

                Sqlalchemy result object. See sqlalchemy documentation on
                    how to handle this further.
                    result.all() will return all results if applicable.
                    result.rowcount will return affected row count if applicable.
      :rtype: Result



   .. py:method:: read_sql_to_df(statement: str | sqlalchemy.TextClause, data: List[dict] | dict | None = None, **kwargs) -> pandas.DataFrame

      Reads a SQL statement and returns the data as a dataframe.

      :param statement: The SQL statement to execute. Can be either a string
                        or sqlalchemy TextClause. The format for data placeholders
                        in the statement should be :key.
      :param data: Optional dict or list of dicts to pass to the statement.
                   This will replace the :key placeholders in the statement
                   with the value. If a list of dicts is passed, the statement
                   will be executed for each dict in the list.
      :param kwargs: A dictionary of additional arguments to pass to the
                     underlying pandas.read_sql function

      :returns: The returned data from the SQL statement in a dataframe.



   .. py:method:: write_df_to_db_table(df, table_name: str, schema_name: str) -> int

      Inserts a dataframe into an existing table.

      Ignores index.

      :param df: The dataframe to insert.
      :param table_name: The name of the table to insert into.
      :param schema_name: The name of the schema to insert into.

      :returns: The number of rows inserted.



   .. py:attribute:: _name


   .. py:attribute:: _password


   .. py:attribute:: _read_url


   .. py:attribute:: _username


   .. py:attribute:: _write_url


   .. py:attribute:: read_engine


   .. py:attribute:: write_engine