`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¶

`Name`	Handles attribute-name parsing including identification of wildcards.
`Item`	Represents a piece of text/content within a header section.
`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.

static check_reserved_nm(attr_name: str, searching_for: str) → bool ¶

Safely checks for key terms within attribute names.

Parameters

attr_name (str) – Attribute name that we are checking (e.g. ‘Results*’)
searching_for (str) – Keyword we are searching for (e.g. ‘results’)

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 ¶

update(self, items: List[Item])¶

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 the snowmobile.core.markup.Markup class in the case of a Marker.

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 vs executed attributes of Script.

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: str

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.

property sql_md(self) → str ¶: Returns renderable sql or an empty string if script-level section.

property body(self) → str ¶: All section content except for header.

property md(self) → str ¶

Constructs a full section as a string from various components.

Returns: Full string of valid markdown for the section.

snowmobile.core.section¶

Module Contents¶

Classes¶

`snowmobile.core.section`¶