Adds Pygments JS RPC example (#50)

* Adds Pygments JS RPC example

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: dom96

.pre-commit-config.yaml

@@ -18,6 +18,11 @@ repos:
     rev: "v2.4.1"
     hooks:
       - id: codespell
+        exclude: |
+          (?x)^(
+            .*package-lock\.json|
+            .*worker-configuration\.d\.ts
+          )$
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.14.3

13-js-api-pygments/README.md

@@ -0,0 +1,60 @@
+# 13-js-api-pygments – Python RPC Server & TS Client
+
+This example shows how to use **JS RPC** to connect a **Python Worker** (server) to a **TypeScript Worker** (client).
+
+The Python Worker exposes a Pygments-powered `highlight_code` RPC method. The TS Worker calls this method to syntax-highlight code on the server side and renders the result as HTML.
+
+## Project Layout
+
+- `py/`
+  - Python Worker (RPC server)
+  - Exposes `HighlighterRpcService.highlight_code()` over RPC using Pygments
+- `ts/`
+  - TypeScript Worker (RPC client)
+  - Calls the Python Worker via a `PYTHON_RPC` service binding and renders the highlighted code
+
+## Prerequisites
+
+- `uv` installed for Python dependency management
+- Node.js + npm
+
+## How to Run
+
+### 1. Install and run the Python RPC server
+
+```bash
+cd 13-js-api-pygments/py
+uv run pywrangler dev
+```
+
+This starts the Python Worker defined in `py/wrangler.jsonc`.
+
+### 2. Install and run the TypeScript RPC client
+
+Open a **second terminal**:
+
+```bash
+cd 13-js-api-pygments/ts
+npm run dev
+```
+
+This starts the TypeScript Worker defined in `ts/wrangler.jsonc`, which has a `services` binding:
+
+```jsonc
+"services": [
+  {
+    "binding": "PYTHON_RPC",
+    "service": "py-rpc-server"
+  }
+]
+```
+
+### 3. Try it out
+
+- Visit the URL printed by `npm run dev` (usually `http://localhost:8787/`).
+- The TS Worker will:
+  - Call the Python Worker via RPC
+  - Have Pygments highlight a sample TypeScript snippet
+  - Return a full HTML page with highlighted code and styling
+
+If you change the Python RPC method or the sample code in `ts/src/index.ts`, just reload the page to see the new output.

13-js-api-pygments/py/package.json

@@ -0,0 +1,13 @@
+{
+	"name": "py-rpc-server",
+	"version": "0.0.0",
+	"private": true,
+	"scripts": {
+		"deploy": "uv run pywrangler deploy",
+		"dev": "uv run pywrangler dev",
+		"start": "uv run pywrangler dev"
+	},
+	"devDependencies": {
+		"wrangler": "^4.49.0"
+	}
+}

13-js-api-pygments/py/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "py-rpc-server"
+version = "0.1.0"
+description = "Python RPC server which responds to highlight_code RPC calls"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "webtypy>=0.1.7",
+    "pygments",
+]
+
+[dependency-groups]
+dev = [
+    "workers-py",
+    "workers-runtime-sdk"
+]

13-js-api-pygments/py/src/entry.py

@@ -0,0 +1,52 @@
+from workers import WorkerEntrypoint, Response, Request
+from pygments import highlight
+from pygments.lexers import get_lexer_by_name, guess_lexer
+from pygments.formatters import HtmlFormatter
+from pygments.util import ClassNotFound
+
+
+class Default(WorkerEntrypoint):
+    async def fetch(self, request: Request):
+        return Response("Python RPC server is running. Use RPC to call methods.")
+
+    async def highlight_code(self, code: str, language: str = None) -> dict:
+        """
+        Syntax highlight code using Pygments.
+
+        Args:
+            code: The source code to highlight
+            language: Programming language (e.g., 'python', 'javascript', 'rust')
+                     If None, will attempt to guess the language
+
+        Returns:
+            Dict with highlighted HTML and CSS
+        """
+        try:
+            # Get the appropriate lexer
+            if language:
+                lexer = get_lexer_by_name(language, stripall=True)
+            else:
+                lexer = guess_lexer(code)
+        except ClassNotFound:
+            return {
+                "error": f"Language '{language}' not found",
+                "html": f"<pre>{code}</pre>",
+                "css": "",
+                "language": "unknown",
+            }
+
+        # Create formatter with line numbers and styling
+        formatter = HtmlFormatter(linenos=True, cssclass="highlight", style="monokai")
+
+        # Generate highlighted HTML
+        highlighted_html = highlight(code, lexer, formatter)
+
+        # Get the CSS for styling
+        css = formatter.get_style_defs(".highlight")
+
+        return {
+            "html": highlighted_html,
+            "css": css,
+            "language": lexer.name,
+            "language_alias": lexer.aliases[0] if lexer.aliases else None,
+        }

13-js-api-pygments/py/uv.lock

@@ -0,0 +1,12 @@
+{
+	"$schema": "node_modules/wrangler/config-schema.json",
+	"name": "py-rpc-server",
+	"main": "src/entry.py",
+	"compatibility_date": "2025-11-02",
+	"compatibility_flags": [
+		"python_workers"
+	],
+	"observability": {
+		"enabled": true
+	}
+}