snowmobile.core.script
¶
snowmobile.Script
is instantiated from a local sql file or a readable text file containing valid sql code.
Module Contents¶
Classes¶
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 thesn
argument is omitted andScript
is instantiating aSnowmobile
in its absence.**kwargs – Any keyword arguments to pass to
Snowmobile
; only applicable if thesn
argument is omitted andScript
is instantiating aSnowmobile
in its absence
-
sn
¶ An instance of
Snowmobile
-
patterns
¶ Configured patterns from snowmobile.toml.
-
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
-
filters
¶ Dictionary of filters that have been passed to the current instance of
snowmobile.core.Script
.
-
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
-
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
-
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.
-
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 fromscript.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 wheren
is the number of statements within the script at the timeparse_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
orexcl
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
attributefrom_id – ID previously used on the same instance of
Script
from which to populate filtered argumentslast – 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
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 byindex_to()
and inclusion/ exclusion scope set byStatement.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.
-
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
andon_failure
are only applicable to derived classes ofStatement
(e.g., those withinsnowmobile.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 Trueon_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.
-
dict
(self, **kwargs) → Dict¶ Unpacking items view into an actual dictionary.