snowmobile.core.connection

Snowmobile is the core of snowmobile’s object model and a given instance is often shared across multiple objects at once.

It is the primary method of executing statement against the warehouse and it stores the fully parsed & validated snowmobile.toml file it was instantiated with as its cfg attribute.

Within snowmobile’s code and documentation, it is referred to as sn for brevity.

Module Contents

Classes

Snowmobile

Primary method of statement execution and accessor to parsed snowmobile.toml.

class snowmobile.core.connection.Snowmobile(creds: Optional[str] = None, delay: bool = False, ensure_alive: bool = True, config_file_nm: Optional[str] = None, from_config: Optional[str, Path] = None, silence: bool = False, **connect_kwargs)

Bases: snowmobile.core.sql.SQL

Primary method of statement execution and accessor to parsed snowmobile.toml.

Parameters

  • creds (Optional[str]) – Alias for the set of credentials to authenticate with; default behavior will fall back to the connection.default-creds specified in snowmobile.toml, or the first set of credentials stored if this configuration option is left blank.

  • delay (bool) – Optionally delay establishing a connection when the object is instantiated, enabling access to the configuration object model through the Connection.cfg attribute; defaults to False.

  • ensure_alive (bool) – Establish a new connection if a method requiring a connection against the database is called while alive is False; defaults to True.

  • config_file_nm (Optional[str]) – Name of configuration file to use; defaults to snowmobile.toml.

  • from_config (Optional[str, Path]) – A full path to a specific configuration file to use; bypasses any checks for a cached file location and can be useful for container-based processes with restricted access to the local file system.

  • **connect_kwargs –

    Additional arguments to provide to snowflake.connector.connect(); arguments provided here will over-ride connection arguments specified in snowmobile.toml, including:

    • Connection parameters in connection.default-arguments

    • Credentials parameters associated with a given alias

    • Connection parameters associated with a given alias

Initializes a snowmobile.SQL object.

cfg :Configuration

snowmobile.toml

Type

snowmobile.core.configuration.Configuration

con :Optional[SnowflakeConnection]

Can be None until set by Snowmobile.connect()

Type

SnowflakeConnection

e :ExceptionHandler

Exception / context management

Type

snowmobile.core.exception_handler.ExceptionHandler

ensure_alive :bool

Reconnect to Snowflake if connection is lost

Type

bool

connect(self, **kwargs) → snowmobile.core.connection.Snowmobile

Establishes connection to Snowflake.

Re-implements snowflake.connector.connect() with connection arguments sourced from snowmobile’s object model, specifically:

  • Credentials from snowmobile.toml.

  • Default connection arguments from snowmobile.toml.

  • Optional keyword arguments either passed to snowmobile.connect() or directly to this method.

kwargs:

Optional keyword arguments to pass to snowflake.connector.connect(); arguments passed here will over-ride connection.default-arguments specified in snowmobile.toml.

disconnect(self) → snowmobile.core.connection.Snowmobile

Disconnect from connection with which Connection() was instantiated.

property alive(self) → bool

Check if the connection is alive.

property cursor(self) → snowflake.connector.connection.SnowflakeCursor

SnowflakeCursor accessor.

property dictcursor(self) → snowflake.connector.DictCursor

DictCursor accessor.

ex(self, sql: str, on_error: Optional[str] = None, **kwargs) → snowflake.connector.connection.SnowflakeCursor

Executes a command via SnowflakeCursor.

Parameters

  • sql (str) – sql command as a string.

  • on_error (str) – String value to impose a specific behavior if an error occurs during the execution of sql.

  • **kwargs – Optional keyword arguments for SnowflakeCursor.execute().

Returns (SnowflakeCursor):

SnowflakeCursor object that executed the command.

exd(self, sql: str, on_error: Optional[str] = None, **kwargs) → snowflake.connector.DictCursor

Executes a command via DictCursor.

Parameters

  • sql (str) – sql command as a string.

  • on_error (str) – String value to impose a specific behavior if an error occurs during the execution of sql.

  • **kwargs – Optional keyword arguments for SnowflakeCursor.execute().

Returns (DictCursor):

DictCursor object that executed the command.

query(self, sql: str, as_df: bool = False, as_cur: bool = False, as_dcur: bool = False, as_scalar: bool = False, lower: bool = True, on_error: Optional[str] = None) → Union[pd.DataFrame, SnowflakeCursor]

Execute a query and return results.

Default behavior of results=True will return results as a pandas.DataFrame, otherwise will execute the sql provided with a SnowflakeCursor and return the cursor object.

Parameters

  • sql (str) – Raw SQL to execute.

  • as_df (bool) – Return results in DataFrame.

  • as_cur (bool) – Return results in Cursor.

  • as_dcur (bool) – Return results in a DictCursor.

  • as_scalar (bool) – Return results as a single scalar value.

  • lower (bool) – Boolean value indicating whether or not to return results with columns lower-cased.

  • on_error (str) – String value to impose a specific behavior if an error occurs during the execution of sql.

Returns (Union[pd.DataFrame, SnowflakeCursor]):

Results from sql as a DataFrame by default or the SnowflakeCursor object if results=False.