Argument Clinic¶

author:: Larry Hastings

Argument Clinic은 CPython C 파일용 전처리기입니다. 인트로스펙션 시그니처를 제공하고 CPython 내장 함수, 모듈 수준 함수 및 클래스 메서드의 인자 구문 분석을 위한 고성능 맞춤형 상용구 코드를 생성하기 위해 PEP 436과 함께 Python 3.4에서 도입되었습니다. 이 문서는 네 개의 주요 절로 나뉩니다:

배경에서는 Argument Clinic의 기본 개념과 목표를 설명합니다.
참조에서는 명령줄 인터페이스와 Argument Clinic 용어를 설명합니다.
튜토리얼에서는 기존 C 함수를 Argument Clinic에 맞게 조정하는 데 필요한 모든 단계를 안내합니다.
방법 안내서에서는 특정 작업을 처리하는 방법을 자세히 설명합니다.

참고

Argument Clinic은 CPython 내부 전용으로 간주됩니다. CPython 외부의 파일에서 사용하는 것은 지원되지 않으며, 향후 버전의 하위 호환성도 보장되지 않습니다. 다시 말해, CPython용 외부 C 확장을 유지 관리한다면 자체 코드에서 Argument Clinic을 자유롭게 시험해 볼 수 있습니다. 그러나 다음 CPython 버전에 포함되는 Argument Clinic 버전은 완전히 호환되지 않을 수도 있으며 모든 코드를 망가뜨릴 수도 있습니다.

배경¶

기본 개념¶

관련 명령줄 인터페이스나 make clinic을 통해 파일에서 Argument Clinic을 실행하면 입력 파일을 훑으며 start lines을 찾습니다:

/*[clinic input]

하나를 찾으면 end line까지의 모든 내용을 읽습니다:

[clinic start generated code]*/

이 두 줄 사이의 모든 내용은 Argument Clinic input입니다. Argument Clinic이 입력을 구문 분석하면 output을 생성합니다. 출력은 입력 바로 뒤의 C 파일에 다시 작성되며, 그 뒤에는 checksum line이 이어집니다. 관련 start line과 checksum line을 포함한 이 모든 줄을 통틀어 Argument Clinic block이라고 합니다:

/*[clinic input]
... clinic input goes here ...
[clinic start generated code]*/
... clinic output goes here ...
/*[clinic end generated code: ...]*/

같은 파일에서 Argument Clinic을 두 번째로 실행하면 이전 output을 버리고 새로운 checksum line과 함께 새 출력을 작성합니다. 관련 input이 변경되지 않았다면 출력도 변경되지 않습니다.

참고

변경 사항은 향후 Argument Clinic 실행 시 모두 사라지므로 Argument Clinic 블록의 출력을 절대로 수정해서는 안 됩니다. Argument Clinic은 출력 체크섬 불일치를 감지하고 올바른 출력을 다시 생성합니다. 생성된 출력이 만족스럽지 않다면 원하는 출력이 생성될 때까지 입력을 변경해야 합니다.

참조¶

용어¶

시작 줄¶
start line¶: /*[clinic input] 줄입니다. 이 줄은 Argument Clinic 입력의 시작을 나타냅니다. 시작 줄은 C 블록 주석을 연다는 점에 유의하십시오.
종료 줄¶
end line¶: [clinic start generated code]*/ 줄입니다. 종료 줄은 Argument Clinic 입력의 끝을 표시하는 동시에 Argument Clinic 출력의 시작을 표시하므로, 텍스트는 “clinic start start generated code”입니다. 종료 줄은 시작 줄이 연 C 블록 주석을 닫는다는 점에 유의하십시오.
체크섬¶
checksum¶: 고유한 입력들과 출력들을 구별하기 위한 해시입니다.
체크섬 줄¶
checksum line¶: /*[clinic end generated code: ...]*/ 형태의 줄입니다. 세 개의 점은 입력에서 생성된 체크섬과 출력에서 생성된 체크섬으로 대체됩니다. 체크섬 줄은 Argument Clinic이 생성한 코드의 끝을 표시하며, Argument Clinic이 출력을 다시 생성해야 하는지 판단하는 데 사용됩니다.
입력¶
input¶: 관련 시작 줄과 종료 줄 사이의 텍스트입니다. 시작 줄과 종료 줄은 C 블록 주석을 열고 닫으므로, 입력은 동일한 C 블록 주석의 일부라는 점에 유의하십시오.
출력¶
output¶: 관련 종료 줄과 체크섬 줄 사이의 텍스트입니다.
블록¶
block¶: 관련 시작 줄부터 체크섬 줄까지 양 끝을 포함한 모든 텍스트입니다.

명령줄 인터페이스¶

Argument Clinic CLI(명령줄 인터페이스)는 일반적으로 다음과 같이 단일 소스 파일을 처리하는 데 사용됩니다.

$ python3 ./Tools/clinic/clinic.py foo.c

CLI는 다음 옵션을 지원합니다.

-h, --help¶: CLI 사용법을 출력하십시오.

-f, --force¶: 출력을 강제로 다시 생성하십시오.

-o, --output OUTPUT¶: 파일 출력을 OUTPUT으로 리디렉션하십시오.

-v, --verbose¶: 상세 출력 모드를 활성화하십시오.

--converters¶: 지원되는 모든 컨버터와 반환 컨버터의 목록을 출력하십시오.

--make¶: 관련된 모든 파일을 대상으로 실행하려면 --srcdir을 순회하십시오.

--srcdir SRCDIR¶: 관련 --make 모드에서 순회할 디렉터리 트리입니다.

--exclude EXCLUDE¶: 관련 --make 모드에서 제외할 파일입니다. 이 옵션은 여러 번 지정할 수 있습니다.

--limited¶: 생성된 C 코드에서 인자를 파싱하려면 제한 API를 사용하십시오. 관련 Limited C API를 사용하는 방법를 참고하십시오.

FILE ...¶: 처리할 파일 목록입니다.

Argument Clinic 확장용 클래스¶

class clinic.CConverter¶

모든 변환기의 베이스 클래스입니다. 이 클래스를 서브클래싱하는 방법은 사용자 정의 변환기를 작성하는 방법를 참조하십시오.

type¶: 이 변수에 사용할 C 타입입니다. type은 타입을 지정하는 Python 문자열이어야 하며, 예를 들면 'int'입니다. 포인터 타입인 경우 타입 문자열은 ' *'로 끝나야 합니다.

default¶: Python 값으로 나타낸 이 매개변수의 Python 기본값입니다. 또는 기본값이 없으면 매직 값 unspecified입니다.

py_default¶: Python 코드에 나타나야 하는 default의 문자열 형식입니다. 또는 기본값이 없으면 None입니다.

c_default¶: C 코드에 나타나야 하는 default의 문자열 형식입니다. 또는 기본값이 없으면 None입니다.

c_ignored_default¶: 기본값이 없을 때 C 변수를 초기화하는 데 사용되는 기본값이지만, 기본값을 지정하지 않으면 “초기화되지 않은 변수” 경고가 발생할 수 있습니다. 옵션 그룹을 사용할 때 이런 일이 쉽게 발생할 수 있습니다. 올바르게 작성된 코드에서는 실제로 이 값을 사용하지 않지만, 변수는 impl에 전달되며 C 컴파일러는 초기화되지 않은 값의 “사용”에 관해 경고합니다. 이 값은 항상 비어 있지 않은 문자열이어야 합니다.

converter¶: 문자열로 나타낸 C 변환기 함수의 이름입니다.

impl_by_reference¶: 불리언 값입니다. 참이면 Argument Clinic은 변수를 impl 함수에 전달할 때 변수 이름 앞에 &를 추가합니다.

parse_by_reference¶: 불리언 값입니다. 참이면 Argument Clinic은 변수를 PyArg_ParseTuple()에 전달할 때 변수 이름 앞에 &를 추가합니다.