https://github.com/codesue/io
🌑 A mini Python REPL web component
https://github.com/codesue/io
pyodide python repl web-components
Last synced: 3 months ago
JSON representation
🌑 A mini Python REPL web component
- Host: GitHub
- URL: https://github.com/codesue/io
- Owner: codesue
- License: mit
- Created: 2023-08-06T18:20:40.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-22T06:22:28.000Z (about 1 year ago)
- Last Synced: 2025-03-19T20:13:54.503Z (9 months ago)
- Topics: pyodide, python, repl, web-components
- Language: JavaScript
- Homepage: https://codesue.github.io/io/
- Size: 759 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Io
[![License][license_badge]][license_link]
[![npm][npm_badge]][npm_link]
[![Repo Size][repo_size_badge]][repo_size_link]
[![Docs][docs_badge]][docs_link]
Io is web component library for running Python codeblocks in the browser. Its
core element is ``, a mini Python REPL powered by [Pyodide](https://pyodide.org/en/stable/).
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](https://pyscript.net) instead.
## Quickstart
Add the `` script to the head of your HTML document:
```html
```
Add the following rule to your stylesheet to prevent the component from being
displayed until its ready:
```css
io-repl:not(:defined) {
opacity: 0;
transition: opacity 0.3s ease-in-out;
}
```
Use `` in your HTML document:
```html
import this
```
## Installation
### Linking to a CDN
```html
```
### Installing from npm
```bash
npm i io-repl
```
### Building from source
1. Clone this repository
```sh
git clone https://github.com/codesue/io.git
```
2. Navigate to the project's directory
```sh
cd io
```
3. Install dependencies
```sh
npm i
```
## Usage
### Importing the component in a module
```js
import 'io-repl';
```
### Adding a REPL to your HTML document
Adding an empty REPL:
```html
```
Adding default code to the REPL:
```html
print('Hello, world!')
```
Adding default code that relies on indentation to the REPL:
```html
def greet():
print('Hello, there!')
greet()
```
### 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 precedence over any text inside the
`` tags.
Here's an example of how to do this:
```html
```
### Styling with CSS
#### Preventing FOUC (flash of unstyled content)
Add the following rules to your stylesheet:
```css
io-repl:not(:defined) {
opacity: 0;
transition: opacity 0.3s ease-in-out;
}
```
#### Customizing component styles
You can change the style of the `` element directly:
```css
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 `` tag:
```css
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:
```css
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:
```bash
npm start
```
The website will be available at http://localhost:8000/.
### Testing with Web Test Runner
To execute a single test, run:
```sh
npm run test
```
To run the tests in interactive watch mode, run:
```sh
npm run test:watch
```
### Linting and formatting
To scan the project for linting and formatting errors, run
```sh
npm run lint
```
To automatically fix linting and formatting errors, run
```sh
npm run format
```
## Contributing
Currently, this project does not accept external contributions.
## License
Copyright © 2023 [Suzen Fylke](https://suzenfylke.com). Distributed under
the MIT License.
## Acknowledgements
This project was scaffolded with [open-wc](https://github.com/open-wc/open-wc)'s
web component generator.
It forks PyScript's [ltrim](https://github.com/pyscript/pyscript/blob/2023.05.1/pyscriptjs/src/utils.ts#L14-L27)
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](https://github.com/pyscript/pyscript/blob/main/LICENSE).
[docs_badge]: https://img.shields.io/github/actions/workflow/status/codesue/io/publish-docs.yml?label=docs&colorA=363a4f&colorB=b7bdf8&style=flat
[docs_link]: https://github.com/codesue/io/actions/workflows/publish-docs.yml
[license_badge]: https://img.shields.io/github/license/codesue/io?colorA=363a4f&colorB=b7bdf8&style=flat
[license_link]: https://github.com/codesue/io/tree/main/LICENSE
[npm_badge]: https://img.shields.io/npm/v/io-repl?colorA=363a4f&colorB=b7bdf8&style=flat
[npm_link]: https://www.npmjs.com/package/io-repl
[repo_size_badge]: https://img.shields.io/github/repo-size/codesue/io?colorA=363a4f&colorB=b7bdf8&style=flat
[repo_size_link]: https://github.com/codesue/io