Saya sedang menulis kelas ringan yang atributnya dimaksudkan agar dapat diakses publik, dan hanya terkadang diganti dalam contoh tertentu. Tidak ada ketentuan dalam bahasa Python untuk membuat docstring untuk atribut kelas, atau atribut apa pun, dalam hal ini. Apa cara yang diharapkan dan didukung, haruskah ada, untuk mendokumentasikan atribut ini? Saat ini saya melakukan hal semacam ini:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Attributes:
"""
flight_speed = 691
__doc__ += """
flight_speed (691)
The maximum speed that such a bird can attain.
"""
nesting_grounds = "Raymond Luxury-Yacht"
__doc__ += """
nesting_grounds ("Raymond Luxury-Yacht")
The locale where these birds congregate to reproduce.
"""
def __init__(self, **keyargs):
"""Initialize the Albatross from the keyword arguments."""
self.__dict__.update(keyargs)
Ini akan menghasilkan docstring kelas yang berisi bagian docstring standar awal, serta baris yang ditambahkan untuk setiap atribut melalui tugas tambahan ke __doc__
.
Meskipun gaya ini tampaknya tidak dilarang secara tegas dalam pedoman gaya docstring, gaya ini juga tidak disebutkan sebagai opsi. Keuntungannya di sini adalah menyediakan cara untuk mendokumentasikan atribut bersama definisinya, sambil tetap membuat docstring kelas yang rapi, dan menghindari keharusan menulis komentar yang mengulangi informasi dari docstring. Saya masih kesal karena saya harus benar-benar menulis atribut dua kali; Saya sedang mempertimbangkan untuk menggunakan representasi string dari nilai-nilai di docstring untuk setidaknya menghindari duplikasi nilai default.
Apakah ini pelanggaran keji dari konvensi komunitas ad hoc? Apakah itu oke Apakah ada cara yang lebih baik? Misalnya, dimungkinkan untuk membuat kamus yang berisi nilai dan docstrings untuk atribut dan kemudian menambahkan konten ke kelas __dict__
dan docstring di akhir deklarasi kelas; ini akan mengurangi kebutuhan untuk mengetik nama dan nilai atribut dua kali. sunting : ide terakhir ini, saya pikir, sebenarnya tidak mungkin, setidaknya tidak tanpa secara dinamis membangun seluruh kelas dari data, yang tampaknya seperti ide yang sangat buruk kecuali ada alasan lain untuk melakukan itu.
Saya cukup baru mengenal python dan masih mengerjakan detail gaya pengkodean, jadi kritik yang tidak terkait juga diterima.
sumber
attribute doc string
disebutkan dalam PEP 257 yang tidak terkenal dan tampaknya sulit ditemukan yang mungkin menjawab pertanyaan OP, dan didukung oleh beberapa alat sumber. Ini bukan opini. Itu fakta, dan bagian dari bahasa, dan hampir persis seperti yang diinginkan OP.Jawaban:
Untuk menghindari kebingungan: istilah properti memiliki arti khusus dalam python. Yang Anda bicarakan adalah yang kami sebut atribut kelas . Karena mereka selalu ditindaklanjuti melalui kelas mereka, menurut saya masuk akal untuk mendokumentasikannya dalam string dokumen kelas. Sesuatu seperti ini:
Saya pikir itu jauh lebih mudah dilihat daripada pendekatan dalam contoh Anda. Jika saya benar-benar ingin salinan nilai atribut muncul di string dokumen, saya akan meletakkannya di samping atau di bawah deskripsi setiap atribut.
Perlu diingat bahwa di Python, string dokumen adalah anggota sebenarnya dari objek yang mereka dokumentasikan, bukan hanya anotasi kode sumber. Karena variabel atribut kelas bukanlah objek itu sendiri tetapi referensi ke objek, mereka tidak memiliki cara untuk menyimpan string doc mereka sendiri. Saya kira Anda bisa membuat kasus untuk string doc pada referensi, mungkin untuk menjelaskan "apa yang harus diletakkan di sini" daripada "apa yang sebenarnya ada di sini", tapi saya merasa cukup mudah untuk melakukannya dalam string doc kelas yang berisi.
sumber
flight_speed = 691; flight_speed.__doc__ = "blah blah"
. Saya pikir inilah yang Anda sebutkan dalam suntingan Anda . Sayangnya, ini tidak berfungsi untuk contoh jenis bawaan (kebanyakan?) (Sepertiint
dalam contoh itu). Ini berfungsi untuk contoh tipe yang ditentukan pengguna. =========== Sebenarnya ada PEP (maaf, lupakan nomornya) yang mengusulkan penambahan docstring untuk atribut kelas / modul, tapi ditolak karena mereka tidak bisa menemukan cara untuk menjelaskannya apakah docstring untuk atribut sebelumnya atau berikut.Anda mengutip PEP257: Konvensi Docstring, di bagian Apa itu docstring dinyatakan:
Dan ini dijelaskan lebih detail di PEP 258: Dokumentasi atribut. Seperti yang dijelaskan di atas ʇsәɹoɈ. atribut bukan objek yang bisa memiliki __doc__ sehingga tidak akan muncul di
help()
atau pydoc. Docstring ini hanya dapat digunakan untuk dokumentasi yang dibuat.Mereka digunakan di Sphinx dengan directive autoattribute
Sphinx dapat menggunakan komentar pada baris sebelum tugas atau komentar khusus setelah tugas atau docstring setelah definisi yang akan didokumentasikan secara otomatis.
sumber
Anda dapat menyalahgunakan properti untuk efek ini. Properti berisi getter, setter, deleter, dan docstring . Secara naif, ini akan menjadi sangat bertele-tele:
Maka Anda akan memiliki docstring milik Cx:
Melakukan ini untuk banyak atribut memang merepotkan, tetapi Anda bisa membayangkan fungsi pembantu myprop:
Kemudian, memanggil Pythons interaktif
help
akan memberikan:yang menurut saya seharusnya sesuai dengan keinginan Anda.
Sunting : Saya menyadari sekarang bahwa kita mungkin dapat menghindari perlunya memberikan argumen pertama
myprop
sama sekali, karena nama internal tidak masalah. Jika panggilan berikutnyamyprop
entah bagaimana dapat berkomunikasi satu sama lain, itu dapat secara otomatis memutuskan nama atribut internal yang panjang dan tidak mungkin. Saya yakin ada cara untuk menerapkan ini, tetapi saya tidak yakin apakah itu sepadan.sumber