Định dạng tiêu đề phổ biến của các tệp Python là gì?

Tôi đã xem qua định dạng tiêu đề sau cho các tệp nguồn Python trong một tài liệu về hướng dẫn mã hóa Python:

#!/usr/bin/env python

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

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

Đây có phải là định dạng chuẩn của các tiêu đề trong thế giới Python không? Những lĩnh vực / thông tin nào khác tôi có thể đặt trong tiêu đề? Các chuyên gia về Python chia sẻ các nguyên tắc của bạn cho các tiêu đề nguồn Python tốt :-)

Tất cả siêu dữ liệu của nó cho các Foobarmô-đun.

Cái đầu tiên là docstringmô-đun, đã được giải thích trong câu trả lời của Peter .

Làm cách nào để tổ chức các mô-đun của tôi (tệp nguồn)? (Lưu trữ)

Dòng đầu tiên của mỗi tập tin shoud được #!/usr/bin/env python. Điều này làm cho nó có thể chạy tệp dưới dạng một tập lệnh gọi trình thông dịch ngầm, ví dụ như trong ngữ cảnh CGI.

Tiếp theo nên là chuỗi doc với một mô tả. Nếu mô tả dài, dòng đầu tiên phải là một bản tóm tắt ngắn có ý nghĩa riêng, tách biệt với phần còn lại bằng một dòng mới.

Tất cả các mã, bao gồm các câu lệnh nhập, phải tuân theo chuỗi doc. Mặt khác, chuỗi doc sẽ không được trình thông dịch nhận ra và bạn sẽ không có quyền truy cập vào nó trong các phiên tương tác (tức là thông qua obj.__doc__) hoặc khi tạo tài liệu bằng các công cụ tự động.

Trước tiên, nhập các mô-đun tích hợp, tiếp theo là các mô-đun của bên thứ ba, theo sau là bất kỳ thay đổi nào đối với đường dẫn và các mô-đun của riêng bạn. Đặc biệt, các bổ sung cho đường dẫn và tên của các mô-đun của bạn có thể sẽ thay đổi nhanh chóng: giữ chúng ở một nơi giúp chúng dễ dàng tìm thấy hơn.

Tiếp theo nên là thông tin về quyền tác giả. Thông tin này phải theo định dạng này:

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

Trạng thái thường là một trong "Nguyên mẫu", "Phát triển" hoặc "Sản xuất". __maintainer__nên là người sẽ sửa lỗi và cải thiện nếu được nhập. __credits__khác với __author__trong đó __credits__bao gồm những người báo cáo sửa lỗi, đưa ra đề xuất, v.v. nhưng không thực sự viết mã.

Ở đây bạn có thêm thông tin, niêm yết __author__, __authors__, __contact__, __copyright__, __license__, __deprecated__, __date__và __version__siêu dữ liệu như được công nhận.

Tôi đặc biệt ủng hộ các tiêu đề tệp tối thiểu, ý tôi là:

• Hashbang ( #!dòng) nếu đây là tập lệnh thực thi
• Mô-đun mô-đun
• Nhập khẩu, được nhóm theo cách tiêu chuẩn, ví dụ:

  import os    # standard library
  import sys

  import requests  # 3rd party packages

  import mypackage.mymodule  # local source
  import mypackage.myothermodule  

I E. ba nhóm nhập khẩu, với một dòng trống duy nhất giữa chúng. Trong mỗi nhóm, nhập khẩu được sắp xếp. Nhóm cuối cùng, nhập khẩu từ nguồn địa phương, có thể là nhập tuyệt đối như được hiển thị hoặc nhập khẩu tương đối rõ ràng.

Mọi thứ khác là một sự lãng phí thời gian, không gian trực quan và chủ động gây hiểu lầm.

Nếu bạn có từ chối trách nhiệm pháp lý hoặc thông tin cấp phép, nó sẽ đi vào một tệp riêng. Nó không cần phải lây nhiễm mọi tập tin mã nguồn. Bản quyền của bạn nên là một phần của điều này. Mọi người sẽ có thể tìm thấy nó trong LICENSEtệp của bạn , không phải mã nguồn ngẫu nhiên.

Siêu dữ liệu như quyền tác giả và ngày tháng đã được duy trì bởi kiểm soát nguồn của bạn. Không cần phải thêm một phiên bản ít chi tiết, sai sót và lỗi thời của cùng một thông tin trong chính tệp.

Tôi không tin có bất kỳ dữ liệu nào khác mà mọi người cần phải đưa vào tất cả các tệp nguồn của họ. Bạn có thể có một số yêu cầu cụ thể để làm như vậy, nhưng những điều như vậy chỉ áp dụng cho bạn. Họ không có chỗ trong các tiêu đề chung được đề xuất cho mọi người.

Các câu trả lời ở trên thực sự đầy đủ, nhưng nếu bạn muốn một tiêu đề nhanh và bẩn để sao chép, hãy sử dụng:

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

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

Tại sao đây là một trong những tốt:

• Dòng đầu tiên dành cho người dùng * nix. Nó sẽ chọn trình thông dịch Python trong đường dẫn người dùng, do đó sẽ tự động chọn trình thông dịch ưa thích của người dùng.
• Cái thứ hai là mã hóa tập tin. Ngày nay mỗi tập tin phải có một mã hóa liên quan. UTF-8 sẽ hoạt động ở mọi nơi. Chỉ cần các dự án cũ sẽ sử dụng mã hóa khác.
• Và một tài liệu rất đơn giản. Nó có thể điền vào nhiều dòng.

Xem thêm: https://www.python.org/dev/peps/pep-0263/

Nếu bạn chỉ viết một lớp trong mỗi tệp, bạn thậm chí không cần tài liệu (nó sẽ đi vào bên trong tài liệu lớp).

Đồng thời xem PEP 263 nếu bạn đang sử dụng bộ ký tự không phải mã ascii

trừu tượng

PEP này đề xuất giới thiệu một cú pháp để khai báo mã hóa của tệp nguồn Python. Thông tin mã hóa sau đó được trình phân tích cú pháp Python sử dụng để diễn giải tệp bằng cách sử dụng mã hóa đã cho. Đáng chú ý nhất là điều này giúp tăng cường việc giải thích các chữ Unicode trong mã nguồn và cho phép viết các chữ Unicode bằng cách sử dụng trực tiếp UTF-8 trong trình soạn thảo nhận thức Unicode.

Vấn đề

Trong Python 2.1, các chữ Unicode chỉ có thể được viết bằng cách sử dụng mã hóa "unicode-esc" dựa trên Latin-1. Điều này làm cho môi trường lập trình khá không thân thiện với người dùng Python sống và làm việc ở các địa phương không phải là người Latin-1 như nhiều quốc gia châu Á. Các lập trình viên có thể viết các chuỗi 8 bit của họ bằng cách sử dụng mã hóa yêu thích, nhưng bị ràng buộc với mã hóa "unicode-esc" cho các chữ Unicode.

Giải pháp đề xuất

Tôi đề xuất làm cho mã hóa mã nguồn Python có thể nhìn thấy và thay đổi được trên cơ sở tệp trên mỗi nguồn bằng cách sử dụng một nhận xét đặc biệt ở đầu tệp để khai báo mã hóa.

Để làm cho Python biết về khai báo mã hóa này, một số thay đổi khái niệm là cần thiết đối với việc xử lý dữ liệu mã nguồn Python.

Xác định mã hóa

Python sẽ mặc định ASCII là mã hóa tiêu chuẩn nếu không có gợi ý mã hóa nào khác được đưa ra.

Để xác định mã hóa mã nguồn, một chú thích ma thuật phải được đặt vào các tệp nguồn là dòng đầu tiên hoặc thứ hai trong tệp, chẳng hạn như:

      # coding=<encoding name>

hoặc (sử dụng các định dạng được công nhận bởi các biên tập viên phổ biến)

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

hoặc là

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

...