[PyCharm] 타입 힌트 관련 경고 끄는 방법

서론

개발할 때 PyCharm에서 자꾸 눈에 거슬리는 경고 메시지들이 보이는데 너무 짜증나요

진짜 에디터에서 너무 거슬립니다.

• Expected type 'CategoryResponse', got 'Category' instead
• Expected type 'list[Product]', got 'list[Type[Product]]' instead
• Invalid type hints definitions and usage
• Invalid TypedDict definition and usage
• Shadows built-in name 'type'

이런 경고는 실제 코드 실행이나 배포에는 영향을 주지 않지만,

PyCharm이 타입 힌트 또는 추론 과정에서 의심스러운 부분을 미리 알려주는 역할을 해요.

하지만 개발 단계에서 너무 민감하게 뜨는 경우, IDE 설정을 통해 끌 수 있습니다.

---

본문

1. 설정 방법

1.1 PyCharm Preferences 열기

Cmd + , 또는 메뉴에서 PyCharm > Preferences

 

1.2 검색창에 Inspections 검색 후 이동

또는 Editor > Inspections 로 직접 진입

 

1.3 검색창에 type 입력

아래와 같은 항목들을 확인하고 비활성화합니다:

• Incorrect type
• Invalid type hints definitions and usage
• Invalid TypedDict definition and usage
• Invalid usage of new-style type parameters
• Type in docstring does not match declared type

1.4 체크 해제하거나, Severity(심각도)를 Weak Warning 또는 No highlighting으로 조정

---

2. PyCharm 타입 관련 경고 항목 해설

2.1 Incorrect type

• 설명: 타입 힌트를 지정했는데, 해당 타입과 맞지 않는 값을 리턴하거나 파라미터로 사용하는 경우 발생.
• 예제:

def get_items() -> list[str]: return [str] # ❗Expected 'str', got 'type[str]' instead

 

• 해결 방법:
  • str이 아니라 "hello" 같은 실제 문자열 값이어야 함.
  • 개발 중에는 의도적인 임시 코드일 수 있으므로 경고를 끌 수 있음.

---

2.2 Invalid type hints definitions and usage

• 설명: 잘못된 타입 힌트 구문을 사용하거나, Python 버전에서 지원되지 않는 방식일 때 발생.
• 예제:

def process(data: list | dict): # ❗Python <3.10에서는 'list | dict' 문법 지원 안함 pass

• 해결 방법:
  • Python 3.10 이상에서는 정상이나, 낮은 버전에서는 Union[list, dict] 사용.
  • 호환성 테스트 필요 없으면 경고 끄는 것도 가능.

---

2.3 Invalid TypedDict definition and usage

• 설명: TypedDict를 사용할 때 잘못된 선언이나 필드 타입이 명확하지 않을 때 발생.
• 예제:

class MyDict(TypedDict): name: str age = 20 # ❗정적 타입 선언 안됨. 타입 힌트가 누락됨

• 해결 방법:
• class MyDict(TypedDict): name: str age: int

• 참고: TypedDict 사용이 많지 않거나 타입 엄격함이 필요 없으면 비활성화 가능.

---

2.4 Invalid usage of new-style type parameters

• 설명: list[str] 같은 타입을 사용했을 때, IDE가 이를 완벽히 해석하지 못하는 경우 발생 (특히 Python < 3.9).
• 예제:

def test() -> list[str]: # ❗오래된 인터프리터에서는 에러 return ["a", "b"]

• 해결 방법: Python 버전 맞춰야 하며, 아니면 List[str] (from typing)으로 변경.

---

2.5 Type in docstring does not match declared type

• 설명: 함수 주석(docstring)에 명시된 타입과 실제 코드 상의 타입 힌트가 다를 때 발생.
• 예제:

def add(a: int, b: int) -> int: """ :param a: str # ❗docstring 상 타입이 코드와 다름 :param b: int :return: int """ return a + b

• 해결 방법: docstring 안의 타입을 일치시키거나, docstring 타입 검사 비활성화.

---

3. 참고: 왜 끄는 걸까?

• 개발 중 스키마나 모델 구조가 자주 바뀔 때, 매번 타입 경고가 방해될 수 있어요.
• 타입 힌트를 쓰고는 있지만, 정확성보다 생산성이 더 중요한 상황
• 실제 런타임에는 에러가 발생하지 않기 때문에, 개발 효율을 위해 경고만 무시하는 전략도 괜찮습니다.
• 타입 정확성은 ruff, mypy, pytest 등으로 외부에서 검사하고 있는 경우

---

마무리

눈에 거슬리는 경고는 없애고, 개발에만 집중하세요!

나중에 구조가 확정되고 안정화되면 다시 켜서 정리해도 늦지 않아요.

실제 코드 품질과 실행에 영향을 주지 않는다면, 내 환경에 맞게 IDE를 조절하는 것도 작업속도에 향상에 도움이 됩니다.