From d20746f92cfab349efb07d14c6ce4fa325e8e6ce Mon Sep 17 00:00:00 2001
From: Utz-Uwe Haus <uhaus@hpe.com>
Date: Tue, 8 Nov 2022 15:59:22 +0000
Subject: [PATCH] Fix installability of python wrappers
libtool-based, setup.py and pip-based install now working
python package name is 'maestro_core' due to too many maestro-* packages
being on pypi already.
---
configure.ac | 3 ++
scripting/.gitignore | 4 ++
scripting/Makefile.am | 16 ++++----
scripting/README.md | 82 +++++++++++++++++++++++++++++++++++++---
scripting/__init__.py.in | 2 +-
scripting/maestro-py.i | 2 +-
scripting/setup.py.in | 10 +++--
7 files changed, 99 insertions(+), 20 deletions(-)
diff --git a/configure.ac b/configure.ac
index 0e82c067..0aeaff0a 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 1c378cb8..41f937d2 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 a6157f0e..b26280f5 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 ebc0014a..1262e735 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 c8927394..85364f7a 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 20064c8f..8b042f23 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 43278f7a..83b54e6f 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"],
)
--
GitLab