python - पायथन में कक्षा विशेषताओं को कैसे दस्तावेज़ित करें?




class documentation (2)

आप PEP257 का उद्धरण देते हैं: अनुभाग में डॉकस्ट्रिंग सम्मेलन, एक डॉकस्ट्रिंग क्या है यह कहा गया है:

पायथन कोड में कहीं और होने वाली स्ट्रिंग अक्षर भी दस्तावेज़ीकरण के रूप में कार्य कर सकते हैं। उन्हें पायथन बाइटकोड कंपाइलर द्वारा पहचाना नहीं जाता है और रनटाइम ऑब्जेक्ट विशेषताओं (यानी __doc__ को असाइन नहीं किया गया) के रूप में सुलभ नहीं हैं, लेकिन सॉफ़्टवेयर टूल द्वारा दो प्रकार के अतिरिक्त डॉकस्ट्रिंग निकाले जा सकते हैं:

मॉड्यूल, कक्षा, या __init__ विधि के शीर्ष स्तर पर एक साधारण असाइनमेंट के तुरंत बाद स्ट्रिंग अक्षरलेखक "विशेषता दस्तावेज़" कहा जाता है।

और पीईपी 258 में अधिक जानकारी में यह समझाया गया है: गुण डॉकस्ट्रिंग्स। जैसा कि ऊपर बताता है ʇsәɹoɈ। एक विशेषता एक ऑब्जेक्ट नहीं है जो __doc__ के मालिक हो सकती है ताकि वे help() या pydoc में दिखाई न दें। ये दस्तावेज़ों का उपयोग केवल जेनरेट किए गए दस्तावेज़ों के लिए किया जा सकता है।

लेकिन वर्तमान में कुछ उपकरण उनका उपयोग करते हैं।

पुराना एपीडोक उनका उपयोग करता है और स्फिंक्स ने इसे v0.6 में पेश किया और इसे v1.1 में बढ़ा दिया। स्फिंक्स एक असाइनमेंट से पहले या किसी असाइनमेंट के बाद एक विशेष टिप्पणी में लाइन पर डॉकस्ट्रिंग का उपयोग कर सकते हैं।

स्फिंक्स मैनुअल में डायरेक्टिव ऑटोएट्रिब्यूट और विशेषता डॉकस्ट्रिंग के उदाहरण देखें।

मैं एक हल्के वर्ग को लिख रहा हूं जिसका गुण सार्वजनिक रूप से सुलभ होने का इरादा है, और कभी-कभी विशिष्ट तत्कालताओं में ओवरराइड किया जाता है। उस मामले के लिए वर्ग विशेषताओं, या किसी भी प्रकार के विशेषताओं के लिए दस्तावेज़ बनाने के लिए पाइथन भाषा में कोई प्रावधान नहीं है। इन विशेषताओं को दस्तावेज करने के लिए स्वीकार्य तरीका क्या होना चाहिए, क्या होना चाहिए? वर्तमान में मैं इस तरह की चीज कर रहा हूं:

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)

इसके परिणामस्वरूप क्लास के डॉकस्ट्रिंग में शुरुआती मानक डॉकस्ट्रिंग सेक्शन होगा, साथ ही __doc__ को संवर्धित असाइनमेंट के माध्यम से प्रत्येक विशेषता के लिए जोड़े गए लाइन भी __doc__

यद्यपि यह शैली डॉकस्ट्रिंग शैली दिशानिर्देशों में स्पष्ट रूप से वर्जित नहीं लगती है, लेकिन इसे एक विकल्प के रूप में भी नहीं बताया गया है। यहां का लाभ यह है कि यह अपनी परिभाषाओं के साथ विशेषताओं को दस्तावेज करने का एक तरीका प्रदान करता है, जबकि अभी भी एक प्रस्तुत करने योग्य वर्ग डॉकस्ट्रिंग बना रहा है, और डॉकस्ट्रिंग से जानकारी दोहराते हुए टिप्पणियां लिखने से परहेज करता है। मैं अभी भी परेशान हूं कि मुझे वास्तव में गुणों को दो बार लिखना है; मैं कम से कम डिफ़ॉल्ट मानों के डुप्लिकेशंस से बचने के लिए डॉकस्ट्रिंग में मानों के स्ट्रिंग प्रस्तुतियों का उपयोग करने पर विचार कर रहा हूं।

क्या यह विज्ञापन समुदाय सम्मेलनों का एक गंभीर उल्लंघन है? क्या यह सही है? क्या कोई बेहतर तरीका है? उदाहरण के लिए, गुणों के लिए मूल्यों और डॉकस्ट्रिंग वाले शब्दकोश बनाना संभव है और फिर श्रेणी घोषणा के अंत में सामग्री __dict__ और docstring में सामग्री जोड़ें; यह विशेषता नाम और मानों को दो बार टाइप करने की आवश्यकता को कम करेगा। संपादित करें : मुझे लगता है कि, यह आखिरी विचार है, वास्तव में संभव नहीं है, कम से कम गतिशील रूप से पूरी कक्षा को डेटा से नहीं बनाते, जो वास्तव में एक बुरा विचार लगता है जब तक कि ऐसा करने का कोई अन्य कारण न हो।

मैं अजगर के लिए काफी नया हूं और अभी भी कोडिंग शैली के विवरण का काम कर रहा हूं, इसलिए असंबद्ध आलोचनाओं का भी स्वागत है।


आप इस प्रभाव के लिए गुणों का दुरुपयोग कर सकते हैं। गुणों में एक गेटर, एक सेटर, एक डिलीटर, और एक डॉकस्ट्रिंग होता है । नैतिक रूप से, यह बहुत verbose मिलेगा:

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

फिर आपके पास सीएक्स से संबंधित डॉकस्ट्रिंग होगा:

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 यह होगा:

Help on class C in module __main__:

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

which I think should be pretty much what you're after.

संपादित करें : मुझे अब एहसास है कि हम शायद myprop को पहले तर्क को पारित करने की आवश्यकता से बच सकते हैं, क्योंकि आंतरिक नाम कोई फर्क नहीं पड़ता। यदि myprop की अगली कॉल किसी अन्य के साथ संवाद कर सकती हैं, तो यह स्वचालित रूप से एक लंबे और असंभव आंतरिक विशेषता नाम पर निर्णय ले सकती है। मुझे यकीन है कि इसे लागू करने के तरीके हैं, लेकिन मुझे यकीन नहीं है कि वे इसके लायक हैं या नहीं।





class-attributes