Python argparse suggest_on_error 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Python argparse suggest_on_error 사용법

argparse.ArgumentParser의 suggest_on_error는 사용자가 선택지 이름이나 서브커맨드 이름을 잘못 입력했을 때 가까운 값을 제안해 주는 옵션이다. Python 공식 문서 기준으로 이 옵션은 Python 3.14에서 추가됐다.

핵심은 세 가지다. 이 기능은 모든 파싱 오류를 고쳐 주는 것이 아니라 문자열 choices와 서브파서 이름 같은 일부 입력 실수에만 도움을 준다. Python 3.14 환경에서는 기본 동작으로 가정하지 말고 명시적으로 켜는 편이 안전하다. 또한 오류 처리 정책은 exit_on_error, 도움말 출력 정책은 color와 따로 판단해야 한다.

suggest_on_error는 언제 켜면 될까?

명령행 도구를 다른 개발자나 운영자가 직접 입력해 실행하는 경우라면 기본 후보로 두기 좋다. 서브커맨드가 많거나 choices 목록이 길수록 오타 교정 힌트의 체감 효과가 커진다.

• 사용자가 deploy, rollback 같은 서브커맨드를 직접 입력한다.
• choices에 debug, dryrun처럼 비슷한 문자열이 있다.
• 실패 메시지를 조금 더 친절하게 만들고 싶다.

반대로 인자를 사람이 직접 치지 않는 자동화 내부 호출이라면 우선순위가 낮다. 그 경우에는 제안 메시지보다 종료 코드와 예외 처리의 일관성이 더 중요할 수 있다.

어떤 오타에서 동작할까?

Python 3.14 argparse 문서는 이 기능이 잘못 입력한 argument choice와 subparser name에 대해 제안을 제공한다고 설명한다. 즉 문자열 후보 목록을 가진 인자나 서브커맨드 이름에서 효과가 있고, 모든 형태의 타입 오류를 자동 보정하는 기능은 아니다.

import argparse

parser = argparse.ArgumentParser(suggest_on_error=True)
parser.add_argument("--action", choices=["debug", "dryrun"])

parser.parse_args(["--action", "debugg"])

이 경우 공식 문서 예시처럼 debugg 입력에 대해 debug를 제안하는 메시지가 나온다. 반면 정수 변환 실패나 필수 인자 누락 같은 오류는 여전히 일반적인 파싱 오류로 처리된다.

Python 3.14에서 어떻게 켜는 편이 안전할까?

가장 단순한 방법은 ArgumentParser 생성 시 suggest_on_error=True를 주는 것이다. 다만 Python 공식 문서는 구버전과의 호환이 필요하면 생성자 인수 대신 속성을 나중에 설정하는 방식도 안내한다.

import argparse

parser = argparse.ArgumentParser(description="example")

if hasattr(parser, "suggest_on_error"):
    parser.suggest_on_error = True

이 패턴은 Python 3.14 미만 환경에서 같은 코드를 재사용해야 할 때 유용하다. 즉 런타임 버전이 섞여 있으면 키워드 인수에 바로 의존하기보다 속성 존재 여부를 확인하는 편이 더 보수적이다.

exit_on_error와는 무엇이 다를까?

suggest_on_error는 오류 메시지의 품질을 높이는 옵션이고, exit_on_error는 오류가 났을 때 파서를 종료할지 예외를 올릴지 결정하는 옵션이다. Python 공식 문서는 exit_on_error=False이면 ArgumentError를 직접 잡을 수 있다고 설명한다.

즉 사용성 개선과 제어 흐름 제어는 별개다. CLI를 라이브러리처럼 감싸서 테스트하거나 상위 코드에서 오류를 복구해야 한다면 exit_on_error=False를 먼저 검토하고, 사용자 친화적인 안내까지 원하면 그 위에 suggest_on_error를 추가하는 식이 자연스럽다.

color 옵션은 같이 봐야 할까?

Python 3.14에서는 도움말 색상 출력을 제어하는 color 옵션도 함께 추가됐다. 공식 문서 기준으로 도움말은 기본적으로 ANSI 색상 시퀀스를 사용할 수 있고, color=False면 환경 변수와 무관하게 비활성화된다.

운영 로그나 파일 리다이렉션 결과를 사람이 나중에 읽는 환경이라면 색상 제어를 같이 보는 편이 좋다. 특히 문서에는 오류 메시지가 stderr를 파일로 리다이렉션할 때도 색상 코드가 포함될 수 있으므로, 필요하면 NO_COLOR 또는 PYTHON_COLORS 환경 변수를 사용하라고 안내한다.

 

 

실무에서는 어떤 기준으로 적용하면 될까?

대부분의 개발자용 CLI에서는 아래 기준이면 충분하다.

• Python 3.14 이상만 지원하면 suggest_on_error=True를 명시한다.
• 여러 Python 버전을 함께 지원하면 속성 존재 여부를 확인한 뒤 켠다.
• 상위 코드에서 파싱 실패를 처리해야 하면 exit_on_error=False를 같이 검토한다.
• 도움말이나 오류 출력을 파일로 남길 수 있으면 color 정책도 같이 정한다.

정리하면 suggest_on_error는 작은 기능이지만, 사용자가 직접 타이핑하는 CLI에서는 실패 경험을 눈에 띄게 줄여 준다. 다만 적용 범위와 버전 조건을 정확히 이해하고 켜는 편이 맞다.

FAQ

suggest_on_error는 모든 argparse 오류에 대해 추천을 보여줄까?

아니다. Python 3.14 문서는 잘못 입력한 argument choice와 subparser name에 대한 제안을 설명한다. 타입 변환 실패나 필수 인자 누락까지 자동으로 보정하는 기능은 아니다.

Python 3.13 이하에서도 같은 키워드 인수를 쓸 수 있을까?

Python 공식 문서 기준으로 suggest_on_error는 3.14에서 추가됐다. 따라서 3.13 이하를 함께 지원하면 생성자 키워드 인수 사용 전 버전 호환성을 먼저 확인해야 한다.

stderr를 파일로 돌릴 때 색상 코드가 섞일 수 있을까?

그럴 수 있다. Python 3.14 문서는 오류 메시지가 stderr를 파일로 리다이렉션할 때 색상 코드를 포함할 수 있다고 설명하며, 이를 피하려면 NO_COLOR 또는 PYTHON_COLORS 환경 변수를 사용할 수 있다고 안내한다.

참고 자료

• Python 3.14 argparse 문서
• What's New in Python 3.14
• Python 3.12 argparse 문서