PEP 689 – 불안정 C API 티어

Author:

Petr Viktorin <encukou at gmail.com>

Discussions-To:

Discourse thread

Status:

Final

Type:

Standards Track

Requires:

523

Created:

22-Apr-2022

Python-Version:

3.12

Post-History:

27-Apr-2022, 25-Aug-2022, 27-Oct-2022

Resolution:

Discourse message

---

Table of Contents

• 초록
• 동기 및 근거
  • 불안정 C API 티어
  • 비공개 API를 위한 이름 앞 밑줄 예약
  • 불필요하게 코드를 중단하지 않기
• 사양
  • 선행 밑줄
  • 초기 Unstable API
• 하위 호환성
• 이 내용을 가르치는 방법
• 참조 구현
• 거부된 아이디어
  • 특수 접두사 없음
  • 밑줄 접두사
  • 새 헤더 디렉터리
  • 파이썬 API
• Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

Important

This PEP is a historical document. The up-to-date, canonical documentation can now be found at Changing Python’s C API.

×

사용자 대상 문서는 Unstable C API에 있습니다.

See PEP 1 for how to propose changes.

초록

C API의 일부 함수와 타입은 불안정으로 지정되며, 이는 패치(버그 수정/보안) 릴리스에서는 변경되지 않지만 마이너 릴리스 간(예: 3.11과 3.12 사이)에는 사용 중단 경고 없이 변경될 수 있음을 의미합니다.

이름 앞에 밑줄이 붙은 모든 C API는 내부로 지정되며, 이는 어떠한 통지도 없이 변경되거나 사라질 수 있음을 의미합니다.

동기 및 근거

불안정 C API 티어

Python C API는 현재 세 가지 안정성 티어로 나뉩니다.

• 높은 호환성이 기대되는 제한된 API
• 공개 API는 하위 호환성 정책을 따르며 변경 전에 지원 중단 경고를 요구합니다.
• 언제든지 변경될 수 있는 내부(비공개) API입니다.

CPython 내부에 액세스해야 하는 도구(예: 고급 디버거와 JIT 컴파일러)는 CPython의 마이너 시리즈 릴리스용으로 빌드되는 경우가 많으며, 사용되는 C API 내부가 패치 릴리스에서 변경되지 않는다고 가정합니다. 이러한 도구를 지원하려면 마이너 시리즈 릴리스 전체에서 안정성을 보장하는 공개 C API와 비공개 C API 사이의 티어가 필요합니다. 이것이 제안된 불안정 티어입니다.

PyCode_New()와 같은 일부 함수는 불안정하다고 문서화되어 있으며(“이를 직접 호출하면 특정 Python 버전에 종속될 수 있습니다”), 실제로도 자주 변경됩니다. 불안정 티어는 문서를 충분히 주의 깊게 읽지 않는 사람에게도 해당 상태를 명확히 드러내어 실수로 사용하기 어렵게 해야 합니다.

비공개 API를 위한 이름 앞 밑줄 예약

현재 CPython 개발자들은 API 이름에서 이름 앞 밑줄의 정확한 의미에 대해 합의하지 못하고 있습니다. 이름 앞 밑줄은 두 가지 서로 다른 의미로 사용됩니다.

• 여기서 제안한 불안정 티어의 경우처럼 마이너 릴리스 간에 변경될 수 있는 API(예: PEP 523에서 도입된 함수)
• 비공개이며 CPython 외부에서는 전혀 사용해서는 안 되는 API(예: 통지 없이 변경될 수 있거나, CPython이 아닌 코드가 보장할 수 없는 문서화되지 않은 가정에 의존하기 때문)

의미가 불분명하기 때문에 밑줄은 본래 가능했을 만큼 유용하지 않습니다. 밑줄이 비공개 API만 표시한다면 CPython 개발자는 CPython 외부에서 해당 함수가 어떻게 문서화되었거나 사용되는지 조사하지 않고도 밑줄이 붙은 함수를 변경하거나 사용되지 않는 함수를 제거할 수 있습니다.

전용 불안정 티어를 도입하면 이름 앞 밑줄의 의미를 명확히 할 수 있습니다. 이름 앞 밑줄은 비공개 API만 표시해야 합니다.

불필요하게 코드를 중단하지 않기

이 PEP는 불안정 티어의 API에 특수한 이름 접두사가 있어야 한다고 명시합니다. 이는 함수(매크로 등)의 이름을 변경해야 함을 의미합니다. 이름을 변경한 후에도 호환되지 않는 변경이 이루어질 때까지(즉, 호출 위치를 어차피 업데이트해야 할 때까지) 이전 이름을 계속 사용할 수 있어야 합니다. 다시 말해 함수의 티어만 변경하는 것으로는 사용자의 코드가 중단되지 않아야 합니다.

사양

C API는 안정성 기대 수준에 따라 세 가지 “섹션” (내부, 공개, 제한)으로 나뉩니다. 이제 이를 안정성 티어 또는 줄여서 티어라고 부르겠습니다.

Unstable tier가 추가됩니다.

이 계층의 API(함수, 타입 등)는 선행 밑줄 없이 PyUnstable_ 접두사로 이름이 지정됩니다.

이 API는 공개 API에 사용되는 헤더(Include/*.h)에 선언되며, Include/unstable/와 같은 하위 디렉터리에는 선언되지 않습니다.

Unstable tier를 다루기 위한 몇 가지 규칙이 도입됩니다.

• Unstable API에는 패치 릴리스 간 하위 호환성을 깨뜨리는 변경이 없어야 하지만, 마이너 릴리스(3.x.0 및 3.x.0의 알파와 베타 릴리스 포함)에서는 변경되거나 제거될 수 있습니다. 이러한 변경 사항은 문서화하고 What’s New 문서에 언급해야 합니다.
• 이러한 API에 대한 하위 호환성을 깨뜨리는 변경은 해당 API를 사용하는 코드가 새 버전으로 컴파일되도록 업데이트되어야 하는 방식으로 이루어져야 합니다(예: 인자를 추가하거나 제거하거나 함수 이름을 변경해야 하지만, 인자의 의미적 해석은 변경해서는 안 됩니다).
• Unstable API는 문서화하고 테스트해야 합니다.
• 공개 계층의 API를 unstable tier로 이동하려면 새로운 PyUnstable_* 이름으로 노출해야 합니다.

  이전 이름은 더 이상 사용되지 않도록 지정해야 하지만(예: Py_DEPRECATED 사용), API에 호환성을 깨뜨리는 변경이 이루어질 때까지 계속 사용할 수 있어야 합니다. Python의 하위 호환성 정책(PEP 387)에 따라 이러한 사용 중단 지정은 SC 예외 없이 at least 두 번의 릴리스 동안 유지되어야 합니다. 그러나 이 기간은 무기한 지속될 수도 있습니다. 예를 들어 오늘 PEP 590의 “provisional” _PyObject_Vectorcall이 추가된다면, 처음에는 PyUnstable_Object_Vectorcall이라는 이름으로 지정되고 이 이름을 제거할 계획은 없을 것입니다.

  다음과 같은 경우에는 함수가 이미 Unstable tier의 일부였던 것처럼 SC 예외 없이 호환성을 깨뜨리는 변경(따라서 사용 중단된 이름의 제거)을 허용합니다.

  • Python 3.12 이전에 도입되었으며 기본값보다 안정성이 낮다고 documented된 모든 API입니다.
  • Python 3.12 이전에 도입되었으며 선행 밑줄이 포함된 이름으로 지정된 모든 API입니다.

  예시는 이 PEP에 지정된 Initial unstable API 를 참조하십시오.

• internal API를 unstable tier로 이동하려면 새로운 PyUnstable_* 이름으로 노출해야 합니다.

  이전 이름이 문서화되어 있거나 외부에서 널리 사용되는 경우, 호환성을 깨뜨리는 변경이 이루어질 때까지 계속 사용할 수 있어야 합니다(그리고 호출 위치를 업데이트해야 합니다). 해당 이름은 사용 중단 경고를 발생시키기 시작해야 합니다(예: Py_DEPRECATED 사용).

• unstable tier의 API를 공개 계층으로 이동하려면 PyUnstable_* 접두사 없이 노출해야 합니다.

  이전 이름은 API가 사용 중단되거나 제거될 때까지 계속 사용할 수 있어야 합니다.

• 기존 기능에 대한 새로운 불안정 API의 추가는 베타 기능 동결 이후에도 첫 번째 릴리스 후보까지 허용됩니다. 베타 기간에는 Core Development Discourse에서 합의가 필요합니다.

이러한 규칙은 devguide 에 문서화되며, user documentation 도 그에 맞게 업데이트됩니다.

PyUnstable_*로 이름이 지정된 C API의 참조 문서에는 unstable tier 문서로 연결되는 링크가 포함된 참고 사항이 자동으로 표시됩니다.

선행 밑줄

선행 밑줄이 포함된 이름으로 지정된 C API와 Py_BUILD_CORE로만 사용할 수 있는 API는 internal로 간주됩니다. 이는 다음을 의미합니다.

• 이러한 API는 마이너 릴리스(3.x.0 및 3.x.0의 알파와 베타 릴리스 포함)에서 without notice 없이 변경되거나 제거될 수 있습니다. 패치 릴리스나 릴리스 후보에서 API를 변경하는 일은 반드시 필요한 경우에만 수행해야 합니다.
• 이러한 API는 공개 문서가 아니라 소스 주석이나 Devguide에만 문서화해야 합니다.
• Python 3.12 이전에 도입되었으며 문서화되어 있거나 외부에서 널리 사용되는 API는 위에서 설명한 대로 Unstable tier로 이동해야 합니다.

  이 PEP가 승인된 후 한참 뒤에 이러한 일이 발생할 수 있습니다. 따라서 몇 년 동안은 코어 개발자가 밑줄이 붙은 API를 변경하기 전에 일부 조사를 수행해야 하며, 특히 Py_BUILD_CORE를 필요로 하지 않는 경우에는 더욱 그렇습니다.

C API 사용자는 코드베이스에서 _Py 및 _PY 식별자 접두사를 검색하고, 검색 결과를 결국 수정해야 할 문제로 간주해야 합니다 – 기존 대안으로 전환하거나, 해당 사용 사례에 대한 공개 API 노출을 요청하는 CPython 이슈를 개설한 후 궁극적으로 해당 API로 전환해야 합니다.

초기 Unstable API

다음 API는 개념 증명으로서 초기 구현에서 Unstable 계층으로 이동합니다.

코드 객체 생성자:

• PyUnstable_Code_New() (PyCode_New에서 이름 변경)
• PyUnstable_Code_NewWithPosOnlyArgs() (PyCode_NewWithPosOnlyArgs에서 이름 변경)

코드 추가 정보 (PEP 523):

• PyUnstable_Eval_RequestCodeExtraIndex() (_PyEval_RequestCodeExtraIndex에서 이름 변경)
• PyUnstable_Code_GetExtra() (_PyCode_GetExtra에서 이름 변경)
• PyUnstable_Code_SetExtra() (_PyCode_SetExtra에서 이름 변경)

Python 3.12에서는 또 다른 PEP가 필요하지 않은 상태로 더 많은 API가 추가될 것으로 예상됩니다.

하위 호환성

C API의 하위 호환성에 대한 기대 사항을 더 명확히 합니다.

이름이 변경된 모든 API는 가능한 한 오랫동안 기존 이름으로도 사용할 수 있습니다.

이 내용을 가르치는 방법

이러한 변경 사항은 고급 C 프로그래머에게 영향을 미치므로, 이들은 업데이트된 참조 문서, devguide 및/또는 What’s New 문서를 참조해야 합니다.

참조 구현

https://github.com/python/cpython/compare/main…encukou:unstable-tier

거부된 아이디어

특수 접두사 없음

이 PEP의 초기 버전에서는 불안정 API에 PyUnstable접두사가 없었습니다. 대신 Py_USING_UNSTABLE_API를 정의하면 특정 소스 파일에서 API를 사용할 수 있었으며, 이는 해당 파일 전체를 각 Python 릴리스마다 다시 검토해야 할 가능성이 있음을 인정한다는 의미였습니다.

그러나 불안정성은 개별 이름에 드러나야 한다고 결정되었습니다.

밑줄 접두사

비공개 API와 불안정 API를 모두 앞에 밑줄을 붙여 표시할 수는 있습니다. 그러나 그렇게 하면 _Py접두사의 의미가 약화됩니다. 접두사를 내부 API 전용으로 예약하면 검색이 매우 간단해집니다.

새 헤더 디렉터리

다른 API 계층에는 헤더 전용 디렉터리가 있습니다(Include/cpython/, Include/internal/).

Unstable 계층은 매우 명확한 명명 규칙을 사용하고 이름을 항상 사용할 수 있으므로, Include/unstable/와 같은 디렉터리는 필요하지 않습니다.

파이썬 API

파이썬(C가 아닌) API에 유사한 계층을 추가하는 것이 좋을 수 있습니다. 예를 들어 types.CodeType에 대해 추가할 수 있습니다. 그러나 이를 위한 메커니즘은 달라야 합니다. 이는 PEP의 범위를 벗어납니다.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.