모듈 객체¶

PyTypeObject PyModule_Type¶: 상의 안정 ABI.
이 PyTypeObject 인스턴스는 Python 모듈 형을 나타냅니다. 이것은 Python 프로그램에서 :py:class:`types.ModuleType`으로 노출됩니다.

int PyModule_Check(PyObject *p)¶: p가 모듈 객체이거나 모듈 객체의 서브 형이면 참을 반환합니다. 이 함수는 항상 성공합니다.

int PyModule_CheckExact(PyObject *p)¶: p가 모듈 객체이지만, PyModule_Type의 서브 형이 아니면 참을 반환합니다. 이 함수는 항상 성공합니다.

PyObject *PyModule_NewObject(PyObject *name)¶

반환값: 새 참조. 상의 안정 ABI 버전 3.7 이후로.

module.__name__이 name으로 설정된 새 모듈 객체를 반환합니다. 모듈의 __name__, __doc__, __package__ 및 __loader__ 어트리뷰트가 채워집니다 (__name__을 제외하고 모두 None으로 설정됩니다). __file__ 어트리뷰트를 설정하는 것은 호출자의 책임입니다.

오류 발생 시, 예외를 설정하고 NULL 을 반환합니다.

Added in version 3.3.

버전 3.4에서 변경: __package__와 __loader__가 이제 None으로 설정됩니다.

PyObject *PyModule_New(const char *name)¶: 반환값: 새 참조. 상의 안정 ABI.
PyModule_NewObject()와 비슷하지만, name이 유니코드 객체 대신 UTF-8로 인코딩된 문자열입니다.

PyObject *PyModule_GetDict(PyObject *module)¶

반환값: 빌린 참조. 상의 안정 ABI.

module의 이름 공간을 구현하는 딕셔너리 객체를 반환합니다; 이 객체는 모듈 객체의 __dict__ 어트리뷰트와 같습니다. module이 모듈 객체(또는 모듈 객체의 서브 형)가 아니면, SystemError가 발생하고 NULL이 반환됩니다.

확장은 모듈의 __dict__를 직접 조작하지 말고 다른 PyModule_*과 PyObject_* 함수를 사용하는 것이 좋습니다.

반환된 참조는 모듈에서 빌려 온 것이므로, 모듈이 파괴될 때까지 유효합니다.

PyObject *PyModule_GetNameObject(PyObject *module)¶: 반환값: 새 참조. 상의 안정 ABI 버전 3.7 이후로.
module의 __name__ 값을 반환합니다. 모듈이 제공하지 않거나, 문자열이 아니면, SystemError가 발생하고 NULL이 반환됩니다.

Added in version 3.3.

const char *PyModule_GetName(PyObject *module)¶

상의 안정 ABI.

PyModule_GetNameObject()와 비슷하지만 'utf-8'로 인코딩된 이름을 반환합니다.

반환되는 버퍼는 모듈 이름이 변경되거나 파괴될 때까지만 유효합니다. Python 코드는 __name__ 속성을 설정하여 모듈의 이름을 변경할 수 있다는 점에 유의하십시오.

PyModuleDef *PyModule_GetDef(PyObject *module)¶

상의 안정 ABI.

모듈이 만들어진 PyModuleDef 구조체에 대한 포인터나 모듈이 정의에서 만들어지지 않았으면 NULL을 반환합니다.

오류 발생 시 예외와 함께 NULL 을 반환합니다. 이 경우 PyErr_Occurred() 를 사용하여 누락된 PyModuleDef 와 구별하십시오.

PyObject *PyModule_GetFilenameObject(PyObject *module)¶: 반환값: 새 참조. 상의 안정 ABI.
module의 __file__ 어트리뷰트를 사용하여 module이 로드된 파일 이름을 반환합니다. 정의되지 않았거나 문자열이 아니면, SystemError를 발생시키고 NULL을 반환합니다; 그렇지 않으면 유니코드 객체에 대한 참조를 반환합니다.

Added in version 3.2.

const char *PyModule_GetFilename(PyObject *module)¶

상의 안정 ABI.

PyModule_GetFilenameObject()와 비슷하지만 ‘utf-8’로 인코딩된 파일명을 반환합니다.

반환된 버퍼는 모듈의 __file__ 속성이 재할당되거나 모듈이 파괴될 때까지만 유효합니다.

버전 3.2부터 폐지됨: PyModule_GetFilename()은 인코딩할 수 없는 파일명에 대해 UnicodeEncodeError를 발생시킵니다, 대신 PyModule_GetFilenameObject()를 사용하십시오.

모듈 정의¶

C API를 사용하여 생성된 모듈은 일반적으로 모듈이 어떻게 생성되어야 하는지에 대한 “설명”을 제공하는 PySlot 구조체의 배열을 사용하여 정의됩니다. 슬롯에 대한 자세한 정보는 :ref:`capi-slots`를 참조하십시오.

버전 3.15에서 변경: 이전에 모듈을 정의하려면 PyModuleDef 구조가 필요했습니다. 모듈을 정의하는 이전 방식은 여전히 사용 가능하며, 이전 Python 버전을 지원하려는 경우 모듈 정의 구조체 섹션 또는 이 문서의 초기 버전을 참조하십시오.

슬롯 배열은 일반적으로 확장 모듈의 “메인” 모듈 객체(자세한 내용은 확장 모듈 정의 참조)를 정의하는 데 사용됩니다. 또한 :ref:`확장 모듈을 동적으로 생성 <module-from-slots>`하는 데 사용할 수 있습니다.

별도로 지정하지 않는 한, 슬롯 배열 내에서 동일한 슬롯 ID를 반복할 수 없습니다.

메타데이터 슬롯¶

Py_mod_name¶

상의 안정 ABI 버전 3.15 이후로.

새 모듈 이름에 대한 Slot ID 는 NUL-terminated UTF8-encoded const char * 입니다.

모듈은 일반적으로 ModuleSpec`을 사용하여 생성되며, 그 경우 spec의 이름이 :c:data:!Py_mod_name` 대신 사용됩니다. 그러나 직성 검사 및 디버깅 목적으로 이 슬롯에 포함하는 것이 여전히 권장됩니다.

Added in version 3.15: 이전 버전을 지원하려면 대신 :c:member:`PyModuleDef.m_name`을 사용하십시오.

Py_mod_doc¶

상의 안정 ABI 버전 3.15 이후로.

새 모듈의 독스트링에 대한 Slot ID 는 NUL로 종료된 UTF8 인코딩된 const char * 입니다.

일반적으로 PyDoc_STRVAR\로 생성된 변수에 설정됩니다.

Added in version 3.15: 이전 버전을 지원하려면 대신 :c:member:`PyModuleDef.m_doc`을 사용하십시오.

기능 슬롯¶

Py_mod_abi¶

상의 안정 ABI 버전 3.15 이후로.

확장 기능이 사용하는 ABI를 설명하는 PyABIInfo 구조체를 가리키는 값인 :c:member:`Slot ID <PySlot.sl_id>`입니다.

적절한 PyABIInfo 변수는 다음과 같이 PyABIInfo_VAR 매크로를 사용하여 정의할 수 있습니다:

PyABIInfo_VAR(abi_info);

static PySlot mymodule_slots[] = {
   PySlot_DATA(Py_mod_abi, &abi_info),
   ...
};

모듈을 생성할 때, Python은 :c:func:`PyABIInfo_Check`를 사용하여 이 슬롯의 값을 확인합니다.

이 슬롯은 :c:struct:`PyModuleDef`에서 생성된 모듈을 제외하고는 필수입니다.

Added in version 3.15.

Py_mod_multiple_interpreters¶

상의 안정 ABI 버전 3.12 이후로.

값 중 하나가 다음인 Slot ID:

Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED¶: 해당 모듈은 서브 인터프리터에서 가져와지는 것을 지원하지 않습니다.

Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED¶: 이 모듈은 서브 인터프리터에서 가져오는 것을 지원하지만, 메인 인터프리터의 GIL을 공유할 때만 가능합니다. (참조: 확장 모듈 격리하기.)

Py_MOD_PER_INTERPRETER_GIL_SUPPORTED¶: 이 모듈은 게다가 자체 GIL을 가진 서브 인터프리터에서도 임포트될 수 있습니다. ( 확장 모듈 격리하기 참조.)

이 슬롯은 서브 인터프리터에서 이 모듈을 임포트하는 것이 실패할지 여부를 결정합니다.

Py_mod_multiple_interpreters 가 지정되지 않은 경우, 임포트 장치는 Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED 로 기본 설정됩니다.

For historical reasons, the values are declared as pointers (void *). When using PySlot arrays, use PySlot_DATA for Py_mod_multiple_interpreters:

PySlot_DATA(Py_mod_multiple_interpreters,
            Py_MOD_PER_INTERPRETER_GIL_SUPPORTED)

Added in version 3.12.

Py_mod_gil¶

상의 안정 ABI 버전 3.13 이후로.

값 중 하나가 다음인 Slot ID:

Py_MOD_GIL_USED¶: The module depends on the presence of the global interpreter lock (GIL), and may access global state without synchronization.

Py_MOD_GIL_NOT_USED¶: 이 모듈은 활성 GIL 없이는 실행해도 안전합니다.

이 슬롯은 :option:`–disable-gil`로 구성되지 않은 파이썬 빌드에서는 무시됩니다. 그렇지 않으면, 이 모듈을 임포트하는 것이 GIL을 자동으로 활성화할지 여부를 결정합니다. 자세한 내용은 :ref:`whatsnew313-free-threaded-cpython`을 참조하십시오.

Py_mod_gil 이 지정되지 않은 경우, 임포트 장치는 Py_MOD_GIL_USED 로 기본 설정됩니다.

For historical reasons, the values are declared as pointers (void *). When using PySlot arrays, use PySlot_DATA for Py_mod_gil:

PySlot_DATA(Py_mod_gil, Py_MOD_GIL_NOT_USED)

Added in version 3.13.

생성 및 초기화 슬롯¶

Py_mod_create¶

상의 안정 ABI 버전 3.5 이후로.

:c:member:`Slot ID <PySlot.sl_id>`는 모듈 객체 자체를 생성하는 함수입니다. 이 함수는 다음과 같은 시그니처를 가져야 합니다:

PyObject *create_module(PyObject *spec, PyModuleDef *def)¶

함수에는 다음이 전달됩니다:

spec: a ModuleSpec-like object, meaning that any attributes defined for importlib.machinery.ModuleSpec have matching semantics. However, any of the attributes may be missing.
def: NULL 이거나 모듈로부터 생성된 경우 해당 모듈 정의입니다.

이 함수는 새 모듈 객체를 반환하거나 오류를 설정하고 NULL 을 반환해야 합니다.

이 함수는 최소한으로 유지해야 합니다. 특히 같은 모듈을 다시 임포트 하려고 시도하면 무한 루프가 발생할 수 있어서, 임의의 파이썬 코드를 호출하면 안 됩니다.

Py_mod_create를 지정하지 않으면, 임포트 절차는 PyModule_New()를 사용하여 일반 모듈 객체를 만듭니다. 이름은 정의가 아니라 spec에서 취합니다, 확장 모듈이 단일 모듈 정의를 공유하면서 모듈 계층 구조에서 해당 위치에 동적으로 조정되고 심볼릭 링크를 통해 다른 이름으로 임포트 될 수 있도록 하기 위함입니다.

반환되는 객체가 PyModule_Type 인스턴스여야 할 필요는 없습니다. 하지만 일부 슬롯은 PyModule_Type 인스턴스와 함께 사용될 수 있으며, 특히 다음과 같은 경우가 있습니다:

Py_mod_exec,
모듈 상태 슬롯 (Py_mod_state_*),
Py_mod_token.

Added in version 3.5.

버전 3.15에서 변경: slots 인수는 실제 ModuleSpec 인스턴스가 아니라 ModuleSpec 와 유사한 객체일 수 있습니다. 이전 버전의 CPython에서는 이를 강제하지 않았음에 유의하십시오.

모듈은 반드시 정의(definition)에서 만들어지는 것이 아니기 때문에, def 인수는 NULL 일 수 있습니다.

Py_mod_exec¶

상의 안정 ABI 버전 3.5 이후로.

Slot ID 는 모듈을 :dfn:`실행`하거나 초기화할 함수를 위한 것입니다. 이 함수는 파이썬 모듈의 코드를 실행하는 것과 동등한 작업을 수행합니다. 일반적으로 클래스와 상수들을 모듈에 추가합니다. 함수의 서명은 다음과 같습니다:

int exec_module(PyObject *module)¶

사용 가능한 일부 유용한 함수들을 호출하려면 지원 함수 섹션을 참조하십시오.

하위 호환성을 위해, PyModuleDef.m_slots 배열에는 여러 개의 Py_mod_exec 슬롯이 포함될 수 있습니다. 이러한 슬롯은 배열에 나타나는 순서대로 처리됩니다. 다른 곳에서는 (즉, :c:func:`PyModule_FromSlotsAndSpec`의 인수나 :samp:`PyModExport_{<name>}`의 반환 값에서는) 슬롯을 반복하는 것이 허용되지 않습니다.

Added in version 3.5.

버전 3.15에서 변경: 반복된 Py_mod_exec 슬롯은, :c:type:`PyModuleDef.m_slots`를 제외하고는 허용되지 않습니다.

Py_mod_methods¶

상의 안정 ABI 버전 3.15 이후로.

Slot ID 는 모듈 레벨 함수들의 테이블을 위한 것입니다. 이는 PyModule_AddFunctions() 의 functions 인수(argument)로 적합한 PyMethodDef 값의 배열입니다.

다른 슬롯 ID와 마찬가지로, 슬롯 배열에는 하나의 Py_mod_methods 항목만 포함될 수 있습니다. 여러 개의 PyMethodDef 배열에서 함수를 추가하려면, Py_mod_exec 함수 내에서 :c:func:`PyModule_AddFunctions`를 호출하십시오.

테이블은 정적으로 할당되어야 합니다 (또는 모듈 객체보다 수명이 길 것이 보장되어야 합니다).

Added in version 3.15: 이전 버전을 지원하려면 대신 :c:member:`PyModuleDef.m_methods`를 사용하십시오.

모듈 상태¶

확장 모듈은 모듈 상태 (module state)를 가질 수 있습니다. 이는 모듈 생성 시 할당되고, 모듈 객체가 해제될 때 해제되는 메모리 조각입니다. 모듈 상태는 전용 슬롯 을 사용하여 지정합니다.

모듈 상태의 일반적인 사용 사례는 예외 유형(exception type)을 저장하는 것입니다. 나아가 모듈에 의해 정의된 모든 타입 객체도 가능합니다.

모듈의 파이썬 속성(Python attributes)과 달리, 파이썬 코드는 모듈 상태에 저장된 데이터를 대체하거나 삭제할 수 없습니다.

정적 전역 변수가 아닌, 속성과 모듈 상태에 모듈별 정보를 유지하면, 모듈 객체가 격리 되고 여러 서브 인터프리터에서 사용하기 더 안전해집니다. 또한 파이썬이 종료될 때 체계적인 정리 작업을 하는 데 도움을 줍니다.

모듈 상태의 일부로 파이썬 객체에 대한 참조를 유지하는 확장은, 참조 누수를 방지하기 위해 Py_mod_state_traverse 및 Py_mod_state_clear 함수를 구현해야 합니다.

특정 모듈에서 상태(state)를 검색하려면 다음 함수들을 사용하십시오:

void *PyModule_GetState(PyObject *module)¶

상의 안정 ABI.

모듈의 “상태”, 즉 모듈 생성 시 할당된 메모리 블록을 가리키는 포인터나 NULL 을 반환합니다. Py_mod_state_size 를 참조하십시오.

오류 발생 시, 예외를 설정하고 NULL 을 반환합니다. 이 경우와 누락된 모듈 상태를 구분하려면 PyErr_Occurred() 를 사용하십시오.

int PyModule_GetStateSize(PyObject *module, Py_ssize_t *result)¶

상의 안정 ABI 버전 3.15 이후로.

*result 에 module’의 상태 크기, 즉 Py_mod_state_size (또는 PyModuleDef.m_size)를 사용하여 지정한 크기를 설정하고 0을 반환합니다.

오류 발생 시, *result 에 -1을 설정하고 예외와 함께 -1을 반환합니다.

Added in version 3.15.

모듈 상태 정의를 위한 슬롯(Slots)¶

다음 슬롯 ID 는 모듈 상태를 정의하는 데 사용할 수 있습니다.

Py_mod_state_size¶

상의 안정 ABI 버전 3.15 이후로.

모듈 상태 크기(bytes)에 대한 슬롯 ID.

값을 음수(non-negative)가 아닌 값으로 설정하는 것은 모듈이 다시 초기화될 수 있음을 의미하며, 그 상태에 필요한 추가 메모리 양을 지정합니다.

자세한 내용은 PEP 3121을 참조하십시오.

특정 모듈의 크기를 검색하려면 PyModule_GetStateSize() 를 사용하십시오.

Added in version 3.15: 이전 버전을 지원하려면 대신 :c:member:`PyModuleDef.m_size`를 사용하십시오.

Py_mod_state_traverse¶

상의 안정 ABI 버전 3.15 이후로.

모듈 객체의 GC 순회(traversal) 중 호출할 트래버설 함수에 대한 슬롯 ID 입니다.

함수의 서명 및 인수의 의미는 PyTypeObject.tp_traverse 와 유사합니다:

int traverse_module_state(PyObject *module, visitproc visit, void *arg)¶

모듈 상태가 요청되었지만 아직 할당되지 않은 경우 이 함수는 호출되지 않습니다. 이는 모듈이 생성된 직후부터 모듈이 실행되기 전까지의 경우입니다 (Py_mod_exec 함수). 더 구체적으로 말하면, 상태 크기 (Py_mod_state_size)가 0보다 크고, 모듈 상태( PyModule_GetState() \가 반환하는)가 NULL 일 때 이 함수는 호출되지 않습니다.

Added in version 3.15: 이전 버전을 지원하려면 대신 :c:member:`PyModuleDef.m_size`를 사용하십시오.

Py_mod_state_clear¶

상의 안정 ABI 버전 3.15 이후로.

객체에 대한 가비지 컬렉션(GC) 해제 시 호출할 명확한 함수를 위한 :c:member:`Slot ID <PySlot.sl_id>`입니다.

함수의 서명은 다음과 같습니다:

int clear_module_state(PyObject *module)¶

‘PyTypeObject.tp_clear 와 같이, 이 함수는 모듈이 해제되기 전에 항상 호출되는 것은 아닙니다. 예를 들어, 참조 횟수 계산만으로 객체가 더 이상 사용되지 않음을 판단할 수 있는 경우, 순환 가비지 컬렉터가 관여하지 않고 Py_mod_state_free 함수가 직접 호출됩니다.

Added in version 3.15: 이전 버전을 지원하려면 대신 :c:member:`PyModuleDef.m_clear`를 사용하십시오.

Py_mod_state_free¶

상의 안정 ABI 버전 3.15 이후로.

모듈 객체가 해제될 때 호출할 함수를 위한 :c:member:`Slot ID <PySlot.sl_id>`입니다.

함수의 서명은 다음과 같습니다:

int free_module_state(PyObject *module)¶

Added in version 3.15: 이전 버전을 지원하려면 대신 :c:member:`PyModuleDef.m_free`를 사용하십시오.

모듈 토큰¶

각 모듈은 관련 토큰 을 가질 수 있습니다: 이는 모듈 상태의 메모리 레이아웃을 식별하기 위해 사용되는 포인터 크기 값입니다. 즉, 모듈 객체를 가지고 있지만 그것이 확장 모듈에 “속하는”지 확실하지 않은 경우 다음과 같은 코드를 사용하여 확인할 수 있습니다:

PyObject *module = <관련 모듈>

void *module_token;
if (PyModule_GetToken(module, &module_token) < 0) {
    return NULL;
}
if (module_token != your_token) {
    PyErr_SetString(PyExc_ValueError, "unexpected module")
    return NULL;
}

// 이 모듈의 상태는 예상되는 메모리 레이아웃을 가지고 있으므로 캐스팅하는 것이 안전합니다.
struct my_state state = (struct my_state*)PyModule_GetState(module)

모듈의 토큰 – 그리고 위 코드에서 사용할 your_token 값은 다음과 같습니다:

:c:type:`PyModuleDef`로 생성된 모듈의 경우: 해당 :c:type:`PyModuleDef`의 주소입니다.
Py_mod_token 슬롯으로 정의된 모듈의 경우: 해당 슬롯 값입니다.
PyModExport_* export hook <extension-export-hook>`에서 생성된 모듈의 경우: 내보내기 훅이 반환한 슬롯 배열( :c:macro:`Py_mod_token\로 재정의되지 않은 경우)입니다.

Py_mod_token¶

상의 안정 ABI 버전 3.15 이후로.

모듈 토큰을 위한 :c:member:`Slot ID <PySlot.sl_id>`입니다.

이 슬롯을 사용하여 모듈 토큰을 설정하는 경우(기본값에 의존하는 것이 아니라), 다음 사항을 확인해야 합니다:

포인터는 클래스보다 오래 남아 있어, 클래스가 존재하는 동안 다른 용도로 재사용되지 않도록 해야 합니다.
이는 클래스가 존재하는 확장 모듈에 “속하기” 때문에 다른 확장과 충돌하지 않습니다.
토큰이 PyModuleDef 구조체를 가리키는 경우, 모듈은 마치 해당 :c:type:`PyModuleDef`에서 생성된 것처럼 동작해야 합니다. 특히, 모듈 상태는 일치하는 레이아웃과 의미론을 가져야 합니다.

:c:type:`PyModuleDef`에서 생성된 모듈은 항상 :c:type:`PyModuleDef`의 주소를 토큰으로 사용합니다. 이는 :c:macro:!Py_mod_token`을 :c:member:`PyModuleDef.m_slots`에서 사용할 수 없음을 의미합니다.

Added in version 3.15.

int PyModule_GetToken(PyObject *module, void **result)¶

상의 안정 ABI 버전 3.15 이후로.

*result 를 module 의 모듈 토큰으로 설정하고 0을 반환합니다.

오류 발생 시, *result 를 NULL로 설정하고 예외를 설정한 후 -1을 반환합니다.

Added in version 3.15.

또한 :c:func:`PyType_GetModuleByToken`도 참조하십시오.

확장 모듈 동적 생성하기¶

다음 함수들은 확장 모듈을 확장 기능의 :ref:`export hook <extension-export-hook>`이 아닌 방식으로 동적으로 생성하는 데 사용될 수 있습니다.

PyObject *PyModule_FromSlotsAndSpec(const PySlot *slots, PyObject *spec)¶

반환값: 새 참조. 상의 안정 ABI 버전 3.15 이후로.

slots 배열과 ModuleSpec spec 을 사용하여 새로운 모듈 객체를 생성합니다.

The slots argument must point to an array of PySlot structures, terminated by an entry with slot ID of 0 (typically written as PySlot_END). The array must include a Py_mod_abi entry.

spec 인수는 Py_mod_create 문서에 설명된 모든 ModuleSpec 과 유사한 객체일 수 있습니다. 현재 spec 은 “name” 속성을 가지고 있어야 합니다.

성공하면 새 모듈을 반환합니다. 오류가 발생하면 예외를 설정하고 NULL 을 반환합니다.

참고할 점은 이 설명서가 모듈의 실행 슬롯(Py_mod_exec)을 처리하지 않는다는 것입니다. 모듈을 완전히 초기화하려면 PyModule_FromSlotsAndSpec`과 :c:func:`PyModule_Exec() 모두를 호출해야 합니다. (참고: 다단계 초기화.)

Added in version 3.15.

int PyModule_Exec(PyObject *module)¶

상의 안정 ABI 버전 3.15 이후로.

module 의 Py_mod_exec 슬롯(들)을 실행합니다.

성공하면, 0을 반환하고 오류 시에는 예외를 설정하여 -1을 반환합니다.

명확히 하자면: 만약 module 에 슬롯이 없다면(예를 들어 레거시 단단계 초기화 을 사용하는 경우), 이 함수는 아무것도 하지 않고 0을 반환합니다.

Added in version 3.15.

모듈 정의 구조체¶

전통적으로 확장 모듈은 슬롯 배열을 직접 사용하는 대신, module definition 을 어떻게 모듈이 생성되어야 하는지에 대한 “설명”으로 정의했습니다. 이 정의는 대부분 일반적인 기능에 대해 전용 멤버를 가지고 있으며 확장 메커니즘으로 추가 슬롯을 허용합니다.

이러한 방식으로 모듈을 정의하는 것은 여전히 사용할 수 있으며 제거할 계획은 없습니다.

type PyModuleDef¶

상의 안정 ABI (see below).

모듈 객체를 생성하는 데 필요한 정보를 담고 있는 모듈 정의 구조체입니다.

이 구조체는 정적으로 할당되어야 합니다 (또는 이 구조체로부터 생성되는 모든 모듈이 존재하는 동안 유효한 것으로 보장되어야 합니다). 일반적으로, 이러한 방식으로 정의된 각 확장 모듈에 대해서만 하나의 변수가 있습니다.

이 구조체는 비-자유 스레드 빌드 (abi3)의 안정 ABI <stable-abi>`의 일부입니다. 자유 스레드 빌드 (``abi3t`)의 안정 ABI에서는 이 구조체가 불투명하며 실제로 사용할 수 없습니다. 대체 방법은 :ref:`pymoduledef_slot`을 참조하십시오.

PyModuleDef_Base m_base¶

이 멤버를 항상 PyModuleDef_HEAD_INIT:로 초기화해야 합니다.

type PyModuleDef_Base¶

상의 안정 ABI (see below).

:c:member:`!PyModuleDef.m_base`의 타입입니다.

이 구조체는 비-자유 스레드 빌드 (abi3)의 안정 ABI <stable-abi>`의 일부입니다. 자유 스레드 빌드 (``abi3t`)에서 이 구조체는 불투명하며 실제 사용이 불가능합니다.

PyModuleDef_HEAD_INIT¶: :c:member:`!PyModuleDef.m_base`에 필요한 초기 값입니다.

const char *m_name¶: Py_mod_name 슬롯에 해당합니다.

const char *m_doc¶: 이 멤버들은 Py_mod_doc 슬롯에 해당합니다. 이를 NULL로 설정하는 것은 해당 슬롯을 생략하는 것과 같습니다.

Py_ssize_t m_size¶

Py_mod_state_size 슬롯에 해당합니다. 이것을 0으로 설정하는 것은 해당 슬롯을 생략하는 것과 같습니다.

레거시 단단계 초기화 를 사용하거나 PyModule_Create() 또는 PyModule_Create2() 를 사용하여 동적으로 모듈을 생성하는 경우, m_size 가 -1로 설정될 수 있습니다. 이는 해당 모듈이 전역 상태를 가지고 있기 때문에 서브 인터프리터를 지원하지 않음을 나타냅니다.

PyMethodDef *m_methods¶: Py_mod_methods 슬롯에 해당합니다. 이를 NULL로 설정하는 것은 슬롯을 생략하는 것과 같습니다.

PyModuleDef_Slot *m_slots¶

추가 슬롯의 배열이며, {0, NULL} 항목으로 끝납니다. 참고로 이 항목들은 PySlot 보다 이전 버전의 PyModuleDef_Slot 구조체를 사용합니다.

만약 배열이 PyModuleDef 멤버에 해당하는 슬롯을 포함한다면, 값들은 일치해야 합니다. 예를 들어, :c:member:`!m_slots`에서 :c:macro:`Py_mod_name`을 사용하는 경우, :c:member:`PyModuleDef.m_name`은 동일한 포인터로 설정되어야 합니다 (단순히 같은 문자열이어서는 안 됩니다).

버전 3.5에서 변경: 버전 3.5 이전에는, 이 멤버가 항상 NULL로 설정되었으며, 다음과 같이 정의되었습니다:

inquiry m_reload¶

type PyModuleDef_Slot¶

상의 안정 ABI (모든 멤버 포함) 버전 3.5 이후로.

모듈의 추가 슬롯을 정의하는 이전 구조체입니다.

PyModuleDef_Slot 배열은 Py_mod_slots 를 사용하여 PySlot 배열에 포함될 수 있으며, 그 반대도 Py_slot_subslots 를 사용하여 가능합니다.

각 PyModuleDef_Slot 구조체 modslot 은 다음의 PySlot 구조체로 해석됩니다:

(PySlot){
   .sl_id=modslot.slot,
   .sl_flags=PySlot_INTPTR | sub_static,
   .sl_ptr=modslot.value
}

여기서 sub_static 은 슬롯이 플래그를 요구하는 경우 (예: Py_mod_methods) 또는 이 플래그가 “상위” Py_mod_slots 슬롯에 존재하는 경우 PySlot_STATIC 입니다.

int slot¶: :c:member:`PySlot.sl_id`에 해당합니다.

void *value¶: :c:member:`PySlot.sl_ptr`에 해당합니다.

Added in version 3.5.

traverseproc m_traverse¶

inquiry m_clear¶

freefunc m_free¶

이 멤버들은 각각 Py_mod_state_traverse, Py_mod_state_clear, 및 Py_mod_state_free 슬롯에 해당합니다.

이러한 멤버들을 NULL로 설정하는 것은 해당 슬롯을 생략하는 것과 같습니다.

버전 3.9에서 변경: 모듈 상태가 할당되기 전에 m_traverse, m_clear 및 m_free 함수는 더 이상 호출되지 않습니다.

PyTypeObject PyModuleDef_Type¶: 상의 안정 ABI 버전 3.5 이후로.
PyModuleDef 객체의 타입입니다.

Py_mod_slots¶: 상의 안정 ABI 버전 3.15 이후로.
Slot ID 는 Py_slot_subslots 처럼 작동하지만, PyModuleDef_Slot 구조체 배열을 지정합니다.

Added in version 3.15.

다음 API를 사용하여 PyModuleDef 구조체로부터 모듈을 생성할 수 있습니다:

PyObject *PyModule_Create(PyModuleDef *def)¶: 반환값: 새 참조.
정의 def 에서 주어진 것으로 새 모듈 객체를 만듭니다. 이 매크로는 module_api_version 을 PYTHON_API_VERSION 으로 설정하여 PyModule_Create2() 를 호출하거나, limited API 을 사용하는 경우 module_api_version 에 PYTHON_ABI_VERSION 을 설정하는 것이 기본입니다.

PyObject *PyModule_Create2(PyModuleDef *def, int module_api_version)¶

반환값: 새 참조. 상의 안정 ABI.

def의 정의에 따라, API 버전 module_api_version을 가정하여 새 모듈 객체를 만듭니다. 해당 버전이 실행 중인 인터프리터 버전과 일치하지 않으면, RuntimeWarning을 발생시킵니다.

오류 발생 시, 예외를 설정하고 NULL 을 반환합니다.

이 함수는 슬롯을 지원하지 않습니다. def 의 m_slots 멤버는 NULL 이어야 합니다.

참고

이 함수는 대부분 PyModule_Create()를 대신 사용해야 합니다; 확실히 필요할 때만 사용하십시오.

PyObject *PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)¶: 반환값: 새 참조.
이 매크로는 module_api_version 을 PYTHON_API_VERSION 으로 설정하여 PyModule_FromDefAndSpec2() 를 호출하거나, limited API 을 사용하는 경우 PYTHON_ABI_VERSION 으로 설정합니다.

Added in version 3.5.

버전 3.16.0a0 (unreleased)부터 약하게 폐지 <Soft deprecated>: 새 코드에서는 :c:func:`PyModule_FromSlotsAndSpec`를 선호하십시오.

PyObject *PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)¶

반환값: 새 참조. 상의 안정 ABI 버전 3.7 이후로.

API 버전 module_api_version을 가정하여, 주어진 def의 정의와 ModuleSpec spec으로 새 모듈 객체를 만듭니다. 해당 버전이 실행 중인 인터프리터 버전과 일치하지 않으면, RuntimeWarning을 발생시킵니다.

오류 발생 시, 예외를 설정하고 NULL 을 반환합니다.

이것은 실행 슬롯(Py_mod_exec)을 처리하지 않음에 유의하십시오. 모듈을 완전히 초기화하려면 PyModule_FromDefAndSpec 와 PyModule_ExecDef 를 모두 호출해야 합니다.

참고

이 함수는 대부분 PyModule_FromDefAndSpec()을 대신 사용해야 합니다; 확실히 필요할 때만 사용하십시오.

Added in version 3.5.

버전 3.16.0a0 (unreleased)부터 약하게 폐지 <Soft deprecated>: 새 코드에서는 :c:func:`PyModule_FromSlotsAndSpec`를 선호하십시오.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)¶: 상의 안정 ABI 버전 3.7 이후로.
def에 지정된 모든 실행 슬롯(Py_mod_exec)을 처리합니다.

Added in version 3.5.

버전 3.16.0a0 (unreleased)부터 약하게 폐지 <Soft deprecated>: 모듈 자체 실행 슬롯을 실행하려면 PyModuleDef 구조체로부터 생성된 모듈이 아닌 모듈에 대해 작동하는 :c:func:`PyModule_Exec`를 선호하십시오.

PYTHON_API_VERSION¶

PYTHON_API_STRING¶

정수형인 C API 버전(1013)과 문자열 형식(“1013”)입니다. 하위 호환성을 위해 정의되었습니다.

현재 이 상수는 새 파이썬 버전에서 업데이트되지 않으며, 버전 관리에 유용하지 않습니다. 향후 변경될 수 있습니다.

PYTHON_ABI_VERSION¶

PYTHON_ABI_STRING¶

하위 호환성을 위해 각각 3 과 “3”으로 정의되었습니다.

현재 이 상수는 새 파이썬 버전에서 업데이트되지 않으며, 버전 관리에 유용하지 않습니다. 향후 변경될 수 있습니다.

지원 함수¶

다음 함수들은 모듈 객체 초기화를 돕기 위해 제공됩니다. 하나는 모듈의 실행 슬롯(Py_mod_exec)용이고, 다른 하나는 레거시 :ref:`single-phase initialization <single-phase-initialization>`을 위한 초기화 함수이며, 나머지 하나는 동적으로 모듈을 생성하는 코드용입니다.

int PyModule_AddObjectRef(PyObject *module, const char *name, PyObject *value)¶

상의 안정 ABI 버전 3.10 이후로.

module에 객체를 name으로 추가합니다. 모듈의 초기화 함수에서 사용할 수 있는 편의 함수입니다.

성공하면, 0을 반환합니다. 에러 시, 예외를 발생시키고 -1을 반환합니다.

사용 예:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    if (obj == NULL) {
        return -1;
    }
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_DECREF(obj);
    return res;
 }

편의를 위해 이 함수는 예외가 설정된 NULL value 를 받습니다. 이 경우, -1 을 반환하고 발생한 예외는 변경하지 않은 채로 남겨둡니다.

예제는 obj 가 명시적으로 NULL 인지 확인하지 않고도 작성할 수 있습니다:

static int
add_spam(PyObject *module, int value)
{
    PyObject *obj = PyLong_FromLong(value);
    int res = PyModule_AddObjectRef(module, "spam", obj);
    Py_XDECREF(obj);
    return res;
 }

이 경우, obj 는 NULL 일 수 있으므로 Py_DECREF() 대신 Py_XDECREF() 를 사용해야 합니다.

이 함수에 전달되는 다양한 name 문자열의 개수는 적게 유지해야 하며, 일반적으로 name 으로 정적으로 할당된 문자열만 사용하는 것이 좋습니다. 컴파일 시간에 알 수 없는 이름의 경우, PyUnicode_FromString() 과 PyObject_SetAttr() 를 직접 호출하는 것을 선호하십시오. 더 자세한 내용은 키 객체를 생성하는 데 내부적으로 사용될 수 있는 PyUnicode_InternFromString() 을 참조하십시오.

Added in version 3.10.

int PyModule_Add(PyObject *module, const char *name, PyObject *value)¶

상의 안정 ABI 버전 3.13 이후로.

PyModule_AddObjectRef() 와 유사하지만 value 에 대한 참조를 “훔칩니다”. 그 결과를 확인하거나 변수에 저장할 필요 없이 호출할 수 있습니다.

사용 예:

if (PyModule_Add(module, "spam", PyBytes_FromString(value)) < 0) {
    goto error;
}

Added in version 3.13.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)¶

상의 안정 ABI.

PyModule_AddObjectRef() 와 유사하지만 성공 시 value 에 대한 참조를 훔칩니다 (0 을 반환하는 경우).

PyModule_AddObject() 함수를 오용하여 참조 누수가 발생하기 쉬우므로, 새로운 PyModule_Add() 또는 PyModule_AddObjectRef() 함수 사용이 권장됩니다.

참고

참조를 훔치는 다른 함수와 달리, PyModule_AddObject()는 성공 시에만 value에 대한 참조를 해제합니다.

이는 반환 값을 확인해야 하며, 에러 시 호출하는 코드가 수동으로 value를 Py_XDECREF() 해야 함을 뜻합니다.

사용 예:

PyObject *obj = PyBytes_FromString(value);
if (PyModule_AddObject(module, "spam", obj) < 0) {
    // 'obj' 가 NULL 이 아니고 PyModule_AddObject() 가 실패하면,
    // 'obj' 강한 참조는 Py_XDECREF() 로 삭제해야 합니다.
    // 'obj' 가 NULL 이면, Py_XDECREF() 는 아무것도 하지 않습니다.
    Py_XDECREF(obj);
    goto error;
}
// PyModule_AddObject() 는 obj 에 대한 참조를 훔칩니다:
// 여기에서 Py_XDECREF(obj) 는 필요 없습니다.

버전 3.13부터 약하게 폐지 <Soft deprecated>.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)¶

상의 안정 ABI.

module에 정수 상수를 name으로 추가합니다. 이 편의 함수는 모듈의 초기화 함수에서 사용할 수 있습니다. 에러 시 예외를 설정하고 -1을, 성공하면 0을 반환합니다.

:c:func:`PyLong_FromLong`과 :c:func:`PyModule_AddObjectRef`를 호출하는 편의 함수입니다. 자세한 내용은 해당 문서를 참조하십시오.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)¶

상의 안정 ABI.

module에 문자열 상수를 name으로 추가합니다. 이 편의 함수는 모듈의 초기화 함수에서 사용할 수 있습니다. 문자열 value는 NULL로 끝나야 합니다. 에러 시 예외를 설정하고 -1을, 성공 시 0을 반환합니다.

:c:func:`PyUnicode_InternFromString`과 :c:func:`PyModule_AddObjectRef`를 호출하는 편의 함수입니다. 자세한 내용은 해당 문서를 참조하십시오.

PyModule_AddIntMacro(module, macro)¶: module에 int 상수를 추가합니다. 이름과 값은 macro에서 취합니다. 예를 들어 PyModule_AddIntMacro(module, AF_INET)은 AF_INET 값을 가진 int 상수 AF_INET을 module에 추가합니다. 에러 시 예외를 설정하고 -1을, 성공하면 0을 반환합니다.

PyModule_AddStringMacro(module, macro)¶: module에 문자열 상수를 추가합니다.

int PyModule_AddType(PyObject *module, PyTypeObject *type)¶: 상의 안정 ABI 버전 3.10 이후로.
module에 형 객체를 추가합니다. 내부적으로 PyType_Ready()를 호출하여 형 객체를 파이널라이즈합니다. 형 객체의 이름은 점 뒤 tp_name의 마지막 구성 요소에서 가져옵니다. 에러가 발생하면 예외를 설정하고 -1을, 성공하면 0을 반환합니다.

Added in version 3.9.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)¶

상의 안정 ABI 버전 3.7 이후로.

NULL 으로 종료된 functions 배열에서 module 로 함수들을 추가합니다. 개별 항목에 대한 자세한 내용은 PyMethodDef 문서를 참조하십시오 (공유 모듈 네임스페이스의 부족으로 인해 C로 구현된 모듈 수준 “함수”는 일반적으로 첫 번째 매개변수로 모듈을 받기 때문에, 파이썬 클래스의 인스턴스 메서드와 유사합니다).

이 함수는 PyModuleDef``로부터 모듈을 생성할 때(예: :ref:`multi-phase-initialization`, ``PyModule_Create, 또는 PyModule_FromDefAndSpec 사용 시) 자동으로 호출됩니다. 일부 모듈 작성자는 여러 개의 PyMethodDef 배열에 함수를 정의하는 것을 선호할 수 있습니다. 이 경우 직접 이 함수를 호출해야 합니다.

함수 배열은 정적으로 할당되어야 합니다 (또는 모듈 객체보다 오래 지속되는 것이 보장되어야 합니다).

Added in version 3.5.

int PyModule_SetDocString(PyObject *module, const char *docstring)¶

상의 안정 ABI 버전 3.7 이후로.

모듈 에 대한 docstring을 docstring 으로 설정합니다. 이 함수는 PyModuleDef 로부터 모듈을 생성할 때(예: 다단계 초기화 사용 시, PyModule_Create 또는 PyModule_FromDefAndSpec) 자동으로 호출됩니다.

성공 시 0 을 반환합니다. 에러 시 예외와 함께 -1 을 반환합니다.

Added in version 3.5.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)¶: 이것은 불안정 API. 경고 없이 사소 버전에서 변경될 수 있습니다.

전역 인터프리터 잠금(GIL) 없이 실행하는지 여부를 Py_mod_gil 값 중 하나를 사용하여 모듈 이 지원하는지 표시합니다. 이 함수는 레거시 단일 단계 초기화 을 사용할 때 모듈 의 초기화 함수 내에서 호출되어야 합니다. 모듈 초기화 중에 이 함수가 호출되지 않으면, 임포트 메커니즘은 해당 모듈이 GIL 없이 실행되는 것을 지원하지 않는다고 가정합니다. 이 함수는 --disable-gil 으로 구성된 Python 빌드에서만 사용할 수 있습니다. 에러 시 예외와 함께 -1 을 반환하고, 성공 시 0 을 반환합니다.

Added in version 3.13.

모듈 조회 (단단계 초기화)¶

레거시 single-phase initialization 초기화 방식은 현재 인터프리터의 컨텍스트에서 검색할 수 있는 싱글톤 모듈을 생성합니다. 이를 통해 모듈 정의에 대한 참조만으로 나중에 모듈 객체를 가져올 수 있습니다.

이 함수들은 다단계 초기화를 사용하여 만들어진 모듈에서는 작동하지 않습니다. 단일 정의에서 그러한 모듈이 여러 개 만들어질 수 있기 때문입니다.

PyObject *PyState_FindModule(PyModuleDef *def)¶: 반환값: 빌린 참조. 상의 안정 ABI.
현재 인터프리터에 대해 def에서 만들어진 모듈 객체를 반환합니다. 이 메서드를 사용하려면 먼저 모듈 객체가 PyState_AddModule()로 인터프리터 상태에 연결되어 있어야 합니다. 해당 모듈 객체를 찾을 수 없거나 인터프리터 상태에 아직 연결되지 않았으면, NULL을 반환합니다.

int PyState_AddModule(PyObject *module, PyModuleDef *def)¶

상의 안정 ABI 버전 3.3 이후로.

함수에 전달된 모듈 객체를 인터프리터 상태에 연결합니다. 이는 PyState_FindModule()을 통해 모듈 객체에 액세스 할 수 있도록 합니다.

단단계 초기화를 사용하여 만든 모듈에만 효과가 있습니다.

Python은 single-phase initialization 을 사용하는 모듈을 임포트한 후 자동으로 PyState_AddModule 를 호출하므로, 모듈 초기화 코드에서 이 함수를 호출할 필요는 없습니다 (하지만 무해합니다). 명시적인 호출이 필요한 경우는 모듈 자체의 init 코드가 나중에 PyState_FindModule 을 호출하는 경우뿐입니다. 이 함수는 주로 대체 임포트 메커니즘 구현용으로 사용됩니다(직접 호출하거나, 필요한 상태 업데이트에 대한 세부 정보는 해당 구현을 참조하여).

모듈이 동일한 def 를 사용하여 이전에 연결된 경우, 새 모듈 로 대체됩니다.

호출자는 :term:`attached thread state`를 가지고 있어야 합니다.

에러 시 예외를 설정하고 -1을, 성공 시 0을 반환합니다.

Added in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)¶

상의 안정 ABI 버전 3.3 이후로.

def에서 만들어진 모듈 객체를 인터프리터 상태에서 제거합니다. 에러 시 예외를 설정하고 -1을, 성공 시 0을 반환합니다.

호출자는 :term:`attached thread state`를 가지고 있어야 합니다.

Added in version 3.3.

모듈 객체¶

모듈 정의¶

메타데이터 슬롯¶

기능 슬롯¶

생성 및 초기화 슬롯¶

모듈 상태¶

모듈 상태 정의를 위한 슬롯(Slots)¶

모듈 토큰¶

확장 모듈 동적 생성하기¶

모듈 정의 구조체¶

지원 함수¶

모듈 조회 (단단계 초기화)¶

분실물 보관소