PEP 12 – reStructuredText PEP 템플릿 예시
- Author:
- David Goodger <goodger at python.org>, Barry Warsaw <barry at python.org>, Brett Cannon <brett at python.org>
- Status:
- Active
- Type:
- Process
- Created:
- 05-Aug-2002
- Post-History:
- 30-Aug-2002 22-Feb-2026
번역·라이선스 안내
이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain or CC0-1.0, whichever is more permissive 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판
Note
이전에 PEP를 작성해 본 적이 있는 분들을 위해 template이 있습니다(이는 PEPs repository에 파일로 포함되어 있습니다).
요약
이 PEP는 여러분 자신의 reStructuredText PEP를 작성하기 위한 상용구 또는 샘플 템플릿을 제공합니다. 여러분은 PEP 1의 콘텐츠 지침을 함께 활용해 아래 형식에 맞는 PEP를 쉽게 작성할 수 있습니다.
참고: 만약 웹을 통해 이 PEP를 읽고 있다면, 아래 단계를 완료하기 위해 먼저 이 PEP의 텍스트(reStructuredText) 소스를 가져와야 합니다. HTML 파일을 템플릿으로 사용하지 마십시오!
이(또는 어떤) PEP의 소스는 PEPs 저장소에서 찾을 수 있으며, 각 PEP 하단의 링크를 통해서도 찾을 수 있습니다.
명세
PEP를 제출하려는 경우, 형식 문제로 인해 제출이 자동으로 거부되지 않도록 아래의 형식 지침과 함께 반드시 이 템플릿을 사용해야 합니다.
근거
reStructuredText는 원본 텍스트에서 쉬운 가독성을 유지하면서도 PEP 저자들에게 유용한 기능성과 표현력을 제공합니다. 처리된 HTML 형식은 활성 하이퍼링크, 스타일이 적용된 텍스트, 표, 이미지, 자동 목차 등 여러 이점을 통해 독자들이 이러한 기능에 접근할 수 있게 해줍니다.
이 템플릿 사용 방법
이 템플릿을 사용하려면 먼저 여러분의 PEP가 정보성(Informational) PEP인지 표준 트랙(Standards Track) PEP인지를 결정해야 합니다. 대부분의 PEP는 Python 언어나 표준 라이브러리에 새로운 기능을 제안하기 때문에 표준 트랙입니다. 확실하지 않다면 자세한 내용은 PEP 1을 읽거나, PEPs 저장소에서 트래커 이슈를 열어 도움을 요청하십시오.
여러분의 PEP가 어떤 유형이 될지 결정했다면, 아래의 지침을 따르십시오.
- 이 파일(
.rst파일이며, HTML은 아닙니다!)의 사본을 만들고 다음의 편집 작업을 수행하십시오. 새 파일의 이름은pep-NNNN.rst로 지정하되, (공개되었거나 PR로 제출된 PEP에서 사용되지 않은) 다음으로 사용 가능한 번호를 사용하십시오. - “PEP: 12” 헤더를 파일 이름과 일치하는 “PEP: NNNN”으로 교체하십시오. 파일 이름은 0으로 채워야 하지만(예:
pep-0012.rst), 헤더는 그렇지 않다는 점(PEP: 12)에 유의하십시오. - Title 헤더를 여러분의 PEP 제목으로 변경하십시오.
- Author 헤더를 여러분의 이름과, 선택적으로 이메일 주소를 포함하도록 변경하십시오. 형식을 신중하게 따르십시오: 이름이 먼저 나와야 하며, 괄호 안에 포함되어서는 안 됩니다. 이메일 주소는 두 번째로 나올 수 있으며(생략할 수도 있음), 나올 경우 꺾쇠괄호 안에 표시되어야 합니다. 이메일 주소를 난독화하는 것은 괜찮습니다.
- 저자 중 파이썬 코어 개발자가 없다면, 여러분의 PEP를 후원하는 코어 개발자의 이름을 Sponsor 헤더에 포함하십시오.
- PEP의 정식 논의 스레드(예: Python-Dev, Discourse 등)의 직접 URL을 Discussions-To 헤더 아래에 추가하십시오. 스레드가 PEP가 공식 초안으로 제출된 이후에 생성될 예정이라면, 처음에는 그냥 “Pending”이라고 적어도 괜찮지만, PEP가 PEPs 저장소에 성공적으로 병합되고 해당 논의 스레드를 생성하는 즉시 URL로 PEP를 업데이트해야 함을 기억하십시오. 자세한 내용은 PEP 1를 참조하십시오.
- Status 헤더를 “Draft”로 변경하십시오.
- Standards Track PEP의 경우, Type 헤더를 “Standards Track”으로 변경하십시오.
- 정보용(Informational) PEP의 경우, Type 헤더를 “Informational”로 변경하십시오.
- 표준 트랙(Standards Track) PEP의 경우, 여러분의 기능이 현재 개발 중인 다른 PEP의 승인에 의존한다면, Type 헤더 바로 뒤에 Requires 헤더를 추가하십시오. 그 값은 여러분의 PEP가 의존하는 PEP의 번호여야 합니다. 의존하는 기능이 Final 상태의 PEP에 기술되어 있다면 이 헤더를 추가하지 마십시오.
- Created 헤더를 오늘 날짜로 변경하십시오. 형식을 반드시 정확히 지키십시오.
DD-MMM-YYYY형식이어야 하며, 여기서MMM은 영문 월 이름의 세 글자 약어로, 즉 Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec 중 하나입니다. - 표준 트랙 PEP의 경우, Created 헤더 뒤에 Python-Version 헤더를 추가하고 그 값을 Python의 다음 예정 버전, 즉 여러분의 새 기능이 처음 등장하기를 바라는 버전으로 설정하십시오. 여기에는 alpha나 beta 릴리스 지정을 사용하지 마십시오. 따라서 Python의 마지막 버전이 2.2 alpha 1이었고 여러분의 새 기능을 Python 2.2에 넣고자 한다면, 헤더를 다음과 같이 설정하십시오:
Python-Version: 2.2
- PEP가 주제별 색인에 표시된 항목 중 하나에 속한다면 Topic 헤더를 추가하십시오. 대부분의 PEP는 그렇지 않습니다.
- Post-History는 당분간 ‘Pending’으로 둘 수 있으며, 여러분이 지정된 토론 포럼에 PEP를 게시할 때마다 이 헤더에 날짜와 해당 링크를 추가하게 됩니다(그리고 위에서와 같이 해당 링크로 Discussions-To 헤더를 갱신합니다). 각 스레드에 대해, 날짜(
DD-MMM-YYYY형식)를 링크 텍스트로 사용하고, URL을 익명 reST Hyperlinks로 인라인 삽입하되, 게시물마다 쉼표로 구분하십시오.만약 여러분이 PEP에 대한 스레드를 2001년 8월 14일과 2001년 9월 3일에 게시했다면, Post-History 헤더는 예를 들어 다음과 같이 보일 것입니다:
Post-History: `14-Aug-2001 <https://www.example.com/thread_1>`__, `03-Sept-2001 <https://www.example.com/thread_2>`__
새로운 토론 스레드를 게시하자마자 여기에 새 날짜/링크를 추가해야 합니다.
- PEP가 이전 PEP를 대체하는 경우 Replaces 헤더를 추가하십시오. 이 헤더의 값은 새 PEP가 대체하는 PEP의 번호입니다. 이전 PEP가 “최종(final)” 형태, 즉 Accepted, Final, Rejected 중 하나인 경우에만 이 헤더를 추가하십시오. 경쟁하는 아이디어를 제출하는 것이라면 열려 있는 이전 PEP를 대체하는 것이 아닙니다.
- 이제 PEP의 초록(Abstract), 근거(Rationale), 그리고 그 밖의 내용을 작성하여, 이 알아볼 수 없는 텍스트를 여러분 자신의 글로 대체하십시오. 아래의 형식 지침, 특히 탭 문자 금지와 들여쓰기 요구 사항을 반드시 준수하십시오. 포함할 섹션의 템플릿은 아래의 “Suggested Sections”를 참조하십시오.
- 텍스트에서 참조하는 각주와 인라인이 아닌 링크 대상을 나열하여 Footnotes 섹션을 갱신하십시오.
./build.py를 실행하여 PEP가 오류 없이 렌더링되는지 확인하고,build/pep-NNNN.html의 출력이 의도한 대로인지 확인하십시오.- PEPs repository에 풀 리퀘스트를 생성하십시오.
참고로, 가능한 모든 헤더 필드는 다음과 같습니다(대괄호 안의 내용은 모두 대체해야 하며, 선택 사항임을 나타내는 *로 시작하고 여러분의 PEP에 해당하지 않는 필드는 제거해야 합니다):
PEP: [NNN]
Title: [...]
Author: [Full Name <email at example.com>]
Sponsor: *[Full Name <email at example.com>]
PEP-Delegate:
Discussions-To: [URL]
Status: Draft
Type: [Standards Track | Informational | Process]
Topic: *[Governance | Packaging | Release | Typing]
Requires: *[NNN]
Created: [DD-MMM-YYYY]
Python-Version: *[M.N]
Post-History: [`DD-MMM-YYYY <URL>`__]
Replaces: *[NNN]
Superseded-By: *[NNN]
Resolution:
reStructuredText PEP 형식 요구 사항
다음은 PEP에 특화된 reStructuredText 문법 요약입니다. 간결함과 간명함을 위해 많은 세부 사항이 생략되어 있습니다. 더 자세한 내용은 아래의 Resources를 참조하십시오. 순수 텍스트 마크업을 보여주기 위해, 마크업 처리가 이루어지지 않는 Literal Blocks가 전체에 걸쳐 예제로 사용됩니다.
일반 사항
URL 및 이와 유사한 경우를 제외하고, 줄은 일반적으로 79번째 열을 넘어서는 안 됩니다. 탭 문자는 문서 어디에도 절대 나타나서는 안 됩니다.
섹션 제목
PEP 제목은 0번째 열에서 시작해야 하며, 각 단어의 첫 글자는 책 제목에서와 같이 대문자로 표기해야 합니다. 약어는 모두 대문자로 표기해야 합니다. 섹션 제목에는 밑줄을 달아야 하며, 이는 0번째 열에서 시작하고 제목 텍스트의 오른쪽 끝까지는 최소한 이어져야 하는(최소 4자) 단일 문장 부호를 반복한 것입니다. 1단계 섹션 제목은 “=”(등호)로, 2단계 섹션 제목은 “-“(하이픈)로, 3단계 섹션 제목은 “’”(작은따옴표)로 밑줄을 긋습니다. 예를 들면:
First-Level Title
=================
Second-Level Title
------------------
Third-Level Title
'''''''''''''''''
PEP에 3단계보다 많은 수준의 섹션이 있는 경우, 다음과 같이 1단계와 2단계에 위아래 줄(overline/underline)로 장식된 제목을 넣을 수 있습니다.:
============================
First-Level Title (optional)
============================
-----------------------------
Second-Level Title (optional)
-----------------------------
Third-Level Title
=================
Fourth-Level Title
------------------
Fifth-Level Title
'''''''''''''''''
PEP에 5단계보다 많은 수준의 섹션을 두어서는 안 됩니다. 만약 그렇게 되었다면, 다시 작성하는 것을 고려해야 합니다.
섹션 본문의 마지막 줄과 다음 섹션 제목 사이에는 빈 줄을 두 줄 사용해야 합니다. 하위 섹션 제목이 섹션 제목 바로 다음에 오는 경우에는, 그 사이에 빈 줄 한 줄이면 충분합니다.
아래에서 설명하는 몇몇 구성 요소는 들여쓰기를 사용하지만, 각 섹션의 본문은 일반적으로 들여쓰기하지 않습니다. 구성 요소를 구분하는 데는 빈 줄을 사용합니다.
문단
문단은 빈 줄로 구분되는 왼쪽 정렬된 텍스트 블록입니다. 문단은 (블록 인용문이나 목록 항목처럼) 들여쓰기된 구성체의 일부가 아닌 이상 들여쓰지 않습니다.
인라인 마크업
문단과 기타 텍스트 블록 내의 텍스트 일부는 스타일이 지정될 수 있습니다. 예를 들면:
Text may be marked as *emphasized* (single asterisk markup,
typically shown in italics) or **strongly emphasized** (double
asterisks, typically boldface). ``Inline literals`` (using double
backquotes) are typically rendered in a monospaced typeface. No
further markup recognition is done within the double backquotes,
so they're safe for any kind of code snippets.
블록 인용문
블록 인용문은 들여쓰기된 본문 요소로 구성됩니다. 예를 들면:
This is a paragraph.
This is a block quote.
A block quote may contain many paragraphs.
블록 인용문은 다른 출처에서 발췌한 긴 구절을 인용하는 데 사용됩니다. 블록 인용문은 다른 본문 요소 안에 중첩될 수 있습니다. 들여쓰기 수준마다 공백 4개를 사용하십시오.
리터럴 블록
리터럴 블록은 코드 샘플과 기타 미리 서식이 지정된 텍스트에 사용됩니다. 리터럴 블록을 나타내려면 들여쓰기된 텍스트 블록 앞에 “::”(콜론 두 개)를 붙이거나 .. code-block:: 지시어를 사용하십시오. 텍스트 블록을 공백 4개로 들여쓰십시오. 리터럴 블록은 들여쓰기가 끝날 때까지 계속됩니다. 예를 들면:
This is a typical paragraph. A literal block follows.
::
for a in [5, 4, 3, 2, 1]: # this is program code, shown as-is
print(a)
print("it's...")
“::”는 모든 단락의 끝에서도 인식됩니다. 다만 바로 앞에 공백이 없으면 최종 출력에 콜론 하나가 그대로 남습니다.:
This is an example::
Literal block
기본적으로 리터럴 블록은 Python 코드로 구문 강조됩니다. 다른 언어나 형식의 코드나 데이터를 담은 특정 블록에는 .. code-block:: language 지시어를 사용하여, language 자리에 해당하는 Pygments lexer의 “짧은 이름”(강조 표시를 비활성화하려면 text)을 대입하십시오. 예를 들어:
.. code-block:: rst
An example of the ``rst`` lexer (i.e. *reStructuredText*).
특정 언어의 리터럴 블록을 주로 담은 PEP에서는, PEP 본문 상단(헤더 아래, 초록 위)에 적절한 language를 지정하여 .. highlight:: language 지시어를 사용하십시오. 그러면 특정 .. code-block에서 달리 지정하지 않는 한, 모든 리터럴 블록이 해당 언어로 처리됩니다. 예를 들어:
.. highlight:: c
Abstract
========
Here's some C code::
printf("Hello, World!\n");
목록
글머리 기호 목록 항목은 “-”, “*”, “+”(하이픈, 별표, 더하기 기호) 중 하나로 시작하며, 그 뒤에 공백과 목록 항목 본문이 옵니다. 목록 항목 본문은 왼쪽 정렬되어야 하며 글머리 기호를 기준으로 들여써야 합니다. 글머리 기호 바로 뒤의 텍스트가 들여쓰기 수준을 결정합니다. 예를 들어:
This paragraph is followed by a list.
* This is the first bullet list item. The blank line above the
first list item is required; blank lines between list items
(such as below this paragraph) are optional.
* This is the first paragraph in the second item in the list.
This is the second paragraph in the second item in the list.
The blank line above this paragraph is required. The left edge
of this paragraph lines up with the paragraph above, both
indented relative to the bullet.
- This is a sublist. The bullet lines up with the left edge of
the text blocks above. A sublist is a new list so requires a
blank line above and below.
* This is the third item of the main list.
This paragraph is not part of the list.
번호 매김 목록 항목도 이와 비슷하지만, 글머리 기호 대신 번호 매기기 기호를 사용합니다. 번호 매기기 기호는 숫자(1, 2, 3, …), 문자(A, B, C, …; 대문자 또는 소문자), 또는 로마 숫자(i, ii, iii, iv, …; 대문자 또는 소문자)이며, 마침표 접미사(“1.”, “2.”), 괄호(“(1)”, “(2)”), 또는 오른쪽 괄호 접미사(“1)”, “2)”)로 표기됩니다. 예를 들어:
1. As with bullet list items, the left edge of paragraphs must
align.
2. Each list item may contain multiple paragraphs, sublists, etc.
This is the second paragraph of the second list item.
a) Enumerated lists may be nested.
b) Blank lines may be omitted between list items.
정의 목록은 다음과 같이 작성합니다.:
what
Definition lists associate a term with a definition.
how
The term is a one-line phrase, and the definition is one
or more paragraphs or body elements, indented relative to
the term.
표
간단한 테이블은 쉽고 간결합니다:
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
테이블에는 최소 두 개의 열이 있어야 합니다(섹션 제목과 구별하기 위함입니다). 열 병합은 하이픈으로 된 밑줄을 사용합니다(“Inputs”가 처음 두 열에 걸쳐 있습니다):
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======
첫 번째 열 셀에 텍스트가 있으면 새 행이 시작됩니다. 첫 번째 열에 텍스트가 없으면 이어지는 줄임을 나타내며, 나머지 셀은 여러 줄로 구성될 수 있습니다. 예를 들면:
===== =========================
col 1 col 2
===== =========================
1 Second column of row 1.
2 Second column of row 2.
Second line of paragraph.
3 - Second column of row 3.
- Second item in bullet
list (row 3, column 2).
===== =========================
하이퍼링크
PEP 본문에서 외부 웹 페이지를 참조할 때는, 인라인 하이퍼링크나 URL이 포함된 별도의 명시적 대상을 사용하여 텍스트에 페이지 제목이나 적절한 설명을 포함해야 합니다. PEP 본문 텍스트에 URL을 그대로 포함하지 말고, 가능한 경우 항상 HTTPS 링크를 사용하십시오.
하이퍼링크 참조는 역따옴표와 뒤에 붙는 밑줄을 사용하여 참조 텍스트를 표시하며, 참조 텍스트가 한 단어인 경우 역따옴표는 생략할 수 있습니다. 예를 들어, Python website라는 이름의 하이퍼링크 대상을 참조하려면 다음과 같이 작성합니다:
In this paragraph, we refer to the `Python website`_.
링크를 한 번만 참조하려 하고 텍스트와 함께 인라인으로 정의하려는 경우, 링크로 연결하려는 텍스트 뒤, 닫는 역따옴표 앞에 꺾쇠괄호(<>)를 삽입하되, 텍스트와 여는 역따옴표 사이에는 공백을 둡니다. 또한 닫는 역따옴표 뒤에는 홑밑줄 대신 겹밑줄을 사용해야 하는데, 이는 다른 대상 이름과의 충돌을 피하는 익명 참조로 만들어 줍니다. 예를 들면:
Visit the `website <https://www.python.org/>`__ for more.
하나의 링크를 여러 곳에서 다른 링크 텍스트로 사용하고 싶거나, 링크 텍스트를 변경할 때마다 링크 대상 이름을 갱신하지 않도록 하려면, 링크로 연결할 텍스트 뒤에 대상 이름을 꺾쇠괄호 안에 포함하되, 대상 이름 뒤와 닫는 꺾쇠괄호 앞에 밑줄을 넣어야 합니다 (그렇지 않으면 링크가 작동하지 않습니다). 예를 들면:
For further examples, see the `documentation <pydocs_>`_.
명시적 타겟은 URL을 제공합니다. 타겟은 PEP 끝의 각주 섹션에 두거나, 참조가 있는 문단 바로 뒤에 둡니다. 하이퍼링크 타겟은 마침표 두 개와 공백(“명시적 마크업 시작”)으로 시작하고, 그 뒤에 선행 밑줄, 참조 텍스트, 콜론, URL이 이어집니다.
.. _Python web site: https://www.python.org/
.. _pydocs: https://docs.python.org/
참조 텍스트와 타겟 텍스트는 일치해야 합니다(단, 대소문자를 구분하지 않고 공백 차이는 무시됩니다). 밑줄이 참조 텍스트 뒤에는 오지만 타겟 텍스트 앞에는 온다는 점에 유의하십시오. 밑줄을 오른쪽을 가리키는 화살표라고 생각하면, 화살표는 참조에서 멀어지고 타겟을 향합니다.
내부 링크 및 PEP/RFC 링크
하이퍼링크와 동일한 메커니즘을 내부 참조에도 사용할 수 있습니다. 고유한 섹션 제목은 각각 암묵적으로 내부 하이퍼링크 타겟을 정의합니다. 초록 섹션에 대한 링크는 다음과 같이 만들 수 있습니다:
Here is a hyperlink reference to the `Abstract <yeokja-pep-0012-target-625_>`_ section. The
backquotes are optional since the reference text is a single word;
we can also just write: Abstract_.
PEP나 RFC를 참조할 때는 하드코딩된 URL을 절대 사용하지 말고, 항상 :pep: 롤과 :rfc: 롤을 사용하십시오. 예를 들면:
See :pep:`1` for more information on how to write a PEP,
and :pep:`the Hyperlink section of PEP 12 <12#hyperlinks>` for how to link.
이는 다음과 같이 렌더링됩니다:
PEP 작성 방법에 대한 자세한 내용은 PEP 1을 참고하고, 링크 방법에 대해서는 PEP 12의 하이퍼링크 섹션을 참고하십시오.
본문에서 PEP 번호는 절대 0으로 채우지 않으며, “PEP”나 “RFC”와 숫자 사이에는 (대시가 아닌) 공백이 들어갑니다. 위의 롤을 사용하면 이 부분은 자동으로 처리됩니다.
각주
각주 참조는 왼쪽 대괄호, 레이블, 오른쪽 대괄호, 그리고 뒤따르는 밑줄로 구성됩니다. 숫자 대신 “#word” 형식의 레이블을 사용하십시오. 여기서 “word”는 영숫자와 내부 하이픈, 밑줄, 마침표로 이루어진 기억하기 쉬운 이름입니다(공백이나 다른 문자는 허용되지 않습니다). 예를 들면 다음과 같습니다:
Refer to The TeXbook [#TeXbook]_ for more information.
이는 다음과 같이 렌더링됩니다:
자세한 내용은 The TeXbook [1]을 참조하십시오.
각주 참조 앞에는 공백이 있어야 합니다. 각주 참조와 그 앞 단어 사이에 공백을 남기십시오.
온라인에서 쉽게 구할 수 없는 서적이나 기타 출처에 대한 참조뿐만 아니라 추가 참고 사항, 설명, 주의 사항에도 각주를 사용하십시오. 온라인 리소스에 대한 URL을 포함할 때는 각주보다 reST 고유의 하이퍼링크 타깃이나 텍스트 내 인라인 하이퍼링크를 우선적으로 사용해야 합니다.
각주는 “.. “(명시적 마크업 시작)로 시작하며, 그 뒤에 각주 마커(밑줄 없이)가 오고, 그다음에 각주 본문이 옵니다. 예를 들면 다음과 같습니다:
.. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
이는 다음과 같이 렌더링됩니다:
각주와 각주 참조는 자동으로 번호가 매겨지며, 번호는 항상 일치합니다.
이미지
PEP에 다이어그램이나 다른 그래픽이 포함되어 있다면, image 지시어를 사용하여 처리된 출력물에 포함할 수 있습니다:
.. image:: diagram.png
브라우저 친화적인 그래픽 형식이면 무엇이든 가능하며, 그래픽에는 SVG나 PNG를, 사진에는 JPEG를, 애니메이션에는 GIF를 사용하는 것이 좋습니다. 이미지는 파일 크기를 줄이기 위해 최적화되어야 하며, 브라우저의 라이트 모드와 다크 모드 모두에서 잘 보여야 합니다.
접근성과 원본 텍스트 독자를 위해, image 디렉티브의 :alt: 옵션을 사용하여 이미지에 대한 설명과 그 안에 포함된 주요 정보를 포함해야 합니다:
.. image:: dataflow.png
:alt: Data flows from the input module, through the "black box"
module, and finally into (and through) the output module.
주석
주석은 명시적 마크업 시작(마침표 두 개와 공백) 바로 뒤에 오는 임의 텍스트의 들여쓰기된 블록입니다. 주석이 다른 명시적 마크업 구성으로 잘못 해석되지 않도록 “..”을 한 줄에 단독으로 두십시오. 주석은 처리된 문서에 표시되지 않습니다. 예를 들면:
..
This section should be updated in the final PEP.
Ensure the date is accurate.
이스케이프 메커니즘
reStructuredText는 백슬래시(”\”)를 사용하여 마크업 문자에 부여된 특별한 의미를 무시하고 문자 그대로의 문자를 얻습니다. 리터럴 백슬래시를 얻으려면 이스케이프된 백슬래시(”\\”)를 사용하십시오. 백슬래시가 특별한 의미를 갖지 않는 두 가지 문맥이 있습니다: Literal Blocks와 인라인 리터럴(위의 Inline Markup 참조)입니다. 이러한 문맥에서는 마크업 인식이 이루어지지 않으며, 단일 백슬래시는 두 번 겹치지 않아도 리터럴 백슬래시를 나타냅니다.
텍스트에 백슬래시를 사용해야 한다고 판단되면, 대신 인라인 리터럴이나 리터럴 블록을 사용하는 것을 고려하십시오.
Intersphinx
다른 Sphinx 사이트, 예를 들어 Python documentation, packaging.python.org, typing.python.org 등에 대해 Intersphinx references를 사용하면 페이지, 섹션, Python/C 객체를 쉽게 상호 참조할 수 있습니다.
예를 들어, typing 문서의 한 절을 가리키는 링크를 만들려면 다음과 같이 작성합니다.:
:ref:`type expression <typing:type-expression>`
정규 문서
PEP는 Final로 표시되면 역사적 문서로 간주되며, 이는 PEP 1에서 설명하는 바와 같이, 그 정규 문서/명세는 다른 곳으로 옮겨야 합니다. 이를 나타내려면 canonical-doc 지시어나 적절한 하위 클래스를 사용하십시오.
- 패키징 표준을 위한
canonical-pypa-spec - 타이핑 표준을 위한
canonical-typing-spec
헤더와 PEP의 첫 번째 절(보통 초록) 사이에 지시어를 추가하고, 정규 문서/명세의 Intersphinx 참조(대상이 Sphinx 사이트에 없는 경우 reST 하이퍼링크)를 인자로 전달하십시오.
예를 들어, sqlite3 문서를 가리키는 배너를 만들려면 다음과 같이 작성합니다.:
.. canonical-doc:: :mod:`python:sqlite3`
이는 다음 배너를 생성합니다.
또는 Core metadata specifications와 같은 PyPA 명세의 경우 다음을 사용합니다.:
.. canonical-pypa-spec:: :ref:`packaging:core-metadata`
이는 다음과 같이 렌더링됩니다.
런타임에 새로운 객체를 도입하지 않는 typing PEP의 경우 다음 중 첫 번째와 같은 것을 사용할 수 있으며, 런타임에 typing 모듈에 새로운 객체를 도입하는 typing PEP의 경우 두 번째를 사용할 수 있습니다.:
.. canonical-typing-spec:: :ref:`typing:packaging-typed-libraries`
.. canonical-typing-spec:: :ref:`typing:literal-types` and
:py:data:`typing.Literal`
이 둘은 다음과 같이 렌더링됩니다.
이 인자는 임의의 reST를 받아들이므로 여러 개의 연결된 문서/명세를 포함하고 원하는 대로 이름을 붙일 수 있으며, 텍스트에 삽입될 지시어 내용도 포함할 수 있습니다. 다음의 고급 예제:
.. canonical-doc:: the :ref:`python:sqlite3-connection-objects` and :exc:`python:~sqlite3.DataError` docs
Also, see the :ref:`Data Persistence docs <persistence>` for other examples.
다음과 같이 렌더링됩니다:
피해야 할 습관
TeX에 익숙한 많은 프로그래머는 종종 인용 부호를 이렇게 씁니다:
`single-quoted' or ``double-quoted''
백쿼트는 reStructuredText에서 중요한 의미를 가지므로, 이러한 관행은 피해야 합니다. 일반 텍스트에는 일반적인 ‘single-quotes’나 “double-quotes”를 사용하십시오. 인라인 리터럴 텍스트(위의 Inline Markup참조)에는 이중 백쿼트를 사용하십시오:
``literal text: in here, anything goes!``
권장 섹션
여러 섹션이 PEP 전반에 걸쳐 공통적으로 나타나며, PEP 1에 개요가 설명되어 있습니다. 편의를 위해 해당 섹션들이 여기에 제공됩니다.
PEP: <REQUIRED: pep number>
Title: <REQUIRED: pep title>
Author: <REQUIRED: list of authors' names and optionally, email addrs>
Sponsor: <name of sponsor>
PEP-Delegate: <PEP delegate's name>
Discussions-To: Pending
Status: <REQUIRED: Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
Type: <REQUIRED: Standards Track | Informational | Process>
Topic: <Governance | Packaging | Release | Typing>
Requires: <pep numbers>
Created: <date created on, in dd-mmm-yyyy format>
Python-Version: <version number>
Post-History: Pending
Replaces: <pep number>
Superseded-By: <pep number>
Resolution: <url>
Abstract
========
[A short (~200 word) description of the technical issue being addressed.]
Motivation
==========
[Clearly explain why the existing language specification is inadequate to address the problem that the PEP solves.]
Specification
=============
[Describe the syntax and semantics of any new language feature.]
Rationale
=========
[Describe why particular design decisions were made.]
Backwards Compatibility
=======================
[Describe potential impact and severity on pre-existing code.]
Security Implications
=====================
[How could a malicious user take advantage of this new feature?]
How to Teach This
=================
[How to teach users, new and experienced, how to apply the PEP to their work.]
Reference Implementation
========================
[Link to any existing implementation and details about its state, e.g. proof-of-concept.]
Rejected Ideas
==============
[Why certain ideas that were brought while discussing this PEP were not ultimately pursued.]
Open Issues
===========
[Any points that are still being decided/discussed.]
Acknowledgements
================
[Thank anyone who has helped with the PEP.]
Footnotes
=========
[A collection of footnotes cited in the PEP, and a place to list non-inline hyperlink targets.]
Change History
==============
[A summary of major changes the PEP has undergone. Whenever you update the
``Post-History``, add a new bullet item in newest-first (i.e. reverse
chronological) order, using the same ``DD-MMM-YYYY`` format, with sub-bullets
summarizing the changes. You can use the same link for the date bullet as you
do in the ``Post-History`` addition.]
Copyright
=========
This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.
참고 자료
기본 Docutils에서 지원하는 것과 Sphinx에서 추가한 확장 기능 모두, 그 밖에도 많은 구성 요소와 변형이 가능합니다.
이에 대해 더 알아볼 수 있는 여러 자료가 있습니다:
- Sphinx ReStructuredText Primer, 부드럽지만 상당히 상세한 입문서입니다.
- reStructuredText Markup Specification, 기본 reST 구문, 지시어, 역할 등에 대한 권위 있고 포괄적인 문서입니다.
- Sphinx Roles와 Sphinx Directives, PEP를 HTML로 렌더링하는 데 사용되는 Sphinx 문서화 시스템에서 추가한 확장 구성 요소입니다.
위 자료들이 다루지 않는, PEP 작성에 관한 질문이 있거나 도움이 필요하시면 GitHub에서 @python/pep-editors를 멘션하시거나 PEPs 저장소의 이슈를 여시거나 PEP 편집자에게 직접 연락하십시오.
변경 이력
- 22-Feb-2026
- PEP 템플릿에
Change History라는 제목의 새 섹션을 추가할 것을 제안하고, 이 PEP에도 해당 섹션을 추가합니다. Rationale섹션은 이제Specification섹션 뒤에 옵니다.
- PEP 템플릿에
Copyright
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.