Python dosyalarının genel başlık formatı nedir?

Python kodlama yönergeleri hakkında bir belgede Python kaynak dosyaları için aşağıdaki başlık formatına rastladım:

#!/usr/bin/env python

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

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

Bu Python dünyasındaki standart başlık formatı mıdır? Başlığa başka hangi alanları / bilgileri koyabilirim? Python gurus iyi Python kaynak üstbilgileri için yönergelerinizi paylaşın :-)

FoobarModül için tüm meta verileri .

Birincisi docstring, Peter'ın cevabında açıklanmış olan modülün .

Modüllerimi (kaynak dosyalar) nasıl düzenlerim? (Arşiv)

Her dosyanın ilk satırı olmalıdır #!/usr/bin/env python. Bu, dosyayı, örneğin bir CGI bağlamında, yorumlayıcıyı dolaylı olarak çağıran bir komut dosyası olarak çalıştırmayı mümkün kılar.

Sonra bir açıklama ile doktora olmalıdır. Açıklama uzunsa, ilk satır, diğerlerinden bir satırsonu çizgisiyle ayrılmış, kendi başına anlamlı olan kısa bir özet olmalıdır.

İçe aktarma ifadeleri de dahil olmak üzere tüm kodlar öğretiyi izlemelidir. Aksi takdirde, doktora yorumlayıcı tarafından tanınmayacak ve interaktif oturumlarda (yani aracılığıyla obj.__doc__) veya otomatik araçlarla dokümantasyon oluştururken buna erişemeyeceksiniz .

Önce yerleşik modülleri, ardından üçüncü taraf modülleri, ardından yoldaki değişiklikleri ve kendi modüllerinizi içe aktarın. Özellikle, modüllerinizin yoluna ve adlarına eklemeler hızlı bir şekilde değişecektir: bunları tek bir yerde tutmak onları bulmayı kolaylaştırır.

Sonra yazarlık bilgisi olmalıdır. Bu bilgi şu biçimde olmalıdır:

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

Durum genellikle "Prototip", "Geliştirme" veya "Üretim" den biri olmalıdır. __maintainer__içe aktarılırsa hataları düzeltecek ve iyileştirmeler yapacak kişi olmalıdır. __credits__dan farklıdır __author__ki __credits__vb hata düzeltmeleri, yapılan önerileri rapor ama aslında kod yazmadım insanları kapsamaktadır.

İşte size, listeleme daha fazla bilgiye sahip __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__ve __version__olarak kabul meta.

Ben çok az dosya başlıkları, sadece demek istediğim:

• #!Yürütülebilir bir komut dosyasıysa hashbang ( satır)
• Modül öğretimi
• Standart şekilde gruplandırılmış ithalatlar, örneğin:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

yani. aralarında tek bir boş satır bulunan üç ithalat grubu. Her grupta ithalatlar sıralanır. Nihai grup, yerel kaynaktan ithalat, gösterildiği gibi mutlak ithalat veya açık göreli ithalat olabilir.

Diğer her şey zaman kaybı, görsel alan ve aktif olarak yanıltıcıdır.

Yasal feragatnameleriniz veya lisans bilgileriniz varsa, bunlar ayrı bir dosyaya gider. Her kaynak kodu dosyasına bulaşmasına gerek yoktur. Telif hakkınız bunun bir parçası olmalıdır. İnsanlar LICENSErasgele kaynak kodunu değil , dosyanızda bulabilmelidir .

Yazarlık ve tarih gibi meta veriler kaynak denetiminiz tarafından zaten korunur. Dosyanın kendisine aynı bilgilerin daha az ayrıntılı, hatalı ve güncel olmayan bir sürümünü eklemenize gerek yoktur.

Herkesin tüm kaynak dosyalarına koyması gereken başka bir veri olduğuna inanmıyorum. Bunu yapmak için belirli bir gereksiniminiz olabilir, ancak bu tür şeyler tanım gereği sadece sizin için geçerlidir. “Herkes için önerilen genel başlıklar” da yeri yoktur.

Yukarıdaki cevaplar gerçekten eksiksiz, ancak kopyala yapıştırmak için hızlı ve kirli bir başlık istiyorsanız, bunu kullanın:

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

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

Bu neden iyi?

• İlk satır * nix kullanıcıları içindir. Kullanıcı yolunda Python yorumlayıcısını seçecektir, böylece otomatik olarak kullanıcının tercih ettiği yorumlayıcıyı seçecektir.
• İkincisi dosya kodlamasıdır. Günümüzde her dosyanın ilişkili bir kodlaması olmalıdır. UTF-8 her yerde çalışacaktır. Sadece eski projeler diğer kodlamaları kullanırdı.
• Ve çok basit bir dokümantasyon. Birden fazla satırı doldurabilir.

Ayrıca bakınız: https://www.python.org/dev/peps/pep-0263/

Her dosyaya sadece bir sınıf yazarsanız, belgelere bile ihtiyacınız yoktur (sınıf belgesinin içine girer).

Ayrıca ascii olmayan bir karakter seti kullanıyorsanız PEP 263'e bakın

Öz

Bu PEP, bir Python kaynak dosyasının kodlamasını bildirmek için bir sözdizimi sunmayı önerir. Kodlama bilgisi daha sonra Python ayrıştırıcısı tarafından verilen kodlamayı kullanarak dosyayı yorumlamak için kullanılır. En önemlisi, bu, Unicode değişmezlerinin kaynak kodundaki yorumunu geliştirir ve örneğin Unicode değişmez değerlerini doğrudan Unicode farkında bir editörde örneğin UTF-8 kullanarak yazmayı mümkün kılar.

Sorun

Python 2.1'de, Unicode değişmez değerleri yalnızca Latin-1 tabanlı "unicode-escape" kodlaması kullanılarak yazılabilir. Bu, programlama ortamını birçok Asya ülkesi gibi Latin-1 dışındaki bölgelerde yaşayan ve çalışan Python kullanıcıları için oldukça düşmanca hale getirir. Programcılar 8 bit dizelerini favori kodlamayı kullanarak yazabilir, ancak Unicode değişmez değerleri için "unicode-escape" kodlamasına bağlıdır.

Önerilen çözüm

Kodlama bildirmek için dosyanın üst kısmında özel bir yorum kullanarak Python kaynak kodunu kaynak başına dosya bazında görünür ve değiştirilebilir yapmayı öneriyorum.

Python'un bu kodlama bildiriminden haberdar olması için Python kaynak kodu verilerinin işlenmesiyle ilgili olarak bir dizi kavram değişikliği gereklidir.

Kodlamayı Tanımlama

Başka kodlama ipuçları verilmezse Python varsayılan olarak standart kodlama olarak ASCII'yi kullanır.

Bir kaynak kodu kodlaması tanımlamak için, kaynak dosyalara dosyadaki birinci veya ikinci satır olarak sihirli bir yorum yerleştirilmelidir, örneğin:

      # coding=<encoding name>

veya (popüler editörler tarafından tanınan formatları kullanarak)

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

veya

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

...