인자 구문 분석과 값 구축¶

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

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

인자 구문 분석¶

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

문자열과 버퍼¶

참고

Python 3.12 및 이전 버전에서는, 모든 # 포맷 변형(s#, y# 등)을 사용하려면 <code >Python.h</code>를 포함하기 전에 PY_SSIZE_T_CLEAN 매크로를 정의해야 합니다. 이는 Python 3.13 이상에서는 필요하지 않습니다.

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

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

문자와 버퍼가 C로 변환되는 세 가지 방법이 있습니다:

y* 와 s* 같은 포맷은 Py_buffer 구조체를 채웁니다. 이는 하부 버퍼를 잠가서, 호출자가 Py_BEGIN_ALLOW_THREADS 블록 내에서도 가변 데이터의 크기가 조정되거나 파괴될 위험 없이 이후에 버퍼를 사용할 수 있습니다. 결과적으로, 데이터 처리를 마친 후 (또는 모든 조기 중단의 경우) PyBuffer_Release()를 호출해야 합니다.
es, es#, et 및 et# 포맷은 결과 버퍼를 할당합니다. 데이터 처리를 마친 후 (또는 예상치 못한 중간 종료의 경우) :c:func:`PyMem_Free`를 호출해야 합니다.
다른 포맷은 str 또는 읽기 전용 bytes-like object`와 같은 :class:`bytes`를 취하고, 그 버퍼에 대한 ``const char *` 포인터를 제공합니다. 이 경우 버퍼는 “빌려집니다”: 해당 Python 객체에 의해 관리되고, 이 객체의 수명을 공유합니다. 여러분이 직접 메모리를 해제할 필요가 없습니다.

기본 버퍼가 안전하게 빌려질 수 있도록 보장하려면, 객체의 PyBufferProcs.bf_releasebuffer 필드가 NULL 이어야 합니다. 이렇게 하면 bytearray 와 같은 일반적인 가변 객체뿐만 아니라, bytes 의 memoryview 와 같은 일부 읽기 전용 객체도 허용하지 않습니다.

이 bf_releasebuffer 요구사항 외에도, 입력 객체가 불변인지(예: 쓰기 가능한 버퍼를 요청할 경우 지킬 수 있는지, 또는 다른 스레드가 데이터를 변경할 수 있는지)를 확인할 검사가 없습니다.

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 *, 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 *, Py_ssize_t]

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

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

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

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

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

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

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

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

S (bytes) [PyBytesObject *]

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

Y (bytearray) [PyByteArrayObject *]

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

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, 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, Py_ssize_t *buffer_length]

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

버전 3.12에서 변경: 레거시 Py_UNICODE* 표현을 사용했기 때문에 u, u#, Z, 및 Z# 은 제거되었습니다.

숫자¶

이 포맷들은 Python 숫자 또는 단일 문자들을 C 숫자로 표현할 수 있게 합니다. int, float 또는 complex`가 필요한 포맷들은 해당 Python 객체를 필요한 타입으로 변환하기 위해 :meth:`~object.__index__, __float__() 또는 :meth:`~object.__complex__`와 같은 해당 특수 메서드를 사용할 수도 있습니다.

부호 있는 정수 포맷의 경우, 값이 C 타입 범위를 벗어나면 :exc:`OverflowError`가 발생합니다. 부호 없는 정수 포맷의 경우, 수신 필드가 값을 받기에 너무 작으면 가장 중요한 비트들이 조용히 잘리고, 값이 C 타입의 최대값보다 크거나 같은 크기의 해당 부호 있는 정수 타입의 최소값보다 작은 경우 :exc:`DeprecationWarning`이 발생합니다.

b (int) [unsigned char]: 음이 아닌 파이썬 정수를 부호 없는 작은 정수로 변환하고, C unsigned char에 저장합니다.
B (int) [unsigned char]: 파이썬 정수를 오버플로 검사 없이 작은 정수로 변환하여 C 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\으로 변환합니다.

버전 3.14에서 변경: 사용 가능하다면 :meth:`~object.__index__`를 사용합니다.
L (int) [long long]: 파이썬 정수를 C long long으로 변환합니다.
K (int) [unsigned long long]: 파이썬 정수를 C unsigned long long\으로 변환합니다.

버전 3.14에서 변경: 사용 가능하다면 :meth:`~object.__index__`를 사용합니다.
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 구조체로 변환합니다.

버전 3.15부터 폐지됨: B, H, I, k 및 K 와 같은 부호 없는 정수 포맷의 경우, 값이 C 타입의 최대 범위를 초과하거나, 같은 크기의 해당 부호 있는 정수 타입의 최소 범위를 미만일 때 DeprecationWarning 이 발생합니다.

기타 객체¶

O (object) [PyObject *]: C 객체 포인터에 파이썬 객체를 (변환 없이) 저장합니다. 따라서 C 프로그램은 전달된 실제 객체를 받습니다. 객체에 대한 새로운 강한 참조는 생성되지 않습니다 (즉, 객체의 참조 횟수는 증가하지 않습니다). 저장된 포인터는 NULL이 아닙니다.
O! (object) [typeobject, PyObject *]: C 객체 포인터에 파이썬 객체를 저장합니다. 이것은 O와 유사하지만, 두 개의 C 인자를 취합니다: 첫 번째는 파이썬 형 객체의 주소이고, 두 번째는 객체 포인터가 저장되는 (PyObject* 형의) C 변수의 주소입니다. 파이썬 객체가 필요한 형이 아니면, TypeError가 발생합니다.

O& (object) [converter, address]

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는 원래 호출과 같은 값을 갖습니다.

변환기 예시: PyUnicode_FSConverter() 및 PyUnicode_FSDecoder().

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

p (bool) [int]

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

Added in version 3.3.

(items) (시퀀스) [matching-items]

객체는 items 에 있는 포맷 단위의 개수와 길이가 일치하는 파이썬 시퀀스여야 합니다(str, bytes 또는 bytearray 제외). C 인자들은 items 의 개별 포맷 단위에 대응해야 합니다. 시퀀스에 대한 포맷 단위는 중첩될 수 있습니다.

If items contains format units which store a borrowed buffer (s, s#, z, z#, y, or y#) or a borrowed reference (S, Y, U, O, or O!), the object must be a Python tuple. The converter for the O& format unit in items must not store a borrowed buffer or a borrowed reference.

버전 3.14에서 변경: str 및 bytearray 객체는 더 이상 시퀀스로 받아들여지지 않습니다.

버전 3.14부터 폐지됨: items 가 빌린 버퍼나 빌린 참조를 저장하는 포맷 단위를 포함하는 경우, 비-튜플 시퀀스는 사용이 중단됩니다.

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

|: 파이썬 인자 리스트의 나머지 인자가 선택 사항임을 나타냅니다. 선택적 인자에 해당하는 C 변수는 기본값으로 초기화되어야 합니다 — 선택적 인자가 지정되지 않을 때, PyArg_ParseTuple()은 해당 C 변수의 내용을 건드리지 않습니다.
$: PyArg_ParseTupleAndKeywords() 전용: 파이썬 인자 리스트의 나머지 인자가 키워드 전용임을 나타냅니다. 현재, 모든 키워드 전용 인자는 선택적 인자여야 하므로, |는 항상 포맷 문자열에서 $ 앞에 지정되어야 합니다.

Added in version 3.3.
:: 포맷 단위 리스트는 여기에서 끝납니다; 콜론 뒤의 문자열은 에러 메시지에서 함수 이름으로 사용됩니다 (PyArg_ParseTuple()이 발생시키는 예외의 “연관된 값”).
;: 포맷 단위 리스트는 여기에서 끝납니다; 세미콜론 뒤의 문자열은 기본 에러 메시지의 에러 메시지 대신 에러 메시지로 사용됩니다. :와 ;는 서로를 배제합니다.

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

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

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

API 함수¶

int PyArg_ParseTuple(PyObject *args, const char *format, ...)¶: 상의 안정 ABI.
위치 매개 변수만 지역 변수로 취하는 함수의 매개 변수를 구문 분석합니다. 성공하면 참을 반환합니다; 실패하면, 거짓을 반환하고 적절한 예외를 발생시킵니다.

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)¶: 상의 안정 ABI.
가변 개수의 인자가 아닌 va_list를 받아들인다는 점을 제외하면, PyArg_ParseTuple()과 동일합니다.

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)¶: 상의 안정 ABI.
위치와 키워드 매개 변수를 모두 지역 변수로 취하는 함수의 매개 변수를 구문 분석합니다. keywords 인자는 널-종료된 ASCII 나 UTF-8 인코딩된 C 문자열로 지정된 키워드 매개 변수 이름의 NULL-종료 배열입니다. 빈 이름은 위치-전용 매개 변수를 나타냅니다. 성공하면 참을 반환합니다; 실패하면, 거짓을 반환하고 적절한 예외를 발생시킵니다.

참고

keywords 매개 변수 선언은 C에서 char *const* 이고 C++에서 const char *const* 입니다. 이는 PY_CXX_CONST 매크로를 사용하여 재정의할 수 있습니다.

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

버전 3.13에서 변경: keywords 매개 변수가 이제 C에서 char *const* 이고 C++에서 const char *const* 형식을 가집니다. 이는 기존의 char** 형식 대신입니다. 비-ASCII 키워드 매개 변수 이름에 대한 지원이 추가되었습니다.

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)¶: 상의 안정 ABI.
가변 개수의 인자가 아닌 va_list를 받아들인다는 점을 제외하면, PyArg_ParseTupleAndKeywords() 와 동일합니다.

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

Added in version 3.2.

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

상의 안정 ABI.

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

예제:

// METH_O 호출 규칙을 사용하는 함수
static PyObject*
my_function(PyObject *module, PyObject *arg)
{
    int value;
    if (!PyArg_Parse(arg, "i:my_function", &value)) {
        return NULL;
    }
    // ... value 를 사용합니다 ...
}

int PyArg_ParseArray(PyObject *const *args, Py_ssize_t nargs, const char *format, ...)¶: 인수만 배열 매개 변수를 받는 함수의 매개 변수들을 로컬 변수로 파싱합니다(즉, METH_FASTCALL 호출 규약을 사용하는 함수). 성공 시 true를 반환하고, 실패 시 false를 반환하고 적절한 예외를 발생시킵니다.

Added in version 3.15.

int PyArg_ParseArrayAndKeywords(PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames, const char *format, const char *const *kwlist, ...)¶: 인수가 배열 및 키워드 매개 변수를 모두 받는 함수의 매개 변수들을 로컬 변수로 파싱합니다(즉, METH_FASTCALL | METH_KEYWORDS 호출 규약을 사용하는 함수). 성공 시 true를 반환하고, 실패 시 false를 반환하고 적절한 예외를 발생시킵니다.

Added in version 3.15.

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

상의 안정 ABI.

인자 형을 지정하기 위해 포맷 문자열을 사용하지 않는 더 간단한 형식의 매개 변수 조회. 이 방법으로 매개 변수를 꺼내는 함수는 함수나 메서드 테이블에서 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)

PY_CXX_CONST¶: The value to be inserted, if any, before char *const* in the keywords parameter declaration of PyArg_ParseTupleAndKeywords() and PyArg_VaParseTupleAndKeywords(). Default empty for C and const for C++ (const char *const*). To override, define it to the desired value before including Python.h.

Added in version 3.13.

값 구축¶

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

반환값: 새 참조. 상의 안정 ABI.

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 *, Py_ssize_t]: 'utf-8' 인코딩을 사용하여 C 문자열과 그 길이를 파이썬 str 객체로 변환합니다. C 문자열 포인터가 NULL이면, 길이가 무시되고 None이 반환됩니다.
y (bytes) [const char *]: 이것은 C 문자열을 파이썬 bytes 객체로 변환합니다. C 문자열 포인터가 NULL이면, None이 반환됩니다.
y# (bytes) [const char *, Py_ssize_t]: 이것은 C 문자열과 그 길이를 파이썬 객체로 변환합니다. C 문자열 포인터가 NULL이면, None이 반환됩니다.
z (str 또는 None) [const char *]: s와 같습니다.
z# (str 또는 None) [const char *, Py_ssize_t]: s#과 같습니다.
u (str) [const wchar_t *]: 유니코드 (UTF-16 또는 UCS-4) 데이터의 널-종료 wchar_t 버퍼를 파이썬 유니코드 객체로 변환합니다. 유니코드 버퍼 포인터가 NULL이면, None이 반환됩니다.
u# (str) [const wchar_t *, Py_ssize_t]: 유니코드 (UTF-16 또는 UCS-4) 데이터 버퍼와 그 길이를 파이썬 유니코드 객체로 변환합니다. 유니코드 버퍼 포인터가 NULL이면, 길이가 무시되고 None이 반환됩니다.
U (str 또는 None) [const char *]: s와 같습니다.
U# (str 또는 None) [const char *, 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를 파이썬 정수로 변환합니다.

p (bool) [int]

C int\를 Python bool 객체로 변환합니다.

이 형식은 int 인수가 필요하다는 점에 유의하십시오. C의 대부분 다른 컨텍스트와 달리, 가변 인수는 자동으로 적절한 유형으로 강제 변환되지 않습니다. (x) ? 1 : 0 또는 !!x``를 사용하여 다른 유형(예: 포인터 또는 float)을 적절한 ``int 값으로 변환할 수 있습니다.

Added in version 3.14.

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)¶: 반환값: 새 참조. 상의 안정 ABI.
가변 개수의 인자가 아닌 va_list를 받아들인다는 점을 제외하면, Py_BuildValue()와 동일합니다.