Wes/module system

.gitignore

@@ -1,19 +1,22 @@
 build/
 .vscode/
 pyvenv.cfg
+python/pythonmonkey/version.py
+python/pythonmonkey/node_modules
 bin/
 lib/*
 .pytest_cache
 .DS_Store
 firefox-*.tar.xz
 firefox-*/
-tests/__pycache__/*
-tests/python/__pycache__/*
+__pycache__
 Testing/Temporary
 _spidermonkey_install
-__pycache__
+__pycache__/*
 dist
 *.so
+_spidermonkey_install/*
+*~
 *.dylib
 *.dll
 *.pyd

CMakeLists.txt

@@ -55,7 +55,7 @@ if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
     set(PYTHON_INCLUDE_DIR ${Python_INCLUDE_DIRS})
     set(PYTHON_LIBRARIES ${Python_LIBRARIES})
     message("Apple - Using Python:${Python_VERSION_MAJOR} - Libraries:${PYTHON_LIBRARIES} - IncludeDirs: ${PYTHON_INCLUDE_DIR}")
-  elseif(LINUX)
+  elseif(UNIX)
     find_package(Python 3.8 COMPONENTS Interpreter Development REQUIRED)
     set(Python_FIND_VIRTUALENV FIRST) # (require cmake >= v3.15 and this is the default) use the Python version configured by pyenv if available
     set(PYTHON_LIBRARIES ${Python_LIBRARIES})

README.md

@@ -6,7 +6,7 @@
 PythonMonkey is a Mozilla [SpiderMonkey](https://firefox-source-docs.mozilla.org/js/index.html) JavaScript engine embedded into the Python VM,
 using the Python engine to provide the JS host environment.
 
-This product is in an early stage, approximately 65% to MVP as of March 2023. It is under active development by Distributive Corp.,
+This product is in an early stage, approximately 80% to MVP as of May 2023. It is under active development by Distributive Corp.,
 https://distributive.network/. External contributions and feedback are welcome and encouraged.
 
 The goal is to make writing code in either JS or Python a developer preference, with libraries commonly used in either language
@@ -30,15 +30,15 @@ this package to execute our complex `dcp-client` library, which is written in JS
 - [done] JS functions coerce to Python function wrappers
 - [done] JS exceptions propagate to Python
 - [done] Implement `eval()` function in Python which accepts JS code and returns JS->Python coerced values
-- [underway] NodeJS+NPM-compatible CommonJS module system
+- [done] NodeJS+NPM-compatible CommonJS module system
 - [done] Python strings coerce to JS strings
 - [done] Python intrinsics coerce to JS intrinsics
-- Python dicts coerce to JS objects
-- Python `require` function, returns a coerced dict of module exports
+- [done] Python dicts coerce to JS objects
+- [done] Python `require` function, returns a coerced dict of module exports
 - [done] Python functions coerce to JS function wrappers
-- CommonJS module system .py loader, loads Python modules for use by JS
+- [done] CommonJS module system .py loader, loads Python modules for use by JS
 - JS object->Python dict coercion supports inherited-property lookup (via __getattribute__?)
-- Python host environment supplies event loop, including EventEmitter, setTimeout, etc.
+- [done] Python host environment supplies event loop, including EventEmitter, setTimeout, etc.
 - Python host environment supplies XMLHttpRequest (other project?)
 - Python host environment supplies basic subsets of NodeJS's fs, path, process, etc, modules; as-needed by dcp-client (other project?)
 - Python TypedArrays coerce to JS TypeArrays
@@ -53,6 +53,7 @@ this package to execute our complex `dcp-client` library, which is written in JS
     - rust
     - python3.8 or later with header files (python3-dev)
     - spidermonkey 102.2.0 or later
+    - npm (nodejs)
     - [Poetry](https://python-poetry.org/docs/#installation)
     - [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning)
 
@@ -95,3 +96,23 @@ Type "help", "copyright", "credits" or "license" for more information.
 ```
 
 Alternatively, you can build a `wheel` package by running `poetry build --format=wheel`, and install it by `pip install dist/*.whl`.
+
+## Examples
+
+* [examples/](examples/)
+* https://github.com/Distributive-Network/PythonMonkey-examples
+* https://github.com/Distributive-Network/PythonMonkey-Crypto-JS-Fullstack-Example
+
+# Troubleshooting Tips
+
+## REPL - pmjs 
+A basic JavaScript shell, `pmjs`, ships with PythonMonkey.
+
+## 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.
+
+### Extra Symbols
+Loading the CommonJS subsystem declares some extra symbols which may be helpful in debugging -
+- `python.print` - the Python print function
+- `python.getenv` - the Python getenv function
+

build_script.sh

@@ -1,3 +1,12 @@
+#! /bin/bash
+#
+# @file         build.sh
+# @author       Giovanni Tedesco <giovanni@distributive.network>
+# @date         Aug 2022
+
+cd `dirname "$0"`
+topDir=`pwd`
+
 # Get number of CPU cores
 CPUS=$(getconf _NPROCESSORS_ONLN 2>/dev/null || getconf NPROCESSORS_ONLN 2>/dev/null || echo 1)
 
@@ -14,3 +23,8 @@ else
   cmake .. 
 fi
 cmake --build . -j$CPUS --config Release
+
+cd ../python/pythonmonkey
+# npm is used to load JS components, see package.json
+cd "${topDir}/python/pythonmonkey/"
+npm i

examples/use-python-module.py

@@ -0,0 +1,9 @@
+# @file         use-require.py
+#               Sample code which demonstrates how to use require
+# @author       Wes Garland, wes@distributive.network
+# @date         Jun 2023
+
+import pythonmonkey as pm
+
+require = pm.createRequire(__file__)
+require('./use-python-module');

examples/use-python-module/index.js

@@ -0,0 +1,3 @@
+const { helloWorld } = require('./my-python-module');
+helloWorld()
+

examples/use-python-module/my-python-module.py

@@ -0,0 +1,5 @@
+def helloWorld():
+  print('hello, world!')
+
+exports['helloWorld'] = helloWorld
+

examples/use-require.py

@@ -0,0 +1,11 @@
+# @file         use-require.py
+#               Sample code which demonstrates how to use require
+# @author       Wes Garland, wes@distributive.network
+# @date         Jun 2023
+
+import pythonmonkey as pm
+
+require = pm.createRequire(__file__)
+require('./use-require/test1');
+print("Done")
+

examples/use-require/test1.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const makeOutput = require('./test2').makeOutput;
+
+makeOutput('hello world');

examples/use-require/test2.js

@@ -0,0 +1,9 @@
+'use strict'
+
+exports.makeOutput = function makeOutput()
+{
+  const argv = Array.from(arguments);
+  argv.unshift('TEST OUTPUT: ');
+  python.print.apply(null, argv);
+}
+

js-test-runner

@@ -0,0 +1,16 @@
+#! /usr/bin/env python3
+# @file         js-test-runner
+#               A simple test driver for peter-jr that runs JS code via PythonMonkey.require
+# @author       Wes Garland, wes@distributive.network
+# @date         Jun 2023
+
+import sys, os
+import pythonmonkey as pm
+
+# Main
+require = pm.createRequire(__file__)
+require('console');
+
+testName = os.path.realpath(sys.argv[1]);
+testDir = os.path.dirname(testName);
+pm.createRequire(testName)(testName);

peter-jr

@@ -0,0 +1,130 @@
+#! /bin/bash
+#
+# @file         peter-js
+#               A simple test framework in the spirit of Peter (npmjs.com/packages/peter) for testing
+#               basic PythonMonkey functionality.
+#
+#               Exit Codes:
+#               0 - all tests passed
+#               1 - one or more tests failed
+#               2 - no tests ran
+#               3 - internal error
+#
+# @author       Wes Garland, wes@distributive.network
+# @date         Jun 2023
+#
+runDir=`pwd`
+cd `dirname "$0"`
+topDir=`pwd`
+cd "$runDir"
+
+set -u
+set -o pipefail
+peter_exit_code=2
+
+if [ "${1:-}" = "-v" ]; then
+  VERBOSE=1
+  shift
+else
+  VERBOSE="${VERBOSE:-}"
+fi
+
+[ "${1:-}" ] || set "${topDir}/tests/js"
+testLocations=("$@")
+
+function panic()
+{
+  echo "PANIC: $*" >&2
+  exit 3
+}
+
+TMP=`mktemp -d`
+([ "${TMP}" ] && [ -d "${TMP}" ]) || exit 3
+
+trap "rm -r \"${TMP}\"" EXIT
+
+if [ "$VERBOSE" ]; then
+  stdout="/dev/stdout"
+  stderr="/dev/stderr"
+else
+  stdout="$TMP/stdout"
+  stderr="$TMP/stderr"
+fi
+
+red()
+{
+  printf "\e[0;31m%s\e[0m" "$*"
+}
+
+green()
+{
+  printf "\e[0;32m%s\e[0m" "$*"
+}
+
+yellow()
+{
+  printf "\e[0;33m%s\e[0m" "$*"
+}
+
+grey()
+{
+  printf "\e[0;90m%s\e[0m" "$*"
+}
+
+(
+  for loc in "${testLocations[@]}"
+  do
+    find $(realpath "$loc") -type f -name \*.simple
+    find $(realpath "$loc") -type f -name \*.bash
+  done
+) \
+| while read file
+  do
+    sfile=$(realpath --relative-to="${runDir}" "${file}")
+    printf 'Testing %-40s ... ' "${sfile}"
+    ext="${file##*.}"
+    (
+      case "$ext" in
+        "simple")
+          "${topDir}/js-test-runner" "$file"
+          exitCode="$?"
+          ;;
+        "bash")
+          bash "$file"
+          exitCode="$?"
+          ;;
+        *)
+          echo
+          panic "${file}: invalid extension '$ext'"
+          ;;
+      esac
+
+      exit "$exitCode"
+    )> $stdout 2>$stderr
+    exitCode="$?"
+
+    if [ "$exitCode" = "0" ]; then
+      echo "$(green PASS)"
+      [ "${peter_exit_code}" = "2" ] && peter_exit_code=0
+      printf "\e[0;31m"
+      [ "$VERBOSE" ] || cat "$stderr"
+      printf "\e[0m"
+    else
+      echo "$(red FAIL)"
+      peter_exit_code=1
+      if [ ! "$VERBOSE" ]; then
+        echo
+        echo "$(grey --) $(yellow ${file}) $(grey vvvvvvvvvvvvvv)"
+        cat "$stdout" | sed 's/^/   /'
+        printf "\e[0;31m"
+        cat "$stderr" | sed -e 's/^/   /'
+        printf "\e[0m"
+        echo "$(grey --) $(yellow ${file}) $(grey ^^^^^^^^^^^^^^)"
+        echo
+      fi
+    fi
+    (exit ${peter_exit_code})
+  done
+peter_exit_code="$?"
+
+exit ${peter_exit_code}