PEP 387 – 하위 호환성 정책

Author:: Benjamin Peterson <benjamin at python.org>
PEP-Delegate:: Brett Cannon <brett at python.org>
Status:: Active
Type:: Process
Created:: 18-Jun-2009
Post-History:: 19-Jun-2009, 12-Jun-2020, 19-Dec-2022, 16-Jun-2023
Replaces:: 291

Table of Contents

초록
근거
하위 호환성 규칙
- 하위 호환성의 기본 정책
소프트 지원 중단
비호환성 변경 사항 적용
변경 이력
참고 문헌
Copyright

번역·라이선스 안내

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

초록

이 PEP는 Python의 하위 호환성 정책을 개괄합니다.

근거

오늘날 가장 널리 사용되는 프로그래밍 언어 중 하나인 [1] Python의 핵심 언어와 표준 라이브러리는 수백만 개의 애플리케이션과 라이브러리에서 중요한 역할을 합니다. 이는 매우 훌륭한 일입니다. 그러나 이는 개발 팀이 새 릴리스로 기존의 타사 코드를 손상하지 않도록 매우 주의해야 한다는 의미입니다.

이 PEP는 “하위 호환성 결여”를 변경 후 기존 코드가 더 이상 비교 가능한 방식으로 작동하지 않는다는 의미로 봅니다. 이것이 구체적인 정의가 아니라는 점은 인정하지만, 일반적으로 사람들이 “하위 호환성 결여”가 무엇을 의미하는지 이해할 것으로 기대하며, 확실하지 않은 경우 Python 개발 팀 및/또는 운영 위원회에 지침을 요청할 수 있습니다.

하위 호환성 규칙

이 정책은 모든 공개 API에 적용됩니다. 여기에는 다음이 포함됩니다.

참조 매뉴얼에 정의된 이러한 구성 요소의 구문과 동작입니다.
C-API입니다.
함수, 클래스, 모듈, 속성 및 메서드의 이름과 타입입니다.
주어진 인자 집합에 대한 함수의 반환값, 부작용 및 발생한 예외입니다. 이는 합리적인 버그 수정에 따른 변경을 배제하지 않습니다.
인자와 반환값의 위치 및 예상 타입입니다.
서브클래스와 관련된 클래스의 동작, 즉 재정의된 메서드가 호출되는 조건입니다.
문서화된 예외와 해당 예외의 발생으로 이어지는 의미 체계입니다.
EAFP 시나리오에서 일반적으로 발생하는 예외입니다.

그 밖의 항목은 명시적으로 공개 API에 포함되지 않습니다. 이러한 항목은 언제든 어떤 방식으로든 변경되거나 제거될 수 있습니다. 여기에는 다음이 포함됩니다.

특수한 이름을 제외하고 “_”가 앞에 붙은 함수, 클래스, 모듈, 속성, 메서드 및 C-API의 이름과 타입입니다.
공개적으로 비공개라고 문서화된 모든 항목입니다. 전혀 문서화되지 않은 항목이 자동으로 비공개로 간주되는 것은 아닙니다.
가져온 모듈입니다(공개 API의 일부라고 명시적으로 문서화된 경우는 제외합니다. 예를 들어 spam에서 bacon 모듈을 가져온다고 해서 해당 모듈이 그렇게 문서화되지 않은 한 spam.bacon이 자동으로 공개 API의 일부가 되는 것은 아닙니다).
내부 클래스의 상속 패턴입니다.
테스트 모음입니다. (Lib/test 디렉터리 또는 패키지의 테스트 하위 디렉터리에 있는 모든 항목을 의미합니다.)
하위 호환성 규칙은 PEP 411에 따라 Provisional로 명시적으로 문서화된 모듈이나 API에는 적용되지 않습니다.

하위 호환성의 기본 정책

일반적으로 비호환성은 파손 대비 이점의 비율이 높아야 하며, 영향을 받는 코드에서 해당 비호환성을 쉽게 해결할 수 있어야 합니다. 예를 들어, 서드 파티 패키지와 이름이 같은 표준 라이브러리 모듈을 추가하는 것은 일반적으로 허용되지 않습니다. 그러나 상속을 통해 서드 파티 코드와 충돌하는 메서드나 속성을 추가하는 것은 대체로 합리적일 가능성이 높습니다.
아래의 지원 중단 절차를 따르는 경우가 아니라면, API의 동작은 연속된 두 릴리스 사이에서 호환되지 않는 방식으로 변경되어서는 안 됩니다. Python의 연례 릴리스 프로세스(PEP 602)에 따라 지원 중단 기간은 최소 2년간 지속되어야 합니다.
마찬가지로 연속된 두 릴리스 사이에서 기능을 예고 없이 제거할 수 없습니다.
지원 중단 경고를 발생시킬 수 없는 변경 사항은 운영 위원회와 협의하십시오.
운영 위원회는 이 정책에 대한 예외를 승인할 수 있습니다. 특히 기능에 요구되는 지원 중단 기간을 단축할 수 있습니다. 예외는 위험할 정도로 손상되었거나 안전하지 않은 기능, 또는 합리적으로 누구도 의존할 수 없는 기능(예: 완전히 폐기된 플랫폼에 대한 지원)과 같은 극단적인 상황에서만 승인됩니다.

소프트 지원 중단

새 코드를 작성할 때 더 이상 사용해서는 안 되지만 기존 코드에서 계속 사용해도 안전한 API에는 소프트 지원 중단을 적용할 수 있습니다. API는 문서화되고 테스트된 상태로 유지되지만, 더 이상 개발되지 않습니다(개선 사항 없음).

“소프트” 지원 중단과 (일반적인) “하드” 지원 중단의 주요 차이점은 소프트 지원 중단이 지원 중단된 API의 제거 일정을 정한다는 의미를 내포하지 않는다는 점입니다.

또 다른 차이점은 소프트 지원 중단은 경고를 발행하지 않는다는 점입니다. 즉 문서에만 언급되는 반면, 일반적으로 “하드” 지원 중단은 런타임에 DeprecationWarning 경고를 발행합니다. 소프트 지원 중단에 관한 문서에는 API를 피해야 하는 이유를 설명하고, 가능하다면 대체 방법을 제안해야 합니다.

현재 소프트 지원 중단된 기능을 (일반적인 의미로) 지원 중단하기로 결정한 경우, 해당 지원 중단은 Backwards Compatibility Rules를 따라야 합니다(즉, 해당 기능이 이미 소프트 지원 중단되었다는 이유로 예외가 적용되지 않습니다).

비호환성 변경 사항 적용

비호환성 변경 사항을 적용하는 작업은 여러 릴리스에 걸쳐 수행되는 점진적인 프로세스입니다.

변경 사항을 논의하십시오. 비호환성의 정도에 따라 Discourse에서, issue tracker에서, 또는 적절한 작업 그룹이나 SIG에서 논의할 수 있습니다. 논의가 합의에 도달하면 PEP 또는 유사한 문서를 작성할 수 있습니다. 영향을 받는 API의 사용자들이 의견을 제시하기를 바랍니다.
현재 main 브랜치에 경고를 추가하십시오. 동작이 변경되는 경우 API에 새로운 동작을 수행하는 새 함수나 메서드를 추가할 수 있으며, 기존 사용 방식에서는 경고가 발생해야 합니다. API가 제거되는 경우에는 해당 API에 진입할 때마다 경고를 발생시키면 됩니다. 일반적으로 사용할 경고 범주는 DeprecationWarning이지만, API의 이전 버전과 새 버전이 여러 릴리스 동안 공존하는 특수한 경우에는 PendingDeprecationWarning을 사용할 수 있습니다 [2]. 경고 메시지에는 비호환성이 기본 동작이 될 것으로 예상되는 릴리스와 사용자가 피드백을 게시할 수 있는 이슈 링크를 포함해야 합니다. 가능한 경우 typeshed 를 변경하여 지원 중단된 API에 @deprecated 데코레이터(PEP 702 참조)를 추가함으로써, 정적 타입 검사기 사용자가 지원 중단 사실을 알 수 있는 또 다른 방법을 제공하십시오.
C API의 경우 Py_DEPRECATED 매크로가 생성하는 컴파일러 경고도 허용됩니다.
동일한 주 버전의 Python에서 최소 두 개의 마이너 버전, 또는 이전 주 버전에서 하나의 마이너 버전에 경고가 나타날 때까지 기다리십시오(예: Python 3.10.0에서 경고를 발생시키는 경우 변경 사항을 적용하려면 Python 3.12 또는 Python 4.0 이상이 될 때까지 기다려야 합니다). 다만 제거하기 전에 5년을 기다리는 것이 바람직합니다(예: Python 3.10부터 경고를 발생시키고 3.15에서 제거하는 방식이며, 이는 공교롭게도 현재 Python 마이너 릴리스의 수명과 일치합니다).
- 지원 중단된 동작에 대한 예상 유지 관리 부담과 보안 위험이 작다면(예: 기존 함수를 새롭고 더 일반적인 함수에 기반하여 재구현하는 경우), 해당 동작을 무기한 유지할 수 있습니다(또는 상황이 바뀔 때까지 유지할 수 있습니다).
- 폐지 예정 기능이 새로운 기능으로 대체되는 경우, 일반적으로 새로운 기능을 포함하지 않는 마지막 Python 버전의 지원이 종료된 후에만 제거해야 합니다.
피드백이 있는지 확인하십시오. 원래 논의에 참여하지 않았던 사용자들도 경고를 확인한 후 이제 의견을 낼 수 있습니다. 재고할 수도 있습니다.
선언된 버전에 도달했으므로, 이제 동작 변경이나 기능 제거를 기본값으로 만들거나 영구적으로 만들 수 있습니다. 이전 버전과 경고를 제거하십시오.
사용자에게 경고를 제공할 수 없는 경우, 운영 위원회에 문의하십시오.

변경 이력

2025년 1월 27일: 제거 전 5년간의 폐지 예정 기간을 선호하도록 갱신되었습니다.
2023년 11월 14일: PEP 702에 따라 @deprecated 데코레이터가 추가되었습니다.
2023년 7월 3일: https://discuss.python.org/t/27957에서 논의된 대로, 소프트 폐지(Soft Deprecation) 섹션이 추가되었습니다.
2023년 6월 26일: https://discuss.python.org/t/22042에서 논의된 대로, 여러 소소한 업데이트와 명확화가 있었습니다.
2022년 4월 4일: 몇몇 예외적인 경우에 운영 위원회(Steering Council)에 문의하라는 명시적인 안내가 추가되었습니다.
2021-Apr-16: 변경을 가하기 전에 경고를 얼마나 오래 발생시켜야 하는지 명확히 했습니다.
2020-Jul-20: 최초 승인 버전입니다.

참고 문헌

Copyright

This document has been placed in the public domain.