Twoslash Python

LSP-powered type information for Python code blocks, built on Shiki.

Live Demo

Hover over symbols in the code block below to see type signatures and documentation.

Loading highlighter...

Installation

1. Node.js package

bun add twoslash-python

2. Python CLI (requires Python 3.12+)

pip install pytwoslash

How It Works

1
Generate hover data

Run pytwoslash on your Python source file. It starts a language server via multilspy, walks the AST, and fetches hover info for each symbol.

pytwoslash example.py /path/to/project -o example.nodes.json
2
Configure the Shiki transformer

Pass the transformer to Shiki. It reads the JSON and injects hover popups into the rendered HTML.

import {
  createTwoslasherPython,
  transformerTwoslashPython,
  rendererRichPython,
  renderMarkdown,
  renderMarkdownInline,
} from 'twoslash-python';

const transformer = transformerTwoslashPython({
  twoslasher: createTwoslasherPython({}),
  renderer: rendererRichPython({
    renderMarkdown,
    renderMarkdownInline,
  }),
  explicitTrigger: true,
  langs: ['python'],
});
3
Render your code

Use Shiki with the transformer. Point to the generated JSON via metadata.

const html = await codeToHtml(code, {
  lang: 'python',
  theme: 'github-dark',
  transformers: [transformer],
  meta: {
    json_file_path: './example.nodes.json',
    __raw: 'twoslash',
  },
});

Features

  • Type signatures and documentation on hover
  • Works with any Python project (uses the real LSP)
  • Seamless integration with Shiki themes
  • Compatible with VitePress, Astro, SvelteKit, and more
  • Pre-generated JSON -- no LSP at runtime