Skip to content

Commit 2341405

Browse files
committed
Add configurable reset function for custom fences
1 parent 0e0060d commit 2341405

5 files changed

Lines changed: 94 additions & 8 deletions

File tree

‎docs/src/markdown/about/changelog.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@ icon: lucide/scroll-text
33
---
44
# Changelog
55

6+
## 13.0
7+
8+
- **NEW**: SuperFences: Add optional `reset` function that can be specified for custom fences.
9+
610
## 12.0.1
711

812
- **FIX**: BetterEm: fix a case with new logic.

‎docs/src/markdown/extensions/superfences.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -732,6 +732,7 @@ Keys | Description
732732
`class` | The class name assigned to the HTML element when converting from Markdown to HTML.
733733
`format` | A function that formats the HTML output. The function should return a string as HTML.
734734
`validator` | An optional parameter that is used to provide a function to validate custom fence parameters.
735+
`reset` | An optional parameter that is used to provide a function that is called when the `Markdown` object has reset called on it.
735736

736737
/// warning | Logging
737738
When a custom fence fails, the error will be swallowed up and the error will be handled gracefully. If logging is
@@ -871,6 +872,20 @@ see the [FAQ](../faq.md#function-references-in-yaml) to see how to specify funct
871872
- If a `validator` fails, the next `validator`/`formatter` pair will be tired.
872873
///
873874

875+
### Reset
876+
877+
> [!new] New in 13.0
878+
879+
Some custom fences may track data and may require a way to reset that data when the `Markdown` object has its own reset
880+
called. A special reset can be crafted using the format below and set to `reset` when defining a custom fence.
881+
882+
```
883+
def custom_reset(md):
884+
"""Custom reset."""
885+
```
886+
887+
`md` is the `Markdown` object.
888+
874889
### Exception Handling
875890

876891
In general, if an exception occurs in either a validator or a formatter, SuperFences will gracefully ignore the

‎pymdownx/__meta__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -193,5 +193,5 @@ def parse_version(ver: str) -> Version:
193193
return Version(major, minor, micro, release, pre, post, dev)
194194

195195

196-
__version_info__ = Version(12, 0, 1, "final")
196+
__version_info__ = Version(13, 0, 0, "final")
197197
__version__ = __version_info__._get_canonical()

‎pymdownx/superfences.py‎

Lines changed: 26 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -203,13 +203,15 @@ def _validator(language, inputs, options, attrs, md, validator=None):
203203
"""Validator wrapper."""
204204

205205
md.preprocessors['fenced_code_block'].get_hl_settings()
206-
return validator(language, inputs, options, attrs, md)
206+
if validator:
207+
return validator(language, inputs, options, attrs, md)
207208

208209

209210
def _formatter(src='', language='', options=None, md=None, class_name="", _fmt=None, **kwargs):
210211
"""Formatter wrapper."""
211212

212-
return _fmt(src, language, class_name, options, md, **kwargs)
213+
if _fmt:
214+
return _fmt(src, language, class_name, options, md, **kwargs)
213215

214216

215217
def _test(language, test_language=None):
@@ -218,6 +220,17 @@ def _test(language, test_language=None):
218220
return test_language is None or test_language == "*" or language == test_language
219221

220222

223+
def _reset(md, _reset=None):
224+
"""Reset wrapper."""
225+
226+
if _reset:
227+
_reset(md)
228+
229+
230+
def default_reset(md):
231+
"""Default reset."""
232+
233+
221234
class SuperFencesCodeExtension(Extension):
222235
"""SuperFences code block extension."""
223236

@@ -239,14 +252,15 @@ def __init__(self, *args, **kwargs):
239252
}
240253
super().__init__(*args, **kwargs)
241254

242-
def extend_super_fences(self, name, formatter, validator):
255+
def extend_super_fences(self, name, formatter, validator, reset):
243256
"""Extend SuperFences with the given name, language, and formatter."""
244257

245258
obj = {
246259
"name": name,
247260
"test": functools.partial(_test, test_language=name),
248261
"formatter": formatter,
249-
"validator": validator
262+
"validator": validator,
263+
"reset": reset
250264
}
251265

252266
if name == '*':
@@ -268,7 +282,8 @@ def extendMarkdown(self, md):
268282
"name": "superfences",
269283
"test": _test,
270284
"formatter": None,
271-
"validator": functools.partial(_validator, validator=highlight_validator)
285+
"validator": functools.partial(_validator, validator=highlight_validator),
286+
"reset": None
272287
}
273288
)
274289

@@ -279,11 +294,13 @@ def extendMarkdown(self, md):
279294
class_name = custom.get('class')
280295
fence_format = custom.get('format', fence_code_format)
281296
validator = custom.get('validator', default_validator)
297+
reset = custom.get('reset', default_reset)
282298
if name is not None and class_name is not None:
283299
self.extend_super_fences(
284300
name,
285301
functools.partial(_formatter, class_name=class_name, _fmt=fence_format),
286-
functools.partial(_validator, validator=validator)
302+
functools.partial(_validator, validator=validator),
303+
functools.partial(_reset, _reset=reset)
287304
)
288305

289306
self.md = md
@@ -327,6 +344,9 @@ def reset(self):
327344
"""Clear the stash."""
328345

329346
self.stash.clear_stash()
347+
for entry in self.superfences:
348+
if entry['reset'] is not None:
349+
entry['reset'](self.md)
330350

331351

332352
class SuperFencesBlockPreprocessor(Preprocessor):

‎tests/test_extensions/test_superfences.py‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@
88
def custom_format(source, language, class_name, options, md, **kwargs):
99
"""Custom format."""
1010

11+
if hasattr(md, 'special_tracker'):
12+
md.special_tracker = 0
13+
14+
md.special_tracker += 1
15+
1116
return '<div lang="{}" class_name="class-{}", option="{}">{}</div>'.format(language, class_name,
1217
options['opt'], source)
1318

@@ -18,6 +23,12 @@ def default_format(source, language, class_name, options, md, **kwargs):
1823
return '<custom lang="{}" class_name="class-{}">{}</custom>'.format(language, class_name, source)
1924

2025

26+
def custom_reset(md):
27+
"""Default format."""
28+
29+
md.special_tracker = 0
30+
31+
2132
def custom_exploder(source, language, class_name, options, md, **kwargs):
2233
"""Broken format."""
2334

@@ -1013,7 +1024,8 @@ class TestSuperFencesCustom(util.MdCase):
10131024
'name': 'test',
10141025
'class': 'test',
10151026
'format': custom_format,
1016-
'validator': custom_validator
1027+
'validator': custom_validator,
1028+
'reset': custom_reset
10171029
}
10181030
]
10191031
}
@@ -1117,6 +1129,41 @@ def test_custom_options_attr_list(self):
11171129
True
11181130
)
11191131

1132+
def test_reset(self):
1133+
"""Test reset."""
1134+
1135+
import markdown
1136+
import textwrap
1137+
content = textwrap.dedent(
1138+
"""
1139+
```test opt="A"
1140+
content
1141+
```
1142+
"""
1143+
)
1144+
1145+
md = markdown.Markdown(
1146+
extensions=['pymdownx.superfences'],
1147+
extension_configs={
1148+
'pymdownx.superfences': {
1149+
'custom_fences': [
1150+
{
1151+
'name': 'test',
1152+
'class': 'test',
1153+
'format': custom_format,
1154+
'validator': custom_validator,
1155+
'reset': custom_reset
1156+
}
1157+
]
1158+
}
1159+
}
1160+
)
1161+
1162+
print(md.convert(content))
1163+
self.assertEqual(md.special_tracker, 1)
1164+
md.reset()
1165+
self.assertEqual(md.special_tracker, 0)
1166+
11201167

11211168
class TestSuperFencesCustomException(util.MdCase):
11221169
"""Test custom validator and format."""

0 commit comments

Comments
 (0)