:mod:`snowmobile.core.script` ============================= .. py:module:: snowmobile.core.script .. autoapi-nested-parse:: :class:`snowmobile.Script` is instantiated from a local sql file or a readable text file containing valid sql code. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: snowmobile.core.script.Script .. class:: Script(sn: Optional[Snowmobile] = None, path: Optional[(Path, str)] = None, sql: Optional[str] = None, as_generic: bool = False, delay: bool = True, **kwargs) Bases: :class:`snowmobile.core.Generic` Parser and operator of local sql files. :param sn: An instance of :class:`~snowmobile.core.connection.Snowmobile`. :type sn: snowmobile.core.connection.Snowmobile :param path: A full path to a sql file or readable text file containing valid sql code. :type path: Optional[Path, str] :param path: A raw string of valid sql code as opposed to reading from a ``path``. :type path: Optional[str] :param as_generic: Instantiate all statements as generic st; skips all checks for a mapping of a statement anchor to a derived statement class to instantiate in the place of a generic :class:`~snowmobile.core.statement.Statement`. :type as_generic: bool :param delay: Delay connection of the :class:`Snowmobile`; only applicable if the ``sn`` argument is omitted and :class:`Script` is instantiating a :class:`Snowmobile` in its absence. :type delay: bool :param \*\*kwargs: Any keyword arguments to pass to :class:`Snowmobile`; only applicable if the ``sn`` argument is omitted and :class:`Script` is instantiating a :class:`Snowmobile` in its absence .. attribute:: sn An instance of :class:`~snowmobile.core.connection.Snowmobile` :type: snowmobile.core.connection.Snowmobile .. attribute:: patterns Configured patterns from :ref:`snowmobile.toml`. :type: snowmobile.core.cfg.script.Pattern .. attribute:: as_generic Instantiate all statements as generic st; skips all checks for a mapping of a statement anchor to a derived statement class to instantiate in the place of a generic :class:`~snowmobile.core.statement.Statement`. :type: bool .. attribute:: filters Dictionary of filters that have been passed to the current instance of :class:`snowmobile.core.Script`. :type: Dict[Any[str, int], Dict[str, Set]] .. attribute:: markers Dictionary of all markers found in the script. :type: Dict[int, cfg.Marker] .. attribute:: path Path to sql file (e.g. *full/path/to/script.sql*). :type: Path .. attribute:: name Name of sql file (e.g. *script.sql*). :type: str .. attribute:: source Raw sql text of script; will be the text contained in the raw sql file when initially read from source and reflect any modifications to the script's contents made post-instantiation. :type: str .. method:: read(self, path: pathlib.Path = None) -> snowmobile.core.script.Script Runs quick path validation and reads in a sql file as a string. A valid `path` must be provided if the `script.path` attribute hasn't been set; ``ValueErrors`` will be thrown if neither is valid. :param path: Full path to a sql object. :type path: pathlib.Path .. method:: from_str(self, sql: str, name: str, directory: pathlib.Path = Path.cwd()) -> snowmobile.core.script.Script Instantiates a raw string of sql as a script. .. method:: source(self, original: bool = False) -> str The script's sql as a raw string. .. method:: parse_one(self, s: Union[(sqlparse.sql.Statement, str)], index: Optional[int] = None, nm: Optional[str] = None) -> None Adds a statement object to the script. Default behavior will only add ``sqlparse.sql.Statement`` objects returned from ``script.source_stream``. ``clean_parse()`` utility function is utilized so that generated sql within Python can be inserted back into the script as raw strings. :param s: A sqlparse.sql.Statement object or a raw string of SQL for an individual statement. :type s: Union[sqlparse.sql.Statement, str] :param index: Index position of the statement within the script; defaults to ``n + 1`` if index is not provided where ``n`` is the number of statements within the script at the time ``parse_one()`` is called. :type index: int :param nm: Optionally provided the name of the statement being added; the script instance will treat this value as if it were provided within an in-script wrap. :type nm: Optional[str] .. method:: parse_stream(self, stream: str) -> None Parses a stream of sql and adds onto existing Script contents. .. method:: filter(self, incl_kw: Optional[(List[str], str)] = None, incl_obj: Optional[(List[str], str)] = None, incl_desc: Optional[(List[str], str)] = None, incl_anchor: Optional[(List[str], str)] = None, incl_nm: Optional[(List[str], str)] = None, excl_kw: Optional[(List[str], str)] = None, excl_obj: Optional[(List[str], str)] = None, excl_desc: Optional[(List[str], str)] = None, excl_anchor: Optional[(List[str], str)] = None, excl_nm: Optional[(List[str], str)] = None, as_id: Optional[Union[str, int]] = None, from_id: Optional[Union[str, int]] = None, last: bool = False) -> ContextManager[Script] Subset the script based on attributes of its st. ``script.filter()`` returns a modified instance of script that can be operated on within the context defined. .. note:: Keyword arguments beginning with ``incl`` or ``excl`` expect a string or a list of strings containing regex patterns with which to check for a match against the associated attribute of its st' :class:`~snowmobile.core.name.Name`. :param incl_kw: Include only :attr:`~snowmobile.core.name.Name.kw` :param incl_obj: Include only :attr:`~snowmobile.core.name.Name.obj` :param incl_desc: Include only :attr:`~snowmobile.core.name.Name.desc` :param incl_anchor: Include only :attr:`~snowmobile.core.name.Name.anchor` :param incl_nm: Include only :attr:`~snowmobile.core.name.Name.nm` :param excl_kw: Exclude :attr:`~snowmobile.core.name.Name.kw` :param excl_obj: Exclude :attr:`~snowmobile.core.name.Name.obj` :param excl_desc: Exclude :attr:`~snowmobile.core.name.Name.desc` :param excl_anchor: Exclude :attr:`~snowmobile.core.name.Name.anchor` :param excl_nm: Exclude :attr:`~snowmobile.core.name.Name.nm` :param as_id: ID to assign the filters passed to method; used to populated the :attr:`filters` attribute :param from_id: ID previously used on the same instance of :class:`Script` from which to populate filtered arguments :param last: Re-use the last set of filters passed to context manager. Returns (Script): The instance of script based on the context imposed by arguments pr. .. method:: depth(self) -> int :property: Count of statements in the script. .. method:: lines(self) -> int :property: Number of lines in the script .. method:: excluded(self) :property: All statements by index position excluded from the current context. .. method:: executed(self) -> Dict[(int, Statement)] :property: Executed statements by index position included in the current context. .. method:: reset(self, index: bool = False, ctx_id: bool = False, in_context: bool = False, scope: bool = False, _filter: bool = False) -> snowmobile.core.script.Script Resets indices and scope on all statements to their state as read from source. Invoked before exiting :meth:`filter()` context manger to reverse the revised indices set by :meth:`index_to()` and inclusion/ exclusion scope set by :meth:`Statement.Name.scope()`. .. method:: duplicates(self) -> Dict[(str, int)] :property: Dictionary of indistinct statement names/tags within script. .. method:: s(self, _id: Optional[(str, int)] = None) -> Any[(Statement, Empty, Diff)] Fetch a single statement by _id. .. method:: st(self) -> Dict[(Union[int, str], Statement)] :property: Accessor for all statements. .. method:: dtl(self, full: bool = False, excluded: bool = False, title: bool = True, r: bool = False) -> Union[(str, None)] Prints summary of statements within the current scope to console. .. method:: first_s(self) :property: First statement by index position. .. method:: last_s(self) :property: Last statement by index position .. method:: first(self) -> Union[(Statement, Empty, Diff)] :property: First statement executed. .. method:: last(self) -> Union[(Statement, Empty, Diff)] :property: Last statement executed. .. method:: doc(self, nm: Optional[str] = None, prefix: Optional[str] = None, suffix: Optional[str] = None, incl_markers: Optional[bool] = True, incl_sql: Optional[bool] = True, incl_exp_ctx: Optional[bool] = True, result_wrap: Optional[str] = None) -> snowmobile.core.Markup Returns a :class:`~snowmobile.core.markup.Markup` from the script. :param nm: Alternate file name to use. :type nm: Optional[str] :param prefix: Prefix for file name. :type prefix: Optional[str] :param suffix: Suffix for file name. :type suffix: Optional[str] :param incl_markers: Include markers in exported files. :type incl_markers: Optional[bool] :param incl_sql: Include sql in exported files. :type incl_sql: Optional[bool] :param incl_exp_ctx: Include disclaimer of programmatic save in exported sql file. :type incl_exp_ctx: Optional[bool] :returns: A :class:`~snowmobile.core.markup.Markup` instance based on the contents included in the script's context. .. method:: ids(self, _id: Optional[Union[Tuple, List]] = None) -> List[int] Utility function to get a list of statement IDs given an `_id`. Invoked within script.run() if the `_id` parameter is either a: (1) tuple of integers (lower and upper bound of statement indices to run) (2) list of integers or strings (statement names or indices to run) (3) default=None; returns all statement indices within scope if so :param _id: _id field provided to script.run() if it's neither an integer or a string. :type _id: Union[Tuple, List] Returns (List[int]): A list of statement indices to run. .. method:: run(self, _id: Optional[(str, int, Tuple[int, int], List)] = None, as_df: bool = True, on_error: Optional[str] = None, on_exception: Optional[str] = None, on_failure: Optional[str] = None, lower: bool = True, render: bool = False, **kwargs) -> None Performs statement-by-statement execution of the script's contents. Executes script's contents that are included within its current context and any (optional) value passed to the ``_id`` argument. .. note:: Keyword arguments ``on_exception`` and ``on_failure`` are only applicable to derived classes of :class:`~snowmobile.core.statement.Statement` (e.g., those within :mod:`snowmobile.core.qa` by default). :param _id: Identifier for statement(s) to execute, can be either: - *None* (default); execute all statements - A single statement's :attr:`~snowmobile.core.Name.nm` - A single statement's index position - A tuple of lower/upper index bounds of statements to execute - A list of statement names or index positions to execute :type _id: Optional[str, int, Tuple[int, int], List] :param as_df: Store statement's results as a :class:`~pandas.DataFrame`; defaults to *True* :type as_df: bool :param on_error: Action to take on **execution** error; providing `c` will continue execution as opposed to raising exception. :type on_error: Optional[str] :param on_exception: Action to take on **post-processing** error from a derived :class:`~snowmobile.core.statement.Statement`; providing `c` will continue execution as opposed to raising exception. :type on_exception: Optional[str] :param on_failure: Action to take on **failure** of post-processing assertion from a derived :class:`~snowmobile.core.statement.Statement`; providing `c` will continue execution as opposed to raising exception. :type on_failure: Optional[str] :param lower: Lower-case columns in results returned if ``as_df=True``. :type lower: bool :param render: Render sql executed as markdown; only applicable in Jupyter/iPython environments. :type render: bool :param \*\*kwargs: .. method:: items(self, by_index: bool = True, ignore_scope: bool = False, statements: bool = True, markers: bool = False, validate: bool = True) -> ItemsView[(Union[int, str], Union[Statement, Marker])] Dunder items. .. method:: keys(self, **kwargs) -> KeysView[Union[int, str]] Access keys of items only. .. method:: values(self, **kwargs) -> ValuesView[Union[int, str]] Access values of items only. .. method:: dict(self, **kwargs) -> Dict Unpacking items view into an actual dictionary.