From 2203c0f0815b567b792588409f31017ad8e86bcd Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Tue, 17 Nov 2026 18:09:30 +0100 Subject: [PATCH 1/2] docs: run a Click or Typer command line tool, and PyPI name spellings Co-Authored-By: Claude Opus 5.5 --- docs/src/content/docs/features/run-code.mdx | 33 ++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/features/run-code.mdx b/docs/src/content/docs/features/run-code.mdx index cebd7bd..59c4e68 100644 --- a/docs/src/content/docs/features/run-code.mdx +++ b/docs/src/content/docs/features/run-code.mdx @@ -65,7 +65,9 @@ The Python runtime reads the `import` lines of the code before it runs it, and i 1. Packages that are part of Pyodide install from the Pyodide CDN. Pyodide has about 350 packages, such as NumPy, pandas, SciPy and scikit-learn. The [Pyodide package list](https://pyodide.org/en/stable/usage/packages-in-pyodide.html) has them all. 2. Other imports install from [PyPI](https://pypi.org/) with [micropip](https://micropip.pyodide.org/), under the name of the import. This works for pure Python packages: packages with a wheel that ends in `py3-none-any.whl`. -When the package name is not the import name, add `runnable.packages` to the fence line. For example, `import slugify` needs the `python-slugify` package. Without the attribute, the runtime would install the package called `slugify`, which is a different one. Separate several packages with spaces. A name can have a version, such as `tabulate==0.9.0`. The packages install before the code runs, and a package that does not install shows an error in the panel. +PyPI reads `_`, `-` and `.` in a package name as the same character, and ignores case. So `import rich_click` installs the `rich-click` package, with no attribute. + +When the package name is a different name, not only a different spelling, add `runnable.packages` to the fence line. For example, `import slugify` needs the `python-slugify` package. Without the attribute, the runtime would install the package called `slugify`, which is a different one. Separate several packages with spaces. A name can have a version, such as `tabulate==0.9.0`. The packages install before the code runs, and a package that does not install shows an error in the panel. For code that cannot run in the browser, such as a command line tool, write its output in the block. The lines after `[!output]` are the output. They leave the code, and the button prints them a line at a time, as if the code ran. `[!output end]` ends the output, for code after it. Without it, the output goes to the next `[!run]` line or the end of the block. @@ -186,6 +188,35 @@ print(slugify("Hello, World: Run Code!")) +### A command line tool + +A [Click](https://click.palletsprojects.com/) command reads `sys.argv` and calls `sys.exit()` when it finishes. In a code block, give it the arguments as a list, and add `standalone_mode=False`, so that it returns instead of exiting. Without it, the panel shows a `SystemExit` traceback, also for `--help`. The `COLUMNS` environment variable sets the width of the help text. The output panel is not a terminal, so without it Click and Rich use 80 columns, which can be wider than the panel: + +export const cli = ` +\`\`\`py runnable +import os + +os.environ["COLUMNS"] = "60" + +import click + +@click.command() +@click.option("--count", default=1, help="Number of greetings.") +@click.argument("name") +def hello(count, name): + """Greet NAME, COUNT times.""" + for _ in range(count): + click.echo(f"Hello, {name}!") + +hello(["--help"], prog_name="hello", standalone_mode=False) +hello(["--count", "2", "Ada"], prog_name="hello", standalone_mode=False) +\`\`\` +`; + + + +`prog_name` sets the command name in the usage line. Without it, the usage line has no command name in the browser. A [Typer](https://typer.tiangolo.com/) app takes the same arguments: `app(["--help"], prog_name="hello", standalone_mode=False)`. Its help text needs two packages that Pyodide does not install with Rich, so add `runnable.packages="markdown-it-py pygments"` to the fence line. Hide the set-up lines with [hidden lines](/starlight-codeblocks/features/hidden-lines/), and use [`runnable.outputLang=ansi`](#output-in-a-language) with `FORCE_COLOR` for the colours of [rich-click](https://ewels.github.io/rich-click/) or Typer. + ### An error An error in Python shows the traceback, from the line of the example that failed: From fb2beb27574ecea6d939372a21ead6119673a8a4 Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Wed, 18 Nov 2026 09:17:54 +0100 Subject: [PATCH 2/2] docs: remove the command line tool example, which #43 replaces, and add PyPI spellings to the skill Co-Authored-By: Claude Opus 5.5 --- docs/src/content/docs/features/run-code.mdx | 29 ------------------- .../references/copy-and-run.md | 2 +- 2 files changed, 1 insertion(+), 30 deletions(-) diff --git a/docs/src/content/docs/features/run-code.mdx b/docs/src/content/docs/features/run-code.mdx index 59c4e68..951b361 100644 --- a/docs/src/content/docs/features/run-code.mdx +++ b/docs/src/content/docs/features/run-code.mdx @@ -188,35 +188,6 @@ print(slugify("Hello, World: Run Code!")) -### A command line tool - -A [Click](https://click.palletsprojects.com/) command reads `sys.argv` and calls `sys.exit()` when it finishes. In a code block, give it the arguments as a list, and add `standalone_mode=False`, so that it returns instead of exiting. Without it, the panel shows a `SystemExit` traceback, also for `--help`. The `COLUMNS` environment variable sets the width of the help text. The output panel is not a terminal, so without it Click and Rich use 80 columns, which can be wider than the panel: - -export const cli = ` -\`\`\`py runnable -import os - -os.environ["COLUMNS"] = "60" - -import click - -@click.command() -@click.option("--count", default=1, help="Number of greetings.") -@click.argument("name") -def hello(count, name): - """Greet NAME, COUNT times.""" - for _ in range(count): - click.echo(f"Hello, {name}!") - -hello(["--help"], prog_name="hello", standalone_mode=False) -hello(["--count", "2", "Ada"], prog_name="hello", standalone_mode=False) -\`\`\` -`; - - - -`prog_name` sets the command name in the usage line. Without it, the usage line has no command name in the browser. A [Typer](https://typer.tiangolo.com/) app takes the same arguments: `app(["--help"], prog_name="hello", standalone_mode=False)`. Its help text needs two packages that Pyodide does not install with Rich, so add `runnable.packages="markdown-it-py pygments"` to the fence line. Hide the set-up lines with [hidden lines](/starlight-codeblocks/features/hidden-lines/), and use [`runnable.outputLang=ansi`](#output-in-a-language) with `FORCE_COLOR` for the colours of [rich-click](https://ewels.github.io/rich-click/) or Typer. - ### An error An error in Python shows the traceback, from the line of the example that failed: diff --git a/skills/starlight-codeblocks/references/copy-and-run.md b/skills/starlight-codeblocks/references/copy-and-run.md index f6c5e3c..b63e0eb 100644 --- a/skills/starlight-codeblocks/references/copy-and-run.md +++ b/skills/starlight-codeblocks/references/copy-and-run.md @@ -127,6 +127,6 @@ Hello world! ERROR ~ Error executing process > 'sayHello' # [!code error] ``` ```` -- Python packages: the runtime reads the `import` lines and installs Pyodide's packages (NumPy, pandas and about 350 more). It installs any other import from PyPI with micropip, under the import name. PyPI packages must be pure Python. When the package name differs from the import name, name it: ` ```py runnable runnable.packages="python-slugify" ` for `import slugify`. Separate several names with spaces; `name==1.2` pins a version. +- Python packages: the runtime reads the `import` lines and installs Pyodide's packages (NumPy, pandas and about 350 more). It installs any other import from PyPI with micropip, under the import name. PyPI reads `_`, `-` and `.` as the same character and ignores case, so `import rich_click` installs `rich-click`. PyPI packages must be pure Python. When the package name differs from the import name, name it: ` ```py runnable runnable.packages="python-slugify" ` for `import slugify`. Separate several names with spaces; `name==1.2` pins a version. - Options: `runnable.timeout` (default `10000` ms), `runnable.button` and `runnable.outputDelay` set the defaults for blocks. `runnable.outputLabel: true` shows an **Output** label above the output. `runnable.runtimes` is a map of language to a runtime module (a package path or a path from the project root). To wrap or replace a built-in runtime, import it from `starlight-codeblocks/runtimes/pyodide`, `/javascript` or `/typescript`. Guide: https://ewels.github.io/starlight-codeblocks/extend/add-a-runtime/ - Limits: Pyodide loads from the jsDelivr CDN and packages from PyPI. Every runtime runs its worker from a `blob:` URL. A Content Security Policy must allow all three. Without JavaScript, the button is hidden.