사용 중단 권고 (Deprecated)

사용 중단 권고(Deprecated)는 기능이나 API의 새 사용을 피하고 대체 방식으로 옮기도록 알리는 상태입니다. 이미 제거되어 호출할 수 없다는 뜻과는 구분되며, 실제 제거 여부와 시점은 해당 프로젝트의 정책을 따릅니다. 기존 코드가 계속 실행되더라도 문서의 대체 기능과 호환 조건을 확인해 변경을 준비합니다. 경고 표시 여부도 언어와 도구에 따라 다릅니다.

권고와 실제 제거 사이의 단계

Python의 하위 호환성 정책 PEP 387은 기존 코드가 갑자기 깨지는 일을 줄이기 위해 비호환 변경을 여러 릴리스에 걸쳐 진행하는 절차를 설명합니다. 사용 중단을 알리고, 의견을 받은 뒤, 정해진 버전에서 기능이나 동작을 바꾸는 방식입니다. 특정 함수에 이 표시가 붙었다면 그 함수를 새 코드에 계속 늘려 쓰기보다 공식 문서가 안내하는 대체 경로를 확인하는 계기가 됩니다.

제거된 기능은 실제 호출이나 가져오기가 실패할 수 있는 상태인 반면, 사용 중단이 권고된 기능은 호환을 위해 남아 있을 수 있습니다. 같은 오류 메시지가 언제나 나오는 것도 아닙니다. 경고를 내며 실행하는 구현과 문서에만 표시하는 구현이 있으므로, 실행 성공 여부와 지원 정책을 따로 확인합니다. 오래된 예제가 작동한다는 사실만으로 그 방식이 새 개발에도 권장된다고 판단하지 않습니다.

대체 기능으로 옮길 때는 이름만 바꾸는 것으로 끝나지 않을 수 있습니다. 입력 인자, 반환값, 예외, 기본 동작이 달라졌다면 호출하는 쪽 코드도 영향을 받습니다. 이전 함수와 새 함수가 같은 목적을 가졌더라도 어떤 조건에서 결과가 같은지 대조합니다. SDK 버전을 올린 뒤에는 실제 애플리케이션이 사용하는 경로를 확인해야 문서의 전환 안내가 코드에 제대로 반영됐는지 알 수 있습니다.

경고와 문서의 표시 방식

Python의 warnings 문서는 경고의 종류와 표시 여부를 제어하는 방법을 설명합니다. DeprecationWarning은 개발자가 대응할 사용 중단 변경을 알리는 경고 범주입니다. 이 경고는 기본 설정에서 숨겨지는 경우가 있으며 __main__ 코드에서 발생한 경우 등은 다르게 취급됩니다. 화면에 경고가 없었다는 이유만으로 의존하는 API에 사용 중단 계획이 없다고 볼 수 없습니다.

경고 필터는 같은 문제를 보이게 하거나 숨기고, 경우에 따라 오류로 취급하도록 정할 수 있습니다. 시험 환경에서 경고가 실패로 처리됐더라도 그 API가 이미 제거됐다고 단정하지 않습니다. 반대로 경고를 숨기는 설정은 코드를 대체 구현으로 바꾸지 않습니다. 실행 정책과 실제 API 상태를 구분하면 버전을 올리면서 생긴 실패의 원인을 더 정확히 설명할 수 있습니다.

문서에 표시된 상태와 에디터의 취소선, 실행 중 경고가 서로 다른 시점에 반영될 수도 있습니다. 에디터는 타입 정보나 라이브러리가 제공한 표시를 읽고, 실행기는 실제 호출 경로의 경고를 처리합니다. 프로젝트가 설치한 버전의 문서인지 확인하면 개발 환경의 표시와 웹 문서가 어긋나는 이유를 좁힐 수 있습니다. 여러 도구의 경고 개수를 지원 상태의 단일 지표로 합치지는 않습니다.

프로젝트별 정책과 전환 범위

PEP 387의 소프트 사용 중단 설명은 새 코드에는 쓰지 않기를 권하지만 기존 코드에서 계속 사용하는 것이 안전한 별도 상태를 둡니다. 이 상태는 API의 제거 일정을 뜻하지 않고 문서화와 시험은 유지되며 추가 기능 개발은 하지 않는 것으로 설명됩니다. 2026년 10월 11일 확인한 Python 정책의 구분이며, 다른 언어나 서비스가 같은 이름으로 같은 절차를 제공한다고 일반화하지 않습니다.

정규 사용 중단에도 예외와 개별 일정이 있습니다. 보안이나 심각한 결함 때문에 전환 기간이 달라질 수 있고, 대체 기능의 제공 시점과 기존 버전의 지원 기간도 영향을 줍니다. 상태 라벨 하나에서 제거 날짜를 추정하기보다 해당 기능의 공지와 변경 기록을 확인합니다. 코드에서 그 기능을 직접 쓰는지, 다른 패키지를 거쳐 간접으로 쓰는지에 따라 수정할 주체도 달라집니다.

전환 작업에서는 사용 위치, 설치 버전, 대체 API, 기대 결과를 함께 남깁니다. 반환값이 바뀌는 경로와 오류가 발생하는 경로를 비교하면 겉으로 보이는 호출 성공만으로 놓치는 차이를 찾기 쉽습니다. AI 코딩 도구가 오래된 사용 예시를 생성했을 때도 같은 방식으로 실제 문서와 대조합니다. 경고를 없앤 결과와 호환되는 동작을 확인한 결과는 별도로 기록합니다.