You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
2. Run `poetry run pip install --verbose python/pminit ./`. This command automatically compiles the project and installs the project as well as dependencies into the poetry virtualenv.
64
+
2. Run `poetry install`. This command automatically compiles the project and installs the project as well as dependencies into the poetry virtualenv.
65
+
66
+
If you are using VSCode, you can just press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>B</kbd> to [run build task](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks) - We have [the `tasks.json` file configured for you](.vscode/tasks.json).
61
67
62
68
## Running tests
63
69
1. Compile the project
64
70
2. Install development dependencies: `poetry install --no-root --only=dev`
65
71
3. From the root directory, run `poetry run pytest ./tests/python`
66
72
73
+
For VSCode users, similar to the Build Task, we have a Test Task ready to use.
74
+
67
75
## Using the library
68
76
69
77
### Install from [PyPI](https://pypi.org/project/pythonmonkey/)
@@ -98,22 +106,147 @@ Type "help", "copyright", "credits" or "license" for more information.
98
106
99
107
Alternatively, you can build a `wheel` package by running `poetry build --format=wheel`, and install it by `pip install dist/*.whl`.
100
108
109
+
## Debugging Steps
110
+
111
+
1. [build the project locally](#build-instructions)
112
+
2. To use gdb, run `poetry run gdb python`.
113
+
See [Python Wiki: DebuggingWithGdb](https://wiki.python.org/moin/DebuggingWithGdb)
114
+
115
+
If you are using VSCode, it's more convenient to debug in [VSCode's built-in debugger](https://code.visualstudio.com/docs/editor/debugging). Simply press <kbd>F5</kbd> on an open Python to start debugging - We have [the `launch.json`file configured for you](.vscode/launch.json).
**`.json`--JSON module; exports are the result of parsing the JSON text in the file
140
+
141
+
### globalThis
142
+
A Python Dict which is equivalent to the globalThis objectin JavaScript.
143
+
144
+
### createRequire(filename, extraPaths, isMain)
145
+
Factory function which returns a new require function
146
+
- filename: the pathname of the module that this require function could be used for
147
+
- extraPaths: [optional] a list of extra paths to search to resolve non-relative and non-absolute module identifiers
148
+
- isMain: [optional] Trueif the require function is being created for a main module
149
+
150
+
### runProgramModule(filename, argv, extraPaths)
151
+
Load and evaluate a program (main) module. Program modules must be written in JavaScript. Program modules are not
152
+
necessary unless the main entry point of your program is written in JavaScript.
153
+
- filename: the location of the JavaScript source code
154
+
- argv: the program's argument vector
155
+
- extraPaths: [optional] a list of extra paths to search to resolve non-relative and non-absolute module identifiers
156
+
157
+
Care should be taken to ensure that only one program module is run per JS context.
158
+
159
+
## Built-In Functions
160
+
-`console`
161
+
-`setTimeout`
162
+
-`setInterval`
163
+
-`clearTimeout`
164
+
-`clearInterval`
165
+
166
+
### CommonJS Subsystem Additions
167
+
The CommonJS subsystem is activated by invoking the `require`or`createRequire` exports of the (Python)
168
+
pythonmonkey module.
169
+
-`require`
170
+
-`exports`
171
+
-`module`
172
+
-`python.print`- the Python print function
173
+
-`python.getenv`- the Python getenv function
174
+
-`python.stdout`- an objectwith`read`and`write` methods, which read and write to stdout
175
+
-`python.stderr`- an objectwith`read`and`write` methods, which read and write to stderr
176
+
-`python.exec`- the Python exec function
177
+
-`python.eval`- the Python eval function
178
+
-`python.exit`- the Python exit function (wrapped to return BigInt in place of number)
179
+
-`python.paths`- the Python sys.paths list (currently a copy; will become an Array-like reflection)
180
+
181
+
## Type Transfer (Coercion / Wrapping)
182
+
When sending variables from Python into JavaScript, PythonMonkey will intelligently coerce or wrap your
183
+
variables based on their type. PythonMonkey will share backing stores (use the same memory) for ctypes,
184
+
typed arrays, and strings; moving these types across the language barrier is extremely fast because
185
+
there is no copying involved.
186
+
187
+
*Note:* There are plans in Python 3.12 (PEP623) to change the internal string representation so that
188
+
every character in the string uses four bytes of memory. This will break fast string transfers
189
+
for PythonMonkey, as it relies on the memory layout being the same in Python and JavaScript. As
190
+
of this writing (July 2023), "classic" Python strings still work in the 3.12 beta releases.
191
+
192
+
Where shared backing store isnot possible, PythonMonkey will automatically emit wrappers that use
193
+
the "real" data structure as its value authority. Only immutable intrinsics are copied. This means
194
+
that if you update an objectin JavaScript, the corresponding Dict in Python will be updated, etc.
195
+
196
+
| Python Type | JavaScript Type |
197
+
|:------------|:----------------|
198
+
| String | string
199
+
| Integer | number
200
+
| Bool | boolean
201
+
| Function | function
202
+
| Dict |object
203
+
| List | Array-like object
204
+
| datetime | Date object
205
+
| awaitable | Promise
206
+
| Error | Error object
207
+
| Buffer | ArrayBuffer
208
+
209
+
| JavaScript Type | Python Type |
210
+
|:---------------------|:----------------|
211
+
| string | String
212
+
| number | Float
213
+
| bigint | Integer
214
+
| boolean | Bool
215
+
| function | Function
216
+
|object- most | JSObjectProxy which inherits from Dict
217
+
|object- Date | datetime
218
+
|object- Array | List
219
+
|object- Promise | awaitable
220
+
|object- ArrayBuffer | Buffer
221
+
|object-type arrays | Buffer
222
+
|object- Error | Error
223
+
224
+
## Tricks
225
+
### Integer Type Coercion
226
+
You can force a number in JavaScript to be coerced as an integer by casting it to BigInt.
227
+
```javascript
228
+
function myFunction(a, b) {
229
+
const result = calculate(a, b);
230
+
return BigInt(Math.floor(result));
231
+
}
232
+
```
233
+
234
+
### Symbol injection via cross-language IIFE
235
+
You can use a JavaScript IIFE to create a scope in which you can inject Python symbols:
236
+
```python
237
+
globalThis.python.exit = pm.eval("""'use strict';
238
+
(exit) => function pythonExitWrapper(exitCode) {
239
+
if (typeof exitCode === 'number')
240
+
exitCode = BigInt(Math.floor(exitCode));
241
+
exit(exitCode);
242
+
}
243
+
""")(sys.exit);
244
+
```
245
+
107
246
# Troubleshooting Tips
108
247
109
248
## REPL - pmjs
110
-
A basic JavaScript shell, `pmjs`, ships with PythonMonkey.
249
+
A basic JavaScript shell, `pmjs`, ships with PythonMonkey. This shell can also run JavaScript programs with
111
250
112
251
## CommonJS (require)
113
252
If you are having trouble with the CommonJS require function, set environment variable DEBUG='ctx-module*'and you can see the filenames it tries to laod.
114
-
115
-
### Extra Symbols
116
-
Loading the CommonJS subsystem declares some extra symbols which may be helpful in debugging -
0 commit comments