使用 F2PY#

本頁包含 f2py 命令的所有命令列選項參考，以及 numpy.f2py 模組的內部函數參考。

將 f2py 作為命令列工具使用#

當 f2py 作為命令列工具使用時，它有三種主要模式，透過使用 -c 和 -h 切換來區分。

1. 簽名檔產生#

若要掃描 Fortran 原始碼並產生簽名檔，請使用

f2py -h <filename.pyf> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]                \
    [ skip: <fortran functions>  : ]]...           \
  [<fortran files> ...]

注意

Fortran 原始碼檔案可能包含許多常式，而且通常不需要允許所有常式都可從 Python 使用。在這種情況下，請指定應封裝哪些常式（在 only: .. : 部分中）或 F2PY 應忽略哪些常式（在 skip: .. : 部分中）。

F2PY 沒有「每個檔案」skip 或 only 清單的概念，因此如果函數列在 only 中，則不會從任何其他檔案中取得其他函數。

如果將 <filename.pyf> 指定為 stdout，則簽名會寫入標準輸出，而不是檔案。

在其他選項（請參閱下文）中，以下選項可用於此模式

--overwrite-signature

覆寫現有的簽名檔。

2. 擴充模組建構#

若要建構擴充模組，請使用

f2py -m <modulename> <options> <fortran files>   \
  [[ only: <fortran functions>  : ]              \
    [ skip: <fortran functions>  : ]]...          \
  [<fortran files> ...]

建構的擴充模組會儲存為目前目錄中的 <modulename>module.c。

此處 <fortran files> 也可能包含簽名檔。在其他選項（請參閱下文）中，以下選項可用於此模式

--debug-capi

將偵錯掛鉤新增至擴充模組。當使用此擴充模組時，關於封裝器的各種診斷資訊會寫入標準輸出，例如變數的值、採取的步驟等。

-include'<includefile>'

將 CPP #include 陳述式新增至擴充模組原始碼。<includefile> 應以以下其中一種形式給定

"filename.ext"
<filename.ext>

include 陳述式會插入在封裝器函數之前。此功能讓您可以在 F2PY 產生的封裝器中使用任意 C 函數（在 <includefile> 中定義）。

注意

此選項已棄用。請使用 usercode 陳述式，以在簽名檔中直接指定 C 程式碼片段。

--[no-]wrap-functions

建立 Fortran 子常式封裝器給 Fortran 函數。--wrap-functions 是預設值，因為它可以確保最大的可攜性和編譯器獨立性。

--[no-]freethreading-compatible

建立一個模組，宣告它是否需要 GIL。預設值是為了向後相容性而設定的 --no-freethreading-compatible。在傳遞 --freethreading-compatible 之前，請檢查您要封裝的 fortran 程式碼是否有執行緒安全問題，因為 f2py 不會分析 fortran 程式碼的執行緒安全問題。

--include-paths "<path1>:<path2>..."

從給定的目錄搜尋 include 檔案。

注意

路徑應以正確的作業系統分隔符號 pathsep 分隔，也就是 Linux/MacOS 上的 : 和 Windows 上的 ;。在 CMake 中，這對應於使用 $<SEMICOLON>。

--help-link [<資源名稱清單>]

列出 numpy_distutils/system_info.py 找到的系統資源。例如，嘗試 f2py --help-link lapack_opt。

3. 建置模組#

若要建置擴充模組，請使用

f2py -c <options> <fortran files>       \
  [[ only: <fortran functions>  : ]     \
    [ skip: <fortran functions>  : ]]... \
  [ <fortran/c source files> ] [ <.o, .a, .so files> ]

如果 <fortran files> 包含簽名檔，則會建構擴充模組的原始碼，編譯所有 Fortran 和 C 原始碼，最後將所有物件和程式庫檔案連結到擴充模組 <modulename>.so，並將其儲存到目前目錄中。

如果 <fortran files> 不包含簽名檔，則會先掃描所有 Fortran 原始碼以取得常式簽名，然後再繼續建置擴充模組，藉此建構擴充模組。

警告

從 Python 3.12 開始，distutils 已移除。請改用環境變數或原生檔案與 meson 互動。如需更多資訊，請參閱其 FAQ。

在其他選項（請參閱下文）和先前模式描述的選項中，可以使用以下選項。

注意

版本 1.26.0 已變更：現在有兩種可以使用的獨立建置後端：distutils 和 meson。強烈建議使用者切換到 meson，因為在 Python 3.12 以上版本中，它是預設值。

常見的建置旗標

--backend <backend_type>

指定編譯過程的建置後端。支援的後端為 meson 和 distutils。如果未指定，則預設為 distutils。在 Python 3.12 或更高版本中，預設值為 meson。

--f77flags=<string>

指定 F77 編譯器旗標

--f90flags=<string>

指定 F90 編譯器旗標

--debug

使用偵錯資訊編譯

-l<libname>

連結時使用程式庫 <libname>。

-D<macro>[=<defn=1>]

將巨集 <macro> 定義為 <defn>。

-U<macro>

取消定義巨集 <macro>

-I<dir>

將目錄 <dir> 附加到搜尋 include 檔案的目錄清單。

-L<dir>

將目錄 <dir> 新增至要搜尋 -l 的目錄清單。

meson 特有的旗標為

--dep <dependency> 僅限 meson

指定模組的 meson 相依性。可以針對多個相依性多次傳遞此選項。相依性會儲存在清單中以供進一步處理。範例：--dep lapack --dep scalapack 這會將「lapack」和「scalapack」識別為相依性，並從 argv 中移除它們，留下包含 [“lapack”, “scalapack”] 的相依性清單。

較舊的 distutils 旗標為

--help-fcompiler 非 meson

列出可用的 Fortran 編譯器。

--fcompiler=<Vendor> 非 meson

依廠商指定 Fortran 編譯器類型。

--f77exec=<path> 非 meson

指定 F77 編譯器的路徑

--f90exec=<path> 非 meson

指定 F90 編譯器的路徑

--opt=<string> 非 meson

指定最佳化旗標

--arch=<string> 非 meson

指定架構特定的最佳化旗標

--noopt 非 meson

編譯時不使用最佳化旗標

--noarch 非 meson

編譯時不使用與架構相關的最佳化旗標

link-<resource> 非 meson

將擴充模組與 numpy_distutils/system_info.py 定義的 <resource> 連結。例如，若要與最佳化的 LAPACK 程式庫（MacOSX 上的 vecLib，其他地方的 ATLAS）連結，請使用 --link-lapack_opt。另請參閱 --help-link 切換。

注意

f2py -c 選項必須應用於現有的 .pyf 檔案（加上原始碼/物件/程式庫檔案），或者必須指定 -m <modulename> 選項（加上原始碼/物件/程式庫檔案）。請使用下列其中一個選項

f2py -c -m fib1 fib1.f

或

f2py -m fib1 fib1.f -h fib1.pyf
f2py -c fib1.pyf fib1.f

如需更多資訊，請參閱 建置 C 和 C++ 擴充 Python 文件以取得詳細資訊。

在建置擴充模組時，非 gcc Fortran 編譯器可能需要下列巨集的組合

-DPREPEND_FORTRAN
-DNO_APPEND_FORTRAN
-DUPPERCASE_FORTRAN

若要測試 F2PY 產生介面的效能，請使用 -DF2PY_REPORT_ATEXIT。然後，在 Python 結束時會印出各種計時的報告。此功能可能無法在所有平台上運作，目前僅支援 Linux。

若要查看 F2PY 產生的介面是否執行陣列引數的複製，請使用 -DF2PY_REPORT_ON_ARRAY_COPY=<int>。當陣列引數的大小大於 <int> 時，會將關於複製的訊息傳送到 stderr。

其他選項#

-m <modulename>

擴充模組的名稱。預設值為 untitled。

警告

如果使用簽名檔 (*.pyf)，請勿使用此選項。

版本 1.26.3 已變更：如果提供 pyf 檔案，將會忽略 -m。

--[no-]lower

在 <fortran files> 中[不]將字母改為小寫。預設情況下，使用 -h 切換時會假設為 --lower，而不使用 -h 切換時則假設為 --no-lower。

-include<header>

在 C 封裝器中寫入其他標頭，可以多次傳遞，每次產生 #include <header>。請注意，這表示以單引號且不含空格的方式傳遞，例如 '-include<stdbool.h>'

--build-dir <dirname>

所有 F2PY 產生的檔案都會在 <dirname> 中建立。預設值為 tempfile.mkdtemp()。

--f2cmap <filename>

從給定的檔案載入 Fortran 到 C 的 KIND 規格。

--quiet

安靜執行。

--verbose

以額外的詳細程度執行。

--skip-empty-wrappers

除非輸入需要，否則不要產生封裝器檔案。這是為了向後相容性而設定的旗標，以還原 1.22.4 之前的行為。

-v

印出 F2PY 版本並結束。

執行不含任何選項的 f2py，以取得可用選項的最新清單。

Python 模組 numpy.f2py#

警告

版本 2.0.0 已變更：過去有一個 f2py.compile 函數，該函數已移除，使用者可以透過 subprocess.run 手動封裝 python -m numpy.f2py，並設定環境變數以視需要與 meson 互動。

當使用 numpy.f2py 作為模組時，可以調用以下函數。

Fortran 到 Python 介面產生器。

Copyright 1999 – 2011 Pearu Peterson all rights reserved. Copyright 2011 – present NumPy Developers. Permission to use, modify, and distribute this software is given under the terms of the NumPy License.

不提供任何明示或暗示的保證。使用風險自負。

numpy.f2py.get_include()[source]#

傳回包含 fortranobject.c 和 .h 檔案的目錄。

注意

當直接從 .f 和/或 .pyf 檔案一次性使用 numpy.distutils 建置擴充功能時，不需要此函數。

使用 f2py 產生的程式碼建置的 Python 擴充模組需要使用 fortranobject.c 作為原始碼檔案，並包含 fortranobject.h 標頭。此函數可用於取得包含這兩個檔案的目錄。

傳回值:
include_pathstr

包含 fortranobject.c 和 fortranobject.h 的目錄的絕對路徑。

另請參閱

numpy.get_include

傳回 numpy include 目錄的函數

註解

版本 1.21.1 中的新功能。

除非您使用的建置系統對 f2py 有特定的支援，否則使用 .pyf 簽名檔建置 Python 擴充功能是一個兩步驟的過程。對於模組 mymod

  • 步驟 1：執行 python -m numpy.f2py mymod.pyf --quiet。這會在 mymod.pyf 旁邊產生 mymodmodule.c 和（如果需要）mymod-f2pywrappers.f 檔案。

  • 步驟 2：建置您的 Python 擴充模組。這需要下列原始碼檔案

    • mymodmodule.c

    • mymod-f2pywrappers.f（如果在步驟 1 中產生）

    • fortranobject.c

numpy.f2py.run_main(comline_list)[source]#

相當於執行

f2py <args>

其中 <args>=string.join(<list>,' ')，但在 Python 中。除非使用 -h，否則此函數會傳回一個字典，其中包含關於產生的模組及其對原始碼檔案的相依性資訊。

您無法使用此函數建置擴充模組，也就是說，不允許使用 -c。請改用 compile 命令。

範例

命令 f2py -m scalar scalar.f 可以從 Python 執行如下。

>>> import numpy.f2py
>>> r = numpy.f2py.run_main(['-m','scalar','doc/source/f2py/scalar.f'])
Reading fortran codes...
        Reading file 'doc/source/f2py/scalar.f' (format:fix,strict)
Post-processing...
        Block: scalar
                        Block: FOO
Building modules...
        Building module "scalar"...
        Wrote C/API module "scalar" to file "./scalarmodule.c"
>>> print(r)
{'scalar': {'h': ['/home/users/pearu/src_cvs/f2py/src/fortranobject.h'],
	 'csrc': ['./scalarmodule.c', 
                  '/home/users/pearu/src_cvs/f2py/src/fortranobject.c']}}

自動擴充模組產生#

如果您想要發佈您的 f2py 擴充模組，那麼您只需要包含 .pyf 檔案和 Fortran 程式碼。NumPy 中的 distutils 擴充功能可讓您完全根據此介面檔案定義擴充模組。允許發佈 add.f 模組（作為 f2py_examples 套件的一部分，使其會載入為 f2py_examples.add）的有效 setup.py 檔案為

def configuration(parent_package='', top_path=None)
    from numpy.distutils.misc_util import Configuration
    config = Configuration('f2py_examples',parent_package, top_path)
    config.add_extension('add', sources=['add.pyf','add.f'])
    return config

if __name__ == '__main__':
    from numpy.distutils.core import setup
    setup(**configuration(top_path='').todict())

使用以下命令可以輕鬆安裝新的套件

pip install .

假設您具有寫入您使用的 Python 版本的主要 site-packages 目錄的適當權限。為了使產生的套件能夠運作，您需要建立一個名為 __init__.py 的檔案（與 add.pyf 位於同一個目錄中）。請注意，擴充模組完全根據 add.pyf 和 add.f 檔案定義。.pyf 檔案到 .c 檔案的轉換由 numpy.distutils 處理。