Simon Willison TIL

Using Parseable with Datasette for OpenTelemetry traces

2026-10-06T19:07:31+00:00

Parseable is a brand new observability tool, compatible with OpenTelemetry, for storing and querying observability data.

Datasette 1.0a41 added support for OpenTelemetry tracing, contributed by Alex Garcia.

Here's how I ran the two together, giving me neat local visualizations of traces of Datasette responses.

Installing Parseable

I used the open source release of Parseable from their GitHub releases - I tried v3.2.4. They have a macOS Apple Silicon release (a 171MB download) which I downloaded and ran like so:

curl -fL https://github.com/parseablehq/parseable/releases/download/v3.2.4/Parseable_OSS_aarch64-apple-darwin -o parseable
chmod +x parseable
./parseable local-store

Running ./parseable local-store starts Parseable with all of the default settings, and stores data in ./data and ./staging directories. It uses ports 8000, 8001, and 8002.

Then visit http://localhost:8000/ and sign in with the default admin/admin username and password.

Running Datasette

I fetched a test database for Datasette to use:

wget https://latest.datasette.io/fixtures.db

Then I started Datasette like this:

OTEL_SERVICE_NAME=datasette-local \
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:8000 \
OTEL_EXPORTER_OTLP_TRACES_HEADERS='Authorization=Basic%20YWRtaW46YWRtaW4%3D,X-P-Stream=datasette_traces' \
OTEL_TRACES_EXPORTER=otlp_json_http \
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
uvx --from 'opentelemetry-instrumentation==0.66b1' \
  --with 'opentelemetry-distro==0.66b1' \
  --with 'datasette==1.0a41' \
  --with 'opentelemetry-exporter-otlp-json-http==0.66b1' \
  opentelemetry-instrument datasette fixtures.db -p 8004

Note that we are not starting datasette directly - we are instead starting opentelemetry-instrument datasette ... to properly initialize the tracing.

Viewing a trace

Load up http://localhost:8004/ and click around a bit, then wait a few seconds for the traces to be sent to Parseable. Then navigate to "traces" in the Parseable web interface and you should be able to find things like this:

Each request now has a trace which shows the details of every subsequent SQL query. Consult the Datasette OpenTelemetry docs for more details.

Alternative ports

To run Parseable on ports other than 8000, 8001, and 8002:

P_ADDR=127.0.0.1:18000 ./parseable local-store \
  --grpc-port 18001 \
  --flight-port 18002

You'll need to also update Datasette's environment variable to point at the new port:

OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:18000

Using Blender with coding agents on macOS

2026-09-05T15:42:28+00:00

Modern frontier models have got really good at using Blender. I've been having a lot of fun trying this out recently - models can produce .blend files you can edit in Blender itself, and can also render images and even movies (by rendering a sequence of images and combining them with ffmpeg).

Setting this up, at least on macOS, is really easy. Install the Blender desktop app from blender.org and then tell the coding agent:

Use the already install /Applications/Blender to render a scene of a pelican riding a bicycle

That worked for me with GPT-6 Astra. You can also be a bit more explicit, to save the model some time figuring out how to use it:

Use Blender like this: /Applications/Blender.app/Contents/MacOS/Blender --background --python scene.py

A pelican riding a bicycle with GPT-6 Astra

I used GPT-6 Astra (Medium) in the ChatGPT macOS application, Codex mode:

Use the already install /Applications/Blender to render a scene of a pelican riding a bicycle

2m39s later:

pelican-bicycle.blend, pelican_scene.py

OK add a background and a lot of flair

3m51s later:

pelican-bicycle-festival.blend, pelican_flair.py

OK make it a whole lot better

5m59s later:

pelican-coastal-parade.blend, pelican_final.py

The project lives in this repo, and here's the exported transcript from Codex.

Creating a skill

Codex makes it pretty easy to create skills (using its built-in skill creating skill), so I finished up by prompting:

Create a quick skill that describes how to use the currently installed /Application/Blender based on what you learned

It produced and installed this Markdown skill, which I have since used for further Blender experiments with prompts like this:

Use your Blender Local skill to build this scene (attached image)

Adding a custom MCP server to Claude and ChatGPT

2026-07-29T00:13:18+00:00

I've started exploring MCP in more detail. The web chat UIs for both Claude and ChatGPT can access MCP servers but it's not obvious how to set them up. Here's what I figured out.

I'm using my new unauthenticated MCP for my blog - https://datasette.simonwillison.net/-/mcp - which uses https://github.com/datasette/datasette-mcp to allow the execution of read-only SQL queries against a copy of my site's database.

Claude

Adding an MCP in Claude.ai is quite straight-forward. Start with the + menu next to the chat prompt and navigate through it like this:

The "Add custom connector" modal then contains the necessary fields to add the MCP URL, and optionally configure authentication (I haven't tried this yet):

You can then toggle the new MCP on and off in the Connectors menu, shown above.

ChatGPT

ChatGPT is a whole lot more complicated. First, you need to enable "Developer mode" for your account in the Security and login panel:

Having done that, you can add your new MCP. The button for that is hard to find - it's the "+" icon on the top right of the ChatGPT Plugins directory page:

This gives you the "New Plugin" modal. Apparently an MCP is a "Plugin" in the user-facing ChatGPT UI.

Be sure to set authentication to "No Auth" if the plugin does not need OAuth configured:

Activating the MCP is difficult as well. On web I found I had to click the + icon next to the chat and then type the name of the MCP to search for it, then select it so I could run a prompt:

The first time you do this it will prompt you to enable the MCP:

Then show you this more visually impressive splash screen:

After all of this... it works!

Sadly I was not able to access MCPs from ChatGPT Advanced Voice mode - I was hoping I could connect them to a regular chat and then start voice mode and drive an MCP purely through voice commands, but it looks like they are not available as tools while the voice mode conversation is running.

Using uvx in GitHub Actions in a cache-friendly way

2026-07-14T00:56:20+00:00

I often find myself wanting to run a quick Python tool inside of GitHub Actions using uvx name-of-tool - but I don't want that to result in a network request to PyPI every time the workflow runs. I want the tool to be fetched the first time and then reused from the GitHub Actions cache for subsequent runs.

I've tried unsuccessfully to find patterns I like for this in the past, especially given the standard pattern in GitHub Actions of using the hashed contents of a file - often pyproject.toml or requirements.txt - as a key for the cache.

This is usually a good pattern, but for simple scripts I don't want to have to maintain an additional file just to get the cache to work correctly.

Today (with the help of GPT-5.6 Sol) I finally found a pattern I like.

My goal was to be able to drop uvx name-of-tool into a GitHub Actions workflow anywhere I like, while still trusting that the tool would be cached between builds - and could be cache-invalidated if I needed to.

The key turned out to be the UV_EXCLUDE_NEWER environment variable. This works the same as uvx --exclude-newer DATE, allowing you to tell uv to install the most recent package as-of a specific date.

That date can then also be used as part of the cache key for GitHub Actions! This means you can set the date in the script once and get a repeatable set of installed versions for all of the tools. Then any time you want to bust the cache you can increment the date in that one place:

name: Run tools

on:
  workflow_dispatch:

env:
  # Bump this date to allow newer package releases and a fresh cache:
  UV_EXCLUDE_NEWER: "2026-07-12"

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Install uv and restore cache
        id: setup-uv
        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
        with:
          enable-cache: true
          cache-dependency-glob: ""
          cache-suffix: "tools-${{ env.UV_EXCLUDE_NEWER }}"
          prune-cache: false
    
      - name: Require cache-only uv on cache hits
        if: steps.setup-uv.outputs.cache-hit == 'true'
        run: echo "UV_OFFLINE=1" >> "$GITHUB_ENV"
    
      - name: Run sqlite-utils
        run: uvx sqlite-utils --version
    
      - name: Run datasette
        run: uvx --pre datasette --version
    
      - name: Run LLM
        run: uvx llm --version

astral-sh/setup-uv is Astral's official Action for getting uv. I'm annoyed that it appears to hit Astral's own releases.astral.sh site every time it runs but if that's how they want it to work I guess that's on them.

Those settings:

enable-cache: true turns on GitHub Actions caching
cache-dependency-glob: "" disables the feature where it looks for pyproject.toml or similar to use as a cache key
cache-suffix: "tools-${{ env.UV_EXCLUDE_NEWER }}" is the bit that uses our single UV_EXCLUDE_NEWER value for the cache key
prune-cache: false is necessary because Astral default to deliberately pruning your cache of any downloaded wheels, the exact opposite of what I want!

I should note that my preferences here go directly against what uv advises:

However, in continuous integration environments, persisting pre-built wheels may be undesirable. With uv, it turns out that it's often faster to omit pre-built wheels from the cache (and instead re-download them from the registry on each run).

Personally I'd rather suffer from very slightly slower CI builds (presumably because GitHub's cache restore operations are slower than fresh installations from PyPI?) than optimize my builds by hitting the PyPI CDN for every tool execution.

This block here enforces that the cache is used correctly:

      - name: Require cache-only uv on cache hits
        if: steps.setup-uv.outputs.cache-hit == 'true'
        run: echo "UV_OFFLINE=1" >> "$GITHUB_ENV"

Setting that UV_OFFLINE=1 environment variable causes uvx tool-name to fail if the tool has not been previously installed. We only run that if we got a cache hit from the GitHub Actions cache.

This means that if you add a new tool to the workflow without also bumping the UV_EXCLUDE_NEWER date you'll get an error.

Cloudflare CAPTCHA on at least one ampersand

2026-06-16T00:21:36+00:00

I use Cloudflare's CAPTCHA (they call it a "Managed Challenge") on simonwillison.net/search/ to prevent crawlers from following every single possible combination of my faceted search UI.

This was getting pretty annoying, since I had to wait for the challenge every time I searched my own site.

I don't particularly care about regular ?q=term searches. Where things get messy is if a crawler starts hitting every combination of:

?q=term&type=entry
?q=term&type=entry&year=2006
?q=term&type=entry&year=2006&tag=browsers

etc.

I decided to switch the Cloudflare rules around to activating only on hits to /search/ that included at least one & in the query string section.

Here's what that rule expression looks like:

(http.request.uri.path wildcard r"/search/*" and http.request.uri.query contains "&")

Trying the Cloudflare MCP

I originally tried to figure this out using Claude Code and Cloudflare's MCP server. I got that working by creating a dedicated folder:

mkdir cloudflare-dev
cd cloudflare-dev

And then setting up the MCP so it would only be active for Claude Code sessions started in that folder:

echo '{
  "mcpServers": {
    "cloudflare-api": {
      "type": "http",
      "url": "https://mcp.cloudflare.com/mcp"
    }
  }
}' > .mcp.json
mkdir .claude
echo '{
  "enabledMcpjsonServers": [
    "cloudflare-api"
  ]
}' > .claude/settings.local.json

(I actually set it up by pasting the MCP JSON into Claude Code and saying "set this up to only work in this project folder", but the above is effectively what it did.)

Then I ran claude in the folder and used the /mcp command, selected the Cloudflare MCP and used the authenticate option to jump through an OAuth flow.

... which didn't work, because as far as I can tell Cloudflare's MCP doesn't yet implement tools to view and modify the rules in question.

Claude did suggest using the API instead, but I'd need an API token.

Using the API instead

I created an API token using dash.cloudflare.com/profile/api-tokens.

Cloudflare have a template for "Read all resources", and it turns out you can use that as a starting point.

I flipped the "Zone WAF" one to "Edit" and set the key to expire tomorrow. Then I copied the resulting key into a token.txt file.

(In the Cloudflare dashboard I believe this feature is called "Web Application Firewall > Custom rules".)

Then I let Claude Code handle the rest. Here's a rough version of what it did, assuming a token in a $TOKEN environment variable:

export TOKEN="$(cat token.txt)"
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.cloudflare.com/client/v4/zones?name=simonwillison.net" \
  | jq '{success, errors, zones: [.result[] | {id, name}]}'

This got back the zone ID, which is 2ce4f4f41f239d041e25f8320ad3c3fd.

Then to list the custom WAF rules:

export ZONE="2ce4f4f41f239d041e25f8320ad3c3fd"
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.cloudflare.com/client/v4/zones/$ZONE/rulesets/phases/http_request_firewall_custom/entrypoint" \
  | jq '{success, errors, rules: [.result.rules[]? | {description, action, expression, enabled}]}'

This started with:

{
  "success": true,
  "errors": [],
  "rules": [
    {
      "description": "/search/ extra protection",
      "action": "managed_challenge",
      "expression": "(http.request.uri.path wildcard r\"/search/*\")",
      "enabled": true
    },

To edit that rule via API we need the ruleset ID and the rule ID:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.cloudflare.com/client/v4/zones/$ZONE/rulesets/phases/http_request_firewall_custom/entrypoint" \
  | jq '{ruleset_id: .result.id, rule: (.result.rules[] | select(.description=="/search/ extra protection") | {id, description, action, expression, enabled})}'

Returning:

{
  "ruleset_id": "0682fdbd40cc444cbe1e93d136e2b174",
  "rule": {
    "id": "8b2766d7802e4e988163531670976cb9",
    "description": "/search/ extra protection",
    "action": "managed_challenge",
    "expression": "(http.request.uri.path wildcard r\"/search/*\"",
    "enabled": true
  }
}

And finally we can update that with the new expression:

export RS=0682fdbd40cc444cbe1e93d136e2b174
export RULE=8b2766d7802e4e988163531670976cb9

curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://api.cloudflare.com/client/v4/zones/$ZONE/rulesets/$RS/rules/$RULE" \
  --data '{
    "action": "managed_challenge",
    "expression": "(http.request.uri.path wildcard r\"/search/*\" and http.request.uri.query contains \"&\")",
    "description": "/search/ extra protection",
    "enabled": true
  }'

Setting a custom price for a model in AgentsView

2026-06-09T21:35:31+00:00

I'm a recent convent to AgentsView, Wes McKinney's (previously of Pandas fame) Python toolkit for analyzing transcripts of coding agents from your own computer.

AgentsView can calculate your token spending based on those transcripts, across multiple different coding agents (Claude Code, Codex, Pi and more.)

You can run it via uvx like this to get as ASCII table of spending numbers in your terminal:

uvx agentsview usage daily

Example output:

DATE        INPUT     OUTPUT   CACHE_CR  CACHE_RD    COST      MODELS
----        -----     ------   --------  --------    ----      ------
...
2026-06-04  5248968   387578   149428    78087993    $77.72    gpt-5.5, claude-opus-4-8
2026-06-05  963595    115773   0         8383360     $8.62     gpt-5.5, gpt-5.4-mini, deepseek/deepseek-v4-flash, meta-llama/llama-3.2-3b-instruct:free, nvidia/nemotron-nano-9b-v2:free
2026-06-06  324888    36869    0         3231872     $4.35     gpt-5.5
2026-06-07  669027    46379    0         7486464     $8.48     gpt-5.5
2026-06-08  3346262   253637   0         49214208    $48.95    gpt-5.5
2026-06-09  787043    427018   1098673   78305086    $97.79    claude-fable-5, gpt-5.5, claude-haiku-4-5-20251001
----        -----     ------   --------  --------    ----      ------
TOTAL       73610282  7260576  4399393   1717538611  $1472.87

Anthropic's latest model Claude Fable 5 came out today. The pricing data AgentsView uses doesn't yet include that model.

So I had Claude Fable 5 reverse engineer AgentsView with the following prompt against claude.ai:

Clone https://github.com/kenn-io/agentsview and tell me how I can set a price for a model that it does not know the price of yet

It turns out you can add custom pricing information to your ~/.agentsview/config.toml file. Here's what I added:

[custom_model_pricing."claude-fable-5"]
input = 10.0
output = 50.0
cache_creation = 12.50
cache_read = 1

I think those numbers are right, I got them from this pricing page. Fable is 2x the price of Opus for input and output.

With the config file edited I can run Fable again to get pricing estimates. I used the serve command to get a web application on port 8080:

I've used the equivalent of $82.92 in tokens since getting access to Fable 5 about four and a half hours ago. This is all included in my $100/month Claude Max subscription though, which based on prior experience will likely give me around 10x the token usage compared to if I was paying list price.

Using LLM in the shebang line of a script

2026-05-11T18:48:57+00:00

This comment on Hacker News inspired me to investigate patterns for using my LLM CLI tool in a shebang line:

But seriously, you can put a shebang on an english text file now (if you're sufficiently brave) [...]

LLM can end up installed in all sorts of unpredictable places so the best way to run it is via the #!/usr/bin/env pattern.

Here's how to make English (or Spanish or any other language) text executable via LLM:

#!/usr/bin/env -S llm -f
Generate an SVG of a pelican riding a bicycle

Save this as pelican.sh and make it executable with:

chmod +x pelican.sh

Then run it:

./pelican.sh

Other arguments will be passed through to LLM, so if you want to use a different model:

./pelican.sh -m gpt-5.4-nano

This prompt often returns commentary in addition to an SVG. To extract just the first code block in the response add the -x LLM option:

#!/usr/bin/env -S llm -x -f
Generate an SVG of a pelican riding a bicycle

The -f option needs to come last as it will be passed the path to the script file.

How this works

#!/usr/bin/env -S llm -f

The -S (for split) option to env is required because, without it, the env command will treat the rest of the line as the full name of the command, producing this error:

/usr/bin/env: 'llm -f': No such file or directory

With -S the -f is passed as an argument to LLM, and then the path to the file itself is passed after that:

llm -f path/to/pelican.sh

This takes advantage of LLM's fragments mechanism. The argument to -f is the path to a file, and the contents of that file will then be appended to the prompt.

Adding tools

Scripts like this are a lot more interesting if they can execute tools.

LLM has some default tools which you can try out. Here's how to use the llm_time tool which makes the current time available for the model to call:

#!/usr/bin/env -S llm -T llm_time -f
Write a haiku that mentions the exact current time

I got (at 17:52 UTC):

Whispers of the hour,
Seventeen fifty-two chimes,
Time flows ever on.

Using templates

LLM supports templates - YAML files that can mix a prompt, system prompt, model options, and tool definitions.

These can be used with a shebang line by ending that line with a -t, for example:

#!/usr/bin/env -S llm -t
prompt: Write a haiku
system: Output Spanish

I got this:

Brisa en el bosque,
hojas susurran sueños,
paz en el silencio.

Templates can include parameters, for example:

#!/usr/bin/env -S llm -t
prompt: |
  Two line poem about $animal who lives in $place

This needs to be run like this:

./poem.sh -p animal skunk -p place "hovercraft port"

In hovercraft's hum, where the engines start,
A skunk claims his kingdom, with pride and art.

Templates with tools

The most interesting way to use templates is with embedded tool functions. Here's a simple example of that, saved as calc.sh:

#!/usr/bin/env -S llm -t
model: gpt-5.4-mini
system: |
  Use tools to run calculations
functions: |
  def add(a: int, b: int) -> int:
      return a + b
  def multiply(a: int, b: int) -> int:
      return a * b

Then:

chmod 755 calc.sh
./calc.sh 'what is 2344 * 5252 + 134' --td

Which outputs (thanks to the --td tool debug option):

Tool call: multiply({'a': 2344, 'b': 5252})
  12310688

Tool call: add({'a': 12310688, 'b': 134})
  12310822

2344 × 5252 + 134 = **12,310,822**

Here's a more complex example which defines a tool for searching my blog:

#!/usr/bin/env -S llm -t
model: gpt-5.5
system: |
  You answer questions from Simon Willison's blog
functions: |
  import httpx

  url = "https://datasette.simonwillison.net/simonwillisonblog.json"
  sql = """
  WITH results AS (
    SELECT 'entry' AS type, blog_entry.id AS id, blog_entry.slug AS slug,
           blog_entry.title AS title, blog_entry.created AS created,
           snippet(blog_entry_fts, -1, '<mark>', '</mark>', '…', 100) AS snippet,
           blog_entry_fts.rank AS rank
    FROM blog_entry_fts JOIN blog_entry ON blog_entry.rowid = blog_entry_fts.rowid
    WHERE blog_entry_fts MATCH :q
    UNION ALL
    SELECT 'blogmark', blog_blogmark.id, blog_blogmark.slug,
           blog_blogmark.link_title, blog_blogmark.created,
           snippet(blog_blogmark_fts, -1, '<mark>', '</mark>', '…', 100),
           blog_blogmark_fts.rank
    FROM blog_blogmark_fts JOIN blog_blogmark ON blog_blogmark.rowid = blog_blogmark_fts.rowid
    WHERE blog_blogmark_fts MATCH :q
    UNION ALL
    SELECT 'quotation', blog_quotation.id, blog_quotation.slug,
           blog_quotation.source, blog_quotation.created,
           snippet(blog_quotation_fts, -1, '<mark>', '</mark>', '…', 100),
           blog_quotation_fts.rank
    FROM blog_quotation_fts JOIN blog_quotation ON blog_quotation.rowid = blog_quotation_fts.rowid
    WHERE blog_quotation_fts MATCH :q
    UNION ALL
    SELECT 'note', id, slug, title, created,
           -- crude snippet: ~100 chars around the first match
           -- because notes do not yet have FTS enabled
           '…' || substr(body, max(1, instr(lower(body), lower(:q)) - 40), 200) || '…',
           0.0  -- no real rank available
    FROM blog_note
    WHERE body LIKE '%' || :q || '%' OR title LIKE '%' || :q || '%'
  )
  SELECT snippet FROM results
  ORDER BY rank
  LIMIT 20
  """

  def search_blog(query: str) -> str:
      """Search Simon's blog"""
      return httpx.get(url, params={"sql": sql, "q": query}).text

This sets up a tool called search_blog(query) which then executes an HTTP request against my datasette.simonwillison.net Datasette instance carrying a SQL query that searches various types of content.

Result:

./blog.sh "Has Simon implemented GraphQL?"

Output:

Yes. Simon implemented GraphQL support for Datasette as a plugin called datasette-graphql.

He described it as “a plugin that adds GraphQL query support to Datasette,” and later as a “Datasette plugin providing an automatic GraphQL API for your SQLite databases.” It can expose Datasette tables through GraphQL, including nested fields based on foreign-key relationships.

Here's the full log of that response showing the tool calls that were executed.

SQL functions in Google Sheets to fetch data from Datasette

2026-04-20T02:33:58+00:00

I've been experimenting with ways to fetch data from Datasette and display it in Google Sheets.

I've found three patterns that work so far. importdata() and "named functions" can only fetch from public Datasette instances. Apps Script can fetch from API key protected instances as well.

Using IMPORTDATA()

The easiest way to get this up and running doesn't involve any custom sheets functions at all. The IMPORTDATA() default function can fetch any CSV data from a URL and load it into the sheet - and Datasette exports CSV by default.

https://latest.datasette.io/fixtures/roadside_attractions.csv - the CSV data for the roadside_attractions table.
https://latest.datasette.io/fixtures/-/query.csv?sql=select+pk%2C+name%2C+address%2C+url%2C+latitude%2C+longitude+from+roadside_attractions - a SQL export of a database query, in this case one that returns all rows from that table.

Either of these URLs can be used in a Google Sheets cell like this:

=importdata("https://latest.datasette.io/fixtures/-/query.csv?sql=select+pk%2C+name%2C+address%2C+url%2C+latitude%2C+longitude+from+roadside_attractions&_size=max")

Using a named function

Ideally I'd like to use =sql("SELECT ...") in my spreadsheet cells instead. Google Sheets lets you define new "named functions" on a per-sheet basis, which can use existing Sheets functions and formulas - including importdata().

Go to Data -> Named functions and select "Add new function". Call it SQL and add a single argument placeholder called query, then set the following formula definition:

=IMPORTDATA(
  "https://latest.datasette.io/fixtures/-/query.csv?sql=" &
  ENCODEURL(query)
)

Now you can use =SQL("select * from roadside_attractions") in a cell to execute that SQL query and load in the CSV data:

Using Apps Script

There's one big downside of importdata() or a named function built on top of it: only unauthenticated URLs to CSV exports are supported. If your Datasette instance is protected by authentication and requires API keys to be sent as HTTP headers you will not be able to use them.

(importdata() can work fine here if the API key is a query string argument though. Here's how to enable that using the datasette-auth-tokens plugin.)

Apps Script lets you define custom server-side JavaScript functions which can then be called from a Google Sheets cell. These can be a lot more flexible, including sending API tokens in HTTP headers.

To create an Apps Script for a spreadsheet, use "Extensions -> Apps Script". This will start you on a code editor with a Code.gs file that you can edit. Here's a function definition for a =datasette_sql(query) custom function:

function datasette_sql(query) {
  var baseUrl = 'https://latest.datasette.io/fixtures'
  var token = '';

  // Strip a trailing slash so we control the join
  baseUrl = baseUrl.replace(/\/+$/, "");

  var url = baseUrl + "/-/query.json?sql=" + encodeURIComponent(query);

  var options = { muteHttpExceptions: true };
  if (token) {
    options.headers = { Authorization: "Bearer " + token };
  }

  var response = UrlFetchApp.fetch(url, options);
  var json = JSON.parse(response.getContentText());

  if (!json.ok) {
    throw new Error(json.error || "Query failed");
  }

  var rows = json.rows;
  if (!rows || rows.length === 0) return [["No results"]];

  var cols = Object.keys(rows[0]);
  var result = [cols];

  for (var i = 0; i < rows.length; i++) {
    var row = [];
    for (var j = 0; j < cols.length; j++) {
      var val = rows[i][cols[j]];
      row.push(val === null ? "" : val);
    }
    result.push(row);
  }

  return result;
}

You can set the base URL and an optional API token in variables at the top of the script.

You can ignore that "Deploy" button entirely, it's not necessary for custom functions for sheets. I had to hit the Command+S key combination to save my changes - confusingly I could not find a "save" button in the editor UI.

Apps Script has a script and document properties mechanism which theoretically could be used to keep secret values separate from that code, but I wasn't able to get that to work without confusing permission dialogs popping up.

As far as I can tell users who have "view" permission but not "edit" permission on the spreadsheet are unable to view the source code, so it should be safe to keep read-only API tokens in the source code even for shared spreadsheets.

I've prepared this demo sheet showing all three of the above solutions - importdata(), a named sql() function and a datasette_sql() function defined using Apps Script.

Running OpenClaw in Docker

2026-02-01T23:59:07+00:00

I'm not brave enough to run OpenClaw (aka Clawdbot aka Moltbot) directly on my Mac, so I decided to try running it in a Docker instead container.

OpenClaw has Docker support out of the box, described on this page of their documentation. Here's what worked for me.

Use their Docker Compose configuration

First, clone their GitHub repository:

git clone https://github.com/openclaw/openclaw

It contains a script for running OpenClaw in Docker called docker-setup.sh which in turn uses Docker Compose and their docker-compose.yml file.

The script will create two folders directly on your Mac which will then be mounted as volumes in the Docker container:

~/.openclaw is the configuration directory. This will eventually contain OpenClaw memory, configuration, third party API keys, etc.
~/openclaw/workspace is the workspace directory full of files that are directly available to the agent as it runs inside the container. Files the agent creates will be saved here too.

Answering all of those questions

On first run OpenClaw asks you a lot of questions. Most of these are reasonably obvious but I still had to start over a couple of times to get everything right. Some that I found tricky:

Onboarding mode: manual
What do you want to set up?: Local gateway (this machine)
Model provider. I decided to go for OpenAI Codex with ChatGPT OAuth, which then allowed me to authenticate against ChatGPT to spend tokens already covered by my $20/month OpenAI subscription. I did this because I've heard that OpenClaw can spend a lot of tokens on API plans, and using ChatGPT put an easy upper limit on how much it could spend. When you opt for this OpenClaw gives you a URL to open in your browser which redirects back to a non-running localhost service and displays an error message - you then copy and paste that localhost URL back into OpenClaw to complete the authentication. Here's what that looks like.
Tailscale: I tried to configure this the first time and it resulted in a machine I couldn't use, so the second time I said "no".

Once it's up and running you can run:

docker ps

To see the container. Mine is running the image openclaw:local and has a container name openclaw-openclaw-gateway-1.

Running administrative commands

The other container provided by Docker Compose is called openclaw-cli and can be used to run the openclaw CLI commands for managing the instance.

This works for that, but you must run it in the same folder as that docker-compose.yml file.

docker compose run --rm openclaw-cli status

Setting up a Telegram bot

OpenClaw can communicate via a number of different messaging platforms, including WhatsApp and iMessage and Telegram and Slack and Discord. This means you can control the instance in your container directly from your phone.

I decided Telegram looked like the least hassle to set up.

You'll need a Telegram account. Then create a new bot by chatting to @BotFather on Telegram.

Start a chat with @BotFather
Send the command /newbot
Follow the instructions to name your bot and get a token

That token can then be provided to OpenClaw as part of the initial setup wizard.

There's one remaining step: you have to pair your Telegram account with your new bot and your OpenClaw instance.

OpenClaw will send you a message via Telegram with the pairing code, then run this:

docker compose run --rm openclaw-cli pairing approve telegram <CODE>

At this point you should be able to message your bot directly from Telegram on your phone!

Accessing the web UI

OpenClaw runs a default web UI on port 18789. If you access this directly at http://localhost:18789 you'll see an error telling you that you need to authenticate first.

To do that you need a special ?token=... URL parameter. This may have been displayed during setup, but if you lose it you can get a new one like this:

docker compose run --rm openclaw-cli dashboard --no-open

Follew the URL that spits out to access the interface.

Sometimes that's not enough either - you may see this error:

disconnected (1008): pairing required

For some reason the openclaw-cli container didn't work for me here, but this alternative way of running the openclaw commands did:

docker compose exec openclaw-gateway \
  node dist/index.js devices list

That shows a list of pairings, hopefully including a request that is not yet approved like this one:

Pending (1)
┌──────────────────────────────────────┬───────────────────────────────────┬──────────┬────────────┬────────┬────────┐
│ Request                              │ Device                            │ Role     │ IP         │ Age    │ Flags  │
├──────────────────────────────────────┼───────────────────────────────────┼──────────┼────────────┼────────┼────────┤
│ 6f9db1bd-a1cc-4d3f-b643-2c195262464e │ 8b7bbf4f69633058dc3beee8a56adbccf │ operator │ 172.18.0.1 │ 2m ago │        │
│                                      │ aafc8be8058bea8a06be1cb7bfad9b3   │          │            │        │        │
└──────────────────────────────────────┴───────────────────────────────────┴──────────┴────────────┴────────┴────────┘

To approve that, run this command:

docker compose exec openclaw-gateway \
  node dist/index.js devices approve \
  6f9db1bd-a1cc-4d3f-b643-2c195262464e

The dashboard UI looks like this, and has a whole load of different debugging tools plus a web chat interface:

Running commands as root

I found myself wanting to install some extra packages, but the OpenClaw bot itself runs as a user without sudo access (probably for the best!)

You can access a Bash shell as root like this:

docker compose exec -u root openclaw-gateway bash

I installed extra packages there like this:

apt-get update && apt-get install -y ripgrep

Cloudflare response header transform rules

2026-01-23T15:08:25+00:00

I serve Python files from my tools.simonwillison.net subdomain, which is a GitHub Pages site that's served via Cloudflare. For example:

https://tools.simonwillison.net/python/q3_tts.py

This is meant to be used with uv as described here:

uv run https://tools.simonwillison.net/python/q3_tts.py \
  'I am a pirate, give me your gold!' \
  -i 'gruff voice' -o pirate.wav

By default files with .py extensions are served with a content-type: application/octet-stream header. This means browsers will download them rather than displaying them directly to the user.

For code that you're going to execute on your machine it's nice to be able to preview it in your browser first!

Here's that default content-type header:

~ % curl -I 'https://tools.simonwillison.net/python/q3_tts.py'
HTTP/2 200 
date: Fri, 23 Jan 2026 14:52:54 GMT
content-type: application/octet-stream

I can't control how GitHub Pages serves files, but since the site is behind Cloudflare I can fix the problem there instead.

Navigating the Cloudflare dashboard

The area to look for here is called "Rules". Within that area the "Create rule" button has an option to create a "Response Header Transform Rule":

I created a rule that looks like this:

The response header transform rule

My new rule has the following settings:

Rule name: tools.simonwillison.net .py files to text/plain
When incoming requests match: Custom filter expression
Filter expression:
- Hostname equals tools.simonwillison.net
- AND URI Path ends with .py
Then:
- Set static content-type to text/plain; charset=utf-8

I clicked 'Deploy' and within a few seconds saw this result:

~ % curl -I 'https://tools.simonwillison.net/python/q3_tts.py'
HTTP/2 200 
date: Fri, 23 Jan 2026 14:52:58 GMT
content-type: text/plain; charset=utf-8

And now https://tools.simonwillison.net/python/q3_tts.py displays the Python code directly in my browser.

Previewing Claude Code for web branches with GitHub Pages

2026-01-22T16:43:41+00:00

I'm a big user of Claude Code on the web, Anthropic's poorly named cloud-based version of Claude Code which can be driven via the web or their native mobile and desktop applications.

I mostly use it through the Claude iPhone app.

The biggest downside of this way of working is that, beyond CLI tools or code libraries, it's difficult to preview its work while it is iterating on the code.

I've started using GitHub Pages against private repositories to work around this limitation recently - at least for HTML projects - and it's working really well.

Here's how I'll spin up a new experimental prototype such that I can preview it on my phone.

Create a new private repository at https://github.com/new - include an empty README here to ensure the repo has been initialized.
Start a task in Claude Code against that repo - you may need to restart the app to ensure it picks up the newly created repo.
Tell Claude Code what to build, using a variation on "self-contained HTML file, vanilla JavaScript, no build step, load any dependencies from a CDN" - this ensures that the code it writes will run directly in a browser without needing to mess with npm

Claude Code will get to work, and after a few minutes will create a branch in your repository. Here's the clever bit:

Navigate to the Pages area of your repository settings, make sure "Deploy from a branch" is selected (the default) and then open the branch picker and select the claude/... branch that Claude Code just created

Wait about a minute for the deploy to complete and your new preview should become available at this (secret) URL:

https://your-username.github.io/your-repo/index.html

This will serve the full static contents of your repository so you can also reuse the same private repository for other projects like this in the future, though you'll have to manually select the new branch that Claude creates each time.

Crucially, your Claude Code for web session is still running. You can request changes from Claude - and even drop in screenshots of what it's built so far - and Claude will make changes and then push them to the existing branch, which means they'll be available in your preview shortly afterwards.

I've not found a limit on how long these Claude sessions stay available - it's possible you could keep that session and PR running indefinitely, continually pushing changes to your deployed environment for many weeks to come.

When you land the PR don't forget to update the Pages settings to point back to the main branch.

Unlike Claude's own Artifacts feature there are no CSP restrictions on what apps deployed to GitHub Pages can do, which means they can interact directly with JSON APIs hosted on other domains.

There are other good options for deploying previews of branches - I've used Cloudflare Pages for this in the past - but it's nice to be able to get this done using GitHub alone.

Taking Neon I at the Crucible

2026-01-11T17:34:29+00:00

I took the Neon I intensive week-long evening class at the Crucible in Oakland, with teachers Dan Kuppe and Kat. I learned to make a neon sign! It's still awaiting final infusion of gas, but I'll share photos here once it's finished.

Here's much of what I learned, at least the parts that can be translated into text.

At the Neon 1 level, the craft is almost entirely around making shapes out of glass. The starting point is lengths of glass tubes - I think ours were 10mm in diameter and 4 feet long.

The way you make those shapes is by heating up and bending that glass, using a variety of gas torches.

This can be done mostly by naked hand - protective gloves weren’t necessary for the bends that we made.

You hold the glass over the gas flame and rotate it constantly to ensure it is equally warmed. Then after som time - usually 15-30s - the glass becomes malleable enough that you can bend it.

The key trick to getting the right bend is heating the right section of the glass. For a tight corner you heat just the very short segment that will form the corner. For a long curve you heat the section that will be part of the curve.

Bending the glass upwards is more effective than bending it downwards - you can use gravity to help, especially useful for larger curves where the glass will naturally sag once it hits the right temperature.

For corners you need to ensure the glass both stays sealed but has a hole that the neon can flow through later. You can help achieve this by blowing air into the glass tube, using a stopper at one end and a rubber hose attached to a mouthpiece at the other.

In a Jedi-make-their-own-lightsabers move, we created our own mouthpieces for the hose by putting a 90 degree bend in a thin tube and then heating and flaring out the end using a torch and a file. I dropped one of these and had to make another one.

It is crucial you don’t blow into the glass while it is in the flame because it is likely to burst! Instead you blow when the glass has just come out of the flame but is still hot - this can visibly affect the shape of the bend you are making. The goal is to have as close to a round hole in the center of the pipe as possible, although even a misinformed oval will still be OK as long as air (and eventually neon) can flow through it.

The best way to achieve a specific shape is to draw it precisely on paper, then cover that paper with a wire mesh so you can drop the glass onto it while it’s still malleable and form it to match the illustration. If you forget the mesh (I did that once) your paper will catch fire!

A tricky skill is planning out the sequence of bends that you will perform on a piece of glass. I haven’t developed a good instinct for this yet. You need to consider the rotation of the glass on the burner - if you create the wrong corners too early you won’t be able to safely position it on the gas such that you can rotate it without burning your hand or getting the glass caught on the apparatus.

Cutting the glass is quite easy: score one edge with a file and then tap it firmly such that it breaks. Some of my breaks were clean and others were jagged, and I’m not sure why but people with better technique consistently achieved clean breaks.

By far the hardest technique (for me at least) was welding. This is when you have two glass tubes and you wish to join them together as if they are one - important for combining pieces of the right shape, fixing breaks and attaching the electrodes at the end (more on that below).

To weld you wedge one glass piece firmly on a table with weights such that the end you attach to protrudes over the edge. Then you align the other glass piece with it and use a hand-held torch to rotate around and heat the ends of the glass tubes - keeping them about half a centimeter away from each other.

Once they are hot enough you kiss them together, then continue to heat the junction to get it malleable. Then you remove the heat and blow down the tube while stretching it out a little to try to get a clean merged section - ideally looking as close to a regular tube of glass as possible.

Doing this requires depth perception and a lot of practice. I only have one working eye, which usually doesn’t affect me much but turns out to make welding incredibly hard do to the need to align two glass tubes and a hand torch all at the same time.

The final step is to attach electrodes to the ends of your glass segments. These come as short glass tubes with wires coming out of them, which you weld onto the ends.

One of those electrodes will have a thin glass tube protruding from the end. This is used later on to insert the neon (or argon) gas as the final part of the process.

A few more miscellaneous tips I picked up:

The final piece should not have two glass tubes touching each other as this can cause arcs to interfere with each other. A thin layer of silicon between the tubes fixes this.
Neon comes out orange, argon comes out purple. There are colored glasses that can achieve other colors but we didn’t use these in our beginners’ class.
It’s important to wrap your rubber hose around your arm in a way that avoids it coming into contact with the burner or hot glass.
Use wooden paddles to help flatten glass shapes while they are still warm. Using cold metal can cause the glass to weaken or fracture.

Downloading archived Git repositories from archive.softwareheritage.org

2025-12-30T23:43:48+00:00

Last February I blogged about a neat script called sqlite-s3vfs which was released as MIT licensed open source by the UK government's Department for Business and Trade.

I went looking for it today and found that the github.com/uktrade/sqlite-s3vfs repository is now a 404.

Since this is taxpayer-funded software and was released MIT I felt a moral obligation to try and restore the repository!

My restored copy can be found at github.com/simonw/sqlite-s3vfs. Here's how I made it.

Claude suggested trying the Software Heritage archive and sure enough a search for https://github.com/uktrade/sqlite-s3vfs on their site resolved to this archived page, which appeared to have a full copy of the repo.

Downloading a snapshot of the most recent state was easy enough, but I wanted the full Git history. I stumbled across this Hacker News comment which helped me figure out the right way to do this.

Software Heritage have all sorts of different IDs. The ID that worked for me was something they call a "snapshot ID". I found this in their "Permalinks" sidebar under the "snapshot" tag:

It started swh:1:snp: - the ID for this repository was:

swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf

You can then make an API call to request a Git bundle for that snapshot:

curl -XPOST 'https://archive.softwareheritage.org/api/1/vault/git-bare/swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf/'

This returned JSON that looks like this:

{
  "fetch_url": "https://archive.softwareheritage.org/api/1/vault/git-bare/swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf/raw/",
  "progress_message": null,
  "id": 417949633,
  "status": "done",
  "swhid": "swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf"
}

That fetch_url is what you need to download the Git bundle as a .tar.gz file. It redirects to blob storage so you need to use -L with curl:

curl -L -o bundle.tar.gz 'https://archive.softwareheritage.org/api/1/vault/git-bare/swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf/raw/'

Then decompress it:

tar -xzvf bundle.tar.gz

The result starts like this:

x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/HEAD
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/branches/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/config
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/description
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/hooks/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/info/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/info/exclude
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/info/refs
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/objects/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/objects/info/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/objects/info/packs
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/objects/pack/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/objects/pack/pack-9946e5e52f40fd1df3352da074f9ac059e87ca9d.idx
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/objects/pack/pack-9946e5e52f40fd1df3352da074f9ac059e87ca9d.pack
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/heads/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/heads/dependabot/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/heads/dependabot/github_actions/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/heads/dependabot/github_actions/dot-github/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/heads/dependabot/github_actions/dot-github/workflows/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/heads/dependabot/github_actions/dot-github/workflows/actions/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/heads/dependabot/github_actions/dot-github/workflows/actions/download-artifact-4.1.7
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/heads/main
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/pull/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/pull/11/
x swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git/refs/pull/11/head
...

That swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git is a bare Git repository. You can clone it into a usable working copy like this:

git clone swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git sqlite-s3vfs

I created an empty repo on GitHub and ran these commands to push everything up:

cd sqlite-s3vfs
git remote set-url origin git@github.com:simonw/sqlite-s3vfs.git
git push --all origin
git push --tags origin

I had to use set-url because the original origin was that /tmp/swh:1:snp:1930ecd7bcc8c8666c721c4def3944c98d650abf.git local path.

Building an HTML tool to make this easier in the future

It turns out all of the relevant APIs are unauthenticated and support CORS headers, so I had Claude Code build me a page for automating part of this process in the future:

https://tools.simonwillison.net/software-heritage-repo

Here's that tool with the old GitHub repo URL pre-filled, just click the button:

https://tools.simonwillison.net/software-heritage-repo#https%3A%2F%2Fgithub.com%2Fuktrade%2Fsqlite-s3vfs

And here's the Claude Code transcript I used to build this.

Subtests in pytest 9.0.0+

2025-12-05T05:44:04+00:00

pytest 9.0.0 was released on November 8th 2025. I just got around to looking at the release notes and the biggest new feature is subtests, previously available as the separate pytest-subtests plugin.

I copied the documentation into Claude Code and told it to find a good place to try them in the Datasette test suite. It suggested tests/test_docs.py, which currently make heavy use of the @pytest.mark.parametrize mechanism. I wrote about how that works a few years ago in Documentation unit tests - here's an example test:

@pytest.mark.parametrize("setting", app.SETTINGS)
def test_settings_are_documented(settings_headings, setting):
    assert setting.name in settings_headings

Understanding subtests

The idea behind subtests is to allow a test to programatically create new subtest within itself at runtime.

My above example does the same thing using @pytest.mark.parametrize - but it relies on the list of settings being known at test collection time. This might not be possible for things that need to be introspected after the test has run some initial setup code.

Here's the above test ported to use subtests instead:

def test_settings_are_documented(settings_headings, subtests):
    for setting in app.SETTINGS:
        with subtests.test(setting=setting.name):
            assert setting.name in settings_headings

subtests is a new default pytest fixture - if you list that as a parameter to your test function you can use it in the body of the test.

Using with subtests.test(...) creates a new subtest. Here I'm doing that in a loop. The keyword arguments passed to subtests.test() are used to identify the subtest in the test report.

That's all it takes! Here's a commit that ported several of my parameterized tests to use subtests instead.

How subtests differ from parametrize

If you use @pytest.mark.parametrize pytest will behave as if every one of your parameter combinations is a separate test function. Running the old pytest tests/test_docs.py tests looked like this:

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.0.1, pluggy-1.6.0
SQLite: 3.50.4
rootdir: /private/tmp/datasette
configfile: pytest.ini
plugins: anyio-4.12.0, xdist-3.8.0, timeout-2.4.0, asyncio-1.3.0
asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
collected 120 items                                                            

tests/test_docs.py ..................................................... [ 44%]
...................................................................      [100%]

============================= 120 passed in 0.84s ==============================

Porting to subtests causes each test to be reported just once:

...
collected 9 items                                                             

tests/test_docs.py .........                                            [100%]

============================== 9 passed in 0.15s ==============================

But... if you add -v for verbose output you get back a report that does include every subtest. Truncated, that looks like this:

...
collected 9 items                                                                                                

tests/test_docs.py::test_settings_are_documented SUBPASSED(setting='default_page_size')                    [ 11%]
tests/test_docs.py::test_settings_are_documented SUBPASSED(setting='max_returned_rows')                    [ 11%]
...
tests/test_docs.py::test_settings_are_documented PASSED                                                    [ 11%]
tests/test_docs.py::test_plugin_hooks_are_documented SUBPASSED(plugin='actor_from_request')                [ 22%]
tests/test_docs.py::test_plugin_hooks_are_documented SUBPASSED(plugin='actors_from_ids')                   [ 22%]
tests/test_docs.py::test_plugin_hooks_are_documented PASSED                                                [ 22%]...

...
tests/test_docs.py::test_rst_heading_underlines_match_title_length PASSED                                  [ 66%]
tests/test_docs.py::test_homepage PASSED                                                                   [ 77%]
tests/test_docs.py::test_actor_is_null PASSED                                                              [ 88%]
tests/test_docs.py::test_signed_cookie_actor PASSED                                                        [100%]

============================== 9 passed, 116 subtests passed in 0.15s ==============================

The last line shows how many subtests passed in addition to how many tests.

It looks to me like subtests run substantially faster than the eqpuivalent parameterized tests. I'm more interested in the fact that subtests can now be programatically generated at runtime based on test setup code.

Dependency groups and uv run

2025-12-03T04:55:17+00:00

I've adopted a new (to me) pattern for my Python projects to make them easier to hack on using uv run. I'm using a PEP 735 dependency group called dev to declare my development dependencies - in particular pytest - such that running uv run pytest executes the tests for my project without me having to even think about setting up a virtual environment first.

Here's the pattern I'm using. I start by creating a new library using uv init --lib like this:

mkdir my-new-library
cd my-new-library
uv init --lib

This creates a pyproject.toml file like this:

[project]
name = "my-new-library"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
    { name = "Simon Willison", email = "...@gmail.com" }
]
requires-python = ">=3.10"
dependencies = []

[build-system]
requires = ["uv_build>=0.9.15,<0.10.0"]
build-backend = "uv_build"

It also creates a src/my_new_library/__init__.py file with a hello() example function.

Next, I add pytest as a development dependency using this command:

uv add --dev pytest

Doing so adds a new section to the end of that pyproject.toml file:

[dependency-groups]
dev = [
    "pytest>=9.0.1",
]

This also creates the virtual environment in .venv and uv.lock file, but we don't need to think about those.

Then I create a test:

mkdir tests
echo  'from my_new_library import hello

def test_hello():
    assert hello() == "Hello from my-new-library!"' > tests/test_my_new_library.py

Now I can run that test suite using:

uv run pytest

The dev dependency group is a special case for uv run - it will always install those dependencies as well such that commands like pytest can work correctly.

When you package a project for distribution the dev dependencies will not be automatically installed for users of your package.

The importance of [build-system] for specifying a package

That [build-system] section is crucial, because it tells uv that the directory should be treated as a "package". This means that when uv run executes it installs the current directory as an editable package in the virtual environment.

Removing [build-system] and then rm -rf .venv to delete the virtual environment results in the following error when trying to run uv run pytest:

________________ ERROR collecting tests/test_my_new_library.py _________________
ImportError while importing test module '/private/tmp/my-new-library/tests/test_my_new_library.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/opt/homebrew/Caskroom/miniconda/base/lib/python3.10/importlib/__init__.py:126: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/test_my_new_library.py:1: in <module>
    from my_new_library import hello
E   ModuleNotFoundError: No module named 'my_new_library'
=========================== short test summary info ============================
ERROR tests/test_my_new_library.py
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
=============================== 1 error in 0.07s ===============================

Adding the [build-system] section back in gets rid of this error.

There's an alternative to having a [build-system] section, which is to add this to the pyproject.toml file instead:

[tool.uv]
package = true

I had Claude Code investigate this and it found this section of code explaining what's going on:

pub fn is_package(&self, require_build_system: bool) -> bool {
    // If `tool.uv.package` is set, defer to that explicit setting.
    if let Some(is_package) = self.tool_uv_package() {
        return is_package;
    }
    // Otherwise, a project is assumed to be a package if `build-system` is present.
    self.build_system.is_some() || !require_build_system
}

So there's no need to use that [tool.uv] section if you already have a [build-system] section.

Installation in CI

If you're still using regular pip in your CI scripts you'll need to ensure the dev dependency group is installed like this:

pip install . --group dev

The end result

Projects that use this pattern become a whole lot easier for other people to hack on. I first used this for my datasette-extract package, with the result that checking out and running the tests is now a case of running just the following commands:

git clone https://github.com/datasette/datasette-extract
cd datasette-extract
uv run pytest

No need to think about virtual environments or development dependencies - this just works.

Building a distributable wheel of the project is a one-liner as well:

uv build

This creates two files:

dist/datasette_extract-0.2a0-py3-none-any.whl
dist/datasette_extract-0.2a0.tar.gz

The .tar.gz file should contain everything including the tests - the .whl file should contain just the non-development Python code.

Bonus tip: defining dev in terms of other dependency groups

The dev group is a special case: tools like uv run will install everything in that group automatically.

What if you want to divide up your dependencies into test dependencies, documentation dependencies and so on?

Thanks to Martín Gaitán's python-package-copier-template I learned about this pattern for defining dev in terms of other groups:

[dependency-groups]
test = [
    "pytest",
    "pytest-asyncio"
]
docs = [
    "sphinx"
]
dev = [
    { include-group = "test" },
    { include-group = "docs" }
]

Now if you just want to use the test dependencies you can run this:

uv run --group test pytest