函式物件 (Function Objects)
***************************

這有一些特用於 Python 函式的函式。

type PyFunctionObject

   用於函式的 C 結構。

PyTypeObject PyFunction_Type

   這是個 "PyTypeObject" 的實例，且代表了 Python 函式型別，Python 程式
   設計者可透過 "types.FunctionType" 使用它。

int PyFunction_Check(PyObject *o)

   如果 *o* 是個函式物件（擁有 "PyFunction_Type" 的型別）則回傳 true。
   參數必須不為 "NULL"。此函式必能成功執行。

PyObject *PyFunction_New(PyObject *code, PyObject *globals)
    *回傳值：新的參照。*

   回傳一個與程式碼物件 *code* 相關聯的函式物件。*globals* 必須是一個
   帶有函式能夠存取的全域變數的字典。

   函式的文件字串 (docstring) 和名稱是從程式碼物件所取得，"__module__"
   是自 *globals* 所取得。引數預設值、標註 (annotation) 和閉包
   (closure) 被設為 "NULL"，"__qualname__" 被設為和程式碼物件
   "co_qualname" 欄位相同的值。

PyObject *PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
    *回傳值：新的參照。*

   和 "PyFunction_New()" 相似，但也允許函式物件 "__qualname__" 屬性的
   設定，*qualname* 應為一個 unicode 物件或是 "NULL"；如為 "NULL"，
   "__qualname__" 屬性會被設為與程式碼物件 "co_qualname" 欄位相同的值
   。

   在 3.3 版被加入.

PyObject *PyFunction_GetCode(PyObject *op)
    *回傳值：借用參照。*

   回傳與程式碼物件相關的函式物件 *op*。

PyObject *PyFunction_GetGlobals(PyObject *op)
    *回傳值：借用參照。*

   回傳與全域函式字典相關的函式物件 *op*。

PyObject *PyFunction_GetModule(PyObject *op)
    *回傳值：借用參照。*

   回傳一個函式物件 *op* 之 "__module__" 屬性的 *borrowed reference*，
   它可以是 *NULL*。

   這通常是個包含模組名稱的"字串"，但可以被 Python 程式設為任何其他物
   件。

PyObject *PyFunction_GetDefaults(PyObject *op)
    *回傳值：借用參照。*

   回傳函式物件 *op* 的引數預設值，這可以是一個含有多個引數的 tuple（
   元組）或 "NULL"。

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)

   設定函式物件 *op* 的引數預設值。*defaults* 必須是 "Py_None" 或一個
   tuple。

   引發 "SystemError" 且在失敗時回傳 "-1"。

void PyFunction_SetVectorcall(PyFunctionObject *func, vectorcallfunc vectorcall)

   為一個給定的函式物件 *func* 設定 vectorcall 欄位。

   警告：使用此 API 的擴充套件必須保留未更改（預設）vectorcall 函式的
   行為！

   在 3.12 版被加入.

PyObject *PyFunction_GetKwDefaults(PyObject *op)
    *回傳值：借用參照。*

   回傳函式物件 *op* 的僅限關鍵字引數預設值，這可以是一個含有多個引數
   的字典或 "NULL"。

int PyFunction_SetKwDefaults(PyObject *op, PyObject *defaults)

   設定函式物件 *op* 的僅限關鍵字引數預設值。*defaults* 必須是僅限關鍵
   字引數的字典或 "Py_None"。

   此函式在成功時回傳 "0"，在失敗時回傳 "-1" 且設定一個例外。

PyObject *PyFunction_GetClosure(PyObject *op)
    *回傳值：借用參照。*

   回傳與函式物件 *op* 相關聯的閉包，這可以是個 "NULL" 或是一個包含
   cell 物件的 tuple。

int PyFunction_SetClosure(PyObject *op, PyObject *closure)

   設定與函式物件 *op* 相關聯的閉包，*closure* 必須是 "Py_None" 或是一
   個包含 cell 物件的 tuple。

   引發 "SystemError" 且在失敗時回傳 "-1"。

PyObject *PyFunction_GetAnnotations(PyObject *op)
    *回傳值：借用參照。*

   回傳函式物件 *op* 的標註，這可以是一個可變動的 (mutable) 字典或
   "NULL"。

int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)

   設定函式物件 *op* 的標註，*annotations* 必須是一個字典或 "Py_None"
   。

   引發 "SystemError" 且在失敗時回傳 "-1"。

PyObject *PyFunction_GET_CODE(PyObject *op)
PyObject *PyFunction_GET_GLOBALS(PyObject *op)
PyObject *PyFunction_GET_MODULE(PyObject *op)
PyObject *PyFunction_GET_DEFAULTS(PyObject *op)
PyObject *PyFunction_GET_KW_DEFAULTS(PyObject *op)
PyObject *PyFunction_GET_CLOSURE(PyObject *op)
PyObject *PyFunction_GET_ANNOTATIONS(PyObject *op)
    *回傳值：借用參照。*

   These functions are similar to their "PyFunction_Get*"
   counterparts, but do not do type checking. Passing anything other
   than an instance of "PyFunction_Type" is undefined behavior.

int PyFunction_AddWatcher(PyFunction_WatchCallback callback)

   Register *callback* as a function watcher for the current
   interpreter. Return an ID which may be passed to
   "PyFunction_ClearWatcher()". In case of error (e.g. no more watcher
   IDs available), return "-1" and set an exception.

   在 3.12 版被加入.

int PyFunction_ClearWatcher(int watcher_id)

   Clear watcher identified by *watcher_id* previously returned from
   "PyFunction_AddWatcher()" for the current interpreter. Return "0"
   on success, or "-1" and set an exception on error (e.g.  if the
   given *watcher_id* was never registered.)

   在 3.12 版被加入.

type PyFunction_WatchEvent

      Enumeration of possible function watcher events:

      * "PyFunction_EVENT_CREATE"

      * "PyFunction_EVENT_DESTROY"

      * "PyFunction_EVENT_MODIFY_CODE"

      * "PyFunction_EVENT_MODIFY_DEFAULTS"

      * "PyFunction_EVENT_MODIFY_KWDEFAULTS"

   在 3.12 版被加入.

typedef int (*PyFunction_WatchCallback)(PyFunction_WatchEvent event, PyFunctionObject *func, PyObject *new_value)

   Type of a function watcher callback function.

   If *event* is "PyFunction_EVENT_CREATE" or
   "PyFunction_EVENT_DESTROY" then *new_value* will be "NULL".
   Otherwise, *new_value* will hold a *borrowed reference* to the new
   value that is about to be stored in *func* for the attribute that
   is being modified.

   The callback may inspect but must not modify *func*; doing so could
   have unpredictable effects, including infinite recursion.

   If *event* is "PyFunction_EVENT_CREATE", then the callback is
   invoked after *func* has been fully initialized. Otherwise, the
   callback is invoked before the modification to *func* takes place,
   so the prior state of *func* can be inspected. The runtime is
   permitted to optimize away the creation of function objects when
   possible. In such cases no event will be emitted. Although this
   creates the possibility of an observable difference of runtime
   behavior depending on optimization decisions, it does not change
   the semantics of the Python code being executed.

   If *event* is "PyFunction_EVENT_DESTROY",  Taking a reference in
   the callback to the about-to-be-destroyed function will resurrect
   it, preventing it from being freed at this time. When the
   resurrected object is destroyed later, any watcher callbacks active
   at that time will be called again.

   If the callback sets an exception, it must return "-1"; this
   exception will be printed as an unraisable exception using
   "PyErr_WriteUnraisable()". Otherwise it should return "0".

   There may already be a pending exception set on entry to the
   callback. In this case, the callback should return "0" with the
   same exception still set. This means the callback may not call any
   other API that can set an exception unless it saves and clears the
   exception state first, and restores it before returning.

   在 3.12 版被加入.
