[Python] SyntaxWarning: invalid escape sequence — 왜 이 문자열만 걸리나

증상

apps/folders/utils.py:39: SyntaxWarning: "\)" is an invalid escape sequence.
Such sequences will not work in the future. Did you mean "\\)"? A raw string is also an option.
  - 파일구분문자(/, \), 제어문자, 콜론 등 제거 또는 대체

apps/folders/utils.py:255: SyntaxWarning: "\S" is an invalid escape sequence.
Such sequences will not work in the future. Did you mean "\\S"? A raw string is also an option.
  """DB에 저장된 \\SERVER\SHARE\path 를 /mnt/nas/path 로 변환"""

python manage.py check를 돌릴 때마다 이 경고가 뜨는데, 기능상 문제는 없어서 계속 넘어가고 있었다. 근데 같은 파일을 만질 때마다 반복해서 뜨길래, 정확히 왜 뜨는지 짚어봤다.

핵심 — "비슷한 내용"이 아니라 "문자열 리터럴 안인가"가 기준

이 경고는 내용이 비슷해서 뜨는 게 아니라, Python이 실제로 파싱하는 문자열 리터럴(따옴표로 감싼 것) 안에, Python이 모르는 이스케이프 조합이 있을 때만 뜬다. 두 가지를 구분해야 한다.

1. # 주석은 절대 해당 안 됨

#으로 시작하는 줄은 Python이 문자열로 파싱하지 않고 통째로 무시한다. 그 안에 백슬래시가 몇 개 있든 경고가 안 뜬다.

2. """...""" docstring이나 "..."/'...' 문자열은 실제 문자열 리터럴

Python이 이 안에 있는 \ 뒤에 오는 글자를 이스케이프 시퀀스로 해석하려고 시도한다.

• \n, \t, \\, \" 처럼 Python이 아는 조합이면 조용히 넘어간다
• \)나 \S, \p처럼 Python이 모르는 조합이면 "지금은 그냥 백슬래시+글자 그대로 넣어주지만, 나중 버전에서는 에러가 될 거다"라고 경고한다

이번 케이스

• "파일구분문자(/, \), 제어문자..." 안의 \) (백슬래시+닫는 괄호) → Python이 모르는 조합
• "\\SERVER\SHARE\path" 안의 \S, \p (백슬래시+S, 백슬래시+p) → 역시 모르는 조합

Windows 경로(\\SERVER\SHARE\...)를 설명하는 docstring을 적다가, 일반 문자열인 걸 깜빡하고 백슬래시를 그대로 써넣은 경우였다.

해결 — raw string

r"""DB에 저장된 \\SERVER\SHARE\path 를 /mnt/nas/path 로 변환"""

문자열 앞에 r을 붙이면 raw string이 된다. raw string 안에서는 백슬래시가 이스케이프 문자로 취급되지 않고, 그냥 문자 그대로(\ 자체)로 처리된다. 그래서 \), \S 같은 걸 백슬래시+글자 조합으로 그대로 두고 싶을 때(정규식 패턴, Windows 경로 설명 등) raw string이 정확히 맞는 도구다.

프로젝트 전체를 다시 훑어봤다

비슷한 경고가 다른 곳에도 있을까 싶어서 apps/ 트리 전체를 백슬래시 패턴으로 검색해봤다. 결과는:

• 실제로 문제였던 건 이번에 고친 2곳뿐
• 나머지 검색된 곳들은 전부 이미 r"..." / r'...'로 시작하거나, # 주석이라 애초에 경고 대상이 아니었다:
  • Windows 경로를 다루는 곳들 (r"\\NAS_SERVER\Shared") — raw string으로 이미 잘 처리됨
  • 정규식을 쓰는 곳들 (re.sub(r'...'), re.compile(r"..."), re.search(r"\(...\)$")) — 마찬가지로 raw string
  • \\처럼 이미 올바르게 이스케이프된 문자열

즉 이 프로젝트는 정규식이나 Windows 경로처럼 백슬래시가 들어가는 문자열엔 이미 대체로 raw string을 잘 써왔고, 이번에 걸린 두 곳만 docstring이라 raw string 표시를 깜빡한 경우였다. "이 파일을 만질 때마다 반복해서 떴다"고 느꼈던 건, 정확히 그 파일 안의 이 두 줄이 매번 걸렸기 때문이었다.

정리

• SyntaxWarning: invalid escape sequence는 문자열 리터럴 안(docstring 포함)에서만 뜬다 — 주석(#)은 절대 대상이 아니다
• 백슬래시 뒤에 Python이 아는 이스케이프 문자(n, t, \, " 등)가 아닌 글자가 오면 경고가 뜬다
• Windows 경로, 정규식 패턴처럼 백슬래시를 문자 그대로 쓰고 싶은 문자열은 항상 r"..." (raw string)로 선언하는 게 안전하다
• 경고가 하나 발견되면, 같은 패턴이 프로젝트 전체에 더 있는지 한 번 검색해서 훑어보는 게 재발을 줄이는 방법이다