snowmobile.core.section
¶
A Section
is created by a Statement
or a Marker
when the doc()
method is called on an instance of Script
.
Note
script.doc()
returns a Markup
instance containing a Section
for each statement or marker within the script’s context at the time doc()
was called.
Respecting the script’s context enables calling script.doc()
on the instance of script
returned by script.filter()
and exporting an annotated markdown file and/or a tidied sql file that include only the contents within that context.
By default this results in two files being exported into a .snowmobile folder in the same directory as the .sql file with which the instance of Script
was instantiated.
Header-levels and formatting of tagged information is configured in the snowmobile.toml file, with defaults resulting in the following structure:
```md
# Script Name.sql *[script name gets an 'h1' header]
----
- **Tag1**: Value1 [tags are bolded, associated values are not]
- **Tag2**: Value2 [same for all tags/attributes found]
- ...
**Description** *[except for the 'Description' section]
*[this is just a blank canvas of markdown..]
*[..but this is configurable]
## (1) create-table~dummy_name *[st get 'h2' level headers]
----
- **Tag1**: Value1 *[tags can also be validations arguments..
- **Arg1**: Val2 [that snowmobile will run on the sql results]
**Description** *[st get one of these too]
**SQL** *[their rendered sql does as well]
...sql
...
...
...
## (2) update-table~dummy_name2
----
[structure repeats for all statements in the script]
```
Module Contents¶
Classes¶
Handles attribute-name parsing including identification of wildcards. | |
Represents a piece of text/content within a header section. | |
Represents any (1-6 level) header section within Script Name (doc).md. |
-
snowmobile.core.section.
PRESERVE_WHITESPACE
= True¶
-
snowmobile.core.section.
WIDE_CHARS_MODE
= False¶
-
snowmobile.core.section.
MIN_PADDING
= 0¶
- class
snowmobile.core.section.
Name
(nm: str, cfg: snowmobile.core.Configuration, is_title: Optional[bool] = None)¶ Bases:
snowmobile.core.Generic
Handles attribute-name parsing including identification of wildcards.
- class
snowmobile.core.section.
Item
(index: int, flattened_attrs: Tuple, cfg: snowmobile.core.Configuration, results: Optional[pd.DataFrame] = None, sql_md: Optional[str] = None, result_wrap: Optional[str] = None)¶ Bases:
snowmobile.core.section.Name
Represents a piece of text/content within a header section.
-
is_sibling
(self, other: snowmobile.core.section.Item) → bool¶
-
as_results
(self, results: pandas.DataFrame)¶
- property
md
(self)¶
-
- class
snowmobile.core.section.
Section
(cfg: snowmobile.core.Configuration, is_marker: bool = None, h_contents: Optional[str] = None, index: Optional[int] = None, parsed: Optional[Dict] = None, raw: Optional[str] = None, sql: Optional[str] = None, results: Optional[pd.DataFrame] = None, incl_sql_tag: bool = False, is_multiline: bool = False, result_wrap: Optional[str] = None)¶ Bases:
snowmobile.core.Generic
Represents any (1-6 level) header section within Script Name (doc).md.
Class is created with a call to the
as_section()
method or by thesnowmobile.core.markup.Markup
class in the case of aMarker
.In order to include execution metadata if available without sacrificing base-case parsing, the below implementation heavily relies properties over attributes to reconcile what’s populated in the
st
vsexecuted
attributes ofScript
.- Parameters
is_marker (bool) – Information provided is associated with a marker as opposed to a statement; defaults to False.
h_contents (str) – String representation of header contents.
index (int) – Statement index position or None if marker.
parsed (dict) – Parsed arguments from the statement or marker within the script.
raw (str) – Raw wrap as
parsed
was parsed from.sql (str) – Statement’s raw sql or None if marker.
results (pd.DataFrame) – Results returned by statement’s sql as a
DataFrame
; will be None if statement hasn’t been executed or if a marker.
-
hx
¶ String representation of header level (e.g. ‘#’ for h1), based on the script/statement header-level specifications in snowmobile.toml.
- Type
Instantiation of a
script.Section
object.-
reorder_attrs
(self, parsed: dict, cfg: snowmobile.core.Configuration) → Dict¶ Re-orders parsed attributes based on configuration.
-
parse_contents
(self, cfg: snowmobile.core.Configuration) → List[Item]¶ Unpacks sorted dictionary of parsed attributes into formatted Items.
- property
header
(self) → str¶ Constructs the header for a section.
- Uses specifications in snowmobile.toml to determine:
The level of the header depending on whether it’s a statement section or a script section.
Whether or not to include the statement index as part of the header.
- Returns
Formatted header line as a string.