sphinx-examples-as-code 0.8.3__tar.gz → 0.9.0__tar.gz

{sphinx_examples_as_code-0.8.3 → sphinx_examples_as_code-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.8.3
+Version: 0.9.0
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -159,7 +159,15 @@ Imports are read from the code, not run. Each imported top-level module maps to
 project that provides it in the environment building the docs; standard-library
 modules, relative imports and modules no single installed project provides are left
 out. Projects the code needs but never imports, such as an optional backend, go in
-`dependencies`. In Python scripts and Jupyter notebooks, a dependency with no version or extras of
+`dependencies`, or for a single page in an `examples-as-code-dependencies` directive anywhere on it.
+It takes PEP 508 requirements separated by spaces or commas, adds them to every download from
+that page, and renders nothing:
+
+```rst
+.. examples-as-code-dependencies:: sympy imageio-ffmpeg>=0.4
+```
+
+In a Sphinx-Gallery example, put it in the example's docstring. In Python scripts and Jupyter notebooks, a dependency with no version or extras of
 its own is left out when another listed one already installs it on every platform, e.g. `numpy`
 next to `pyvista`. marimo notebooks list every dependency, since marimo's sandbox adds back any
 it does not find by name.

{sphinx_examples_as_code-0.8.3 → sphinx_examples_as_code-0.9.0}/README.md

@@ -128,7 +128,15 @@ Imports are read from the code, not run. Each imported top-level module maps to
 project that provides it in the environment building the docs; standard-library
 modules, relative imports and modules no single installed project provides are left
 out. Projects the code needs but never imports, such as an optional backend, go in
-`dependencies`. In Python scripts and Jupyter notebooks, a dependency with no version or extras of
+`dependencies`, or for a single page in an `examples-as-code-dependencies` directive anywhere on it.
+It takes PEP 508 requirements separated by spaces or commas, adds them to every download from
+that page, and renders nothing:
+
+```rst
+.. examples-as-code-dependencies:: sympy imageio-ffmpeg>=0.4
+```
+
+In a Sphinx-Gallery example, put it in the example's docstring. In Python scripts and Jupyter notebooks, a dependency with no version or extras of
 its own is left out when another listed one already installs it on every platform, e.g. `numpy`
 next to `pyvista`. marimo notebooks list every dependency, since marimo's sandbox adds back any
 it does not find by name.

{sphinx_examples_as_code-0.8.3 → sphinx_examples_as_code-0.9.0}/sphinx_examples_as_code/__init__.py

@@ -23,6 +23,7 @@ from urllib.parse import urlsplit
 
 from docutils import nodes
 from docutils.core import publish_doctree
+from packaging.requirements import InvalidRequirement
 from packaging.requirements import Requirement
 from packaging.specifiers import InvalidSpecifier
 from packaging.specifiers import SpecifierSet
@@ -32,6 +33,7 @@ from packaging.version import Version
 from sphinx import addnodes
 from sphinx.errors import ConfigError
 from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
 
 from ._version import __version__
 
@@ -42,6 +44,7 @@ if TYPE_CHECKING:
 
     from sphinx.application import Sphinx
     from sphinx.config import Config
+    from sphinx.environment import BuildEnvironment
 
 # Node types marking the start of another section - bound the end of an
 # Examples span. Includes desc/index -- numpydoc renders a class's members
@@ -336,14 +339,19 @@ def _join_segments(segments: list[Segment]) -> list[str]:
 
 
 def _convert_doctest_block(node: nodes.doctest_block) -> list[Segment]:
-    """Convert a doctest block, stripping ``>>> ``/``... `` prompts.
+    """Convert a doctest block; see ``_convert_doctest_source``."""
+    return _convert_doctest_source(node.astext())
+
+
+def _convert_doctest_source(source: str) -> list[Segment]:
+    """Convert doctest text, stripping ``>>> ``/``... `` prompts.
 
     Non-prompted, non-blank lines are doctest *output* -- dropped entirely,
     not kept as comments.
     """
     lines: list[str] = []
     has_code = False
-    for line in node.astext().splitlines():
+    for line in source.splitlines():
         if line.startswith('>>> ') or line == '>>>':
             lines.append(_clean_code_comment(line[4:]))
             has_code = True
@@ -382,6 +390,8 @@ def _convert_literal_block(node: nodes.Element) -> list[Segment]:
         language, source = node.get('language', ''), node.astext()
     # Case-insensitive: sphinx-gallery emits ``.. code-block:: Python`` (capitalized).
     if language.lower() in _PYTHON_LANGUAGES:
+        if source.lstrip().startswith('>>>'):
+            return _convert_doctest_source(source)
         lines = [_clean_code_comment(line) for line in source.splitlines()]
         while lines and not lines[-1].strip():
             lines.pop()
@@ -1006,20 +1016,29 @@ def _drop_future_imports(source: list[str]) -> list[str]:
     return [line for i, line in enumerate(source, start=1) if i not in dropped]
 
 
+# Stands in for a line's leading % so marimo does not read it as an IPython magic.
+_PERCENT_MARK = '\ue000'
+
+
+def _mark_percent_lines(source: list[str]) -> list[str]:
+    """Replace the ``%`` that starts a line with ``_PERCENT_MARK``."""
+    return [_PERCENT_MARK + line[1:] if line.startswith('%') else line for line in source]
+
+
 def _write_marimo_notebook(app: Sphinx, name: str, notebook: dict, header: str = '') -> str:
     """Convert a generated Jupyter notebook with marimo's own converter and write it."""
     from marimo._convert.converters import MarimoConvert
 
     # A __future__ import inside a marimo cell is a SyntaxError when run as a script.
     cells = [
-        {**cell, 'source': _drop_future_imports(cell['source'])}
+        {**cell, 'source': _mark_percent_lines(_drop_future_imports(cell['source']))}
         if cell['cell_type'] == 'code'
         else cell
         for cell in notebook['cells']
     ]
     ir = MarimoConvert.from_ipynb(json.dumps({**notebook, 'cells': cells})).to_ir()
     source = MarimoConvert.from_ir(replace(ir, cells=_title_first(ir.cells))).to_py()
-    return _write_download_file(app, name, _FMT_MARIMO, header + source)
+    return _write_download_file(app, name, _FMT_MARIMO, header + source.replace(_PERCENT_MARK, '%'))
 
 
 @functools.cache
@@ -1351,10 +1370,13 @@ def _build_download_entries(
     if script_metadata is not None:
         implied = {_FMT_MARIMO: ['marimo']}
         extra = script_metadata['dependencies']
+        page = script_metadata.get('page_dependencies', [])
         project = _documented_project(script_metadata['project'])
         pins = {project.name: project.pin} if project and project.pin else {}
         deps = {
-            fmt: _script_dependencies(source, [*implied.get(fmt, []), *extra.get(fmt, [])], pins)
+            fmt: _script_dependencies(
+                source, [*implied.get(fmt, []), *extra.get(fmt, []), *page], pins
+            )
             for fmt in formats
         }
 
@@ -1595,6 +1617,7 @@ def _process_doctree(app: Sphinx, doctree: nodes.document, docname: str) -> None
             'dependencies': conf['dependencies'],
             'requires_python': conf['requires_python'],
             'project': app.config.project,
+            'page_dependencies': _page_dependencies(app.env).get(docname, []),
         }
         if conf['script_metadata']
         else None
@@ -1837,8 +1860,48 @@ def _disable_gallery_notebooks(_app: Sphinx, config: Config) -> None:
     config.sphinx_gallery_conf = {**gallery_conf, **overrides}
 
 
+def _page_dependencies(env: BuildEnvironment) -> dict[str, list[str]]:
+    """Return the requirements each page added with ``examples-as-code-dependencies``."""
+    return vars(env).setdefault('_examples_as_code_dependencies', {})
+
+
+class _DependenciesDirective(SphinxDirective):
+    """Add requirements to every download from this page; renders nothing."""
+
+    required_arguments = 1
+    final_argument_whitespace = True
+
+    def run(self) -> list[nodes.Node]:
+        """Record the requirements for the current page."""
+        requirements = self.arguments[0].replace(',', ' ').split()
+        for requirement in requirements:
+            try:
+                Requirement(requirement)
+            except InvalidRequirement as exc:
+                msg = f'Invalid requirement {requirement!r}: {exc}'
+                raise self.error(msg) from None
+        _page_dependencies(self.env).setdefault(self.env.docname, []).extend(requirements)
+        return []
+
+
+def _purge_page_dependencies(_app: Sphinx, env: BuildEnvironment, docname: str) -> None:
+    """Forget a page's requirements before it is read again."""
+    _page_dependencies(env).pop(docname, None)
+
+
+def _merge_page_dependencies(
+    _app: Sphinx, env: BuildEnvironment, docnames: set[str], other: BuildEnvironment
+) -> None:
+    """Copy the requirements a parallel reader recorded into the main environment."""
+    theirs = _page_dependencies(other)
+    _page_dependencies(env).update((name, theirs[name]) for name in docnames if name in theirs)
+
+
 def setup(app: Sphinx) -> dict:  # numpydoc ignore=RT01
     """Register the extension."""
+    app.add_directive('examples-as-code-dependencies', _DependenciesDirective)
+    app.connect('env-purge-doc', _purge_page_dependencies)
+    app.connect('env-merge-info', _merge_page_dependencies)
     app.connect('doctree-resolved', _process_doctree)
     app.connect('config-inited', _finalize_conf)
     # sphinx-gallery fills its own defaults at priority 10.

{sphinx_examples_as_code-0.8.3 → sphinx_examples_as_code-0.9.0}/sphinx_examples_as_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.8.3'
-__version_tuple__ = version_tuple = (0, 8, 3)
+__version__ = version = '0.9.0'
+__version_tuple__ = version_tuple = (0, 9, 0)
 
-__commit_id__ = commit_id = 'g1289062e0'
+__commit_id__ = commit_id = 'g71df6bcfb'

{sphinx_examples_as_code-0.8.3 → sphinx_examples_as_code-0.9.0}/sphinx_examples_as_code.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.8.3
+Version: 0.9.0
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -159,7 +159,15 @@ Imports are read from the code, not run. Each imported top-level module maps to
 project that provides it in the environment building the docs; standard-library
 modules, relative imports and modules no single installed project provides are left
 out. Projects the code needs but never imports, such as an optional backend, go in
-`dependencies`. In Python scripts and Jupyter notebooks, a dependency with no version or extras of
+`dependencies`, or for a single page in an `examples-as-code-dependencies` directive anywhere on it.
+It takes PEP 508 requirements separated by spaces or commas, adds them to every download from
+that page, and renders nothing:
+
+```rst
+.. examples-as-code-dependencies:: sympy imageio-ffmpeg>=0.4
+```
+
+In a Sphinx-Gallery example, put it in the example's docstring. In Python scripts and Jupyter notebooks, a dependency with no version or extras of
 its own is left out when another listed one already installs it on every platform, e.g. `numpy`
 next to `pyvista`. marimo notebooks list every dependency, since marimo's sandbox adds back any
 it does not find by name.

{sphinx_examples_as_code-0.8.3 → sphinx_examples_as_code-0.9.0}/sphinx_examples_as_code.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.8.3",
+  "tag": "0.9.0",
   "distance": 0,
-  "node": "g1289062e019a00bf142aa7e7389f8839220c7b39",
+  "node": "g71df6bcfbe9de4cdd1532fe1c93bdb15c9f402fb",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-11-02"

{sphinx_examples_as_code-0.8.3 → sphinx_examples_as_code-0.9.0}/tests/test_gallery_downloads.py

@@ -334,3 +334,52 @@ def test_gallery_downloads_enabled_warns_about_notebook_settings(tmp_path: Path)
     assert "sphinx_gallery_conf key(s) 'pypandoc', 'first_notebook_cell' have no effect" in err
     assert "'pypandoc' not available" not in err
     assert not list((src_dir / 'auto_examples').rglob('*.ipynb'))
+
+
+def _build_with_dependencies(tmp_path: Path, requirements: str) -> tuple[int, str, str, Path]:
+    """Build the fixture with an ``examples-as-code-dependencies`` directive in its example."""
+    src_dir = tmp_path / 'src'
+    shutil.copytree(FIXTURE_DIR, src_dir)
+    example = src_dir / 'examples' / 'plot_minimal.py'
+    source = example.read_text(encoding='utf-8')
+    marker = '==========================\n'
+    directive = f'{marker}\n.. examples-as-code-dependencies:: {requirements}\n'
+    example.write_text(source.replace(marker, directive, 1), encoding='utf-8')
+    html_dir = tmp_path / 'html'
+    sphinx_args = (
+        '-D',
+        'sphinx_examples_as_code_conf.gallery_downloads=1',
+        '-D',
+        'sphinx_examples_as_code_conf.script_metadata=1',
+        '-D',
+        'sphinx_examples_as_code_conf.formats=python,jupyter,marimo',
+    )
+    returncode, out, err = _run_sphinx_build(
+        _sphinx_build_cmd(src_dir, html_dir, tmp_path / 'doctrees', sphinx_args)
+    )
+    return returncode, out, err, html_dir
+
+
+def test_dependencies_directive_adds_to_every_download(tmp_path: Path):
+    """``examples-as-code-dependencies`` lists its requirements in each download's header."""
+    returncode, out, err, html_dir = _build_with_dependencies(tmp_path, 'sympy tqdm>=4')
+    assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
+    downloads = [
+        path
+        for path in (html_dir / '_downloads').rglob('plot_minimal*')
+        if path.suffix == '.ipynb'
+        or (path.suffix == '.py' and path.read_text(encoding='utf-8').startswith('# /// script'))
+    ]
+    assert sorted(path.suffix for path in downloads) == ['.ipynb', '.py', '.py']
+    for path in downloads:
+        text = path.read_text(encoding='utf-8')
+        assert 'sympy' in text
+        assert 'tqdm>=4' in text
+        assert 'examples-as-code-dependencies' not in text
+    html = (html_dir / 'auto_examples' / 'plot_minimal.html').read_text(encoding='utf-8')
+    assert 'examples-as-code-dependencies' not in html
+
+
+def test_dependencies_directive_rejects_invalid_requirement(tmp_path: Path):
+    _returncode, _out, err, _html_dir = _build_with_dependencies(tmp_path, 'not!valid')
+    assert "Invalid requirement 'not!valid'" in err

{sphinx_examples_as_code-0.8.3 → sphinx_examples_as_code-0.9.0}/tests/test_sphinx_examples_as_code.py

@@ -15,6 +15,7 @@ from unittest.mock import Mock
 
 from docutils import nodes
 from docutils.core import publish_doctree
+from docutils.parsers.rst import DirectiveError
 import pytest
 from sphinx import addnodes
 from sphinx.errors import ConfigError
@@ -352,6 +353,13 @@ def test_convert_doctest_block_trailing_blank_trimmed():
 # ---------------------------------------------------------------------------
 
 
+@pytest.mark.parametrize('language', ['python', 'py'])
+def test_convert_literal_block_python_doctest_style(language: str):
+    node = nodes.literal_block('', '>>> import math\n>>> math.floor(8.5)\n8')
+    node['language'] = language
+    assert seac._convert_literal_block(node) == [('code', ['import math', 'math.floor(8.5)'])]
+
+
 def test_convert_literal_block_python():
     # Sphinx's own code-block directive sets a ``language`` attribute
     # (unlike plain docutils', which uses CSS classes instead), so this
@@ -3096,6 +3104,21 @@ def test_script_metadata_drops_covered_except_marimo(
     assert ('numpy' in str(header)) is listed
 
 
+def test_write_marimo_notebook_keeps_percent_lines(tmp_path: Path):
+    code = ['art = """\n', '% %\n', '%%  %\n', '"""\n', 'x = 5 % 3']
+    notebook = {
+        'cells': [{'cell_type': 'code', 'metadata': {}, 'source': code}],
+        'metadata': {},
+        'nbformat': 4,
+        'nbformat_minor': 5,
+    }
+    rel_path = seac._write_marimo_notebook(Mock(outdir=str(tmp_path)), 'art', notebook)
+    source = (tmp_path / '_downloads' / rel_path).read_text(encoding='utf-8')
+    assert 'magic command' not in source
+    assert seac._PERCENT_MARK not in source
+    assert '    art = """\n    % %\n    %%  %\n    """\n    x = 5 % 3\n' in source
+
+
 @pytest.mark.parametrize(
     ('codes', 'expected'),
     [
@@ -3304,3 +3327,39 @@ def test_drop_covered_keeps_pinned_platform_specific_and_cycles(fake_requires):
 def test_drop_covered_without_metadata_keeps_everything(fake_requires):
     fake_requires({})
     assert seac._drop_covered(['numpy', 'pyvista']) == ['numpy', 'pyvista']
+
+
+def test_page_dependencies_purge_and_merge():
+    env, other = SimpleNamespace(), SimpleNamespace()
+    seac._page_dependencies(env)['a'] = ['sympy']
+    seac._page_dependencies(other).update({'b': ['tqdm'], 'c': ['rich']})
+    seac._merge_page_dependencies(None, env, {'b'}, other)
+    assert seac._page_dependencies(env) == {'a': ['sympy'], 'b': ['tqdm']}
+    seac._purge_page_dependencies(None, env, 'a')
+    seac._purge_page_dependencies(None, env, 'missing')
+    assert seac._page_dependencies(env) == {'b': ['tqdm']}
+
+
+def _run_dependencies_directive(argument: str, env: SimpleNamespace) -> list[nodes.Node]:
+    """Run ``examples-as-code-dependencies`` with ``argument`` on page ``page``."""
+    state = Mock()
+    state.document.settings.env = env
+    directive = seac._DependenciesDirective(
+        'examples-as-code-dependencies', [argument], {}, [], 1, 0, '', state, Mock()
+    )
+    return directive.run()
+
+
+def test_dependencies_directive_records_requirements():
+    env = SimpleNamespace(docname='page')
+    assert _run_dependencies_directive('sympy, tqdm>=4', env) == []
+    _run_dependencies_directive('rich', env)
+    assert seac._page_dependencies(env) == {'page': ['sympy', 'tqdm>=4', 'rich']}
+
+
+def test_dependencies_directive_invalid_requirement():
+    env = SimpleNamespace(docname='page')
+    with pytest.raises(DirectiveError) as excinfo:
+        _run_dependencies_directive('sympy not!valid', env)
+    assert excinfo.value.msg.startswith("Invalid requirement 'not!valid'")
+    assert seac._page_dependencies(env) == {}