programming python

Giải thích chuỗi doc trong Python

Hướng dẫn này giải thích Python Docstring là gì và cách sử dụng nó để ghi lại các hàm Python với các ví dụ

Các hàm rất quan trọng trong Python đến mức Python có hàng chục hàm tích hợp sẵn. Python cũng cho chúng ta khả năng tạo các hàm của riêng mình

Tuy nhiên, các chức năng không chỉ dừng lại ở việc tạo ra chúng, chúng ta phải ghi lại chúng để chúng rõ ràng, dễ đọc và dễ bảo trì. Ngoài ra, các chức năng có các thuộc tính có thể được sử dụng để xem xét nội tâm và điều này cho phép chúng tôi xử lý các chức năng theo nhiều cách khác nhau

=> Đọc qua loạt bài đào tạo Python dễ dàng

Bạn sẽ học được gì

Chuỗi tài liệu Python

Trong phần này, chúng ta sẽ xem nhanh hàm là gì và điều này đã được trình bày đầy đủ trong Hàm Python

Các hàm giống như các chương trình nhỏ trong một chương trình và nhóm một loạt các câu lệnh để chúng có thể được sử dụng và tái sử dụng trong các phần khác nhau của chương trình

Các câu lệnh liên quan đến chức năng Python với ví dụ về mã

Câu lệnh Mã mẫu Ví dụdef, tham số, returndef add[a, b=1, *args, **kwargs]. trả về a + b + tổng [args] + tổng [kwargs. values[]]callsadd[3,4,5, 9, c=1, d=8] # Đầu ra. 30

Tài liệu Một chức năng

Hầu hết chúng ta thấy khó ghi lại các chức năng của mình vì nó có thể tốn thời gian và nhàm chán

Tuy nhiên, mặc dù không ghi lại mã của chúng tôi, nhìn chung, có vẻ ổn đối với các chương trình nhỏ, nhưng khi mã trở nên phức tạp và lớn hơn, sẽ khó hiểu và khó bảo trì

Phần này khuyến khích chúng tôi luôn ghi lại các chức năng của mình cho dù chương trình của chúng tôi có vẻ nhỏ đến đâu

Tầm quan trọng của tài liệu chức năng

Có câu nói rằng “Chương trình phải được viết ra để con người đọc, và chỉ tình cờ để máy thực thi”

Chúng tôi không thể nhấn mạnh rằng việc ghi lại các chức năng của chúng tôi sẽ giúp các nhà phát triển khác [bao gồm cả chính chúng tôi] dễ dàng hiểu và đóng góp vào mã của chúng tôi

Tôi cá là chúng ta đã từng bắt gặp một đoạn mã mà chúng ta đã viết cách đây nhiều năm và chúng ta giống như “Tôi đang nghĩ gì vậy. ” Điều này là do không có tài liệu nhắc nhở chúng tôi về những gì mã đã làm và nó đã làm như thế nào

Điều đó đang được nói, nói chung, ghi lại các chức năng hoặc mã của chúng tôi mang lại những lợi ích sau

Thêm nhiều ý nghĩa hơn cho mã của chúng tôi, do đó làm cho nó rõ ràng và dễ hiểu
dễ dàng bảo trì. Với tài liệu phù hợp, chúng tôi có thể quay lại mã của mình nhiều năm sau và vẫn có thể duy trì mã nhanh chóng
Dễ dàng đóng góp. Trong một dự án mã nguồn mở, ví dụ: nhiều nhà phát triển làm việc đồng thời trên cơ sở mã. Tài liệu kém hoặc không có sẽ không khuyến khích các nhà phát triển đóng góp cho các dự án của chúng tôi.
Nó cho phép các công cụ sửa lỗi phổ biến của IDE hỗ trợ chúng tôi một cách hiệu quả trong quá trình phát triển của chúng tôi

Tài liệu chức năng với Python Docstrings

Theo

“Chuỗi tài liệu là một chuỗi ký tự xuất hiện dưới dạng câu lệnh đầu tiên trong định nghĩa mô-đun, hàm, lớp hoặc phương thức. Một chuỗi tài liệu như vậy trở thành thuộc tính đặc biệt __doc__ của đối tượng. ”

Các tài liệu được định nghĩa với định dạng chuỗi triple-double quote[“””]. Ở mức tối thiểu, một chuỗi tài liệu Python sẽ đưa ra một bản tóm tắt nhanh về bất kỳ chức năng nào đang thực hiện

Chuỗi tài liệu của hàm có thể được truy cập theo hai cách. Trực tiếp thông qua thuộc tính đặc biệt __doc__ của hàm hoặc sử dụng hàm tích hợp để truy cập __doc__ đằng sau mui xe

Ví dụ 1. Truy cập chuỗi tài liệu của hàm thông qua thuộc tính đặc biệt __doc__ của hàm.

def add[a, b]:
    """Return the sum of two numbers[a, b]"""
    return a + b

if __name__ == '__main__':
    # print the function's docstring using the object’s special __doc__ attribute
    print[add.__doc__]

đầu ra

NB. Chuỗi tài liệu ở trên đại diện cho chuỗi tài liệu một dòng. Nó xuất hiện trong một dòng và tóm tắt những gì chức năng làm

Ví dụ 2. Truy cập chuỗi tài liệu của hàm bằng cách sử dụng hàm help[] tích hợp.

Chạy lệnh sau từ thiết bị đầu cuối Python Shell

>>> help[sum] # access docstring of sum[]

đầu ra

NB. Nhấn q để thoát khỏi màn hình này

Chuỗi tài liệu Python nhiều dòng kỹ lưỡng hơn và có thể chứa tất cả những điều sau đây

Mục đích của chức năng
Thông tin về lập luận
Thông tin về dữ liệu trả về

Bất kỳ thông tin nào khác có vẻ hữu ích đối với chúng tôi

Ví dụ dưới đây cho thấy một cách toàn diện về tài liệu chức năng của chúng tôi. Nó bắt đầu bằng cách đưa ra một bản tóm tắt ngắn về chức năng của hàm và một dòng trống theo sau là giải thích chi tiết hơn về mục đích của hàm, sau đó một dòng trống khác theo sau là thông tin về đối số, giá trị trả về và bất kỳ ngoại lệ nào nếu có

Chúng tôi cũng nhận thấy một khoảng cách ngắt sau dấu ngoặc kép kèm theo trước phần thân của chức năng của chúng tôi

ví dụ 3

def add_ages[age1, age2=30]:
    """ Return the sum of ages  

    Sum and return the ages of your son and daughter

    Parameters
    ------------
        age1: int
            The age of your son
        age2: int, Optional
            The age of your daughter[default to 30]
    Return
    -----------
        age : int
            The sum of your son and daughter ages. 
    """

    age = age1 + age2
    return age

if __name__ == '__main__':
    # print the function's docstring using the object's special __doc__ attribute
    print[add_ages.__doc__]

đầu ra

NB. Đây không phải là cách duy nhất để ghi tài liệu bằng docstring. Đọc về các định dạng khác quá

Định dạng chuỗi tài liệu Python

Định dạng chuỗi tài liệu được sử dụng ở trên là định dạng kiểu NumPy/SciPy. Các định dạng khác cũng tồn tại, chúng tôi cũng có thể tạo định dạng của mình để công ty của chúng tôi hoặc nguồn mở sử dụng. Tuy nhiên, thật tốt khi sử dụng các định dạng nổi tiếng được tất cả các nhà phát triển công nhận

Một số định dạng nổi tiếng khác là , reStructuredText, Epytext

Ví dụ 4. Bằng cách tham chiếu mã từ ví dụ 3, hãy sử dụng định dạng chuỗi tài liệu Google docstrings, reStructuredText và Epytext để viết lại chuỗi tài liệu.

#1] Tài liệu của Google

"""Return the sum of ages

Sum and return the ages of your son and daughter

Args:
    age1 [int]: The age of your son
    age2 [int]: Optional; The age of your daughter [ default is 30]

Returns:
    age [int]: The sum of your son and daughter ages. 
"""

#2] Tái cấu trúc văn bản

"""Return the sum of ages

Sum and return the ages of your son and daughter

:param age1: The age of your son
:type age1: int
:param age2: Optional; The age of your daughter [ default is 30]
:type age2: int
:returns age: The sum of your son and daughter ages. 
:rtype: int
"""

#3] Văn bản

"""Return the sum of ages

Sum and return the ages of your son and daughter

@type age1: int
@param age1: The age of your son
@type age2: int
@param age2: Optional; The age of your daughter [ default is 30]
@rtype: int
@returns age: The sum of your son and daughter ages. 
"""

Cách các công cụ khác sử dụng DocStrings

Hầu hết các công cụ như trình chỉnh sửa mã, IDE, v.v. đều sử dụng các chuỗi tài liệu để cung cấp cho chúng tôi một số chức năng có thể giúp chúng tôi phát triển, gỡ lỗi và thử nghiệm

Trình chỉnh sửa mã

Các trình chỉnh sửa mã như Visual Studio Code với tiện ích mở rộng Python được cài đặt có thể hỗ trợ chúng tôi hiệu quả và tốt hơn trong quá trình phát triển nếu chúng tôi ghi lại chính xác các chức năng và lớp của mình bằng chuỗi tài liệu

Ví dụ 5

Mở Visual Studio Code đã cài đặt tiện ích mở rộng Python, sau đó lưu mã của ví dụ 2 dưới dạng ex2_dd_ages. py. Trong cùng thư mục, tạo tệp thứ hai có tên ex3_import_ex2. py và dán vào đó mã bên dưới

from ex2_add_ages import add_ages # import 

result = add_ages[4,5] # execute
print[result]

Chúng ta đừng chạy mã này mà hãy di chuột [đặt chuột lên] add_ages trong trình chỉnh sửa của chúng ta

Chúng ta sẽ thấy chuỗi tài liệu của hàm như trong hình bên dưới

Visual Studio Code hiển thị tài liệu của chức năng

Chúng tôi thấy rằng điều này giúp chúng tôi có bản xem trước về những gì hàm làm, những gì nó mong đợi ở dạng đầu vào và cả những gì mong đợi ở dạng giá trị trả về từ hàm mà không cần kiểm tra hàm ở bất kỳ đâu mà nó đã được xác định

Mô-đun thử nghiệm

Python có một mô-đun thử nghiệm gọi là doctest. Nó tìm kiếm các đoạn văn bản chuỗi tài liệu bắt đầu bằng tiền tố >>>[đầu vào từ trình bao Python] và thực thi chúng để xác minh rằng chúng hoạt động và tạo ra kết quả chính xác như mong đợi

Điều này cung cấp một cách nhanh chóng và dễ dàng để viết các bài kiểm tra cho các chức năng của chúng tôi

Ví dụ 6

def add_ages[age1, age2= 30]:
    """ Return the sum of ages  

    Sum and return the ages of your son and daughter

    Test
    -----------
    >>> add_ages[10, 10]
    20
    """

    age = age1 + age2
    return age

if __name__ == '__main__':
    import doctest
    doctest.testmod[] # run test

Trong chuỗi tài liệu ở trên, bài kiểm tra của chúng tôi được đặt trước >>> và bên dưới nó là kết quả mong đợi, trong trường hợp này là 20

Hãy lưu mã ở trên dưới dạng ex4_test. py và chạy nó từ terminal bằng lệnh

________số 8

đầu ra

Chức năng chú thích

Ngoài các chuỗi tài liệu, Python cho phép chúng ta đính kèm siêu dữ liệu vào các tham số và giá trị trả về của hàm, được cho là đóng vai trò quan trọng trong tài liệu hàm và kiểm tra kiểu. Điều này được gọi là Chú thích chức năng được giới thiệu trong PEP 3107

cú pháp

def [: expression, : expression = ]-> expression

Ví dụ, hãy xem xét một hàm làm tròn số float thành số nguyên

Chú thích chức năng

Từ hình trên, các chú thích của chúng tôi ngụ ý rằng loại đối số mong muốn phải nổi và loại trả về mong đợi phải là một số nguyên

Thêm chú thích

Có hai cách để thêm chú thích vào một chức năng. Cách đầu tiên như đã thấy ở trên, nơi các chú thích đối tượng được gắn vào tham số và giá trị trả về

Cách thứ hai là thêm chúng thủ công thông qua thuộc tính __annotations__

Ví dụ 7

>>> help[sum] # access docstring of sum[]

đầu ra

NB. Tra từ điển ta thấy tên tham số được dùng làm khóa cho tham số và chuỗi ‘return’ được dùng làm khóa cho giá trị trả về

Nhớ lại từ cú pháp trên rằng các chú thích có thể là bất kỳ biểu thức hợp lệ nào

Vì vậy, nó có thể là

Một chuỗi mô tả đối số dự kiến hoặc giá trị trả về
Các loại dữ liệu khác như Danh sách, Từ điển, v.v.

Ví dụ 8. Xác định các chú thích khác nhau

>>> help[sum] # access docstring of sum[]

đầu ra

Truy cập chú thích

Trình thông dịch Python tạo một từ điển chú thích của hàm và đưa chúng vào thuộc tính đặc biệt __annotations__ của hàm. Vì vậy, truy cập các chú thích cũng giống như truy cập các mục từ điển

Ví dụ 9. Truy cập chú thích của hàm.

>>> help[sum] # access docstring of sum[]

đầu ra

NB. Nếu một tham số lấy một giá trị mặc định, thì nó phải xuất hiện sau chú thích

Sử dụng chú thích

Bản thân chú thích không làm được gì nhiều. Trình thông dịch Python không sử dụng nó để áp đặt bất kỳ hạn chế nào. Chúng chỉ là một cách khác để ghi lại một chức năng

Ví dụ 10. Truyền đối số thuộc loại khác với chú thích.

>>> help[sum] # access docstring of sum[]

đầu ra

Chúng tôi thấy rằng trình thông dịch Python không đưa ra một ngoại lệ hoặc cảnh báo nào

Mặc dù vậy, các chú thích có thể được sử dụng để hạn chế các đối số kiểu dữ liệu. Nó có thể được thực hiện theo nhiều cách nhưng trong hướng dẫn này, chúng ta sẽ định nghĩa một trình trang trí sử dụng các chú thích để kiểm tra các kiểu dữ liệu đối số

Ví dụ 11. Sử dụng chú thích trong trang trí để kiểm tra kiểu dữ liệu đối số.

Đầu tiên, hãy xác định trang trí của chúng tôi

>>> help[sum] # access docstring of sum[]

NB. Chức năng trên là một trang trí

Cuối cùng, hãy xác định chức năng của chúng tôi và sử dụng trình trang trí để kiểm tra bất kỳ loại dữ liệu đối số nào

>>> help[sum] # access docstring of sum[]

đầu ra

Từ kết quả ở trên, chúng ta thấy rằng lệnh gọi hàm đầu tiên được thực thi thành công, nhưng lệnh gọi hàm thứ hai đưa ra một dấu hiệu cho biết rằng các mục trong đối số thứ ba không tôn trọng kiểu dữ liệu được chú thích. Yêu cầu tất cả các mục trong danh sách đối số thứ ba là kiểu float

Nội quan chức năng

Các đối tượng chức năng có nhiều thuộc tính có thể được sử dụng để xem xét nội quan. Để xem tất cả các thuộc tính này, chúng ta có thể sử dụng hàm dir[] như hình bên dưới

Ví dụ 13. In ra các thuộc tính của hàm.

>>> help[sum] # access docstring of sum[]

đầu ra

NB. Hình trên là các thuộc tính của các hàm do người dùng định nghĩa có thể hơi khác so với các hàm và đối tượng lớp tích hợp

Trong phần này, chúng ta sẽ xem xét một số thuộc tính có thể giúp chúng ta xem xét nội hàm

Các thuộc tính của hàm do người dùng định nghĩa

AttributeDescriptionState__dict__Một từ điển hỗ trợ các thuộc tính chức năng tùy ý. Writable__closure__A Không có hoặc bộ ô chứa các liên kết cho các biến tự do của hàm. Read-Only__code__Bytecode đại diện cho siêu dữ liệu hàm đã biên dịch và thân hàm. Writable__defaults__Một bộ chứa các giá trị mặc định cho các đối số mặc định hoặc Không có nếu không có đối số mặc định. Writable__kwdefaults__Một lệnh chứa các giá trị mặc định cho các tham số chỉ từ khóa. Writable__name__A str là tên hàm. Writable__qualname__A str là tên đủ điều kiện của hàm. Có thể ghi

Chúng tôi không bao gồm __annotations__ trong bảng trên vì chúng tôi đã giải quyết nó trước đó trong hướng dẫn này. Hãy xem kỹ một số thuộc tính được trình bày trong bảng trên

#1] chính tả

Python sử dụng thuộc tính __dict__ của hàm để lưu trữ các thuộc tính tùy ý được gán cho hàm

Nó thường được gọi là một dạng chú thích nguyên thủy. Mặc dù nó không phải là một thông lệ phổ biến, nhưng nó có thể trở nên hữu ích cho tài liệu

Ví dụ 14. Gán thuộc tính tùy ý cho hàm mô tả chức năng của hàm.

>>> help[sum] # access docstring of sum[]

đầu ra

#2] Đóng Python

Việc đóng cho phép một hàm lồng nhau có quyền truy cập vào một biến miễn phí của hàm kèm theo của nó

Nhà bị tịch thu để xảy ra, ba điều kiện cần phải được đáp ứng

Nó phải là một chức năng lồng nhau
Hàm lồng nhau có quyền truy cập vào các biến hàm kèm theo của nó [biến tự do]
Hàm kèm theo trả về hàm lồng nhau

Ví dụ 15. Minh họa việc sử dụng bao đóng trong các hàm lồng nhau.

Hàm kèm theo [divide_by] nhận một ước số và trả về một hàm lồng nhau [cổ tức] nhận cổ tức và chia nó cho ước số

Mở trình chỉnh sửa, dán mã bên dưới và lưu dưới dạng đóng. py

>>> help[sum] # access docstring of sum[]

đầu ra

Vì vậy, việc sử dụng __closure__ là gì. Thuộc tính này trả về một bộ đối tượng ô xác định thuộc tính cell_contents chứa tất cả các biến của hàm kèm theo

Ví dụ 16. Trong thư mục đóng cửa. py đã được lưu, hãy mở terminal và khởi động trình bao Python bằng lệnh python và thực thi mã bên dưới.

>>> help[sum] # access docstring of sum[]

NB. __closure__ trả về Không nếu nó không phải là hàm lồng nhau

#3] mã, mặc định, kwdefault, Tên, tên chất lượng

__name__ trả về tên của hàm và __qualname__ trả về tên đủ điều kiện. Tên đủ điều kiện là tên có dấu chấm mô tả đường dẫn chức năng từ phạm vi toàn cầu của mô-đun của nó. Đối với các chức năng cấp cao nhất, __qualname__ giống như __name__

Ví dụ 17. Trong thư mục đóng cửa. py trong ví dụ 15 đã được lưu, hãy mở terminal và khởi động trình bao Python bằng lệnh python và thực thi mã bên dưới.

def add_ages[age1, age2=30]:
    """ Return the sum of ages  

    Sum and return the ages of your son and daughter

    Parameters
    ------------
        age1: int
            The age of your son
        age2: int, Optional
            The age of your daughter[default to 30]
    Return
    -----------
        age : int
            The sum of your son and daughter ages. 
    """

    age = age1 + age2
    return age

if __name__ == '__main__':
    # print the function's docstring using the object's special __doc__ attribute
    print[add_ages.__doc__]

__defaults__ chứa các giá trị của tham số mặc định của hàm trong khi __kwdefaults__ chứa từ điển các tham số và giá trị chỉ từ khóa của hàm

__code__ xác định các thuộc tính co_varnames chứa tên của tất cả các tham số của hàm và co_argcount chứa số lượng tham số của hàm ngoại trừ các tham số có tiền tố * và **

Ví dụ 18

def add_ages[age1, age2=30]:
    """ Return the sum of ages  

    Sum and return the ages of your son and daughter

    Parameters
    ------------
        age1: int
            The age of your son
        age2: int, Optional
            The age of your daughter[default to 30]
    Return
    -----------
        age : int
            The sum of your son and daughter ages. 
    """

    age = age1 + age2
    return age

if __name__ == '__main__':
    # print the function's docstring using the object's special __doc__ attribute
    print[add_ages.__doc__]

đầu ra

Tất cả các tham số mặc định sau dấu * trống trở thành tham số chỉ từ khóa [mới trong Python 3]
co_argcount đếm 2 vì nó không xem xét bất kỳ biến đối số nào có tiền tố là * hoặc **

Các câu hỏi thường gặp

Q #1] Python có thực thi các gợi ý kiểu không?

Câu trả lời. Trong Python, bản thân các gợi ý gõ không làm được gì nhiều. Chúng chủ yếu được sử dụng để thông báo cho người đọc về loại mã mà một biến được mong đợi. Tin tốt là thông tin của nó có thể được sử dụng để thực hiện kiểm tra kiểu. Điều này thường được thực hiện trong trình trang trí Python

Q #2] Docstring trong Python là gì?

Câu trả lời. Chuỗi tài liệu là chuỗi ký tự đầu tiên được đặt trong dấu ngoặc kép ba lần [“””] và ngay sau định nghĩa của một lớp, mô-đun hoặc hàm. Một chuỗi tài liệu thường mô tả những gì đối tượng đang làm, các tham số và giá trị trả về của nó

Câu hỏi 3] Làm cách nào để bạn có được Chuỗi tài liệu Python?

Câu trả lời. Nói chung, có hai cách để lấy chuỗi tài liệu của đối tượng. Bằng cách sử dụng thuộc tính đặc biệt của đối tượng __doc__ hoặc bằng cách sử dụng hàm help[] tích hợp sẵn

Q #4] Làm thế nào để bạn viết một Docstring tốt?

Câu trả lời. PEP 257 chứa các quy ước Docstring chính thức. Ngoài ra, các định dạng nổi tiếng khác tồn tại như kiểu Numpy/SciPy, Google docstrings, ReStructured Text, Epytext

Phần kết luận

Trong hướng dẫn này, chúng ta đã xem xét tài liệu chức năng nơi chúng ta thấy tầm quan trọng của việc ghi lại các chức năng của mình và cũng học cách chúng ta có thể lập tài liệu bằng docstring

Chúng tôi cũng đã xem xét nội quan chức năng trong đó chúng tôi đã kiểm tra một số thuộc tính chức năng có thể được sử dụng để xem xét nội quan

Ví dụ về chuỗi tài liệu Python là gì?

Chuỗi tài liệu Python hay thường được gọi là chuỗi doc, là một chuỗi ký tự và được sử dụng trong định nghĩa lớp, mô-đun, hàm hoặc phương thức. Docstrings are accessible from the doc attribute [__doc__] for any of the Python objects and also with the built-in help[] function.

Ba loại docstrings là gì?

Các chuỗi tài liệu có thể được chia thành ba loại chính. .

Tài liệu lớp học. Lớp và phương thức lớp

Tài liệu gói và mô-đun. Gói, mô-đun và chức năng

Tài liệu kịch bản. Kịch bản và chức năng

docstring là gì?

Trong lập trình, chuỗi tài liệu là một chuỗi ký tự được chỉ định trong mã nguồn được sử dụng, giống như nhận xét, để ghi lại một đoạn mã cụ thể.

Mục đích của hàm docstring là gì?

Như đã đề cập ở trên, chuỗi tài liệu Python là chuỗi được sử dụng ngay sau định nghĩa của hàm, phương thức, lớp hoặc mô-đun [như trong Ví dụ 1]. Chúng được sử dụng để ghi lại mã của chúng tôi. Chúng ta có thể truy cập các chuỗi tài liệu này bằng thuộc tính __doc__

Chuỗi tài liệu Python

Tài liệu Một chức năng

Tầm quan trọng của tài liệu chức năng

Tài liệu chức năng với Python Docstrings

Định dạng chuỗi tài liệu Python

Cách các công cụ khác sử dụng DocStrings

Chức năng chú thích

Thêm chú thích

Truy cập chú thích

Sử dụng chú thích

Nội quan chức năng

#1] chính tả

#2] Đóng Python

#3] mã, mặc định, kwdefault, Tên, tên chất lượng

Các câu hỏi thường gặp

Phần kết luận

Ví dụ về chuỗi tài liệu Python là gì?

Ba loại docstrings là gì?

docstring là gì?

Mục đích của hàm docstring là gì?

Bài Viết Liên Quan

Toplist mới

Bài mới nhất

Chủ Đề