diff --git a/configure.ac b/configure.ac
index 0e82c06773daed1c38295fbe23989c10fbdce0b8..0aeaff0a5494b2e520482ea93a67e58e2d2b4d97 100644
--- a/configure.ac
+++ b/configure.ac
@@ -626,6 +626,9 @@ AS_IF([test "x$SWIG" != "x"],[
AC_CONFIG_FILES([scripting/setup.py], [chmod +x scripting/setup.py])
AC_CONFIG_FILES([scripting/__init__.py])
AC_CONFIG_FILES([scripting/mpython], [chmod +x scripting/mpython])
+ # force python package installation dir name to match package name:
+ pkgpythondir=\${pythondir}/maestro_core
+ pkgpyexecdir=\${pyexecdir}/maestro_core
])
diff --git a/scripting/.gitignore b/scripting/.gitignore
index 1c378cb8a0fb8d360a88b47d5f2f284c0981f559..41f937d284778e276ceef12fc7b214c64ef817aa 100644
--- a/scripting/.gitignore
+++ b/scripting/.gitignore
@@ -1,7 +1,11 @@
__init__.py
maestro-py_wrap.c
maestro.py
+maestro_core.py
setup.py
__pycache__
maestro.*.so
_maestro.so
+mpython
+build/
+README.html
diff --git a/scripting/Makefile.am b/scripting/Makefile.am
index a6157f0e028b14d1e7b5208e5d5dd50b5667cff8..b26280f5bd899ebb70829394f2858171bd0afee0 100644
--- a/scripting/Makefile.am
+++ b/scripting/Makefile.am
@@ -42,12 +42,12 @@ if WITH_SWIG
BUILT_SOURCES = maestro-py_wrap.c
SWIG_SOURCES = maestro-py.i
-pkgpython_PYTHON = maestro.py __init__.py setup.py
-pkgpyexec_LTLIBRARIES = _maestro.la
-_maestro_la_LDFLAGS = -avoid-version -module
-_maestro_la_SOURCES = maestro-py_wrap.c $(SWIG_SOURCES)
-_maestro_la_LIBADD = $(top_srcdir)/libmaestro.la -lpython@PYTHON_VERSION@
-_maestro_la_CPPFLAGS = $(AX_SWIG_PYTHON_CPPFLAGS) \
+pkgpython_PYTHON = maestro_core.py __init__.py setup.py
+pkgpyexec_LTLIBRARIES = _maestro_core.la
+_maestro_core_la_LDFLAGS = -avoid-version -module
+_maestro_core_la_SOURCES = maestro-py_wrap.c $(SWIG_SOURCES)
+_maestro_core_la_LIBADD = $(top_srcdir)/libmaestro.la -lpython@PYTHON_VERSION@
+_maestro_core_la_CPPFLAGS = $(AX_SWIG_PYTHON_CPPFLAGS) \
-I$(top_srcdir)/include \
-I$(top_srcdir)/deps/mamba/common \
-I$(top_srcdir)/deps/mamba/memory \
@@ -68,11 +68,11 @@ WRAPPED = $(top_srcdir)/include/maestro.h\
$(top_srcdir)/include/maestro/scope.h \
$(top_srcdir)/include/maestro/status.h
-maestro-py_wrap.c maestro.py: $(SWIG_SOURCES) $(WRAPPED)
+maestro-py_wrap.c maestro_core.py: $(SWIG_SOURCES) $(WRAPPED)
$(SWIG) $(AX_SWIG_PYTHON_OPT) -I$(top_srcdir)/include -I/usr/include/python@PYTHON_VERSION@ -o $@ $<
-MAINTAINERCLEANFILES = maestro-py_wrap.c maestro.py
+MAINTAINERCLEANFILES = maestro-py_wrap.c maestro_core.py
endif # WITH_SWIG
diff --git a/scripting/README.md b/scripting/README.md
index ebc0014a57be171bc811dde90adaa93b6f796948..1262e7352e4f79287a07dcbeef7adf90c9420a60 100644
--- a/scripting/README.md
+++ b/scripting/README.md
@@ -1,8 +1,9 @@
Scripting interface to the maestro library
==========================================
+At this time we only provide a low-level python wrapper for the libmaestro library.
-We are providing a low-level wrapper library for `libmaestro` at this time for python.
+To avoid confusion with other packages called 'maestro' on pypi.org it is called `maestro_core`.
To build it, install swig from your system repositories, or from swig.org. A version >=4.0.1 is recommended.
@@ -40,16 +41,36 @@ Installation using setup.py
---------------------------
If you use the `setup.py` file provided you should be able to install
-the wrappers into 'the ususal place', e.g., the user site-packages or
-the `venv` package destination.
+the wrappers into 'the ususal place', e.g., the global python installation,
+user site-packages location or in a virtual environment as provided by the
+`venv` package.
+
+Examples:
+
+```
+./setup.py install
+```
+
+for a global installation.
+
+Using a virtual environment (assuming you have installed the `venv` and `wheel` packages, e.g., via `pip`):
+
+```
+# ensure virtual environment has wheel installed:
+pip install wheel
+# in $top_srcdir/scripting do:
+pip install .
+```
-THIS CURRENTLY DOES NOT WORK.
Installation into user-site-packages directory
------------------------------------------------
-See above -- use `setup.py`
-THIS CURRENTLY DOES NOT WORK.
+Use the `setup.py` script provided:
+
+```
+./setup.py install --user
+```
Testing without installation
@@ -60,3 +81,52 @@ configure time with enough PYTHONPATH so that the maestro package can be
imported successfully even while not yet installed. This is used during `make
check`, but may also be useful for experimenting.
+
+Usage
+-----
+
+All public API functions and constants are available in the
+`maestro_core` package via their C name. Return status codes are
+mapped to python exceptions, and functions that have
+effectively-output arguments in the C API are mapped to properly
+return (one or more) python return values.
+
+Example:
+
+```
+import maestro_core as M
+
+# initialize maestro runtime
+M.mstro_init("sample-workflow", "sample-component-1", 0)
+
+# Create two CDOs, no attributes so far
+cdo1 = M.mstro_cdo_declare("CDO 1", None)
+cdo2 = M.mstro_cdo_declare("CDO 2", None)
+
+# offer them
+M.mstro_cdo_offer(cdo1)
+M.mstro_cdo_offer(cdo2)
+
+# create another handle for the CDO named "CDO 2"
+cdo2_handle2 = M.mstro_cdo_declare("CDO 2", None)
+
+# announce we'll need it
+M.mstro_cdo_require(cdo2_handle2)
+M.mstro_cdo_demand(cdo2_handle2)
+
+# withdraw the initially offered CDOs
+M.mstro_cdo_withdraw(cdo1)
+M.mstro_cdo_withdraw(cdo2)
+
+# dispose handles
+M.mstro_cdo_dispose(cdo1)
+M.mstro_cdo_dispose(cdo2)
+M.mstro_cdo_dispose(cdo2_handle2)
+
+# stop runtime (can be restarted later)
+M.mstro_finalize()
+
+```
+
+
+
diff --git a/scripting/__init__.py.in b/scripting/__init__.py.in
index c89273944471632382499e59b1798cc24a03872a..85364f7a2f3b656f2228c2147f2ebdcc7a7f3e92 100644
--- a/scripting/__init__.py.in
+++ b/scripting/__init__.py.in
@@ -1,3 +1,3 @@
# Maestro public API
# Currently importing everything that swig wrapped; we may want to be more specific later on
-from .maestro import *
+from .maestro_core import *
diff --git a/scripting/maestro-py.i b/scripting/maestro-py.i
index 20064c8fda7b307a1981e16945fb59e2835dda37..8b042f23bac4e84d20dc844dd2b9f0d6debcf709 100644
--- a/scripting/maestro-py.i
+++ b/scripting/maestro-py.i
@@ -1,4 +1,4 @@
-%module maestro
+%module maestro_core
%include "typemaps.i"
%include "stdint.i"
%include "cpointer.i"
diff --git a/scripting/setup.py.in b/scripting/setup.py.in
index 43278f7aa6ea9d1902bb67bd4709e95ba4304652..83b54e6f763053d60c3cf23ada701d3d0382d2df 100644
--- a/scripting/setup.py.in
+++ b/scripting/setup.py.in
@@ -7,7 +7,7 @@ setup.py file for Maestro SWIG module
from distutils.core import setup, Extension
-maestro_module = Extension('maestro',
+maestro_module = Extension('_maestro_core',
sources=['maestro-py_wrap.c'],
include_dirs = ['@top_srcdir@/include',
'@top_srcdir@/deps/mamba/common',
@@ -17,10 +17,12 @@ maestro_module = Extension('maestro',
libraries = ['maestro'],
)
-setup (name = 'maestro',
+setup (name = 'maestro_core',
version = '@PACKAGE_VERSION@',
- author = "Maestro Project",
+ author = """Maestro Project""",
+ author_email = """emearesearchlab@hpe.com""",
+ license = """BSD-3""",
description = """Maestro swig module""",
ext_modules = [maestro_module],
- py_modules = ["maestro"],
+ py_modules = ["maestro_core"],
)