Làm cách nào để tạo các thuộc tính đối tượng tài liệu Python/Sphinx chỉ được khai báo trong __init__?

Question

tôi có các lớp học Python với các thuộc tính đối tượng mà chỉ tuyên bố như một phần của hoạt động các nhà xây dựng, như vậy:

class Foo(object): 
    def __init__(self, base): 
     self.basepath = base 

     temp = [] 
     for run in os.listdir(self.basepath): 
      if self.foo(run): 
       temp.append(run) 
     self.availableruns = tuple(sorted(temp)) 

Nếu bây giờ tôi sử dụng một trong hai help(Foo) hoặc cố tài liệu Foo trong Sphinx, những self.basepath và self.availableruns thuộc tính không được hiển thị. Đó là vấn đề đối với người dùng API của chúng tôi.

Tôi đã thử tìm kiếm một cách tiêu chuẩn để đảm bảo rằng các thuộc tính "được khai báo động" này có thể được tìm thấy (và tốt hơn là docstring'd) bởi trình phân tích cú pháp, nhưng không may mắn cho đến nay. Bất kỳ đề xuất? Cảm ơn.

Answer 1

Bạn có thể định nghĩa một biến lớp học với tên giống như biến ví dụ. Biến lớp đó sau đó sẽ bị che mờ bởi biến thể hiện khi bạn thiết lập nó. Ví dụ:

class Foo(object): 
    #: Doc comment for availableruns 
    availableruns =() 

    def __init__(self, base): 
     ... 
     self.availableruns = tuple(sorted(temp)) 

Thật vậy, nếu biến dụ có hữu ích bất biến giá trị mặc định (ví dụ Không có hoặc tuple trống), sau đó bạn có thể tiết kiệm một bộ nhớ nhỏ bằng cách chỉ không thiết lập các biến nếu cần phải có mặc định của nó giá trị. Tất nhiên, cách tiếp cận này sẽ không hoạt động nếu bạn đang nói về một biến mẫu mà bạn có thể muốn xóa (ví dụ: del foo.availableruns) - nhưng tôi thấy đó không phải là trường hợp rất phổ biến.

Nếu bạn đang sử dụng nhân sư, và có "tự động phân bổ", sau đó điều này sẽ được tài liệu một cách thích hợp. Hoặc, tùy thuộc vào bối cảnh của những gì bạn đang làm, bạn chỉ có thể trực tiếp sử dụng chỉ thị Sphinx .. py:attribute::.

Answer 2

Tôi đã thử tìm kiếm một cách tiêu chuẩn để đảm bảo rằng các thuộc tính "được khai báo động" này có thể được tìm thấy (và tốt hơn là docstring'd) bởi trình phân tích cú pháp. Bất kỳ đề xuất?

Chúng không bao giờ được "phát hiện" bởi bất kỳ trình phân tích cú pháp nào.

Python có setattr. Tập hợp các thuộc tính hoàn toàn không bao giờ là "có thể phát hiện được", theo bất kỳ nghĩa nào của từ đó.

Bạn hoàn toàn phải mô tả chúng trong chuỗi tài liệu.

[Trừ khi bạn muốn thực hiện một loạt các chương trình meta để tạo các tài liệu từ những thứ bạn thu thập được từ inspect hoặc một thứ gì đó. Thậm chí sau đó, bạn "giải pháp" sẽ không đầy đủ ngay sau khi bạn bắt đầu sử dụng setattr.]

class Foo(object): 
    """ 
    :ivar basepath: 
    :ivar availableruns: 
    """ 
    def __init__(self, base):