Python에서 클래스 속성을 어떻게 문서화합니까?

Python에서 클래스 속성을 어떻게 문서화합니까?

저는 공개적으로 액세스할 수 있는 속성을 가진 경량 클래스를 작성하고 있으며, 특정 인스턴스에서만 가끔 오버라이드됩니다.Python 언어에는 클래스 속성이나 어떤 종류의 속성에 대한 문서 문자열을 만들 수 있는 조항이 없습니다.이러한 특성을 문서화하는 데 필요한 예상 및 지원 방법은 무엇입니까?현재 저는 다음과 같은 일을 하고 있습니다.

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
    """

    flight_speed = 691
    __doc__ += """
        flight_speed (691)
          The maximum speed that such a bird can attain.
    """

    nesting_grounds = "Raymond Luxury-Yacht"
    __doc__ += """
        nesting_grounds ("Raymond Luxury-Yacht")
          The locale where these birds congregate to reproduce.
    """

    def __init__(self, **keyargs):
        """Initialize the Albatross from the keyword arguments."""
        self.__dict__.update(keyargs)

각 "docstring"에 대한 되는 줄이 됩니다.__doc__.

이 스타일은 docstring 스타일 지침에서 명시적으로 금지된 것으로 보이지는 않지만, 옵션으로도 언급되지 않습니다.여기서의 장점은 속성을 정의와 함께 문서화하는 방법을 제공하는 동시에 표시 가능한 클래스 docstring을 만들고 docstring에서 정보를 반복하는 주석을 작성할 필요가 없다는 것입니다.속성을 실제로 두 번 써야 한다는 것이 여전히 짜증납니다. 최소한 기본값의 중복을 피하기 위해 문서 문자열에 있는 값의 문자열 표현을 사용하는 것을 고려하고 있습니다.

이것은 특별 지역 사회 협약의 극악무도한 위반입니까?이거 괜찮아요?더 좋은 방법이 있습니까?를 들어,하는 사전을 다음 수 .__dict__및 docstring을 클래스 선언의 끝에 추가합니다. 이렇게 하면 속성 이름과 값을 두 번 입력할 필요가 줄어듭니다.편집: 이 마지막 아이디어는, 제 생각에, 제가 생각하기에, 실제로는, 적어도 데이터로부터 동적으로 전체 클래스를 구축하지 않고서는 불가능합니다. 이것은 그렇게 할 다른 이유가 없는 한 정말 나쁜 생각인 것 같습니다.

저는 파이썬에 꽤 익숙하고 코딩 스타일의 세부 사항을 아직도 해결하고 있기 때문에 관련 없는 비평도 환영합니다.

요약: 클래스 속성은 클래스 및 함수와 같은 방식으로 doc 문자열을 가질 수 없습니다.

혼동을 피하기 위해 속성이라는 용어는 python에서 특정한 의미를 가집니다.당신이 말하는 것은 우리가 클래스 속성이라고 부르는 것입니다.항상 클래스를 통해 수행되므로 클래스의 문서 문자열 내에서 문서화하는 것이 타당하다고 생각합니다.이와 같은 것:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

저는 그것이 당신의 예에서 접근하는 것보다 눈에 훨씬 더 쉽다고 생각합니다.속성 값의 복사본을 문서 문자열에 표시하려면 각 속성의 설명 옆이나 아래에 놓아야 합니다.

Python에서 doc 문자열은 단순히 소스 코드 주석이 아니라 문서화된 객체의 실제 멤버입니다.클래스 속성 변수는 객체 자체가 아니라 객체에 대한 참조이므로 자체 문서 문자열을 보유할 수 없습니다.참고 문헌에 대한 사례를 만들 수 있을 것 같습니다. 아마도 "여기에 실제로 무엇이 있는지"가 아니라 "여기에 무엇이 가야 하는지"를 설명하는 것이 좋습니다. 하지만 저는 포함된 클래스 문서 문자열에서 그렇게 하는 것이 충분히 쉽다고 생각합니다.

PEP257: Docstring 규약을 인용하면 다음과 같습니다. "Docstring이란 무엇입니까?" 섹션에 명시되어 있습니다.

Python 코드의 다른 곳에서 발생하는 문자열 리터럴도 문서로 작동할 수 있습니다.속성으로 수 이들파바즉컴의않인드런해파다않음접니없수습근할로객지속으성체은임이식타되당할으썬이되며에지트코, ▁assigned▁attrib지않▁they음▁toutesi▁are▁((다▁runtime▁object).__doc__단, 도구에 두 의 추가 을 추출할 수

모의 하는 문자열 리터럴은 클 스 또 직 발 에 는 하 생 럴 리 문 터 열 자 후 듈 당 할 래 한 는 위 상 서 최 에 간 수 단__init__메소드를 "메소드 docstrings"라고 합니다.

이에 대한 자세한 내용은 PEP 258: Attribute Docstrings 섹션을 참조하십시오.위에서 설명한 바와 같이 속성은 다음을 소유할 수 있는 객체가 아닙니다.__doc__그래서 그들은 출연하지 않습니다.help()또는 파이독.이러한 문서 문자열은 생성된 문서에만 사용할 수 있습니다.

스핑크스에서는 지시 자동 속성과 함께 사용됩니다.

스핑크스는 자동 문서화될 정의 뒤에 있는 할당 또는 문서 문자열 뒤에 있는 특수 주석 또는 할당 앞에 있는 줄에 주석을 사용할 수 있습니다.

다른 대답들은 매우 구식입니다.PEP-224(Python 2.1!에서 사용 가능)는 속성에 대해 docstring을 사용하는 방법을 설명합니다.그들은 이상하게도 속성을 추구합니다.

class C:
    "class C doc-string"

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

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

또한 다음과 같은 유형 주석에 대해서도 작동합니다.

class C:
    "class C doc-string"

    a: int
    "attribute C.a doc-string (1)"

    b: str
    "attribute C.b doc-string (2)"

VSCode는 이러한 표시를 지원합니다.

이 경우 속성을 악용할 수 있습니다.속성에는 게터, 세터, 삭제자 및 문서 문자열이 포함됩니다.기본적으로, 이것은 매우 장황하게 될 것입니다.

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """Docstring goes here."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

그러면 C.x에 속한 문서 문자열을 갖게 됩니다.

In [24]: print(C.x.__doc__)
Docstring goes here.

많은 속성에 대해 이 작업을 수행하는 것은 번거롭지만 도우미 기능 myprop:

def myprop(x, doc):
    def getx(self):
        return getattr(self, '_' + x)

    def setx(self, val):
        setattr(self, '_' + x, val)

    def delx(self):
        delattr(self, '_' + x)

    return property(getx, setx, delx, doc)

class C:
    a = myprop("a", "Hi, I'm A!")
    b = myprop("b", "Hi, I'm B!")

In [44]: c = C()

In [46]: c.b = 42

In [47]: c.b
Out[47]: 42

In [49]: print(C.b.__doc__)
Hi, I'm B!

그런 다음, 파이썬스를 대화형이라고 부릅니다.help다음을 제공:

Help on class C in module __main__:

class C
 |  Data descriptors defined here:
 |  
 |  a
 |      Hi, I'm A!
 |  
 |  b
 |      Hi, I'm B!

제 생각엔 당신이 추구하는 것과 거의 비슷할 것 같습니다.

편집: 저는 이제 우리가 첫 번째 주장을 전달할 필요를 피할 수 있다는 것을 깨달았습니다.myprop내부 이름은 중요하지 않기 때문입니다.이후의 전화가 있을 경우myprop어떻게든 서로 통신할 수 있으며, 길고 가능성이 낮은 내부 속성 이름을 자동으로 결정할 수 있습니다.이를 구현할 수 있는 방법이 있을 것으로 확신하지만, 그럴 만한 가치가 있는지는 잘 모르겠습니다.

언급URL : https://stackoverflow.com/questions/3051241/how-to-document-class-attributes-in-python