☰ Menu Python

☰ Menu

모듈 객체

PyTypeObject PyModule_Type

…의 일부 안정 ABI.

이 PyTypeObject 인스턴스는 Python 모듈 타입을 나타냅니다. 이는 Python 프로그램에서 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 을 반환하십시오. 이 경우를 누락된 PyModuleDef 와 구별하려면 PyErr_Occurred() 를 사용하십시오.

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 구조체 배열을 사용하여 정의되며, 이는 모듈이 어떻게 생성되어야 하는지에 대한 “설명”을 제공합니다. 슬롯에 관한 자세한 내용은 정의 슬롯 를 참조하십시오.

버전 3.15에서 변경: 이전에는 모듈을 정의하기 위해 PyModuleDef 구조체가 필요했습니다. 이전 방식의 모듈 정의는 여전히 사용할 수 있으므로, 이전 버전의 Python을 지원할 계획이라면 모듈 정의 구조체 섹션이나 이 문서의 이전 버전을 참조하십시오.

슬롯 배열은 일반적으로 확장 모듈의 “메인” 모듈 객체를 정의하는 데 사용됩니다(자세한 내용은 확장 모듈 정의 참조). 또한 이를 사용하여 동적으로 확장 모듈 생성 도 가능합니다.

별도로 명시되지 않는 한, 슬롯 배열에서 동일한 슬롯 ID가 중복될 수 없습니다.

메타데이터 슬롯

Py_mod_name

…의 일부 안정 ABI 버전 3.15 이후로.

새 모듈의 이름에 대한 Slot ID 로, NUL 종료된 UTF8 인코딩 const char * 입니다.

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

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

Py_mod_doc

…의 일부 안정 ABI 버전 3.15 이후로.

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

보통은 PyDoc_STRVAR 로 생성된 변수로 설정됩니다.

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

기능 슬롯

Py_mod_abi

…의 일부 안정 ABI 버전 3.15 이후로.

확장 모듈이 사용하는 ABI를 설명하는 PyABIInfo 구조체를 가리키는 값의 Slot ID 입니다.

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

PyABIInfo_VAR(abi_info);

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

모듈을 생성할 때 Python은 PyABIInfo_Check() 를 사용하여 이 슬롯의 값을 확인합니다.

이 슬롯은 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_INTERPRETER_SUPPORTED 를 기본값으로 사용합니다.

역사적인 이유로 값들은 포인터(void *)로 선언됩니다. PySlot 배열을 사용할 때는 Py_mod_multiple_interpreters 에 대해 PySlot_DATA 를 사용하십시오:

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

이 모듈은 전역 인터프리터 록(GIL)의 존재에 의존하며, 동기화 없이 전역 상태에 접근할 수 있습니다.

Py_MOD_GIL_NOT_USED

이 모듈은 활성화된 GIL 없이도 실행하기 안전합니다.

이 슬롯은 --disable-gil 옵션으로 구성되지 않은 Python 빌드에서는 무시됩니다. 그 외의 경우, 이 모듈을 가져올 때 GIL이 자동으로 활성화되는지 여부를 결정합니다. 자세한 내용은 자유 스레딩의 파이썬 을 참조하십시오.

Py_mod_gil 이 명시되지 않은 경우, 임포트 메커니즘은 Py_MOD_GIL_USED 를 기본값으로 사용합니다.

역사적인 이유로 값들은 포인터(void *)로 선언됩니다. PySlot 배열을 사용할 때는 Py_mod_gil 에 대해 PySlot_DATA 를 사용하십시오:

PySlot_DATA(Py_mod_gil, Py_MOD_GIL_NOT_USED)

Added in version 3.13.

생성 및 초기화 슬롯

Py_mod_create

…의 일부 안정 ABI 버전 3.5 이후로.

모듈 객체를 직접 생성하는 함수에 대한 Slot ID 입니다. 해당 함수는 다음 시그니처를 가져야 합니다:

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

함수는 다음과 같이 호출됩니다:

• spec: ModuleSpec 와 유사한 객체로, 즉 importlib.machinery.ModuleSpec 에 정의된 모든 속성이 동일한 의미를 가짐을 의미합니다. 다만, 속성 중 일부는 누락될 수 있습니다.

• def: NULL 또는 모듈이 정의로부터 생성된 경우 해당 모듈 정의.

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

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

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

반환된 객체가 반드시 PyModule_Type 의 인스턴스일 필요는 없습니다. 하지만 일부 슬롯은 PyModule_Type 인스턴스에서만 사용될 수 있습니다. 특히 다음과 같은 경우입니다:

• Py_mod_exec,

• module state slots (Py_mod_state_*),

• Py_mod_token.

Added in version 3.5.

버전 3.15에서 변경: slots 인자는 실제 ModuleSpec 인스턴스가 아닌 ModuleSpec 과 유사한 객체일 수 있습니다. 이전 버전의 CPython은 이를 강제하지 않았습니다.

모듈이 반드시 정의로부터 만들어지는 것은 아니기 때문에 이제 def 인자가 NULL 일 수 있습니다.

Py_mod_exec

…의 일부 안정 ABI 버전 3.5 이후로.

모듈을 execute 하거나 초기화하는 함수를 위한 Slot ID 입니다. 이 함수는 파이썬 모듈의 코드를 실행하는 것과 동일한 역할을 수행하며, 일반적으로 클래스와 상수를 모듈에 추가합니다. 함수의 시그니처는 다음과 같습니다.

int exec_module(PyObject *module)

호출 가능한 유용한 함수에 대해서는 지원 함수 섹션을 참조하십시오.

하위 호환성을 위해 PyModuleDef.m_slots 배열은 여러 개의 Py_mod_exec 슬롯을 포함할 수 있으며, 이들은 배열에 나타나는 순서대로 처리됩니다. 그 외의 경우(즉, PyModule_FromSlotsAndSpec() 의 인자와 PyModExport_{<name>}`의 반환 값)에서는 슬롯을 중복해서 사용할 수 없습니다.

Added in version 3.5.

버전 3.15에서 변경: PyModuleDef.m_slots 을 제외하고 중복된 Py_mod_exec 슬롯은 허용되지 않습니다.

Py_mod_methods

…의 일부 안정 ABI 버전 3.15 이후로.

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

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

테이블은 정적으로 할당되어야 하며(또는 모듈 객체보다 오래 유지됨이 보장되어야 합니다).

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

모듈 상태

확장 모듈은 모듈 상태 를 가질 수 있습니다. 이는 모듈 생성 시 할당되고 모듈 객체가 해제될 때 해제되는 메모리 영역입니다. 모듈 상태는 dedicated slots 를 사용하여 정의됩니다.

모듈 상태의 일반적인 용도는 예외 유형을 저장하는 것이며, 실제로 모듈에 의해 정의된 모든 종류의 타입 객체를 저장할 수 있습니다.

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

정적 전역 변수가 아닌 속성과 모듈 상태에 모듈별 정보를 유지하면 모듈 객체가 격리 되어 여러 서브 인터프리터에서 사용하기 더 안전해집니다. 또한 파이썬 종료 시 체계적인 정리가 가능해집니다.

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

주어진 모듈에서 상태를 가져오려면 다음 함수들을 사용하십시오.

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 이후로.

모듈 상태의 크기를 Py_mod_state_size (또는 PyModuleDef.m_size)로 지정된 값으로 결과 에 설정하고 0을 반환합니다.

에러 발생 시 결과 를 -1로 설정하고, 예외를 설정하며 -1을 반환합니다.

Added in version 3.15.

모듈 상태 정의를 위한 슬롯

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

Py_mod_state_size

…의 일부 안정 ABI 버전 3.15 이후로.

모런 상태의 크기를 바이트 단위로 나타내는 슬롯 ID 입니다.

이 값을 음수가 아닌 값으로 설정하면 모듈을 재초기화할 수 있음을 의미하며, 상태를 위해 필요한 추가 메모리 양을 지정합니다.

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

주어진 모듈의 크기를 가져오려면 PyModule_GetStateSize() 를 사용하십시오.

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

Py_mod_state_traverse

…의 일부 안정 ABI 버전 3.15 이후로.

모듈 객체의 가비지 컬렉션(GC) 탐색 중에 호출되는 탐색 함수를 위한 슬롯 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: 이전 버전을 지원하려면 대신 PyModuleDef.m_traverse 를 사용하십시오.

Py_mod_state_clear

…의 일부 안정 ABI 버전 3.15 이후로.

모듈 객체의 가비지 컬렉션(GC) 정리 중에 호출되는 정리 함수를 위한 슬롯 ID 입니다.

함수의 시그니처는 다음과 같습니다:

int clear_module_state(PyObject *module)

모듈 상태가 요청되었으나 아직 할당되지 않은 경우 이 함수는 호출되지 않습니다. 이는 모듈이 생성된 직후이자 실행되기 전(Py_mod_exec 함수)에 해당합니다. 더 정확하게는, 상태 크기(Py_mod_state_size)가 0보다 크고 모듈 상태(PyModule_GetState() 가 반환한 값)이 NULL 인 경우 이 함수가 호출되지 않습니다.

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

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

Py_mod_state_free

…의 일부 안정 ABI 버전 3.15 이후로.

모듈 객체 해제 시 호출되는 함수를 위한 슬롯 ID 입니다.

함수의 시그니처는 다음과 같습니다:

int free_module_state(PyObject *module)

모듈 상태가 요청되었으나 아직 할당되지 않은 경우 이 함수는 호출되지 않습니다. 이는 모듈이 생성된 직후이자 실행되기 전(Py_mod_exec 함수)에 해당합니다. 더 정확하게는, 상태 크기(Py_mod_state_size)가 0보다 크고 모듈 상태(PyModule_GetState() 가 반환한 값)이 NULL 인 경우 이 함수가 호출되지 않습니다.

Added in version 3.15: 이전 버전을 지원하려면 대신 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 값은 다음과 같습니다.

• PyModuleDef 로 생성된 모듈의 경우 해당 PyModuleDef 의 주소입니다.

• Py_mod_token 슬롯으로 정의된 모듈의 경우: 해당 슬롯 값입니다.

• PyModExport_* export hook 에서 생성된 모듈의 경우, 해당 내보내기 훅이 반환한 슬롯 배열입니다(단, Py_mod_token 으로 재정의되지 않은 경우에 한함).

Py_mod_token

…의 일부 안정 ABI 버전 3.15 이후로.

모듈 토큰을 위한 슬롯 ID 입니다.

기본값에 의존하는 대신 이 슬롯을 사용하여 모듈 토큰을 설정하는 경우, 다음 사항을 보장해야 합니다.

• 포인터가 클래스보다 오래 유지되어야 하며, 클래스가 존재하는 동안 다른 용도로 재사용되지 않아야 합니다.

• 해당 포인터는 클래스가 위치한 확장 모듈에 “속해” 있어야 하므로 다른 확장 프로그램과 충돌하지 않습니다.

• 토큰이 PyModuleDef 구조체를 가리키는 경우, 모듈은 해당 PyModuleDef 로부터 생성된 것처럼 동작해야 합니다. 특히 모듈 상태는 일치하는 레이아웃과 의미를 가져야 합니다.

PyModuleDef 에서 생성된 모듈은 항상 해당 PyModuleDef 의 주소를 토큰으로 사용합니다. 이는 PyModuleDef.m_slots 에서 Py_mod_token 을 사용할 수 없음을 의미합니다.

Added in version 3.15.

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

…의 일부 안정 ABI 버전 3.15 이후로.

모듈 의 모듈 토큰을 결과 에 설정하고 0을 반환합니다.

에러 시 결과 를 NULL로 설정하고, 예외를 설정하며 -1을 반환합니다.

Added in version 3.15.

PyType_GetModuleByToken() 도 참조하십시오.

확장 모듈 동적 생성

다음 함수들은 확장 모듈의 export hook 을 통한 방식 대신 확장 모듈을 동적으로 생성할 때 사용될 수 있습니다.

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

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

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

slots 인자는 슬롯 ID가 0인 항목(일반적으로 PySlot_END 로 표기됨)으로 끝나는 PySlot 구조체 배열을 가리켜야 합니다. 해당 배열은 반드시 Py_mod_abi 항목을 포함해야 합니다.

spec 인자는 Py_mod_create 문서에 설명된 대로 ModuleSpec``과 유사한 어떤 객체라도 될 수 있습니다. 현재 *spec*은 ``name 속성을 가져야 합니다.

성공 시 새 모듈을 반환합니다. 에러 시 예외를 설정하고 NULL 을 반환합니다.

이것은 모듈의 실행 슬롯(Py_mod_exec)을 처리하지 않습니다. 모듈을 완전히 초기화하려면 PyModule_FromSlotsAndSpec() 과 PyModule_Exec() 를 모두 호출해야 합니다. (참조: 다단계 초기화.)

Added in version 3.15.

int PyModule_Exec(PyObject *module)

…의 일부 안정 ABI 버전 3.15 이후로.

모듈 의 Py_mod_exec 슬롯을 실행합니다.

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

명확성을 위해 설명하자면, 모듈 이 슬롯을 가지고 있지 않은 경우(예를 들어 legacy single-phase initialization 를 사용하는 경우), 이 함수는 아무것도 수행하지 않고 0을 반환합니다.

Added in version 3.15.

모듈 정의 구조체

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

이러한 방식의 모듈 정의는 여전히 가능하며 이를 제거할 계획은 없습니다.

type PyModuleDef

…의 일부 안정 ABI (see below).

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

이 구조체는 정적으로 할당되어야 하며(또는 이로부터 생성된 모듈이 존재하는 동안 유효함이 보장되어야 합니다). 보통 이러한 방식으로 정의된 각 확장 모듈에 대해 이 유형의 변수는 하나만 존재합니다.

모든 멤버를 포함한 이 구조체는 non-free-threaded 빌드(abi3)의 Stable ABI 에 포함됩니다. free-threaded 빌드의 Stable ABI(abi3t)에서 이 구조체는 불투명하며 실제로는 사용할 수 없습니다. 대체 사항은 모듈 정의 을 참조하십시오.

PyModuleDef_Base m_base

이 멤버를 항상 PyModuleDef_HEAD_INIT 으로 초기화하십시오:

type PyModuleDef_Base

…의 일부 안정 ABI (see below).

PyModuleDef.m_base 의 타입입니다.

이 구조체는 비자유 스레딩 빌드(abi3)를 위한 Stable ABI 의 일부입니다. 자유 스레딩 빌드를 위한 Stable ABI(abi3t)에서 이 구조체는 불투명하며 실제로는 사용할 수 없습니다.

PyModuleDef_HEAD_INIT

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 멤버에 해당하는 슬롯이 포함된 경우, 값들이 일치해야 합니다. 예를 들어, m_slots 에서 Py_mod_name 을 사용하는 경우, 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

PySlot.sl_id 에 해당합니다.

void *value

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 이후로.

Py_slot_subslots 와 유사하게 작동하지만, PyModuleDef_Slot 구조체 배열을 지정하는 Slot ID 입니다.

Added in version 3.15.

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

PyObject *PyModule_Create(PyModuleDef *def)

반환값: 새 참조.

def 의 정의를 사용하여 새 모듈 객체를 생성합니다. 이 매크로는 module_api_version 을 PYTHON_API_VERSION 으로 설정하여 PyModule_Create2() 를 호출하며, 제한된 API 를 사용하는 경우에는 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() 를 호출하며, 제한된 API 를 사용하는 경우에는 PYTHON_ABI_VERSION 으로 설정합니다.

Added in version 3.5.

버전 3.16.0a0 (unreleased)부터 약하게 폐지 <Soft deprecated>: 새 코드에서는 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>: 새 코드에서는 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 구조체에서 생성되지 않은 모듈에서도 작동하는 PyModule_Exec() 를 사용하는 것을 권장합니다.

PYTHON_API_VERSION

PYTHON_API_STRING

C API 버전을 각각 정수(1013)와 문자열("1013")로 나타냅니다. 하위 호환성을 위해 정의되었습니다.

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

PYTHON_ABI_VERSION

PYTHON_ABI_STRING

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

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

지원 함수

모듈 객체 초기화를 돕기 위해 다음 함수들이 제공됩니다. 이들은 모듈의 실행 슬롯(Py_mod_exec), 레거시 단일 단계 초기화 를 위한 초기화 함수, 또는 모듈을 동적으로 생성하는 코드를 위해 설계되었습니다.

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 에 대한 참조를 “steals “합니다. 결과의 성공 여부를 확인하거나 변수에 저장하지 않고도 새 참조를 반환하는 함수의 결과값으로 호출할 수 있습니다.

사용 예:

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() 와 유사하지만, 성공 시(즉, 0 을 반환할 때) value 에 대한 참조를 “steals “합니다.

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을 반환합니다.

이것은 PyLong_FromLong() 및 PyModule_AddObjectRef() 를 호출하는 편의 기능입니다. 자세한 내용은 해당 문서들을 참조하십시오.

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

…의 일부 안정 ABI.

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

이것은 PyUnicode_InternFromString() 및 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 로부터 모듈을 생성할 때 자동으로 호출됩니다(예: 다단계 초기화, PyModule_Create, 또는 PyModule_FromDefAndSpec 사용 시). 일부 모듈 작성자는 여러 개의 PyMethodDef 배열에 함수를 정의하는 것을 선호할 수 있으며, 이 경우 해당 함수를 직접 호출해야 합니다.

functions 배열은 정적으로 할당되어야 하며(또는 모듈 객체보다 오래 유지됨이 보장되어야 함).

Added in version 3.5.

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

…의 일부 안정 ABI 버전 3.7 이후로.

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

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

Added in version 3.5.

int PyUnstable_Module_SetGIL(PyObject *module, void *gil)

이것은 불안정 API. 마이너 릴리스에서 예고 없이 변경될 수 있습니다.

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

Added in version 3.13.

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

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

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

PyObject *PyState_FindModule(PyModuleDef *def)

반환값: 빌린 참조. …의 일부 안정 ABI.

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

int PyState_AddModule(PyObject *module, PyModuleDef *def)

…의 일부 안정 ABI 버전 3.3 이후로.

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

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

파이썬은 단일 단계 초기화 를 사용하는 모듈을 임포트한 후 PyState_AddModule 을 자동으로 호출하므로, 모듈 초기화 코드에서 이를 호출하는 것은 불필요하지만 해롭지는 않습니다. 명시적인 호출이 필요한 경우는 모듈의 자체 초기화 코드가 이후에 PyState_FindModule 을 호출하는 경우뿐입니다. 이 함수는 주로 대체 임포트 메커니즘을 구현하기 위해 설계되었습니다(직접 호출하거나, 요구되는 상태 업데이트에 대한 세부 정보를 확인하기 위해 해당 구현을 참조할 수 있습니다).

동일한 def 를 사용하여 이전에 연결된 모듈이 있다면, 새 module 로 교체됩니다.

The caller must have an attached thread state.

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

Added in version 3.3.

int PyState_RemoveModule(PyModuleDef *def)

…의 일부 안정 ABI 버전 3.3 이후로.

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

The caller must have an attached thread state.

Added in version 3.3.

분실물 보관소