이 문서는 더는 지원되지 않는 이전 버전의 파이썬 용입니다. 업그레이드하고, 다음 설명서를 읽어야 합니다: 현재 안정 버전에 대한 파이썬 설명서.

# 캡슐

이 객체 사용에 대한 자세한 정보는 Providing a C API for an Extension Module를 참조하십시오.

버전 3.1에 추가.

`PyCapsule`

  이 `PyObject`의 서브 형은 불투명한 값을 나타내며, 파이썬 코드를 통해 다른 C 코드로 불투명한 값(`void*` 포인터로)을 전달해야 하는 C 확장 모듈에 유용합니다. 이것은 한 모듈에서 정의된 C 함수 포인터를 다른 모듈에서 사용할 수 있게 만드는 데 종종 사용되므로, 일반 임포트 메커니즘을 사용하여 동적으로 로드된 모듈에 정의된 C API에 액세스할 수 있습니다.

`PyCapsule_Destructor`

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

      typedef void (*PyCapsule_Destructor)(PyObject *);

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

int `PyCapsule_CheckExact`(PyObject *p)

  인자가 `PyCapsule`이면 참을 돌려줍니다.

PyObject* `PyCapsule_New`(void *pointer, const char *name, PyCapsule_Destructor destructor)
  Return value: New reference.

  Create a `PyCapsule` encapsulating the pointer. The pointer argument may not be `NULL`.

  On failure, set an exception and return `NULL`.

  The name string may either be `NULL` or a pointer to a valid C string. If non-`NULL`, this string must outlive the capsule. (Though it is permitted to free it inside the destructor.)

  If the destructor argument is not `NULL`, it will be called with the capsule as its argument when it is destroyed.

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

void* `PyCapsule_GetPointer`(PyObject *capsule, const char *name)

  Retrieve the pointer stored in the capsule. On failure, set an exception and return `NULL`.

  The name parameter must compare exactly to the name stored in the capsule. If the name stored in the capsule is `NULL`, the name passed in must also be `NULL`. Python uses the C function `strcmp()` to compare capsule names.

PyCapsule_Destructor `PyCapsule_GetDestructor`(PyObject *capsule)

  Return the current destructor stored in the capsule. On failure, set an exception and return `NULL`.

  It is legal for a capsule to have a `NULL` destructor. This makes a `NULL` return code somewhat ambiguous; use `PyCapsule_IsValid()` or `PyErr_Occurred()` to disambiguate.

void* `PyCapsule_GetContext`(PyObject *capsule)

  Return the current context stored in the capsule. On failure, set an exception and return `NULL`.

  It is legal for a capsule to have a `NULL` context. This makes a `NULL` return code somewhat ambiguous; use `PyCapsule_IsValid()` or `PyErr_Occurred()` to disambiguate.

const char* `PyCapsule_GetName`(PyObject *capsule)

  Return the current name stored in the capsule. On failure, set an exception and return `NULL`.

  It is legal for a capsule to have a `NULL` name. This makes a `NULL` return code somewhat ambiguous; use `PyCapsule_IsValid()` or `PyErr_Occurred()` to disambiguate.

void* `PyCapsule_Import`(const char *name, int no_block)

  모듈의 캡슐 어트리뷰트에서 C 객체에 대한 포인터를 임포트 합니다. name 매개 변수는 `module.attribute` 처럼 어트리뷰트의 전체 이름을 지정해야 합니다. 캡슐에 저장된 name은, 이 문자열과 정확히 일치해야 합니다. no_block이 참이면, 블록하지 않고 모듈을 임포트 합니다 (`PyImport_ImportModuleNoBlock()`를 사용해서). no_block이 거짓이면, 모듈을 평범하게 임포트 합니다 (`PyImport_ImportModule()`을 사용해서).

  Return the capsule’s internal pointer on success. On failure, set an exception and return `NULL`.

int `PyCapsule_IsValid`(PyObject *capsule, const char *name)

  Determines whether or not capsule is a valid capsule. A valid capsule is non-`NULL`, passes `PyCapsule_CheckExact()`, has a non-`NULL` pointer stored in it, and its internal name matches the name parameter. (See `PyCapsule_GetPointer()` for information on how capsule names are compared.)

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

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

int `PyCapsule_SetContext`(PyObject *capsule, void *context)

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

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

int `PyCapsule_SetDestructor`(PyObject *capsule, PyCapsule_Destructor destructor)

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

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

int `PyCapsule_SetName`(PyObject *capsule, const char *name)

  Set the name inside capsule to name. If non-`NULL`, the name must outlive the capsule. If the previous name stored in the capsule was not `NULL`, no attempt is made to free it.

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

int `PyCapsule_SetPointer`(PyObject *capsule, void *pointer)

  Set the void pointer inside capsule to pointer. The pointer may not be `NULL`.

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