인자 구문 분석과 값 구축

이 함수들은 자체 확장 함수와 메서드를 만들 때 유용합니다. 추가 정보와 예제는 파이썬 인터프리터 확장 및 내장에 있습니다.

설명된 이러한 함수 중 처음 세 개인 PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords() 및 PyArg_Parse()는 모두 예상 인자에 관한 사항을 함수에 알리는 데 사용되는 포맷 문자열(format strings)을 사용합니다. 포맷 문자열은 이러한 각 함수에 대해 같은 문법을 사용합니다.

인자 구문 분석

포맷 문자열은 0개 이상의 "포맷 단위(format units)"로 구성됩니다. 포맷 단위는 하나의 파이썬 객체를 설명합니다; 일반적으로 단일 문자나 괄호로 묶인 포맷 단위 시퀀스입니다. 몇 가지 예외를 제외하고, 괄호로 묶인 시퀀스가 아닌 포맷 단위는 일반적으로 이러한 함수에 대한 단일 주소 인자에 대응합니다. 다음 설명에서, 인용된(quoted) 형식은 포맷 단위입니다; (둥근) 괄호 안의 항목은 포맷 단위와 일치하는 파이썬 객체 형입니다; [대괄호] 안의 항목은 주소를 전달해야 하는 C 변수의 형입니다.

문자열과 버퍼

이러한 포맷을 사용하면 연속적인 메모리 청크로 객체에 액세스 할 수 있습니다. 반환된 유니코드나 바이트열 영역에 대한 원시 저장소를 제공할 필요가 없습니다.

일반적으로, 포맷이 버퍼에 대한 포인터를 설정할 때, 버퍼는 해당 파이썬 객체에 의해 관리되고, 버퍼는 이 객체의 수명을 공유합니다. 여러분이 직접 메모리를 해제할 필요가 없습니다. 유일한 예외는 es, es#, et 및 et#입니다.

그러나, Py_buffer 구조체가 채워질 때, 하부 버퍼가 잠겨서, 호출자가 Py_BEGIN_ALLOW_THREADS 블록 내에서도 가변 데이터의 크기가 조정되거나 파괴될 위험 없이 이후에 버퍼를 사용할 수 있습니다. 결과적으로, 데이터 처리를 마친 후 (또는 모든 조기 중단의 경우) PyBuffer_Release()를 호출해야 합니다.

달리 명시되지 않는 한, 버퍼는 NUL로 종료되지 않습니다.

일부 포맷에는 읽기 전용 바이트열류 객체가 필요하며, 버퍼 구조체 대신 포인터를 설정합니다. 객체의 PyBufferProcs.bf_releasebuffer 필드가 NULL인지 확인하여 작동하며, 이때는 bytearray와 같은 가변 객체를 허용하지 않습니다.

참고

모든 포맷의 # 변형(s#, y# 등)에 대해, 길이 인자의 형(int나 Py_ssize_t)은 Python.h를 포함하기 전에 매크로 PY_SSIZE_T_CLEAN을 정의하여 제어됩니다. 매크로가 정의되었으면, 길이는 int가 아닌 Py_ssize_t입니다. 이 동작은 향후 파이썬 버전에서 Py_ssize_t만 지원하고 int 지원을 중단하도록 변경됩니다. 항상 PY_SSIZE_T_CLEAN을 정의하는 것이 가장 좋습니다.

s (str) [const char *]

유니코드 객체를 문자열에 대한 C 포인터로 변환합니다. 기존 문자열에 대한 포인터는 여러분이 주소를 전달한 문자 포인터 변수에 저장됩니다. C 문자열은 NUL로 종료됩니다. 파이썬 문자열은 내장된 널 코드 포인트를 포함하지 않아야 합니다; 그렇다면 ValueError 예외가 발생합니다. 유니코드 객체는 'utf-8' 인코딩을 사용하여 C 문자열로 변환됩니다. 이 변환이 실패하면, UnicodeError가 발생합니다.

참고

이 포맷은 바이트열류 객체를 받아들이지 않습니다. 파일 시스템 경로를 받아들이고 이를 C 문자열로 변환하려면, PyUnicode_FSConverter()를 converter로 O& 포맷을 사용하는 것이 좋습니다.

버전 3.5에서 변경: 이전에는, 파이썬 문자열에서 내장된 널 코드 포인트가 발견되면 TypeError가 발생했습니다.

s* (str 또는 바이트열류 객체) [Py_buffer]

이 포맷은 바이트열류 객체뿐만 아니라 유니코드 객체를 받아들입니다. 호출자가 제공한 Py_buffer 구조체를 채웁니다. 이 경우 결과 C 문자열은 내장된 NUL 바이트를 포함할 수 있습니다. 유니코드 객체는 'utf-8' 인코딩을 사용하여 C 문자열로 변환됩니다.

s# (str, 읽기 전용 바이트열류 객체) [const char *, int 또는 Py_ssize_t]

가변 객체를 받아들이지 않는다는 점을 제외하면, s*와 같습니다. 결과는 두 개의 C 변수에 저장됩니다. 첫 번째 변수는 C 문자열에 대한 포인터이고, 두 번째 변수는 길이입니다. 문자열은 내장 널 바이트를 포함할 수 있습니다. 유니코드 객체는 'utf-8' 인코딩을 사용하여 C 문자열로 변환됩니다.

z (str 또는 None) [const char *]

s와 비슷하지만, 파이썬 객체가 None일 수도 있는데, 이 경우 C 포인터가 NULL로 설정됩니다.

z* (str, 바이트열류 객체 또는 None) [Py_buffer]

s*와 비슷하지만, 파이썬 객체는 None일 수도 있습니다, 이 경우 Py_buffer 구조체의 buf 멤버가 NULL로 설정됩니다.

z# (str, 읽기 전용 바이트열류 객체 또는 None) [const char *, int 또는 Py_ssize_t]

s#와 비슷하지만, 파이썬 객체는 None일 수도 있습니다, 이 경우 C 포인터가 NULL로 설정됩니다.

y (읽기 전용 바이트열류 객체) [const char *]

이 포맷은 바이트열류 객체를 문자열에 대한 C 포인터로 변환합니다; 유니코드 객체를 받아들이지 않습니다. 바이트열 버퍼는 내장 널 바이트를 포함하지 않아야 합니다; 만약 그렇다면, ValueError 예외가 발생합니다.

버전 3.5에서 변경: 이전에는, 바이트열 버퍼에서 내장 널 바이트가 발견되면 TypeError가 발생했습니다.

y* (바이트열류 객체) [Py_buffer]

s*의 이 변형은 유니코드 객체가 아니라 바이트열류 객체만 받아들입니다. 바이너리 데이터를 받아들이는 권장 방법입니다.

y# (읽기 전용 바이트열류 객체) [const char *, int 또는 Py_ssize_t]

s#의 이 변형은 유니코드 객체가 아니라 바이트열류 객체만 받아들입니다.

S (bytes) [PyBytesObject *]

변환을 시도하지 않고, 파이썬 객체가 bytes 객체일 것을 요구합니다. 객체가 바이트열 객체가 아니면 TypeError를 발생시킵니다. C 변수는 PyObject*로 선언될 수도 있습니다.

Y (bytearray) [PyByteArrayObject *]

변환을 시도하지 않고, 파이썬 객체가 bytearray 객체일 것을 요구합니다. 객체가 bytearray 객체가 아니면 TypeError를 발생시킵니다. C 변수는 PyObject*로 선언될 수도 있습니다.

u (str) [const Py_UNICODE *]

파이썬 유니코드 객체를 유니코드 문자의 NUL 종료 버퍼에 대한 C 포인터로 변환합니다. 기존 유니코드 버퍼에 대한 포인터로 채워질, Py_UNICODE 포인터 변수의 주소를 전달해야 합니다. Py_UNICODE 문자의 너비는 컴파일 옵션에 따라 다음에 유의하십시오 (16비트나 32비트입니다). 파이썬 문자열은 내장 널 코드 포인트를 포함하지 않아야 합니다; 만약 그렇다면, ValueError 예외가 발생합니다.

버전 3.5에서 변경: 이전에는, 파이썬 문자열에서 내장된 널 코드 포인트가 발견되면 TypeError가 발생했습니다.

Deprecated since version 3.3, will be removed in version 3.12: 이전 스타일 Py_UNICODE API의 일부입니다; PyUnicode_AsWideCharString() 을 사용하여 마이그레이션 하십시오.

u# (str) [const Py_UNICODE *, int 또는 Py_ssize_t]

u의 이 변형은 두 개의 C 변수에 저장됩니다, 첫 번째 변수는 유니코드 데이터 버퍼에 대한 포인터이고, 두 번째 변수는 길이입니다. 이 변형은 널 코드 포인트를 허용합니다.

Deprecated since version 3.3, will be removed in version 3.12: 이전 스타일 Py_UNICODE API의 일부입니다; PyUnicode_AsWideCharString() 을 사용하여 마이그레이션 하십시오.

Z (str 또는 None) [const Py_UNICODE *]

u와 비슷하지만, 파이썬 객체는 None일 수도 있습니다, 이 경우 Py_UNICODE 포인터가 NULL로 설정됩니다.

Deprecated since version 3.3, will be removed in version 3.12: 이전 스타일 Py_UNICODE API의 일부입니다; PyUnicode_AsWideCharString() 을 사용하여 마이그레이션 하십시오.

Z# (str 또는 None) [const Py_UNICODE *, int or Py_ssize_t]

u#와 비슷하지만, 파이썬 객체는 None일 수도 있습니다, 이 경우 Py_UNICODE 포인터가 NULL로 설정됩니다.

Deprecated since version 3.3, will be removed in version 3.12: 이전 스타일 Py_UNICODE API의 일부입니다; PyUnicode_AsWideCharString() 을 사용하여 마이그레이션 하십시오.

U (str) [PyObject *]

변환을 시도하지 않고, 파이썬 객체가 유니코드 객체일 것을 요구합니다. 객체가 유니코드 객체가 아니면 TypeError를 발생시킵니다. C 변수는 PyObject*로 선언될 수도 있습니다.

w* (읽기-쓰기 바이트열류 객체) [Py_buffer]

이 포맷은 읽기-쓰기 버퍼 인터페이스를 구현하는 모든 객체를 허용합니다. 호출자가 제공한 Py_buffer 구조체를 채웁니다. 버퍼에는 내장 널 바이트가 포함될 수 있습니다. 호출자는 버퍼로 할 일을 마치면 PyBuffer_Release()를 호출해야 합니다.

es (str) [const char *encoding, char **buffer]

s의 이 변형은 유니코드를 문자 버퍼로 인코딩하는 데 사용됩니다. 내장 NUL 바이트가 포함되지 않은 인코딩된 데이터에 대해서만 작동합니다.

이 포맷에는 두 개의 인자가 필요합니다. 첫 번째는 입력으로만 사용되며, 인코딩 이름을 가리키는 NUL 종료 문자열로 const char*이거나, 'utf-8' 인코딩이 사용되도록 하는 NULL이어야 합니다. 명명된 인코딩이 파이썬에 알려지지 않았으면 예외가 발생합니다. 두 번째 인자는 char**여야 합니다; 참조하는 포인터의 값은 인자 텍스트의 내용이 있는 버퍼로 설정됩니다. 텍스트는 첫 번째 인자에 지정된 인코딩으로 인코딩됩니다.

PyArg_ParseTuple()은 필요한 크기의 버퍼를 할당하고, 인코딩된 데이터를 이 버퍼에 복사하고 새로 할당된 스토리지를 참조하도록 *buffer를 조정합니다. 호출자는 사용 후에 할당된 버퍼를 해제하기 위해 PyMem_Free()를 호출해야 합니다.

et (str, bytes 또는 bytearray) [const char *encoding, char **buffer]

바이트 문자열 객체를 다시 코딩하지 않고 통과시킨다는 점을 제외하면 es와 같습니다. 대신, 구현은 바이트 문자열 객체가 매개 변수로 전달된 인코딩을 사용한다고 가정합니다.

es# (str) [const char *encoding, char **buffer, int 또는 Py_ssize_t *buffer_length]

s#의 이 변형은 유니코드를 문자 버퍼로 인코딩하는 데 사용됩니다. es 포맷과 달리, 이 변형은 NUL 문자를 포함하는 입력 데이터를 허용합니다.

세 가지 인자가 필요합니다. 첫 번째는 입력으로만 사용되며, 인코딩 이름을 가리키는 NUL 종료 문자열로 const char*이거나, 'utf-8' 인코딩이 사용되도록 하는 NULL이어야 합니다. 명명된 인코딩이 파이썬에 알려지지 않았으면 예외가 발생합니다. 두 번째 인자는 char**여야 합니다; 참조하는 포인터의 값은 인자 텍스트의 내용이 있는 버퍼로 설정됩니다. 텍스트는 첫 번째 인자에 지정된 인코딩으로 인코딩됩니다. 세 번째 인자는 정수에 대한 포인터여야 합니다; 참조된 정수는 출력 버퍼의 바이트 수로 설정됩니다.

두 가지 작동 모드가 있습니다:

*buffer가 NULL 포인터를 가리키면, 함수는 필요한 크기의 버퍼를 할당하고, 이 버퍼로 인코딩된 데이터를 복사하고 *buffer를 새로 할당된 스토리지를 참조하도록 설정합니다. 호출자는 사용 후 할당된 버퍼를 해제하기 위해 PyMem_Free()를 호출해야 합니다.

*buffer가 NULL이 아닌 포인터를 가리키면 (이미 할당된 버퍼), PyArg_ParseTuple()은 이 위치를 버퍼로 사용하고 *buffer_length의 초깃값을 버퍼 크기로 해석합니다. 그런 다음 인코딩된 데이터를 버퍼에 복사하고 NUL 종료합니다. 버퍼가 충분히 크지 않으면, ValueError가 설정됩니다.

두 경우 모두, *buffer_length는 후행 NUL 바이트를 제외한 인코딩된 데이터의 길이로 설정됩니다.

et# (str, bytes 또는 bytearray) [const char *encoding, char **buffer, int 또는 Py_ssize_t *buffer_length]

바이트 문자열 객체를 다시 코딩하지 않고 통과시킨다는 점을 제외하면 es#와 같습니다. 대신, 구현은 바이트 문자열 객체가 매개 변수로 전달된 인코딩을 사용한다고 가정합니다.

숫자

b (int) [unsigned char]

음이 아닌 파이썬 정수를 부호 없는 작은 정수로 변환하고, C unsigned char에 저장합니다.

B (int) [unsigned char]

오버플로 검사 없이 파이썬 정수를 작은 정수로 변환하고, C unsigned char에 저장합니다.

h (int) [short int]

파이썬 정수를 C short int로 변환합니다.

H (int) [unsigned short int]

오버플로 검사 없이, 파이썬 정수를 C unsigned short int로 변환합니다.

i (int) [int]

파이썬 정수를 일반 C int로 변환합니다.

I (int) [unsigned int]

오버플로 검사 없이, 파이썬 정수를 C unsigned int로 변환합니다.

l (int) [long int]

파이썬 정수를 C long int로 변환합니다.

k (int) [unsigned long]

오버플로 검사 없이 파이썬 정수를 C unsigned long으로 변환합니다.

L (int) [long long]

파이썬 정수를 C long long으로 변환합니다.

K (int) [unsigned long long]

오버플로 검사 없이 파이썬 정수를 C unsigned long long으로 변환합니다.

n (int) [Py_ssize_t]

파이썬 정수를 C Py_ssize_t로 변환합니다.

c (길이 1의 bytes 또는 bytearray) [char]

길이가 1인 bytes나 bytearray 객체로 표시된, 파이썬 바이트를 C char로 변환합니다.

버전 3.3에서 변경: bytearray 객체를 허용합니다.

C (길이 1의 str) [int]

길이가 1인 str 객체로 표시된, 파이썬 문자를 C int로 변환합니다.

f (float) [float]

파이썬 부동 소수점 숫자를 C float로 변환합니다.

d (float) [double]

파이썬 부동 소수점 숫자를 C double로 변환합니다.

D (complex) [Py_complex]

파이썬 복소수를 C Py_complex 구조체로 변환합니다.

기타 객체

O (object) [PyObject *]

C 객체 포인터에 파이썬 객체를 (변환 없이) 저장합니다. 따라서 C 프로그램은 전달된 실제 객체를 받습니다. 객체의 참조 횟수는 증가하지 않습니다. 저장된 포인터는 NULL이 아닙니다.

O! (object) [typeobject, PyObject *]

C 객체 포인터에 파이썬 객체를 저장합니다. 이것은 O와 유사하지만, 두 개의 C 인자를 취합니다: 첫 번째는 파이썬 형 객체의 주소이고, 두 번째는 객체 포인터가 저장되는 (PyObject* 형의) C 변수의 주소입니다. 파이썬 객체가 필요한 형이 아니면, TypeError가 발생합니다.

O& (object) [converter, anything]

converter 함수를 통해 파이썬 객체를 C 변수로 변환합니다. 두 개의 인자를 취합니다: 첫 번째는 함수이고, 두 번째는 void *로 변환된, (임의의 형의) C 변수의 주소입니다. converter 함수는 다음과 같이 호출됩니다:

status = converter(object, address);

여기서 object는 변환할 파이썬 객체이고 address는 PyArg_Parse*() 함수에 전달된 void* 인자입니다. 반환된 status는 성공적인 변환의 경우 1이고 변환에 실패한 경우 0이어야 합니다. 변환이 실패하면, converter 함수는 예외를 발생시키고 address의 내용을 수정하지 않은 상태로 두어야 합니다.

converter가 Py_CLEANUP_SUPPORTED를 반환하면, 인자 구문 분석이 결국 실패하면 두 번째로 호출되어 변환기에 이미 할당된 메모리를 해제할 기회를 제공할 수 있습니다. 이 두 번째 호출에서, object 매개 변수는 NULL이 됩니다; address는 원래 호출과 같은 값을 갖습니다.

버전 3.1에서 변경: Py_CLEANUP_SUPPORTED가 추가되었습니다.

p (bool) [int]

전달된 값의 논리값을 테스트(불리언 predicate)하고 결과를 동등한 C 참/거짓 정숫값으로 변환합니다. 표현식이 참이면 int를 1로, 거짓이면 0으로 설정합니다. 모든 유효한 파이썬 값을 허용합니다. 파이썬이 논리값을 테스트하는 방법에 대한 자세한 내용은 논리값 검사를 참조하십시오.

버전 3.3에 추가.

(items) (tuple) [matching-items]

객체는 길이가 items에 있는 포맷 단위의 수인 파이썬 시퀀스여야 합니다. C 인자들은 items의 개별 포맷 단위에 대응해야 합니다. 시퀀스의 포맷 단위는 중첩될 수 있습니다.

"긴" 정수(값이 플랫폼의 LONG_MAX를 초과하는 정수)를 전달할 수 있지만 적절한 범위 검사가 수행되지 않습니다 --- 수신 필드가 값을 수신하기에 너무 작을 때 최상위 비트가 자동으로 잘립니다 (실제로, 이 의미는 C의 다운 캐스트에서 물려받았습니다 --- 여러분의 경험은 다를 수 있습니다).

몇 가지 다른 문자는 포맷 문자열에서 의미가 있습니다. 중첩된 괄호 안에서는 나타날 수 없습니다. 그들은:

|

파이썬 인자 리스트의 나머지 인자가 선택 사항임을 나타냅니다. 선택적 인자에 해당하는 C 변수는 기본값으로 초기화되어야 합니다 --- 선택적 인자가 지정되지 않을 때, PyArg_ParseTuple()은 해당 C 변수의 내용을 건드리지 않습니다.

$

PyArg_ParseTupleAndKeywords() 전용: 파이썬 인자 리스트의 나머지 인자가 키워드 전용임을 나타냅니다. 현재, 모든 키워드 전용 인자는 선택적 인자여야 하므로, |는 항상 포맷 문자열에서 $ 앞에 지정되어야 합니다.

버전 3.3에 추가.

:

포맷 단위 리스트는 여기에서 끝납니다; 콜론 뒤의 문자열은 에러 메시지에서 함수 이름으로 사용됩니다 (PyArg_ParseTuple()이 발생시키는 예외의 "연관된 값").

;

포맷 단위 리스트는 여기에서 끝납니다; 세미콜론 뒤의 문자열은 기본 에러 메시지의 에러 메시지 대신 에러 메시지로 사용됩니다. :와 ;는 서로를 배제합니다.

호출자에게 제공되는 모든 파이썬 객체 참조는 빌려온(borrowed) 참조임에 유의하십시오; 참조 횟수를 줄이지 마십시오!

이러한 함수에 전달되는 추가 인자는 포맷 문자열에 의해 형이 결정되는 변수의 주소여야 합니다; 이들은 입력 튜플의 값을 저장하는 데 사용됩니다. 위의 포맷 단위 리스트에서 설명된 대로, 이러한 매개 변수가 입력값으로 사용되는 몇 가지 경우가 있습니다; 이 경우 해당 포맷 단위에 대해 지정된 것과 일치해야 합니다.

변환이 성공하려면, arg 객체가 포맷과 일치해야 하며 포맷이 소진되어야 합니다. 성공하면, PyArg_Parse*() 함수는 참을 반환하고, 그렇지 않으면 거짓을 반환하고 적절한 예외를 발생시킵니다. 포맷 단위 중 하나의 변환 실패로 인해 PyArg_Parse*() 함수가 실패하면, 해당 주소의 변수와 그 뒤에 오는 포맷 단위는 건드리지 않습니다.

API 함수

int PyArg_ParseTuple(PyObject *args, const char *format, ...)

위치 매개 변수만 지역 변수로 취하는 함수의 매개 변수를 구문 분석합니다. 성공하면 참을 반환합니다; 실패하면, 거짓을 반환하고 적절한 예외를 발생시킵니다.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

가변 개수의 인자가 아닌 va_list를 받아들인다는 점을 제외하면, PyArg_ParseTuple()과 동일합니다.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

위치와 키워드 매개 변수를 모두 지역 변수로 취하는 함수의 매개 변수를 구문 분석합니다. keywords 인자는 키워드 매개 변수 이름의 NULL-종료 배열입니다. 빈 이름은 위치-전용 매개 변수를 나타냅니다. 성공하면 참을 반환합니다; 실패하면, 거짓을 반환하고 적절한 예외를 발생시킵니다.

버전 3.6에서 변경: 위치-전용 매개 변수에 대한 지원이 추가되었습니다.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

가변 개수의 인자가 아닌 va_list를 받아들인다는 점을 제외하면, PyArg_ParseTupleAndKeywords() 와 동일합니다.

int PyArg_ValidateKeywordArguments(PyObject *)

키워드 인자 딕셔너리의 키가 문자열인지 확인합니다. PyArg_ParseTupleAndKeywords() 가 사용되지 않는 경우에만 필요합니다, 여기서는 이미 이 검사를 수행하기 때문입니다.

버전 3.2에 추가.

int PyArg_Parse(PyObject *args, const char *format, ...)

"이전 스타일" 함수의 인자 리스트를 분해하는 데 사용되는 함수 --- 이들은 파이썬 3에서 제거된 METH_OLDARGS 매개 변수 구문 분석 메서드를 사용하는 함수입니다. 새 코드에서 매개 변수 구문 분석에 사용하는 것은 권장되지 않고, 표준 인터프리터에 있는 대부분의 코드는 더는 이런 목적으로 사용하지 않도록 수정되었습니다. 그러나, 다른 튜플을 분해하는 편리한 방법으로 남아 있으며, 그런 목적으로 계속 사용할 수 있습니다.

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

인자 형을 지정하기 위해 포맷 문자열을 사용하지 않는 더 간단한 형식의 매개 변수 조회. 이 방법으로 매개 변수를 꺼내는 함수는 함수나 메서드 테이블에서 METH_VARARGS로 선언되어야 합니다. 실제 매개 변수를 포함하는 튜플은 args로 전달되어야 합니다; 이것은 실제로 튜플이어야 합니다. 튜플의 길이는 min 이상 max 이하이어야 합니다; min과 max는 같을 수 있습니다. 추가 인자는 함수에 전달되어야 하며, 각 인자는 PyObject* 변수에 대한 포인터여야 합니다; 이들은 args의 값으로 채워집니다; 빌린 참조가 포함됩니다. args에서 제공하지 않는 선택적 매개 변수에 해당하는 변수는 채워지지 않습니다; 이것들은 호출자에 의해 초기화되어야 합니다. 이 함수는 성공하면 참을 반환하고 args가 튜플이 아니거나, 잘못된 수의 요소를 포함하면 거짓을 반환합니다; 실패하면 예외가 설정됩니다.

다음은 이 함수 사용의 예입니다, 약한 참조를 위한 _weakref 도우미 모듈의 소스에서 가져왔습니다:

static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        result = PyWeakref_NewRef(object, callback);
    }
    return result;
}

이 예제에서 PyArg_UnpackTuple()에 대한 호출은 PyArg_ParseTuple()에 대한 다음 호출과 전적으로 동등합니다:

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

값 구축

PyObject* Py_BuildValue(const char *format, ...)

Return value: New reference.

PyArg_Parse*() 함수 계열에서 받아들이는 것과 유사한 포맷 문자열과 값 시퀀스를 기반으로 새 값을 만듭니다. 값을 반환하거나 에러가 발생하면 NULL을 반환합니다; NULL이 반환되면 예외가 발생합니다.

Py_BuildValue()는 항상 튜플을 구축하지는 않습니다. 포맷 문자열에 둘 이상의 포맷 단위가 포함되었을 때만 튜플을 구축합니다. 포맷 문자열이 비어 있으면, None을 반환합니다; 정확히 하나의 포맷 단위를 포함하면, 해당 포맷 단위가 기술하는 객체가 무엇이건 반환합니다. 크기가 0이나 1인 튜플을 반환하도록 하려면, 포맷 문자열을 괄호로 묶으십시오.

s와 s# 포맷의 경우처럼, 메모리 버퍼가 데이터를 빌드 객체에 제공하기 위해 매개 변수로 전달될 때, 필요한 데이터가 복사됩니다. 호출자가 제공하는 버퍼는 Py_BuildValue()가 만든 객체에 의해 참조되지 않습니다. 즉, 여러분의 코드가 malloc()을 호출하고 할당된 메모리를 Py_BuildValue()에 전달하면, 인단 Py_BuildValue()가 반환되면 여러분이 코드가 해당 메모리에 대해 free()를 호출해야 합니다.

다음 설명에서, 인용된 형식은 포맷 단위입니다; (둥근) 괄호 안의 항목은 포맷 단위가 반환할 파이썬 객체 형입니다; [대괄호] 안의 항목은 전달할 C 값의 형입니다.

문자 스페이스, 탭, 콜론 및 쉼표는 포맷 문자열에서 무시됩니다 (하지만 s#와 같은 포맷 단위 내에서는 아닙니다). 이것은 긴 포맷 문자열을 좀 더 읽기 쉽게 만드는 데 사용할 수 있습니다.

s (str 또는 None) [const char *]

'utf-8' 인코딩을 사용하여 널-종료 C 문자열을 파이썬 str 객체로 변환합니다. C 문자열 포인터가 NULL이면, None이 사용됩니다.

s# (str 또는 None) [const char *, int or Py_ssize_t]

'utf-8' 인코딩을 사용하여 C 문자열과 그 길이를 파이썬 str 객체로 변환합니다. C 문자열 포인터가 NULL이면, 길이가 무시되고 None이 반환됩니다.

y (bytes) [const char *]

이것은 C 문자열을 파이썬 bytes 객체로 변환합니다. C 문자열 포인터가 NULL이면, None이 반환됩니다.

y# (bytes) [const char *, int 또는 Py_ssize_t]

이것은 C 문자열과 그 길이를 파이썬 객체로 변환합니다. C 문자열 포인터가 NULL이면, None이 반환됩니다.

z (str 또는 None) [const char *]

s와 같습니다.

z# (str 또는 None) [const char *, int 또는 Py_ssize_t]

s#과 같습니다.

u (str) [const wchar_t *]

유니코드 (UTF-16 또는 UCS-4) 데이터의 널-종료 wchar_t 버퍼를 파이썬 유니코드 객체로 변환합니다. 유니코드 버퍼 포인터가 NULL이면, None이 반환됩니다.

u# (str) [const wchar_t *, int 또는 Py_ssize_t]

유니코드 (UTF-16 또는 UCS-4) 데이터 버퍼와 그 길이를 파이썬 유니코드 객체로 변환합니다. 유니코드 버퍼 포인터가 NULL이면, 길이가 무시되고 None이 반환됩니다.

U (str 또는 None) [const char *]

s와 같습니다.

U# (str 또는 None) [const char *, int 또는 Py_ssize_t]

s#과 같습니다.

i (int) [int]

일반 C int를 파이썬 정수 객체로 변환합니다.

b (int) [char]

일반 C char을 파이썬 정수 객체로 변환합니다.

h (int) [short int]

일반 C short int를 파이썬 정수 객체로 변환합니다.

l (int) [long int]

C long int를 파이썬 정수 객체로 변환합니다.

B (int) [unsigned char]

C unsigned char을 파이썬 정수 객체로 변환합니다.

H (int) [unsigned short int]

C unsigned short int를 파이썬 정수 객체로 변환합니다.

I (int) [unsigned int]

C unsigned int를 파이썬 정수 객체로 변환합니다.

k (int) [unsigned long]

C unsigned long을 파이썬 정수 객체로 변환합니다.

L (int) [long long]

C long long을 파이썬 정수 객체로 변환합니다.

K (int) [unsigned long long]

C unsigned long long을 파이썬 정수 객체로 변환합니다.

n (int) [Py_ssize_t]

C Py_ssize_t를 파이썬 정수로 변환합니다.

c (길이 1의 bytes) [char]

바이트를 나타내는 C int를 길이 1의 파이썬 bytes 객체로 변환합니다.

C (길이 1의 str) [int]

문자를 나타내는 C int를 길이 1의 파이썬 str 객체로 변환합니다.

d (float) [double]

C double을 파이썬 부동 소수점 숫자로 변환합니다.

f (float) [float]

C float를 파이썬 부동 소수점 숫자로 변환합니다.

D (complex) [Py_complex *]

C Py_complex 구조체를 파이썬 복소수로 변환합니다.

O (object) [PyObject *]

파이썬 객체를 손대지 않고 전달합니다 (1 증가하는 참조 횟수는 예외입니다). 전달된 객체가 NULL 포인터면, 인자를 생성하는 호출이 에러를 발견하고 예외를 설정했기 때문으로 간주합니다. 따라서, Py_BuildValue()는 NULL을 반환하지만, 예외를 발생시키지 않습니다. 아직 예외가 발생하지 않았으면, SystemError가 설정됩니다.

S (object) [PyObject *]

O와 같습니다.

N (object) [PyObject *]

O와 같지만, 객체의 참조 횟수를 증가시키지 않습니다. 인자 리스트에서 객체 생성자를 호출하여 객체를 만들 때 유용합니다.

O& (object) [converter, anything]

converter 함수를 통해 anything을 파이썬 객체로 변환합니다. 함수는 인자로 anything(void*와 호환되어야 합니다)을 사용하여 호출되며 "새" 파이썬 객체를 반환하거나, 에러가 발생하면 NULL을 반환해야 합니다.

(items) (tuple) [matching-items]

C값의 시퀀스를 항목 수가 같은 파이썬 튜플로 변환합니다.

[items] (list) [matching-items]

C값의 시퀀스를 항목 수가 같은 파이썬 리스트로 변환합니다.

{items} (dict) [matching-items]

C값의 시퀀스를 파이썬 딕셔너리로 변환합니다. 연속된 C 값의 각 쌍은 딕셔너리에 하나의 항목을 추가하여, 각각 키와 값으로 사용됩니다.

포맷 문자열에 에러가 있으면, SystemError 예외가 설정되고 NULL이 반환됩니다.

PyObject* Py_VaBuildValue(const char *format, va_list vargs)

Return value: New reference.

가변 개수의 인자가 아닌 va_list를 받아들인다는 점을 제외하면, Py_BuildValue()와 동일합니다.