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, 이슈 트래커, 또는 적절한 작업 그룹이나 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-Jan-27: 제거 전 5년의 폐지 예정 기간을 두는 것을 권장하도록 갱신했습니다.
2023-Nov-14: PEP 702에 따라 @deprecated 데코레이터를 추가했습니다.
2023-Jul-03: https://discuss.python.org/t/27957에서 논의한 대로 소프트 폐지(Soft Deprecation) 절을 추가했습니다.
2023-Jun-26: https://discuss.python.org/t/22042에서 논의한 여러 소규모 갱신과 명확화를 반영했습니다.
2022-Apr-04: 몇몇 예외적인 경우에 운영 위원회에 문의하도록 명시적인 안내를 추가했습니다.
2021-Apr-16: 변경을 적용하기 전에 경고를 얼마나 오래 내보내야 하는지 명확히 했습니다.
2020-Jul-20: 최초 승인 버전입니다.

참고 문헌

Copyright

This document has been placed in the public domain.