If you sponsor publicly, you're automatically added here with a link to your profile and avatar to show your support for *Markdown Exec*. Alternatively, if you wish to keep your sponsorship private, you'll be a silent +1. You can select visibility during checkout and change it afterwards. ## Funding ### Goals The following section lists all funding goals. Each goal contains a list of features prefixed with a checkmark symbol, denoting whether a feature is :octicons-check-circle-fill-24:{ style="color: #00e676" } already available or :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features are released for general availability. ```python exec="1" session="insiders" idprefix="" for goal in goals.values(): if not goal.complete: goal.render() ``` ### Goals completed This section lists all funding goals that were previously completed, which means that those features were part of Insiders, but are now generally available and can be used by all users. ```python exec="1" session="insiders" for goal in goals.values(): if goal.complete: goal.render() ``` ## Frequently asked questions ### Compatibility > We're building an open source project and want to allow outside collaborators to use *Markdown Exec* locally without having access to Insiders. Is this still possible? Yes. Insiders is compatible with *Markdown Exec*. Almost all new features and configuration options are either backward-compatible or implemented behind feature flags. Most Insiders features enhance the overall experience, though while these features add value for the users of your project, they shouldn't be necessary for previewing when making changes to content. ### Payment > We don't want to pay for sponsorship every month. Are there any other options? Yes. You can sponsor on a yearly basis by [switching your GitHub account to a yearly billing cycle][billing cycle]. If for some reason you cannot do that, you could also create a dedicated GitHub account with a yearly billing cycle, which you only use for sponsoring (some sponsors already do that). If you have any problems or further questions, please reach out to pawamoy@pm.me. ### Terms > Are we allowed to use Insiders under the same terms and conditions as *Markdown Exec*? Yes. Whether you're an individual or a company, you may use *Markdown Exec Insiders* precisely under the same terms as *Markdown Exec*, which are given by the [ISC License][license]. However, we kindly ask you to respect our **fair use policy**: - Please **don't distribute the source code** of Insiders. You may freely use it for public, private or commercial projects, privately fork or mirror it, but please don't make the source code public, as it would counteract the sponsorware strategy. - If you cancel your subscription, you're automatically removed as a collaborator and will miss out on all future updates of Insiders. However, you may **use the latest version** that's available to you **as long as you like**. Just remember that [GitHub deletes private forks][private forks]. [insiders]: #what-is-insiders [sponsorship]: #what-sponsorships-achieve [sponsors]: #how-to-become-a-sponsor [features]: #whats-in-it-for-me [funding]: #funding [goals completed]: #goals-completed [github sponsor profile]: https://github.com/sponsors/pawamoy [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle [license]: ../license.md [private forks]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository markdown-exec-1.8.0/docs/insiders/installation.md 0000664 0000000 0000000 00000015527 14546046442 0022102 0 ustar 00root root 0000000 0000000 --- title: Getting started with Insiders --- # Getting started with Insiders *Markdown Exec Insiders* is a compatible drop-in replacement for *Markdown Exec*, and can be installed similarly using `pip` or `git`. Note that in order to access the Insiders repository, you need to [become an eligible sponsor] of @pawamoy on GitHub. [become an eligible sponsor]: index.md#how-to-become-a-sponsor ## Installation ### with PyPI Insiders [PyPI Insiders](https://pawamoy.github.io/pypi-insiders/) is a tool that helps you keep up-to-date versions of Insiders projects in the PyPI index of your choice (self-hosted, Google registry, Artifactory, etc.). See [how to install it](https://pawamoy.github.io/pypi-insiders/#installation) and [how to use it](https://pawamoy.github.io/pypi-insiders/#usage). ### with pip (ssh/https) *Markdown Exec Insiders* can be installed with `pip` [using SSH][using ssh]: ```bash pip install git+ssh://git@github.com/pawamoy-insiders/markdown-exec.git ``` [using ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh Or using HTTPS: ```bash pip install git+https://${GH_TOKEN}@github.com/pawamoy-insiders/markdown-exec.git ``` >? NOTE: **How to get a GitHub personal access token** > The `GH_TOKEN` environment variable is a GitHub token. > It can be obtained by creating a [personal access token] for > your GitHub account. It will give you access to the Insiders repository, > programmatically, from the command line or GitHub Actions workflows: > > 1. Go to https://github.com/settings/tokens > 2. Click on [Generate a new token] > 3. Enter a name and select the [`repo`][scopes] scope > 4. Generate the token and store it in a safe place > > [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token > [Generate a new token]: https://github.com/settings/tokens/new > [scopes]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes > > Note that the personal access > token must be kept secret at all times, as it allows the owner to access your > private repositories. ### with pip (self-hosted) Self-hosting the Insiders package makes it possible to depend on *Markdown Exec* normally, while transparently downloading and installing the Insiders version locally. It means that you can specify your dependencies normally, and your contributors without access to Insiders will get the public version, while you get the Insiders version on your machine. WARNING: **Limitation** With this method, there is no way to force the installation of an Insiders version rather than a public version. If there is a public version that is more recent than your self-hosted Insiders version, the public version will take precedence. Remember to regularly update your self-hosted versions by uploading latest distributions. You can build the distributions for Insiders yourself, by cloning the repository and using [build] to build the distributions, or you can download them from our [GitHub Releases]. You can upload these distributions to a private PyPI-like registry ([Artifactory], [Google Cloud], [pypiserver], etc.) with [Twine]: [build]: https://pypi.org/project/build/ [Artifactory]: https://jfrog.com/help/r/jfrog-artifactory-documentation/pypi-repositories [Google Cloud]: https://cloud.google.com/artifact-registry/docs/python [pypiserver]: https://pypi.org/project/pypiserver/ [Github Releases]: https://github.com/pawamoy-insiders/markdown-exec/releases [Twine]: https://pypi.org/project/twine/ ```bash # download distributions in ~/dists, then upload with: twine upload --repository-url https://your-private-index.com ~/dists/* ``` You might also need to provide a username and password/token to authenticate against the registry. Please check [Twine's documentation][twine docs]. [twine docs]: https://twine.readthedocs.io/en/stable/ You can then configure pip (or other tools) to look for packages into your package index. For example, with pip: ```bash pip config set global.extra-index-url https://your-private-index.com/simple ``` Note that the URL might differ depending on whether your are uploading a package (with Twine) or installing a package (with pip), and depending on the registry you are using (Artifactory, Google Cloud, etc.). Please check the documentation of your registry to learn how to configure your environment. **We kindly ask that you do not upload the distributions to public registries, as it is against our [Terms of use](index.md#terms).** >? TIP: **Full example with `pypiserver`** > In this example we use [pypiserver] to serve a local PyPI index. > > ```bash > pip install --user pypiserver > # or pipx install pypiserver > > # create a packages directory > mkdir -p ~/.local/pypiserver/packages > > # run the pypi server without authentication > pypi-server run -p 8080 -a . -P . ~/.local/pypiserver/packages & > ``` > > We can configure the credentials to access the server in [`~/.pypirc`][pypirc]: > > [pypirc]: https://packaging.python.org/en/latest/specifications/pypirc/ > > ```ini title=".pypirc" > [distutils] > index-servers = > local > > [local] > repository: http://localhost:8080 > username: > password: > ``` > > We then clone the Insiders repository, build distributions and upload them to our local server: > > ```bash > # clone the repository > git clone git@github.com:pawamoy-insiders/markdown-exec > cd markdown-exec > > # install build > pip install --user build > # or pipx install build > > # checkout latest tag > git checkout $(git describe --tags --abbrev=0) > > # build the distributions > pyproject-build > > # upload them to our local server > twine upload -r local dist/* --skip-existing > ``` > > Finally, we configure pip, and for example [PDM][pdm], to use our local index to find packages: > > ```bash > pip config set global.extra-index-url http://localhost:8080/simple > pdm config pypi.extra.url http://localhost:8080/simple > ``` > > [pdm]: https://pdm.fming.dev/latest/ > > Now when running `pip install markdown-exec`, > or resolving dependencies with PDM, > both tools will look into our local index and find the Insiders version. > **Remember to update your local index regularly!** ### with git Of course, you can use *Markdown Exec Insiders* directly from `git`: ``` git clone git@github.com:pawamoy-insiders/markdown-exec ``` When cloning from `git`, the package must be installed: ``` pip install -e markdown-exec ``` ## Upgrading When upgrading Insiders, you should always check the version of *Markdown Exec* which makes up the first part of the version qualifier. For example, a version like `8.x.x.4.x.x` means that Insiders `4.x.x` is currently based on `8.x.x`. If the major version increased, it's a good idea to consult the [changelog] and go through the steps to ensure your configuration is up to date and all necessary changes have been made. [changelog]: ./changelog.md markdown-exec-1.8.0/docs/js/ 0000775 0000000 0000000 00000000000 14546046442 0015641 5 ustar 00root root 0000000 0000000 markdown-exec-1.8.0/docs/js/insiders.js 0000664 0000000 0000000 00000005062 14546046442 0020022 0 ustar 00root root 0000000 0000000 function humanReadableAmount(amount) { const strAmount = String(amount); if (strAmount.length >= 4) { return `${strAmount.slice(0, strAmount.length - 3)},${strAmount.slice(-3)}`; } return strAmount; } function getJSON(url, callback) { var xhr = new XMLHttpRequest(); xhr.open('GET', url, true); xhr.responseType = 'json'; xhr.onload = function () { var status = xhr.status; if (status === 200) { callback(null, xhr.response); } else { callback(status, xhr.response); } }; xhr.send(); } function updateInsidersPage(author_username) { const sponsorURL = `https://github.com/sponsors/${author_username}` const dataURL = `https://raw.githubusercontent.com/${author_username}/sponsors/main`; getJSON(dataURL + '/numbers.json', function (err, numbers) { document.getElementById('sponsors-count').innerHTML = numbers.count; Array.from(document.getElementsByClassName('sponsors-total')).forEach(function (element) { element.innerHTML = '$ ' + humanReadableAmount(numbers.total); }); getJSON(dataURL + '/sponsors.json', function (err, sponsors) { const sponsorsElem = document.getElementById('sponsors'); const privateSponsors = numbers.count - sponsors.length; sponsors.forEach(function (sponsor) { sponsorsElem.innerHTML += `
'
sponsors.forEach(function (sponsor) {
html += `
`
});
html += '
')
markdown-exec-1.8.0/docs/snippets/gallery/matplotlib.py 0000664 0000000 0000000 00000002216 14546046442 0023253 0 ustar 00root root 0000000 0000000 # https://matplotlib.org/stable/gallery/lines_bars_and_markers/scatter_demo2.html
from io import StringIO
import matplotlib.cbook as cbook
import matplotlib.pyplot as plt
import numpy as np
# Load a numpy record array from yahoo csv data with fields date, open, close,
# volume, adj_close from the mpl-data/example directory. The record array
# stores the date as an np.datetime64 with a day unit ('D') in the date column.
price_data = cbook.get_sample_data("goog.npz", np_load=True)["price_data"].view(np.recarray)
price_data = price_data[-250:] # get the most recent 250 trading days
delta1 = np.diff(price_data.adj_close) / price_data.adj_close[:-1]
# Marker size in units of points^2
volume = (15 * price_data.volume[:-2] / price_data.volume[0]) ** 2
close = 0.003 * price_data.close[:-2] / 0.003 * price_data.open[:-2]
fig, ax = plt.subplots()
ax.scatter(delta1[:-1], delta1[1:], c=close, s=volume, alpha=0.5)
ax.set_xlabel(r"$\Delta_i$", fontsize=15)
ax.set_ylabel(r"$\Delta_{i+1}$", fontsize=15)
ax.set_title("Volume and percent change")
ax.grid(True)
fig.tight_layout()
buffer = StringIO()
plt.savefig(buffer, format="svg")
print(buffer.getvalue())
markdown-exec-1.8.0/docs/snippets/gallery/pydeps.py 0000664 0000000 0000000 00000002602 14546046442 0022407 0 ustar 00root root 0000000 0000000 from pydeps import cli, colors, dot, py2depgraph
from pydeps.pydeps import depgraph_to_dotsrc
from pydeps.target import Target
cli.verbose = cli._not_verbose
options = cli.parse_args(["src/markdown_exec", "--noshow"])
colors.START_COLOR = options["start_color"]
target = Target(options["fname"])
with target.chdir_work():
dep_graph = py2depgraph.py2dep(target, **options)
dot_src = depgraph_to_dotsrc(target, dep_graph, **options)
svg = dot.call_graphviz_dot(dot_src, "svg").decode()
svg = "".join(svg.splitlines()[6:])
svg = svg.replace('fill="white"', 'fill="transparent"')
reference = "../reference"
modules = (
"markdown_exec",
"markdown_exec.formatters",
"markdown_exec.formatters.base",
"markdown_exec.formatters.bash",
"markdown_exec.formatters.console",
"markdown_exec.formatters.markdown",
"markdown_exec.formatters.pycon",
"markdown_exec.formatters.python",
"markdown_exec.formatters.sh",
"markdown_exec.formatters.tree",
"markdown_exec.logger",
"markdown_exec.mkdocs_plugin",
"markdown_exec.processors",
"markdown_exec.rendering",
)
for module in modules:
svg_title = module.replace(".", "_")
title_tag = f"{code}") # markdown-exec: hide markdown-exec-1.8.0/docs/snippets/usage/multiple.pycon 0000664 0000000 0000000 00000000114 14546046442 0023077 0 ustar 00root root 0000000 0000000 >>> name = "Baron" >>> print(name) Baron >>> age = "???" >>> print(age) ??? markdown-exec-1.8.0/docs/snippets/usage/platform_html.py 0000664 0000000 0000000 00000000436 14546046442 0023423 0 ustar 00root root 0000000 0000000 import platform print( f"""
- machine:
{platform.machine()} - version:
{platform.version()} - platform:
{platform.platform()} - system:
{platform.system()}
%(initial_code)s
"
def _run_python(
code: str,
returncode: int | None = None, # noqa: ARG001
session: str | None = None,
id: str | None = None, # noqa: A002
**extra: str,
) -> str:
title = extra.get("title", None)
code_block_id = _code_block_id(id, session, title)
_code_blocks[code_block_id] = code.split("\n")
exec_globals = _sessions_globals[session] if session else {}
buffer = StringIO()
exec_globals["print"] = partial(_buffer_print, buffer)
try:
compiled = compile(code, filename=code_block_id, mode="exec")
exec(compiled, exec_globals) # noqa: S102
except Exception as error: # noqa: BLE001
trace = traceback.TracebackException.from_exception(error)
for frame in trace.stack:
if frame.filename.startswith(" str:
return base_format(language="python", run=_run_python, **kwargs)
markdown-exec-1.8.0/src/markdown_exec/formatters/sh.py 0000664 0000000 0000000 00000001554 14546046442 0023071 0 ustar 00root root 0000000 0000000 """Formatter for executing shell code."""
from __future__ import annotations
import subprocess
from typing import Any
from markdown_exec.formatters.base import ExecutionError, base_format
from markdown_exec.rendering import code_block
def _run_sh(
code: str,
returncode: int | None = None,
session: str | None = None, # noqa: ARG001
id: str | None = None, # noqa: A002,ARG001
**extra: str,
) -> str:
process = subprocess.run(
["sh", "-c", code], # noqa: S603,S607
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
text=True,
check=False,
)
if process.returncode != returncode:
raise ExecutionError(code_block("sh", process.stdout, **extra), process.returncode)
return process.stdout
def _format_sh(**kwargs: Any) -> str:
return base_format(language="sh", run=_run_sh, **kwargs)
markdown-exec-1.8.0/src/markdown_exec/formatters/tree.py 0000664 0000000 0000000 00000003776 14546046442 0023426 0 ustar 00root root 0000000 0000000 """Formatter for file-system trees."""
from __future__ import annotations
from textwrap import dedent
from typing import TYPE_CHECKING, Any
from markdown_exec.rendering import MarkdownConverter, code_block
if TYPE_CHECKING:
from markdown import Markdown
def _rec_build_tree(lines: list[str], parent: list, offset: int, base_indent: int) -> int:
while offset < len(lines):
line = lines[offset]
lstripped = line.lstrip()
indent = len(line) - len(lstripped)
if indent == base_indent:
parent.append((lstripped, []))
offset += 1
elif indent > base_indent:
offset = _rec_build_tree(lines, parent[-1][1], offset, indent)
else:
return offset
return offset
def _build_tree(code: str) -> list[tuple[str, list]]:
lines = dedent(code.strip()).split("\n")
root_layer: list[tuple[str, list]] = []
_rec_build_tree(lines, root_layer, 0, 0)
return root_layer
def _rec_format_tree(tree: list[tuple[str, list]], *, root: bool = True) -> list[str]:
lines = []
n_items = len(tree)
for index, node in enumerate(tree):
last = index == n_items - 1
prefix = "" if root else f"{'└' if last else '├'}── "
if node[1]:
lines.append(f"{prefix}📁 {node[0]}")
sublines = _rec_format_tree(node[1], root=False)
if root:
lines.extend(sublines)
else:
indent_char = " " if last else "│"
lines.extend([f"{indent_char} {line}" for line in sublines])
else:
name = node[0].split()[0]
icon = "📁" if name.endswith("/") else "📄"
lines.append(f"{prefix}{icon} {node[0]}")
return lines
def _format_tree(code: str, md: Markdown, result: str, **options: Any) -> str:
markdown = MarkdownConverter(md)
output = "\n".join(_rec_format_tree(_build_tree(code)))
return markdown.convert(code_block(result or "bash", output, **options.get("extra", {})))
markdown-exec-1.8.0/src/markdown_exec/logger.py 0000664 0000000 0000000 00000004075 14546046442 0021551 0 ustar 00root root 0000000 0000000 """This module contains logging utilities.
We provide the [`patch_loggers`][markdown_exec.logger.patch_loggers]
function so dependant libraries can patch loggers as they see fit.
For example, to fit in the MkDocs logging configuration
and prefix each log message with the module name:
```python
import logging
from markdown_exec.logger import patch_loggers
class LoggerAdapter(logging.LoggerAdapter):
def __init__(self, prefix, logger):
super().__init__(logger, {})
self.prefix = prefix
def process(self, msg, kwargs):
return f"{self.prefix}: {msg}", kwargs
def get_logger(name):
logger = logging.getLogger(f"mkdocs.plugins.{name}")
return LoggerAdapter(name.split(".", 1)[0], logger)
patch_loggers(get_logger)
```
"""
from __future__ import annotations
import logging
from typing import Any, Callable, ClassVar
class _Logger:
_default_logger: Any = logging.getLogger
_instances: ClassVar[dict[str, _Logger]] = {}
def __init__(self, name: str) -> None:
# default logger that can be patched by third-party
self._logger = self.__class__._default_logger(name)
# register instance
self._instances[name] = self
def __getattr__(self, name: str) -> Any:
# forward everything to the logger
return getattr(self._logger, name)
@classmethod
def _patch_loggers(cls, get_logger_func: Callable) -> None:
# patch current instances
for name, instance in cls._instances.items():
instance._logger = get_logger_func(name)
# future instances will be patched as well
cls._default_logger = get_logger_func
def get_logger(name: str) -> _Logger:
"""Create and return a new logger instance.
Parameters:
name: The logger name.
Returns:
The logger.
"""
return _Logger(name)
def patch_loggers(get_logger_func: Callable[[str], Any]) -> None:
"""Patch loggers.
Parameters:
get_logger_func: A function accepting a name as parameter and returning a logger.
"""
_Logger._patch_loggers(get_logger_func)
markdown-exec-1.8.0/src/markdown_exec/mkdocs_plugin.py 0000664 0000000 0000000 00000011135 14546046442 0023123 0 ustar 00root root 0000000 0000000 """This module contains an optional plugin for MkDocs."""
from __future__ import annotations
import logging
import os
from pathlib import Path
from typing import TYPE_CHECKING, Any, MutableMapping
from mkdocs.config import config_options
from mkdocs.config.base import Config
from mkdocs.plugins import BasePlugin
from mkdocs.utils import write_file
from markdown_exec import formatter, formatters, validator
from markdown_exec.logger import patch_loggers
from markdown_exec.rendering import MarkdownConverter, markdown_config
if TYPE_CHECKING:
from jinja2 import Environment
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.structure.files import Files
try:
__import__("pygments_ansi_color")
except ImportError:
ansi_ok = False
else:
ansi_ok = True
class _LoggerAdapter(logging.LoggerAdapter):
def __init__(self, prefix: str, logger: logging.Logger) -> None:
super().__init__(logger, {})
self.prefix = prefix
def process(self, msg: str, kwargs: MutableMapping[str, Any]) -> tuple[str, MutableMapping[str, Any]]:
return f"{self.prefix}: {msg}", kwargs
def _get_logger(name: str) -> _LoggerAdapter:
logger = logging.getLogger(f"mkdocs.plugins.{name}")
return _LoggerAdapter(name.split(".", 1)[0], logger)
patch_loggers(_get_logger)
class MarkdownExecPluginConfig(Config):
"""Configuration of the plugin (for `mkdocs.yml`)."""
ansi = config_options.Choice(("auto", "off", "required", True, False), default="auto")
"""Whether the `ansi` extra is required when installing the package."""
languages = config_options.ListOfItems(
config_options.Choice(formatters.keys()),
default=list(formatters.keys()),
)
"""Which languages to enabled the extension for."""
class MarkdownExecPlugin(BasePlugin[MarkdownExecPluginConfig]):
"""MkDocs plugin to easily enable custom fences for code blocks execution."""
def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
"""Configure the plugin.
Hook for the [`on_config` event](https://www.mkdocs.org/user-guide/plugins/#on_config).
In this hook, we add custom fences for all the supported languages.
We also save the Markdown extensions configuration
into [`markdown_config`][markdown_exec.rendering.markdown_config].
Arguments:
config: The MkDocs config object.
Returns:
The modified config.
"""
self.mkdocs_config_dir = os.getenv("MKDOCS_CONFIG_DIR")
os.environ["MKDOCS_CONFIG_DIR"] = os.path.dirname(config["config_file_path"])
self.languages = self.config.languages
mdx_configs = config.setdefault("mdx_configs", {})
superfences = mdx_configs.setdefault("pymdownx.superfences", {})
custom_fences = superfences.setdefault("custom_fences", [])
for language in self.languages:
custom_fences.append(
{
"name": language,
"class": language,
"validator": validator,
"format": formatter,
},
)
markdown_config.save(config.markdown_extensions, config.mdx_configs)
return config
def on_env( # noqa: D102
self,
env: Environment,
*,
config: MkDocsConfig,
files: Files, # noqa: ARG002
) -> Environment | None:
if self.config.ansi in ("required", True) or (self.config.ansi == "auto" and ansi_ok):
self._add_css(config, "ansi.css")
if "pyodide" in self.languages:
self._add_css(config, "pyodide.css")
self._add_js(config, "pyodide.js")
return env
def on_post_build(self, *, config: MkDocsConfig) -> None: # noqa: ARG002,D102
MarkdownConverter.counter = 0
markdown_config.reset()
if self.mkdocs_config_dir is None:
os.environ.pop("MKDOCS_CONFIG_DIR", None)
else:
os.environ["MKDOCS_CONFIG_DIR"] = self.mkdocs_config_dir
def _add_asset(self, config: MkDocsConfig, asset_file: str, asset_type: str) -> None:
asset_filename = f"assets/_markdown_exec_{asset_file}"
asset_content = Path(__file__).parent.joinpath(asset_file).read_text()
write_file(asset_content.encode("utf-8"), os.path.join(config.site_dir, asset_filename))
config[f"extra_{asset_type}"].insert(0, asset_filename)
def _add_css(self, config: MkDocsConfig, css_file: str) -> None:
self._add_asset(config, css_file, "css")
def _add_js(self, config: MkDocsConfig, js_file: str) -> None:
self._add_asset(config, js_file, "javascript")
markdown-exec-1.8.0/src/markdown_exec/processors.py 0000664 0000000 0000000 00000010303 14546046442 0022463 0 ustar 00root root 0000000 0000000 """This module contains a Markdown extension allowing to integrate generated headings into the ToC."""
from __future__ import annotations
import copy
import re
from typing import TYPE_CHECKING
from xml.etree.ElementTree import Element
from markdown.treeprocessors import Treeprocessor
from markdown.util import HTML_PLACEHOLDER_RE
if TYPE_CHECKING:
from markdown import Markdown
from markupsafe import Markup
# code taken from mkdocstrings, credits to @oprypin
class IdPrependingTreeprocessor(Treeprocessor):
"""Prepend the configured prefix to IDs of all HTML elements."""
name = "markdown_exec_ids"
def __init__(self, md: Markdown, id_prefix: str) -> None: # noqa: D107
super().__init__(md)
self.id_prefix = id_prefix
def run(self, root: Element) -> None: # noqa: D102
if not self.id_prefix:
return
for el in root.iter():
id_attr = el.get("id")
if id_attr:
el.set("id", self.id_prefix + id_attr)
href_attr = el.get("href")
if href_attr and href_attr.startswith("#"):
el.set("href", "#" + self.id_prefix + href_attr[1:])
name_attr = el.get("name")
if name_attr:
el.set("name", self.id_prefix + name_attr)
if el.tag == "label":
for_attr = el.get("for")
if for_attr:
el.set("for", self.id_prefix + for_attr)
# code taken from mkdocstrings, credits to @oprypin
class HeadingReportingTreeprocessor(Treeprocessor):
"""Records the heading elements encountered in the document."""
name = "markdown_exec_record_headings"
regex = re.compile("[Hh][1-6]")
def __init__(self, md: Markdown, headings: list[Element]): # noqa: D107
super().__init__(md)
self.headings = headings
def run(self, root: Element) -> None: # noqa: D102
for el in root.iter():
if self.regex.fullmatch(el.tag):
el = copy.copy(el) # noqa: PLW2901
# 'toc' extension's first pass (which we require to build heading stubs/ids) also edits the HTML.
# Undo the permalink edit so we can pass this heading to the outer pass of the 'toc' extension.
if len(el) > 0 and el[-1].get("class") == self.md.treeprocessors["toc"].permalink_class: # type: ignore[attr-defined]
del el[-1]
self.headings.append(el)
class InsertHeadings(Treeprocessor):
"""Our headings insertor."""
name = "markdown_exec_insert_headings"
def __init__(self, md: Markdown):
"""Initialize the object.
Arguments:
md: A `markdown.Markdown` instance.
"""
super().__init__(md)
self.headings: dict[Markup, list[Element]] = {}
def run(self, root: Element) -> None: # noqa: D102 (ignore missing docstring)
if not self.headings:
return
for el in root.iter():
match = HTML_PLACEHOLDER_RE.match(el.text or "")
if match:
counter = int(match.group(1))
markup: Markup = self.md.htmlStash.rawHtmlBlocks[counter] # type: ignore[assignment]
if markup in self.headings:
div = Element("div", {"class": "markdown-exec"})
div.extend(self.headings[markup])
el.append(div)
class RemoveHeadings(Treeprocessor):
"""Our headings remover."""
name = "markdown_exec_remove_headings"
def run(self, root: Element) -> None: # noqa: D102
carry_text = ""
for el in reversed(root): # Reversed mainly for the ability to mutate during iteration.
for subel in reversed(el):
if subel.tag == "div" and subel.get("class") == "markdown-exec":
# Delete the duplicated headings along with their container, but keep the text (i.e. the actual HTML).
carry_text = (subel.text or "") + carry_text
el.remove(subel)
elif carry_text:
subel.tail = (subel.tail or "") + carry_text
carry_text = ""
if carry_text:
el.text = (el.text or "") + carry_text
markdown-exec-1.8.0/src/markdown_exec/py.typed 0000664 0000000 0000000 00000000000 14546046442 0021377 0 ustar 00root root 0000000 0000000 markdown-exec-1.8.0/src/markdown_exec/pyodide.css 0000664 0000000 0000000 00000001521 14546046442 0022060 0 ustar 00root root 0000000 0000000 html[data-theme="light"] {
@import "https://cdn.jsdelivr.net/npm/highlightjs-themes@1.0.0/tomorrow.css"
}
html[data-theme="dark"] {
@import "https://cdn.jsdelivr.net/npm/highlightjs-themes@1.0.0/tomorrow-night-blue.min.css"
}
.ace_gutter {
z-index: 1;
}
.pyodide-editor {
width: 100%;
min-height: 200px;
max-height: 400px;
font-size: .85em;
}
.pyodide-editor-bar {
color: var(--md-primary-bg-color);
background-color: var(--md-primary-fg-color);
width: 100%;
font: monospace;
font-size: 0.75em;
padding: 2px 0 2px;
}
.pyodide-bar-item {
padding: 0 18px 0;
display: inline-block;
width: 50%;
}
.pyodide pre {
margin: 0;
}
.pyodide-output {
width: 100%;
margin-bottom: -15px;
max-height: 400px
}
.pyodide-clickable {
cursor: pointer;
text-align: right;
} markdown-exec-1.8.0/src/markdown_exec/pyodide.js 0000664 0000000 0000000 00000007405 14546046442 0021713 0 ustar 00root root 0000000 0000000 var _sessions = {};
function getSession(name, pyodide) {
if (!(name in _sessions)) {
_sessions[name] = pyodide.globals.get("dict")();
}
return _sessions[name];
}
function writeOutput(element, string) {
element.innerHTML += string + '\n';
}
function clearOutput(element) {
element.innerHTML = '';
}
async function evaluatePython(pyodide, editor, output, session) {
pyodide.setStdout({ batched: (string) => { writeOutput(output, string); } });
let result, code = editor.getValue();
clearOutput(output);
try {
result = await pyodide.runPythonAsync(code, { globals: getSession(session, pyodide) });
} catch (error) {
writeOutput(output, error);
}
if (result) writeOutput(output, result);
hljs.highlightElement(output);
}
async function initPyodide() {
try {
let pyodide = await loadPyodide();
await pyodide.loadPackage("micropip");
return pyodide;
} catch(error) {
return null;
}
}
function getTheme() {
return document.body.getAttribute('data-md-color-scheme');
}
function setTheme(editor, currentTheme, light, dark) {
// https://gist.github.com/RyanNutt/cb8d60997d97905f0b2aea6c3b5c8ee0
if (currentTheme === "default") {
editor.setTheme("ace/theme/" + light);
document.querySelector(`link[title="light"]`).removeAttribute("disabled");
document.querySelector(`link[title="dark"]`).setAttribute("disabled", "disabled");
} else if (currentTheme === "slate") {
editor.setTheme("ace/theme/" + dark);
document.querySelector(`link[title="dark"]`).removeAttribute("disabled");
document.querySelector(`link[title="light"]`).setAttribute("disabled", "disabled");
}
}
function updateTheme(editor, light, dark) {
// Create a new MutationObserver instance
const observer = new MutationObserver((mutations) => {
// Loop through the mutations that occurred
mutations.forEach((mutation) => {
// Check if the mutation was a change to the data-md-color-scheme attribute
if (mutation.attributeName === 'data-md-color-scheme') {
// Get the new value of the attribute
const newColorScheme = mutation.target.getAttribute('data-md-color-scheme');
// Update the editor theme
setTheme(editor, newColorScheme, light, dark);
}
});
});
// Configure the observer to watch for changes to the data-md-color-scheme attribute
observer.observe(document.body, {
attributes: true,
attributeFilter: ['data-md-color-scheme'],
});
}
async function setupPyodide(idPrefix, install = null, themeLight = 'tomorrow', themeDark = 'tomorrow_night', session = null) {
const editor = ace.edit(idPrefix + "editor");
const run = document.getElementById(idPrefix + "run");
const clear = document.getElementById(idPrefix + "clear");
const output = document.getElementById(idPrefix + "output");
updateTheme(editor, themeLight, themeDark);
editor.session.setMode("ace/mode/python");
setTheme(editor, getTheme(), themeLight, themeDark);
writeOutput(output, "Initializing...");
let pyodide = await pyodidePromise;
if (install && install.length) {
micropip = pyodide.pyimport("micropip");
for (const package of install)
await micropip.install(package);
}
clearOutput(output);
run.onclick = () => evaluatePython(pyodide, editor, output, session);
clear.onclick = () => clearOutput(output);
output.parentElement.parentElement.addEventListener("keydown", (event) => {
if (event.ctrlKey && event.key.toLowerCase() === 'enter') {
event.preventDefault();
run.click();
}
});
}
var pyodidePromise = initPyodide();
markdown-exec-1.8.0/src/markdown_exec/rendering.py 0000664 0000000 0000000 00000022363 14546046442 0022247 0 ustar 00root root 0000000 0000000 """Markdown extensions and helpers."""
from __future__ import annotations
from contextlib import contextmanager
from functools import lru_cache
from textwrap import indent
from typing import TYPE_CHECKING, Any, Iterator
from markdown import Markdown
from markupsafe import Markup
from markdown_exec.processors import (
HeadingReportingTreeprocessor,
IdPrependingTreeprocessor,
InsertHeadings,
RemoveHeadings,
)
if TYPE_CHECKING:
from xml.etree.ElementTree import Element
from markdown import Extension
def code_block(language: str, code: str, **options: str) -> str:
"""Format code as a code block.
Parameters:
language: The code block language.
code: The source code to format.
**options: Additional options passed from the source, to add back to the generated code block.
Returns:
The formatted code block.
"""
opts = " ".join(f'{opt_name}="{opt_value}"' for opt_name, opt_value in options.items())
return f"````````{language} {opts}\n{code}\n````````"
def tabbed(*tabs: tuple[str, str]) -> str:
"""Format tabs using `pymdownx.tabbed` extension.
Parameters:
*tabs: Tuples of strings: title and text.
Returns:
The formatted tabs.
"""
parts = []
for title, text in tabs:
title = title.replace(r"\|", "|").strip() # noqa: PLW2901
parts.append(f'=== "{title}"')
parts.append(indent(text, prefix=" " * 4))
parts.append("")
return "\n".join(parts)
def _hide_lines(source: str) -> str:
return "\n".join(line for line in source.split("\n") if "markdown-exec: hide" not in line).strip()
def add_source(
*,
source: str,
location: str,
output: str,
language: str,
tabs: tuple[str, str],
result: str = "",
**extra: str,
) -> str:
"""Add source code block to the output.
Parameters:
source: The source code block.
location: Where to add the source (above, below, tabbed-left, tabbed-right, console).
output: The current output.
language: The code language.
tabs: Tabs titles (if used).
result: Syntax to use when concatenating source and result with "console" location.
**extra: Extra options added back to source code block.
Raises:
ValueError: When the given location is not supported.
Returns:
The updated output.
"""
source = _hide_lines(source)
if location == "console":
return code_block(result or language, source + "\n" + output, **extra)
source_block = code_block(language, source, **extra)
if location == "above":
return source_block + "\n\n" + output
if location == "below":
return output + "\n\n" + source_block
if location == "material-block":
return source_block + f'\n\n\n\n{output}\n\n'
source_tab_title, result_tab_title = tabs
if location == "tabbed-left":
return tabbed((source_tab_title, source_block), (result_tab_title, output))
if location == "tabbed-right":
return tabbed((result_tab_title, output), (source_tab_title, source_block))
raise ValueError(f"unsupported location for sources: {location}")
class MarkdownConfig:
"""This class returns a singleton used to store Markdown extensions configuration.
You don't have to instantiate the singleton yourself:
we provide it as [`markdown_config`][markdown_exec.rendering.markdown_config].
"""
_singleton: MarkdownConfig | None = None
def __new__(cls) -> MarkdownConfig: # noqa: D102,PYI034
if cls._singleton is None:
cls._singleton = super().__new__(cls)
return cls._singleton
def __init__(self) -> None: # noqa: D107
self.exts: list[str] | None = None
self.exts_config: dict[str, dict[str, Any]] | None = None
def save(self, exts: list[str], exts_config: dict[str, dict[str, Any]]) -> None:
"""Save Markdown extensions and their configuration.
Parameters:
exts: The Markdown extensions.
exts_config: The extensions configuration.
"""
self.exts = exts
self.exts_config = exts_config
def reset(self) -> None:
"""Reset Markdown extensions and their configuration."""
self.exts = None
self.exts_config = None
markdown_config = MarkdownConfig()
"""This object can be used to save the configuration of your Markdown extensions.
For example, since we provide a MkDocs plugin, we use it to store the configuration
that was read from `mkdocs.yml`:
```python
from markdown_exec.rendering import markdown_config
# ...in relevant events/hooks, access and modify extensions and their configs, then:
markdown_config.save(extensions, extensions_config)
```
See the actual event hook: [`on_config`][markdown_exec.mkdocs_plugin.MarkdownExecPlugin.on_config].
See the [`save`][markdown_exec.rendering.MarkdownConfig.save]
and [`reset`][markdown_exec.rendering.MarkdownConfig.reset] methods.
Without it, Markdown Exec will rely on the `registeredExtensions` attribute
of the original Markdown instance, which does not forward everything
that was configured, notably extensions like `tables`. Other extensions
such as `attr_list` are visible, but fail to register properly when
reusing their instances. It means that the rendered HTML might differ
from what you expect (tables not rendered, attribute lists not injected,
emojis not working, etc.).
"""
# FIXME: When a heading contains an XML entity such as —,
# the entity is stashed and replaced with a placeholder.
# The heading therefore contains this placeholder.
# When reporting the heading to the upper conversion layer (for the ToC),
# the placeholder gets unstashed using the upper Markdown instance
# instead of the neste one. If the upper instance doesn't know the placeholder,
# nothing happens. But if it knows it, we then get a heading with garbabe/previous
# contents within it, messing up the ToC.
# We should fix this somehow. In the meantime, the workaround is to avoid
# XML entities that get stashed in headings.
@lru_cache(maxsize=None)
def _register_headings_processors(md: Markdown) -> None:
md.treeprocessors.register(
InsertHeadings(md),
InsertHeadings.name,
priority=75, # right before markdown.blockprocessors.HashHeaderProcessor
)
md.treeprocessors.register(
RemoveHeadings(md),
RemoveHeadings.name,
priority=4, # right after toc
)
def _mimic(md: Markdown, headings: list[Element], *, update_toc: bool = True) -> Markdown:
new_md = Markdown()
extensions: list[Extension | str] = markdown_config.exts or md.registeredExtensions # type: ignore[assignment]
extensions_config: dict[str, dict[str, Any]] = markdown_config.exts_config or {}
new_md.registerExtensions(extensions, extensions_config)
new_md.treeprocessors.register(
IdPrependingTreeprocessor(md, ""),
IdPrependingTreeprocessor.name,
priority=4, # right after 'toc' (needed because that extension adds ids to headings)
)
new_md._original_md = md # type: ignore[attr-defined]
if update_toc:
_register_headings_processors(md)
new_md.treeprocessors.register(
HeadingReportingTreeprocessor(new_md, headings),
HeadingReportingTreeprocessor.name,
priority=1, # Close to the end.
)
return new_md
@contextmanager
def _id_prefix(md: Markdown, prefix: str | None) -> Iterator[None]:
MarkdownConverter.counter += 1
id_prepending_processor = md.treeprocessors[IdPrependingTreeprocessor.name]
id_prepending_processor.id_prefix = prefix if prefix is not None else f"exec-{MarkdownConverter.counter}--" # type: ignore[attr-defined]
try:
yield
finally:
id_prepending_processor.id_prefix = "" # type: ignore[attr-defined]
class MarkdownConverter:
"""Helper class to avoid breaking the original Markdown instance state."""
counter: int = 0
def __init__(self, md: Markdown, *, update_toc: bool = True) -> None: # noqa: D107
self._md_ref: Markdown = md
self._headings: list[Element] = []
self._update_toc = update_toc
@property
def _original_md(self) -> Markdown:
return getattr(self._md_ref, "_original_md", self._md_ref)
def _report_headings(self, markup: Markup) -> None:
self._original_md.treeprocessors[InsertHeadings.name].headings[markup] = self._headings # type: ignore[attr-defined]
self._headings = []
def convert(self, text: str, stash: dict[str, str] | None = None, id_prefix: str | None = None) -> Markup:
"""Convert Markdown text to safe HTML.
Parameters:
text: Markdown text.
stash: An HTML stash.
Returns:
Safe HTML.
"""
md = _mimic(self._original_md, self._headings, update_toc=self._update_toc)
# convert markdown to html
with _id_prefix(md, id_prefix):
converted = md.convert(text)
# restore html from stash
for placeholder, stashed in (stash or {}).items():
converted = converted.replace(placeholder, stashed)
markup = Markup(converted)
# pass headings to upstream conversion layer
if self._update_toc:
self._report_headings(markup)
return markup
markdown-exec-1.8.0/tests/ 0000775 0000000 0000000 00000000000 14546046442 0015437 5 ustar 00root root 0000000 0000000 markdown-exec-1.8.0/tests/__init__.py 0000664 0000000 0000000 00000000246 14546046442 0017552 0 ustar 00root root 0000000 0000000 """Tests suite for `markdown_exec`."""
from pathlib import Path
TESTS_DIR = Path(__file__).parent
TMP_DIR = TESTS_DIR / "tmp"
FIXTURES_DIR = TESTS_DIR / "fixtures"
markdown-exec-1.8.0/tests/conftest.py 0000664 0000000 0000000 00000001173 14546046442 0017640 0 ustar 00root root 0000000 0000000 """Configuration for the pytest test suite."""
import pytest
from markdown import Markdown
from markdown_exec import formatter, formatters, validator
@pytest.fixture()
def md() -> Markdown:
"""Return a Markdown instance.
Returns:
Markdown instance.
"""
fences = [
{
"name": language,
"class": language,
"validator": validator,
"format": formatter,
}
for language in formatters
]
return Markdown(
extensions=["pymdownx.superfences"],
extension_configs={"pymdownx.superfences": {"custom_fences": fences}},
)
markdown-exec-1.8.0/tests/test_base_formatter.py 0000664 0000000 0000000 00000002643 14546046442 0022052 0 ustar 00root root 0000000 0000000 """Tests for the base formatter."""
import pytest
from markdown import Markdown
from markdown_exec.formatters.base import base_format
def test_no_p_around_html(md: Markdown) -> None:
"""Assert HTML isn't wrapped in a `p` tag.
Parameters:
md: A Markdown instance (fixture).
"""
code = "hello
"
html = base_format(
language="whatever",
run=lambda code, **_: code,
code=code,
md=md,
html=True,
)
assert html == code
@pytest.mark.parametrize("html", [True, False])
def test_render_source(md: Markdown, html: bool) -> None:
"""Assert source is rendered.
Parameters:
md: A Markdown instance (fixture).
html: Whether output is HTML or not.
"""
markup = base_format(
language="python",
run=lambda code, **_: code,
code="hello",
md=md,
html=html,
source="tabbed-left",
)
assert "Source" in markup
def test_render_console_plus_ansi_result(md: Markdown) -> None:
"""Assert we can render source as console style with `ansi` highlight.
Parameters:
md: A Markdown instance (fixture).
"""
markup = base_format(
language="bash",
run=lambda code, **_: code,
code="echo -e '\033[31mhello'",
md=md,
html=False,
source="console",
result="ansi",
)
assert "ansi" in markup
markdown-exec-1.8.0/tests/test_converter.py 0000664 0000000 0000000 00000004040 14546046442 0021055 0 ustar 00root root 0000000 0000000 """Tests for the Markdown converter."""
from __future__ import annotations
import re
from textwrap import dedent
from typing import TYPE_CHECKING
import pytest
from markdown.extensions.toc import TocExtension
from markdown_exec.rendering import MarkdownConfig, markdown_config
if TYPE_CHECKING:
from markdown import Markdown
def test_rendering_nested_blocks(md: Markdown) -> None:
"""Assert nested blocks are properly handled.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
````md exec="1"
```python exec="1"
print("**Bold!**")
```
````
""",
),
)
assert html == "Bold!
"
def test_instantiating_config_singleton() -> None:
"""Assert that the Markdown config instances act as a singleton."""
assert MarkdownConfig() is markdown_config
markdown_config.save([], {})
markdown_config.reset()
@pytest.mark.parametrize(
("id", "id_prefix", "expected"),
[
("", None, 'id="exec-\\d+--heading"'),
("", "", 'id="heading"'),
("", "some-prefix-", 'id="some-prefix-heading"'),
("some-id", None, 'id="some-id-heading"'),
("some-id", "", 'id="heading"'),
("some-id", "some-prefix-", 'id="some-prefix-heading"'),
],
)
def test_prefixing_headings(md: Markdown, id: str, id_prefix: str | None, expected: str) -> None: # noqa: A002
"""Assert that we prefix headings as specified.
Parameters:
md: A Markdown instance (fixture).
id: The code block id.
id_prefix: The code block id prefix.
expected: The id we expect to find in the HTML.
"""
TocExtension().extendMarkdown(md)
prefix = f'idprefix="{id_prefix}"' if id_prefix is not None else ""
html = md.convert(
dedent(
f"""
```python exec="1" id="{id}" {prefix}
print("# HEADING")
```
""",
),
)
assert re.search(expected, html)
markdown-exec-1.8.0/tests/test_python.py 0000664 0000000 0000000 00000010361 14546046442 0020372 0 ustar 00root root 0000000 0000000 """Tests for the Python formatters."""
from __future__ import annotations
from textwrap import dedent
from typing import TYPE_CHECKING
if TYPE_CHECKING:
import pytest
from markdown import Markdown
def test_output_markdown(md: Markdown) -> None:
"""Assert Markdown is converted to HTML.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```python exec="yes"
print("**Bold!**")
```
""",
),
)
assert html == "Bold!
"
def test_output_html(md: Markdown) -> None:
"""Assert HTML is injected as is.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```python exec="yes" html="yes"
print("**Bold!**")
```
""",
),
)
assert html == "**Bold!**\n
"
def test_error_raised(md: Markdown, caplog: pytest.LogCaptureFixture) -> None:
"""Assert errors properly log a warning and return a formatted traceback.
Parameters:
md: A Markdown instance (fixture).
caplog: Pytest fixture to capture logs.
"""
html = md.convert(
dedent(
"""
```python exec="yes"
raise ValueError("oh no!")
```
""",
),
)
assert "Traceback" in html
assert "ValueError" in html
assert "oh no!" in html
assert "Execution of python code block exited with errors" in caplog.text
def test_can_print_non_string_objects(md: Markdown) -> None:
"""Assert we can print non-string objects.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```python exec="yes"
class NonString:
def __str__(self):
return "string"
nonstring = NonString()
print(nonstring, nonstring)
```
""",
),
)
assert "Traceback" not in html
def test_sessions(md: Markdown) -> None:
"""Assert sessions can be reused.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```python exec="1" session="a"
a = 1
```
```pycon exec="1" session="b"
>>> b = 2
```
```pycon exec="1" session="a"
>>> print(f"a = {a}")
>>> try:
... print(b)
... except NameError:
... print("ok")
... else:
... print("ko")
```
```python exec="1" session="b"
print(f"b = {b}")
try:
print(a)
except NameError:
print("ok")
else:
print("ko")
```
""",
),
)
assert "a = 1" in html
assert "b = 2" in html
assert "ok" in html
assert "ko" not in html
def test_reporting_errors_in_sessions(md: Markdown, caplog: pytest.LogCaptureFixture) -> None:
"""Assert errors and source lines are correctly reported across sessions.
Parameters:
md: A Markdown instance (fixture).
caplog: Pytest fixture to capture logs.
"""
html = md.convert(
dedent(
"""
```python exec="1" session="a"
def fraise():
raise RuntimeError("strawberry")
```
```python exec="1" session="a"
print("hello")
fraise()
```
""",
),
)
assert "Traceback" in html
assert "strawberry" in html
assert "fraise()" in caplog.text
assert 'raise RuntimeError("strawberry")' in caplog.text
def test_removing_output_from_pycon_code(md: Markdown) -> None:
"""Assert output lines are removed from pycon snippets.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```pycon exec="1" source="console"
>>> print("ok")
ko
```
""",
),
)
assert "ok" in html
assert "ko" not in html
markdown-exec-1.8.0/tests/test_shell.py 0000664 0000000 0000000 00000003753 14546046442 0020167 0 ustar 00root root 0000000 0000000 """Tests for the shell formatters."""
from __future__ import annotations
from textwrap import dedent
from typing import TYPE_CHECKING
if TYPE_CHECKING:
import pytest
from markdown import Markdown
def test_output_markdown(md: Markdown) -> None:
"""Assert Markdown is converted to HTML.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```sh exec="yes"
echo "**Bold!**"
```
""",
),
)
assert html == "Bold!
"
def test_output_html(md: Markdown) -> None:
"""Assert HTML is injected as is.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```sh exec="yes" html="yes"
echo "**Bold!**"
```
""",
),
)
assert html == "**Bold!**\n
"
def test_error_raised(md: Markdown, caplog: pytest.LogCaptureFixture) -> None:
"""Assert errors properly log a warning and return a formatted traceback.
Parameters:
md: A Markdown instance (fixture).
caplog: Pytest fixture to capture logs.
"""
html = md.convert(
dedent(
"""
```sh exec="yes"
echo("wrong syntax")
```
""",
),
)
assert "error" in html
assert "Execution of sh code block exited with unexpected code 2" in caplog.text
def test_return_code(md: Markdown, caplog: pytest.LogCaptureFixture) -> None:
"""Assert return code is used correctly.
Parameters:
md: A Markdown instance (fixture).
caplog: Pytest fixture to capture logs.
"""
html = md.convert(
dedent(
"""
```sh exec="yes" returncode="1"
echo Not in the mood
exit 1
```
""",
),
)
assert "Not in the mood" in html
assert "exited with" not in caplog.text
markdown-exec-1.8.0/tests/test_toc.py 0000664 0000000 0000000 00000004437 14546046442 0017645 0 ustar 00root root 0000000 0000000 """Tests for the logic updating the table of contents."""
from __future__ import annotations
from textwrap import dedent
from typing import TYPE_CHECKING
from markdown.extensions.toc import TocExtension
if TYPE_CHECKING:
from markdown import Markdown
def test_updating_toc(md: Markdown) -> None:
"""Assert ToC is updated with generated headings.
Parameters:
md: A Markdown instance (fixture).
"""
TocExtension().extendMarkdown(md)
html = md.convert(
dedent(
"""
```python exec="yes"
print("# big heading")
```
""",
),
)
assert " None:
"""Assert ToC is not updated with generated headings.
Parameters:
md: A Markdown instance (fixture).
"""
TocExtension().extendMarkdown(md)
html = md.convert(
dedent(
"""
```python exec="yes" updatetoc="no"
print("# big heading")
```
""",
),
)
assert " None:
"""Assert ToC is not updated with generated headings.
Parameters:
md: A Markdown instance (fixture).
"""
TocExtension().extendMarkdown(md)
html = md.convert(
dedent(
"""
```python exec="yes" updatetoc="no"
print("# big heading")
```
```python exec="yes" updatetoc="yes"
print("## medium heading")
```
```python exec="yes" updatetoc="no"
print("### small heading")
```
```python exec="yes" updatetoc="yes"
print("#### tiny heading")
```
""",
),
)
assert " None:
"""Assert we can highlight lines in the output.
Parameters:
md: A Markdown instance (fixture).
"""
html = md.convert(
dedent(
"""
```tree hl_lines="2"
1
2
3
```
""",
),
)
assert '' in html
markdown-exec-1.8.0/tests/test_validator.py 0000664 0000000 0000000 00000001743 14546046442 0021042 0 ustar 00root root 0000000 0000000 """Tests for the `validator` function."""
import pytest
from markdown.core import Markdown
from markdown_exec import validator
@pytest.mark.parametrize(
("exec_value", "expected"),
[
("yes", True),
("YES", True),
("on", True),
("ON", True),
("whynot", True),
("true", True),
("TRUE", True),
("1", True),
("-1", True),
("0", False),
("no", False),
("NO", False),
("off", False),
("OFF", False),
("false", False),
("FALSE", False),
],
)
def test_validate(md: Markdown, exec_value: str, expected: bool) -> None:
"""Assert the validator returns True or False given inputs.
Parameters:
md: A Markdown instance.
exec_value: The exec option value, passed from the code block.
expected: Expected validation result.
"""
assert validator("whatever", inputs={"exec": exec_value}, options={}, attrs={}, md=md) is expected