모듈 객체
*********

PyTypeObject PyModule_Type

   이 "PyTypeObject" 인스턴스는 파이썬 모듈 형을 나타냅니다. 이것은
   "types.ModuleType"으로 파이썬 프로그램에 노출됩니다.

int PyModule_Check(PyObject *p)

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

int PyModule_CheckExact(PyObject *p)

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

PyObject* PyModule_NewObject(PyObject *name)
    *Return value: New reference.*

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

   버전 3.3에 추가.

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

PyObject* PyModule_New(const char *name)
    *Return value: New reference.*

   "PyModule_NewObject()"와 비슷하지만, name이 유니코드 객체 대신
   UTF-8로 인코딩된 문자열입니다.

PyObject* PyModule_GetDict(PyObject *module)
    *Return value: Borrowed reference.*

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

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

PyObject* PyModule_GetNameObject(PyObject *module)
    *Return value: New reference.*

   *module*의 "__name__" 값을 반환합니다. 모듈이 제공하지 않거나, 문자
   열이 아니면, "SystemError"가 발생하고 "NULL"이 반환됩니다.

   버전 3.3에 추가.

const char* PyModule_GetName(PyObject *module)

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

void* PyModule_GetState(PyObject *module)

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

PyModuleDef* PyModule_GetDef(PyObject *module)

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

PyObject* PyModule_GetFilenameObject(PyObject *module)
    *Return value: New reference.*

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

   버전 3.2에 추가.

const char* PyModule_GetFilename(PyObject *module)

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

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


C 모듈 초기화
=============

모듈 객체는 일반적으로 확장 모듈(초기화 함수를 내보내는 공유 라이브러
리)이나 컴파일된 모듈(초기화 함수가 "PyImport_AppendInittab()"을 사용
하여 추가된)에서 만들어집니다. 자세한 내용은 C와 C++ 확장 빌드하기나
내장된 파이썬을 확장하기를 참조하십시오.

초기화 함수는 모듈 정의 인스턴스를 "PyModule_Create()"에 전달하고 결과
모듈 객체를 반환하거나, 정의 구조체 자체를 반환하여 "다단계 초기화"를
요청할 수 있습니다.

PyModuleDef

   모듈 객체를 만드는 데 필요한 모든 정보를 담고 있는 모듈 정의 구조체
   . 일반적으로 각 모듈에 대해 이 형의 정적으로 초기화된 변수가 하나만
   있습니다.

   PyModuleDef_Base m_base

      이 멤버를 항상 "PyModuleDef_HEAD_INIT"로 초기화하십시오.

   const char *m_name

      새 모듈의 이름.

   const char *m_doc

      모듈의 독스트링; 일반적으로 "PyDoc_STRVAR"로 만들어진 독스트링
      변수가 사용됩니다.

   Py_ssize_t m_size

      모듈 상태는 정적 전역이 아닌 "PyModule_GetState()"로 조회할 수
      있는 모듈별 메모리 영역에 유지될 수 있습니다. 이것은 여러 서브
      인터프리터에서 모듈을 사용하는 것을 안전하게 만듭니다.

      이 메모리 영역은 모듈 생성 시 *m_size*를 기준으로 할당되며, 모듈
      객체가 할당 해제될 때 (있다면 "m_free" 함수가 호출된 후에) 해제
      됩니다.

      "m_size"를 "-1"로 설정하면 모듈이 전역 상태를 갖기 때문에 서브
      인터프리터를 지원하지 않는다는 뜻입니다.

      음수가 아닌 값으로 설정하면 모듈을 다시 초기화 할 수 있다는 뜻이
      며 상태에 필요한 추가 메모리양을 지정합니다. 다단계 초기화에는
      음이 아닌 "m_size"가 필요합니다.

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

   PyMethodDef* m_methods

      "PyMethodDef" 값으로 기술되는 모듈 수준 함수 테이블에 대한 포인
      터. 함수가 없으면 "NULL"일 수 있습니다.

   PyModuleDef_Slot* m_slots

      다단계 초기화를 위한 슬롯 정의 배열, "{0, NULL}" 항목으로 종료됩
      니다. 단단계 초기화를 사용할 때, *m_slots*는 "NULL"이어야 합니다
      .

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

         inquiry m_reload

   traverseproc m_traverse

      모듈 객체의 GC 탐색 중 호출할 탐색 함수나, 필요하지 않으면
      "NULL".

      모듈 상태가 요청되었지만, 아직 할당되지 않았으면 이 함수가 호출
      되지 않습니다. 이것은 모듈이 만들이진 직후, 모듈이 실행되기 직전
      의 경우입니다 ("Py_mod_exec" 함수). 더 정확하게는, "m_size"가 0
      보다 크고 모듈 상태("PyModule_GetState()"가 반환하는)가 "NULL"이
      면 이 함수가 호출되지 않습니다.

      버전 3.9에서 변경: 모듈 상태가 할당되기 전에 더는 호출되지 않습
      니다.

   inquiry m_clear

      모듈 객체의 GC 정리 중에 호출할 정리(clear) 함수나, 필요하지 않
      으면 "NULL".

      모듈 상태가 요청되었지만, 아직 할당되지 않았으면 이 함수가 호출
      되지 않습니다. 이것은 모듈이 만들이진 직후, 모듈이 실행되기 직전
      의 경우입니다 ("Py_mod_exec" 함수). 더 정확하게는, "m_size"가 0
      보다 크고 모듈 상태("PyModule_GetState()"가 반환하는)가 "NULL"이
      면 이 함수가 호출되지 않습니다.

      Like "PyTypeObject.tp_clear", this function is not *always*
      called before a module is deallocated. For example, when
      reference counting is enough to determine that an object is no
      longer used, the cyclic garbage collector is not involved and
      "m_free" is called directly.

      버전 3.9에서 변경: 모듈 상태가 할당되기 전에 더는 호출되지 않습
      니다.

   freefunc m_free

      모듈 객체 할당 해제 중에 호출할 함수나, 필요하지 않으면 "NULL".

      모듈 상태가 요청되었지만, 아직 할당되지 않았으면 이 함수가 호출
      되지 않습니다. 이것은 모듈이 만들이진 직후, 모듈이 실행되기 직전
      의 경우입니다 ("Py_mod_exec" 함수). 더 정확하게는, "m_size"가 0
      보다 크고 모듈 상태("PyModule_GetState()"가 반환하는)가 "NULL"이
      면 이 함수가 호출되지 않습니다.

      버전 3.9에서 변경: 모듈 상태가 할당되기 전에 더는 호출되지 않습
      니다.


단단계 초기화
-------------

모듈 초기화 함수는 모듈 객체를 직접 만들고 반환할 수 있습니다. 이것을
"단단계 초기화"라고 하며, 다음 두 모듈 생성 함수 중 하나를 사용합니다:

PyObject* PyModule_Create(PyModuleDef *def)
    *Return value: New reference.*

   *def*의 정의에 따라, 새 모듈 객체를 만듭니다. 이것은
   *module_api_version*이 "PYTHON_API_VERSION"으로 설정된
   "PyModule_Create2()"처럼 동작합니다.

PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
    *Return value: New reference.*

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

   참고:

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

초기화 함수에서 반환되기 전에, 결과 모듈 객체는 일반적으로
"PyModule_AddObject()"와 같은 함수를 사용하여 채워집니다.


다단계 초기화
-------------

확장을 지정하는 다른 방법은 "다단계 초기화"를 요청하는 것입니다. 이 방
법으로 만들어진 확장 모듈은 파이썬 모듈과 더 비슷하게 동작합니다: 초기
화는 모듈 객체가 만들어질 때의 *생성 단계(creation phase)*와 채워질 때
의 *실행 단계(execution phase)*로 분할됩니다. 구별은 클래스의
"__new__()"와 "__init__()" 메서드와 유사합니다.

단단계 초기화를 사용하여 만들어진 모듈과 달리, 이 모듈은 싱글톤이 아닙
니다: *sys.modules* 항목을 제거하고 모듈을 다시 임포트 하면, 새 모듈
객체가 만들어지고, 이전 모듈은 일반 가비지 수집이 적용됩니다 -- 파이썬
모듈과 마찬가지입니다. 기본적으로, 같은 정의에서 만들어진 여러 모듈은
독립적이어야 합니다: 하나를 변경해도 다른 모듈에는 영향을 미치지 않습
니다. 즉, 모든 상태는 모듈 객체(예를 들어 "PyModule_GetState()"를 사용
해서)나 그 내용(가령 모듈의 "__dict__"나 "PyType_FromSpec()"으로 만든
개별 클래스)으로 제한되어야 합니다.

다단계 초기화를 사용하여 만들어진 모든 모듈은 서브 인터프리터를 지원할
것으로 기대됩니다. 다중 모듈을 독립적으로 유지하는 것은 일반적으로 이
를 달성하기에 충분합니다.

다단계 초기화를 요청하기 위해, 초기화 함수(PyInit_modulename)는 비어
있지 않은 "m_slots"를 가진 "PyModuleDef" 인스턴스를 반환합니다. 반환되
기 전에, "PyModuleDef" 인스턴스를 다음 함수를 사용하여 초기화해야 합니
다:

PyObject* PyModuleDef_Init(PyModuleDef *def)
    *Return value: Borrowed reference.*

   모듈 정의가 형과 참조 횟수를 올바르게 보고하는 올바르게 초기화된 파
   이썬 객체이게 합니다.

   *def*를 "PyObject*"로 캐스트 하거나, 에러가 발생하면 "NULL"을 반환
   합니다.

   버전 3.5에 추가.

모듈 정의의 *m_slots* 멤버는 "PyModuleDef_Slot" 구조체의 배열을 가리켜
야 합니다:

PyModuleDef_Slot

   int slot

      아래 설명된 사용 가능한 값 중에서 선택된, 슬롯 ID.

   void* value

      슬롯 ID에 따라 그 의미가 달라지는, 슬롯의 값.

   버전 3.5에 추가.

*m_slots* 배열은 id가 0인 슬롯으로 종료해야 합니다.

사용 가능한 슬롯 형은 다음과 같습니다:

Py_mod_create

   모듈 객체 자체를 만들기 위해 호출되는 함수를 지정합니다. 이 슬롯의
   *value* 포인터는 다음과 같은 서명을 갖는 함수를 가리켜야 합니다:

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

   이 함수는 **PEP 451**에 정의된 대로, "ModuleSpec" 인스턴스와 모듈
   정의를 받습니다. 새 모듈 객체를 반환하거나, 에러를 설정하고 "NULL"
   을 반환해야 합니다.

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

   하나의 모듈 정의에서 여러 "Py_mod_create" 슬롯을 지정할 수 없습니다
   .

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

   반환된 객체가 "PyModule_Type"의 인스턴스 일 필요는 없습니다. 임포트
   관련 어트리뷰트 설정과 읽기를 지원하는 한 모든 형을 사용할 수 있습
   니다. 그러나, "PyModuleDef"에 "NULL"이 아닌 "m_traverse",
   "m_clear", "m_free"; 0이 아닌 "m_size"; 또는 "Py_mod_create" 이외의
   슬롯이 있으면, "PyModule_Type" 인스턴스 만 반환될 수 있습니다.

Py_mod_exec

   모듈을 *실행*하기 위해 호출되는 함수를 지정합니다. 이것은 파이썬 모
   듈의 코드를 실행하는 것과 동등합니다: 일반적으로, 이 함수는 클래스
   와 상수를 모듈에 추가합니다. 함수의 서명은 다음과 같습니다:

   int exec_module(PyObject* module)

   여러 개의 "Py_mod_exec" 슬롯이 지정되면, *m_slots* 배열에 나타나는
   순서대로 처리됩니다.

다단계 초기화에 대한 자세한 내용은 **PEP 489**를 참조하십시오.


저수준 모듈 생성 함수
---------------------

다단계 초기화를 사용할 때 수면 아래에서는 다음 함수가 호출됩니다. 이들
은 직접 사용할 수 있는데, 예를 들어 모듈 객체를 동적으로 생성할 때 그
렇습니다. 모듈을 완전히 초기화하려면 "PyModule_FromDefAndSpec"과
"PyModule_ExecDef"를 모두 호출해야 함에 유의하십시오.

PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
    *Return value: New reference.*

   주어진 *모듈*의 정의와 ModuleSpec *spec*으로 새 모듈 객체를 만듭니
   다. 이것은 *module_api_version*이 "PYTHON_API_VERSION"으로 설정된
   "PyModule_FromDefAndSpec2()"처럼 동작합니다.

   버전 3.5에 추가.

PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
    *Return value: New reference.*

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

   참고:

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

   버전 3.5에 추가.

int PyModule_ExecDef(PyObject *module, PyModuleDef *def)

   *def*에 지정된 모든 실행 슬롯("Py_mod_exec")을 처리합니다.

   버전 3.5에 추가.

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

   *module*의 독스트링을 *docstring*으로 설정합니다. 이 함수는
   "PyModule_Create"나 "PyModule_FromDefAndSpec"을 사용하여
   "PyModuleDef"에서 모듈을 만들 때 자동으로 호출됩니다.

   버전 3.5에 추가.

int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)

   "NULL" 종료 *functions* 배열의 함수를 *module*에 추가합니다. 개별
   항목에 대한 자세한 내용은 "PyMethodDef" 설명서를 참조하십시오 (공유
   모듈 이름 공간이 없기 때문에, C로 구현된 모듈 수준 "함수
   (functions)"는 일반적으로 첫 번째 매개 변수로 모듈을 수신하여, 파이
   썬 클래스의 인스턴스 메서드와 유사하게 만듭니다). 이 함수는
   "PyModule_Create"나 "PyModule_FromDefAndSpec"을 사용하여
   "PyModuleDef"에서 모듈을 만들 때 자동으로 호출됩니다.

   버전 3.5에 추가.


지원 함수
---------

모듈 초기화 함수(단단계 초기화를 사용하는 경우)나 모듈 실행 슬롯에서
호출되는 함수(다단계 초기화를 사용하는 경우)는, 모듈 상태 초기화를 도
우려고 다음 함수를 사용할 수 있습니다:

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

   *name*으로 *module*에 객체를 추가합니다. 모듈의 초기화 함수에서 사
   용할 수 있는 편의 함수입니다. 성공 시 *value*에 대한 참조를 훔칩니
   다. 에러 시 "-1"을, 성공하면 "0"을 반환합니다.

   참고:

     참조를 훔치는 다른 함수와 달리, "PyModule_AddObject()"는 **성공
     시**에만 *value*의 참조 횟수를 감소시킵니다.이는 반환 값을 확인해
     야 하며, 에러 시 호출하는 코드가 수동으로 *value*를 "Py_DECREF()"
     해야 함을 뜻합니다. 사용법 예:

        Py_INCREF(spam);
        if (PyModule_AddObject(module, "spam", spam) < 0) {
            Py_DECREF(module);
            Py_DECREF(spam);
            return NULL;
        }

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

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

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

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

int PyModule_AddIntMacro(PyObject *module, macro)

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

int PyModule_AddStringMacro(PyObject *module, macro)

   *module*에 문자열 상수를 추가합니다.

int PyModule_AddType(PyObject *module, PyTypeObject *type)

   *module*에 형 객체를 추가합니다. 내부적으로 "PyType_Ready()"를 호출
   하여 형 객체를 파이널라이즈합니다. 형 객체의 이름은 점 뒤 "tp_name"
   의 마지막 구성 요소에서 가져옵니다. 에러가 발생하면 "-1", 성공하면
   "0"을 반환합니다.

   버전 3.9에 추가.


모듈 조회
=========

단단계 초기화는 현재 인터프리터의 컨텍스트에서 조회할 수 있는 싱글톤
모듈을 만듭니다. 이는 나중에 모듈 정의에 대한 참조만으로 모듈 객체를
검색할 수 있도록 합니다.

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

PyObject* PyState_FindModule(PyModuleDef *def)
    *Return value: Borrowed reference.*

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

int PyState_AddModule(PyObject *module, PyModuleDef *def)

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

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

   파이썬은 모듈을 임포트 한 후 자동으로 "PyState_AddModule"을 호출하
   므로, 모듈 초기화 코드에서 호출하는 것은 불필요합니다 (하지만 무해
   합니다). 모듈의 자체 초기화 코드가 추후 "PyState_FindModule"을 호출
   하는 경우에만 명시적인 호출이 필요합니다. 이 함수는 주로 대안 임포
   트 메커니즘을 구현하기 위한 것입니다 (직접 호출하거나, 필요한 상태
   갱신에 대한 자세한 내용에 대해 해당 구현을 참조함으로써).

   호출자는 GIL을 보유해야 합니다.

   성공하면 0을, 실패하면 -1을 반환합니다.

   버전 3.3에 추가.

int PyState_RemoveModule(PyModuleDef *def)

   *def*에서 만들어진 모듈 객체를 인터프리터 상태에서 제거합니다. 성공
   하면 0을, 실패하면 -1을 반환합니다.

   호출자는 GIL을 보유해야 합니다.

   버전 3.3에 추가.
