Apa format header umum file Python?

Saya menemukan format header berikut untuk file sumber Python dalam dokumen tentang pedoman pengkodean Python:

#!/usr/bin/env python

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

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

Apakah ini format standar header di dunia Python? Apa bidang / informasi lain yang bisa saya taruh di header? Guru python membagikan panduan Anda untuk tajuk sumber Python yang bagus :-)

Semua metadata untuk Foobarmodul.

Yang pertama adalah docstringmodul, yang sudah dijelaskan dalam jawaban Peter .

Bagaimana cara mengatur modul saya (file sumber)? (Arsip)

Baris pertama dari setiap file harus #!/usr/bin/env python. Ini memungkinkan untuk menjalankan file sebagai skrip yang memanggil penerjemah secara implisit, misalnya dalam konteks CGI.

Selanjutnya harus menjadi docstring dengan deskripsi. Jika uraiannya panjang, baris pertama harus berupa ringkasan pendek yang masuk akal sendiri, dipisahkan dari yang lainnya oleh baris baru.

Semua kode, termasuk pernyataan impor, harus mengikuti docstring. Jika tidak, dokumen tidak akan dikenali oleh penerjemah, dan Anda tidak akan memiliki akses ke sana dalam sesi interaktif (yaitu melalui obj.__doc__) atau ketika membuat dokumentasi dengan alat otomatis.

Impor modul bawaan terlebih dahulu, diikuti oleh modul pihak ketiga, diikuti oleh perubahan pada jalur dan modul Anda sendiri. Terutama, penambahan jalur dan nama modul Anda cenderung berubah dengan cepat: menyimpannya di satu tempat membuatnya lebih mudah ditemukan.

Berikutnya adalah informasi kepengarangan. Informasi ini harus mengikuti format ini:

__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__ = "[email protected]"
__status__ = "Production"

Status biasanya harus salah satu dari "Prototipe", "Pengembangan", atau "Produksi". __maintainer__harus menjadi orang yang akan memperbaiki bug dan melakukan perbaikan jika diimpor. __credits__berbeda dari __author__yang __credits__mencakup orang yang melaporkan perbaikan bug, membuat saran, dll. tetapi tidak benar-benar menulis kode.

Di sini Anda memiliki informasi lebih lanjut, daftar __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__dan __version__metadata yang diakui.

Saya sangat menyukai header file minimal, yang saya maksud hanya:

• Hashbang ( #!baris) jika ini adalah skrip yang dapat dieksekusi
• Modul modul
• Impor, dikelompokkan dengan cara standar, misalnya:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

yaitu. tiga kelompok impor, dengan satu baris kosong di antara mereka. Dalam setiap grup, impor diurutkan. Kelompok terakhir, impor dari sumber lokal, dapat berupa impor absolut seperti yang ditunjukkan, atau impor relatif eksplisit.

Yang lainnya adalah buang-buang waktu, ruang visual, dan secara aktif menyesatkan.

Jika Anda memiliki penafian hukum atau info lisensi, itu masuk ke file terpisah. Tidak perlu menginfeksi setiap file kode sumber. Hak cipta Anda harus menjadi bagian dari ini. Orang-orang seharusnya dapat menemukannya di LICENSEfile Anda , bukan kode sumber acak.

Metadata seperti kepengarangan dan tanggal sudah dikelola oleh kontrol sumber Anda. Tidak perlu menambahkan versi yang kurang detail, salah, dan ketinggalan zaman dari informasi yang sama dalam file itu sendiri.

Saya tidak percaya ada data lain yang semua orang perlu masukkan ke semua file sumber mereka. Anda mungkin memiliki beberapa persyaratan khusus untuk melakukannya, tetapi hal-hal seperti itu, menurut definisi, hanya berlaku untuk Anda. Mereka tidak memiliki tempat di "header umum yang direkomendasikan untuk semua orang".

Jawaban di atas benar-benar lengkap, tetapi jika Anda ingin tajuk yang cepat dan kotor untuk disalin, gunakan ini:

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

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

Mengapa ini bagus?

• Baris pertama adalah untuk pengguna * nix. Ini akan memilih juru bahasa Python di jalur pengguna, jadi akan secara otomatis memilih juru bahasa yang disukai pengguna.
• Yang kedua adalah pengkodean file. Saat ini setiap file harus memiliki encoding yang terkait. UTF-8 akan bekerja di mana saja. Hanya proyek lawas yang akan menggunakan pengodean lainnya.
• Dan dokumentasi yang sangat sederhana. Itu dapat mengisi beberapa baris.

Lihat juga: https://www.python.org/dev/peps/pep-0263/

Jika Anda hanya menulis kelas di setiap file, Anda bahkan tidak memerlukan dokumentasi (itu akan masuk ke dalam dokumen kelas).

Juga lihat PEP 263 jika Anda menggunakan karakter non-ascii

Abstrak

PEP ini mengusulkan untuk memperkenalkan sintaksis untuk mendeklarasikan penyandian file sumber Python. Informasi pengkodean kemudian digunakan oleh pengurai Python untuk menginterpretasikan file menggunakan pengkodean yang diberikan. Terutama ini meningkatkan interpretasi Unicode literal dalam kode sumber dan memungkinkan untuk menulis literal Unicode menggunakan misalnya UTF-8 langsung di editor sadar Unicode.

Masalah

Dalam Python 2.1, Unicode literal hanya dapat ditulis menggunakan pengkodean berbasis Latin-1 "unicode-escape". Ini membuat lingkungan pemrograman agak tidak bersahabat bagi pengguna Python yang tinggal dan bekerja di lokal non-Latin-1 seperti banyak negara Asia. Pemrogram dapat menulis string 8-bit mereka menggunakan pengkodean favorit, tetapi terikat pada pengkodean "unicode-escape" untuk literal Unicode.

Solusi yang Diusulkan

Saya mengusulkan untuk membuat pengkodean kode sumber Python terlihat dan dapat diubah berdasarkan file per-sumber dengan menggunakan komentar khusus di bagian atas file untuk mendeklarasikan pengkodean.

Untuk membuat Python sadar akan deklarasi enkode ini, sejumlah perubahan konsep diperlukan sehubungan dengan penanganan data kode sumber Python.

Mendefinisikan Pengkodean

Python akan default ke ASCII sebagai pengkodean standar jika tidak ada petunjuk pengkodean lain yang diberikan.

Untuk menentukan pengkodean kode sumber, komentar ajaib harus ditempatkan ke file sumber baik sebagai baris pertama atau kedua dalam file, seperti:

      # coding=<encoding name>

atau (menggunakan format yang dikenali oleh editor populer)

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

atau

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

...