feat: Allow changing working directory for code blocks execution

Issue-20: #20

docs/usage/index.md

@@ -28,6 +28,7 @@ linking to their related documentation:
 - [`session`](#sessions): Execute code blocks within a named session, reusing previously defined variables, etc..
 - [`source`](#render-the-source-code-as-well): Render the source as well as the output.
 - [`tabs`](#change-the-titles-of-tabs): When rendering the source using tabs, choose the tabs titles.
+- [`workdir`](#change-the-working-directory): Change the working directory.
 - [`title`](#additional-options): Title is a [Material for MkDocs][material] option.
 - [`updatetoc`](#generated-headings-in-table-of-contents): Whether to update the Table of Contents with generated headings.
 
@@ -264,6 +265,20 @@ $ cat .git/config
 WARNING: **Limitation**  
 Wrapping the result is not possible when HTML output is enabled.
 
+## Change the working directory
+
+To change the working directory for the execution of a code block, use the `workdir` option.
+
+````md exec="1" source="tabbed-left"
+```bash exec="1"
+pwd
+```
+
+```bash exec="1" workdir=".."
+pwd
+```
+````
+
 ## Additional options
 
 If you are using [Material for MkDocs][material],

src/markdown_exec/__init__.py

@@ -76,6 +76,7 @@ def validator(
     update_toc_value = _to_bool(inputs.pop("updatetoc", "yes"))
     tabs_value = inputs.pop("tabs", "|".join(default_tabs))
     tabs = tuple(_tabs_re.split(tabs_value, maxsplit=1))
+    workdir_value = inputs.pop("workdir", None)
     options["id"] = id_value
     options["id_prefix"] = id_prefix_value
     options["html"] = html_value
@@ -85,6 +86,7 @@ def validator(
     options["session"] = session_value
     options["update_toc"] = update_toc_value
     options["tabs"] = tabs
+    options["workdir"] = workdir_value
     options["extra"] = inputs
     return True
 

src/markdown_exec/formatters/base.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+import os
+from contextlib import contextmanager
 from textwrap import indent
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any, Callable, Iterator
 from uuid import uuid4
 
 from markupsafe import Markup
@@ -18,6 +20,24 @@
 default_tabs = ("Source", "Result")
 
 
+@contextmanager
+def working_directory(path: str | None = None) -> Iterator[None]:
+    """Change the working directory for the duration of the context.
+
+    Parameters:
+        path: The path to change the working directory to.
+    """
+    if path:
+        old_cwd = os.getcwd()
+        os.chdir(path)
+        try:
+            yield
+        finally:
+            os.chdir(old_cwd)
+    else:
+        yield
+
+
 class ExecutionError(Exception):
     """Exception raised for errors during execution of a code block.
 
@@ -55,6 +75,7 @@ def base_format(
     transform_source: Callable[[str], tuple[str, str]] | None = None,
     session: str | None = None,
     update_toc: bool = True,
+    workdir: str | None = None,
     **options: Any,
 ) -> Markup:
     """Execute code and return HTML.
@@ -77,6 +98,7 @@ def base_format(
         session: A session name, to persist state between executed code blocks.
         update_toc: Whether to include generated headings
             into the Markdown table of contents (toc extension).
+        workdir: The working directory to use for the execution.
         **options: Additional options passed from the formatter.
 
     Returns:
@@ -92,7 +114,8 @@ def base_format(
         source_output = code
 
     try:
-        output = run(source_input, returncode=returncode, session=session, id=id, **extra)
+        with working_directory(workdir):
+            output = run(source_input, returncode=returncode, session=session, id=id, **extra)
     except ExecutionError as error:
         identifier = id or extra.get("title", "")
         identifier = identifier and f"'{identifier}' "

tests/test_base_formatter.py

@@ -1,5 +1,7 @@
 """Tests for the base formatter."""
 
+import subprocess
+
 import pytest
 from markdown import Markdown
 
@@ -73,3 +75,19 @@ def test_dont_render_anything_if_output_is_empty(md: Markdown) -> None:
         md=md,
     )
     assert not markup
+
+
+def test_changing_working_directory(md: Markdown) -> None:
+    """Assert we can change the working directory with `workdir`.
+
+    Parameters:
+        md: A Markdown instance (fixture).
+    """
+    markup = base_format(
+        language="python",
+        run=lambda code, **_: subprocess.check_output(code, shell=True, text=True),  # noqa: S602
+        code="pwd",
+        md=md,
+        workdir="/",
+    )
+    assert markup == "<p>/</p>"