Trích dẫn đơn Python trong chuỗi

Dọn dẹp các vấn đề về định dạng và PEP 8 trên master, không phải trên nhánh tính năng. Tất nhiên trừ khi bạn đang thay đổi đoạn mã đó. Điều này sẽ giúp tránh xung đột hợp nhất giả và hỗ trợ đọc các yêu cầu kéo

Sử dụng dấu nháy đơn

Sử dụng dấu nháy đơn cho chuỗi ký tự, e. g.

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Dấu nháy đơn dễ đọc và dễ nhập hơn, nhưng nếu một chuỗi chứa các ký tự nháy đơn thì dấu nháy kép sẽ tốt hơn là thoát các ký tự nháy đơn hoặc gói chuỗi trong dấu nháy đơn kép

Chúng tôi cũng sử dụng ba dấu ngoặc đơn cho chuỗi tài liệu, xem Tài liệu

nhập khẩu

• Không sử dụng

  _(' .. {foo} .. {bar} ...').format(foo='foo-value', bar='bar-value')
  

  0 hoặc

  _(' .. {foo} .. {bar} ...').format(foo='foo-value', bar='bar-value')
  

  1. Thay vào đó, chỉ cần

  _(' .. {foo} .. {bar} ...').format(foo='foo-value', bar='bar-value')
  

  2 và sau đó truy cập tên bằng

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  0. Xem Thành ngữ và Chống thành ngữ trong Python

  Bạn có thể đặt tên mô-đun dài ngắn gọn hơn bằng cách đặt bí danh cho chúng

  và sau đó truy cập nó bằng

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  1 trong mã của bạn

• Thực hiện tất cả các lần nhập ở đầu tệp, sau chuỗi tài liệu mô-đun. Nhập khẩu nên được nhóm lại theo thứ tự sau

  1. Nhập thư viện tiêu chuẩn
  2. Nhập khẩu của bên thứ ba
  3. hàng nhập khẩu CKAN

ghi nhật ký

• Giữ thông điệp tường trình ngắn
• Không bao gồm các biểu diễn đối tượng trong thông điệp tường trình. Sẽ rất hữu ích khi bao gồm một mã định danh mô hình miền khi thích hợp
• Chọn một cấp độ nhật ký thích hợp (DEBUG, INFO, ERROR, WARNING hoặc CRITICAL, xem phần HOWTO ghi nhật ký của Python)

Định dạng chuỗi

Không sử dụng định dạng chuỗi kiểu %s cũ, e. g.

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Sử dụng cái mới. format() và đặt tên có ý nghĩa cho từng trường thay thế, chẳng hạn

_(' .. {foo} .. {bar} ...').format(foo='foo-value', bar='bar-value')

tài liệu

Chúng tôi muốn các tài liệu của CKAN rõ ràng và dễ đọc đối với các lập trình viên thông minh và có năng lực nhưng có thể không biết nhiều thuật ngữ kỹ thuật của CKAN và ngôn ngữ đầu tiên của họ có thể không phải là tiếng Anh. Chúng tôi cũng muốn dễ dàng duy trì các chuỗi tài liệu và luôn cập nhật chúng với hành vi thực tế của mã khi nó thay đổi theo thời gian. Cho nên

• Tất cả các mô-đun và tất cả các hàm, lớp và phương thức công khai được xuất bởi một mô-đun thường phải có các chuỗi tài liệu (xem PEP 257)
• Giữ các chuỗi tài liệu ngắn gọn, chỉ mô tả những gì cần thiết và không hơn thế nữa,
• Giữ docstrings đơn giản. sử dụng tiếng Anh đơn giản, ngắn gọn
• Cố gắng tránh lặp lại

PEP 257 (Quy ước về chuỗi tài liệu)

Nói chung, hãy làm theo PEP 257 để biết các tài liệu. Chúng tôi sẽ chỉ mô tả những cách mà CKAN khác hoặc mở rộng PEP 257 bên dưới

Các tài liệu CKAN lệch khỏi PEP 257 theo một số cách

• Chúng tôi sử dụng

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  3 xung quanh chuỗi tài liệu, không phải

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  4 (đặt ba dấu nháy đơn xung quanh chuỗi tài liệu một dòng cũng như chuỗi tài liệu nhiều dòng, điều này giúp chúng dễ dàng mở rộng hơn sau này)
• Chúng tôi sử dụng chỉ thị Sphinx để ghi lại các tham số, ngoại lệ và giá trị trả về (xem bên dưới)

Danh sách trường nhân sư

Sử dụng danh sách trường Sphinx để ghi lại các tham số, ngoại lệ và trả về của hàm

• Sử dụng

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  5 và

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  6 để mô tả từng thông số
• Sử dụng

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  7 và

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  8 để mô tả mỗi lợi nhuận
• Sử dụng

  @property
  def packages(self):
      '''Return a list of all packages that have this tag, sorted by name.
  
      :rtype: list of ckan.model.package.Package objects
  
      '''
  

  9 để mô tả từng ngoại lệ được đưa ra

Ví dụ về một chuỗi tài liệu ngắn

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Ví dụ về chuỗi tài liệu dài hơn

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Các cụm từ theo sau

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Cho biết các đối số tùy chọn bằng cách kết thúc mô tả của chúng bằng

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Bạn cũng có thể sử dụng một đánh dấu reStructuredText nội tuyến nhỏ trong tài liệu, e. g.

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Tài liệu API hành động

Các tài liệu từ API hành động của CKAN được xử lý bằng autodoc và được đưa vào chương API của tài liệu của CKAN. Đối tượng dự định của các chuỗi tài liệu này là người dùng API CKAN chứ không phải (chỉ) các nhà phát triển cốt lõi của CKAN

Trong nguồn Python, mỗi hàm API có hai đối số giống nhau (

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Trong trường hợp thực tế, sẽ rất hữu ích khi đưa ra các ví dụ về giá trị tham số và giá trị trả về trong tài liệu API

Bộ dữ liệu CKAN từng được gọi là gói và tên cũ vẫn xuất hiện trong nguồn, e. g. trong các tên hàm như

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Ví dụ về ckan. Hợp lý. chuỗi tài liệu API hành động

@property
def packages(self):
    '''Return a list of all packages that have this tag, sorted by name.

    :rtype: list of ckan.model.package.Package objects

    '''

Một số công cụ hữu ích cho chất lượng mã Python

Có nhiều công cụ khác nhau có thể giúp bạn kiểm tra mã Python của mình để biết sự tuân thủ PEP8 và chất lượng mã chung. Chúng tôi khuyên bạn nên sử dụng chúng

chúng ta có thể sử dụng đơn

Bạn có thể sử dụng dấu ngoặc đơn cho chuỗi không?

đang độc thân