:orphan: :mod:`snowmobile.core.section` ============================== .. py:module:: snowmobile.core.section .. autoapi-nested-parse:: ---- A :class:`Section` is created by a :class:`~snowmobile.core.Statement` or a :class:`~snowmobile.core.cfg.Marker` when the :meth:`~snowmobile.Script.doc()` method is called on an instance of :class:`~snowmobile.Script`. .. note:: :meth:`script.doc() ` returns a :class:`~snowmobile.core.markup.Markup` instance containing a :class:`Section` for each statement or marker *within the script's context at the time* :meth:`~snowmobile.Script.doc()` *was called*. Respecting the script's context enables calling :meth:`script.doc() ` on the instance of ``script`` returned by :meth:`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 :class:`~snowmobile.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 ~~~~~~~ .. autoapisummary:: snowmobile.core.section.Name snowmobile.core.section.Item snowmobile.core.section.Section .. data:: PRESERVE_WHITESPACE :annotation: = True .. data:: WIDE_CHARS_MODE :annotation: = False .. data:: MIN_PADDING :annotation: = 0 .. class:: Name(nm: str, cfg: snowmobile.core.Configuration, is_title: Optional[bool] = None) Bases: :class:`snowmobile.core.Generic` Handles attribute-name parsing including identification of wildcards. .. method:: check_reserved_nm(attr_name: str, searching_for: str) -> bool :staticmethod: Safely checks for key terms within attribute names. :param attr_name: Attribute name that we are checking (e.g. 'Results\*') :type attr_name: str :param searching_for: Keyword we are searching for (e.g. 'results') :type searching_for: str .. class:: 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: :class:`snowmobile.core.section.Name` Represents a piece of text/content within a header section. .. method:: is_sibling(self, other: snowmobile.core.section.Item) -> bool .. method:: update(self, items: List[Item]) .. method:: as_results(self, results: pandas.DataFrame) .. method:: md(self) :property: .. class:: 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: :class:`snowmobile.core.Generic` Represents any (1-6 level) header section within `Script Name (doc).md`. Class is created with a call to the :meth:`~snowmobile.core.statement.Statement.as_section()` method or by the :class:`snowmobile.core.markup.Markup` class in the case of a :class:`~snowmobile.core.cfg.script.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 :attr:`~snowmobile.Script.st` vs :attr:`~snowmobile.Script.executed` attributes of :class:`~snowmobile.core.Script`. :param is_marker: Information provided is associated with a marker as opposed to a statement; defaults to *False*. :type is_marker: bool :param h_contents: String representation of header contents. :type h_contents: str :param index: Statement index position or *None* if marker. :type index: int :param parsed: Parsed arguments from the statement or marker within the script. :type parsed: dict :param raw: Raw wrap as :attr:`parsed` was parsed from. :type raw: str :param sql: Statement's raw sql or *None* if marker. :type sql: str :param results: Results returned by statement's sql as a :class:`~pandas.DataFrame`; will be *None* if statement hasn't been executed or if a marker. :type results: pd.DataFrame .. attribute:: 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. .. method:: reorder_attrs(self, parsed: dict, cfg: snowmobile.core.Configuration) -> Dict Re-orders parsed attributes based on configuration. .. method:: parse_contents(self, cfg: snowmobile.core.Configuration) -> List[Item] Unpacks sorted dictionary of parsed attributes into formatted Items. .. method:: header(self) -> str :property: Constructs the header for a section. Uses specifications in `snowmobile.toml` to determine: (1) The level of the header depending on whether it's a statement section or a script section. (2) Whether or not to include the statement index as part of the header. :returns: Formatted header line as a string. .. method:: sql_md(self) -> str :property: Returns renderable sql or an empty string if script-level section. .. method:: body(self) -> str :property: All section content except for header. .. method:: md(self) -> str :property: Constructs a full section as a string from various components. :returns: Full string of valid markdown for the section.