Python

The {exec} python directive allows executing Python code in the browser.

import platform
import pyodide_js

print(f"{platform.python_implementation()}"
      f" {'.'.join(platform.python_version_tuple())}"
      f" on {platform.platform()},"
      f" using Pyodide {pyodide_js.version}")

Module setup

Module setup code can be defined as a named {exec} python block, to be referenced in the :after: option of other blocks.

def factorial(n):
  res = 1
  for i in range(2, n + 1):
    res *= i
  return res

Program output

Terminal

The terminal output generated by an {exec} python block via sys.stdout and sys.stderr (and therefore, via print()) is displayed in an output block. Output to sys.stderr is colored.

for i in range(10):
  print(f"factorial({i}) = {factorial(i)}")

import sys
sys.stderr.write("Program terminated.\n")

The terminal output block can be cleared with the form-feed control character (\x0c).

import asyncio

for i in range(10, 0, -1):
  print(f"\x0c{i}...")
  await asyncio.sleep(1)
print("\x0cHappy new year!")

The width of the terminal output block is limited by the page content width.

print("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do "
      "eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad "
      "minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip "
      "ex ea commodo consequat. Duis aute irure dolor in reprehenderit in "
      "voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur "
      "sint occaecat cupidatat non proident, sunt in culpa qui officia "
      "deserunt mollit anim id est laborum.")

The height of the terminal output block can be limited with :console-style:.

for i in range(100):
  print(i)

Graphics

See the tdoc.svg module.

from tdoc import svg

def paint_heart(c):
  c.path('M -40,-20 A 20,20 0,0,1 0,-20 A 20,20 0,0,1 40,-20 '
         'Q 40,10 0,40 Q -40,10 -40,-20 z',
         stroke='red', fill='transparent')
  c.path('M -40,30 -30,30 -30,40 '
         'M -30,30 0,0 M 34,-34 45,-45'
         'M 35,-45 45,-45 45,-35',
         stroke=svg.Stroke('black', width=2), fill='transparent')

img = svg.Image(400, 100, stroke='darkorange', fill='#c0c0ff',
                style='width: 100%; height: 100%')
img.stylesheet = """
.bold {
  stroke: blue;
  stroke-width: 2;
  fill: #c0ffc0;
}
"""
img.circle(20, 30, 10)
img.ellipse(20, 70, 10, 20, klass='bold')
img.line(0, 0, 400, 100)
g = img.group(transform=svg.translate(200, 10))
g.polygon((0, 0), (30, 0), (40, 20), klass='bold')
g.polyline((0, 0), (30, 0), (40, 20), fill='transparent',
           transform=svg.translate(x=50, y=10))
img.rect(0, 0, 400, 100, fill='transparent')
img.text(50, 90, "Some text", stroke='transparent', fill='green')
paint_heart(img.group(transform=svg.translate(360, 30).rotate(20).scale(0.5)))
render(img)

Animations can be implemented by rendering images repeatedly in a loop, with a short sleep between images. Don't forget to sleep, otherwise the program becomes unstoppable and the page must be reloaded.

import random

img = svg.Image(400, 100, style='width: 100%; height: 100%')
sym = img.symbol()
paint_heart(sym)
hearts = [(img.use(href=sym),
           random.uniform(0, 100), random.uniform(0, 100),
           random.uniform(-180, 180))
          for _ in range(20)]

def saw(value, amplitude):
  return abs((value + amplitude) % (2 * amplitude) - amplitude)

def pose(t, vx, vy, va):
  return saw(t * vx, img.width), saw(t * vy, img.height), (t * va) % 360.0

start = await animation_frame()
while True:
  t = (await animation_frame() - start) / 1000
  for heart, vx, vy, va in hearts:
    heart.x, heart.y, a = pose(t, vx, vy, va)
    heart.transform = svg.rotate(a, heart.x, heart.y)
  img.width, img.height = await render(img)

Program input

User input can be requested by awaiting functions available in the global environment. Unfortunately, sys.stdin (and anything that depends on it) cannot be used, due to its blocking nature.

Line of text

See input_line().

name = await input_line("What is your name?")
print(f"Hello, {name}!")

Multi-line text

See input_text().

print("Please enter some text.")
text = await input_text()
print(f"\x0cThe text was:\n-------------\n{text}")

Buttons

See input_buttons().

colors = ["Red", "Green", "Blue"]
index = await input_buttons("Pick a color:", colors)
print(f"You picked: {colors[index]}")

Pause

See pause().

n = 5
fact = 1
for i in range(2, n + 1):
  fact *= i
  await pause(f"i={i}, fact={fact}")
print(f"The factorial of {n} is {fact}")

Exceptions

Uncaught exceptions are displayed as a traceback on sys.stderr.

def outer():
  try:
    inner()
  except Exception as e:
    raise Exception("inner() failed") from e

def inner():
  raise Exception("Something is broken")

outer()

Friendly

The following code block shows how to install the friendly package to improve the tracebacks of uncaught exceptions. It can be added to a page (hidden with :class: hidden) and used by other blocks on the page via an :after: dependency.

if once('friendly'):  # Install only once per interpreter
  # Install friendly and markdown-it-py from PyPI. The latter is required by
  # rich, which is used by friendly, but it isn't part of rich's dependencies.
  import micropip
  await micropip.install(['friendly', 'markdown-it-py'])
  # BUG(friendly-0.7.21): Importing friendly triggers a DeprecationWarning. It
  # also enables all warnings, so it's not possible to ignore the warning using
  # the standard warnings module. The next version should have a fix, but in the
  # meantime, add a filter to friendly_traceback.
  import friendly_traceback
  friendly_traceback.add_ignored_warnings(
    lambda m, w, *_: w is DeprecationWarning)
  # Activate friendly in French.
  import friendly
  friendly.install(lang='fr')
  # Exclude the tdoc.core module from tracebacks. This should normally use
  # friendly.exclude_file_from_traceback(), but the latter checks if the file
  # exists, and the check fails because the file is in a .zip archive.
  from tdoc import core
  from friendly_traceback.path_info import EXCLUDED_FILE_PATH
  EXCLUDED_FILE_PATH.add(core.__file__)

The following block uses the block above and raises an exception. It runs in a separate interpreter to avoid polluting the other blocks on this page; if all blocks on a page should use friendly, this isn't necessary.

print("Importing foo...")
import foo

Concurrency

All {exec} python blocks on a page and referencing the same environment are executed in a shared, single-threaded interpreter. Therefore, only one block can run at any given time. Nevertheless, concurrent execution is possible through async coroutines. The asyncio module provides functionality related to async concurrency.

import asyncio
import time

while True:
  print(f"\x0c{time.strftime('%Y-%m-%d %H:%M:%S')}")
  await asyncio.sleep(1)

import asyncio

i = 0
while True:
  print(f"\x0ci={i}")
  i += 1
  await asyncio.sleep(0.2)

Calling async functions synchronously via pyodide.ffi.run_sync() only works on Chromium-based browsers.

from pyodide import ffi

def input(prompt):
  return ffi.run_sync(input_line(prompt))

name = input("Name:")
print(f"Hello, {name}!")

Packages

Additional packages can be made available through the exec.python.packages metadata, which holds a list of packages to load.

import pathlib
import sqlite3

path = pathlib.Path('database.sqlite')
exists = path.exists()
db = sqlite3.connect(path)
if not exists:
  print("Creating database")
  db.executescript(pathlib.Path('database.sql').read_text())
for k, v in db.execute('select * from kv;'):
  print(f"key: {k}, value: {v}")

Packages can also be installed directly from PyPI using micropip (which must itself be added to the exec.python.packages metadata). For example, the following code installs the snowballstemmer package. Note how the installation is only performed once per interpreter, using once().

if once('snowballstemmer'):  # Install only once per interpreter
  import micropip
  await micropip.install(['snowballstemmer'])

import snowballstemmer
stemmer = snowballstemmer.stemmer('english')
for word in ['running', 'runs', 'ran',
             'caring', 'cared', 'careful',
             'university', 'universities',
             'fairly', 'unfairly',
             'singing', 'singer', 'song']:
  print(f"{word:12} => {stemmer.stemWord(word)}")

Note

Installing from PyPI introduces a serving dependency on PyPI servers. This can reduce the availability of the site. It's also not very nice to the operators of PyPI to drive traffic their way (though browser caching should alleviate the issue). For high-traffic pages, the .whl packages should be included in the site's _static and installed via the exec.python.packages metadata.

Filesystem

The block below lists all the files and directories on the virtual filesystem seen by Python code.

import pathlib

paths = []
for base, dirs, files in pathlib.Path('/').walk(on_error=lambda e: None):
  if base == pathlib.Path('/proc/self'): dirs.remove('fd')
  paths.extend(str(base / e) for e in dirs + files)
paths.sort()
print('\n'.join(paths))