# Python 포맷터

URL: https://discuvr.org/python-formatter/?hl=ko
Last updated: 2026-11-07
MCP tool: `format_python`

Python 코드를 붙여넣으면 원하는 줄 길이와 옵션으로 Black이 포맷팅해 줍니다. 구문 오류는 정확한 줄을 표시합니다. 코드는 절대 실행되거나 저장되지 않습니다.

이 도구는 대부분의 Python 프로젝트가 이미 합의한 포맷터인 Black을, 붙여넣은 내용에 대해 당신이 선택한 줄 길이와 인용 부호 처리 방식으로 실행합니다. 파일을 파싱할 수 없으면 어느 줄인지 알려주고, 이미 포맷되어 있다면 뭔가 한 것처럼 꾸미지 않고 그 사실도 알려줍니다.

## 기능

- 79, 88, 100 또는 120열로 Black 포맷팅.
- "검사만 하기" 모드: 파일을 변경하지 않고도 변경 여부를 알 수 있습니다.
- 자신만의 인용 부호 스타일을 유지하거나, Black이 정규화하도록 둘 수 있습니다.
- 컬렉션을 펼쳐진 상태로 유지하는 매직 트레일링 커마를 따르거나 무시할 수 있습니다.
- 문법이 버전에 민감할 때 특정 Python 버전을 대상으로 지정할 수 있습니다.
- 구문 오류는 줄, 열, 주변 코드를 알려줍니다.
- 추가되고 삭제된 줄 수와 파일의 형태를 알려줍니다.

## 작동 방식

1. 코드를, 또는 파일 하나 분량을 붙여넣습니다.
2. 줄 길이와 관심 있는 옵션을 선택합니다.
3. 포맷을 누른 다음 결과를 복사하거나 다운로드합니다.

## 당신의 코드는 결코 실행되지 않습니다

Python을 포맷하는 데 그것을 실행할 필요는 없습니다. 코드는 구문 트리로 파싱되고 그 트리로부터 완전히 메모리상에서 다시 작성됩니다 - 파일에 쓰여지지도, 임포트되지도, 실행되지도 않습니다. 붙여넣은 내용을 실행하는 포맷터가 있다면, 그것은 텍스트 상자가 달린 원격 셸일 뿐입니다.

## 왜 Black인가, 우리만의 의견이 아닌 이유

Black은 AST를 보존하는 변환입니다. 나오는 코드는 들어간 코드와 같은 프로그램입니다. 이 속성이야말로 포맷터를 신뢰할 수 있는 유일한 이유이며, 이 도구의 어느 부분에도 언어 모델이 관여하지 않는 이유입니다. 코드를 정리하라는 요청을 받은 모델은 작업 중에 가끔 한 줄을 다시 쓰게 되며, 작동하는 코드에 대한 조용한 변경은 포맷터가 감당할 수 없는 단 하나의 실패입니다.

## 검사만 하기

CI가 묻는 것과 같은 질문입니다. 이 파일이 변경될까요? 검사 모드는 원본 코드를 그대로 반환하고 Black이 그것을 다시 포맷했을지, 몇 줄이나 바뀌었을지를 알려줍니다. 로컬에서 재현할 수 없는 파일에서 파이프라인이 실패하는 이유를 빠르게 알아내는 방법입니다.

## 매직 마지막 쉼표와 fmt: off 실전 예시

마지막 항목 뒤의 쉼표는 Black에게 호출이나 컬렉션을 한 줄에 한 항목씩 유지하라고 알려 줍니다. result = compute(alpha, beta,)는 네 줄로 돌아오며 alpha,와 beta,가 각각 자기 줄에 놓입니다. 매직 마지막 쉼표 무시를 체크하면 같은 입력이 줄 길이에 들어가는 한 result = compute(alpha, beta)가 됩니다. 행렬처럼 손으로 정렬한 블록을 지키려면 그 위 줄에 # fmt: off, 아래에 # fmt: on을 쓰세요. Black은 그 사이를 작성한 그대로 둡니다. 줄 끝의 # fmt: skip은 그 한 줄만 보호합니다. 모두 Black 자체의 주석이라 프로젝트 CI가 Black을 실행할 때도 그대로 적용됩니다.

## 질문

**내 코드가 업로드되거나 저장되나요?**

서버로 전송되어 메모리에서 포맷된 뒤 같은 응답으로 반환됩니다. 디스크에 기록되거나 캐시되거나 로그에 남는 것은 전혀 없으며, 사용 기록에는 크기, 옵션, 변경된 줄 수 같은 개수만 남고 코드 자체는 절대 남지 않습니다.

**포맷팅이 내 코드가 하는 일을 바꾸나요?**

아니요. Black은 동작이 아니라 레이아웃을 바꾸지만, 공백만 옮기는 것은 아닙니다. 불필요한 괄호를 없애고(x = (1)은 x = 1로), 숫자의 접두사와 지수를 소문자로 바꾸며(0XABCDEF는 0xABCDEF로, 1E5는 1e5로), 호출을 여러 줄로 나눌 때 끝에 쉼표를 붙이고, 연속된 빈 줄을 줄이며, docstring 안쪽의 공백을 잘라냅니다(""" Doc. """는 """Doc."""로). 마지막 변경은 __doc__의 텍스트를 바꾸므로, 코드가 자기 docstring을 읽을 때만 영향이 있습니다.

**왜 내 파일이 전혀 다시 포맷되지 않았나요?**

당신이 선택한 줄 길이로 이미 포맷되어 있었기 때문입니다. 이 도구는 조용히 복사본을 반환하는 대신 "이미 포맷됨"이라고 알려줍니다.

**제 import를 정렬하나요?**

아니요. import 정렬은 Black의 일이 아니라 isort의 일이며, 둘은 충분히 자주 의견이 달라서 여기서 그렇게 했다면 당신을 놀라게 했을 것입니다.

**구문 오류가 있는 파일을 포맷할 수 있나요?**

어떤 포맷터도 할 수 없습니다 - 파싱할 수 없는 파일에는 다시 쓸 구조가 없습니다. 줄, 열, 주변 코드를 받아서 고친 뒤 다시 시도할 수 있습니다.

**PEP 8을 따르나요?**

Black은 한 가지 잘 알려진 예외를 제외하면 PEP 8과 호환됩니다. 기본 줄 길이는 79가 아니라 88입니다. 더 엄격한 수치가 필요하면 줄 길이 선택기에서 79를 고르세요.

**얼마나 큰 파일을 포맷할 수 있나요?**

한 번에 최대 400,000자입니다. 포맷은 10초가 지나면 중단되며, 이는 매우 크거나 반복이 심한 파일에서만 일어납니다. IP 주소마다 10분에 30번까지 포맷할 수 있습니다.

**에디터, pre-commit, CI에서 같은 포맷 결과를 얻으려면 어떻게 하나요?**

이 페이지는 Black을 실행하며, 넓은 화면에서는 페이지 상단 헤더에 버전이 표시됩니다. Black은 프로젝트 설정을 pyproject.toml의 [tool.black] 섹션에서 옵션의 긴 이름으로 읽습니다. 선택한 "줄 길이"에는 line-length = 88, "작은따옴표 유지"를 체크했다면 skip-string-normalization = true, "매직 마지막 쉼표 무시"에는 skip-magic-trailing-comma = true, "대상"에서 고정한 버전에는 target-version = ["py311"]을 씁니다. 에디터 플러그인과 pre-commit 훅도 같은 파일을 읽습니다. 포맷은 black . 으로, CI에서는 black --check --diff . 를 실행하세요. 아무것도 바꾸지 않고, 다시 포맷될 파일이 있으면 종료 코드 1로 끝납니다. 매 달력 연도의 첫 릴리스에서 안정 스타일이 바뀔 수 있으므로 이 페이지와 같은 Black 버전으로 고정하세요.

**결과가 Ruff 포맷터(ruff format)와 같나요?**

거의 항상 같지만 바이트 단위로 같지는 않습니다. Ruff 포맷터는 Black을 그대로 대체하도록 설계되었고, Ruff 문서에 따르면 Django나 Zulip처럼 Black으로 포맷된 대규모 프로젝트에서 99.9%가 넘는 줄이 동일하게 나옵니다. Black을 거친 적 없는 코드, 특히 줄 끝 주석에서는 차이가 더 크며, 의도적인 차이는 문서에 정리되어 있습니다. 기본 줄 길이도 88이며 [tool.ruff]의 line-length로 설정합니다. [tool.ruff.format]의 quote-style = "preserve"는 "작은따옴표 유지"에, skip-magic-trailing-comma = true는 "매직 마지막 쉼표 무시"에 해당합니다. CI에서 ruff format --check를 실행한다면 이 페이지가 아니라 Ruff로 파일을 확인하세요.

## 개발자 도구의 다른 도구

- [HTML 뷰어](https://discuvr.org/html-viewer/?hl=ko)
- [IP 서브넷 계산기](https://discuvr.org/ip-subnet-calculator/?hl=ko)
- [인코딩 / 디코딩](https://discuvr.org/encode-decode/?hl=ko)
- [Unix 타임스탬프 변환기](https://discuvr.org/timestamp-converter/?hl=ko)

## 함께 자주 쓰는 도구

- [텍스트 비교](https://discuvr.org/text-diff/?hl=ko)
- [대소문자 변환기 및 줄 도구](https://discuvr.org/case-converter/?hl=ko)
- [Study Buddy](https://discuvr.org/study-buddy/?hl=ko)

---

Part of Discuvr (https://discuvr.org/): Discuvr is a collection of free, focused tools for day-to-day professional work - office and data utilities, legal and compliance helpers, privacy and security checks, and developer formatters. Every tool has its own page, and most can also be called from ChatGPT or Claude over MCP.