पायथन फ़ाइलों का सामान्य हेडर प्रारूप क्या है?

508

मैं पायथन कोडिंग दिशानिर्देशों के बारे में एक दस्तावेज़ में पायथन स्रोत फ़ाइलों के लिए निम्नलिखित हेडर प्रारूप में आया था:

#!/usr/bin/env python

"""Foobar.py: Description of what foobar does."""

__author__      = "Barack Obama"
__copyright__   = "Copyright 2009, Planet Earth"

क्या यह पायथन दुनिया में हेडर का मानक प्रारूप है? मैं हेडर में कौन से अन्य क्षेत्र / जानकारी डाल सकता हूँ? पायथन गुरु अच्छे पायथन स्रोत हेडर के लिए अपने दिशानिर्देश साझा करते हैं :-)

python header comments

— अश्विन नंजप्पा
स्रोत

यहां शुरू करने के लिए एक अच्छी जगह है: पीईपी 257 , जो डॉकस्ट्रिंग्स के बारे में बात करता है, और कई अन्य प्रासंगिक दस्तावेजों के लिंक।

— पीटर

41

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

— जोनाथन हार्टले

हाहा महान @ जोनाथनहार्टले! अपनी खुद की परियोजनाओं के लिए, जैसा कि आप इसे "मैं अपने ओसीडी बुत को लिप्त करता हूं।" hahaaha stackoverflow.com/a/51914806/1896134

— JayRizzo

577

Foobarमॉड्यूल के लिए इसकी सभी मेटाडेटा ।

पहला एक docstringमॉड्यूल है, जो पहले से ही पीटर के जवाब में समझाया गया है ।

मैं अपने मॉड्यूल (स्रोत फ़ाइलों) को कैसे व्यवस्थित करूं? (पुरालेख)

प्रत्येक फ़ाइल की पहली पंक्ति जोर से हो #!/usr/bin/env python। यह फ़ाइल को एक स्क्रिप्ट के रूप में चलाना संभव बनाता है जो इंटरप्रेटर को स्पष्ट रूप से लागू करता है, उदाहरण के लिए CGI संदर्भ में।

अगला एक विवरण के साथ docstring होना चाहिए। यदि विवरण लंबा है, तो पहली पंक्ति एक संक्षिप्त सारांश होनी चाहिए जो अपने आप में समझ में आता है, शेष को एक नई रेखा द्वारा अलग किया जाता है।

आयात विवरण सहित सभी कोड को डॉकस्ट्रिंग का पालन करना चाहिए। अन्यथा, डॉकस्ट्रिंग को दुभाषिया द्वारा मान्यता नहीं दी जाएगी, और आपके पास इंटरेक्टिव सत्र (अर्थात obj.__doc__) के माध्यम से या स्वचालित टूल के साथ प्रलेखन उत्पन्न करते समय इसका उपयोग नहीं होगा ।

पहले निर्मित मॉड्यूल आयात करें, उसके बाद तीसरे पक्ष के मॉड्यूल, पथ और अपने स्वयं के मॉड्यूल में किसी भी बदलाव के बाद। विशेष रूप से, आपके मॉड्यूल के पथ और नामों के परिवर्धन में तेजी से परिवर्तन होने की संभावना है: उन्हें एक स्थान पर रखने से उन्हें ढूंढना आसान हो जाता है।

इसके बाद लेखक की जानकारी होनी चाहिए। यह जानकारी इस प्रारूप का पालन करना चाहिए:
__author__ = "Rob Knight, Gavin Huttley, and Peter Maxwell"
__copyright__ = "Copyright 2007, The Cogent Project"
__credits__ = ["Rob Knight", "Peter Maxwell", "Gavin Huttley",
                    "Matthew Wakefield"]
__license__ = "GPL"
__version__ = "1.0.1"
__maintainer__ = "Rob Knight"
__email__ = "rob@spot.colorado.edu"
__status__ = "Production"
स्थिति आमतौर पर "प्रोटोटाइप", "विकास", या "उत्पादन" में से एक होनी चाहिए। __maintainer__ऐसा व्यक्ति होना चाहिए जो बग्स को ठीक करेगा और आयात किए जाने पर सुधार करेगा। __credits__इसमें से भिन्न लोगों __author__में __credits__बग फिक्स, रिपोर्ट किए गए सुझाव आदि शामिल हैं, लेकिन वास्तव में कोड नहीं लिखा था।

यहाँ आप अधिक जानकारी लिस्टिंग है, __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__और __version__के रूप में पहचाना मेटाडाटा।

— एस्टेबन कुबेर
स्रोत

7

क्या हेडर जानकारी का निर्माण किसी भी तरह से नई फ़ाइलों के लिए स्वचालित हो सकता है?

— Hauke

184

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

— जोनाथन हार्टले

28

जोनाथन हार्टले से पूरी तरह सहमत हैं। कोड को प्राप्त करने के लिए अगले व्यक्ति के पास तीन विकल्प हैं: 1) हर बार यह अपडेट करें कि वह कोड 2 को संपादित करता है) उसे अकेला छोड़ दें, इस मामले में यह 3 गलत होगा) सभी इसे हटा दें। विकल्प 1 उनके समय की बर्बादी है, खासकर जब से उन्हें पूरी तरह से विश्वास है कि मेटाडेटा तारीख तक था जब उन्होंने इसे प्राप्त किया। विकल्प 2 और 3 का मतलब है कि इसे वहां रखने में आपका समय बर्बाद हो गया। समाधान: हर किसी के समय को बचाएं और इसे वहां न डालें।

— spookylukey

77

अधिकांश पायथन फ़ाइलों के लिए एक शेबंग लाइन होने का कोई कारण नहीं है।

— माइक ग्राहम

15

प्रति पीईपी 8 में, __version__पहले और बाद में एक खाली लाइन के साथ, मुख्य डॉकस्ट्रिंग का सीधे पालन करने की आवश्यकता होती है। इसके अलावा, यह सबसे अच्छा अभ्यास है कि आप # -*- coding: utf-8 -*-

— शेर्बांग के

179

मैं दृढ़ता से न्यूनतम फ़ाइल हेडर का समर्थन करता हूं, जिसके द्वारा मेरा मतलब है:

हैशबैंग ( #!लाइन) यदि यह एक निष्पादन योग्य स्क्रिप्ट है
मॉड्यूल docstring
आयात, मानक तरीके से समूहीकृत, जैसे:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule

अर्थात। आयातों के तीन समूह, उनके बीच एक एकल रिक्त रेखा के साथ। प्रत्येक समूह के भीतर, आयात को क्रमबद्ध किया जाता है। अंतिम समूह, स्थानीय स्रोत से आयात, या तो पूर्ण आयात हो सकता है जैसा कि दिखाया गया है, या स्पष्ट सापेक्ष आयात।

बाकी सब कुछ समय की बर्बादी, दृश्य स्थान है, और सक्रिय रूप से भ्रामक है।

यदि आपके पास कानूनी अस्वीकरण या लाइसेंसिंग जानकारी है, तो यह एक अलग फ़ाइल में जाती है। यह हर स्रोत कोड फ़ाइल को संक्रमित करने की आवश्यकता नहीं है। आपका कॉपीराइट इसका हिस्सा होना चाहिए। लोगों को इसे आपकी LICENSEफ़ाइल में खोजने में सक्षम होना चाहिए , न कि यादृच्छिक स्रोत कोड।

मेटाडेटा जैसे कि ऑथरशिप और डेट्स आपके सोर्स कंट्रोल द्वारा पहले से ही बनाए हुए हैं। फ़ाइल में ही जानकारी के कम-विस्तृत, गलत, और आउट-ऑफ-डेट संस्करण को जोड़ने की कोई आवश्यकता नहीं है।

मेरा मानना है कि कोई भी अन्य डेटा है जिसे सभी को अपनी सभी स्रोत फ़ाइलों में डालने की आवश्यकता है। ऐसा करने के लिए आपको कुछ विशेष आवश्यकता हो सकती है, लेकिन ऐसी चीजें केवल परिभाषा के अनुसार लागू होती हैं। "सभी के लिए अनुशंसित सामान्य हेडर" में उनका कोई स्थान नहीं है।

— जोनाथन हार्टले
स्रोत

23

अधिक सहमत नहीं हो सकता है - यह कई स्थानों पर कोड को दोहराने के लिए एक पाप है इसलिए एक हेडर जानकारी के लिए ऐसा ही क्यों करें। इसे एक ही जगह (प्रोजेक्ट रूट) में रखें और कई, कई फाइलों में ऐसी जानकारी को बनाए रखने की परेशानी से बचें।

— ग्रीम

13

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

— प्राम

6

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

— जोनाथन हार्टले

12

कई लाइसेंस के लिए आपको बहुत अच्छे कारण के लिए प्रत्येक फ़ाइल में लाइसेंस बॉयलरप्लेट शामिल करना होगा। यदि कोई फ़ाइल या दो लेता है और उन्हें लाइसेंस के बिना पुनर्वितरित करता है, तो इसे प्राप्त करने वाले लोगों को पता नहीं है कि यह किस लाइसेंस के तहत है, और इसे नीचे ट्रेस करना होगा (यह मानते हुए कि वे अच्छे विश्वास में हैं, यह है)।

— nyuszika7h

3

मॉड्यूल के बहुत सारे (डरावना, सुन्न, matplotlib) __version__मेटाडेटा है, हालांकि, और मुझे लगता है कि यह अच्छा है, क्योंकि यह कार्यक्रमों के लिए सुलभ होना चाहिए और इंटरैक्टिव दुभाषिया में जल्दी से जांचना चाहिए। प्रमाणीकरण और कानूनी जानकारी एक अलग फ़ाइल में है, हालांकि। जब तक आपके पास उपयोग का मामला न होif 'Rob' in __author__:

— एंडॉलिथ

34

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

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""Module documentation goes here
   and here
   and ...
"""

यह एक अच्छा क्यों है:

पहली पंक्ति * निक्स उपयोगकर्ताओं के लिए है। यह उपयोगकर्ता पथ में पायथन इंटरप्रेटर का चयन करेगा, इसलिए स्वचालित रूप से उपयोगकर्ता द्वारा पसंद किए गए इंटरप्रेटर का चयन करेगा।
दूसरा एक फ़ाइल एन्कोडिंग है। आजकल हर फाइल में एक एन्कोडिंग जुड़ा होना चाहिए। यूटीएफ -8 हर जगह काम करेगा। बस विरासत परियोजनाएं अन्य एन्कोडिंग का उपयोग करेंगी।
और एक बहुत ही सरल प्रलेखन। यह कई लाइनों को भर सकता है।

इसे भी देखें: https://www.python.org/dev/peps/pep-0263/

यदि आप प्रत्येक फ़ाइल में सिर्फ एक वर्ग लिखते हैं, तो आपको प्रलेखन की भी आवश्यकता नहीं है (यह कक्षा के अंदर जाएगा)।

— नेवेस
स्रोत

5

> "आजकल हर फ़ाइल में एक एन्कोडिंग जुड़ा होना चाहिए।" यह भ्रामक लगता है। utf8 डिफ़ॉल्ट एन्कोडिंग है, इसलिए इसे निर्दिष्ट नहीं करना पूरी तरह से ठीक है।

— जोनाथन हार्टले

23

पीईपी 263 को भी देखें अगर आप गैर-असिसी पात्र का उपयोग कर रहे हैं

सार

यह PEP पायथन स्रोत फ़ाइल के एन्कोडिंग को घोषित करने के लिए एक सिंटैक्स पेश करने का प्रस्ताव करता है। फिर एन्कोडिंग जानकारी पायथन पार्सर द्वारा दी गई एन्कोडिंग का उपयोग करके फ़ाइल की व्याख्या करने के लिए उपयोग की जाती है। सबसे विशेष रूप से यह स्रोत कोड में यूनिकोड शाब्दिकों की व्याख्या को बढ़ाता है और यूनिकोड जागरूक संपादक में सीधे यूटीएफ -8 का उपयोग करके यूनिकोड शाब्दिक लिखना संभव बनाता है।

मुसीबत

पायथन 2.1 में, यूनिकोड शाब्दिक केवल लैटिन -1 आधारित एन्कोडिंग "यूनिकोड-एस्केप" का उपयोग करके लिखा जा सकता है। यह उन पायथन उपयोगकर्ताओं के लिए प्रोग्रामिंग वातावरण नहीं बनाता है जो एशियाई देशों के गैर-लैटिन -1 स्थानों में रहते हैं और काम करते हैं। प्रोग्रामर पसंदीदा एन्कोडिंग का उपयोग करके अपने 8-बिट स्ट्रिंग्स लिख सकते हैं, लेकिन यूनिकोड शाब्दिकों के लिए "यूनिकोड-एस्केप" एन्कोडिंग के लिए बाध्य हैं।

प्रस्तावित समाधान

मैं पायथन स्रोत कोड एन्कोडिंग को घोषित करने के लिए फ़ाइल के शीर्ष पर एक विशेष टिप्पणी का उपयोग करके, प्रति-स्रोत फ़ाइल आधार पर दृश्यमान और परिवर्तनशील दोनों को एन्कोडिंग बनाने का प्रस्ताव करता हूं।

इस एन्कोडिंग घोषणा के बारे में पायथन को अवगत कराने के लिए पायथन स्रोत कोड डेटा की हैंडलिंग के संबंध में कई अवधारणा परिवर्तन आवश्यक हैं।

एनकोडिंग को परिभाषित करना

यदि कोई अन्य एन्कोडिंग संकेत नहीं दिया जाता है तो पायथन मानक एन्कोडिंग के रूप में ASCII को डिफ़ॉल्ट करेगा।

स्रोत कोड एन्कोडिंग को परिभाषित करने के लिए, एक जादुई टिप्पणी को स्रोत फ़ाइलों में फ़ाइल में पहली या दूसरी पंक्ति में रखा जाना चाहिए, जैसे:
      # coding=<encoding name>
या (लोकप्रिय संपादकों द्वारा मान्यता प्राप्त स्वरूपों का उपयोग करके)
      #!/usr/bin/python
      # -*- coding: <encoding name> -*-
या
      #!/usr/bin/python
      # vim: set fileencoding=<encoding name> :
...

— जॉन ला रोय
स्रोत

15

यह ध्यान देने योग्य है कि पायथन 3 के बाद से, डिफ़ॉल्ट चरित्र सेट UTF-8 है।

— nyuszika7h