Python Docstring: tăng so với số tăng

Question

Tôi sử dụng IDE PyCharm hỗ trợ việc tạo tài liệu tuân thủ PEP0257. Nó cung cấp hai thuộc tính tôi không hoàn toàn hiểu được sự khác biệt/sử dụng giữa:

• :raise Exception: exception explanation here
• :raises Exception: exception explanation here

Khi tôi sẽ sử dụng raise như phản đối để raises trong docstring của tôi? Cụ thể, nếu một lớp yêu cầu một đối số không được cung cấp và đặt ra một số TypeError, nó nên được sử dụng để ghi lại điều đó?

Answer 1

TL; DR

raises được sử dụng để mô tả các trường hợp ngoại lệ có thể được nâng lên. raise được nhận dạng bởi Sphinx khi chạy autodoc và giống như raises.

Full Giải thích

PyCharm giúp trong việc sử dụng một vài phong cách khác nhau của docstring ý kiến.

Ba mà tôi thường sử dụng là:

1. NumPy Format
2. Google Format
3. Sphinx (nhiều hơn một định dạng)

Trong tất cả các có một phần đặc biệt cho Raises mà bạn có thể thấy trong phiên bản thử nghiệm mã PyCharm cũ hơn:

1. Simple NumPy
2. Simple Google

Việc thực hiện cho SphinxDocString chúng ta có thể see here có có rất nhiều từ khóa có thể được công nhận. Sau đó, các thẻ đó sẽ liên kết với danh sách RAISES_TAGS có thể được tìm thấy here.

Tôi hy vọng thông tin này hữu ích.