`snowmobile.core.script`¶

snowmobile.Script is instantiated from a local sql file or a readable text file containing valid sql code.

Module Contents¶

Classes¶

Script

Parser and operator of local sql files.

class snowmobile.core.script.Script(sn: Optional[Snowmobile] = None, path: Optional[Path, str] = None, sql: Optional[str] = None, as_generic: bool = False, delay: bool = True, **kwargs)¶

Bases: snowmobile.core.Generic

Parser and operator of local sql files.

Parameters

sn (snowmobile.core.connection.Snowmobile) – An instance of Snowmobile.
path (Optional[str]) – A full path to a sql file or readable text file containing valid sql code.
path – A raw string of valid sql code as opposed to reading from a path.
as_generic (bool) – 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 Statement.
delay (bool) – Delay connection of the Snowmobile; only applicable if the sn argument is omitted and Script is instantiating a Snowmobile in its absence.
**kwargs – Any keyword arguments to pass to Snowmobile; only applicable if the sn argument is omitted and Script is instantiating a Snowmobile in its absence

sn¶

An instance of Snowmobile

Type: snowmobile.core.connection.Snowmobile

patterns¶

Configured patterns from snowmobile.toml.

Type: snowmobile.core.cfg.script.Pattern

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 Statement.

Type: bool

filters¶

Dictionary of filters that have been passed to the current instance of snowmobile.core.Script.

Type: Dict[Any[str, int], Dict[str, Set]]

markers¶

Dictionary of all markers found in the script.

Type: Dict[int, cfg.Marker]

path¶

Path to sql file (e.g. full/path/to/script.sql).

Type: Path

name¶

Name of sql file (e.g. script.sql).

Type: str

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

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.

Parameters: path (pathlib.Path) – Full path to a sql object.

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.

source(self, original: bool = False) → str ¶: The script’s sql as a raw string.

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.

Parameters

s (Union[sqlparse.sql.Statement, str]) – A sqlparse.sql.Statement object or a raw string of SQL for an individual statement.
index (int) – 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.
nm (Optional[str]) – 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.

parse_stream(self, stream: str) → None ¶: Parses a stream of sql and adds onto existing Script contents.

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’ Name.

Parameters

incl_kw – Include only kw
incl_obj – Include only obj
incl_desc – Include only desc
incl_anchor – Include only anchor
incl_nm – Include only nm
excl_kw – Exclude kw
excl_obj – Exclude obj
excl_desc – Exclude desc
excl_anchor – Exclude anchor
excl_nm – Exclude nm
as_id – ID to assign the filters passed to method; used to populated the filters attribute
from_id – ID previously used on the same instance of Script from which to populate filtered arguments
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.

property depth(self) → int ¶: Count of statements in the script.

property lines(self) → int ¶: Number of lines in the script

property excluded(self)¶: All statements by index position excluded from the current context.

property executed(self) → Dict[int, Statement]¶: Executed statements by index position included in the current context.

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 filter() context manger to reverse the revised indices set by index_to() and inclusion/ exclusion scope set by Statement.Name.scope().

property duplicates(self) → Dict[str, int]¶: Dictionary of indistinct statement names/tags within script.

s(self, _id: Optional[str, int] = None) → Any[Statement, Empty, Diff]¶: Fetch a single statement by _id.

property st(self) → Dict[Union[int, str], Statement]¶: Accessor for all statements.

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.

property first_s(self)¶: First statement by index position.

property last_s(self)¶: Last statement by index position

property first(self) → Union[Statement, Empty, Diff]¶: First statement executed.

property last(self) → Union[Statement, Empty, Diff]¶: Last statement executed.

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 Markup from the script.

Parameters

nm (Optional[str]) – Alternate file name to use.
prefix (Optional[str]) – Prefix for file name.
suffix (Optional[str]) – Suffix for file name.
incl_markers (Optional[bool]) – Include markers in exported files.
incl_sql (Optional[bool]) – Include sql in exported files.
incl_exp_ctx (Optional[bool]) – Include disclaimer of programmatic save in exported sql file.

Returns

A Markup instance based on the contents included in the script’s context.

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:

tuple of integers (lower and upper bound of statement indices to run)
list of integers or strings (statement names or indices to run)
default=None; returns all statement indices within scope if so

Parameters: _id (Union[Tuple, List]) – _id field provided to script.run() if it’s neither an integer or a string.

Returns (List[int]):: A list of statement indices to run.

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 Statement (e.g., those within snowmobile.core.qa by default).

Parameters

_id (Optional[str, int, Tuple[int, int], List]) –
Identifier for statement(s) to execute, can be either:
- None (default); execute all statements
- A single statement’s 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
as_df (bool) – Store statement’s results as a DataFrame; defaults to True
on_error (Optional[str]) – Action to take on execution error; providing c will continue execution as opposed to raising exception.
on_exception (Optional[str]) – Action to take on post-processing error from a derived Statement; providing c will continue execution as opposed to raising exception.
on_failure (Optional[str]) – Action to take on failure of post-processing assertion from a derived Statement; providing c will continue execution as opposed to raising exception.
lower (bool) – Lower-case columns in results returned if as_df=True.
render (bool) – Render sql executed as markdown; only applicable in Jupyter/iPython environments.
**kwargs –

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.

keys(self, **kwargs) → KeysView[Union[int, str]]¶: Access keys of items only.

values(self, **kwargs) → ValuesView[Union[int, str]]¶: Access values of items only.

dict(self, **kwargs) → Dict¶: Unpacking items view into an actual dictionary.

snowmobile.core.script¶

Module Contents¶

Classes¶

`snowmobile.core.script`¶