├── src
├── vite-env.d.ts
├── config
│ └── index.ts
├── setup.py
├── types.ts
├── utils.ts
├── worker.ts
└── main.ts
├── .husky
└── pre-commit
├── .eslintrc.json
├── .gitignore
├── .prettierrc.json
├── playground
├── index.html
└── logo.svg
├── tsconfig.json
├── LICENSE
├── vite.config.ts
├── CHANGELOG.md
├── package.json
├── CODE_OF_CONDUCT.md
└── README.md
/src/vite-env.d.ts:
--------------------------------------------------------------------------------
1 | ///
2 |
--------------------------------------------------------------------------------
/.husky/pre-commit:
--------------------------------------------------------------------------------
1 | #!/bin/sh
2 | . "$(dirname "$0")/_/husky.sh"
3 |
4 | npx lint-staged
5 |
--------------------------------------------------------------------------------
/src/config/index.ts:
--------------------------------------------------------------------------------
1 | const config = {
2 | loadPyodideOptions: {
3 | indexURL: 'https://cdn.jsdelivr.net/pyodide/v0.23.2/full/',
4 | },
5 | };
6 |
7 | export default config;
8 |
--------------------------------------------------------------------------------
/.eslintrc.json:
--------------------------------------------------------------------------------
1 | {
2 | "env": {
3 | "browser": true,
4 | "es2021": true
5 | },
6 | "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
7 | "parser": "@typescript-eslint/parser",
8 | "plugins": ["@typescript-eslint"],
9 | "parserOptions": {
10 | "ecmaVersion": "latest",
11 | "sourceType": "module"
12 | }
13 | }
14 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Logs
2 | logs
3 | *.log
4 | npm-debug.log*
5 | yarn-debug.log*
6 | yarn-error.log*
7 | pnpm-debug.log*
8 | lerna-debug.log*
9 |
10 | node_modules
11 | dist
12 | dist-ssr
13 | *.local
14 |
15 | # Editor directories and files
16 | .vscode/*
17 | !.vscode/extensions.json
18 | .idea
19 | .DS_Store
20 | *.suo
21 | *.ntvs*
22 | *.njsproj
23 | *.sln
24 | *.sw?
25 |
--------------------------------------------------------------------------------
/.prettierrc.json:
--------------------------------------------------------------------------------
1 | {
2 | "tabWidth": 2,
3 | "useTabs": false,
4 | "semi": true,
5 | "singleQuote": true,
6 | "printWidth": 100,
7 | "trailingComma": "all",
8 | "importOrder": ["", "^@/(.*)$", "^[./]"],
9 | "importOrderGroupNamespaceSpecifiers": true,
10 | "importOrderSeparation": true,
11 | "importOrderSortSpecifiers": true
12 | }
13 |
--------------------------------------------------------------------------------
/playground/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 | @x-python/core
8 |
9 |
10 |
11 |
12 |
13 |
check the console 👇
14 |
5 |
6 |
7 |
8 |
9 | A complete solution for python-in-browser. (check the [Usage](#usage) section :point_down:)
10 |
11 |
12 |
13 | 🔥 A REPL powered by `xPython` as `React` component is coming soon
14 |
15 | ⌛️ It's still in beta testing
16 |
17 |
18 |
19 | ## Synopsis
20 |
21 | Clean API to execute Python code, get code completions, format the code, install packages, and many more.
22 |
23 | ## Motivation
24 |
25 | In the past few years we used python in production browser-based applications in quite different scenarios. From just executing a python code to implementing autoformat and autocomplete. And while all of this is possible there are many questionable situations in the implementations. For example, it's been a while since we've had a full `Python` distribution for the browser based on webassembly - [pyodide](https://pyodide.org/en/stable/). `Pyodide` is great! You can just install and use it. But to use it correctly, instead of installing it in the main (UI) thread, it would be desirable to install/run it in a separate thread. Once you've created a separate thread you need to create a channel between main/UI and pyodide worker and come up with some protocol for communication. You also need to do something with error handling, handling standard output streams, non-sequential executions and other all possible corner cases. This was one of the things that `xPython` will handle for you :slightly_smiling_face: It also provides a clean API for code completion, installing packages, and formatting the code... and many more are coming soon. Long story short I tried to provide a clean and complete interface to interact with Python in browser-based applications.
26 |
27 | ## Documentation
28 |
29 | #### Contents
30 |
31 | - [Installation](#installation)
32 | - [Usage](#usage)
33 | - [API](#api)
34 | - [.init](#init)
35 | - [.exec](#exec)
36 | - [.complete](#complete)
37 | - [.repl](#complete)
38 | - [.format](#format)
39 | - [.install](#install)
40 | - [Development](#development)
41 |
42 | ### Installation
43 |
44 | ```bash
45 | npm install @x-python/core
46 | ```
47 |
48 | or
49 |
50 | ```bash
51 | yarn add @x-python/core
52 | ```
53 |
54 | ### Usage
55 |
56 | ```javascript
57 | import * as xPython from '@x-python/core';
58 |
59 | // initialize xPython
60 | await xPython.init();
61 |
62 | // execute python code
63 | await xPython.exec({ code: '1 + 1' });
64 | await xPython.exec({ code: 'print("test")' });
65 |
66 | // multiline example
67 | await xPython.exec({
68 | code: `
69 | import sys
70 | sys.version
71 | `,
72 | });
73 |
74 | // you can use built-in packages without additionally installing them
75 | await xPython.exec({
76 | code: `
77 | import numpy as np
78 | np.random.rand()
79 | `,
80 | });
81 |
82 | // code completion
83 | await xPython.complete.repl({ code: `import sys; sys.ver` });
84 |
85 | // specify the cursor position
86 | await xPython.complete.repl({
87 | code: `
88 | from math import factorial
89 |
90 | test = 8
91 | print(tes)
92 | factorial(x)
93 | `,
94 | line: 5,
95 | column: 9,
96 | });
97 |
98 | // format the code
99 | const { result } = await xPython.format({
100 | code: `
101 | def add(a, b):
102 | return a + b
103 |
104 | print(add(12,
105 |
106 | 54))
107 | `,
108 | });
109 |
110 | console.log(result);
111 |
112 | // install packages
113 | await xPython.install(['nicelog']);
114 |
115 | // and use the newly installed package :)
116 | const { stderr } = await xPython.exec({
117 | code: `
118 | import logging
119 | import sys
120 |
121 | from nicelog.formatters import Colorful
122 |
123 | # Setup a logger
124 | logger = logging.getLogger('foo')
125 | logger.setLevel(logging.DEBUG)
126 |
127 | # Setup a handler, writing colorful output
128 | # to the console
129 | handler = logging.StreamHandler(sys.stderr)
130 | handler.setFormatter(Colorful())
131 | handler.setLevel(logging.DEBUG)
132 | logger.addHandler(handler)
133 |
134 | # Now log some messages..
135 | logger.debug('Debug message')
136 | logger.info('Info message')
137 | logger.warning('Warning message')
138 | logger.error('Error message')
139 | logger.critical('Critical message')
140 | try:
141 | raise ValueError('This is an exception')
142 | except:
143 | logger.exception("An error occurred")
144 | `,
145 | });
146 |
147 | console.log(stderr);
148 | ```
149 |
150 | ## API
151 |
152 | #### .init
153 |
154 | It will initialize `xPython`. Most importantly it will create a separate thread (dedicated web worker), install `pyodide` inside that thread, create a channel, and setup all necessary packages and functions for further usage.
155 |
156 | ```javascript
157 | import * as xPython from '@x-python/core';
158 |
159 | await xPython.init();
160 | ```
161 |
162 | Usually, we do initialize `xPython` before using other methods (like `exec`, `complete`, etc), but it's not mandatory :slightly_smiling_face: So, you can go ahead and do `xPython.exec({ code: '...' })` without doing `xPython.init()` - it will do `xPython.init()` on first `xPython.exec` (or `.complete`, `.format` and any other supported method) call if it's not initialized. The aim of the existence of a separate initialize method is to provide full flexibility to developers. The initialization process takes time and it should be possible to handle that time in the way you want. So, you can do `await xPython.init();` at the beginning or do it after a certain user action or, if you are okay with your users waiting a little bit more after the first execution then you can skip the initialization process and it will be handled automatically :slightly_smiling_face:
163 |
164 | #### .exec
165 |
166 | `exec` is one of the most frequently used. Basically, it's for executing python code. A simple usage looks like this:
167 |
168 | ```javascript
169 | import * as xPython from '@x-python/core';
170 |
171 | await xPython.exec({ code: '1 + 1' });
172 | ```
173 |
174 | You can also provide a `context` with global variables, like:
175 |
176 | ```javascript
177 | import * as xPython from '@x-python/core';
178 |
179 | await xPython.exec({ code: 'x + 1', context: { x: 1 } });
180 | ```
181 |
182 | But let's take a closer look at what it returns. In both cases we will get something like this:
183 |
184 | ```js
185 | { result: 2, error: null, stdout: '', stderr: '' }
186 | ```
187 |
188 | `result` is what is returned from the executed script. But we also have `stdout` (and `stderr`) for standard output streams. If we execute `print("test")` nothing will be returned, but you will have a `stdout`.
189 |
190 | ```javascript
191 | import * as xPython from '@x-python/core';
192 |
193 | await xPython.exec({ code: 'print("test")' });
194 |
195 | // { result: undefined, error: null, stdout: 'test', stderr: '' }
196 | ```
197 |
198 | Of course you can exec multiline code snippets:
199 |
200 | ```javascript
201 | import * as xPython from '@x-python/core';
202 |
203 | await xPython.exec({
204 | code: `
205 | import sys
206 |
207 | sys.version
208 | `,
209 | });
210 | ```
211 |
212 | You can directly use `pyodide` built-in package list without installing them. The full list is [here](https://pyodide.org/en/stable/usage/packages-in-pyodide.html)
213 |
214 | ```javascript
215 | import * as xPython from '@x-python/core';
216 |
217 | await xPython.exec({
218 | code: `
219 | import numpy as np
220 |
221 | np.random.rand()
222 | `,
223 | });
224 | ```
225 |
226 | It will autodetect `numpy` and it will install it if you're using it for the first time.
227 |
228 | #### .complete
229 |
230 | To get code completions you can use `xPython.complete.repl`. Simple usage looks like this:
231 |
232 | ```javascript
233 | import * as xPython from '@x-python/core';
234 |
235 | await xPython.complete.repl({ code: 'import sys; sys.ver' });
236 | ```
237 |
238 | This example will return an array with two possible options: `version` and `version_info` :slightly_smiling_face:
239 |
240 | The full signature of this method also includes `line` and `column` options to specify the cursor position. If `line` isn't provided `xPython` will assume it's the last line and, correspondingly, if `column` isn't provided it will assume that it's the last column. So, in the previous example, it assumed that cursor is at the end of `sys.var` and returned code completions based on that assumption. An example with cursor position specified:
241 |
242 | ```javascript
243 | await xPython.complete.repl({
244 | code: `
245 | from math import factorial
246 |
247 | test = 8
248 | print(tes)
249 | factorial(x)
250 | `,
251 | line: 5,
252 | column: 9,
253 | });
254 | ```
255 |
256 | This will return the only available option here: `test`.
257 |
258 | The curious eye may notice that instead of `.complete` we called `.complete.repl`. When it comes to code completion at least two environments can be your target: `REPL` and `Script/File/Editor`. And based on the environment code completion can vary. In the current version, we do support only `REPL`, but very soon other options will also be available ⏳
259 |
260 | #### .format
261 |
262 | Code formatting is an essential part of interacting with your code. A simple usage looks like this:
263 |
264 | ```javascript
265 | import * as xPython from '@x-python/core';
266 |
267 | const { result } = await xPython.format({
268 | code: `
269 | def add(a, b):
270 | return a + b
271 |
272 | print(add(12,
273 |
274 | 54))
275 | `,
276 | });
277 |
278 | console.log(result);
279 | ```
280 |
281 | **NOTE:** in upcoming versions a full configuration option will be provided.
282 |
283 | #### .install
284 |
285 | The entire standard library is available out of the box, so you can import `sys`, `math`, or `os` without doing anything special. In addition to this `pyodide` also provides a list of built-in packages, like `numpy`, `pandas`, `scipy`, `matplotlib`, `scikit-learn`, etc. Check the full list [here](https://pyodide.org/en/stable/usage/packages-in-pyodide.html). You can use any package from the above-mentioned list and it will be installed automatically and on demand. And if that's not enough you can still install any pure `Python` packages with wheels available on `PyPI` :slightly_smiling_face: Let's install the package called `nicelog`.
286 |
287 | ```javascript
288 | import * as xPython from '@x-python/core';
289 |
290 | await xPython.install(['nicelog']);
291 | ```
292 |
293 | That's it :slightly_smiling_face: Now you have `nicelog` installed and it's ready to be used. Not familiar with `nicelog`? Let's check what's inside:
294 |
295 | ```javascript
296 | import * as xPython from '@x-python/core';
297 |
298 | await xPython.complete.repl({ code: 'from nicelog import ' });
299 | ```
300 |
301 | As it's already installed it should be available for code completion as well :white_check_mark:
302 |
303 | Example from the `nicelog` `PyPI` [page](https://pypi.org/project/nicelog/).
304 |
305 | ```javascript
306 | const { stderr } = await xPython.exec({
307 | code: `
308 | import logging
309 | import sys
310 |
311 | from nicelog.formatters import Colorful
312 |
313 | # Setup a logger
314 | logger = logging.getLogger('foo')
315 | logger.setLevel(logging.DEBUG)
316 |
317 | # Setup a handler, writing colorful output
318 | # to the console
319 | handler = logging.StreamHandler(sys.stderr)
320 | handler.setFormatter(Colorful())
321 | handler.setLevel(logging.DEBUG)
322 | logger.addHandler(handler)
323 |
324 | # Now log some messages..
325 | logger.debug('Debug message')
326 | logger.info('Info message')
327 | logger.warning('Warning message')
328 | logger.error('Error message')
329 | logger.critical('Critical message')
330 | try:
331 | raise ValueError('This is an exception')
332 | except:
333 | logger.exception("An error occurred")
334 | `,
335 | });
336 |
337 | console.log(stderr);
338 | ```
339 |
340 | ### Development
341 |
342 | To play with the library locally do the following steps:
343 |
344 | 1. clone this repo
345 |
346 | ```bash
347 | git clone git@github.com:suren-atoyan/x-python.git
348 | ```
349 |
350 | 2. install dependencies
351 |
352 | ```bash
353 | npm install # or yarn
354 | ```
355 |
356 | 3. run the dev server
357 |
358 | ```bash
359 | npm run dev
360 | ```
361 |
362 | That's it :slightly_smiling_face: Under `/playground` folder you can find the `index.html` file which contains a script with the demo code and under `/src` folder you can find the library source code. Enjoy it :tada:
363 |
364 | ## License
365 |
366 | [MIT](./LICENSE)
367 |
--------------------------------------------------------------------------------