পাইথনে ক্লাসের বৈশিষ্ট্যগুলি কীভাবে ডকুমেন্ট করব? [বন্ধ]

Question

আমি একটি লাইটওয়েট শ্রেণি লিখছি যার বৈশিষ্ট্যগুলি সর্বজনীনভাবে অ্যাক্সেসযোগ্য হয়ে ওঠার উদ্দেশ্যে এবং কেবল কখনও কখনও নির্দিষ্ট তাত্ক্ষণিকতায় ওভাররাইড করা হয়। পাইথন ভাষায় শ্রেণীর বৈশিষ্ট্যগুলির জন্য ডকস্ট্রিংস তৈরির জন্য কোনও বিষয় বা কোনও ধরণের বৈশিষ্ট্য নেই that এই বৈশিষ্ট্যগুলি নথিভুক্ত করার জন্য একটি প্রত্যাশিত এবং সমর্থিত উপায় কী? বর্তমানে আমি এই ধরণের জিনিস করছি:

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

যদিও এই স্টাইলটি ডক্ট্রিং স্টাইলের নির্দেশিকায় স্পষ্টভাবে নিষিদ্ধ বলে মনে হচ্ছে না , এটি বিকল্প হিসাবেও উল্লেখ করা হয়নি। এখানে সুবিধাটি হ'ল এটি তার সংজ্ঞাগুলির পাশাপাশি বৈশিষ্ট্যগুলি দলিল করার একটি উপায় সরবরাহ করে, যখন এখনও উপস্থাপনযোগ্য শ্রেণির ডাস্ট্রিং তৈরি করে এবং ডক্টরিং থেকে তথ্য পুনর্বিবেচনা করে এমন মন্তব্য লিখতে অস্বীকার করে। আমি এখনও একধরনের বিরক্ত হয়েছি যে আমাকে আসলে দুটিবার গুণাবলী লিখতে হবে; আমি কমপক্ষে ডিফল্ট মানগুলির সদৃশতা এড়াতে ডকস্ট্রিংয়ের মানগুলির স্ট্রিং উপস্থাপনাগুলি ব্যবহার করার বিষয়ে বিবেচনা করছি।

এটি কি অ্যাডহক সম্প্রদায়ের সম্মেলনের জঘন্য লঙ্ঘন? ঠিক আছে? একটি ভাল উপায় আছে কি? উদাহরণস্বরূপ, গুণাবলীর জন্য মান এবং ডকাস্ট্রিংস যুক্ত একটি অভিধান তৈরি করা এবং তারপরে ক্লাসে বিষয়বস্তুগুলি যুক্ত করে __dict__এবং ক্লাস ঘোষণার শেষের দিকে ডক্ট্রিং করা সম্ভব; এটি বৈশিষ্ট্যের নাম এবং মানগুলি দুবার টাইপ করার প্রয়োজনীয়তা হ্রাস করবে। সম্পাদনা করুন : এই শেষ ধারণাটি আমি মনে করি, বাস্তবে সম্ভব নয়, ডেটা থেকে সম্পূর্ণ ক্লাসটি গতিশীলভাবে তৈরি না করেই করা উচিত যা এটি করার অন্য কোনও কারণ না থাকলে সত্যই খারাপ ধারণা বলে মনে হয়।

আমি অজগর থেকে বেশ নতুন এবং এখনও কোডিং স্টাইলের বিশদটি প্রকাশ করছি, তাই সম্পর্কযুক্ত সমালোচনাও স্বাগত।

Comments

আপনি যদি জ্যাঙ্গো মডেল বৈশিষ্ট্যগুলি নথিভুক্ত করার কোনও উপায় খুঁজছেন তবে এটি সহায়ক হতে পারে: djangosnippets.org/snippets/2533

— মাইকেল

পাইথনে ক্ষেত্র এবং সম্পত্তি কীভাবে নথির নকল ? যা ভিন্ন সমাধান ধারণ করে।

— বুফ

কেন এটি মতামত ভিত্তিক আমি পাই না। পাইথন বিশেষভাবে এটি পিইপিগুলিতে গ্রহণযোগ্য সম্মেলনের দলিল করে। বিভিন্ন পাইথন উত্স সরঞ্জাম রয়েছে যা সঠিকভাবে ফর্ম্যাট করা ডকুমেন্টেশনগুলি বের করে ract বাস্তবে পাইথনের আসলে পিইপি 257 তে একটি attribute doc stringউল্লেখ রয়েছে যা সুপরিচিত নয় এবং এটি খুঁজে পাওয়া শক্ত মনে হয় যা ওপিএস প্রশ্নের উত্তর দিতে পারে, এবং এটি কিছু উত্স সরঞ্জাম দ্বারা সমর্থিত। এটি মতামত নয়। এটি সত্য, এবং ভাষার একটি অংশ এবং প্রায়শই ঠিক ওপি কী চায়।

— নীলজি

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"

আমি মনে করি এটি আপনার উদাহরণের পদ্ধতির চেয়ে চোখের দিকে অনেক সহজ। আমি যদি ডক স্ট্রিংটিতে সত্যিকারের মানগুলির একটি অনুলিপি উপস্থিত হতে চাইতাম তবে আমি প্রতিটি বৈশিষ্ট্যের বর্ণনার পাশে বা নীচে রেখে দেব put

মনে রাখবেন পাইথনে, ডক স্ট্রিংগুলি তারা নথিভুক্ত অবজেক্টগুলির প্রকৃত সদস্য, কেবল উত্স কোড টীকা নয়। যেহেতু শ্রেণীর বৈশিষ্ট্য ভেরিয়েবলগুলি নিজেরাই বস্তু নয় বরং বস্তুর উল্লেখ re তাই তাদের নিজস্ব ডক স্ট্রিং রাখার কোনও উপায় নেই। আমার অনুমান যে আপনি রেফারেন্সগুলিতে ডক স্ট্রিংয়ের জন্য একটি মামলা করতে পারেন, সম্ভবত "এখানে কী হওয়া উচিত" "আসলে এখানে কী আছে" এর পরিবর্তে, তবে আমি ক্লাসযুক্ত ডক স্ট্রিংটিতে এটি করা খুব সহজ বলে মনে করি।

Comments

আমার ধারণা বেশিরভাগ ক্ষেত্রেই এটি ঠিক আছে, যেহেতু পরিভাষা সংশোধন করার জন্য গুণাবলী - সংক্ষিপ্তভাবে যথেষ্ট ঘোষণা করা হয়েছে যে ক্লাস ঘোষণার শুরুতে তাদের কেবলমাত্র পিছনে পিছনে ফ্লিপ করা অবৈজ্ঞানিক না করেই শ্রেণিবদ্ধ করা যেতে পারে - উভয়ই পড়ুন ডকুমেন্টেশন এবং ডিফল্ট মান} বা both ডকুমেন্টেশন এবং / অথবা ডিফল্ট মান both উভয়ই আপডেট করে}

— intuited

এছাড়াও নোট করুন যে আমার উদাহরণটি ক্লাসের ডক্ট্রিংয়ে বৈশিষ্ট্যগুলির জন্য ডকুমেন্টেশন দেখা দেবে। আমি প্রকৃতপক্ষে গুণাবলীর ডকস্ট্রিংগুলিতে ডকুমেন্টেশনগুলিকে নিজেরাই পছন্দ করতে চাই, তবে এটি বেশিরভাগ বিল্টিন ধরণের জন্য কাজ করে না।

— 16:22

হ্যাঁ, আমার প্রাথমিক ধারণাটি ছিল কেবল উদাহরণ হিসাবে ঘোষণা করা flight_speed = 691; flight_speed.__doc__ = "blah blah"। আমি মনে করি এটি আপনার সম্পাদনায় উল্লেখ করেছেন । দুর্ভাগ্যক্রমে, এটি (সর্বাধিক?) অন্তর্নির্মিত ধরণের ইনস্ট্যান্টেশনের জন্য কাজ করে না ( intউদাহরণস্বরূপ)। এটি ব্যবহারকারী-সংজ্ঞায়িত প্রকারের ইনস্ট্যান্টেশনগুলির জন্য কাজ করে। =========== প্রকৃতপক্ষে একটি পিইপি ছিল (দুঃখিত, সংখ্যাটি ভুলে যান) যা শ্রেণি / মডিউল বৈশিষ্ট্যের জন্য ডকাস্ট্রিং যুক্ত করার প্রস্তাব করেছিল, তবে এটি অস্বীকার করা হয়েছিল কারণ তারা এটিকে পরিষ্কার করার কোনও উপায় বের করতে পারেনি they ডকাস্ট্রিংগুলি পূর্ববর্তী বা নিম্নলিখিত বৈশিষ্ট্যের জন্য ছিল কিনা।

— intuited

সুতরাং যদি তারা উদাহরণস্বরূপ বৈশিষ্ট্য হয়? ক্লাসের ডাস্ট্রিংয়ে এখনও ডকুমেন্ট বা কী?

— n611x007

@intuited এটি কি এই পিইপি ছিল? legacy.python.org/dev/peps/pep-0224

— তাজ

Answer 2

আপনি পিইপি 257: ডক্ট্রিং কনভেনশনগুলি উল্লেখ করেছেন, যে বিভাগে এটি একটি ডক্টস্ট্রিং কী তা বলা হয়েছে:

পাইথন কোডের অন্য কোথাও স্ট্রিং লিটারেলগুলি ডকুমেন্টেশন হিসাবেও কাজ করতে পারে। এগুলি পাইথন বাইটকোড সংকলক দ্বারা স্বীকৃত নয় এবং রানটাইম অবজেক্ট অ্যাট্রিবিউট (যেমন __doc__- এর জন্য নির্ধারিত নয়) হিসাবে অ্যাক্সেসযোগ্য নয়, তবে সফটওয়্যার সরঞ্জাম দ্বারা দুটি ধরণের অতিরিক্ত ডকস্ট্রিংগুলি বের করা যেতে পারে:

মডিউল, শ্রেণি বা __init__ পদ্ধতির শীর্ষ স্তরে একটি সরল অ্যাসাইনমেন্টের সাথে সাথেই স্ট্রিং লিটারেলগুলি ঘটে তাকে "অ্যাট্রিবিউট ডকাস্ট্রিংস" বলা হয়।

এবং এটি পিইপি 258 এ আরও বিশদে ব্যাখ্যা করা হয়েছে: অ্যাট্রিবিউট ডকাস্ট্রিংস। যেমন উপরোক্ত ব্যাখ্যা। একটি অ্যাট্রিবিউট এমন কোনও বস্তু নয় যা একটি __ ডোক__ এর মালিক হতে পারে যাতে তারা উপস্থিত হয় না help()বা পাইডোক। এই ডকাস্ট্রিংগুলি কেবল উত্পন্ন ডকুমেন্টেশনের জন্য ব্যবহার করা যেতে পারে।

এগুলি স্পিঙ্কস-এ নির্দেশাবলী অটোঅ্যাট্রিবিউটের সাথে ব্যবহৃত হয়

স্পিনিক্স একটি অ্যাসাইনমেন্টের আগে একটি লাইনে মন্তব্যগুলি ব্যবহার করতে পারে বা কোনও কার্যনির্বাহীকরণের পরে একটি বিশেষ মন্তব্য বা সংজ্ঞা অনুসরণের পরে একটি ডক্টস্ট্রিং যা স্বতঃবীক্ষণযোগ্য হবে তা ব্যবহার করতে পারে।

Comments

জেডি-ভিআইএম প্লাগইনটি অ্যাট্রিবিউট ডকস্ট্রিংগুলিও সনাক্ত করে।

— দীর্ঘ ভু

কখন এটি প্রবর্তিত হয়েছিল তা আমি জানি না, তবে স্পিঙ্কস ১.২.২ উত্পন্ন ডকুমেন্টেশনে অ্যাট্রিবিউট ডকস্টাস্টিংগুলিকে অন্তর্ভুক্ত বলে মনে হচ্ছে।

— জোচেন

আপনাকে @ জোচেন ধন্যবাদ, আমি আমার উত্তর আপডেট।

— মার্কজ

দয়া করে নোট করুন যে পিইপি 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

তারপরে আপনার কাছে সিএক্সের একটি ডক্ট্রিং থাকবে:

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

অনেক গুণাবলীর জন্য এটি করা কষ্টকর, তবে আপনি কোনও সহায়ক ফাংশন মাইপ্রোপ কল্পনা করতে পারেন:

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কোনওরকম একে অপরের সাথে যোগাযোগ করতে পারে তবে এটি দীর্ঘ এবং অসম্ভব অভ্যন্তরীণ বৈশিষ্ট্যের নামটি স্বয়ংক্রিয়ভাবে সিদ্ধান্ত নিতে পারে। আমি নিশ্চিত যে এটি বাস্তবায়নের জন্য কিছু উপায় আছে তবে আমি নিশ্চিত নই যে তারা এগুলি মূল্যবান কিনা।