:mod:`snowmobile.core.connection` ================================= .. py:module:: snowmobile.core.connection .. autoapi-nested-parse:: :class:`~snowmobile.core.connection.Snowmobile` is the core of :xref:`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 :attr:`~snowmobile.core.connection.Snowmobile.cfg` attribute. Within ``snowmobile``'s code and documentation, it is referred to as ``sn`` for brevity. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: snowmobile.core.connection.Snowmobile .. class:: 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: :class:`snowmobile.core.sql.SQL` Primary method of statement execution and accessor to parsed snowmobile.toml. :param creds: 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`. :type creds: Optional[str] :param delay: Optionally delay establishing a connection when the object is instantiated, enabling access to the configuration object model through the :attr:`Connection.cfg` attribute; defaults to `False`. :type delay: bool :param ensure_alive: Establish a new connection if a method requiring a connection against the database is called while :attr:`alive` is `False`; defaults to `True`. :type ensure_alive: bool :param config_file_nm: Name of configuration file to use; defaults to `snowmobile.toml`. :type config_file_nm: Optional[str] :param from_config: 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. :type from_config: Optional[str, Path] :param \*\*connect_kwargs: Additional arguments to provide to :xref:`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 :class:`snowmobile.SQL` object. .. attribute:: cfg :annotation: :Configuration *snowmobile.toml* :type: snowmobile.core.configuration.Configuration .. attribute:: con :annotation: :Optional[SnowflakeConnection] Can be `None` until set by :meth:`Snowmobile.connect()` :type: SnowflakeConnection .. attribute:: e :annotation: :ExceptionHandler Exception / context management :type: snowmobile.core.exception_handler.ExceptionHandler .. attribute:: ensure_alive :annotation: :bool Reconnect to :ref:`Snowflake` if connection is lost :type: bool .. method:: 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 :meth:`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``. .. method:: disconnect(self) -> snowmobile.core.connection.Snowmobile Disconnect from connection with which Connection() was instantiated. .. method:: alive(self) -> bool :property: Check if the connection is alive. .. method:: cursor(self) -> snowflake.connector.connection.SnowflakeCursor :property: :class:`SnowflakeCursor` accessor. .. method:: dictcursor(self) -> snowflake.connector.DictCursor :property: :class:`DictCursor` accessor. .. method:: ex(self, sql: str, on_error: Optional[str] = None, **kwargs) -> snowflake.connector.connection.SnowflakeCursor Executes a command via :class:`SnowflakeCursor`. :param sql: ``sql`` command as a string. :type sql: str :param on_error: String value to impose a specific behavior if an error occurs during the execution of ``sql``. :type on_error: str :param \*\*kwargs: Optional keyword arguments for :meth:`SnowflakeCursor.execute()`. Returns (SnowflakeCursor): :class:`SnowflakeCursor` object that executed the command. .. method:: exd(self, sql: str, on_error: Optional[str] = None, **kwargs) -> snowflake.connector.DictCursor Executes a command via :class:`DictCursor`. :param sql: ``sql`` command as a string. :type sql: str :param on_error: String value to impose a specific behavior if an error occurs during the execution of ``sql``. :type on_error: str :param \*\*kwargs: Optional keyword arguments for :meth:`SnowflakeCursor.execute()`. Returns (DictCursor): :class:`DictCursor` object that executed the command. .. method:: 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 :class:`pandas.DataFrame`, otherwise will execute the sql provided with a :class:`SnowflakeCursor` and return the cursor object. :param sql: Raw SQL to execute. :type sql: str :param as_df: Return results in DataFrame. :type as_df: bool :param as_cur: Return results in Cursor. :type as_cur: bool :param as_dcur: Return results in a DictCursor. :type as_dcur: bool :param as_scalar: Return results as a single scalar value. :type as_scalar: bool :param lower: Boolean value indicating whether or not to return results with columns lower-cased. :type lower: bool :param on_error: String value to impose a specific behavior if an error occurs during the execution of ``sql``. :type on_error: str Returns (Union[pd.DataFrame, SnowflakeCursor]): Results from ``sql`` as a :class:`DataFrame` by default or the :class:`SnowflakeCursor` object if `results=False`.