पायथन में वर्ग विशेषताओं का दस्तावेज कैसे करें? [बन्द है]

Question

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

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__।

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

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

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

Comments

यदि आप Django मॉडल विशेषताओं को दस्तावेज़ित करने का एक तरीका ढूंढ रहे हैं, तो यह मददगार हो सकता है: djangosnippets.org/snippets/2533

— Michael Scheper

का डुप्लिकेट दस्तावेज़ के खेतों और अजगर में गुण कैसे? जो एक अलग समाधान पकड़।

— bufh

मुझे नहीं लगता कि यह राय आधारित क्यों है। अजगर विशेष रूप से दस्तावेजों यह PEPs में स्वीकार्य सम्मेलनों है। विभिन्न पायथन स्रोत उपकरण हैं जो ठीक से स्वरूपित प्रलेखन को निकालते हैं। वास्तव में Python का वास्तव attribute doc stringमें PEP 257 में एक उल्लेख है जो अच्छी तरह से ज्ञात नहीं है और इसे खोजने में मुश्किल लगता है जो OPs प्रश्न का उत्तर दे सकता है, और कुछ स्रोत टूल द्वारा समर्थित है। यह राय नहीं है। यह तथ्य है, और भाषा का हिस्सा है, और बहुत ज्यादा वही है जो ओपी चाहता है।

— नील

Answer 1

भ्रम से बचने के लिए: शब्द संपत्ति का अजगर में एक विशिष्ट अर्थ है। आप जिस बारे में बात कर रहे हैं, उसे हम क्लास एट्रिब्यूट कहते हैं । चूँकि उनकी कक्षा के माध्यम से उन पर हमेशा कार्रवाई की जाती है, इसलिए मुझे पता चलता है कि इससे उन्हें कक्षा के डॉक स्ट्रिंग में दस्तावेज बनाने में मदद मिलती है। कुछ इस तरह:

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"

मुझे लगता है कि यह आपके उदाहरण में दृष्टिकोण की तुलना में आंखों पर बहुत आसान है। यदि मैं वास्तव में डॉक स्ट्रिंग में प्रदर्शित करने के लिए विशेषता मानों की एक प्रति चाहता था, तो मैं उन्हें प्रत्येक विशेषता के विवरण के साथ या नीचे रखूंगा।

ध्यान रखें कि पायथन में, डॉक स्ट्रिंग्स उन वस्तुओं के वास्तविक सदस्य होते हैं जो वे दस्तावेज करते हैं, न कि केवल स्रोत कोड एनोटेशन। चूँकि क्लास एट्रिब्यूट वैरिएबल खुद ऑब्जेक्ट नहीं हैं बल्कि ऑब्जेक्ट्स के संदर्भ में हैं, इसलिए उनके पास अपने स्वयं के डॉक स्ट्रिंग्स को रखने का कोई तरीका नहीं है। मुझे लगता है कि आप संदर्भों पर डॉक्टर स्ट्रिंग के लिए एक मामला बना सकते हैं, शायद "क्या वास्तव में यहाँ है" के बजाय "यहाँ क्या जाना चाहिए" का वर्णन करने के लिए, लेकिन मुझे यह करना आसान लगता है कि युक्त वर्ग डॉक्टर स्ट्रिंग में।

Comments

मुझे लगता है कि ज्यादातर मामलों में यह ठीक है, क्योंकि शब्दावली-सुधार के लिए गुण-विशेष रूप से पर्याप्त रूप से घोषित किए जाते हैं कि उन्हें केवल कक्षा घोषणा की शुरुआत में वर्गीकृत किया जा सकता है बिना इसे पीछे या पीछे फ्लिप करने के लिए अव्यवहारिक बनाने के लिए {दोनों पढ़ें प्रलेखन और डिफ़ॉल्ट मूल्य} या {प्रलेखन के दोनों उदाहरणों और / या डिफ़ॉल्ट मूल्य को अपडेट करें}।

— intuited

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

— 8:16

हां, मेरा प्रारंभिक विचार सिर्फ उदाहरण की घोषणा करना था flight_speed = 691; flight_speed.__doc__ = "blah blah"। मुझे लगता है कि यह वही है जिसका आप अपने संपादन में उल्लेख कर रहे हैं । दुर्भाग्य से, यह (अधिकांश?) बिल्टइन प्रकारों (जैसे intकि उदाहरण में ) के इंस्टेंटिएशन के लिए काम नहीं करता है । यह उपयोगकर्ता-परिभाषित प्रकारों के तात्कालिकता के लिए काम करता है। =========== वास्तव में एक पीईपी (क्षमा करें, संख्या भूल जाओ) जिसने क्लास / मॉड्यूल विशेषताओं के लिए डॉकस्ट्रिंग्स को जोड़ने का प्रस्ताव दिया था, लेकिन इसे अस्वीकार कर दिया गया था क्योंकि वे इसे स्पष्ट करने का कोई तरीका नहीं निकाल सके थे। क्या डॉकस्ट्रिंग्स पूर्ववर्ती या निम्नलिखित विशेषताओं के लिए थे।

— intuited

तो क्या होगा अगर वे उदाहरण विशेषताएँ हैं? अभी भी दस्तावेज़ में कक्षा में क्या है या क्या है?

— n611x007

@intuited क्या यह पीईपी था? legacy.python.org/dev/peps/pep-0224

— taz

Answer 2

आप PEP257: Docstring सम्मेलनों का हवाला देते हैं, अनुभाग में यह कहा गया है कि क्या है :

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

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

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

उनका उपयोग स्फिंक्स में निर्देशकीय स्वप्रतिरक्षण के साथ किया जाता है

स्फिंक्स एक असाइनमेंट से पहले एक लाइन पर टिप्पणियों का उपयोग कर सकता है या एक असाइनमेंट के बाद एक विशेष टिप्पणी या परिभाषा के बाद एक डॉकस्ट्रिंग जो कि ऑटोडेक्लोनेटेड होगा।

Comments

jedi-vim plugin विशेषता डॉकस्ट्रिंग्स को भी पहचानता है।

— लॉन्ग वू

मुझे नहीं पता कि यह कब पेश किया गया था, लेकिन Sphinx 1.2.2 जनरेट किए गए प्रलेखन में विशेषता डॉकस्ट्रिंग्स को शामिल करता है।

— जोचेन

शुक्रिया @jochen, मैं अपना जवाब अपडेट करता हूं।

— मार्च 19

कृपया ध्यान दें कि PEP 258 अस्वीकृत है। अस्वीकृति नोटिस में कहा गया है: "हालांकि यह अब-स्वतंत्र डोकुटिल के लिए एक दिलचस्प डिजाइन दस्तावेज़ के रूप में काम कर सकता है, यह अब मानक पुस्तकालय में शामिल करने के लिए स्लेट नहीं किया गया है।"

— मिशैल --azowik

Answer 3

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

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

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

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किसी तरह एक-दूसरे के साथ संवाद कर सकती हैं, तो यह स्वचालित रूप से एक लंबे और संभावना नहीं आंतरिक विशेषता नाम पर निर्णय ले सकता है। मुझे यकीन है कि इसे लागू करने के तरीके हैं, लेकिन मुझे यकीन नहीं है कि वे इसके लायक हैं।