PEP 224 – 속성 독스트링

Author:: Marc-André Lemburg <mal at lemburg.com>
Status:: Rejected
Type:: Standards Track
Created:: 23-Aug-2000
Python-Version:: 2.1
Post-History:

Table of Contents

소개
근거
구현
구현상의 주의 사항
가능한 문제점
BDFL의 의견
Copyright
References

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

Warning

This PEP has been rejected.

자세한 내용은 BDFL의 의견을 참고하십시오.

소개

이 PEP는 파이썬 2.0을 위한 “속성 독스트링” 제안을 설명합니다. 이 PEP는 이 기능의 상태와 소유권을 추적합니다. 이 문서는 해당 기능에 대한 설명을 포함하며, 이를 지원하는 데 필요한 변경 사항을 개괄합니다. 이 파일의 CVS 리비전 이력이 결정적인 역사적 기록을 담고 있습니다.

근거

이 PEP는 파이썬이 현재 코드에 내장된 독스트링을 처리하는 방식에 작은 추가 사항을 제안합니다.

파이썬은 현재 클래스 정의, 함수 정의 바로 뒤에 나오거나 모듈의 첫 번째 문자열 리터럴로 나오는 독스트링의 경우만 처리합니다. 해당 문자열 리터럴은 __doc__ 속성 아래 해당 객체에 추가되며, 이후 도움말, 디버깅, 문서화 목적으로 담긴 정보를 추출할 수 있는 introspection 도구에서 사용할 수 있게 됩니다.

앞서 언급한 위치 이외의 곳에 나타나는 독스트링은 단순히 무시되며 어떠한 코드 생성으로도 이어지지 않습니다.

다음은 예시입니다:

class C:
    "class C doc-string"

    a = 1
    "attribute C.a doc-string (1)"

    b = 2
    "attribute C.b doc-string (2)"

독스트링 (1)과 (2)는 현재 파이썬 바이트코드 컴파일러에 의해 무시되고 있지만, 그 앞에 오는 이름이 지정된 할당을 문서화하는 데 분명히 유용하게 쓰일 수 있습니다.

이 PEP는 이러한 경우들도 활용할 수 있도록, 해당 내용을 새로 생성된 속성 이름 아래 그것이 나타나는 객체에 추가하는 의미론을 제안합니다.

위 예시에도 영감을 준 이 접근 방식의 원래 발상은 클래스 속성에 대한 인라인 문서화를 가능하게 하는 것이었는데, 이는 현재 클래스의 독스트링에서만 문서화하거나 introspection에서 사용할 수 없는 주석을 이용하는 방법밖에 없습니다.

구현

독스트링은 바이트코드 컴파일러에 의해 표현식으로 처리됩니다. 현재 구현은 위에서 언급한 몇몇 위치를 특별히 처리하여 이러한 표현식을 활용하지만, 그 외의 경우에는 문자열을 완전히 무시합니다.

이러한 독스트링을 이름이 부여된 할당(예를 들어 클래스 속성을 정의하는 자연스러운 방식)을 문서화하는 데 사용할 수 있도록 하려면, 컴파일러가 마지막으로 할당된 이름을 추적한 다음 이 이름을 사용하여 독스트링의 내용을 상수로 저장하고, 이를 객체 생성 시점에 해당 객체의 네임스페이스에 추가함으로써 포함 객체의 속성에 할당해야 합니다.

앞뒤에 이중 밑줄이 붙은 파이썬의 특수 속성들에 대한 상속 및 은닉과 같은 특성을 보존하기 위해서는, 독스트링이 해당 이름 할당에 속함을 고유하게 식별하고 나중에 네임스페이스를 검사하여 독스트링을 찾을 수 있도록 하는 특별한 이름 맹글링을 적용해야 합니다.

다음의 이름 맹글링 방식은 위의 모든 요구 사항을 충족합니다.:

__doc_<attributename>__

마지막으로 할당된 이름을 추적하기 위해, 바이트코드 컴파일러는 이 이름을 컴파일 구조체의 변수에 저장합니다. 이 변수의 기본값은 NULL입니다. 독스트링을 만나면, 컴파일러는 이 변수를 확인하고 그 이름을 기반으로 위의 이름 맹글링을 수행하여 독스트링을 맹글링된 이름에 암묵적으로 할당합니다. 그런 다음 중복 할당을 방지하기 위해 변수를 다시 NULL로 재설정합니다.

변수가 이름을 가리키지 않는 경우(즉, NULL인 경우), 할당은 이루어지지 않습니다. 이 경우들은 이전과 마찬가지로 계속 무시됩니다. 모든 고전적인 독스트링은 이 경우에 해당하므로, 중복 할당은 이루어지지 않습니다.

위의 예시에서는 다음과 같은 새로운 클래스 속성이 생성됩니다.:

C.__doc_a__ == "attribute C.a doc-string (1)"
C.__doc_b__ == "attribute C.b doc-string (2)"

위 내용을 구현한, 현재 CVS 버전의 Python 2.0에 대한 패치는 SourceForge의 [1]에서 확인할 수 있습니다.

구현상의 주의 사항

구현은 함수 정의와 같은 비표현식을 처리할 때 컴파일 구조체 변수를 재설정하지 않으므로, 마지막으로 할당된 이름은 다음 할당이나 다음 독스트링이 나타날 때까지 계속 유효합니다.

이로 인해 독스트링과 할당문이 다른 표현식에 의해 분리되는 경우가 발생할 수 있습니다:

class C:
    "C doc string"

    b = 2

    def x(self):
        "C.x doc string"
         y = 3
         return 1

    "b's doc string"

메서드 “x”의 정의는 현재 사용된 할당 이름 변수를 재설정하지 않으므로, 컴파일러가 독스트링 “b’s doc string”에 도달했을 때도 여전히 유효하며, 따라서 해당 문자열을 __doc_b__에 할당합니다.

이 문제에 대한 가능한 해결책은 컴파일러에서 모든 비표현식 노드에 대해 이름 변수를 재설정하는 것입니다.

가능한 문제점

가능성은 매우 낮지만, 속성 독스트링이 실수로 속성 값에 연결될 수 있습니다:

class C:
    x = "text" \
        "x's docstring"

뒤에 붙은 슬래시는 Python 컴파일러가 속성 값과 독스트링을 연결하게 만듭니다.

하지만 현대적인 구문 강조 편집기라면 이러한 사고를 쉽게 드러낼 것이며, 속성 정의와 독스트링 사이에 빈 줄을 삽입하는 것만으로도 이러한 연결 가능성을 완전히 피할 수 있으므로, 이 문제는 무시할 만합니다.

또 다른 가능한 문제는 코드의 일부에 대한 주석을 해제하는 방법으로 삼중 인용 문자열을 사용하는 경우입니다.

만약 주석 문자열이 시작되기 바로 직전에 할당문이 있는 경우, 컴파일러는 해당 주석을 독스트링 속성으로 취급하여 위의 로직을 적용하게 됩니다.

이는 문서화되지 않았던 속성에 대해 독스트링을 생성하는 것 외에는 아무런 손상도 일으키지 않습니다.

BDFL의 의견

Guido가 PEP에 대해 초기에 남긴 의견:

저는 속성 독스트링을 갖는다는 아이디어를 “어느 정도” 마음에 들어합니다(이는 저에게 큰 중요성을 갖지 않는다는 뜻입니다). 하지만 현재 제안에는 마음에 들지 않는 두 가지가 있습니다:

당신이 제안한 구문은 너무 모호합니다. 당신이 말했듯이, 독립적인 문자열 리터럴은 다른 용도로 사용되는데 갑자기 속성 독스트링이 될 수 있습니다.

접근 방법도 마음에 들지 않습니다(__doc_<attrname>__).

저자의 답변:

> 1. The syntax you propose is too ambiguous: as you say, stand-alone
>    string literal are used for other purposes and could suddenly
>    become attribute docstrings.
이는 컴파일러 구조체에서 “doc 속성” 플래그를 재설정하도록 컴파일러에 몇 가지 추가 검사를 도입함으로써 해결할 수 있습니다.
> 2. I don't like the access method either (``__doc_<attrname>__``).
다른 이름이라도 상관없습니다. 다음 기준만 충족하면 됩니다:

밑줄 두 개로 시작해야 합니다(__doc__과 일치시키기 위해)

어떤 형태로든 검사(inspection)를 통해 추출 가능해야 합니다(예를 들어 고정된 이름 부분을 포함하는 명명 규칙을 사용하여)

클래스 상속과 호환되어야 합니다(즉, 속성으로 저장되어야 함)

이후 2001년 3월, Guido는 python-dev에서 이 PEP에 대해 판단을 내렸습니다. 다음은 이 PEP의 저자에게 보낸 개인 메일에서 언급된 거부 사유입니다:

…
유용할 수는 있지만, 제안된 문법이 정말 마음에 들지 않습니다.
a = 1
"foo bar"
b = 1
“foo bar”가 a에 대한 독스트링인지 b에 대한 독스트링인지 저는 도무지 알 방법이 없습니다.

…

이 관례를 사용할 수 있습니다:
a = 1
__doc_a__ = "doc string for a"
이렇게 하면 런타임에 사용할 수 있게 됩니다.
> Are you completely opposed to adding attribute documentation
> to Python or is it just the way the implementation works ? I
> find the syntax proposed in the PEP very intuitive and many
> other users on c.l.p and in private emails have supported it
> at the time I wrote the PEP.
구현의 문제가 아니라 문법의 문제입니다. 변수와 독스트링 사이의 결합 관계를 충분히 명확하게 전달하지 못합니다.

Copyright

This document has been placed in the Public Domain.