Skip to content

Commit a06c190

Browse files
synwsynw
committed
Version 0.1.0: better types
1 parent 58a3740 commit a06c190

File tree

6 files changed

+208
-17
lines changed

6 files changed

+208
-17
lines changed

‎package.json

+8-8
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,30 @@
11
{
22
"name": "usepython",
3-
"version": "0.0.12",
3+
"version": "0.1.0",
44
"description": "A Python scripts runner composable",
55
"repository": "https://github.com/synw/usepython",
66
"scripts": {
77
"build": "rollup -c",
88
"dev": "rollup -cw",
9-
"docs": "typedoc --entryPointStrategy expand"
9+
"docs": "typedoc --plugin typedoc-plugin-markdown --entryPointStrategy expand"
1010
},
1111
"dependencies": {
12-
"nanostores": "^0.9.5",
12+
"nanostores": "^0.10.0",
1313
"pyodide": "^0.25.0"
1414
},
1515
"devDependencies": {
1616
"@qortal/rollup-plugin-web-worker-loader": "^1.6.5",
1717
"@rollup/plugin-node-resolve": "^15.2.3",
1818
"@rollup/plugin-terser": "^0.4.4",
19-
"@rollup/plugin-typescript": "^11.1.5",
20-
"@types/node": "^20.11.15",
19+
"@rollup/plugin-typescript": "^11.1.6",
20+
"@types/node": "^20.11.28",
2121
"highlight.js": "^11.9.0",
22-
"rollup": "^4.9.6",
22+
"rollup": "^4.13.0",
2323
"tslib": "^2.6.2",
24-
"typedoc": "^0.25.7",
24+
"typedoc": "^0.25.12",
2525
"typedoc-plugin-markdown": "^3.17.1",
2626
"typedoc-plugin-rename-defaults": "^0.7.0",
27-
"typescript": "^5.3.3"
27+
"typescript": "^5.4.2"
2828
},
2929
"files": [
3030
"dist"

‎src/interfaces.ts

+175-2
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,186 @@
1+
import { MapStore, ReadableAtom } from "nanostores";
2+
3+
/**
4+
* Represents a log entry for a Python execution.
5+
* @interface
6+
*/
17
interface PyLog {
2-
id: string
8+
/**
9+
* Unique identifier for the log entry.
10+
* @type {string}
11+
*/
12+
id: string;
13+
14+
/**
15+
* Array of standard output messages.
16+
* @type {Array<string>}
17+
*/
318
stdOut: Array<string>;
19+
20+
/**
21+
* Array of standard error messages.
22+
* @type {Array<string>}
23+
*/
424
stdErr: Array<string>;
25+
26+
/**
27+
* Exception message, if any occurred during the execution.
28+
* @type {string}
29+
*/
530
exception: string;
631
}
732

33+
/**
34+
* Represents a log entry for the installation process of Python packages.
35+
* @interface
36+
*/
837
interface PyInstallLog {
38+
/**
39+
* The current stage of the installation process.
40+
* @type {number}
41+
*/
942
stage: number;
43+
44+
/**
45+
* Message related to the current stage of the installation process.
46+
* @type {string}
47+
*/
1048
msg: string;
1149
}
1250

13-
export { PyLog, PyInstallLog }
51+
/**
52+
* Interface for a Python runner object.
53+
* @interface
54+
*/
55+
interface PyRunner {
56+
/**
57+
* Method to load Python packages.
58+
* @param {Array<string>} [pyoPackages] - Optional array of Python packages to load.
59+
* @param {Array<string>} [packages] - Optional array of additional packages to load.
60+
* @param {string} [initCode] - Optional initialization code to run.
61+
* @param {string} [transformCode] - Optional transformation code to run.
62+
* @returns {Promise<{ results: any, error: any }>} A promise that resolves with the results or rejects with an error.
63+
*/
64+
load: PyLoadMethod;
65+
66+
/**
67+
* Method to run a Python script synchronously.
68+
* @param {string} script - The Python script to run.
69+
* @param {string} [namespace] - Optional namespace for the script.
70+
* @param {string} [id] - Optional identifier for the script execution.
71+
* @param {Record<string, any>} [context] - Optional context for the script execution.
72+
* @returns {Promise<{ results: any, error: any }>} A promise that resolves with the results or rejects with an error.
73+
*/
74+
run: PyRunMethod;
75+
76+
/**
77+
* Method to run a Python script asynchronously.
78+
* @param {string} script - The Python script to run.
79+
* @param {string} [namespace] - Optional namespace for the script.
80+
* @param {string} [id] - Optional identifier for the script execution.
81+
* @param {Record<string, any>} [context] - Optional context for the script execution.
82+
* @returns {Promise<{ results: any, error: any }>} A promise that resolves with the results or rejects with an error.
83+
*/
84+
runAsync: PyRunAsyncMethod;
85+
86+
/**
87+
* Method to clear a namespace.
88+
* @param {string} namespace - The namespace to clear.
89+
* @returns {Promise<{ results: any, error: any }>} A promise that resolves with the results or rejects with an error.
90+
*/
91+
clear: PyClearMethod;
92+
93+
/**
94+
* Store for installation logs.
95+
* @type {MapStore<PyInstallLog>}
96+
*/
97+
installLog: MapStore<PyInstallLog>;
98+
99+
/**
100+
* Store for execution logs.
101+
* @type {MapStore<PyLog>}
102+
*/
103+
log: MapStore<PyLog>;
104+
105+
/**
106+
* Atom representing whether the runner is currently executing a script.
107+
* @type {ReadableAtom<boolean>}
108+
*/
109+
isExecuting: ReadableAtom<boolean>;
110+
111+
/**
112+
* Atom representing whether the runner is ready to execute scripts.
113+
* @type {ReadableAtom<boolean>}
114+
*/
115+
isReady: ReadableAtom<boolean>;
116+
}
117+
118+
/**
119+
* Type for the `load` method of the PyRunner interface.
120+
* @typedef {function} PyLoadMethod
121+
* @param {Array<string>} [pyoPackages] - Optional array of Python packages to load.
122+
* @param {Array<string>} [packages] - Optional array of additional packages to load.
123+
* @param {string} [initCode] - Optional initialization code to run.
124+
* @param {string} [transformCode] - Optional transformation code to run.
125+
* @returns {Promise<{ results: any, error: any }>} A promise that resolves with the results or rejects with an error.
126+
*/
127+
type PyLoadMethod = (
128+
pyoPackages?: Array<string>,
129+
packages?: Array<string>,
130+
initCode?: string,
131+
transformCode?: string
132+
) => Promise<{ results: any, error: any }>;
133+
134+
/**
135+
* Type for the `run` method of the PyRunner interface.
136+
* @typedef {function} PyRunMethod
137+
* @param {string} script - The Python script to run.
138+
* @param {string} [namespace] - Optional namespace for the script.
139+
* @param {string} [id] - Optional identifier for the script execution.
140+
* @param {Record<string, any>} [context] - Optional context for the script execution.
141+
* @returns {Promise<{ results: any, error: any }>} A promise that resolves with the results or rejects with an error.
142+
*/
143+
type PyRunMethod = (
144+
script: string,
145+
namespace?: string,
146+
id?: string,
147+
context?: Record<string, any>
148+
) => Promise<{ results: any, error: any }>;
149+
150+
/**
151+
* Type for the `runAsync` method of the PyRunner interface.
152+
* @typedef {function} PyRunAsyncMethod
153+
* @param {string} script - The Python script to run.
154+
* @param {string} [namespace] - Optional namespace for the script.
155+
* @param {string} [id] - Optional identifier for the script execution.
156+
* @param {Record<string, any>} [context] - Optional context for the script execution.
157+
* @returns {Promise<{ results: any, error: any }>} A promise that resolves with the results or rejects with an error.
158+
*/
159+
type PyRunAsyncMethod = (
160+
script: string,
161+
namespace?: string,
162+
id?: string,
163+
context?: Record<string, any>
164+
) => Promise<{ results: any, error: any }>;
165+
166+
/**
167+
* Type for the `clear` method of the PyRunner interface.
168+
* @typedef {function} PyClearMethod
169+
* @param {string} namespace - The namespace to clear.
170+
* @returns {Promise<{ results: any, error: any }>} A promise that resolves with the results or rejects with an error.
171+
*/
172+
type PyClearMethod = (namespace: string) => Promise<{ results: any, error: any }>;
173+
174+
/**
175+
* Export the PyRunner interface and related types.
176+
* @type {PyRunner}
177+
*/
178+
export {
179+
PyRunner,
180+
PyLog,
181+
PyInstallLog,
182+
PyRunMethod,
183+
PyRunAsyncMethod,
184+
PyClearMethod,
185+
PyLoadMethod,
186+
};

‎src/main.ts

+20-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,21 @@
1-
import { usePython } from "./py";
2-
import { PyLog, PyInstallLog } from "./interfaces";
1+
import { usePython } from "./py.js";
2+
import {
3+
PyRunner,
4+
PyLog,
5+
PyInstallLog,
6+
PyRunMethod,
7+
PyRunAsyncMethod,
8+
PyClearMethod,
9+
PyLoadMethod,
10+
} from "./interfaces.js";
311

4-
export { PyLog, PyInstallLog, usePython }
12+
export {
13+
usePython,
14+
PyRunner,
15+
PyLog,
16+
PyInstallLog,
17+
PyRunMethod,
18+
PyRunAsyncMethod,
19+
PyClearMethod,
20+
PyLoadMethod,
21+
}

‎src/py.ts

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
import worker from 'web-worker:./webworker.js';
2-
import { pyLog, pyExecState, pyInstallLog, isPyExecuting, isPyReadyState, isPyReady } from "./store";
2+
import { pyLog, pyExecState, pyInstallLog, isPyExecuting, isPyReadyState, isPyReady } from "./store.js";
3+
import { PyRunner } from './interfaces.js';
34

45
/** The main composable */
5-
const usePython = () => {
6+
const usePython = (): PyRunner => {
67
const _pyodideWorker = new worker();
78
//const _pyodideWorker = new Worker(new URL('./webworker.js', import.meta.url), { type: 'classic' })
89
let _callback: (value: {

‎src/store.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { map, atom, computed } from 'nanostores'
2-
import { PyLog, PyInstallLog } from "./interfaces";
2+
import { PyLog, PyInstallLog } from "./interfaces.js";
33

44
const pyLog = map<PyLog>({
55
id: "",

‎src/webworker.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
importScripts("https://cdn.jsdelivr.net/pyodide/v0.22.1/full/pyodide.js");
1+
importScripts("https://cdn.jsdelivr.net/pyodide/v0.25.0/full/pyodide.js");
22

33
var isPyLoaded = false;
44
var namespaces = {};

0 commit comments

Comments
 (0)