이 도구는 대부분의 Python 프로젝트가 이미 합의한 포맷터인 Black을, 붙여넣은 내용에 대해 당신이 선택한 줄 길이와 인용 부호 처리 방식으로 실행합니다. 파일을 파싱할 수 없으면 어느 줄인지 알려주고, 이미 포맷되어 있다면 뭔가 한 것처럼 꾸미지 않고 그 사실도 알려줍니다.
Python을 포맷하는 데 그것을 실행할 필요는 없습니다. 코드는 구문 트리로 파싱되고 그 트리로부터 완전히 메모리상에서 다시 작성됩니다 - 파일에 쓰여지지도, 임포트되지도, 실행되지도 않습니다. 붙여넣은 내용을 실행하는 포맷터가 있다면, 그것은 텍스트 상자가 달린 원격 셸일 뿐입니다.
Black은 AST를 보존하는 변환입니다. 나오는 코드는 들어간 코드와 같은 프로그램입니다. 이 속성이야말로 포맷터를 신뢰할 수 있는 유일한 이유이며, 이 도구의 어느 부분에도 언어 모델이 관여하지 않는 이유입니다. 코드를 정리하라는 요청을 받은 모델은 작업 중에 가끔 한 줄을 다시 쓰게 되며, 작동하는 코드에 대한 조용한 변경은 포맷터가 감당할 수 없는 단 하나의 실패입니다.
CI가 묻는 것과 같은 질문입니다. 이 파일이 변경될까요? 검사 모드는 원본 코드를 그대로 반환하고 Black이 그것을 다시 포맷했을지, 몇 줄이나 바뀌었을지를 알려줍니다. 로컬에서 재현할 수 없는 파일에서 파이프라인이 실패하는 이유를 빠르게 알아내는 방법입니다.
마지막 항목 뒤의 쉼표는 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 정렬은 Black의 일이 아니라 isort의 일이며, 둘은 충분히 자주 의견이 달라서 여기서 그렇게 했다면 당신을 놀라게 했을 것입니다.
어떤 포맷터도 할 수 없습니다 - 파싱할 수 없는 파일에는 다시 쓸 구조가 없습니다. 줄, 열, 주변 코드를 받아서 고친 뒤 다시 시도할 수 있습니다.
Black은 한 가지 잘 알려진 예외를 제외하면 PEP 8과 호환됩니다. 기본 줄 길이는 79가 아니라 88입니다. 더 엄격한 수치가 필요하면 줄 길이 선택기에서 79를 고르세요.
한 번에 최대 400,000자입니다. 포맷은 10초가 지나면 중단되며, 이는 매우 크거나 반복이 심한 파일에서만 일어납니다. IP 주소마다 10분에 30번까지 포맷할 수 있습니다.
이 페이지는 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 포맷터는 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로 파일을 확인하세요.