io-repl

Io

Io is web component library for running Python codeblocks in the browser. Its core element is <io-repl>, a mini Python REPL powered by Pyodide.

Io is a lightweight and highly experimental library. It's just for fun and shouldn't be used for anything serious. If you're looking for a similar library to use in your projects, consider using PyScript instead.

Quickasrt

Add the <io-repl> script to the head of your HTML document:

<script type='module' src='https://www.unpkg.com/io-repl/io-repl.js'></script>

Add the following rule to your stylesheet to prevent the component from being displayed until its ready:

io-repl:not(:defined) {
  opacity: 0;
  transition: opacity 0.3s ease-in-out;
}

Use <io-repl> in your HTML document:

<io-repl>import this</io-repl>

Installation

Linking to a CDN

<script type='module' src='https://www.unpkg.com/io-repl/io-repl.js'></script>

Installing from npm

npm i io-repl

Building from source

1. Clone this repository

   git clone https://github.com/codesue/io.git

2. Navigate to the project's directory

   cd io

3. Install dependencies

   npm i

Usage

Importing the component in a module

import 'io-repl';

Adding a REPL to your HTML document

Adding an empty REPL:

<io-repl></io-repl>

Adding default code to the REPL:

<io-repl>print('Hello, world!')</io-repl>

Adding default code that relies on indentation to the REPL:

<io-repl>
  def greet():
    print('Hello, there!')

  greet()
<io-repl>

Customizing the REPL

You can customize the REPL using the following attributes:

• button-label (string): The text to display as the run button's label.
• disable-button (boolean): Whether to disable and hide the run button.
• disable-input (boolean): Whether to disable editing input code.
• execute (boolean): Whether to execute the code when the component is rendered.
• pyodide-src (string): The path to a pyodide module to import. If not provided, defaults to https://cdn.jsdelivr.net/pyodide/v0.23.4/full/pyodide.js.
• src (string): The path to a file containing Python code. Its text will be set as the code input of the REPL, taking precedent over any text inside the <io-repl></io-repl> tags.

Here's an example of how to do this:

<io-repl execute disable-input button-label='Play' pyodide-src='https://path/to/pyodide.js'>
<io-repl>

Styling with CSS

Preventing FOUC (flash of unstyled content)

Add the following rules to your stylesheet:

io-repl:not(:defined) {
  opacity: 0;
  transition: opacity 0.3s ease-in-out;
}

Customizing component styles

You can change the style of the <io-repl> element directly:

io-repl {
  background: #c9cdee;
  padding: 1em;
  border-radius: 0.25em;
}

You can change the style of its nested elements using css variables defined in the elements <style> tag:

io-repl {
  --input-border-radius: 0.25em;;
  --button-border-radius: 0.25em;;
  --button-font-family: monospace;
  --button-padding: 0.25em 0.5em;
  --button-margin: 0;
}

Alternatively, you can use the elements' part attribute:

io-repl::part(button) {
  border-radius: 0.25em;
}

Parts include label, button, input, input-container, and output.

Developing the library

Running the local demo with web-dev-server

To run a local development server that serves the basic demo located in index.html, run:

npm start

The website will be available at http://localhost:8000/.

Testing with Web Test Runner

To execute a single test, run:

npm run test

To run the tests in interactive watch mode, run:

npm run test:watch

Linting and formatting

To scan the project for linting and formatting errors, run

npm run lint

To automatically fix linting and formatting errors, run

npm run format

Contributing

Currently, this project does not accept external contributions.

License

Copyright © 2023 Suzen Fylke. Distributed under the MIT License.

Acknowledgements

This project was scaffolded with open-wc's web component generator.

It forks PyScript's ltrim function to dedent code input, and parts of its design are heavily influenced by the design of PyScript's web components. PyScript is licensed under the Apache 2.0 License.