Skip to content

trestle.core.jinja.tags

trestle.core.jinja.tags ¤

Trestle utilities to customize jinja tags.

Attributes¤

logger = logging.getLogger(__name__) module-attribute ¤

Classes¤

MDCleanInclude ¤

Bases: TrestleJinjaExtension


              flowchart TD
              trestle.core.jinja.tags.MDCleanInclude[MDCleanInclude]
              trestle.core.jinja.base.TrestleJinjaExtension[TrestleJinjaExtension]

                              trestle.core.jinja.base.TrestleJinjaExtension --> trestle.core.jinja.tags.MDCleanInclude
                


              click trestle.core.jinja.tags.MDCleanInclude href "" "trestle.core.jinja.tags.MDCleanInclude"
              click trestle.core.jinja.base.TrestleJinjaExtension href "" "trestle.core.jinja.base.TrestleJinjaExtension"
            

Inject the parameter of the tag as the resulting content.

Source code in trestle/core/jinja/tags.py
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
class MDCleanInclude(TrestleJinjaExtension):
    """Inject the parameter of the tag as the resulting content."""

    tags = {'md_clean_include'}

    def __init__(self, environment: Environment) -> None:
        """Ensure enviroment is set and carried into class vars."""
        super().__init__(environment)

    def parse(self, parser):
        """Execute parsing of md token and return nodes."""
        kwargs = None
        expected_heading_level = None
        count = 0
        while parser.stream.current.type != lexer.TOKEN_BLOCK_END:
            count = count + 1
            if count > self.max_tag_parse:
                raise err.TrestleError('Unexpected Jinja tag structure provided, please review docs.')
            token = parser.stream.current
            if token.test('name:md_clean_include'):
                parser.stream.expect(lexer.TOKEN_NAME)
                markdown_source = parser.stream.expect(lexer.TOKEN_STRING)
            elif kwargs is not None:
                arg = token.value
                next(parser.stream)
                parser.stream.expect(lexer.TOKEN_ASSIGN)
                token = parser.stream.current
                exp = self.parse_expression(parser)
                kwargs[arg] = exp.value
            else:
                if parser.stream.look().type == lexer.TOKEN_ASSIGN:
                    kwargs = {}
                continue
        md_content, _, _ = self.environment.loader.get_source(self.environment, markdown_source.value)
        fm = frontmatter.loads(md_content)
        content = fm.content
        content += '\n\n'
        if kwargs is not None:
            expected_heading_level = kwargs.get('heading_level')
        if expected_heading_level is not None:
            content = adjust_heading_level(content, expected_heading_level)

        local_parser = Parser(self.environment, content)
        top_level_output = local_parser.parse()

        return top_level_output.body
Attributes¤
tags = {'md_clean_include'} class-attribute instance-attribute ¤
Functions¤
__init__(environment) ¤

Ensure enviroment is set and carried into class vars.

Source code in trestle/core/jinja/tags.py
111
112
113
def __init__(self, environment: Environment) -> None:
    """Ensure enviroment is set and carried into class vars."""
    super().__init__(environment)
parse(parser) ¤

Execute parsing of md token and return nodes.

Source code in trestle/core/jinja/tags.py
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def parse(self, parser):
    """Execute parsing of md token and return nodes."""
    kwargs = None
    expected_heading_level = None
    count = 0
    while parser.stream.current.type != lexer.TOKEN_BLOCK_END:
        count = count + 1
        if count > self.max_tag_parse:
            raise err.TrestleError('Unexpected Jinja tag structure provided, please review docs.')
        token = parser.stream.current
        if token.test('name:md_clean_include'):
            parser.stream.expect(lexer.TOKEN_NAME)
            markdown_source = parser.stream.expect(lexer.TOKEN_STRING)
        elif kwargs is not None:
            arg = token.value
            next(parser.stream)
            parser.stream.expect(lexer.TOKEN_ASSIGN)
            token = parser.stream.current
            exp = self.parse_expression(parser)
            kwargs[arg] = exp.value
        else:
            if parser.stream.look().type == lexer.TOKEN_ASSIGN:
                kwargs = {}
            continue
    md_content, _, _ = self.environment.loader.get_source(self.environment, markdown_source.value)
    fm = frontmatter.loads(md_content)
    content = fm.content
    content += '\n\n'
    if kwargs is not None:
        expected_heading_level = kwargs.get('heading_level')
    if expected_heading_level is not None:
        content = adjust_heading_level(content, expected_heading_level)

    local_parser = Parser(self.environment, content)
    top_level_output = local_parser.parse()

    return top_level_output.body

MDDatestamp ¤

Bases: TrestleJinjaExtension


              flowchart TD
              trestle.core.jinja.tags.MDDatestamp[MDDatestamp]
              trestle.core.jinja.base.TrestleJinjaExtension[TrestleJinjaExtension]

                              trestle.core.jinja.base.TrestleJinjaExtension --> trestle.core.jinja.tags.MDDatestamp
                


              click trestle.core.jinja.tags.MDDatestamp href "" "trestle.core.jinja.tags.MDDatestamp"
              click trestle.core.jinja.base.TrestleJinjaExtension href "" "trestle.core.jinja.base.TrestleJinjaExtension"
            

Inject the parameter of the tag as the resulting content.

Source code in trestle/core/jinja/tags.py
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
class MDDatestamp(TrestleJinjaExtension):
    """Inject the parameter of the tag as the resulting content."""

    tags = {'md_datestamp'}

    def __init__(self, environment: Environment) -> None:
        """Ensure enviroment is set and carried into class vars."""
        super().__init__(environment)

    def parse(self, parser):
        """Execute parsing of md token and return nodes."""
        kwargs = None
        count = 0
        while parser.stream.current.type != lexer.TOKEN_BLOCK_END:
            count = count + 1
            token = parser.stream.current
            if count > self.max_tag_parse:
                raise err.TrestleError(f'Unexpected Jinja tag structure provided at token {token.value}')
            if token.test('name:md_datestamp'):
                parser.stream.expect(lexer.TOKEN_NAME)
            elif kwargs is not None:
                arg = token.value
                next(parser.stream)
                parser.stream.expect(lexer.TOKEN_ASSIGN)
                token = parser.stream.current
                exp = self.parse_expression(parser)
                kwargs[arg] = exp.value
            else:
                if parser.stream.look().type == lexer.TOKEN_ASSIGN or parser.stream.look().type == lexer.TOKEN_STRING:
                    kwargs = {}
                continue

        if kwargs is not None:
            if 'format' in kwargs and type(kwargs['format'] is str):
                date_string = date.today().strftime(kwargs['format'])
            else:
                date_string = date.today().strftime(markdown_const.JINJA_DATESTAMP_FORMAT)
            if 'newline' in kwargs and kwargs['newline'] is False:
                pass
            else:
                date_string += '\n\n'
        else:
            date_string = date.today().strftime(markdown_const.JINJA_DATESTAMP_FORMAT) + '\n\n'

        local_parser = Parser(self.environment, date_string)
        datestamp_output = local_parser.parse()

        return datestamp_output.body
Attributes¤
tags = {'md_datestamp'} class-attribute instance-attribute ¤
Functions¤
__init__(environment) ¤

Ensure enviroment is set and carried into class vars.

Source code in trestle/core/jinja/tags.py
159
160
161
def __init__(self, environment: Environment) -> None:
    """Ensure enviroment is set and carried into class vars."""
    super().__init__(environment)
parse(parser) ¤

Execute parsing of md token and return nodes.

Source code in trestle/core/jinja/tags.py
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
def parse(self, parser):
    """Execute parsing of md token and return nodes."""
    kwargs = None
    count = 0
    while parser.stream.current.type != lexer.TOKEN_BLOCK_END:
        count = count + 1
        token = parser.stream.current
        if count > self.max_tag_parse:
            raise err.TrestleError(f'Unexpected Jinja tag structure provided at token {token.value}')
        if token.test('name:md_datestamp'):
            parser.stream.expect(lexer.TOKEN_NAME)
        elif kwargs is not None:
            arg = token.value
            next(parser.stream)
            parser.stream.expect(lexer.TOKEN_ASSIGN)
            token = parser.stream.current
            exp = self.parse_expression(parser)
            kwargs[arg] = exp.value
        else:
            if parser.stream.look().type == lexer.TOKEN_ASSIGN or parser.stream.look().type == lexer.TOKEN_STRING:
                kwargs = {}
            continue

    if kwargs is not None:
        if 'format' in kwargs and type(kwargs['format'] is str):
            date_string = date.today().strftime(kwargs['format'])
        else:
            date_string = date.today().strftime(markdown_const.JINJA_DATESTAMP_FORMAT)
        if 'newline' in kwargs and kwargs['newline'] is False:
            pass
        else:
            date_string += '\n\n'
    else:
        date_string = date.today().strftime(markdown_const.JINJA_DATESTAMP_FORMAT) + '\n\n'

    local_parser = Parser(self.environment, date_string)
    datestamp_output = local_parser.parse()

    return datestamp_output.body

MDSectionInclude ¤

Bases: TrestleJinjaExtension


              flowchart TD
              trestle.core.jinja.tags.MDSectionInclude[MDSectionInclude]
              trestle.core.jinja.base.TrestleJinjaExtension[TrestleJinjaExtension]

                              trestle.core.jinja.base.TrestleJinjaExtension --> trestle.core.jinja.tags.MDSectionInclude
                


              click trestle.core.jinja.tags.MDSectionInclude href "" "trestle.core.jinja.tags.MDSectionInclude"
              click trestle.core.jinja.base.TrestleJinjaExtension href "" "trestle.core.jinja.base.TrestleJinjaExtension"
            

Inject the parameter of the tag as the resulting content.

Source code in trestle/core/jinja/tags.py
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class MDSectionInclude(TrestleJinjaExtension):
    """Inject the parameter of the tag as the resulting content."""

    tags = {'mdsection_include'}

    def __init__(self, environment: Environment) -> None:
        """Ensure enviroment is set and carried into class vars."""
        super().__init__(environment)

    def parse(self, parser):
        """Execute parsing of md token and return nodes."""
        kwargs = None
        expected_heading_level = None
        count = 0
        while parser.stream.current.type != lexer.TOKEN_BLOCK_END:
            count = count + 1
            if count > self.max_tag_parse:
                raise err.TrestleError('Unexpected Jinja tag structure provided, please review docs.')
            token = parser.stream.current
            if token.test('name:mdsection_include'):
                parser.stream.expect(lexer.TOKEN_NAME)
                markdown_source = parser.stream.expect(lexer.TOKEN_STRING)
                section_title = parser.stream.expect(lexer.TOKEN_STRING)
            elif kwargs is not None:
                arg = token.value
                next(parser.stream)
                parser.stream.expect(lexer.TOKEN_ASSIGN)
                token = parser.stream.current
                exp = self.parse_expression(parser)
                kwargs[arg] = exp.value
            else:
                if parser.stream.look().type == lexer.TOKEN_ASSIGN:
                    kwargs = {}
                continue
        # Use the established environment to source the file
        md_content, _, _ = self.environment.loader.get_source(self.environment, markdown_source.value)
        fm = frontmatter.loads(md_content)
        if not fm.metadata == {}:
            logger.warning('Non zero metadata on MD section include - ignoring')
        full_md = docs_markdown_node.DocsMarkdownNode.build_tree_from_markdown(fm.content.split('\n'))
        md_section = full_md.get_node_for_key(section_title.value, strict_matching=True)
        # adjust
        if kwargs is not None:
            expected_heading_level = kwargs.get('heading_level')
        if expected_heading_level is not None:
            level = md_section.get_node_header_lvl()
            delta = int(expected_heading_level) - level
            if not delta == 0:
                md_section.change_header_level_by(delta)
        if not md_section:
            raise err.TrestleError(
                f'Unable to retrieve section "{section_title.value}"" from {markdown_source.value} jinja template.'
            )
        local_parser = Parser(self.environment, md_section.content.raw_text)
        top_level_output = local_parser.parse()

        return top_level_output.body
Attributes¤
tags = {'mdsection_include'} class-attribute instance-attribute ¤
Functions¤
__init__(environment) ¤

Ensure enviroment is set and carried into class vars.

Source code in trestle/core/jinja/tags.py
52
53
54
def __init__(self, environment: Environment) -> None:
    """Ensure enviroment is set and carried into class vars."""
    super().__init__(environment)
parse(parser) ¤

Execute parsing of md token and return nodes.

Source code in trestle/core/jinja/tags.py
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def parse(self, parser):
    """Execute parsing of md token and return nodes."""
    kwargs = None
    expected_heading_level = None
    count = 0
    while parser.stream.current.type != lexer.TOKEN_BLOCK_END:
        count = count + 1
        if count > self.max_tag_parse:
            raise err.TrestleError('Unexpected Jinja tag structure provided, please review docs.')
        token = parser.stream.current
        if token.test('name:mdsection_include'):
            parser.stream.expect(lexer.TOKEN_NAME)
            markdown_source = parser.stream.expect(lexer.TOKEN_STRING)
            section_title = parser.stream.expect(lexer.TOKEN_STRING)
        elif kwargs is not None:
            arg = token.value
            next(parser.stream)
            parser.stream.expect(lexer.TOKEN_ASSIGN)
            token = parser.stream.current
            exp = self.parse_expression(parser)
            kwargs[arg] = exp.value
        else:
            if parser.stream.look().type == lexer.TOKEN_ASSIGN:
                kwargs = {}
            continue
    # Use the established environment to source the file
    md_content, _, _ = self.environment.loader.get_source(self.environment, markdown_source.value)
    fm = frontmatter.loads(md_content)
    if not fm.metadata == {}:
        logger.warning('Non zero metadata on MD section include - ignoring')
    full_md = docs_markdown_node.DocsMarkdownNode.build_tree_from_markdown(fm.content.split('\n'))
    md_section = full_md.get_node_for_key(section_title.value, strict_matching=True)
    # adjust
    if kwargs is not None:
        expected_heading_level = kwargs.get('heading_level')
    if expected_heading_level is not None:
        level = md_section.get_node_header_lvl()
        delta = int(expected_heading_level) - level
        if not delta == 0:
            md_section.change_header_level_by(delta)
    if not md_section:
        raise err.TrestleError(
            f'Unable to retrieve section "{section_title.value}"" from {markdown_source.value} jinja template.'
        )
    local_parser = Parser(self.environment, md_section.content.raw_text)
    top_level_output = local_parser.parse()

    return top_level_output.body

Functions¤

adjust_heading_level(input_md, expected) ¤

Adjust the header level of a markdown string such that the most significant header matches the expected #'s.

Source code in trestle/core/jinja/tags.py
34
35
36
37
38
39
40
41
42
43
44
def adjust_heading_level(input_md: str, expected: int) -> str:
    """Adjust the header level of a markdown string such that the most significant header matches the expected #'s."""
    output_md = input_md
    mdn = docs_markdown_node.DocsMarkdownNode.build_tree_from_markdown(input_md.split('\n'))
    if mdn.subnodes:
        mdn_top_heading = mdn.subnodes[0].get_node_header_lvl()
        delta = int(expected) - mdn_top_heading
        if not delta == 0:
            mdn.change_header_level_by(delta)
            output_md = mdn.content.raw_text
    return output_md

handler: python