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

    '''
8, nhưng sử dụng dấu ngoặc kép cho các chuỗi có khả năng chứa ký tự dấu nháy đơn như một phần của chính chuỗi đó (chẳng hạn như thông báo lỗi hoặc bất kỳ chuỗi nào chứa ngôn ngữ tự nhiên), 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

    '''
9

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

    '''
2. Loại định dạng chuỗi này không hữu ích cho việc quốc tế hóa và sẽ biến mất trong Python 3

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

    '''
2

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

    '''
20,
@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

    '''
21 hoặc
@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

    '''
22 không được bắt đầu bằng chữ in hoa hoặc kết thúc bằng dấu chấm. Đây phải là những cụm từ ngắn và không phải là câu đầy đủ. Nếu cần thêm chi tiết, hãy đặt nó trong phần mô tả chức năng

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

    '''
23 trong ngoặc. Trường hợp có liên quan cũng chỉ ra giá trị mặc đị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

    '''
24

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

    '''
25 hoặc
@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

    '''
26

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

    '''
27 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

    '''
28), nhưng các chuỗi tài liệu phải ghi lại các khóa mà các hàm đọc từ
@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

    '''
28 chứ không phải bản thâ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

    '''
27 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

    '''
28, vì đây là những gì người dùng phải POST trong JSON

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

    '''
52. Khi ghi lại các chức năng như thế này, hãy ghi tập dữ liệu không phải gói, nhưng lần đầu tiên bạn thực hiện việc này, hãy đặt gói sau nó trong ngoặc để tránh nhầm lẫn, 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

    '''
5

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

    '''
7

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

Có hai cách để biểu diễn chuỗi trong python. Chuỗi được đặt trong dấu nháy đơn hoặc nháy kép . Cả hai cách (dấu nháy đơn hoặc kép) đều đúng tùy theo yêu cầu.

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

Chuỗi trích dẫn đơn. Đây là cách dễ nhất để xác định một chuỗi. Bạn có thể sử dụng nó khi bạn muốn chuỗi chính xác như được viết . Tất cả các chuỗi thoát như \r hoặc \n, sẽ được xuất ra theo chỉ định thay vì có bất kỳ ý nghĩa đặc biệt nào. Trích dẫn đơn thường nhanh hơn trong một số trường hợp.

đang độc thân

Trong Python, dãy ký tự như vậy được bao gồm trong dấu ngoặc đơn hoặc dấu ngoặc kép. Về cú pháp ngôn ngữ, không có sự khác biệt trong chuỗi trích dẫn đơn hoặc kép . Cả hai đại diện có thể được sử dụng thay thế cho nhau.