인자 구문 분석과 값 구축
************************

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

설명된 이러한 함수 중 처음 세 개인 "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]
   전달된 값의 논리값을 테스트(불리언 **p**redicate)하고 결과를 동등한
   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()"와 동일합니다.
