DOC: I'm unable to replicate the examples around f2py

[nbehrnd]

Issue with current documentation:

Web address in question: https://numpy.org/doc/stable/f2py/f2py.getting-started.html#the-smart-way
Test system is an instance of Linux Debian 12/bookworm with both gcc and gfortran (version 12.2.0-14), Python3 (version 3.11.4) and numpy (version 1.24.2) -- all installed from the repositories of Linux Debian 12/bookworm, branch testing.

An ongoing thread fortran-lang.discourse.group lead me to the documentation of numpy, now the numpy mailing list to this board.

My suggestions for improvement are these two:

• The examples of Fortran numpy's reference about f2py shows are written in the old FORTAN77 fixed format style. My recommendation is to rewrite them using contemporary Fortran (free format) in mind, for example in standard of Fortran 2018. This update would affect the examples for section the quick way, the in section the smart way, and the one about the smart and quick way.
• By yesterday I wasn't able to obtain the wanted functionality. Instead, the log captured from the terminal (included in the .zip archive attached) reports errors. Perhaps the documentation is incomplete, and does not state all dependencies to fulfill. Perhaps the documentation once lead to a functional result, but with continuous development of Python, numpy, and Fortran one or multiple interfaces relevant here do not work the same way as they once did. In a subsequent report to fortran-lang, a fellow reader equally noticed difficulties to replicate your instructions. Can you please check - and if necessary, update - the documentation accordingly?

The zip archive example.zip includes both the three files used, as well as the input/output from/to the CLI in the attempt by yesterday 2023-04-13 Thu.

example.zip

Idea or request for content:

No response

[melissawm]

The relevant error here in your log (for all three runs) is

/tmp/tmp_4utdfsz/src.linux-x86_64-3.11/fib1module.c:18:10: fatal error: Python.h: No such file or directory
   18 | #include <Python.h>
      |          ^~~~~~~~~~
compilation terminated.

You might need to install Python header files from the Debian package repository (i.e. something like sudo apt-get install python3-dev). Can you try that? Thanks!

[nbehrnd]

Thank you for the suggestion, I'm just back from a successful pass.

Indeed, the addition of python3-dev (in Linux Debian 12/bookworm, this currently is 3.11.2-1+b1) plus some dependencies automatically resolved/curated by the package manager now allows to run the examples. All three sections ("the quick way", "the smart way", "the quick and smart way"; log attached in the archive) with their variants (section "the smart way") were tested, each time the output now matches the showcase. This is good.

Header files (as the synaptic package manager describes it would add to the system) is something I associate with the family of C languages. Without working knowledge in any one of them, I didn't recognize a benefit to install python3-dev earlier. Possibly many users of Python in general, and numpy in particular are in similar pair of shoes, too. Hence, an explicit note in lines of "the following examples require python3-dev and its dependencies" could be of great benefit for the community. I'm going to share my findings on the discussion board of fortran-lang. Thank you!

2023-04-16_f2py_test02.zip