Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python 개선 제안 한국어 번역

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
Table of Contents

번역·라이선스 안내

이 비공식 한국어 번역은 원문 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(및 다른 모든 PEP)의 소스는 PEPs repository에서 찾을 수 있으며, 각 PEP 하단의 링크를 통해서도 확인할 수 있습니다.

명세

PEP를 제출하려면, 형식 문제로 PEP 제출이 자동으로 거부되지 않도록 반드시 아래의 형식 지침과 함께 이 템플릿을 사용해야 합니다.

근거

reStructuredText는 소스 텍스트의 가독성을 쉽게 유지하면서도 PEP 작성자에게 유용한 기능과 풍부한 표현력을 제공합니다. 처리된 HTML 형태에서는 독자가 이러한 기능을 이용할 수 있습니다. 클릭할 수 있는 하이퍼링크, 서식이 적용된 텍스트, 표, 이미지, 자동 생성 목차 등이 그 이점입니다.

이 템플릿 사용 방법

이 템플릿을 사용하려면 먼저 여러분의 PEP가 정보(Informational) PEP인지 표준 트랙(Standards Track) PEP인지 결정해야 합니다. 대부분의 PEP는 Python 언어나 표준 라이브러리에 새로운 기능을 제안하므로 표준 트랙에 속합니다. 확실하지 않을 때는 PEP 1에서 자세한 내용을 읽거나, PEPs 저장소에 트래커 이슈를 열어 도움을 요청하십시오.

여러분의 PEP가 어떤 유형이 될지 결정했다면 아래 안내를 따르십시오.

  • 이 파일(HTML이 아니라 .rst 파일입니다!)의 사본을 만들고 다음과 같이 편집하십시오. 새 파일의 이름은 (게시되었거나 PR 중인 PEP에서 사용하지 않은) 다음 번호를 사용하여 pep-NNNN.rst로 지정하십시오.
  • “PEP: 12” 헤더를 파일 이름에 맞추어 “PEP: NNNN”으로 바꾸십시오. 파일 이름은 앞을 0으로 채워야 하지만(예: pep-0012.rst), 헤더는 0으로 채우지 않아야 한다는 점(PEP: 12)에 유의하십시오.
  • Title 헤더를 여러분의 PEP 제목으로 바꾸십시오.
  • Author 헤더에 여러분의 이름을 넣고, 원한다면 이메일 주소도 넣으십시오. 형식을 꼼꼼히 지키십시오. 이름이 먼저 나와야 하며, 이름을 괄호로 감싸서는 안 됩니다. 이메일 주소는 이름 다음에 올 수 있으며(생략해도 됩니다), 넣는 경우에는 반드시 꺾쇠괄호로 감싸야 합니다. 이메일 주소는 알아보기 어렵게 바꾸어 적어도 됩니다.
  • 작성자 중 Python 코어 개발자가 없다면, 여러분의 PEP를 후원하는 코어 개발자의 이름을 담은 Sponsor 헤더를 넣으십시오.
  • Discussions-To 헤더에 PEP의 공식 토론 스레드(예: Python-Dev, Discourse 등)로 바로 연결되는 URL을 넣으십시오. PEP가 공식 초안으로 제출된 뒤에 스레드를 만들 예정이라면 처음에는 “Pending”이라고만 적어도 됩니다. 다만 PEP가 PEPs 저장소에 성공적으로 병합되고 해당 토론 스레드를 만들면 곧바로 PEP에 URL을 반영해야 한다는 점을 기억하십시오. 자세한 내용은 PEP 1을 참조하십시오.
  • Status 헤더를 “Draft”로 바꾸십시오.
  • 표준 트랙 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 중 하나입니다.
  • Standards Track PEP라면 Created 헤더 뒤에 Python-Version 헤더를 추가하고, 그 값을 다음으로 계획된 Python 버전, 즉 여러분의 새 기능이 처음 등장하기를 바라는 버전으로 설정하십시오. 여기에는 알파나 베타 릴리스 표기를 사용하지 마십시오. 따라서 마지막 Python 버전이 2.2 알파 1이고 새 기능을 Python 2.2에 넣고자 한다면, 헤더를 다음과 같이 설정하십시오:
    Python-Version: 2.2
  • PEP가 주제별 색인에 표시된 주제 중 하나에 속한다면 Topic 헤더를 추가하십시오. 대부분의 PEP는 해당하지 않습니다.
  • Post-History는 당분간 ‘Pending’으로 두어도 됩니다. 지정된 토론 포럼에 PEP를 게시할 때마다 이 헤더에 날짜와 해당 링크를 추가하게 됩니다(그리고 위에서 설명한 대로 Discussions-To 헤더도 그 링크로 갱신합니다). 각 스레드마다 날짜(DD-MMM-YYYY 형식)를 링크 텍스트로 사용하고, URL은 익명 reST Hyperlinks로 인라인에 삽입하며, 각 게시물 사이는 쉼표로 구분하십시오.

    예를 들어 2001년 8월 14일과 2001년 9월 3일에 PEP 스레드를 게시했다면, 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가 “최종” 상태, 즉 Accepted, Final, Rejected 중 하나인 경우에만 이 헤더를 추가하십시오. 경쟁하는 아이디어를 제출하는 것이라면 아직 열려 있는 이전 PEP를 대체하는 것이 아닙니다.
  • 이제 PEP의 초록(Abstract), 근거, 그 밖의 내용을 작성하여 이 모든 알아듣기 힘든 문구를 여러분 자신의 글로 바꾸십시오. 아래의 형식 지침, 특히 탭 문자 사용 금지와 들여쓰기 요구 사항을 반드시 준수하십시오. 포함할 섹션의 템플릿은 아래의 “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의 절이 세 단계보다 많다면, 다음과 같이 1단계와 2단계에 윗줄과 밑줄로 장식한 제목을 넣을 수 있습니다:

============================
First-Level Title (optional)
============================

-----------------------------
Second-Level Title (optional)
-----------------------------

Third-Level Title
=================

Fourth-Level Title
------------------

Fifth-Level Title
'''''''''''''''''

PEP의 절은 다섯 단계를 넘지 않아야 합니다. 넘는다면 PEP를 다시 작성하는 것을 고려해야 합니다.

절 본문의 마지막 줄과 다음 절 제목 사이에는 빈 줄을 두 줄 넣어야 합니다. 절 제목 바로 다음에 하위 절 제목이 온다면 그 사이에는 빈 줄 한 줄이면 충분합니다.

각 절의 본문은 보통 들여 쓰지 않지만, 아래에서 설명하는 것처럼 일부 구성 요소는 들여쓰기를 사용합니다. 빈 줄은 구성 요소를 구분하는 데 사용합니다.

문단

문단은 빈 줄로 구분된 왼쪽 정렬 텍스트 블록입니다. 문단은 들여 쓴 구성 요소(인용 블록이나 목록 항목 등)의 일부가 아니라면 들여 쓰지 않습니다.

인라인 마크업

문단과 기타 텍스트 블록 안의 텍스트 일부에는 스타일을 적용할 수 있습니다. 예를 들면 다음과 같습니다:

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 본문의 맨 위(헤더 아래, Abstract 위)에 적절한 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_>`_.

명시적 대상(target)이 URL을 제공합니다. 대상은 PEP 끝의 Footnotes 섹션에 두거나, 참조가 있는 단락 바로 뒤에 두십시오. 하이퍼링크 대상은 마침표 두 개와 공백 하나(“명시적 마크업 시작”)로 시작하며, 그 뒤에 선행 밑줄, 참조 텍스트, 콜론, URL이 차례로 옵니다.

.. _Python web site: https://www.python.org/
.. _pydocs: https://docs.python.org/

참조 텍스트와 대상 텍스트는 일치해야 합니다(단, 대소문자를 구분하지 않으며 공백의 차이는 무시합니다). 밑줄은 참조 텍스트에서는 뒤에 오지만 대상 텍스트에서는 앞에 온다는 점에 유의하십시오. 밑줄을 오른쪽을 가리키는 화살표로 생각하면, 밑줄은 참조에서 멀어지는 방향, 즉 대상을 향하는 방향을 가리킵니다.

내부 링크와 PEP/RFC 링크

하이퍼링크와 같은 메커니즘을 내부 참조에도 사용할 수 있습니다. 고유한 섹션 제목은 모두 암묵적으로 내부 하이퍼링크 대상을 정의합니다. Abstract 섹션으로 가는 링크는 다음과 같이 만들 수 있습니다:

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

Python 문서, packaging.python.org, typing.python.org 등 다른 Sphinx 사이트에 대한 Intersphinx 참조를 사용하면 페이지, 섹션, Python/C 객체를 쉽게 상호 참조할 수 있습니다.

예를 들어, typing 문서의 한 섹션을 가리키는 링크를 만들려면 다음과 같이 작성합니다:

:ref:`type expression <typing:type-expression>`

정식 문서

PEP 1에서 설명하듯이, PEP는 Final로 표시되면 역사적 문서로 간주되며, 그 정식 문서/명세는 다른 곳으로 옮겨야 합니다. 이를 나타내려면 canonical-doc 지시자나 적절한 서브클래스를 사용하십시오:

  • 패키징 표준용 canonical-pypa-spec
  • 타이핑 표준용 canonical-typing-spec

헤더와 PEP의 첫 번째 섹션(일반적으로 Abstract) 사이에 디렉티브를 추가하고, 정식 문서/명세의 Intersphinx 참조(대상이 Sphinx 사이트에 있지 않다면 reST 하이퍼링크)를 인자로 전달하십시오.

예를 들어, sqlite3 문서를 가리키는 배너를 만들려면 다음과 같이 작성합니다:

.. canonical-doc:: :mod:`python:sqlite3`

그러면 다음 배너가 생성됩니다:

Important

This PEP is a historical document. The up-to-date, canonical documentation can now be found at sqlite3.

×

See PEP 1 for how to propose changes.

또는 Core metadata specifications와 같은 PyPA 명세의 경우에는 다음을 사용합니다:

.. canonical-pypa-spec:: :ref:`packaging:core-metadata`

다음과 같이 렌더링됩니다:

Important

This PEP is a historical document. The up-to-date, canonical spec, Core metadata specifications, is maintained on the PyPA specs page.

×

See the PyPA specification update process for how to propose changes.

새로운 런타임 객체를 도입하지 않는 타이핑 PEP라면 다음 중 첫 번째와 같은 형태를 사용할 수 있고, 런타임에 typing 모듈에 새로운 객체를 도입하는 타이핑 PEP라면 두 번째를 사용할 수 있습니다:

.. canonical-typing-spec:: :ref:`typing:packaging-typed-libraries`
.. canonical-typing-spec:: :ref:`typing:literal-types` and
                           :py:data:`typing.Literal`

두 가지는 다음과 같이 렌더링됩니다:

Important

This PEP is a historical document: see Type information in libraries for up-to-date specs and documentation. Canonical typing specs are maintained at the typing specs site; runtime typing behaviour is described in the CPython documentation.

×

See the typing specification update process for how to propose changes to the typing spec.

Important

This PEP is a historical document: see Literals and typing.Literal for up-to-date specs and documentation. Canonical typing specs are maintained at the typing specs site; runtime typing behaviour is described in the CPython documentation.

×

See the typing specification update process for how to propose changes to the typing spec.

인자는 임의의 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.

다음과 같이 렌더링됩니다:

Important

This PEP is a historical document. The up-to-date, canonical documentation can now be found at the Connection objects and sqlite3.DataError docs.

×

또한 다른 예제는 데이터 영속성 문서를 참고하십시오.

See PEP 1 for how to propose changes.

피해야 할 습관

TeX에 익숙한 많은 프로그래머는 종종 다음과 같이 따옴표를 씁니다:

`single-quoted' or ``double-quoted''

reStructuredText에서는 역따옴표가 특별한 의미를 가지므로 이러한 습관은 피해야 합니다. 일반 텍스트에는 평범한 ‘작은따옴표’나 “큰따옴표”를 사용하십시오. 인라인 리터럴 텍스트(위의 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가 추가한 확장 기능을 모두 포함하여, 그 밖에도 많은 구문과 변형이 가능합니다.

이에 대해 더 알아볼 수 있는 여러 자료가 있습니다:

위의 자료에서 다루지 않는 질문이 있거나 PEP 작성에 도움이 필요하다면, GitHub에서 @python/pep-editors를 멘션하거나, PEPs 저장소의 이슈를 열거나, PEP 편집자에게 직접 연락하십시오.

변경 이력

  • 22-Feb-2026
    • PEP 템플릿에 Change History라는 제목의 새 섹션을 추가할 것을 제안하고, 이 PEP에도 해당 섹션을 추가합니다.
    • 이제 Rationale 섹션이 Specification 섹션 뒤에 옵니다.