summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCharles Harris <charlesr.harris@gmail.com>2021-09-27 19:40:58 -0600
committerGitHub <noreply@github.com>2021-09-27 19:40:58 -0600
commit02f18a88c15f98c5879bb90e5a29463f08d262ec (patch)
tree233a9ce58afddb173aa44d43a8703af1ae6a2466
parentef56449a92107a54528dca268dcac2b5268328ae (diff)
parentcc32a249b36aa4802138b94847e71acb8b9ca2d2 (diff)
downloadnumpy-02f18a88c15f98c5879bb90e5a29463f08d262ec.tar.gz
Merge pull request #19957 from HaoZeke/capif2py
DOC: Add syntax highlighting, update pronouns
-rw-r--r--doc/source/f2py/index.rst2
-rw-r--r--doc/source/user/c-info.python-as-glue.rst87
2 files changed, 44 insertions, 45 deletions
diff --git a/doc/source/f2py/index.rst b/doc/source/f2py/index.rst
index 07d26e39e..c774a0df6 100644
--- a/doc/source/f2py/index.rst
+++ b/doc/source/f2py/index.rst
@@ -1,3 +1,5 @@
+.. _f2py:
+
=====================================
F2PY user guide and reference manual
=====================================
diff --git a/doc/source/user/c-info.python-as-glue.rst b/doc/source/user/c-info.python-as-glue.rst
index 2798aa08a..6d514f146 100644
--- a/doc/source/user/c-info.python-as-glue.rst
+++ b/doc/source/user/c-info.python-as-glue.rst
@@ -1,6 +1,6 @@
-********************
+====================
Using Python as glue
-********************
+====================
| There is no conversation more boring than the one where everybody
| agrees.
@@ -124,9 +124,9 @@ Creating source for a basic extension module
Probably the easiest way to introduce f2py is to offer a simple
example. Here is one of the subroutines contained in a file named
-:file:`add.f`:
+:file:`add.f`
-.. code-block:: none
+.. code-block:: fortran
C
SUBROUTINE ZADD(A,B,C,N)
@@ -149,14 +149,14 @@ routine can be automatically generated by f2py::
You should be able to run this command assuming your search-path is
set-up properly. This command will produce an extension module named
-addmodule.c in the current directory. This extension module can now be
+:file:`addmodule.c` in the current directory. This extension module can now be
compiled and used from Python just like any other extension module.
Creating a compiled extension module
------------------------------------
-You can also get f2py to compile add.f and also compile its produced
+You can also get f2py to both compile :file:`add.f` along with the produced
extension module leaving only a shared-library extension file that can
be imported from Python::
@@ -211,7 +211,7 @@ interface file use the -h option::
This command leaves the file add.pyf in the current directory. The
section of this file corresponding to zadd is:
-.. code-block:: none
+.. code-block:: fortran
subroutine zadd(a,b,c,n) ! in :add:add.f
double complex dimension(*) :: a
@@ -224,7 +224,7 @@ By placing intent directives and checking code, the interface can be
cleaned up quite a bit until the Python module method is both easier
to use and more robust.
-.. code-block:: none
+.. code-block:: fortran
subroutine zadd(a,b,c,n) ! in :add:add.f
double complex dimension(n) :: a
@@ -277,9 +277,9 @@ Inserting directives in Fortran source
The nice interface can also be generated automatically by placing the
variable directives as special comments in the original Fortran code.
-Thus, if I modify the source code to contain:
+Thus, if the source code is modified to contain:
-.. code-block:: none
+.. code-block:: fortran
C
SUBROUTINE ZADD(A,B,C,N)
@@ -298,14 +298,14 @@ Thus, if I modify the source code to contain:
20 CONTINUE
END
-Then, I can compile the extension module using::
+Then, one can compile the extension module using::
f2py -c -m add add.f
The resulting signature for the function add.zadd is exactly the same
one that was created previously. If the original source code had
contained ``A(N)`` instead of ``A(*)`` and so forth with ``B`` and ``C``,
-then I could obtain (nearly) the same interface simply by placing the
+then nearly the same interface can be obtained by placing the
``INTENT(OUT) :: C`` comment line in the source code. The only difference
is that ``N`` would be an optional input that would default to the length
of ``A``.
@@ -320,7 +320,7 @@ precision floating-point numbers using a fixed averaging filter. The
advantage of using Fortran to index into multi-dimensional arrays
should be clear from this example.
-.. code-block:: none
+.. code-block::
SUBROUTINE DFILTER2D(A,B,M,N)
C
@@ -407,13 +407,12 @@ conversion of the .pyf file to a .c file is handled by `numpy.disutils`.
Conclusion
----------
-The interface definition file (.pyf) is how you can fine-tune the
-interface between Python and Fortran. There is decent documentation
-for f2py found in the numpy/f2py/docs directory where-ever NumPy is
-installed on your system (usually under site-packages). There is also
-more information on using f2py (including how to use it to wrap C
-codes) at https://scipy-cookbook.readthedocs.io under the "Interfacing
-With Other Languages" heading.
+The interface definition file (.pyf) is how you can fine-tune the interface
+between Python and Fortran. There is decent documentation for f2py at
+:ref:`f2py`. There is also more information on using f2py (including how to use
+it to wrap C codes) at the `"Interfacing With Other Languages" heading of the
+SciPy Cookbook.
+<https://scipy-cookbook.readthedocs.io/items/idx_interfacing_with_other_languages.html>`_
The f2py method of linking compiled code is currently the most
sophisticated and integrated approach. It allows clean separation of
@@ -422,7 +421,7 @@ distribution of the extension module. The only draw-back is that it
requires the existence of a Fortran compiler in order for a user to
install the code. However, with the existence of the free-compilers
g77, gfortran, and g95, as well as high-quality commercial compilers,
-this restriction is not particularly onerous. In my opinion, Fortran
+this restriction is not particularly onerous. In our opinion, Fortran
is still the easiest way to write fast and clear code for scientific
computing. It handles complex numbers, and multi-dimensional indexing
in the most straightforward way. Be aware, however, that some Fortran
@@ -493,7 +492,7 @@ Complex addition in Cython
Here is part of a Cython module named ``add.pyx`` which implements the
complex addition functions we previously implemented using f2py:
-.. code-block:: none
+.. code-block:: cython
cimport cython
cimport numpy as np
@@ -546,7 +545,7 @@ Image filter in Cython
The two-dimensional example we created using Fortran is just as easy to write
in Cython:
-.. code-block:: none
+.. code-block:: cython
cimport numpy as np
import numpy as np
@@ -809,7 +808,7 @@ Calling the function
The function is accessed as an attribute of or an item from the loaded
shared-library. Thus, if ``./mylib.so`` has a function named
-``cool_function1``, I could access this function either as:
+``cool_function1``, it may be accessed either as:
.. code-block:: python
@@ -859,7 +858,7 @@ kind of array from a given input.
Complete example
----------------
-In this example, I will show how the addition function and the filter
+In this example, we will demonstrate how the addition function and the filter
function implemented previously using the other approaches can be
implemented using ctypes. First, the C code which implements the
algorithms contains the functions ``zadd``, ``dadd``, ``sadd``, ``cadd``,
@@ -1073,7 +1072,7 @@ Its disadvantages include
- It is difficult to distribute an extension module made using ctypes
because of a lack of support for building shared libraries in
- distutils (but I suspect this will change in time).
+ distutils.
- You must have shared-libraries of your code (no static libraries).
@@ -1095,15 +1094,14 @@ Additional tools you may find useful
These tools have been found useful by others using Python and so are
included here. They are discussed separately because they are
either older ways to do things now handled by f2py, Cython, or ctypes
-(SWIG, PyFort) or because I don't know much about them (SIP, Boost).
-I have not added links to these
-methods because my experience is that you can find the most relevant
-link faster using Google or some other search engine, and any links
-provided here would be quickly dated. Do not assume that just because
-it is included in this list, I don't think the package deserves your
-attention. I'm including information about these packages because many
-people have found them useful and I'd like to give you as many options
-as possible for tackling the problem of easily integrating your code.
+(SWIG, PyFort) or because of a lack of reasonable documentation (SIP, Boost).
+Links to these methods are not included since the most relevant
+can be found using Google or some other search engine, and any links provided
+here would be quickly dated. Do not assume that inclusion in this list means
+that the package deserves attention. Information about these packages are
+collected here because many people have found them useful and we'd like to give
+you as many options as possible for tackling the problem of easily integrating
+your code.
SWIG
@@ -1132,12 +1130,12 @@ to the Python-specific typemaps, SWIG can be used to interface a
library with other languages such as Perl, Tcl, and Ruby.
My experience with SWIG has been generally positive in that it is
-relatively easy to use and quite powerful. I used to use it quite
+relatively easy to use and quite powerful. It has been used
often before becoming more proficient at writing C-extensions.
-However, I struggled writing custom interfaces with SWIG because it
+However, writing custom interfaces with SWIG is often troublesome because it
must be done using the concept of typemaps which are not Python
-specific and are written in a C-like syntax. Therefore, I tend to
-prefer other gluing strategies and would only attempt to use SWIG to
+specific and are written in a C-like syntax. Therefore, other gluing strategies
+are preferred and SWIG would be probably considered only to
wrap a very-large C/C++ library. Nonetheless, there are others who use
SWIG quite happily.
@@ -1170,12 +1168,11 @@ those libraries which provides a concise interface for binding C++
classes and functions to Python. The amazing part of the Boost.Python
approach is that it works entirely in pure C++ without introducing a
new syntax. Many users of C++ report that Boost.Python makes it
-possible to combine the best of both worlds in a seamless fashion. I
-have not used Boost.Python because I am not a big user of C++ and
-using Boost to wrap simple C-subroutines is usually over-kill. It's
-primary purpose is to make C++ classes available in Python. So, if you
-have a set of C++ classes that need to be integrated cleanly into
-Python, consider learning about and using Boost.Python.
+possible to combine the best of both worlds in a seamless fashion. Using Boost
+to wrap simple C-subroutines is usually over-kill. Its primary purpose is to
+make C++ classes available in Python. So, if you have a set of C++ classes that
+need to be integrated cleanly into Python, consider learning about and using
+Boost.Python.
PyFort