Hướng dẫn python docstring return tuple - python docstring trả lại tuple

Quy tắc chung#

Docstrings phải được xác định với ba trích dẫn kép. Không nên để lại các dòng trống trước hoặc sau DocString. Văn bản bắt đầu trong dòng tiếp theo sau các trích dẫn mở. Các trích dẫn đóng có dòng riêng của chúng [có nghĩa là chúng không ở cuối câu cuối cùng].

Trong những dịp hiếm hoi, các kiểu phần còn lại như văn bản in đậm hoặc chữ nghiêng sẽ được sử dụng trong các tài liệu, nhưng nó có phổ biến để có mã nội tuyến, được trình bày giữa các backticks. Những điều sau đây được xem xét mã nội tuyến:

• Tên của một tham số

• Mã Python, một mô-đun, hàm, tích hợp, loại, nghĩa đen [ví dụ:

  def add_values[arr]:
      """
      Add the values in ``arr``.
  
      This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
  
      Some sections are omitted here for simplicity.
      """
      return sum[arr]
  

  1,

  def add_values[arr]:
      """
      Add the values in ``arr``.
  
      This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
  
      Some sections are omitted here for simplicity.
      """
      return sum[arr]
  

  2,

  def add_values[arr]:
      """
      Add the values in ``arr``.
  
      This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
  
      Some sections are omitted here for simplicity.
      """
      return sum[arr]
  

  3,

  def add_values[arr]:
      """
      Add the values in ``arr``.
  
      This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
  
      Some sections are omitted here for simplicity.
      """
      return sum[arr]
  

  4,

  def add_values[arr]:
      """
      Add the values in ``arr``.
  
      This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
  
      Some sections are omitted here for simplicity.
      """
      return sum[arr]
  

  5]

• Một lớp gấu trúc [ở dạng

  def add_values[arr]:
      """
      Add the values in ``arr``.
  
      This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
  
      Some sections are omitted here for simplicity.
      """
      return sum[arr]
  

  6]

• Phương pháp gấu trúc [ở dạng

  def add_values[arr]:
      """
      Add the values in ``arr``.
  
      This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
  
      Some sections are omitted here for simplicity.
      """
      return sum[arr]
  

  7]

• Hàm gấu trúc [ở dạng

  def add_values[arr]:
      """
      Add the values in ``arr``.
  
      This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.
  
      Some sections are omitted here for simplicity.
      """
      return sum[arr]
  

  8]

Ghi chú

Để chỉ hiển thị thành phần cuối cùng của lớp, phương thức hoặc chức năng được liên kết, tiền tố với

def add_values[arr]:
    """
    Add the values in ``arr``.

    This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.

    Some sections are omitted here for simplicity.
    """
    return sum[arr]

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

Good:

def add_values[arr]:
    """
    Add the values in ``arr``.

    This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.

    Some sections are omitted here for simplicity.
    """
    return sum[arr]

Bad:

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

Phần 1: Tóm tắt ngắn#

Tóm tắt ngắn là một câu duy nhất thể hiện những gì chức năng làm một cách ngắn gọn.

Tóm tắt ngắn phải bắt đầu bằng một chữ cái viết hoa, kết thúc bằng một dấu chấm và vừa với một dòng. Nó cần thể hiện những gì đối tượng làm mà không cung cấp chi tiết. Đối với các chức năng và phương pháp, tóm tắt ngắn phải bắt đầu với một động từ nguyên bản.

Good:

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

Bad:

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

def astype[dtype]:
    """
    Method to cast Series type.

    Does not start with verb.
    """
    pass

def astype[dtype]:
    """
    Cast Series type

    Missing dot at the end.
    """
    pass

def astype[dtype]:
    """
    Cast Series type from its current type to the new type defined in
    the parameter dtype.

    Summary is too verbose and doesn't fit in a single line.
    """
    pass

Phần 2: Tóm tắt mở rộng#

Tóm tắt mở rộng cung cấp chi tiết về những gì chức năng làm. Nó không nên đi vào các chi tiết của các tham số, hoặc thảo luận về các ghi chú thực hiện, trong các phần khác.

Một dòng trống được để lại giữa bản tóm tắt ngắn và tóm tắt mở rộng. Mỗi đoạn trong bản tóm tắt mở rộng kết thúc bằng một dấu chấm.

Tóm tắt mở rộng sẽ cung cấp chi tiết về lý do tại sao chức năng này hữu ích và các trường hợp sử dụng của chúng, nếu nó không quá chung chung.

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

Phần 3: Tham số#

Các chi tiết của các tham số sẽ được thêm vào trong phần này. Phần này có tiêu đề Các tham số của người dùng, theo sau là một dòng có dấu gạch nối dưới mỗi chữ cái của từ tham số. Một dòng trống được để lại trước tiêu đề phần, nhưng không phải sau đó, chứ không phải giữa dòng với từ ngữ tham số, và phần có dấu gạch nối.

Sau tiêu đề, mỗi tham số trong chữ ký phải được ghi lại, bao gồm

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

Các tham số được xác định bởi tên của chúng, theo sau là một không gian, dấu hai chấm, không gian khác và loại [hoặc loại]. Lưu ý rằng không gian giữa tên và đại tràng là quan trọng. Các loại không được xác định cho

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

Đối với các đối số từ khóa có giá trị mặc định, mặc định sẽ được liệt kê sau dấu phẩy ở cuối loại. Hình thức chính xác của loại trong trường hợp này sẽ là Int Int, mặc định 0. Trong một số trường hợp, có thể hữu ích để giải thích ý nghĩa của đối số mặc định, có thể được thêm vào sau dấu phẩy Int Int, mặc định -1, có nghĩa là tất cả CPU.

Trong trường hợp giá trị mặc định là

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

Good:

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

Bad:

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

def astype[dtype]:
    """
    Cast Series type.

    This section will provide further details.
    """
    pass

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

Phần 4: Trả về hoặc sản lượng#

Nếu phương thức trả về một giá trị, nó sẽ được ghi lại trong phần này. Ngoài ra nếu phương thức mang lại đầu ra của nó.

Tiêu đề của phần sẽ được xác định theo cách tương tự như các tham số của Google. Với các tên, trả về, hay, người khác đã tạo ra một dòng có nhiều dấu gạch ngang như các chữ cái trong từ trước.

Tài liệu về lợi nhuận cũng tương tự như các tham số. Nhưng trong trường hợp này, sẽ không có tên nào được cung cấp, trừ khi phương thức trả về hoặc mang lại nhiều hơn một giá trị [một bộ giá trị].

Các loại cho các loại trả về trên mạng và các sản phẩm của người khác, giống như các loại đối với các tham số của các tham số. Ngoài ra, mô tả phải kết thúc với một dấu chấm.

Ví dụ: với một giá trị duy nhất:

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

Với nhiều hơn một giá trị:

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

Nếu phương thức mang lại giá trị của nó:

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

Phần 5: Xem thêm#

Phần này được sử dụng để cho người dùng biết về chức năng gấu trúc liên quan đến phần được ghi lại. Trong các trường hợp hiếm hoi, nếu không có phương pháp hoặc chức năng liên quan nào có thể được tìm thấy, phần này có thể được bỏ qua.

Một ví dụ rõ ràng sẽ là các phương pháp

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

Để đưa ra trực giác về những gì có thể được xem xét liên quan, ở đây có một số ví dụ:

• def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  0 và

  def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  1, vì chúng cũng làm như vậy, nhưng trong một trường hợp cung cấp các chỉ số và ở các vị trí khác

• def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  2 và

  def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  3, khi họ làm điều ngược lại

• def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  4,

  def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  5 và

  def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  6, vì thật dễ dàng là người dùng tìm kiếm phương thức lặp lại các cột kết thúc theo phương thức để lặp lại trên các hàng và ngược lại

• def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  7 và

  def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  8, vì cả hai phương thức đều được sử dụng để xử lý các giá trị bị thiếu

• def astype[dtype]:
      """
      Method to cast Series type.
  
      Does not start with verb.
      """
      pass
  

  9 và

  def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  0, vì chúng là bổ sung

• def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  1 và

  def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  2, vì một người là một khái quát của người kia

• def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  3 và

  def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  4, vì người dùng có thể đang đọc tài liệu của

  def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  3 để biết cách diễn ra như một ngày và cách thực hiện nó là với

  def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  4

• def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  7 có liên quan đến

  def astype[dtype]:
      """
      Cast Series type
  
      Missing dot at the end.
      """
      pass
  

  8, vì chức năng của nó dựa trên nó

Khi quyết định những gì có liên quan, bạn chủ yếu nên sử dụng ý thức chung của mình và suy nghĩ về những gì có thể hữu ích cho người dùng đọc tài liệu, đặc biệt là những người ít kinh nghiệm hơn.

Khi liên quan đến các thư viện khác [chủ yếu là

def astype[dtype]:
    """
    Cast Series type

    Missing dot at the end.
    """
    pass

def astype[dtype]:
    """
    Cast Series type from its current type to the new type defined in
    the parameter dtype.

    Summary is too verbose and doesn't fit in a single line.
    """
    pass

def astype[dtype]:
    """
    Cast Series type from its current type to the new type defined in
    the parameter dtype.

    Summary is too verbose and doesn't fit in a single line.
    """
    pass

def astype[dtype]:
    """
    Cast Series type from its current type to the new type defined in
    the parameter dtype.

    Summary is too verbose and doesn't fit in a single line.
    """
    pass

Phần này có một tiêu đề, còn xem thêm [lưu ý vốn S và A], theo sau là dòng có dấu gạch nối và đi trước một dòng trống.

Sau khi tiêu đề, chúng tôi sẽ thêm một dòng cho từng phương pháp hoặc hàm liên quan, theo sau là một không gian, một dấu hai chấm, một không gian khác và một mô tả ngắn minh họa phương pháp hoặc chức năng này, tại sao nó có liên quan trong bối cảnh này và những gì Sự khác biệt chính là giữa hàm được ghi lại và một được tham chiếu. Mô tả cũng phải kết thúc bằng một dấu chấm.

Lưu ý rằng trong các trò chơi trả về của người Hồi giáo và các sản phẩm của người khác, mô tả được đặt trên dòng sau loại. Tuy nhiên, trong phần này, nó nằm trên cùng một dòng, với một dấu hai chấm ở giữa. Nếu mô tả không phù hợp với cùng một dòng, nó có thể tiếp tục vào các dòng khác phải được thụt thêm.

Ví dụ:

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

Phần 6: Ghi chú#

Đây là một phần tùy chọn được sử dụng cho các ghi chú về việc thực hiện thuật toán hoặc để ghi lại các khía cạnh kỹ thuật của hành vi chức năng.

Hãy bỏ qua nó, trừ khi bạn quen thuộc với việc thực hiện thuật toán hoặc bạn khám phá một số hành vi phản trực quan trong khi viết các ví dụ cho hàm.

Phần này theo định dạng giống như phần tóm tắt mở rộng.

Phần 7: Ví dụ#

Đây là một trong những phần quan trọng nhất của một tài liệu, mặc dù được đặt ở vị trí cuối cùng, vì thường mọi người hiểu các khái niệm tốt hơn bằng ví dụ hơn là thông qua các giải thích chính xác.

Các ví dụ trong tài liệu, bên cạnh việc minh họa việc sử dụng hàm hoặc phương thức, phải là mã Python hợp lệ, trả về đầu ra đã cho theo cách xác định và có thể được sao chép và chạy bởi người dùng.

Các ví dụ được trình bày như một phiên trong Terminal Python.

def astype[dtype]:
    """
    Cast Series type from its current type to the new type defined in
    the parameter dtype.

    Summary is too verbose and doesn't fit in a single line.
    """
    pass

def astype[dtype]:
    """
    Cast Series type from its current type to the new type defined in
    the parameter dtype.

    Summary is too verbose and doesn't fit in a single line.
    """
    pass

Cách để trình bày các ví dụ như sau:

1. Nhập thư viện bắt buộc [trừ

   def astype[dtype]:
       """
       Cast Series type
   
       Missing dot at the end.
       """
       pass
   

   9 và

   def astype[dtype]:
       """
       Cast Series type from its current type to the new type defined in
       the parameter dtype.
   
       Summary is too verbose and doesn't fit in a single line.
       """
       pass
   

   6]

2. Tạo dữ liệu cần thiết cho ví dụ

3. Hiển thị một ví dụ rất cơ bản đưa ra ý tưởng về trường hợp sử dụng phổ biến nhất

4. Thêm các ví dụ với các giải thích minh họa cách các tham số có thể được sử dụng cho chức năng mở rộng

Một ví dụ đơn giản có thể là:

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

Các ví dụ nên ngắn gọn nhất có thể. Trong trường hợp sự phức tạp của hàm yêu cầu các ví dụ dài, được khuyến nghị sử dụng các khối có tiêu đề in đậm. Sử dụng Double Star

def astype[dtype]:
    """
    Cast Series type from its current type to the new type defined in
    the parameter dtype.

    Summary is too verbose and doesn't fit in a single line.
    """
    pass

def astype[dtype]:
    """
    Cast Series type from its current type to the new type defined in
    the parameter dtype.

    Summary is too verbose and doesn't fit in a single line.
    """
    pass

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

def func[]:

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func[]:``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar

def astype[dtype]:
    """
    Casts Series type.

    Verb in third-person of the present simple, should be infinitive.
    """
    pass

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

def add[num1, num2]:
    """
    Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Parameters
    ----------
    num1 : int
        First number to add.
    num2 : int
        Second number to add.

    Returns
    -------
    int
        The sum of ``num1`` and ``num2``.

    See Also
    --------
    subtract : Subtract one integer from another.

    Examples
    --------
    >>> add[2, 2]
    4
    >>> add[25, 0]
    25
    >>> add[10, -10]
    0
    """
    return num1 + num2

"""This should fail because Tuple is not imported, but no warning"""
def that[a, b, c]:
    """ 
    :rtype: Tuple[int, float, Foo]
    """
    return a, b, c

"""
This only partially works because 'Foo' isn't in scope. 
This can easily happen if someone refactored the name of 'Foo', 
but the comments wouldn't be updated.
"""
def thing[a, b, c]:
    """
    :rtype: [int, float, Foo]
    """
    return a, b, c

def documentation_nightmare[a, b, c]:
   """ ​
   There are no checks, and everything seems fine, but the documentation is all wrong and hard to maintain. 
   :param a: A
   :type a: float
   :param b: B
   :type b: Bar
   :param c: C
   :type c: int
   ​:rtype: Tuple[int, float, Foo]
   ​"""
   ​return a, b, c

def add[num1, num2]:
    """
    Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Parameters
    ----------
    num1 : int
        First number to add.
    num2 : int
        Second number to add.

    Returns
    -------
    int
        The sum of ``num1`` and ``num2``.

    See Also
    --------
    subtract : Subtract one integer from another.

    Examples
    --------
    >>> add[2, 2]
    4
    >>> add[25, 0]
    25
    >>> add[10, -10]
    0
    """
    return num1 + num2