feat: Add Execution Engines

.gitignore

@@ -15,3 +15,4 @@ py/coverage.xml
 *.out.*
 /ts/types.ts
 .Rproj.user
+py/htmlcov

.travis.yml

@@ -22,6 +22,7 @@ matrix:
 
       install:
         - make -C py setup
+        - make -C py install
 
       script:
         - make -C py lint

package.json

@@ -38,6 +38,7 @@
     "@stencila/dev-config": "^1.1.3",
     "@stencila/encoda": "^0.61.2",
     "@stencila/logga": "^1.2.1",
+    "@types/astring": "^1.3.0",
     "@types/fs-extra": "^8.0.0",
     "@types/jest": "^24.0.15",
     "@types/js-yaml": "^3.12.1",
@@ -46,6 +47,7 @@
     "ajv": "^6.10.2",
     "better-ajv-errors": "^0.6.4",
     "browser-sync": "^2.26.7",
+    "del": "^5.0.0",
     "fs-extra": "^8.1.0",
     "globby": "^10.0.1",
     "husky": "^3.0.1",
@@ -125,5 +127,9 @@
   "release": {
     "extends": "@stencila/semantic-release-config",
     "message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
+  },
+  "dependencies": {
+    "astring": "^1.4.1",
+    "meriyah": "^1.6.10"
   }
 }

py/.coveragerc

@@ -1,3 +1,3 @@
-[run]
+[execute_document]
 omit =
     */stencila/schema/types.py

py/Makefile

@@ -3,12 +3,15 @@ all: setup clean regen lint test build
 setup:
 	pip3 install --upgrade -r requirements-dev.txt
 
+install:
+	python3 setup.py install
+
 regen:
 	npm run build:py
 
 lint:
-	pylint stencila/schema
-	mypy stencila/schema
+	pylint stencila/schema --max-line-length=120
+	mypy stencila/schema --ignore-missing-imports
 
 test:
 	tox
@@ -17,4 +20,4 @@ build:
 	python3 setup.py sdist bdist_wheel
 
 clean:
-	rm -rf build .coverage coverage.xml *.egg-info .tox **/__pycache__
+	rm -rf build .coverage htmlcov coverage.xml *.egg-info .tox **/__pycache__

py/README.md

@@ -32,3 +32,45 @@ serialized = """{"type": "Heading", "content": ["Heading Text"], "depth": 2}"""
 
 h2 = from_json(serialized)
 ```
+
+## Interpreter
+
+This library can also be used to interpret executable documents. Once installed it can be used like this:
+
+```bash
+$ python3 -m stencila.schema execute <inputfile> <outputfile> [parameters]
+```
+
+`inputfile` and/or `outputfile` can be set to `-` to read from stdin and/or write to stdout (respectively).
+
+`[parameters]` is a list of parameters to pass to the document –- these will differ based on what the document defines.
+They can be passed either by `--parameter_name=parameter_value` or `--parameter_name parameter_value`. Each parameter
+must be named.
+
+### Usage in Development
+
+There are three options to run the interpreter without installing this package (which can be useful when developing).
+
+#### setup.py develop
+
+Run `python3 setup.py develop` which will link this library into your site packages directory. You can then execute
+documents with the above Interpreter command.
+
+#### Run interpreter.py directly
+
+You can run the `interpreter.py` script directly, the arguments are the same as running as a module in the example
+above except the first `execute` argument is omitted:
+
+```bash
+$ python3 schema/py/stencila/schema/interpreter.py <inputfile> <outputfile> [parameters]
+```
+
+### cd into stencila directory
+
+You can run the interpreter as a module by changing into the `stencila` directory first, and then ommitting the
+`stencila` namespace:
+
+```bash
+$ cd schema/py/stencila
+$ python3 -m schema execute <inputfile> <outputfile> [parameters]
+```

py/requirements-dev.txt

@@ -1,4 +1,5 @@
-twine
 mypy
 pylint
+tox
 tox-travis
+twine

py/setup.py

@@ -73,7 +73,9 @@ def run(self):
     python_requires='>=3.6.0',
     url='https://github.com/stencila/schema',
     packages=['stencila.schema'],
-    install_requires=[],
+    install_requires=[
+        'astor==0.8.0'
+    ],
     extras_require={},
     include_package_data=True,
     license='Apache-2.0',

py/stencila/schema/__main__.py

@@ -0,0 +1,35 @@
+"""
+__main__.py can be executed (once this library is installed) like this:
+
+python3 -m stencila.schema execute <inputfile> <outputfile> [parameters]
+
+See READEME.md for more information.
+
+Warning: `eval` and `exec` are used to run code in the document. Don't execute documents that you haven't verified
+yourself.
+"""
+
+import logging
+from sys import argv, stderr, stdout
+
+from .interpreter import execute_from_cli
+
+
+def cli_execute():
+    """Execute an executable document, delegating to the execute_from_cli function."""
+    execute_from_cli(argv[2:])
+
+
+def main():
+    """The main entry point to this module, read the first CLI arg and call out to the corresponding function."""
+    command = argv[1] if len(argv) > 1 else ''
+
+    if command == 'execute':
+        logging.basicConfig(stream=stdout, level=logging.DEBUG)
+        cli_execute()
+    else:
+        stderr.write('Unknown command "{}"\n'.format(command))
+
+
+if __name__ == '__main__':
+    main()