Argument Clinic¶

author:: Larry Hastings

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

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

참고

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

배경¶

기본 개념¶

명령줄 인터페이스를 통해서든 make clinic을 통해서든 파일에 대해 Argument Clinic을 실행하면, Argument Clinic은 입력 파일을 훑으며 시작 줄을 찾습니다:

/*[clinic input]

시작 줄을 찾으면 끝 줄까지 모든 내용을 읽습니다:

[clinic start generated code]*/

이 두 줄 사이에 있는 모든 내용이 Argument Clinic 입력입니다. Argument Clinic은 입력을 파싱하면 출력을 생성합니다. 출력은 C 파일의 입력 바로 뒤에 다시 쓰이고, 그 뒤에 체크섬 줄이 이어집니다. 시작 줄과 체크섬 줄을 포함한 이 모든 줄을 통틀어 Argument Clinic 블록이라고 부릅니다:

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

같은 파일에 대해 Argument Clinic을 다시 실행하면, Argument Clinic은 이전 출력을 버리고 새 체크섬 줄과 함께 새 출력을 기록합니다. 입력이 바뀌지 않았다면 출력도 바뀌지 않습니다.

참고

Argument Clinic 블록의 출력은 절대 수정해서는 안 됩니다. 어떤 변경이든 이후 Argument Clinic을 실행할 때 사라지기 때문입니다. Argument Clinic은 출력 체크섬 불일치를 감지하고 올바른 출력을 다시 생성합니다. 생성된 출력이 마음에 들지 않는다면, 출력을 고치는 대신 원하는 출력이 나올 때까지 입력을 변경하십시오.

참조¶

용어¶

시작 줄¶: /*[clinic input] 줄입니다. 이 줄은 Argument Clinic 입력의 시작을 표시합니다. 시작 줄은 C 블록 주석을 연다는 점에 유의하십시오.
끝 줄¶: [clinic start generated code]*/ 줄입니다. 끝 줄은 Argument Clinic 입력의 끝을 표시하는 동시에 Argument Clinic 출력의 시작도 표시합니다. 그래서 텍스트가 “clinic start start generated code”입니다. 끝 줄은 시작 줄이 연 C 블록 주석을 닫는다는 점에 유의하십시오.
체크섬¶: 고유한 입력과 출력을 구별하기 위한 해시입니다.
체크섬 줄¶: /*[clinic end generated code: ...]*/처럼 생긴 줄입니다. 세 개의 점은 입력에서 생성된 체크섬과 출력에서 생성된 체크섬으로 대체됩니다. 체크섬 줄은 Argument Clinic이 생성한 코드의 끝을 표시하며, Argument Clinic이 출력을 다시 생성해야 하는지 판단하는 데 사용됩니다.
입력¶: 시작 줄과 끝 줄 사이의 텍스트입니다. 시작 줄과 끝 줄은 C 블록 주석을 열고 닫으므로, 입력은 같은 C 블록 주석의 일부라는 점에 유의하십시오.
출력¶: 끝 줄과 체크섬 줄 사이의 텍스트입니다.
블록¶: 시작 줄부터 체크섬 줄까지(양 끝 포함)의 모든 텍스트입니다.

명령줄 인터페이스¶

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를 사용합니다. 제한된 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()에 전달할 때 변수 이름 앞에 &를 붙입니다.