# 캡슐

이 객체 사용에 대한 자세한 정보는 확장 모듈을 위한 C API 제공하기를 참조하십시오.

Added in version 3.1.

type PyCapsule

  This subtype of `PyObject` represents an opaque value, useful for C extension modules which need to pass an opaque value (as a void* pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.

PyTypeObject PyCapsule_Type
  Part of the 안정 ABI.

  The type object corresponding to capsule objects. This is the same object as `types.CapsuleType` in the Python layer.

type PyCapsule_Destructor
  Part of the 안정 ABI.

  캡슐에 대한 파괴자(destructor) 콜백 형. 이렇게 정의됩니다:

      typedef void (*PyCapsule_Destructor)(PyObject *);

  PyCapsule_Destructor 콜백의 의미는 `PyCapsule_New()`를 참조하십시오.

int PyCapsule_CheckExact(PyObject *p)
  Thread safety: Atomic.

  인자가 `PyCapsule`이면 참을 돌려줍니다. 이 함수는 항상 성공합니다.

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
  반환값: 새 참조. Part of the 안정 ABI. Thread safety: Atomic.

  pointer를 캡슐화하는 `PyCapsule`을 만듭니다. pointer 인자는 `NULL`이 아닐 수도 있습니다.

  실패하면, 예외를 설정하고 `NULL`을 반환합니다.

  name 문자열은 `NULL` 이나 유효한 C 문자열에 대한 포인터일 수 있습니다. `NULL`이 아니면, 이 문자열은 캡슐보다 오래 유지되어야 합니다. (destructor 내부에서 해제할 수는 있습니다.)

  destructor 인자가 `NULL`이 아니면, 캡슐이 파괴될 때 캡슐을 인자로 호출됩니다.

  이 캡슐을 모듈의 어트리뷰트로 저장하려면, name을 `modulename.attributename`로 지정해야 합니다. 이렇게 하면 다른 모듈이 `PyCapsule_Import()`를 사용하여 캡슐을 임포트 할 수 있습니다.

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  캡슐에 저장된 pointer를 가져옵니다. 실패하면, 예외를 설정하고 `NULL`을 반환합니다.

  name 매개 변수는 캡슐에 저장된 이름과 정확하게 비교되어야 합니다. 캡슐에 저장된 이름이 `NULL`이면, 전달된 name도 `NULL` 이어야 합니다. 파이썬은 C 함수 `strcmp()`를 사용하여 캡슐 이름을 비교합니다.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  캡슐에 저장된 현재 파괴자를 반환합니다. 실패하면, 예외를 설정하고 `NULL`을 반환합니다.

  캡슐이 `NULL` 파괴자를 갖는 것은 합법적입니다. 이것은 `NULL` 반환 코드를 다소 모호하게 만듭니다; 명확히 하려면 `PyCapsule_IsValid()` 나 `PyErr_Occurred()`를 사용하십시오.

void *PyCapsule_GetContext(PyObject *capsule)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  캡슐에 저장된 현재 컨텍스트를 반환합니다. 실패하면, 예외를 설정하고 `NULL`을 반환합니다.

  캡슐이 `NULL` 컨텍스트를 갖는 것은 합법적입니다. 이것은 `NULL` 반환 코드를 다소 모호하게 만듭니다; 명확히 하려면 `PyCapsule_IsValid()` 나 `PyErr_Occurred()`를 사용하십시오.

const char *PyCapsule_GetName(PyObject *capsule)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  캡슐에 저장된 현재 이름을 반환합니다. 실패하면, 예외를 설정하고 `NULL`을 반환합니다.

  캡슐이 `NULL` 이름을 갖는 것은 합법적입니다. 이것은 `NULL` 반환 코드를 다소 모호하게 만듭니다; 명확히 하려면 `PyCapsule_IsValid()` 나 `PyErr_Occurred()`를 사용하십시오.

void *PyCapsule_Import(const char *name, int no_block)
  Part of the 안정 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

  모듈의 캡슐 어트리뷰트에서 C 객체에 대한 포인터를 임포트 합니다. name 매개 변수는 `module.attribute` 처럼 어트리뷰트의 전체 이름을 지정해야 합니다. 캡슐에 저장된 name은, 이 문자열과 정확히 일치해야 합니다.

  이 함수는 name을 `.` 문자로 분리하고, 첫 번째 요소를 임포트 합니다. 그런 다음 어트리뷰트 조회를 사용하여 나머지 요소들을 처리합니다.

  성공하면 캡슐의 내부 pointer를 반환합니다. 실패하면, 예외를 설정하고 `NULL`를 반환합니다.

  참고

  만약 name이 특정 서브 모듈이나 서브 패키지의 어트리뷰트를 가리키는 경우, 어트리뷰트 조회가 성공하려면 해당 서브 모듈이나 서브 패키지를 다른 방법(예를 들어, `PyImport_ImportModule()` 사용)으로 미리 임포트해야 합니다.

  버전 3.3에서 변경: no_block은 더는 효과가 없습니다.

int PyCapsule_IsValid(PyObject *capsule, const char *name)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule이 유효한 캡슐인지를 판단합니다. 유효한 캡슐은 `NULL`이 아니며, `PyCapsule_CheckExact()`를 통과하고, `NULL`이 아닌 포인터가 저장되며, 내부 이름이 name 매개 변수와 일치합니다. (캡슐 이름을 비교하는 방법에 대한 정보는 `PyCapsule_GetPointer()`를 참조하십시오.)

  즉, `PyCapsule_IsValid()`가 참값을 반환하면, 모든 접근자(`PyCapsule_Get`으로 시작하는 모든 함수)에 대한 호출이 성공함이 보장됩니다.

  객체가 유효하고 전달된 이름과 일치하면 0이 아닌 값을 반환합니다. 그렇지 않으면 `0`을 반환합니다. 이 함수는 실패하지 않습니다.

int PyCapsule_SetContext(PyObject *capsule, void *context)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule 내부의 컨텍스트 포인터를 context로 설정합니다.

  성공하면 `0`을 반환합니다. 실패하면 0이 아닌 값을 반환하고 예외를 설정합니다.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule 내부의 파괴자를 destructor로 설정합니다.

  성공하면 `0`을 반환합니다. 실패하면 0이 아닌 값을 반환하고 예외를 설정합니다.

int PyCapsule_SetName(PyObject *capsule, const char *name)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule 내부의 이름을 name으로 설정합니다. `NULL`이 아니면, 이름은 캡슐보다 오래 유지되어야 합니다. 캡슐에 저장된 이전 name이 `NULL`이 아니면, 이를 해제하려고 시도하지 않습니다.

  성공하면 `0`을 반환합니다. 실패하면 0이 아닌 값을 반환하고 예외를 설정합니다.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
  Part of the 안정 ABI. Thread safety: Safe to call without external synchronization on distinct objects.

  capsule 내부의 void 포인터를 pointer로 설정합니다. 포인터는 `NULL`이 아닐 수 있습니다.

  성공하면 `0`을 반환합니다. 실패하면 0이 아닌 값을 반환하고 예외를 설정합니다.