markdown-exec 1.12.6__tar.gz → 1.13.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/CHANGELOG.md +8 -0
  2. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/PKG-INFO +1 -1
  3. markdown_exec-1.13.0/docs/snippets/usage/interactive.pycon +5 -0
  4. markdown_exec-1.13.0/docs/usage/python.md +73 -0
  5. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/duties.py +1 -1
  6. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/pyproject.toml +1 -1
  7. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/scripts/gen_credits.py +1 -1
  8. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/scripts/get_version.py +1 -1
  9. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/_exec_python.py +28 -0
  10. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/base.py +9 -1
  11. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/pycon.py +10 -2
  12. markdown_exec-1.13.0/src/markdown_exec/_internal/formatters/python.py +242 -0
  13. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/tree.py +1 -1
  14. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/main.py +2 -0
  15. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/processors.py +1 -1
  16. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/rendering.py +4 -4
  17. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_python.py +118 -0
  18. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_toc.py +9 -9
  19. markdown_exec-1.12.6/docs/usage/python.md +0 -39
  20. markdown_exec-1.12.6/src/markdown_exec/_internal/formatters/python.py +0 -103
  21. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/AI_POLICY.md +0 -0
  22. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/CODE_OF_CONDUCT.md +0 -0
  23. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/CONTRIBUTING.md +0 -0
  24. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/LICENSE +0 -0
  25. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/README.md +0 -0
  26. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/coverage.ini +0 -0
  27. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/git-changelog.toml +0 -0
  28. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/pytest.ini +0 -0
  29. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/ruff.toml +0 -0
  30. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/ty.toml +0 -0
  31. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/vscode/launch.json +0 -0
  32. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/vscode/settings.json +0 -0
  33. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/vscode/tasks.json +0 -0
  34. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/zed/debug.json +0 -0
  35. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/zed/settings.json +0 -0
  36. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/config/zed/tasks.json +0 -0
  37. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/.overrides/main.html +0 -0
  38. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/.overrides/partials/comments.html +0 -0
  39. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/changelog.md +0 -0
  40. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/code_of_conduct.md +0 -0
  41. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/contributing.md +0 -0
  42. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/credits.md +0 -0
  43. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/css/apidocs.css +0 -0
  44. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/gallery.md +0 -0
  45. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/index.md +0 -0
  46. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/js/feedback.js +0 -0
  47. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/license.md +0 -0
  48. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/reference/api.md +0 -0
  49. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/schema.json +0 -0
  50. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/ansi.sh +0 -0
  51. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/argparse.py +0 -0
  52. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/argparse_format.py +0 -0
  53. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/chalk.py +0 -0
  54. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/d2.py +0 -0
  55. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/diagrams.py +0 -0
  56. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/drawsvg.py +0 -0
  57. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/expandable_filetree.py +0 -0
  58. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/highcharts.py +0 -0
  59. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/hyperbolic.py +0 -0
  60. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/matplotlib.py +0 -0
  61. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/plotly.py +0 -0
  62. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/pydeps.py +0 -0
  63. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/qrcode.py +0 -0
  64. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/rich.py +0 -0
  65. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/rich_terminal.py +0 -0
  66. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/runpy.py +0 -0
  67. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/textual.py +0 -0
  68. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/gallery/vega.py +0 -0
  69. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/usage/boolean_matrix.py +0 -0
  70. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/usage/hide.py +0 -0
  71. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/usage/multiple.pycon +0 -0
  72. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/usage/platform_html.py +0 -0
  73. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/usage/platform_md.py +0 -0
  74. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/usage/source.py +0 -0
  75. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/snippets/usage/source.pycon +0 -0
  76. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/usage/index.md +0 -0
  77. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/usage/pyodide.md +0 -0
  78. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/usage/shell.md +0 -0
  79. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/docs/usage/tree.md +0 -0
  80. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/scripts/make +0 -0
  81. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/scripts/make.py +0 -0
  82. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/__init__.py +0 -0
  83. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/__init__.py +0 -0
  84. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/debug.py +0 -0
  85. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/__init__.py +0 -0
  86. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/bash.py +0 -0
  87. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/console.py +0 -0
  88. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/markdown.py +0 -0
  89. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/pyodide.py +0 -0
  90. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/formatters/sh.py +0 -0
  91. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/logger.py +0 -0
  92. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/_internal/mkdocs_plugin.py +0 -0
  93. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/assets/ansi.css +0 -0
  94. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/assets/pyodide.css +0 -0
  95. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/assets/pyodide.js +0 -0
  96. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/__init__.py +0 -0
  97. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/base.py +0 -0
  98. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/bash.py +0 -0
  99. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/console.py +0 -0
  100. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/markdown.py +0 -0
  101. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/pycon.py +0 -0
  102. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/pyodide.py +0 -0
  103. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/python.py +0 -0
  104. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/sh.py +0 -0
  105. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/formatters/tree.py +0 -0
  106. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/logger.py +0 -0
  107. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/mkdocs_plugin.py +0 -0
  108. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/processors.py +0 -0
  109. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/py.typed +0 -0
  110. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/src/markdown_exec/rendering.py +0 -0
  111. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/__init__.py +0 -0
  112. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/conftest.py +0 -0
  113. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_api.py +0 -0
  114. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_base_formatter.py +0 -0
  115. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_converter.py +0 -0
  116. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_headings.py +0 -0
  117. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_shell.py +0 -0
  118. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_tree.py +0 -0
  119. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/tests/test_validator.py +0 -0
  120. {markdown_exec-1.12.6 → markdown_exec-1.13.0}/zensical.toml +0 -0
@@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
5
5
  and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
6
6
 
7
7
  <!-- insertion marker -->
8
+ ## [1.13.0](https://github.com/pawamoy/markdown-exec/releases/tag/1.13.0) - 2026-11-10
9
+
10
+ <small>[Compare with 1.12.6](https://github.com/pawamoy/markdown-exec/compare/1.12.6...1.13.0)</small>
11
+
12
+ ### Features
13
+
14
+ - Emulate Python REPL in pycon blocks ([b40bdc6](https://github.com/pawamoy/markdown-exec/commit/b40bdc62c4ff707eda5162b74af2608ae0960fa5) by Sydney Duckworth). [Issue-25](https://github.com/pawamoy/markdown-exec/issues/25), [PR-105](https://github.com/pawamoy/markdown-exec/pull/105)
15
+
8
16
  ## [1.12.6](https://github.com/pawamoy/markdown-exec/releases/tag/1.12.6) - 2026-10-31
9
17
 
10
18
  <small>[Compare with 1.12.5](https://github.com/pawamoy/markdown-exec/compare/1.12.5...1.12.6)</small>
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: markdown-exec
3
- Version: 1.12.6
3
+ Version: 1.13.0
4
4
  Summary: Utilities to execute code blocks in Markdown files.
5
5
  Keywords: markdown,python,exec,shell,bash,mkdocs
6
6
  Author-Email: Timothée Mazzucotelli <dev@pawamoy.fr>
@@ -0,0 +1,5 @@
1
+ >>> x = [3, 2, 1]
2
+ # Output from unassigned expressions is displayed without needing `print`
3
+ >>> sorted(x)
4
+ # `print` still works as normal
5
+ >>> print(x)
@@ -0,0 +1,73 @@
1
+ # Python
2
+
3
+ ## Regular Python
4
+
5
+ Python code is executed in the current process,
6
+ with isolated global variables.
7
+
8
+ To capture the output of your code, Markdown Exec patches the `print`
9
+ function so that it writes to a buffer instead of standard output.
10
+
11
+ ````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
12
+ ```python exec="1"
13
+ print("**Hello world!**")
14
+ ```
15
+ ````
16
+
17
+ See the [Gallery](../gallery.md) for more complex examples.
18
+
19
+ ## Python console code
20
+
21
+ Code blocks syntax-highlighted with the `pycon` identifier are also supported.
22
+ These code blocks will be pre-processed to keep only the lines
23
+ starting with `>>> `, and the chevrons (prompt) will be removed from these lines,
24
+ so we can execute them.
25
+
26
+ ````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
27
+ ```pycon exec="1" source="console"
28
+ --8<-- "usage/source.pycon"
29
+ ```
30
+ ````
31
+
32
+ It also means that multiple blocks of instructions will be concatenated,
33
+ as well as their output:
34
+
35
+ ````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
36
+ ```pycon exec="1" source="console"
37
+ --8<-- "usage/multiple.pycon"
38
+ ```
39
+ ````
40
+
41
+ ### Interactive console
42
+
43
+ When the `interactive` flag is set, `pycon` blocks will use an alternative formatter that mimics the behavior of the Python REPL interpreter.
44
+
45
+ In this mode outputs are displayed immediately after their source lines, rather than all outputs being shown at the end.
46
+ Additionally, outputs from unbound expressions are displayed automatically (although `print` can still be used as well).
47
+
48
+ ````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
49
+ ```pycon exec="1" interactive="1"
50
+ --8<-- "usage/interactive.pycon"
51
+ ```
52
+ ````
53
+
54
+ Exceptions are also handled differently: when a line raises an exception other lines in the same block are still executed and displayed as normal.
55
+ The raised exception is printed after the generating line and logged as a warning.
56
+
57
+ ````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
58
+ ```pycon exec="1" interactive="1" id="pycon_error"
59
+ >>> y = 2
60
+ >>> y / 0
61
+ >>> y * 2
62
+ ```
63
+ ````
64
+ === "MkDocs Log"
65
+ ```text
66
+ WARNING - markdown_exec: Unexpected exception while executing pycon code block 'pycon_error':
67
+
68
+ Traceback (most recent call last):
69
+ File "<code block: id pycon_error>", line 3, in <module>
70
+ >>> y / 0
71
+ ~~^~~
72
+ ZeroDivisionError: division by zero
73
+ ```
@@ -53,7 +53,7 @@ def pyprefix(title: str) -> str:
53
53
  def _get_changelog_version() -> str:
54
54
  changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$")
55
55
  with Path(__file__).parent.joinpath("CHANGELOG.md").open("r", encoding="utf8") as file:
56
- return next(filter(bool, map(changelog_version_re.match, file))).group(1) # ty:ignore[unresolved-attribute]
56
+ return next(filter(bool, map(changelog_version_re.match, file))).group(1) # ty:ignore[missing-union-attribute]
57
57
 
58
58
 
59
59
  @duty
@@ -45,7 +45,7 @@ dependencies = [
45
45
  "markupsafe>=2",
46
46
  "pymdown-extensions>=9",
47
47
  ]
48
- version = "1.12.6"
48
+ version = "1.13.0"
49
49
 
50
50
  [project.optional-dependencies]
51
51
  ansi = [
@@ -65,7 +65,7 @@ def _extra_marker(req: Requirement) -> str | None:
65
65
  if not req.marker:
66
66
  return None
67
67
  try:
68
- return next(marker[2].value for marker in req.marker._markers if getattr(marker[0], "value", None) == "extra") # ty:ignore[unresolved-attribute]
68
+ return next(marker[2].value for marker in req.marker._markers if getattr(marker[0], "value", None) == "extra") # ty:ignore[missing-union-attribute]
69
69
  except StopIteration:
70
70
  return None
71
71
 
@@ -22,7 +22,7 @@ import re
22
22
  from contextlib import suppress
23
23
  from pathlib import Path
24
24
 
25
- from pdm.backend.hooks.version import ( # ty: ignore[unresolved-import]
25
+ from pdm.backend.hooks.version import ( # ty: ignore[import-not-found]
26
26
  SCMVersion,
27
27
  Version,
28
28
  default_version_formatter,
@@ -18,9 +18,37 @@
18
18
 
19
19
  # Special module without future annotations for executing Python code.
20
20
 
21
+ import ast
21
22
  from typing import Any
22
23
 
23
24
 
24
25
  def exec_python(code: str, filename: str, exec_globals: dict[str, Any] | None = None) -> None:
25
26
  compiled = compile(code, filename=filename, mode="exec")
26
27
  exec(compiled, exec_globals) # noqa: S102
28
+
29
+
30
+ def exec_python_interactive(code: str, filename: str, exec_globals: dict) -> Any | None:
31
+ cmd = ast.parse(code, filename, "exec")
32
+
33
+ # Check if last statement is an unassigned expression whose result should be returned.
34
+ # Unassigned expressions *within* an input can be ignored,
35
+ # e.g. in `x = 2; x; x + 1` the second statement isn't output.
36
+ if cmd.body and isinstance(cmd.body[-1], ast.Expr):
37
+ expr = ast.Expression(cmd.body[-1].value)
38
+ stmts = cmd.body[:-1]
39
+ else:
40
+ expr = None
41
+ stmts = cmd.body
42
+
43
+ if stmts:
44
+ # Execute all statements that don't generate output.
45
+ exec( # noqa: S102
46
+ compile(ast.Module(stmts, []), filename, "exec"),
47
+ exec_globals,
48
+ )
49
+
50
+ if expr:
51
+ # Execute final expression and return result.
52
+ return eval(compile(expr, filename, "eval"), exec_globals) # noqa: S307
53
+
54
+ return None
@@ -124,6 +124,7 @@ def base_format(
124
124
  update_toc: bool = True,
125
125
  workdir: str | None = None,
126
126
  width: int | None = None,
127
+ interactive: bool = False,
127
128
  **options: Any,
128
129
  ) -> Markup:
129
130
  """Execute code and return HTML.
@@ -163,7 +164,14 @@ def base_format(
163
164
 
164
165
  try:
165
166
  with working_directory(workdir), console_width(width):
166
- output = run(source_input, returncode=returncode, session=session, id=id, **extra)
167
+ output = run(
168
+ source_input,
169
+ returncode=returncode,
170
+ session=session,
171
+ id=id,
172
+ interactive=interactive,
173
+ **extra,
174
+ )
167
175
  except ExecutionError as error:
168
176
  identifier = id or extra.get("title", "")
169
177
  identifier = identifier and f"'{identifier}' "
@@ -40,5 +40,13 @@ def _transform_source(code: str) -> tuple[str, str]:
40
40
  return python_code, "\n".join(pycon_lines)
41
41
 
42
42
 
43
- def _format_pycon(**kwargs: Any) -> Markup:
44
- return base_format(language="pycon", run=_run_python, transform_source=_transform_source, **kwargs)
43
+ def _format_pycon(*, interactive: bool = False, **kwargs: Any) -> Markup:
44
+ transform_source = _transform_source if not interactive else None
45
+
46
+ return base_format(
47
+ language="pycon",
48
+ run=_run_python,
49
+ transform_source=transform_source,
50
+ interactive=interactive,
51
+ **kwargs,
52
+ )
@@ -0,0 +1,242 @@
1
+ # SPDX-License-Identifier: ISC
2
+ #
3
+ # ISC License
4
+ #
5
+ # Copyright (c) 2022, Timothée Mazzucotelli and contributors
6
+ #
7
+ # Permission to use, copy, modify, and/or distribute this software for any
8
+ # purpose with or without fee is hereby granted, provided that the above
9
+ # copyright notice and this permission notice appear in all copies.
10
+ #
11
+ # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12
+ # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13
+ # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14
+ # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15
+ # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16
+ # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17
+ # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18
+
19
+ # Formatter for executing Python code.
20
+
21
+ from __future__ import annotations
22
+
23
+ import re
24
+ import sys
25
+ import traceback
26
+ from collections import defaultdict
27
+ from dataclasses import dataclass
28
+ from functools import partial
29
+ from io import StringIO
30
+ from textwrap import indent
31
+ from types import ModuleType
32
+ from typing import TYPE_CHECKING, Any
33
+
34
+ from markdown_exec._internal.formatters._exec_python import exec_python, exec_python_interactive
35
+ from markdown_exec._internal.formatters.base import ExecutionError, base_format
36
+ from markdown_exec._internal.logger import get_logger
37
+ from markdown_exec._internal.rendering import code_block
38
+
39
+ if TYPE_CHECKING:
40
+ from collections.abc import Iterator
41
+
42
+ _logger = get_logger(__name__)
43
+ _sessions_globals: dict[str, dict] = defaultdict(dict)
44
+ _sessions_counter: dict[str | None, int] = defaultdict(int)
45
+ _code_blocks: dict[str, list[str]] = {}
46
+
47
+
48
+ def _buffer_print(buffer: StringIO, *texts: str, end: str = "\n", **kwargs: Any) -> None: # noqa: ARG001
49
+ buffer.write(" ".join(str(text) for text in texts) + end)
50
+
51
+
52
+ def _code_block_id(
53
+ id: str | None = None, # noqa: A002
54
+ session: str | None = None,
55
+ title: str | None = None,
56
+ ) -> str:
57
+ _sessions_counter[session] += 1
58
+ if id:
59
+ code_block_id = f"id {id}"
60
+ elif session:
61
+ code_block_id = f"session {session}; n{_sessions_counter[session]}"
62
+ if title:
63
+ code_block_id = f"{code_block_id}; title {title}"
64
+ else:
65
+ code_block_id = f"n{_sessions_counter[session]}"
66
+ if title:
67
+ code_block_id = f"{code_block_id}; title {title}"
68
+ return f"<code block: {code_block_id}>"
69
+
70
+
71
+ @dataclass(slots=True)
72
+ class _InteractiveInput:
73
+ """A single interactive input to the interpreter.
74
+
75
+ May consist of one line or multiple lines (`>>>` followed by `...`).
76
+ May contain multiple statements.
77
+ """
78
+
79
+ lineno: int
80
+ display_lines: list[str]
81
+ src_lines: list[str]
82
+
83
+ @classmethod
84
+ def split(cls, code: str, filename: str) -> Iterator[_InteractiveInput]:
85
+ lines = enumerate(code.split("\n"))
86
+ current = None
87
+
88
+ for lineno, line in lines:
89
+ if line.startswith("... "):
90
+ if current:
91
+ current.append(line)
92
+ else:
93
+ raise SyntaxError("Expected '>>>'", (filename, lineno, 1, line, lineno, 4))
94
+ else:
95
+ if current:
96
+ yield current
97
+ current = None
98
+
99
+ if line.startswith(">>> "):
100
+ current = _InteractiveInput.from_line(lineno, line)
101
+
102
+ if current:
103
+ yield current
104
+
105
+ @classmethod
106
+ def from_line(cls, lineno: int, line: str) -> _InteractiveInput:
107
+ return cls(lineno, [line], [line[4:]])
108
+
109
+ def append(self, line: str) -> None:
110
+ self.display_lines.append(line)
111
+ self.src_lines.append(line[4:])
112
+
113
+ def with_traceback(self, error: Exception) -> traceback.TracebackException:
114
+ if isinstance(error, SyntaxError) and (error.filename or "").startswith("<code block: "):
115
+ # Fix line and column for syntax errors originating in the code block.
116
+ error.text = self.display_lines[error.lineno - 1] # ty:ignore[unsupported-operator]
117
+ error.lineno += self.lineno # ty:ignore[unsupported-operator]
118
+ error.offset += 4 # ty:ignore[unsupported-operator]
119
+ if error.end_lineno is not None:
120
+ error.end_lineno += self.lineno
121
+ if error.end_offset is not None:
122
+ error.end_offset += 4
123
+
124
+ trace = traceback.TracebackException.from_exception(error)
125
+
126
+ start = None
127
+ for i, frame in enumerate(trace.stack):
128
+ if frame.filename.startswith("<code block: ") and i > 0:
129
+ # Find first stack frame originating in the code block.
130
+ if start is None:
131
+ start = i
132
+
133
+ if sys.version_info >= (3, 13):
134
+ frame._lines = self.display_lines[frame.lineno - 1] # ty:ignore[missing-attribute,unsupported-operator,unused-ignore-comment,unused-ignore-comment]
135
+ else:
136
+ frame._line = self.display_lines[frame.lineno - 1] # ty:ignore[missing-attribute,unsupported-operator,unused-ignore-comment,unused-ignore-comment]
137
+
138
+ # Fix line and column.
139
+ frame.colno += 4 # ty:ignore[unsupported-operator]
140
+ frame.lineno += self.lineno # ty:ignore[unsupported-operator]
141
+ if frame.end_lineno is not None:
142
+ frame.end_lineno += self.lineno
143
+ if frame.end_colno is not None:
144
+ frame.end_colno += 4
145
+
146
+ if getattr(trace, "filename", "").startswith("<code block: ") and start is None:
147
+ # Syntax errors sort of "skip" a stack frame.
148
+ # We need to check the error's filename to determine
149
+ # if it came from the code block.
150
+ start = len(trace.stack)
151
+
152
+ if start is None:
153
+ # Error originated from this package not the code block, so we need to reraise it.
154
+ raise error
155
+
156
+ # Remove exec/eval frames from stack.
157
+ if start > 0:
158
+ del trace.stack[:start]
159
+
160
+ return trace
161
+
162
+
163
+ def _run_interactive( # noqa: PLR0917
164
+ code: str,
165
+ filename: str,
166
+ exec_globals: dict,
167
+ buffer: StringIO,
168
+ id: str | None, # noqa: A002
169
+ title: str | None,
170
+ ) -> None:
171
+ for inp in _InteractiveInput.split(code, filename):
172
+ buffer.write("\n".join(inp.display_lines) + "\n")
173
+ try:
174
+ if (res := exec_python_interactive("\n".join(inp.src_lines), filename, exec_globals)) is not None:
175
+ buffer.write(repr(res) + "\n")
176
+ except Exception as error: # noqa: BLE001
177
+ trace = inp.with_traceback(error)
178
+ err_msg = "".join(trace.format())
179
+ # Write error traceback to output buffer.
180
+ buffer.write(err_msg)
181
+
182
+ # We need to manually log the warning because we don't want to abort processing the block.
183
+ identifier = id or title
184
+ identifier = identifier and f"'{identifier}'"
185
+ log_err = indent(err_msg, " " * 2)
186
+ log_message = f"Unexpected exception while executing pycon code block {identifier}:\n\n{log_err}"
187
+ _logger.warning(log_message)
188
+
189
+
190
+ def _run_python(
191
+ code: str,
192
+ returncode: int | None = None, # noqa: ARG001
193
+ session: str | None = None,
194
+ id: str | None = None, # noqa: A002
195
+ interactive: bool = False, # noqa: FBT001, FBT002
196
+ **extra: str,
197
+ ) -> str:
198
+ title = extra.get("title")
199
+ code_block_id = _code_block_id(id, session, title)
200
+ _code_blocks[code_block_id] = code.split("\n")
201
+ exec_globals = _sessions_globals[session] if session else {}
202
+
203
+ # Other libraries expect functions to have a valid `__module__` attribute.
204
+ # To achieve this, we need to add a `__name__` attribute to the globals.
205
+ # We compute the name from the code block ID, replacing invalid characters with `_`.
206
+ # We also create a module object with the same name and add it to `sys.modules`,
207
+ # because that's what yet other libraries expect (`dataclasses` for example).
208
+ module_name = re.sub(r"[^a-zA-Z\d]+", "_", code_block_id)
209
+ exec_globals["__name__"] = module_name
210
+ sys.modules[module_name] = ModuleType(module_name)
211
+
212
+ buffer = StringIO()
213
+ exec_globals["print"] = partial(_buffer_print, buffer)
214
+
215
+ try:
216
+ if interactive:
217
+ _run_interactive(code, code_block_id, exec_globals, buffer, id, title)
218
+ else:
219
+ exec_python(code, code_block_id, exec_globals)
220
+ except Exception as error:
221
+ trace = traceback.TracebackException.from_exception(error)
222
+ for frame in trace.stack:
223
+ if frame.filename.startswith("<code block: "):
224
+ if sys.version_info >= (3, 13):
225
+ frame._lines = _code_blocks[frame.filename][frame.lineno - 1] # ty:ignore[missing-attribute,unsupported-operator,unused-ignore-comment,unused-ignore-comment]
226
+ else:
227
+ frame._line = _code_blocks[frame.filename][frame.lineno - 1] # ty:ignore[missing-attribute,unsupported-operator,unused-ignore-comment,unused-ignore-comment]
228
+ raise ExecutionError(code_block("python", "".join(trace.format()), **extra)) from error
229
+
230
+ if interactive:
231
+ return code_block("pycon", buffer.getvalue())
232
+
233
+ return buffer.getvalue()
234
+
235
+
236
+ def _format_python(
237
+ *,
238
+ # Pull out interactive flag to avoid passing to _run_python
239
+ interactive: bool = False, # noqa: ARG001
240
+ **kwargs: Any,
241
+ ) -> str:
242
+ return base_format(language="python", run=_run_python, **kwargs)
@@ -31,7 +31,7 @@ from markupsafe import Markup
31
31
  from markdown_exec._internal.rendering import MarkdownConverter, code_block
32
32
 
33
33
  try:
34
- import material # ty:ignore[unresolved-import]
34
+ import material # ty:ignore[import-not-found]
35
35
  except ImportError:
36
36
  material = None
37
37
 
@@ -94,6 +94,7 @@ def validator(
94
94
  tabs = tuple(_tabs_re.split(tabs_value, maxsplit=1))
95
95
  workdir_value = inputs.pop("workdir", None)
96
96
  width_value = int(inputs.pop("width", "0"))
97
+ interactive = _to_bool(inputs.pop("interactive", "no"))
97
98
  options["id"] = id_value
98
99
  options["id_prefix"] = id_prefix_value
99
100
  options["html"] = html_value
@@ -106,6 +107,7 @@ def validator(
106
107
  options["workdir"] = workdir_value
107
108
  options["width"] = width_value
108
109
  options["extra"] = inputs
110
+ options["interactive"] = interactive
109
111
  return True
110
112
 
111
113
 
@@ -90,7 +90,7 @@ class HeadingReportingTreeprocessor(Treeprocessor):
90
90
  el = copy.deepcopy(el) # noqa: PLW2901
91
91
  # 'toc' extension's first pass (which we require to build heading stubs/ids) also edits the HTML.
92
92
  # Undo the permalink edit so we can pass this heading to the outer pass of the 'toc' extension.
93
- if len(el) > 0 and el[-1].get("class") == self.md.treeprocessors["toc"].permalink_class: # ty:ignore[unresolved-attribute]
93
+ if len(el) > 0 and el[-1].get("class") == self.md.treeprocessors["toc"].permalink_class: # ty:ignore[missing-attribute]
94
94
  del el[-1]
95
95
  self.headings.append(el)
96
96
 
@@ -238,7 +238,7 @@ def _mimic(md: Markdown, headings: list[Element], *, update_toc: bool = True) ->
238
238
  IdPrependingTreeprocessor.name,
239
239
  priority=4, # right after 'toc' (needed because that extension adds ids to headings)
240
240
  )
241
- new_md._original_md = md # ty:ignore[unresolved-attribute]
241
+ new_md._original_md = md # ty:ignore[missing-attribute]
242
242
 
243
243
  if update_toc:
244
244
  _register_headings_processors(md)
@@ -255,11 +255,11 @@ def _mimic(md: Markdown, headings: list[Element], *, update_toc: bool = True) ->
255
255
  def _id_prefix(md: Markdown, prefix: str | None) -> Generator[None]:
256
256
  MarkdownConverter.counter += 1
257
257
  id_prepending_processor = md.treeprocessors[IdPrependingTreeprocessor.name]
258
- id_prepending_processor.id_prefix = prefix if prefix is not None else f"exec-{MarkdownConverter.counter}--" # ty:ignore[unresolved-attribute]
258
+ id_prepending_processor.id_prefix = prefix if prefix is not None else f"exec-{MarkdownConverter.counter}--" # ty:ignore[missing-attribute]
259
259
  try:
260
260
  yield
261
261
  finally:
262
- id_prepending_processor.id_prefix = "" # ty:ignore[unresolved-attribute]
262
+ id_prepending_processor.id_prefix = "" # ty:ignore[missing-attribute]
263
263
 
264
264
 
265
265
  class MarkdownConverter:
@@ -291,7 +291,7 @@ class MarkdownConverter:
291
291
  if element.tail:
292
292
  element.tail = type(element.tail)(HTML_PLACEHOLDER_RE.sub(restash, element.tail))
293
293
 
294
- self._original_md.treeprocessors[InsertHeadings.name].headings[markup] = self._headings # ty:ignore[unresolved-attribute]
294
+ self._original_md.treeprocessors[InsertHeadings.name].headings[markup] = self._headings # ty:ignore[missing-attribute]
295
295
  self._headings = []
296
296
 
297
297
  def convert(self, text: str, stash: dict[str, str] | None = None, id_prefix: str | None = None) -> Markup:
@@ -247,3 +247,121 @@ def test_future_annotations_do_not_leak_into_user_code(md: Markdown) -> None:
247
247
  )
248
248
  assert "<code>Int</code>" not in html
249
249
  assert re.search(r"class '_code_block_n\d+_\.Int'", html)
250
+
251
+
252
+ def test_interactive_continue_on_error(md: Markdown, caplog: pytest.LogCaptureFixture) -> None:
253
+ """Assert subsequent interactive pycon lines are executed if a line raises an exception.
254
+
255
+ Parameters:
256
+ md: A Markdown instance (fixture).
257
+ """
258
+ html = md.convert(
259
+ dedent(
260
+ """
261
+ ```pycon exec="1" interactive="1"
262
+ >>> x = 2
263
+ >>> x / 0
264
+ >>> x + 1
265
+ ```
266
+ """,
267
+ ),
268
+ )
269
+
270
+ assert "Traceback" in html
271
+ assert "ZeroDivisionError" in html
272
+ assert "3" in html
273
+ assert "Unexpected exception" in caplog.text
274
+
275
+
276
+ def test_interactive_syntax_error(md: Markdown, caplog: pytest.LogCaptureFixture) -> None:
277
+ """Assert syntax errors in interactive pycon snippets work the same as other exceptions.
278
+
279
+ This is worth testing because the handling of syntax errors is slightly different from other errors.
280
+
281
+ Parameters:
282
+ md: A Markdown instance (fixture).
283
+ """
284
+ html = md.convert(
285
+ dedent(
286
+ """
287
+ ```pycon exec="1" interactive="1"
288
+ >>> ^123abc_!
289
+ >>> "foo" + "bar"
290
+ ```
291
+ """,
292
+ ),
293
+ )
294
+
295
+ assert "SyntaxError" in html
296
+ assert "foobar" in html
297
+ assert "Unexpected exception" in caplog.text
298
+
299
+
300
+ def test_interactive_line_marker_syntax_error(md: Markdown, caplog: pytest.LogCaptureFixture) -> None:
301
+ """Assert that a `...` line not proceeded by a `>>>` line in a pycon snippet generates a syntax error and aborts execution.
302
+
303
+ Parameters:
304
+ md: A Markdown instance (fixture).
305
+ """
306
+ html = md.convert(
307
+ dedent(
308
+ """
309
+ ```pycon exec="1" interactive="1"
310
+ ... x = 2
311
+ >>> "foo"
312
+ ```
313
+ """,
314
+ ),
315
+ )
316
+
317
+ assert "SyntaxError" in html
318
+ assert "foo" not in html
319
+ assert "Execution of pycon code block exited with errors" in caplog.text
320
+
321
+
322
+ def test_interactive_compound_expressions(md: Markdown) -> None:
323
+ """Assert that interactive pycon snippets execute all expressions in a multi-statement line but only display the last expression.
324
+
325
+ Parameters:
326
+ md: A Markdown instance (fixture).
327
+ """
328
+ html = md.convert(
329
+ dedent(
330
+ """
331
+ ```pycon exec="1" interactive="1"
332
+ >>> def pop(x):
333
+ ... x.pop()
334
+ ... return x
335
+ >>> x = [1, 2, 3]; pop(x); pop(x)
336
+ ```
337
+ """,
338
+ ),
339
+ )
340
+
341
+ assert "[1, 2]" not in html
342
+ assert "[1]" in html
343
+
344
+
345
+ def test_interactive_print_statements(md: Markdown) -> None:
346
+ """Assert that interactive pycon snippets show `print` output before expression output.
347
+
348
+ Parameters:
349
+ md: A Markdown instance (fixture).
350
+ """
351
+ html = md.convert(
352
+ dedent(
353
+ """
354
+ ```pycon exec="1" interactive="1"
355
+ >>> def print_and_add(x):
356
+ ... print(x)
357
+ ... return x + 1
358
+
359
+ >>> print_and_add(4)
360
+ ```
361
+ """,
362
+ ),
363
+ )
364
+
365
+ assert (loc1 := html.find("4")) > 0
366
+ assert (loc2 := html.find("5")) > 0
367
+ assert loc1 < loc2