:mod:`snowmobile.core.statement` ================================ .. py:module:: snowmobile.core.statement .. autoapi-nested-parse:: Base class for all :class:`Statement` objects. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: snowmobile.core.statement.Time snowmobile.core.statement.Statement .. class:: Time(**data) Bases: :class:`pydantic.BaseModel` Container for execution time info. .. attribute:: started :annotation: :int .. attribute:: ended :annotation: :int .. class:: Statement(sn: snowmobile.core.connection.Snowmobile, statement: Union[(sqlparse.sql.Statement, str)], index: Optional[int] = None, attrs_raw: Optional[str] = None, e: Optional[ExceptionHandler] = None, **kwargs) Bases: :class:`snowmobile.core.tag.Attrs`, :class:`snowmobile.core.Name`, :class:`snowmobile.core.Generic` Base class for all :class:`Statement` objects. Home for attributes and methods that are associated with **all** statement objects, generic or QA. .. attribute:: sn :class:`snowmobile.connect` object. :type: snowmobile.connect .. attribute:: statement A :class:`sqlparse.sql.Statement` object. :type: Union[sqlparse.sql.Statement, str] .. attribute:: index The context-specific index position of a statement within a script; can be `None`. :type: int .. attribute:: patterns :class:`config.Pattern` object for more succinct access to values specified in **snowmobile.toml**. :type: config.Pattern .. attribute:: results The results of the statement if executed as a :class:`pandas.DataFrame`. :type: pd.DataFrame .. attribute:: outcome Numeric indicator of outcome; defaults to `0` and is modified based on the outcome of statement execution and/or QA validation for derived classes. :type: int .. attribute:: outcome_txt Plain text of outcome ('skipped', 'failed', 'completed', 'passed'). :type: str .. attribute:: outcome_html HTML text for the outcome as an admonition/information banner based on the following mapping of :attr:`outcome_txt` to admonition argument: * `failed` ------> `warning` * `completed` --> `info` * `passed` -----> `success` :type: str .. attribute:: start_time Unix timestamp of the query start time if executed; 0 otherwise. :type: int .. attribute:: end_time Unix timestamp of the query end time if executed; 0 otherwise. :type: int .. attribute:: execution_time Execution time of the query in seconds if executed; 0 otherwise. :type: int .. attribute:: execution_time_txt Plain text description of execution time if executed; returned in seconds if execution time is less than 60 seconds, minutes otherwise. :type: str .. attribute:: first_keyword The first keyword within the statement as a :class:`sqlparse.sql.Token`. :type: sqlparse.sql.Token .. attribute:: sql The sql associated with the statement as a raw string. :type: str Initialize self. See help(type(self)) for accurate signature. .. method:: sql(self, set_as: Optional[str] = None, tag: bool = False) -> Union[(str, Statement)] Raw sql from statement, including result limit if enabled. .. method:: parse(self) -> Tuple[(Dict, str)] Parses tag contents into a valid dictionary. Uses the values specified in **snowmobile.toml** to parse a raw string of statement attributes into a valid dictionary. .. note:: * If :attr:`is_multiline` is `True` and `name` is not included within the arguments, an assertion error will be thrown. * If :attr:`is_multiline` is `False`, the raw string within the wrap will be treated as the name. * The :attr:`wrap` attribute is set once parsing is completed and name has been validated. Returns (dict): Parsed wrap arguments as a dictionary. .. method:: start(self) Sets :attr:`start_time` attribute. .. method:: end(self) Updates execution time attributes. In namespace, sets: * :attr:`end_time` * :attr:`execution_time` * :attr:`execution_time_txt` .. method:: trim(self) -> str Statement as a string including only the sql and a single-line wrap name. .. note:: The wrap name used here will be the user-pr wrap from the original script or a generated :attr:`Name.nm` if a wrap was not provided for a given statement. .. method:: is_derived(self) :property: Indicates whether or not it's a generic or derived (QA) statement. .. method:: lines(self) -> List[str] :property: Returns each line within the statement as a list. .. method:: as_section(self, incl_sql_tag: Optional[bool] = None, result_wrap: Optional[str] = None) -> snowmobile.core.Section Returns current statement as a :class:`Section` object. .. method:: set_state(self, index: Optional[int] = None, ctx_id: Optional[int] = None, in_context: Optional[bool] = None, filters: dict = None) -> snowmobile.core.statement.Statement Sets current state/context on a statement object. :param ctx_id: Unix timestamp the :meth:`script.filter()` context manager was invoked. :type ctx_id: int :param filters: Kwargs passed to :meth:`script.filter()`. :type filters: dict :param index: Integer to set as the statement's index position. :type index: int .. method:: reset(self, index: bool = False, ctx_id: bool = False, in_context: bool = False, scope: bool = False) -> snowmobile.core.statement.Statement Resets attributes on the statement object to reflect as if read from source. In its current form, includes: * Resetting the statement/wrap's index to their original values. * Resetting the :attr:`is_included` attribute of the statement's :attr:`wrap` to `True`. * Populating :attr:`error_last` with errors from current context. * Caching current context's timestamp and resetting back to `None`. .. method:: process(self) Used by derived classes for post-processing the returned results. .. method:: run(self, as_df: bool = True, lower: bool = True, render: bool = False, on_error: Optional[str] = None, on_exception: Optional[str] = None, on_failure: Optional[str] = None, ctx_id: Optional[int] = None) -> snowmobile.core.statement.Statement Run method for all statement objects. :param as_df: Store results of query as :class:`pandas.DataFrame` or :class:`SnowflakeCursor`. :type as_df: bool :param lower: Lower case column names in :attr:`results` DataFrame if `as_df=True`. :type lower: bool :param render: Render the sql executed as markdown. :type render: bool :param on_error: Behavior if an execution/database error is encountered * `None`: default behavior, exception will be raised * `c`: continue with execution :type on_error: str :param on_exception: Behavior if an exception is raised in the **post-processing** of results from a derived class of :class:`Statement` ( :class:`Empty` and :class:`Diff`). * `None`: default behavior, exception will be raised * `c`: continue with execution :type on_exception: str :param on_failure: Behavior if no error is encountered in execution or post-processing but the result of the post-processing has turned the statement's :attr:`outcome` attribute to False, indicating the results returned by the statement have failed validation. * `None`: default behavior, exception will be raised * `c`: continue with execution :type on_failure: str Returns (Statement): Statement object post-executing query. .. method:: outcome_txt(self, _id: Optional[int] = None) -> str Outcome as a string. .. method:: outcome_html(self) -> str :property: Outcome as an html admonition banner.