Sử dụng ghi đè docstring Python và mở rộng động từ trong Sphinx
Tôi đang sử dụng Sphinx để tạo tài liệu từ các docstrings của mình, được định dạng theo kiểu Sphinx . Theo PEP-257, tôi nên sử dụng động từ "ghi đè" và "mở rộng" để chỉ ra nếu các phương thức kế thừa được thay thế hoặc được gọi.
Nếu một lớp phân lớp một lớp khác và hành vi của nó chủ yếu được kế thừa từ lớp đó, thì docstring của nó phải đề cập đến điều này và tóm tắt các điểm khác biệt. Sử dụng động từ "ghi đè" để chỉ ra rằng một phương thức lớp con thay thế một phương thức lớp cha và không gọi phương thức lớp cha; sử dụng động từ "mở rộng" để chỉ ra rằng một phương thức lớp con gọi phương thức lớp cha (ngoài hành vi của chính nó).
Vì tôi chưa quen với điều này nên tôi không rõ mình nên làm như thế nào ở định dạng Sphinx. Tôi chỉ cần sử dụng một trong những từ trong mô tả của mình hay có một khóa tương tự :return:mà tôi nên áp dụng? Hướng dẫn này được đưa ra ở cấp độ lớp con , đó là nơi các động từ đi đến hay tôi cũng thêm chúng vào các phương thức riêng lẻ?
class A:
"""This is my base class."""
def method_a(self):
"""My base method a."""
pass
def method_b(self):
"""My base method b."""
pass
class B(A):
"""This is the subclass that inherits from :class: A."""
def method_a(self):
"""This method replaces the inherited method_a."""
print("overridden")
def method_b(self):
"""This method calls the inherited method_b."""
super(B, self).method_b()
print("extended")
Một tập hợp docstrings đơn giản nhưng đúng class Bvà các phương thức của nó sẽ như thế nào?
Trả lời
Một ví dụ trực tiếp từ tài liệu Python là defaultdictbộ sưu tập. Nó chỉ ghi đè một phương thức từ điển ( __missing__(key)phương thức).
defaultdict là một lớp con của lớp dict cài sẵn. Nó ghi đè một phương thức (...) Chức năng còn lại giống như đối với lớp dict và không được ghi lại ở đây. (...) Tất cả các đối số còn lại được xử lý giống như khi chúng được chuyển cho hàm tạo dict, bao gồm từ khóa tranh luận.
Tài liệu trình bày rõ ràng điều này trong văn xuôi, ghi lại phương thức ghi đè và giải thích sự khác biệt về các tham số giữa chữ ký của hàm tạo lớp cha và lớp con.
Tôi chỉ sử dụng một trong những từ trong mô tả của mình hay đây là một từ khóa như: return: mà tôi cần đăng ký?
Những gì bạn gọi là "khóa" thực sự được gọi là phần docstring . Không có "phần docstring" cụ thể nào để biểu thị "ghi đè" hoặc "mở rộng", vì điều đó là ẩn. Nếu lớp con định nghĩa một phương thức có cùng tên với một phương thức của lớp cha của nó, thì phương thức đó nhất thiết phải ghi đè hoặc mở rộng.
Kết luận, bạn sẽ ngạc nhiên khi biết tài liệu của bạn thực sự đúng. Tối đa bạn có thể thêm "ghi đè" và "mở rộng" bằng lời nói cùng với tham chiếu chéo đến các phương thức lớp cha, như sau:
class B(A):
"""Neither method_a nor method_b are inherited.
Both methods are redefined in this class.
"""
def method_a(self):
"""This method overrides :meth:`A.method_a`."""
print("overridden")
def method_b(self):
"""This method extends :meth:`A.method_b`."""
super().method_b()
print("extended")
Ví dụ của bạn thiếu các tham số trong các chữ ký, câu trả lời sau đây cho thấy cách các phương thức quá tải và mở rộng có các tham số khác nhau có thể được ghi lại .