[gnuastro-commits] master 5bc6a886: Configure: Updated Python3 checks for venv and different versions

[Mohammad Akhlaghi]

branch: master
commit 5bc6a88698d0530d5d924521da97340cb5fd301b
Author: Jash Shah <jash28582@gmail.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Configure: Updated Python3 checks for venv and different versions
    
    Until now, the Python interface was built conditionally if Python3 or
    greater, with NumPy installed on it was found. The checks performed for
    this in the configure.ac script used both 'AC_CHECK_PROG' and
    'AM_PATH_PYTHON' macros which didn't account for some special cases as
    mentioned below.
    
    1. AC_CHECK_PROG checked for the 'python3' command, this meant that Python
       would not have been detected for systems that had multiple python3
       versions or just a different name for their python3 interpreter (for
       example 'python3.8'). AM_PATH_PYTHON macro solves this issue, by
       checking for python versions greater than or equal to a certain version
       (3.0 in our case). However, the further checks for NumPy were also
       dependent on the the success of 'AC_CHECK_PROG'.
    
    2. For virtual environements, in some cases 'AM_PATH_PYTHON' would detect
       the global Python Interpreter instead of the virtual env. This meant
       that if a user had Python3 and NumPy installed in their virtual env. it
       would not be detected.
    
    3. The '--without-python' option was not documented in the book and Python
       was not mentioned as an optional dependency.
    
    With this commit, both the issues above have been addressed: 1)
    'AC_CHECK_PROG' has been removed. Therefore, only 'AM_PATH_PYTHON' is used,
    which is more general. 2) It is now possible to set the 'PYTHON'
    environment variable to point to the virtual env's Python before running
    the configure script. A cartouche has been added in the optional
    dependencies section of the book regarding this. 3) The '--without-python'
    option is now documented in the configuration options and Python has been
    added as an optional dependency.
---
 NEWS              |  1 -
 configure.ac      | 15 +++++++++++----
 doc/gnuastro.texi | 41 ++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/NEWS b/NEWS
index 9729d36b..96d181df 100644
--- a/NEWS
+++ b/NEWS
@@ -111,7 +111,6 @@ See the end of the file for license conditions.
       keyword within the FITS files.
 
   Library functions:
-
   - gal_box_border_rotate_around_center: width of box after rotation.
   - gal_color_id_to_name: return the name of a color from its ID.
   - gal_color_in_rgb: return the fraction of red-green-blue in a color.
diff --git a/configure.ac b/configure.ac
index c60f852d..e02abf6d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -761,6 +761,10 @@ AS_IF([test "x$has_topcat" = "xno"], [anywarnings=yes])
 #                   to get the include path for Python.h header.
 #     np_check_cmd: Uses numpy's get_include method to get the
 #                   include path for NumPy's core C-API.
+#
+# NOTE: If using a venv then set the $PYTHON variable to point to the
+#       python3 command of the venv before running ./configure to perform
+#       all the following checks in the venv.
 py_check_cmd='from sysconfig import get_paths; \
               print(get_paths().get("include"))'
 np_check_cmd='from numpy import get_include; \
@@ -771,13 +775,13 @@ AC_ARG_WITH([python],
             [], [with_python=yes])
 AS_IF([test "x$with_python" != xno],
       [
-        AC_CHECK_PROG(has_python3, python3, [yes], [no])
+        # Checks if user has a Python version>=3.0
         AM_PATH_PYTHON(3.0,,[:])
-        AS_IF([test $has_python3 = yes],
+        AS_IF([test "$PYTHON" != :],
         [
           AC_DEFINE(HAVE_PYTHON, [1],
                     [Define to 1 if you have Python3.])
-          AC_MSG_CHECKING(if numpy is available in the python3 installation)
+          AC_MSG_CHECKING(if numpy is available in the $PYTHON installation)
           AS_IF([$PYTHON -c "$py_check_cmd" &> /dev/null],
                 [python_includedir="$($PYTHON -c "$py_check_cmd")"
                  AS_IF([$PYTHON -c "$np_check_cmd" &> /dev/null],
@@ -1349,9 +1353,12 @@ AS_IF([test x$enable_guide_message = xyes],
         AS_IF([test "x$has_numpy" = "xno"],
               [dependency_notice=yes
                AS_ECHO(["  - Numpy (https://numpy.org) headers couldn't be 
found within a "])
-               AS_ECHO(["    Python3 environment. If available, Gnuastro's 
library will be "])
+               AS_ECHO(["    Python3 installation. If available, Gnuastro's 
library will be "])
                AS_ECHO(["    installed with some functions that can help 
Python wrappers "])
                AS_ECHO(["    communicate with Gnuastro's library (for example 
pyGnuastro)."])
+               AS_ECHO(["    If you are within a virtual environment, and 
Python3 is"])
+               AS_ECHO(["    available there, please set the 'PYTHON' 
environment variable"])
+               AS_ECHO(["    to the Python3 executable's absolute location."])
                AS_ECHO([]) ])
 
         AS_IF([test "x$has_ds9" = "xno"],
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 25e5ede1..6af9f188 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -7802,6 +7802,31 @@ Just be sure to have it when you run @command{astquery}, 
otherwise you'll get an
 GPL Ghostscript's executable (@command{gs}) is called by ConvertType to 
compile a PDF file from a source PostScript file, see @ref{ConvertType}.
 Therefore its headers (and libraries) are not needed.
 
+@item Python3 with Numpy
+@cindex Numpy
+@cindex Python3
+Python is a high-level programming language and Numpy is the most commonly 
used library within Python to add multi-dimensional arrays and matrices.
+If version 3 of Python is available with a corresponding Numpy Library, 
Gnuastro's library will be built with some Python-related helper functions.
+Python wrappers for Gnuastro's library (for example `pyGnuastro') can use 
these functions when being built from source.
+For more on Gnuastro's Python helper functions, see @ref{Python interface}.
+
+@cindex PyPI
+This Python interface is only relevant if you want to build the Python 
wrappers (like `pyGnuastro') from source.
+If you install the Gnuastro Python wrapper from a pre-built repository like 
PyPI, this feature of your Gnuastro library won't be used.
+Pre-built libraries contain the full Gnuastro library that they need within 
them (you don't even need to have Gnuastro at all!).
+
+@cartouche
+@noindent
+@strong{Can't find the Python3 and Numpy of a virtual environment:} make sure 
to set the @code{$PYTHON} variable to point to the @code{python3} command of 
the virtual environment before running @code{./configure}.
+Note that you don't need to activate the virtual env, just point @code{PYTHON} 
to its Python3 executable, like the example below:
+
+@example
+$ python3 -m venv test-env    # Setting up the virtual env.
+$ export PYTHON="$(pwd)/test-env/bin/python3"
+$ ./configure                 # Gnuastro's configure script.
+@end example
+@end cartouche
+
 @item SAO DS9
 SAO DS9 (@command{ds9}) is a visualization tool for FITS images.
 Gnuastro's @command{astscript-fits-view} program calls DS9 to visualize FITS 
images.
@@ -8693,6 +8718,15 @@ libjpeg is an optional dependency, with this option, 
Gnuastro will ignore any po
 Build Gnuastro without libtiff (for reading/writing to TIFF files), see 
@ref{Optional dependencies}.
 libtiff is an optional dependency, with this option, Gnuastro will ignore any 
possibly existing libtiff that may already be on the system.
 
+@item --without-python
+@cindex PyPI
+@cindex Python
+Don't build the Python interface within Gnuastro's dynamic library.
+This interface can be used for easy communication with Python wrappers (for 
example the pyGnuastro package).
+However upon installing the pyGnuastro package from PyPI, the correct 
configuration of the Gnuastro Library(with the python interface) is already 
packaged with it.
+The Python interface is only necessary if you want to build pyGnuastro from 
source.
+For more on the interface functions, see @ref{Python interface}.
+
 @end vtable
 
 The tests of some programs might depend on the outputs of the tests of other 
programs.
@@ -35907,10 +35941,15 @@ To see why Gnuastro was written in C, please see 
@ref{Why C}.
 The Gnuastro Python Package is built using CPython.
 This entails using Python wrappers around currently existing Gnuastro library 
functions to build @url{https://docs.python.org/3/extending/extending.html#, 
Python Extension Modules}.
 It also makes use of the 
@url{https://numpy.org/doc/stable/reference/c-api/index.html, NumPy C-API} for 
dealing with data arrays.
-Writing an interfacing between these and Gnuastro can be simplified using the 
functions below.
+Writing an interface between these and Gnuastro can be simplified using the 
functions below.
 Since many of these functions depend on the Gnuastro Library itself, it is 
more convenient to package them with the Library to facilitate the work of 
Python package.
 These functions will be expanding as Gnuastro's own Python module (pyGnuastro) 
grows.
 
+The Python interface of Gnuastro's library is built and installed by default 
if a Python 3.0.0 or greater with NumPy is found in @code{$PATH}.
+Users may disable this interface with the @option{--without-python} option to 
@code{./configure} when they installed Gnuastro, see @ref{Gnuastro configure 
options}.
+If you have problems in a Pythin virtual env, see @ref{Optional dependencies}.
+
+
 @deftypefun int gal_python_type_to_numpy (uint8_t @code{type})
 Returns the NumPy datatype corresponding to a certain Gnuastro @code{type}, 
see @ref{Library data types}.
 @end deftypefun