Hướng dẫn python access docstring

Chuỗi tài liệu Python (hoặc docstrings) tạo điều kiện liên kết tài liệu với các mô-đun, hàm, lớp và phương thức Python. Docstring của một đối tượng được định nghĩa bằng cách bao gồm một hằng chuỗi làm câu lệnh đầu tiên trong định nghĩa của đối tượng. Nó được chỉ định trong mã nguồn, được sử dụng, giống như một nhận xét, để ghi lại một đoạn mã cụ thể.

Nội dung chính

  • Cấu trúc của Docstring trong Python
  • Ví dụ về Docstring:
  • Cách sử dụng Docstrings trong Python
  • Khai báo Docstrings trong Python
  • Truy cập Docstrings
  • Ví dụ: Sử dụng dấu ngoặc kép:
  • Ví dụ: Sử dụng dấu ngoặc ba
  • Thụt lề trong Docstrings
  • Docstring một dòng trong Python
  • Docstring nhiều dòng trong Python
  • Sự khác biệt giữa nhận xét Python và docstrings

Không giống như các bình luận mã nguồn thông thường, docstring phải mô tả chức năng hoạt động chứ không phải như thế nào. Tất cả các hàm phải có một Docstring,  Điều này cho phép chương trình kiểm tra các nhận xét này tại thời điểm chạy, ví dụ như một hệ thống trợ giúp tương tác hoặc dưới dạng siêu dữ liệu.

>>> Xem thêm: Không gian tên trong Python- Tìm hiểu về không gian tên trong Python

Ví dụ về Docstring trong Python

Cấu trúc của Docstring trong Python

- Dòng chuỗi doc phải bắt đầu bằng chữ hoa và kết thúc bằng dấu chấm.

- Dòng đầu tiên nên là một mô tả ngắn.

- Nếu có nhiều dòng hơn trong docstring, dòng thứ hai phải để trống, ngăn cách trực quan phần tóm tắt với phần còn lại của mô tả.

- Các dòng sau nên là một hoặc nhiều đoạn văn mô tả các quy ước gọi của đối tượng, các tác dụng phụ của nó,...

Ví dụ về Docstring:

def square(n):

    '''Takes in a number n, returns the square of n'''

    return n**2

Cách sử dụng Docstrings trong Python

Khai báo Docstrings trong Python

Các docstrings được khai báo bằng cách sử dụng "" dấu ngoặc kép ba "" hoặc "" "dấu ngoặc kép ba" "" ngay bên dưới khai báo lớp, phương thức hoặc hàm. Tất cả các chức năng phải có một chuỗi doc.

Truy cập Docstrings

Có thể truy cập docstrings bằng phương thức __doc__ của đối tượng hoặc sử dụng hàm trợ giúp.

Các ví dụ dưới đây trình bày cách khai báo và truy cập một docstring.

Ví dụ: Sử dụng dấu ngoặc kép:

def my_function():

    '''Demonstrates triple double quotes

    docstrings and does nothing really.'''

       return None

print("Using __doc__:")

print(my_function.__doc__)

print("Using help:")

help(my_function)

Output

Using __doc__:

Demonstrates triple double quotes

    docstrings and does nothing really.

Using help:

Help on function my_function in module __main__:

my_function()

    Demonstrates triple double quotes

    docstrings and does nothing really.

Ví dụ: Sử dụng dấu ngoặc ba

def my_function(): 

"""Demonstrates triple double quotes 

docstrings and does nothing really."""

return None

print("Using __doc__:") 

print(my_function.__doc__) 

print("Using help:") 

help(my_function) 

Output:

Using __doc__:

Demonstrates triple double quotes

    docstrings and does nothing really.

Using help:

Help on function my_function in module __main__:

my_function()

    Demonstrates triple double quotes

    docstrings and does nothing really.

>>> Tham khảo: Khóa học lập trình Python

Thụt lề trong Docstrings

Toàn bộ Docstring trong Python được thụt lề giống như các dấu ngoặc kép ở dòng đầu tiên của nó. Các công cụ xử lý Docstring sẽ loại bỏ một lượng thụt lề thống nhất từ ​​dòng thứ hai và các dòng tiếp theo của chuỗi tài liệu, bằng với mức thụt lề tối thiểu của tất cả các dòng không trống sau dòng đầu tiên. Bất kỳ thụt lề nào trong dòng đầu tiên của docstring (tức là lên đến dòng mới đầu tiên) là không đáng kể và sẽ bị loại bỏ. Thụt lề tương đối của các dòng sau đó trong chuỗi docstring được giữ lại.

Docstring một dòng trong Python

Docstring một dòng là một docstrings nằm trong một dòng. Chúng được sử dụng trong những trường hợp hiển nhiên. Như trong ví dụ dưới đây, dấu ngoặc kép đóng và mở đều nằm trên cùng một dòng. 

Ví dụ: def power(a, b):

    """Returns arg1 raised to power arg2."""

    return a**b

print(power.__doc__)

Kết quả:

Returns arg1 raised to power arg2.

Docstring nhiều dòng trong Python

Docstring nhiều dòng bao gồm một dòng tóm tắt tương tự như Docstring một dòng, theo sau là một dòng trống, tiếp theo là mô tả chi tiết hơn. Dòng tóm tắt có thể nằm trên cùng dòng với phần mở đầu hoặc dòng tiếp theo.

Ví dụ dưới đây cho thấy một Docstring nhiều dòng.

def my_function(arg1):

    """

    Summary line.

      Extended description of function.

    Parameters:

    arg1 (int): Description of arg1

    Returns:

    int: Description of return value

      """

      return arg1

print(my_function.__doc__)

Sự khác biệt giữa nhận xét Python và docstrings

Bình luận Python là thông tin hữu ích mà nhà phát triển cung cấp để làm cho người đọc hiểu mã nguồn. Nó giải thích logic hoặc một phần của nó được sử dụng trong mã. Nó được viết bằng cách sử dụng ký hiệu #. 

Trong khi Docstrings trong Python cung cấp một cách thuận tiện để liên kết tài liệu với các mô-đun, hàm, lớp và phương thức Python.

Kết luận: Docstring là một thành phần cần thiết cho quá trình lập trình trong Python. Bài viết trên đã giúp bạn tìm hiểu về Docstring, các khái niệm và cách sử dụng Docstring trong Python. Muốn thành thạo Python và các ngôn ngữ lập trình khác, tìm hiểu ngay các khóa học lập trình tại T3H bạn nhé.

Nguồn: Geeksforgeeks, programiz