sphinx-examples-as-code 0.7.0__tar.gz → 0.8.1__tar.gz

{sphinx_examples_as_code-0.7.0 → sphinx_examples_as_code-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.7.0
+Version: 0.8.1
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -22,6 +22,7 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: packaging>=22
 Requires-Dist: pyvista>=0.48
 Provides-Extra: gallery
 Requires-Dist: sphinx-gallery<0.23,>=0.22; extra == "gallery"
@@ -85,6 +86,9 @@ sphinx_examples_as_code_conf = {
         'jupyter': 'Download Jupyter notebook',
         'marimo': 'Download marimo notebook',
     },
+    'script_metadata': False,
+    'dependencies': {},
+    'requires_python': None,
 }
 ```
 
@@ -92,7 +96,7 @@ 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;
@@ -111,6 +115,17 @@ sphinx_examples_as_code_conf = {
   Markdown link in notebooks, and renders inline as `text url` in Python scripts. Plain
   text with no markup at all becomes one comment line per line of text, and
   blank-line-separated paragraphs stay separated.
+- `script_metadata`: `True` adds each download's dependencies and a one-line run
+  command. See [Dependencies and run commands](#dependencies-and-run-commands) below.
+  `False` (default) adds neither.
+- `dependencies`: extra PEP 508 requirements per format, added to the detected ones, e.g.
+  `{'jupyter': ['pyvista[jupyter]']}`. An entry naming a detected project replaces it,
+  so `{'python': ['pyvista>=0.46']}` sets its version. An entry without a version keeps
+  the automatic pin described below. Only used with `script_metadata` on.
+- `requires_python`: a `requires-python` specifier for the dependency block, e.g.
+  `'>=3.10'`. `None` (default) derives one from the dependencies instead; see
+  [Dependencies and run commands](#dependencies-and-run-commands). Only used with
+  `script_metadata` on.
 
 An unrecognized key raises a configuration error at build start.
 
@@ -122,6 +137,46 @@ Overriding a single key from the command line works via a dotted `-D` flag, e.g.
 `-D sphinx_examples_as_code_conf.link_position=bottom` -- this only touches that one
 key, leaving the rest (`conf.py`'s values, or the defaults) alone.
 
+## Dependencies and run commands
+
+With `script_metadata` on, each download lists the third-party projects its code
+imports, plus any `dependencies` set for its format, and says how to run it:
+
+- Python scripts start with a [PEP 723](https://peps.python.org/pep-0723/) `# /// script`
+  block, followed by `# Run this script with: uv run <name>.py`.
+- Jupyter notebooks say `` Open this notebook with: `uvx --python "<requires-python>" --from jupyterlab --with <dependency> ... jupyter-lab <name>.ipynb` `` in their first cell,
+  with `--python` only when there is a `requires-python`. Arguments are double-quoted where
+  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`.
+- Each run command is followed by a line linking to
+  [uv's installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+Imports are read from the code, not run. Each imported top-level module maps to the
+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`.
+
+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
+`<name>>=X.Y`, the installed release's major and minor version, or plain `<name>` for a
+pre-release or dev build.
+
+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.
+  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.
+
+With neither, the line is left out.
+
 ## Conversion rules
 
 What happens to the content of an Examples section:
@@ -166,7 +221,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.7.0 → sphinx_examples_as_code-0.8.1}/README.md

@@ -54,6 +54,9 @@ sphinx_examples_as_code_conf = {
         'jupyter': 'Download Jupyter notebook',
         'marimo': 'Download marimo notebook',
     },
+    'script_metadata': False,
+    'dependencies': {},
+    'requires_python': None,
 }
 ```
 
@@ -61,7 +64,7 @@ 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;
@@ -80,6 +83,17 @@ sphinx_examples_as_code_conf = {
   Markdown link in notebooks, and renders inline as `text url` in Python scripts. Plain
   text with no markup at all becomes one comment line per line of text, and
   blank-line-separated paragraphs stay separated.
+- `script_metadata`: `True` adds each download's dependencies and a one-line run
+  command. See [Dependencies and run commands](#dependencies-and-run-commands) below.
+  `False` (default) adds neither.
+- `dependencies`: extra PEP 508 requirements per format, added to the detected ones, e.g.
+  `{'jupyter': ['pyvista[jupyter]']}`. An entry naming a detected project replaces it,
+  so `{'python': ['pyvista>=0.46']}` sets its version. An entry without a version keeps
+  the automatic pin described below. Only used with `script_metadata` on.
+- `requires_python`: a `requires-python` specifier for the dependency block, e.g.
+  `'>=3.10'`. `None` (default) derives one from the dependencies instead; see
+  [Dependencies and run commands](#dependencies-and-run-commands). Only used with
+  `script_metadata` on.
 
 An unrecognized key raises a configuration error at build start.
 
@@ -91,6 +105,46 @@ Overriding a single key from the command line works via a dotted `-D` flag, e.g.
 `-D sphinx_examples_as_code_conf.link_position=bottom` -- this only touches that one
 key, leaving the rest (`conf.py`'s values, or the defaults) alone.
 
+## Dependencies and run commands
+
+With `script_metadata` on, each download lists the third-party projects its code
+imports, plus any `dependencies` set for its format, and says how to run it:
+
+- Python scripts start with a [PEP 723](https://peps.python.org/pep-0723/) `# /// script`
+  block, followed by `# Run this script with: uv run <name>.py`.
+- Jupyter notebooks say `` Open this notebook with: `uvx --python "<requires-python>" --from jupyterlab --with <dependency> ... jupyter-lab <name>.ipynb` `` in their first cell,
+  with `--python` only when there is a `requires-python`. Arguments are double-quoted where
+  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`.
+- Each run command is followed by a line linking to
+  [uv's installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+Imports are read from the code, not run. Each imported top-level module maps to the
+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`.
+
+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
+`<name>>=X.Y`, the installed release's major and minor version, or plain `<name>` for a
+pre-release or dev build.
+
+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.
+  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.
+
+With neither, the line is left out.
+
 ## Conversion rules
 
 What happens to the content of an Examples section:
@@ -135,7 +189,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.7.0 → sphinx_examples_as_code-0.8.1}/pyproject.toml

@@ -32,7 +32,7 @@ classifiers = [
   'Programming Language :: Python :: 3.14',
   'Topic :: Scientific/Engineering :: Visualization',
 ]
-dependencies = ['pyvista>=0.48']
+dependencies = ['packaging>=22', 'pyvista>=0.48']
 description = 'Sphinx extension for converting docstring examples into downloadable code.'
 dynamic = ['version']
 keywords = ['download', 'examples', 'sphinx']