Merge pull request #136 from Distributive-Network/Xmader/docs/update-readme

update readme

Author: Xmader

README.md

@@ -28,7 +28,7 @@ js_eval("console.log")('hello, world')
 
 ### Data Interchange
 - Strings share immutable backing stores whenever possible (when allocating engine choses UCS-2 or Latin-1 internal string representation) to keep memory consumption under control, and to make it possible to move very large strings between JS and Python library code without memory-copy overhead.
-- TypedArrays to share mutable backing stores; if this is not possible we will implement a copy-on-write (CoW) solution.
+- TypedArrays share mutable backing stores.
 - JS objects are represented by Python dicts
 - JS Date objects are represented by Python datetime.datetime objects
 - Intrinsics (boolean, number, null, undefined) are passed by value
@@ -86,9 +86,9 @@ For VSCode users, similar to the Build Task, we have a Test Task ready to use.
 
 ## Using the library
 
-### Install from [PyPI](https://pypi.org/project/pythonmonkey/)
+> npm (Node.js) is required **during installation only** to populate the JS dependencies.
 
-> PythonMonkey is not release-ready yet. Our first public release is scheduled for mid-June 2023.
+### Install from [PyPI](https://pypi.org/project/pythonmonkey/)
 
 ```bash
 $ pip install pythonmonkey
@@ -116,7 +116,12 @@ Type "help", "copyright", "credits" or "license" for more information.
 'Hello from Spidermonkey!'
 ```
 
-Alternatively, you can build a `wheel` package by running `poetry build --format=wheel`, and install it by `pip install dist/*.whl`.
+Alternatively, you can build installable packages by running
+```bash
+$ cd python/pminit && poetry build --format=sdist && cd - && mv -v python/pminit/dist/* ./dist/
+$ poetry build --format=wheel
+```
+and install them by `pip install ./dist/*`.
 
 ## Debugging Steps
 
@@ -135,6 +140,16 @@ If you are using VSCode, it's more convenient to debug in [VSCode's built-in deb
 ## API
 These methods are exported from the pythonmonkey module.
 
+### eval(code, evalOpts)
+### isCompilableUnit(code)
+### collect()
+### bigint(int)
+### `SpiderMonkeyError`
+### `JSObjectProxy`
+### `null`
+
+See definitions in [python/pythonmonkey/pythonmonkey.pyi](python/pythonmonkey/pythonmonkey.pyi).
+
 ### require(moduleIdentifier)
 Return the exports of a CommonJS module identified by `moduleIdentifier`, using standard CommonJS
 semantics
@@ -146,9 +161,9 @@ semantics
  - Modules are evaluated immediately after loading
  - Modules are not loaded until they are required
  - The following extensions are supported:
- ** `.js` - JavaScript module; source code decorates `exports` object
- ** `.py` - Python module; source code decorates `exports` dict
- ** `.json` -- JSON module; exports are the result of parsing the JSON text in the file
+  * `.js` - JavaScript module; source code decorates `exports` object
+  * `.py` - Python module; source code decorates `exports` dict
+  * `.json` - JSON module; exports are the result of parsing the JSON text in the file
 
 ### globalThis
 A Python Dict which is equivalent to the globalThis object in JavaScript.
@@ -168,19 +183,23 @@ necessary unless the main entry point of your program is written in JavaScript.
 
 Care should be taken to ensure that only one program module is run per JS context.
 
-## Built-In Functions
+## [Built-In Functions](python/pythonmonkey/global.d.ts)
+
 - `console`
+- `atob`
+- `btoa`
 - `setTimeout`
-- `setInterval`
 - `clearTimeout`
-- `clearInterval`
 
 ### CommonJS Subsystem Additions
 The CommonJS subsystem is activated by invoking the `require` or `createRequire` exports of the (Python)
 pythonmonkey module.
+
 - `require`
 - `exports`
 - `module`
+- `__filename`
+- `__dirname`
 - `python.print`  - the Python print function
 - `python.getenv` - the Python getenv function
 - `python.stdout` - an object with `read` and `write` methods, which read and write to stdout
@@ -264,6 +283,26 @@ globalThis.python.exit = pm.eval("""'use strict';
 """)(sys.exit);
 ```
 
+### Run Python event-loop
+
+You need an event-loop running to use `setTimeout` and `Promise`<=>`awaitable` coercion.
+
+```python
+import asyncio
+
+async def async_fn():
+  await pm.eval("""
+    new Promise((resolve) => setTimeout((...args) => { 
+        console.log(args);
+        resolve();
+      }, 1000, 42, "abc")
+    )
+  """)
+  await pm.eval("async (x) => await x")(asyncio.sleep(0.5))
+
+asyncio.run(async_fn())
+```
+
 # pmjs
 A basic JavaScript shell, `pmjs`, ships with PythonMonkey. This shell can act as a REPL or run
 JavaScript programs; it is conceptually similar to the `node` shell which ships with Node.js.
@@ -286,15 +325,15 @@ The program module, or main module, is a special module in CommonJS. In a progra
    (command-line arguments)
 
 ```console
-# echo "console.log('hello world')" > my-program.js
-# pmjs my-program.js
+$ echo "console.log('hello world')" > my-program.js
+$ pmjs my-program.js
 hello world
-#
+$
 ```
 
 ### CommonJS Module: JavaScript language
-```python
-# date-lib.js - require("./date-lib")
+```js
+// date-lib.js - require("./date-lib")
 const d = new Date();
 exports.today = `${d.getFullYear()}-${String(d.getMonth()).padStart(2,'0')}-${String(d.getDay()).padStart(2,'0')}`
 ```
@@ -309,15 +348,18 @@ exports['today'] = date.today()
 # Troubleshooting Tips
 
 ## CommonJS (require)
-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.
+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.
 
 ## pmjs
 - there is a `.help` menu in the REPL
 - there is a `--help` command-line option
 - the `-r` option can be used to load a module before your program or the REPL runs
 - the `-e` option can be used evaluate code -- e.g. define global variables -- before your program or the REPL runs
-- The REPL can evaluate Python expressions, storing them in variables named `$1`, `$2`, etc. ```
-# pmjs
+- The REPL can evaluate Python expressions, storing them in variables named `$1`, `$2`, etc.
+
+```console
+$ pmjs
+
 Welcome to PythonMonkey v0.2.0.
 Type ".help" for more information.
 > .python import sys

python/pythonmonkey/__init__.py

@@ -5,6 +5,7 @@
 # Expose the package version
 import importlib.metadata
 __version__= importlib.metadata.version(__name__)
+del importlib
 
 # Load the module by default to make `console`/`atob`/`btoa` globally available
 require("console")
@@ -13,7 +14,7 @@
 # Add the `.keys()` method on `Object.prototype` to get JSObjectProxy dict() conversion working
 # Conversion from a dict-subclass to a strict dict by `dict(subclass)` internally calls the .keys() method to read the dictionary keys, 
 # but .keys on a JSObjectProxy can only come from the JS side
-pm.eval("""
+pythonmonkey.eval("""
 (makeList) => {
   const keysMethod = {
     get() {

python/pythonmonkey/cli/pmjs.py

@@ -6,7 +6,7 @@
 import sys, os, readline, signal, getopt
 import pythonmonkey as pm
 globalThis = pm.eval("globalThis")
-evalOpts = { 'filename': __file__, 'fromPythonFrame': True, 'strict': False }
+evalOpts = { 'filename': __file__, 'fromPythonFrame': True, 'strict': False } # type: pm.EvalOptions
 
 if (os.getenv('PMJS_PATH')):
     requirePath = list(map(os.path.abspath, os.getenv('PMJS_PATH').split(':')))

python/pythonmonkey/global.d.ts

@@ -37,6 +37,9 @@ declare const python: {
   paths: string[];
 };
 
+declare var __filename: string;
+declare var __dirname: string;
+
 /** see `pm.eval` */
 declare function pmEval(code: string): any;
 

python/pythonmonkey/pythonmonkey.pyi

@@ -22,6 +22,18 @@ def eval(code: str, evalOpts: EvalOptions = {}, /) -> _typing.Any:
     JavaScript evaluator in Python
     """
 
+def isCompilableUnit(code: str) -> bool:
+    """
+    Hint if a string might be compilable Javascript without actual evaluation
+    """
+
+def internalBinding(namespace: str) -> JSObjectProxy:
+    """
+    INTERNAL USE ONLY
+
+    See function declarations in ./builtin_modules/internal-binding.d.ts
+    """
+
 def collect() -> None:
     """
     Calls the spidermonkey garbage collector

python/pythonmonkey/require.py

@@ -32,15 +32,16 @@
 import functools
 
 from . import pythonmonkey as pm 
+
 node_modules = os.path.abspath(
   os.path.join(
-    importlib.util.find_spec("pminit").submodule_search_locations[0],
+    importlib.util.find_spec("pminit").submodule_search_locations[0], # type: ignore
     "..",
     "pythonmonkey",
     "node_modules"
   )
 )
-evalOpts = { 'filename': __file__, 'fromPythonFrame': True }
+evalOpts = { 'filename': __file__, 'fromPythonFrame': True } # type: pm.EvalOptions
 
 # Add some python functions to the global python object for code in this file to use.
 globalThis = pm.eval("globalThis;", evalOpts)
@@ -240,11 +241,11 @@ def load(filename: str) -> Dict:
     name = os.path.basename(filename)
     if name not in sys.modules:
         sourceFileLoader = machinery.SourceFileLoader(name, filename)
-        spec = importlib.util.spec_from_loader(sourceFileLoader.name, sourceFileLoader)
+        spec: machinery.ModuleSpec = importlib.util.spec_from_loader(sourceFileLoader.name, sourceFileLoader) # type: ignore
         module = importlib.util.module_from_spec(spec)
         sys.modules[name] = module
-        module.exports = {}
-        spec.loader.exec_module(module)
+        module.exports = {} # type: ignore
+        spec.loader.exec_module(module) # type: ignore
     else:
         module = sys.modules[name]
     return module.exports
@@ -344,3 +345,6 @@ def require(moduleIdentifier: str):
     if not os.path.exists(filename):
       filename = os.path.join(os.getcwd(), "__main__") # use the CWD instead
     return createRequire(filename)(moduleIdentifier)
+
+# Restrict what are exposed to the pythonmonkey module.
+__all__ = ["globalThis", "require", "createRequire", "runProgramModule"]