Tài liệu thuộc tính python thường được sử dụng?

Question

Một mặt, chúng tôi được khuyến khích chỉ tạo các trường và không khóa các lớp python của chúng tôi với các hàm truy cập phụ được mô hình hoá trên các ngôn ngữ khác.

Mặt khác, PEP for 'attribute docstrings' bị từ chối.

Mặt khác, epydoc và sphinx hỗ trợ chúng. Với nguy cơ của một câu hỏi không mang tính xây dựng, có một thực hành đơn giản, rõ ràng, phổ biến cho việc ghi lại các biến trong các lớp không?

Answer 1

Tôi rephrase nhận xét của tôi như là một câu trả lời kể từ khi tôi được yêu cầu làm như vậy.

Thông thường các thuộc tính (công khai) là tự giải thích và việc sử dụng chúng không được yêu cầu tài liệu. Tên của thuộc tính và ngữ cảnh là đủ để làm rõ thuộc tính là gì và bạn có thể thêm một chút tài liệu về cách xử lý nó trong tài liệu của lớp .

Bạn có thể gặp phải một số trường hợp mà bạn muốn cung cấp cho người dùng quyền truy cập thuộc tính nhưng thuộc tính không đủ tự giải thích và/hoặc việc xử lý yêu cầu chú ý (vì nếu không được xử lý chính xác thì có thể thổi mọi thứ lên ").

Ví dụ: bạn có thể muốn cho người dùng biết rằng thuộc tính phải có "giao diện" cụ thể để cho phép sử dụng nó. Hoặc bạn phải giải thích một điều kiện phải được đáp ứng bởi thuộc tính.

Trong trường hợp này, việc đưa tài liệu cùng với tài liệu của lớp không phải là một ý tưởng hay, vì tài liệu của lớp học lâu hơn và lâu hơn và nó giải thích rất nhiều kiến ​​thức thực sự cụ thể.

Giải pháp đơn giản và, tôi nghĩ, thanh lịch hơn là sử dụng các thuộc tính. Thuộc tính cho phép bạn thêm một chuỗi tài liệu vào thuộc tính và cung cấp cho bạn một cách để thực sự kiểm soát quyền truy cập trên đó, do đó cho phép lớp học trở nên mạnh mẽ hơn.

Nếu bạn phải đối phó với nhiều thuộc tính thì có thể bạn sẽ gặp khó khăn khi viết hàng chục thuộc tính, nhưng bạn vẫn có thể thêm động, ví dụ bằng cách sử dụng trang trí. Điều này hoạt động tốt đặc biệt nếu bạn chỉ muốn thêm một chuỗi tài liệu, sử dụng luôn luôn cùng một loại getter/setter.

Ví dụ, bạn có thể viết:

def set_properties(names_to_docs): 
    def decorator(cls): 
     for name, doc in names_to_docs.items(): 
      prop = property((lambda self: getattr(self, '_{}'.format(name))), 
          (lambda self, val: setattr(self, '_{}'.format(name), val), 
          doc=doc) 
      setattr(cls, name, prop) 
     return cls 
    return decorator 

Và sử dụng nó như thế này:

>>> @set_properties({'a': 'This is a', 'b': 'This is b'}) 
>>> class Test: 
...  def __init__(self): 
...   self._a = 1 
...   self._b = 2 
... 
>>> print(Test.a.__doc__) 
This is a 
>>> Test().a 
1 

Trong một bình luận Lukas Graf chỉ ra rằng bạn có thể sử dụng Zope.interface để tạo ra một lớp mà chỉ đơn giản mô tả lớp bê tông, cung cấp cho bạn một cơ hội để thêm docstrings vào các thuộc tính. Điều này có lẽ sẽ là một lựa chọn khác. Tôi không có kinh nghiệm trong việc sử dụng Zope.interface vì vậy tôi không thể nói chính xác những gì bạn có thể làm và làm thế nào, và làm thế nào nó tương tác, cuối cùng, với các chương trình tự động tài liệu.