Skip to content

admonition

Admonition extension for Python-Markdown.

Adds rST-style admonitions. Inspired by rST feature with the same name.

See https://pythonhosted.org/Markdown/extensions/admonition.html for documentation.

Original code Copyright Tiago Serafim.

All changes Copyright The Python Markdown Project

License: BSD

Classes

AdmonitionExtension(*args, **kwargs)

Bases: Extension

Admonition extension for Python-Markdown.

Initiate Extension and set up configs.

Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/__init__.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def __init__(self, *args, **kwargs):
    """Initiate Extension and set up configs."""
    # check for configs arg for backward compat.
    # (there only ever used to be one so we use arg[0])
    if len(args):
        if args[0] is not None:
            self.setConfigs(args[0])
        warnings.warn('Extension classes accepting positional args is '
                      'pending Deprecation. Each setting should be '
                      'passed into the Class as a keyword. Positional '
                      'args are deprecated and will raise '
                      'an error in version 2.7. See the Release Notes for '
                      'Python-Markdown version 2.6 for more info.',
                      DeprecationWarning)
    # check for configs kwarg for backward compat.
    if 'configs' in kwargs.keys():
        if kwargs['configs'] is not None:
            self.setConfigs(kwargs.pop('configs', {}))
        warnings.warn('Extension classes accepting a dict on the single '
                      'keyword "config" is pending Deprecation. Each '
                      'setting should be passed into the Class as a '
                      'keyword directly. The "config" keyword is '
                      'deprecated and raise an error in '
                      'version 2.7. See the Release Notes for '
                      'Python-Markdown version 2.6 for more info.',
                      DeprecationWarning)
    # finally, use kwargs
    self.setConfigs(kwargs)

Attributes

config = {} class-attribute instance-attribute

Functions

extendMarkdown(md, md_globals)

Add Admonition to Markdown instance.

Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/admonition.py 
28
29
30
31
32
33
34
def extendMarkdown(self, md, md_globals):
    """Add Admonition to Markdown instance."""
    md.registerExtension(self)

    md.parser.blockprocessors.add('admonition',
                                  AdmonitionProcessor(md.parser),
                                  '_begin')
getConfig(key, default='')

Return a setting for the given key or an empty string.

Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/__init__.py 
49
50
51
52
53
54
def getConfig(self, key, default=''):
    """Return a setting for the given key or an empty string."""
    if key in self.config:
        return self.config[key][0]
    else:
        return default
getConfigs()

Return all configs settings as a dict.

Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/__init__.py 
56
57
58
def getConfigs(self):
    """Return all configs settings as a dict."""
    return dict([(key, self.getConfig(key)) for key in self.config.keys()])
getConfigInfo()

Return all config descriptions as a list of tuples.

Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/__init__.py 
60
61
62
def getConfigInfo(self):
    """Return all config descriptions as a list of tuples."""
    return [(key, self.config[key][1]) for key in self.config.keys()]
setConfig(key, value)

Set a config setting for key with the given value.

Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/__init__.py 
64
65
66
67
68
69
70
def setConfig(self, key, value):
    """Set a config setting for `key` with the given `value`."""
    if isinstance(self.config[key][0], bool):
        value = parseBoolValue(value)
    if self.config[key][0] is None:
        value = parseBoolValue(value, preserve_none=True)
    self.config[key][0] = value
setConfigs(items)

Set multiple config settings given a dict or list of tuples.

Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/__init__.py 
72
73
74
75
76
77
78
def setConfigs(self, items):
    """Set multiple config settings given a dict or list of tuples."""
    if hasattr(items, 'items'):
        # it's a dict
        items = items.items()
    for key, value in items:
        self.setConfig(key, value)

AdmonitionProcessor(parser)

Bases: BlockProcessor

Admonition processor.

Source code in pyrevitlib/pyrevit/coreutils/markdown/blockprocessors.py 
54
55
56
def __init__(self, parser):
    self.parser = parser
    self.tab_length = parser.markdown.tab_length

Attributes

CLASSNAME = 'admonition' class-attribute instance-attribute
CLASSNAME_TITLE = 'admonition-title' class-attribute instance-attribute
RE = re.compile('(?:^|\\n)!!!\\ ?([\\w\\-]+)(?:\\ "(.*?)")?') class-attribute instance-attribute
parser = parser instance-attribute
tab_length = parser.markdown.tab_length instance-attribute

Functions

test(parent, block)
Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/admonition.py 
44
45
46
47
48
def test(self, parent, block):
    sibling = self.lastChild(parent)
    return self.RE.search(block) or \
        (block.startswith(' ' * self.tab_length) and sibling is not None and
         sibling.get('class', '').find(self.CLASSNAME) != -1)
run(parent, blocks)
Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/admonition.py 
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
def run(self, parent, blocks):
    sibling = self.lastChild(parent)
    block = blocks.pop(0)
    m = self.RE.search(block)

    if m:
        block = block[m.end() + 1:]  # removes the first line

    block, theRest = self.detab(block)

    if m:
        klass, title = self.get_class_and_title(m)
        div = etree.SubElement(parent, 'div')
        div.set('class', '%s %s' % (self.CLASSNAME, klass))
        if title:
            p = etree.SubElement(div, 'p')
            p.text = title
            p.set('class', self.CLASSNAME_TITLE)
    else:
        div = sibling

    self.parser.parseChunk(div, block)

    if theRest:
        # This block contained unindented line(s) after the first indented
        # line. Insert these lines as the first block of the master blocks
        # list for future processing.
        blocks.insert(0, theRest)
get_class_and_title(match)
Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/admonition.py 
79
80
81
82
83
84
85
86
87
88
89
90
def get_class_and_title(self, match):
    klass, title = match.group(1).lower(), match.group(2)
    if title is None:
        # no title was provided, use the capitalized classname as title
        # e.g.: `!!! note` will render
        # `<p class="admonition-title">Note</p>`
        title = klass.capitalize()
    elif title == '':
        # an explicit blank title should not be rendered
        # e.g.: `!!! warning ""` will *not* render `p` with a title
        title = None
    return klass, title
lastChild(parent)

Return the last child of an etree element.

Source code in pyrevitlib/pyrevit/coreutils/markdown/blockprocessors.py 
58
59
60
61
62
63
def lastChild(self, parent):
    """Return the last child of an etree element."""
    if len(parent):
        return parent[-1]
    else:
        return None
detab(text)

Remove a tab from the front of each line of the given text.

Source code in pyrevitlib/pyrevit/coreutils/markdown/blockprocessors.py 
65
66
67
68
69
70
71
72
73
74
75
76
def detab(self, text):
    """Remove a tab from the front of each line of the given text."""
    newtext = []
    lines = text.split('\n')
    for line in lines:
        if line.startswith(' '*self.tab_length):
            newtext.append(line[self.tab_length:])
        elif not line.strip():
            newtext.append('')
        else:
            break
    return '\n'.join(newtext), '\n'.join(lines[len(newtext):])
looseDetab(text, level=1)

Remove a tab from front of lines but allowing dedented lines.

Source code in pyrevitlib/pyrevit/coreutils/markdown/blockprocessors.py 
78
79
80
81
82
83
84
def looseDetab(self, text, level=1):
    """Remove a tab from front of lines but allowing dedented lines."""
    lines = text.split('\n')
    for i in range(len(lines)):
        if lines[i].startswith(' '*self.tab_length*level):
            lines[i] = lines[i][self.tab_length*level:]
    return '\n'.join(lines)

Functions

makeExtension(*args, **kwargs)

Source code in pyrevitlib/pyrevit/coreutils/markdown/extensions/admonition.py 
93
94
def makeExtension(*args, **kwargs):
    return AdmonitionExtension(*args, **kwargs)