รูปแบบส่วนหัวทั่วไปของไฟล์ Python คืออะไร

ฉันพบรูปแบบส่วนหัวต่อไปนี้สำหรับไฟล์ต้นฉบับ Python ในเอกสารเกี่ยวกับแนวทางการเข้ารหัสของ Python:

#!/usr/bin/env python

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

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

นี่เป็นรูปแบบมาตรฐานของส่วนหัวในโลก Python หรือไม่ ฉันสามารถใส่ฟิลด์ / ข้อมูลอื่นใดในส่วนหัวได้บ้าง ปรมาจารย์ Python แบ่งปันแนวทางของคุณสำหรับส่วนหัวแหล่ง Python ที่ดี :-)

มันเป็นข้อมูลเมตาทั้งหมดสำหรับFoobarโมดูล

คนแรกเป็นdocstringของโมดูลที่จะมีการอธิบายไว้แล้วในคำตอบของปีเตอร์

ฉันจะจัดระเบียบโมดูล (ไฟล์ต้นฉบับ) ได้อย่างไร (Archive)

บรรทัดแรกของแต่ละไฟล์ shoud #!/usr/bin/env pythonคือ สิ่งนี้ทำให้เป็นไปได้ที่จะเรียกใช้ไฟล์เป็นสคริปต์ที่เรียกล่ามโดยปริยายเช่นในบริบท CGI

ถัดไปควรเป็น docstring พร้อมคำอธิบาย หากคำอธิบายยาวบรรทัดแรกควรเป็นบทสรุปสั้น ๆ ที่สมเหตุสมผลโดยแยกบรรทัดใหม่ออกจากส่วนที่เหลือ

รหัสทั้งหมดรวมถึงข้อความสั่งการนำเข้าควรเป็นไปตาม docstring มิฉะนั้น 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__เป็นที่ยอมรับเมตาดาต้า

ฉันชอบส่วนหัวไฟล์ที่น้อยที่สุดซึ่งฉันหมายถึงเพียง:

• hashbang ( #!บรรทัด) หากนี่เป็นสคริปต์ที่ปฏิบัติการได้
• โมดูล docstring
• นำเข้าจัดกลุ่มตามวิธีมาตรฐานเช่น:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

กล่าวคือ การนำเข้าสามกลุ่มโดยมีบรรทัดว่างหนึ่งบรรทัดระหว่างทั้งสอง ภายในแต่ละกลุ่มการนำเข้าจะถูกจัดเรียง กลุ่มสุดท้ายการนำเข้าจากแหล่งภายในอาจเป็นการนำเข้าแบบสัมบูรณ์ตามที่แสดงหรือการนำเข้าแบบสัมพัทธ์อย่างชัดเจน

ทุกสิ่งทุกอย่างไม่ต้องเสียเวลาพื้นที่ภาพและทำให้เข้าใจผิดอย่างแข็งขัน

หากคุณมีข้อจำกัดความรับผิดชอบทางกฎหมายหรือข้อมูลการอนุญาตให้ใช้สิทธิ์ข้อมูลดังกล่าวจะอยู่ในไฟล์แยกต่างหาก ไม่จำเป็นต้องติดทุกไฟล์ซอร์สโค้ด ลิขสิทธิ์ของคุณควรเป็นส่วนหนึ่งของสิ่งนี้ คนควรจะสามารถค้นหาได้ในLICENSEไฟล์ของคุณไม่ใช่ซอร์สโค้ดแบบสุ่ม

ข้อมูลเมตาเช่นการประพันธ์และวันที่ได้รับการดูแลโดยแหล่งข้อมูลของคุณแล้ว ไม่จำเป็นต้องเพิ่มข้อมูลที่เหมือนกันในรายละเอียดผิดพลาดและล้าสมัยในไฟล์

ฉันไม่เชื่อว่ามีข้อมูลอื่นใดที่ทุกคนต้องใส่ลงในไฟล์ต้นฉบับทั้งหมด คุณอาจมีข้อกำหนดเฉพาะบางประการที่จะทำเช่นนั้น แต่โดยสิ่งเหล่านั้นมีผลกับคุณโดยเฉพาะ พวกเขาไม่มีที่ใน "ส่วนหัวทั่วไปที่แนะนำสำหรับทุกคน"

คำตอบข้างต้นนั้นเสร็จสมบูรณ์จริง ๆ แต่ถ้าคุณต้องการส่วนหัวที่รวดเร็วและสกปรกเพื่อ copy'n แปะใช้นี้:

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

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

ทำไมสิ่งนี้ถึงดี:

• บรรทัดแรกสำหรับผู้ใช้ * nix มันจะเลือก Python interpreter ในพา ธ ผู้ใช้ดังนั้นจะเลือกล่ามที่ผู้ใช้ต้องการโดยอัตโนมัติ
• อันที่สองคือการเข้ารหัสไฟล์ ทุกวันนี้ทุกไฟล์จะต้องมีการเข้ารหัสที่เกี่ยวข้อง UTF-8 จะทำงานได้ทุกที่ แค่โครงการดั้งเดิมจะใช้การเข้ารหัสอื่น ๆ
• และเอกสารที่ง่ายมาก มันสามารถเติมหลายบรรทัด

ดูเพิ่มเติมที่: https://www.python.org/dev/peps/pep-0263/

หากคุณเพิ่งเขียนคลาสในแต่ละไฟล์คุณไม่จำเป็นต้องมีเอกสารประกอบ (มันจะอยู่ในเอกสารชั้นเรียน)

ดูPEP 263 ด้วยถ้าคุณใช้ชุดอักขระที่ไม่ใช่ ASCII

นามธรรม

PEP นี้เสนอให้แนะนำไวยากรณ์เพื่อประกาศการเข้ารหัสของไฟล์ต้นฉบับ Python จากนั้นข้อมูลการเข้ารหัสจะถูกใช้โดยตัวแยกวิเคราะห์ Python เพื่อตีความไฟล์โดยใช้การเข้ารหัสที่กำหนด สิ่งที่สะดุดตาที่สุดคือการปรับปรุงการตีความตัวอักษร Unicode ในซอร์สโค้ดและทำให้สามารถเขียนตัวอักษร Unicode โดยใช้ UTF-8 ได้โดยตรงในโปรแกรมแก้ไข Unicode

ปัญหา

ใน Python 2.1 ตัวอักษร Unicode สามารถเขียนได้โดยใช้การเข้ารหัสแบบ Latin-1 โดยใช้ "unicode-escape" สิ่งนี้ทำให้สภาพแวดล้อมในการเขียนโปรแกรมค่อนข้างไม่เป็นมิตรกับผู้ใช้ Python ที่อาศัยและทำงานในสถานที่ที่ไม่ใช่ภาษาละตินเช่นประเทศในเอเชียหลายแห่ง โปรแกรมเมอร์สามารถเขียนสตริง 8 บิตของพวกเขาโดยใช้การเข้ารหัสที่ชื่นชอบ แต่ผูกพันกับการเข้ารหัส "unicode-escape" สำหรับตัวอักษร Unicode

โซลูชันที่เสนอ

ฉันเสนอให้ทำการเข้ารหัสซอร์สของ Python ทั้งที่มองเห็นและเปลี่ยนแปลงได้บนพื้นฐานของไฟล์ต่อซอร์สโดยใช้ความคิดเห็นพิเศษที่ด้านบนของไฟล์เพื่อประกาศการเข้ารหัส

เพื่อให้ Python ตระหนักถึงการประกาศการเข้ารหัสนี้จำเป็นต้องมีการเปลี่ยนแปลงแนวความคิดเกี่ยวกับการจัดการข้อมูลรหัส Python

การกำหนดการเข้ารหัส

Python จะใช้ค่าเริ่มต้นเป็น ASCII เป็นการเข้ารหัสมาตรฐานหากไม่มีการให้คำแนะนำการเข้ารหัสอื่น ๆ

ในการกำหนดการเข้ารหัสซอร์สโค้ดความคิดเห็นเวทย์มนตร์จะต้องอยู่ในไฟล์ต้นฉบับไม่ว่าจะเป็นบรรทัดแรกหรือบรรทัดที่สองในไฟล์เช่น:

      # coding=<encoding name>

หรือ (ใช้รูปแบบที่รู้จักโดยบรรณาธิการยอดนิยม)

      #!/usr/bin/python
      # -*- coding: <encoding name> -*-

หรือ

      #!/usr/bin/python
      # vim: set fileencoding=<encoding name> :

...