स्फिंक्स दस्तावेज़ मॉड्यूल गुण

Question

मेरे पास एक मॉड्यूल है जिसमें @property होना चाहिए, मैंने मॉड्यूल के रूप में कक्षा सेट करके इसे हल किया। मुझे इस जवाब से विचार मिला: Lazy module variables--can it be done?

मैं चाहता था कि यह दोहराने योग्य और उपयोग में आसान हो ताकि मैंने इसके लिए मेटाक्लास बनाया हो। यह एक आकर्षण की तरह काम करता है।

समस्या यह है कि जब स्पंजिक्स का उपयोग प्रलेखन गुण उत्पन्न करने के लिए दस्तावेज नहीं मिलता है। बाकी सब कुछ अपेक्षित के रूप में दस्तावेज है। मुझे नहीं पता कि इसे कैसे ठीक किया जाए, शायद यह स्फिंक्स के साथ एक समस्या है?

मॉड्यूल:

import sys 
import types 

class ClassAsModule(type): 
    def __new__(cls, name, bases, attrs): 
     # Make sure the name of the class is the module name. 
     name = attrs.pop('__module__') 
     # Create a class. 
     cls = type.__new__(cls, name, bases, attrs) 
     # Instantiate the class and register it. 
     sys.modules[name] = cls = cls(name) 
     # Update the dict so dir works properly 
     cls.__dict__.update(attrs) 

class TestClass(types.ModuleType): 
    """TestClass docstring.""" 
    __metaclass__ = ClassAsModule 
    @property 
    def some_property(self): 
     """Property docstring.""" 
     pass 
    def meth(): 
     """meth doc""" 
     pass 

और एक कॉपी-पेस्ट उत्पन्न करने के लिए/देखने स्फिंक्स प्रलेखन:

sphinx-apidoc . -o doc --full 
sphinx-build doc html 
xdg-open html/module.html 

सबसे जरूरी हिस्सा वर्ग 'गुण दस्तावेज़ के लिए है। मूल मॉड्यूल सदस्यों को दस्तावेज करने के लिए बोनस अंक भी।

संपादित करें: कक्षा को मॉड्यूल के रूप में दस्तावेज किया जाना चाहिए। कक्षा इस तरह प्रयोग की जाती है और इस प्रकार स्फिंक्स में इस तरह दिखाई देनी चाहिए।

वांछित आउटपुट का उदाहरण:

Module Foo 
    TestClass docstring. 

    some_property 
     Property docstring. 

    meth() 
     meth doc 

संपादित करें 2: मैं कुछ है कि एक समाधान खोजने में सहायता कर सकते हैं पाया। जब निम्नलिखित सामग्री के साथ एक नियमित रूप से मॉड्यूल foo होने:

#: Property of foo 
prop = 'test' 

स्फिंक्स दस्तावेज इस तरह:

foo.prop = 'test' 
    Property of foo 

एक ही काम करता है अगर prop एक वर्ग की एक विशेषता है। मुझे पता नहीं चला है कि यह मेरे विशेष मामले में क्यों काम नहीं करता है।

Answer 1

मेरी समझ है।

सिद्धांत है: बनाने एक मॉड्यूल इस (एक सा hacky) जिस तरह से स्फिंक्स लगता है कि वह (पार्स करने के लिए) मॉड्यूल से की जरूरत नहीं है गुण (क्योंकि यह एक वर्ग स्तर के प्रतिमान है बनाता है की तरह एक उत्परिवर्ती अपनी कक्षा अधिनियम)। तो, स्फिंक्स के लिए, एक मॉड्यूल है।

class ClassAsModule(type): 
    pass 

हम डॉक्स में देखेंगे:: -

सबसे पहले, यह सुनिश्चित करें कि अपराधी एक मॉड्यूल की तरह एक वर्ग अधिनियम बनाने के लिए कोड है बनाने के लिए इसे निकाल देने के

package Package 
    script Module 

    class package.script.ClassAsModule 
     Bases: type 

    class package.script.TestClass 
     Bases: module 

     TestClass docstring. 

     meth() 
      meth doc 

     some_property 
      Property docstring. 

जैसा कि आप देखते हैं, स्फिंक्स बिना किसी समस्या के संपत्ति को पढ़ते हैं। यहाँ कुछ खास नहीं है। आपकी समस्या के लिए

---

संभव समाधान @property डेकोरेटर का उपयोग कर से बचने और property वर्ग निर्माता बुला से बदलने के लिए है। जैसे:

import sys 
import types 

class ClassAsModule(type): 
    def __new__(cls, name, bases, attrs): 
     # Make sure the name of the class is the module name. 
     name = attrs.pop('__module__') 
     # Create a class. 
     cls = type.__new__(cls, name, bases, attrs) 
     # Instantiate the class and register it. 
     sys.modules[name] = cls = cls(name) 
     # Update the dict so dir works properly 
     cls.__dict__.update(attrs) 


class TestClass(types.ModuleType): 
    """TestClass docstring.""" 
    __metaclass__ = ClassAsModule 

    def get_some_property(self): 
     """Property docstring.""" 
     pass 

    some_property = property(get_some_property) 

    def meth(self): 
     """meth doc""" 
     pass 

इस कोड को स्फिंक्स के लिए उत्पन्न करता है:

package Package 
    script Module 
     TestClass docstring. 

      package.script.get_some_property(self) 
       Property docstring. 

      package.script.meth(self) 
       meth doc 

हो सकता है जवाब बकवास का एक टुकड़ा है, लेकिन मुझे आशा है कि यह सही दिशा की ओर आकर्षित होगा।

Answer 2

तरह से मैं पाया है कि सबसे अच्छा काम करता फ़ाइल की सामग्री एक ही रखने के लिए के रूप में यदि आप एक नियमित मॉड्यूल लिख रहे थे है, तो अंत में sys.modules में भ्रूण मॉड्यूल की जगह:

"""Module docstring. """ 

import sys 
import types 

def _some_property(self): 
    pass 
some_property = property(_some_property) 
"""Property docstring.""" 

def meth(): 
    """meth doc""" 
    pass 

def _make_class_module(name): 
    mod = sys.modules[name] 
    cls = type('ClassModule', (types.ModuleType,), mod.__dict__) 
    clsmod = cls(name) 
    clsmod.__dict__.update(mod.__dict__) 
    clsmod.__wrapped__ = mod 
    sys.modules[name] = clsmod 
_make_class_module(__name__) 

पाठ प्रलेखन :

mymod Module 
************ 

Module docstring. 

mymod.meth() 

    meth doc 

mymod.some_property = None 

    Property docstring. 

मैं (v1.1.3) का उपयोग कर रहा स्फिंक्स के संस्करण के लिए, ऐसा लगता है कि आप (यदि आप एक डेकोरेटर के रूप में उपयोग नहीं कर सकते हैं) स्पष्ट रूप से संपत्ति निर्माता आवेदन करना होगा लग रहा है, और docstring है निर्माण के बाद लाइन पर शीर्ष स्तर पर फ़ाइल में जाने के लिए या कॉल करें जो संपत्ति बनाता है (यह संपत्ति गेटटर के अंदर एक डॉकस्ट्रिंग के रूप में काम नहीं करता है)। हालांकि, स्रोत अभी भी काफी पठनीय है।