sphinx-examples-as-code 0.8.0__tar.gz → 0.8.2__tar.gz

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.8.0
+Version: 0.8.2
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -96,11 +96,13 @@ sphinx_examples_as_code_conf = {
   (default) or `'bottom'`.
 - `formats`: which downloads to generate. A list containing any of `'python'` (a plain
   Python script, `<name>.py`), `'jupyter'` (a Jupyter notebook, `<name>.ipynb`) and
-  `'marimo'` (a marimo notebook, `<name>.marimo.py`); defaults to all three. Always
+  `'marimo'` (a marimo notebook, `<name>_marimo.py`); defaults to all three. Always
   offered in that order regardless of how the list is written. Without marimo 0.14 or
   newer installed, the default skips the marimo download, and a `formats` that names
   `'marimo'` (in `conf.py` or through `-D`) stops the build with a configuration error. An unknown format raises a configuration error too;
-  the old `'py'` and `'ipynb'` names say what replaced them.
+  the old `'py'` and `'ipynb'` names say what replaced them. `<name>` is the documented
+  object's full name without its top-level package, e.g. `Plotter_show` for
+  `pyvista.Plotter.show`, or the gallery example's file name.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
 - `gallery_downloads`: opt-in takeover of
@@ -149,8 +151,9 @@ imports, plus any `dependencies` set for its format, and says how to run it:
   needed, so the command works in bash, zsh, PowerShell and cmd. An argument containing
   `"`, `$`, a backtick, `\`, `%` or a `!` not followed by `=` is single-quoted instead,
   which cmd does not understand.
-- marimo notebooks start with the same `# /// script` block, which also lists `marimo`,
-  followed by `# Open this notebook with: uvx marimo edit --sandbox <name>.marimo.py`.
+- marimo notebooks start with the same `# /// script` block, which also lists `marimo`
+  unless another dependency installs it,
+  followed by `# Open this notebook with: uvx marimo edit --sandbox <name>_marimo.py`.
 - Each run command is followed by a line linking to
   [uv's installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 
@@ -158,7 +161,9 @@ 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`.
+`dependencies`. 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` and `marimo` next to
+`pyvista[marimo]`.
 
 The project named by Sphinx's own `project` setting (e.g. `project = 'PyVista'`) gets
 extra treatment when an example imports it and it is installed: its dependency becomes
@@ -169,8 +174,8 @@ Unless `requires_python` is set, the block's `requires-python` combines:
 
 - that project's own `Requires-Python`, e.g. `>=3.10`, when it is listed;
 - `<3.N`, one minor version above the newest Python named in the `Programming Language ::
-  Python :: 3.X` classifiers of that project and of every listed dependency installed
-  from a platform-specific wheel, as installed in the environment building the docs.
+  Python :: 3.X` classifiers of that project and of every dependency, listed or left out,
+  installed from a platform-specific wheel, as installed in the environment building the docs.
   Pure-Python dependencies and dependencies without such classifiers don't count, and
   the bound is dropped when it would exclude every Python the project's own
   `Requires-Python` allows.
@@ -221,7 +226,7 @@ cells instead.
 
 Generated marimo notebooks are that same Jupyter notebook converted by marimo's own
 converter, the one behind `marimo convert`. `from __future__` imports are dropped first,
-so the notebook also runs as a plain script (`python <name>.marimo.py`).
+so the notebook also runs as a plain script (`python <name>_marimo.py`).
 
 A download link is only added if the resulting code contains at least one real
 executable statement.

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/README.md

@@ -64,11 +64,13 @@ sphinx_examples_as_code_conf = {
   (default) or `'bottom'`.
 - `formats`: which downloads to generate. A list containing any of `'python'` (a plain
   Python script, `<name>.py`), `'jupyter'` (a Jupyter notebook, `<name>.ipynb`) and
-  `'marimo'` (a marimo notebook, `<name>.marimo.py`); defaults to all three. Always
+  `'marimo'` (a marimo notebook, `<name>_marimo.py`); defaults to all three. Always
   offered in that order regardless of how the list is written. Without marimo 0.14 or
   newer installed, the default skips the marimo download, and a `formats` that names
   `'marimo'` (in `conf.py` or through `-D`) stops the build with a configuration error. An unknown format raises a configuration error too;
-  the old `'py'` and `'ipynb'` names say what replaced them.
+  the old `'py'` and `'ipynb'` names say what replaced them. `<name>` is the documented
+  object's full name without its top-level package, e.g. `Plotter_show` for
+  `pyvista.Plotter.show`, or the gallery example's file name.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
 - `gallery_downloads`: opt-in takeover of
@@ -117,8 +119,9 @@ imports, plus any `dependencies` set for its format, and says how to run it:
   needed, so the command works in bash, zsh, PowerShell and cmd. An argument containing
   `"`, `$`, a backtick, `\`, `%` or a `!` not followed by `=` is single-quoted instead,
   which cmd does not understand.
-- marimo notebooks start with the same `# /// script` block, which also lists `marimo`,
-  followed by `# Open this notebook with: uvx marimo edit --sandbox <name>.marimo.py`.
+- marimo notebooks start with the same `# /// script` block, which also lists `marimo`
+  unless another dependency installs it,
+  followed by `# Open this notebook with: uvx marimo edit --sandbox <name>_marimo.py`.
 - Each run command is followed by a line linking to
   [uv's installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 
@@ -126,7 +129,9 @@ 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`.
+`dependencies`. 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` and `marimo` next to
+`pyvista[marimo]`.
 
 The project named by Sphinx's own `project` setting (e.g. `project = 'PyVista'`) gets
 extra treatment when an example imports it and it is installed: its dependency becomes
@@ -137,8 +142,8 @@ Unless `requires_python` is set, the block's `requires-python` combines:
 
 - that project's own `Requires-Python`, e.g. `>=3.10`, when it is listed;
 - `<3.N`, one minor version above the newest Python named in the `Programming Language ::
-  Python :: 3.X` classifiers of that project and of every listed dependency installed
-  from a platform-specific wheel, as installed in the environment building the docs.
+  Python :: 3.X` classifiers of that project and of every dependency, listed or left out,
+  installed from a platform-specific wheel, as installed in the environment building the docs.
   Pure-Python dependencies and dependencies without such classifiers don't count, and
   the bound is dropped when it would exclude every Python the project's own
   `Requires-Python` allows.
@@ -189,7 +194,7 @@ cells instead.
 
 Generated marimo notebooks are that same Jupyter notebook converted by marimo's own
 converter, the one behind `marimo convert`. `from __future__` imports are dropped first,
-so the notebook also runs as a plain script (`python <name>.marimo.py`).
+so the notebook also runs as a plain script (`python <name>_marimo.py`).
 
 A download link is only added if the resulting code contains at least one real
 executable statement.

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/sphinx_examples_as_code/__init__.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import ast
 from dataclasses import dataclass
+from dataclasses import replace
 import functools
 import hashlib
 import importlib.metadata
@@ -181,6 +182,9 @@ _FMT_PYTHON = 'python'
 _FMT_JUPYTER = 'jupyter'
 _FMT_MARIMO = 'marimo'
 
+#: File name suffix of each download format, e.g. ``pyvista_read_marimo.py``.
+_SUFFIXES = {_FMT_PYTHON: '.py', _FMT_JUPYTER: '.ipynb', _FMT_MARIMO: '_marimo.py'}
+
 
 @dataclass(frozen=True)
 class _RenderContext:
@@ -805,6 +809,14 @@ def _qualified_name_for(node: nodes.Node, docname: str, counter: int) -> str:
     return f'{base}-example-{counter}'
 
 
+def _download_stem(node: nodes.Node, docname: str, counter: int) -> str:
+    """Name a span's downloads, e.g. ``Plotter.show`` for ``pyvista.Plotter.show``."""
+    name = _qualified_name_for(node, docname, counter)
+    if any(_desc_id(desc) is not None for desc in _enclosing_descs(node)):
+        return name.partition('.')[2] or name
+    return name
+
+
 def _header_title(qualified_name: str) -> str:
     """Build the file's own header title text, e.g. ``Examples from pyvista.read``."""
     return f'Examples from {qualified_name}'
@@ -931,13 +943,13 @@ def _build_notebook(cells: list[tuple[str, list[str]]]) -> dict:
     }
 
 
-def _download_filename(name: str, extension: str) -> str:
-    """Return the file name a download is written under, e.g. ``pyvista_read.py``."""
+def _download_filename(name: str, fmt: str) -> str:
+    """Return the file name a download is written under, e.g. ``Plotter_show.py``."""
     safe_name = name.replace('.', '_') if name else 'example'
-    return f'{safe_name}.{extension}'
+    return f'{safe_name}{_SUFFIXES[fmt]}'
 
 
-def _write_download_file(app: Sphinx, name: str, extension: str, content: str) -> str:
+def _write_download_file(app: Sphinx, name: str, fmt: str, content: str) -> str:
     """Write generated content directly into the builder's downloads dir.
 
     Returns the written file's path relative to the downloads directory --
@@ -948,7 +960,7 @@ def _write_download_file(app: Sphinx, name: str, extension: str, content: str) -
     """
     # 32 hex chars, matching Sphinx's own native _downloads/<digest>/... layout.
     digest = hashlib.sha256(content.encode()).hexdigest()[:32]
-    filename = _download_filename(name, extension)
+    filename = _download_filename(name, fmt)
     rel_path = f'{digest}/{filename}'
 
     out_path = Path(app.outdir) / '_downloads' / digest / filename
@@ -959,12 +971,23 @@ def _write_download_file(app: Sphinx, name: str, extension: str, content: str) -
 
 def _write_python_script(app: Sphinx, name: str, source: str) -> str:
     """Write a generated Python script; see ``_write_download_file``."""
-    return _write_download_file(app, name, 'py', source)
+    return _write_download_file(app, name, _FMT_PYTHON, source)
 
 
 def _write_jupyter_notebook(app: Sphinx, name: str, notebook: dict) -> str:
     """Write a generated Jupyter notebook; see ``_write_download_file``."""
-    return _write_download_file(app, name, 'ipynb', json.dumps(notebook, indent=1))
+    return _write_download_file(app, name, _FMT_JUPYTER, json.dumps(notebook, indent=1))
+
+
+def _title_first(cells: list) -> list:
+    """Move marimo's leading ``import marimo as mo`` cell below the title cell after it."""
+    if (
+        len(cells) > 1
+        and cells[0].code == 'import marimo as mo'
+        and cells[1].code.startswith('mo.md(')
+    ):
+        return [cells[1], cells[0], *cells[2:]]
+    return cells
 
 
 def _drop_future_imports(source: list[str]) -> list[str]:
@@ -994,8 +1017,9 @@ def _write_marimo_notebook(app: Sphinx, name: str, notebook: dict, header: str =
         else cell
         for cell in notebook['cells']
     ]
-    source = MarimoConvert.from_ipynb(json.dumps({**notebook, 'cells': cells})).to_py()
-    return _write_download_file(app, name, 'marimo.py', header + source)
+    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)
 
 
 @functools.cache
@@ -1067,6 +1091,66 @@ def _keep_pin(requirement: str, pin: str | None) -> str:
     return str(parsed)
 
 
+_QUOTED = re.compile(r'"[^"]*"|\'[^\']*\'')
+_MARKER_WORDS = {'and', 'or', 'not', 'in'}
+
+
+def _depends_only_on_extras(requirement: Requirement, extras: frozenset[str]) -> bool:
+    """Check whether ``requirement`` applies with ``extras`` on every platform and Python."""
+    if requirement.marker is None:
+        return True
+    names = set(re.findall(r'[A-Za-z_.]+', _QUOTED.sub('', str(requirement.marker))))
+    if names - _MARKER_WORDS != {'extra'}:
+        return False
+    return any(requirement.marker.evaluate({'extra': extra}) for extra in extras | {''})
+
+
+@functools.cache
+def _installed_requirements(name: str, extras: frozenset[str]) -> frozenset[Requirement]:
+    """Return the unconditional requirements of an installed distribution with ``extras``."""
+    try:
+        requires = importlib.metadata.requires(name) or []
+    except importlib.metadata.PackageNotFoundError:
+        return frozenset()
+    parsed = (Requirement(req) for req in requires)
+    return frozenset(req for req in parsed if _depends_only_on_extras(req, extras))
+
+
+def _transitive_names(requirement: str) -> set[str]:
+    """Return the normalized names every install of ``requirement`` pulls in, itself excluded."""
+    root = Requirement(requirement)
+    seen: set[tuple[str, frozenset[str]]] = set()
+    todo = [(canonicalize_name(root.name), frozenset(root.extras))]
+    names: set[str] = set()
+    while todo:
+        key = todo.pop()
+        if key in seen:
+            continue
+        seen.add(key)
+        for req in _installed_requirements(*key):
+            names.add(canonicalize_name(req.name))
+            todo.append((canonicalize_name(req.name), frozenset(req.extras)))
+    names.discard(canonicalize_name(root.name))
+    return names
+
+
+def _drop_covered(deps: list[str]) -> list[str]:
+    """Drop each bare-name dependency that another listed dependency already installs."""
+    pulled = {dep: _transitive_names(dep) for dep in deps}
+    names = {dep: _canonical_name(dep) for dep in deps}
+
+    def covered(dep: str) -> bool:
+        if dep != Requirement(dep).name:
+            return False
+        return any(
+            names[dep] in pulled[other] and names[other] not in pulled[dep]
+            for other in deps
+            if other != dep
+        )
+
+    return [dep for dep in deps if not covered(dep)]
+
+
 @dataclass(frozen=True)
 class _DocumentedProject:
     """The installed distribution named by Sphinx's ``project``."""
@@ -1294,28 +1378,28 @@ def _build_download_entries(
         cap = _python_upper_bound(deps[fmt], project.name if project else None)
         return _python_range(floor, cap)
 
+    shown = {fmt: _drop_covered(fmt_deps) for fmt, fmt_deps in deps.items()}
+
     def header_for(fmt: str, run_line: str) -> str:
         if not deps:
             return ''
-        return _script_metadata_header(deps[fmt], requires_python_for(fmt), run_line)
+        return _script_metadata_header(shown[fmt], requires_python_for(fmt), run_line)
 
     entries = []
     for fmt in _FORMAT_ORDER:
         if fmt not in formats:
             continue
         label = link_labels[fmt]
+        filename = _download_filename(name, fmt)
         if fmt == _FMT_PYTHON:
-            filename = _download_filename(name, 'py')
             header = header_for(fmt, f'Run this script with: uv run {filename}')
             rel_path = _write_python_script(app, name, header + source)
         elif fmt == _FMT_JUPYTER:
-            filename = _download_filename(name, 'ipynb')
             run_line = (
-                _jupyter_run_line(deps[fmt], requires_python_for(fmt), filename) if deps else None
+                _jupyter_run_line(shown[fmt], requires_python_for(fmt), filename) if deps else None
             )
             rel_path = _write_jupyter_notebook(app, name, notebook_for(run_line))
         else:
-            filename = _download_filename(name, 'marimo.py')
             run_line = f'Open this notebook with: uvx marimo edit --sandbox {filename}'
             rel_path = _write_marimo_notebook(
                 app, name, notebook_for(None), header_for(fmt, run_line)
@@ -1346,7 +1430,7 @@ def _process_span(
     entries = _build_download_entries(
         app,
         docname,
-        name,
+        _download_stem(heading, docname, counter),
         _header_title(name),
         nodes_in_span,
         formats,

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/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.0'
-__version_tuple__ = version_tuple = (0, 8, 0)
+__version__ = version = '0.8.2'
+__version_tuple__ = version_tuple = (0, 8, 2)
 
-__commit_id__ = commit_id = 'g35e7c7f07'
+__commit_id__ = commit_id = 'g69288337b'

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/sphinx_examples_as_code.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.8.0
+Version: 0.8.2
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -96,11 +96,13 @@ sphinx_examples_as_code_conf = {
   (default) or `'bottom'`.
 - `formats`: which downloads to generate. A list containing any of `'python'` (a plain
   Python script, `<name>.py`), `'jupyter'` (a Jupyter notebook, `<name>.ipynb`) and
-  `'marimo'` (a marimo notebook, `<name>.marimo.py`); defaults to all three. Always
+  `'marimo'` (a marimo notebook, `<name>_marimo.py`); defaults to all three. Always
   offered in that order regardless of how the list is written. Without marimo 0.14 or
   newer installed, the default skips the marimo download, and a `formats` that names
   `'marimo'` (in `conf.py` or through `-D`) stops the build with a configuration error. An unknown format raises a configuration error too;
-  the old `'py'` and `'ipynb'` names say what replaced them.
+  the old `'py'` and `'ipynb'` names say what replaced them. `<name>` is the documented
+  object's full name without its top-level package, e.g. `Plotter_show` for
+  `pyvista.Plotter.show`, or the gallery example's file name.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
 - `gallery_downloads`: opt-in takeover of
@@ -149,8 +151,9 @@ imports, plus any `dependencies` set for its format, and says how to run it:
   needed, so the command works in bash, zsh, PowerShell and cmd. An argument containing
   `"`, `$`, a backtick, `\`, `%` or a `!` not followed by `=` is single-quoted instead,
   which cmd does not understand.
-- marimo notebooks start with the same `# /// script` block, which also lists `marimo`,
-  followed by `# Open this notebook with: uvx marimo edit --sandbox <name>.marimo.py`.
+- marimo notebooks start with the same `# /// script` block, which also lists `marimo`
+  unless another dependency installs it,
+  followed by `# Open this notebook with: uvx marimo edit --sandbox <name>_marimo.py`.
 - Each run command is followed by a line linking to
   [uv's installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 
@@ -158,7 +161,9 @@ 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`.
+`dependencies`. 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` and `marimo` next to
+`pyvista[marimo]`.
 
 The project named by Sphinx's own `project` setting (e.g. `project = 'PyVista'`) gets
 extra treatment when an example imports it and it is installed: its dependency becomes
@@ -169,8 +174,8 @@ Unless `requires_python` is set, the block's `requires-python` combines:
 
 - that project's own `Requires-Python`, e.g. `>=3.10`, when it is listed;
 - `<3.N`, one minor version above the newest Python named in the `Programming Language ::
-  Python :: 3.X` classifiers of that project and of every listed dependency installed
-  from a platform-specific wheel, as installed in the environment building the docs.
+  Python :: 3.X` classifiers of that project and of every dependency, listed or left out,
+  installed from a platform-specific wheel, as installed in the environment building the docs.
   Pure-Python dependencies and dependencies without such classifiers don't count, and
   the bound is dropped when it would exclude every Python the project's own
   `Requires-Python` allows.
@@ -221,7 +226,7 @@ cells instead.
 
 Generated marimo notebooks are that same Jupyter notebook converted by marimo's own
 converter, the one behind `marimo convert`. `from __future__` imports are dropped first,
-so the notebook also runs as a plain script (`python <name>.marimo.py`).
+so the notebook also runs as a plain script (`python <name>_marimo.py`).
 
 A download link is only added if the resulting code contains at least one real
 executable statement.

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/sphinx_examples_as_code.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.8.0",
+  "tag": "0.8.2",
   "distance": 0,
-  "node": "g35e7c7f071baf732904a6fad8b7ea7a63f03d1f2",
+  "node": "g69288337b5a4907e168725fbd4dbc5e1ea9450f8",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-11-01"

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/tests/test_gallery_downloads.py

@@ -275,7 +275,7 @@ def test_gallery_downloads_generated_python_executes(gallery_build: tuple[Path,
 def test_gallery_downloads_marimo_notebook_executes(gallery_build: tuple[Path, str]):
     """The marimo notebook holds the page's code and runs as a plain script."""
     html_dir, _html = gallery_build
-    (marimo_path,) = (html_dir / '_downloads').rglob('*.marimo.py')
+    (marimo_path,) = (html_dir / '_downloads').rglob('*_marimo.py')
     src = marimo_path.read_text(encoding='utf-8')
     assert 'app = marimo.App(' in src
     assert 'A minimal gallery example' in src

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/tests/test_single_function_page.py

@@ -29,12 +29,12 @@ def test_download_named_after_the_function_not_the_docname(tmp_path: Path):
     assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
 
     downloads_dir = html_dir / '_downloads'
-    python_files = [p for p in downloads_dir.rglob('*.py') if not p.name.endswith('.marimo.py')]
+    python_files = [p for p in downloads_dir.rglob('*.py') if not p.name.endswith('_marimo.py')]
     assert len(python_files) == 1, f'expected exactly one generated .py, got {python_files}'
     python_path = python_files[0]
 
     # not "index-example-1" (the docname-derived fallback name)
-    assert python_path.stem == 'mymodule_download_bunny'
+    assert python_path.stem == 'download_bunny'
 
     lines = python_path.read_text(encoding='utf-8').splitlines()
     assert lines[0] == '# Examples from mymodule.download_bunny'

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/tests/test_sphinx_examples_as_code.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import copy
 import json
+from types import SimpleNamespace
 from typing import TYPE_CHECKING
 from unittest.mock import Mock
 
@@ -1140,6 +1141,24 @@ def test_qualified_name_for_desc_ancestor():
     assert seac._qualified_name_for(heading, 'page', 1) == 'pkg.mod.func'
 
 
+@pytest.mark.parametrize(('desc_id', 'expected'), [('pkg.mod.func', 'mod.func'), ('func', 'func')])
+def test_download_stem_drops_top_level_package(desc_id: str, expected: str):
+    desc = addnodes.desc()
+    desc += addnodes.desc_signature(ids=[desc_id])
+    content = addnodes.desc_content()
+    heading = nodes.rubric()
+    content += heading
+    desc += content
+    assert seac._download_stem(heading, 'page', 1) == expected
+
+
+def test_download_stem_keeps_dotted_fallback_name():
+    section = nodes.section()
+    heading = nodes.rubric()
+    section += heading
+    assert seac._download_stem(heading, 'release.0.44', 1) == 'release.0.44-example-1'
+
+
 def test_qualified_name_for_fallback_no_desc_ancestor():
     section = nodes.section()
     heading = nodes.rubric()
@@ -1613,6 +1632,18 @@ def test_build_notebook_valid_nbformat():
     nbformat.validate(node)  # raises if invalid
 
 
+@pytest.mark.parametrize(
+    ('name', 'fmt', 'expected'),
+    [
+        ('ImageDataFilters.resample', 'marimo', 'ImageDataFilters_resample_marimo.py'),
+        ('plot_vtk9.4', 'python', 'plot_vtk9_4.py'),
+        ('', 'jupyter', 'example.ipynb'),
+    ],
+)
+def test_download_filename(name: str, fmt: str, expected: str):
+    assert seac._download_filename(name, fmt) == expected
+
+
 # ---------------------------------------------------------------------------
 # _write_jupyter_notebook
 # ---------------------------------------------------------------------------
@@ -1856,8 +1887,8 @@ def test_process_span_footer_in_notebook_is_linkified(tmp_path: Path):
         (['jupyter'], ['.ipynb']),
         (['python', 'jupyter'], ['.py', '.ipynb']),
         (['jupyter', 'python'], ['.py', '.ipynb']),  # canonical order regardless of config order
-        (['marimo'], ['.marimo.py']),
-        (['marimo', 'python', 'jupyter'], ['.py', '.ipynb', '.marimo.py']),
+        (['marimo'], ['_marimo.py']),
+        (['marimo', 'python', 'jupyter'], ['.py', '.ipynb', '_marimo.py']),
         ([], []),
     ],
 )
@@ -3052,6 +3083,21 @@ def test_script_metadata_marimo(tmp_path: Path):
     )
     assert source.startswith(header)
     assert 'Open this notebook' not in source.removeprefix(header)
+    assert source.index('mo.md(') < source.index('import marimo as mo')
+
+
+@pytest.mark.parametrize(
+    ('codes', 'expected'),
+    [
+        (['import marimo as mo', 'mo.md("# T")', 'x = 1'], [1, 0, 2]),
+        (['import marimo as mo', 'x = 1'], [0, 1]),
+        (['mo.md("# T")', 'import marimo as mo'], [0, 1]),
+        (['import marimo as mo'], [0]),
+    ],
+)
+def test_title_first(codes: list[str], expected: list[int]):
+    cells = [SimpleNamespace(code=code) for code in codes]
+    assert seac._title_first(cells) == [cells[i] for i in expected]
 
 
 def test_process_doctree_script_metadata_enabled(tmp_path: Path):
@@ -3203,3 +3249,48 @@ def test_script_metadata_documented_project_not_imported(
     source = _python_source_for(tmp_path, 'NumPy', '.. rubric:: Examples\n\n>>> import docutils')
     assert '# requires-python = "<3.15"\n' in source
     assert 'numpy' not in source
+
+
+@pytest.fixture
+def fake_requires(monkeypatch: pytest.MonkeyPatch):
+    """Serve installed requirements from a dict."""
+
+    def install(requires: dict[str, list[str]]) -> None:
+        def fake(name: str) -> list[str]:
+            if name not in requires:
+                raise seac.importlib.metadata.PackageNotFoundError(name)
+            return requires[name]
+
+        monkeypatch.setattr(seac.importlib.metadata, 'requires', fake)
+
+    seac._installed_requirements.cache_clear()
+    yield install
+    seac._installed_requirements.cache_clear()
+
+
+def test_drop_covered_follows_extras_transitively(fake_requires):
+    fake_requires(
+        {
+            'pyvista': ['numpy>=1.21', 'trame-pyvista[marimo]>=0.3; extra == "marimo"'],
+            'trame-pyvista': ['marimo; extra == "marimo"'],
+        }
+    )
+    deps = ['marimo', 'numpy', 'pyvista[marimo]', 'scipy']
+    assert seac._drop_covered(deps) == ['pyvista[marimo]', 'scipy']
+    assert seac._drop_covered(['marimo', 'numpy', 'pyvista']) == ['marimo', 'pyvista']
+
+
+def test_drop_covered_keeps_pinned_platform_specific_and_cycles(fake_requires):
+    fake_requires(
+        {
+            'pyvista': ['numpy', 'pooch; sys_platform == "linux"', 'cycle'],
+            'cycle': ['pyvista'],
+        }
+    )
+    deps = ['cycle', 'numpy>=2', 'pooch', 'pyvista']
+    assert seac._drop_covered(deps) == deps
+
+
+def test_drop_covered_without_metadata_keeps_everything(fake_requires):
+    fake_requires({})
+    assert seac._drop_covered(['numpy', 'pyvista']) == ['numpy', 'pyvista']

{sphinx_examples_as_code-0.8.0 → sphinx_examples_as_code-0.8.2}/tests/test_tinypages.py

@@ -92,7 +92,7 @@ def built(tmp_path_factory) -> tuple[Path, list[Path]]:
     assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
 
     downloads_dir = html_dir / '_downloads'
-    examples = sorted(p for p in downloads_dir.rglob('*.py') if not p.name.endswith('.marimo.py'))
+    examples = sorted(p for p in downloads_dir.rglob('*.py') if not p.name.endswith('_marimo.py'))
     return html_dir, examples
 
 
@@ -228,7 +228,7 @@ def test_table_becomes_an_rst_simple_table_in_python(built: tuple[Path, list[Pat
 
 def test_table_becomes_a_markdown_table_in_jupyter(built_jupyter_notebooks: list[Path]):
     """The same table is a Markdown pipe table in a notebook's markdown cell."""
-    nb_path = next(p for p in built_jupyter_notebooks if p.stem == 'docstring_cases_case_table')
+    nb_path = next(p for p in built_jupyter_notebooks if p.stem == 'case_table')
     notebook = json.loads(nb_path.read_text(encoding='utf-8'))
     lines = [
         line.rstrip()
@@ -246,9 +246,7 @@ def test_table_becomes_a_markdown_table_in_jupyter(built_jupyter_notebooks: list
 
 def test_header_less_table_gets_a_blank_markdown_header(built_jupyter_notebooks: list[Path]):
     """A Markdown pipe table needs a header row, so one is left blank."""
-    nb_path = next(
-        p for p in built_jupyter_notebooks if p.stem == 'docstring_cases_case_table_without_header'
-    )
+    nb_path = next(p for p in built_jupyter_notebooks if p.stem == 'case_table_without_header')
     notebook = json.loads(nb_path.read_text(encoding='utf-8'))
     lines = [
         line.rstrip()
@@ -301,7 +299,7 @@ def test_header_format(built: tuple[Path, list[Path]]):
 
 def test_header_format_jupyter_uses_atx(built_jupyter_notebooks: list[Path]):
     """The same header, in .ipynb, is a single ATX level-1 line -- no underline."""
-    nb_path = next(p for p in built_jupyter_notebooks if p.stem == 'docstring_cases_case_note')
+    nb_path = next(p for p in built_jupyter_notebooks if p.stem == 'case_note')
     notebook = json.loads(nb_path.read_text(encoding='utf-8'))
     header_cell = notebook['cells'][0]
     lines = [line.rstrip() for line in header_cell['source']]
@@ -451,9 +449,7 @@ def test_jupyter_notebook_code_cells_match_python_code(
         line for line in python_src.splitlines() if line and not line.startswith('#')
     ]
 
-    notebook_path = next(
-        p for p in built_jupyter_notebooks if p.stem == 'docstring_cases_case_combined'
-    )
+    notebook_path = next(p for p in built_jupyter_notebooks if p.stem == 'case_combined')
     notebook = json.loads(notebook_path.read_text(encoding='utf-8'))
     code_cells = [c for c in notebook['cells'] if c['cell_type'] == 'code']
     notebook_code_lines = [
@@ -494,7 +490,7 @@ def test_formats_config_selection(
     assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
 
     downloads_dir = html_dir / '_downloads'
-    marimo_files = list(downloads_dir.rglob('*.marimo.py'))
+    marimo_files = list(downloads_dir.rglob('*_marimo.py'))
     python_files = [p for p in downloads_dir.rglob('*.py') if p not in marimo_files]
     jupyter_files = list(downloads_dir.rglob('*.ipynb'))
 
@@ -520,11 +516,7 @@ def test_base_url_unset_no_links_anywhere(
     python_src = _read(built[1], 'case_regular_xref_for_base_url')
     assert 'http' not in python_src
 
-    nb_path = next(
-        p
-        for p in built_jupyter_notebooks
-        if p.stem == 'docstring_cases_case_regular_xref_for_base_url'
-    )
+    nb_path = next(p for p in built_jupyter_notebooks if p.stem == 'case_regular_xref_for_base_url')
     nb_text = nb_path.read_text(encoding='utf-8')
     assert 'http' not in nb_text
     assert '](' not in nb_text  # no markdown links
@@ -553,7 +545,7 @@ def test_base_url_set_resolves_links(tmp_path: Path):
     assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
 
     downloads_dir = html_dir / '_downloads'
-    python_files = [p for p in downloads_dir.rglob('*.py') if not p.name.endswith('.marimo.py')]
+    python_files = [p for p in downloads_dir.rglob('*.py') if not p.name.endswith('_marimo.py')]
     jupyter_files = list(downloads_dir.rglob('*.ipynb'))
 
     # a regular reference: link resolved in .ipynb, omitted in .py
@@ -562,7 +554,7 @@ def test_base_url_set_resolves_links(tmp_path: Path):
     assert '`docstring_cases.Sample`' in regular_python
 
     regular_nb = next(
-        p for p in jupyter_files if p.stem == 'docstring_cases_case_regular_xref_for_base_url'
+        p for p in jupyter_files if p.stem == 'case_regular_xref_for_base_url'
     ).read_text(encoding='utf-8')
     assert '[`docstring_cases.Sample`](https://docs.example.com/' in regular_nb
 
@@ -601,7 +593,7 @@ def test_markdown_cells_use_hard_line_breaks(built_jupyter_notebooks: list[Path]
     with no blank line between -- not the header cell, which is a single
     ATX heading line with nothing else to connect to.
     """
-    nb_path = next(p for p in built_jupyter_notebooks if p.stem == 'docstring_cases_case_note')
+    nb_path = next(p for p in built_jupyter_notebooks if p.stem == 'case_note')
     notebook = json.loads(nb_path.read_text(encoding='utf-8'))
     note_cell = next(
         c
@@ -632,9 +624,7 @@ def test_html_baseurl_missing_scheme_disables_links_without_failing_build(tmp_pa
     )
     assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
 
-    nb_path = next(
-        (html_dir / '_downloads').rglob('docstring_cases_case_regular_xref_for_base_url.ipynb')
-    )
+    nb_path = next((html_dir / '_downloads').rglob('case_regular_xref_for_base_url.ipynb'))
     nb_text = nb_path.read_text(encoding='utf-8')
     assert '](' not in nb_text  # no markdown links -- same as html_baseurl unset entirely
 
@@ -653,9 +643,7 @@ def test_base_url_missing_trailing_slash_still_resolves_subpath(tmp_path: Path):
     )
     assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
 
-    nb_path = next(
-        (html_dir / '_downloads').rglob('docstring_cases_case_regular_xref_for_base_url.ipynb')
-    )
+    nb_path = next((html_dir / '_downloads').rglob('case_regular_xref_for_base_url.ipynb'))
     nb_text = nb_path.read_text(encoding='utf-8')
     assert 'https://docs.example.com/en/stable/docstring_cases.html' in nb_text