Apa format header umum file Python?


508

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 :-)


Inilah tempat yang bagus untuk memulai: PEP 257 , yang berbicara tentang Docstrings, dan tautan ke beberapa dokumen terkait lainnya.
Peter

41
Mungkin panduan yang bermanfaat bagi mereka yang membaca jawaban berbeda untuk pertanyaan ini adalah untuk mempertimbangkan tujuan apa yang mereka harapkan dari header file ini untuk digunakan. Jika Anda memiliki kasus penggunaan yang konkret (misalnya pengacara saya mengatakan kasus pengadilan hilang karena pengembang gagal memasukkan informasi hak cipta di setiap file tunggal). Kemudian tambahkan dan simpan informasi yang Anda butuhkan untuk kasus penggunaan tersebut. Jika tidak, Anda hanya memanjakan jimat OCD Anda.
Jonathan Hartley

haha bagus @JonathanHartley! Untuk proyek saya sendiri, seperti yang Anda katakan, "Saya menikmati jimat OCD saya." hahaaha stackoverflow.com/a/51914806/1896134
JayRizzo

Jawaban:


577

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__ = "rob@spot.colorado.edu"
__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.


7
Bisakah pembuatan info tajuk entah bagaimana otomatis untuk file baru?
Hauke

184
Saya pikir semua metadata ini setelah impor adalah ide yang buruk. Bagian-bagian dari metadata ini yang berlaku untuk satu file (misalnya penulis, tanggal) sudah dilacak oleh kontrol sumber. Menempatkan salinan yang salah & kedaluwarsa dari informasi yang sama dalam file itu sendiri tampaknya salah bagi saya. Bagian-bagian yang berlaku untuk seluruh proyek (misalnya lisensi, versi) tampak lebih baik terletak di tingkat proyek, dalam file mereka sendiri, daripada di setiap file kode sumber.
Jonathan Hartley

28
Setuju sepenuhnya dengan Jonathan Hartley. Orang berikutnya yang mewarisi kode memiliki tiga pilihan: 1) perbarui semuanya setiap kali dia mengedit kode 2) biarkan sendiri, dalam hal ini akan menjadi tidak akurat 3) hapus semuanya. Opsi 1 adalah buang-buang waktu mereka, terutama karena mereka benar-benar tidak percaya bahwa metadata sudah mutakhir ketika mereka menerimanya. Opsi 2 dan 3 berarti bahwa waktu Anda untuk meletakkannya di tempat pertama adalah sia-sia. Solusi: hemat waktu semua orang dan jangan letakkan di sana.
spookylukey

77
Tidak ada alasan bagi kebanyakan file Python untuk memiliki garis shebang.
Mike Graham

15
Per PEP 8, __version__harus langsung mengikuti dokumen utama, dengan baris kosong sebelum dan sesudah. Juga, ini adalah praktik terbaik untuk mendefinisikan rangkaian karakter Anda segera di bawah shebang -# -*- coding: utf-8 -*-
Dave Lasley

179

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".


23
Tidak dapat menyetujui lebih - itu adalah dosa untuk mereplikasi kode di banyak tempat jadi mengapa melakukan hal yang sama untuk informasi header. Letakkan di satu tempat (proyek root) dan hindari kerumitan menjaga informasi tersebut di banyak, banyak file.
Graeme

13
Sementara saya setuju bahwa kontrol sumber cenderung memberikan informasi kepengarangan yang lebih valid, kadang-kadang penulis hanya mendistribusikan sumber tanpa memberikan akses ke repositori, atau mungkin hanya cara distribusi bekerja, misalnya: instalasi terpusat dari pypi. Dengan demikian, menanamkan informasi kepengarangan sebagai header modul masih bermanfaat.
kereta bayi

6
Hai Pram. Saya mengalami kesulitan membayangkan use case yang sebenarnya berguna. Saya bisa membayangkan seseorang yang ingin mengetahui informasi kepengarangan untuk proyek secara keseluruhan, dan mereka bisa mendapatkan nilai dari daftar kontributor utama di satu tempat pusat, mungkin README atau dokumen proyek. Tetapi siapa yang (a) ingin mengetahui kepengarangan dari file individual , dan (b) tidak akan memiliki akses ke repo sumber, dan (c) tidak akan peduli bahwa tidak pernah ada cara untuk mengetahui apakah informasi itu salah atau kadaluarsa?
Jonathan Hartley

12
Banyak lisensi mengharuskan Anda untuk memasukkan boilerplate lisensi di setiap file untuk alasan yang sangat baik. Jika seseorang mengambil satu atau dua file dan mendistribusikannya kembali tanpa lisensi, orang-orang yang menerimanya tidak tahu lisensi apa yang ada di bawahnya, dan harus melacaknya (dengan asumsi mereka dengan itikad baik, yaitu).
nyuszika7h

3
Banyak modul (scipy, numpy, matplotlib) memiliki __version__metadata, dan saya pikir itu bagus untuk dimiliki, karena itu harus dapat diakses oleh program dan untuk memeriksa dengan cepat di interpreter interaktif. Kepengarangan dan informasi hukum termasuk dalam file yang berbeda. Kecuali Anda memiliki use case untukif 'Rob' in __author__:
endolith

34

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).


5
> "Saat ini setiap file harus memiliki penyandian yang terkait." Ini sepertinya menyesatkan. utf8 adalah penyandian default, jadi tidak masalah untuk tidak menentukannya.
Jonathan Hartley

23

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> :

...


15
Perlu dicatat bahwa sejak Python 3, set karakter default adalah UTF-8.
nyuszika7h
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.