* Fix bool Python ser bug

* Add stricter type validation in PythonExtension.groovy
* Add protocol doc

Author: royjacobson

.gitignore

@@ -7,3 +7,5 @@
 build
 work
 out
+
+py/*.egg-info/

doc/protocol.md

@@ -0,0 +1,40 @@
+# nf-python Protocol Specification
+
+`nf-python` currently uses environment variables and a custom JSON-based serialization protocol
+for data passage between Nextflow and the Python code. This is subject to changes in the future.
+The protocol is described here:
+
+## Environment Variables
+
+- `NEXTFLOW_INFILE`: Path to a temporary JSON file containing serialized input arguments
+- `NEXTFLOW_OUTFILE`: Path to a temporary JSON file where serialized output are written by the Python code
+- `NEXTFLOW_PYTHON_COMPAT_VER`: Protocol compatibility version (currently "1")
+
+## JSON Type System
+
+Data is exchanged using typed JSON arrays in the format `[type, value]`, where:
+- `type`: String identifying the data type
+- `value`: The actual data, possibly containing nested typed values
+
+## Type Conversions
+
+The following types are supported for usage as arguments and output values,
+and are automatically serialized and deserialized between native runtime objects.
+
+| Nextflow/Groovy Type | JSON Type | Python Type |
+|-------------|-----------|------------|
+| `null` | `["Null", null]` | `None` |
+| `List` | `["List", [...]]` | `list` |
+| `Set` | `["Set", [...]]` | `set` |
+| `Map` | `["Map", [[k1, v1], [k2, v2]]]` | `dict` |
+| `String` | `["String", "..."]` | `str` |
+| `Integer(*)`, `Long` | `["Integer", n]` | `int` |
+| `BigDecimal` | `["Decimal", "..."]` | `decimal.Decimal` |
+| `Double(*)`, `Float` | `["Float", n]` or `["Float", "inf/nan/-inf"]` | `float` |
+| `Boolean` | `["Boolean", true/false]` | `bool` |
+| `Path` | `["Path", "..."]` | `pathlib.Path` |
+| `nextflow.util.Duration(*)`, `java.time.Duration` | `["Duration", ms]` | `datetime.timedelta` |
+| `nextflow.util.MemoryUnit` | `["MemoryUnit", bytes]` | `MemoryUnit` |
+| `nextflow.util.VersionNumber` | `["VersionNumber", [major, minor, patch]]` | `VersionNumber` |
+
+(*): Used as a Groovy type when deserializing result when multiple types map to the same Python type.

plugins/nf-python/src/main/nextflow/python/PythonExtension.groovy

@@ -166,6 +166,20 @@ from nf_python import nf
         throw new IllegalArgumentException("Expected a list, got: $obj")
     }
 
+    private static Integer cInteger(Object obj) {
+        if (obj instanceof Integer) {
+            return obj
+        }
+        throw new IllegalArgumentException("Expected an integer, got: $obj")
+    }
+
+    private static Boolean cBoolean(Object obj) {
+        if (obj instanceof Boolean) {
+            return obj as Boolean
+        }
+        throw new IllegalArgumentException("Expected an boolean, got: $obj")
+    }
+
     private static def unpackPython(obj) {
         List objList = cList(obj)
         if (objList.size() != 2) {
@@ -186,15 +200,15 @@ from nf_python import nf
                     }
                 }
                 return result
-            case 'String': return data
-            case 'Integer': return data
-            case 'Decimal': return new BigDecimal(cString(data) as String)
+            case 'String': return cString(data)
+            case 'Integer': return cInteger(data)
+            case 'Decimal': return new BigDecimal(cString(data))
             case 'Float': return unpackFloat(data)
-            case 'Boolean': return data
+            case 'Boolean': return cBoolean(data)
             case 'Null': return null
             case 'Path': return java.nio.file.Paths.get(cString(data))
-            case 'Duration': return Duration.of(data as long)
-            case 'MemoryUnit': return new MemoryUnit(data as long)
+            case 'Duration': return Duration.of(cInteger(data))
+            case 'MemoryUnit': return new MemoryUnit(cInteger(data))
             case 'VersionNumber':
                 List dataList = cList(data)
                 if (dataList.size() == 3) {

py/nf_python/nextflow.py

@@ -113,14 +113,15 @@ def pack_python(python_object):
         ]
     elif isinstance(python_object, str):
         return ["String", python_object]
+    # Bool has to come before int because bool is a subclass of int!
+    elif isinstance(python_object, bool):
+        return ["Boolean", python_object]
     elif isinstance(python_object, int):
         return ["Integer", python_object]
     elif isinstance(python_object, decimal.Decimal):
         return ["Decimal", str(python_object)]
     elif isinstance(python_object, float):
         return ["Float", pack_float(python_object)]
-    elif isinstance(python_object, bool):
-        return ["Boolean", python_object]
     elif python_object is None:
         return ["Null", None]
     elif isinstance(python_object, pathlib.Path):