Clarify `warnings.deprecated` public API

Mô tả

Documentation

The current docs only specify that it sets the __deprecated__ attribute on the deprecated item.

Pydantic relies on its full API: the fact that it’s a class, and that its instances have all passed parameters in attributes: deprecated(**kw).__dict__ == kw basically.

Two questions:

Is that safe or might deprecated get e.g. refactored into a function at some point?
Can we subclass it and add parameters? Will type checkers understand this and still mark a @our_deprecated_subclass(...) def ... as deprecated? See https://github.com/python/typing/issues/2256

maybe related to #138165

Linked PRs

gh-153879
gh-154487
gh-154488
gh-154489

Bắt đầu từ đâu

Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.

Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.

Fork repository và làm thay đổi trên một nhánh.

Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Bắt đầu với tài liệu hiện tại về warnings.deprecated, sau đó đọc các PR được liên kết 153879, 154487, 154488 và 154489 cùng với issue liên quan 138165. Công việc được xem là hoàn tất khi đã ghi lại tài liệu về lớp công khai, các thuộc tính của instance, hành vi khi tạo subclass và các kỳ vọng của type checker, hoặc ghi lại những câu trả lời đã được thống nhất.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ

python

Lĩnh vực

documentation

Loại issue

Tài liệu

Độ khó

4/5

Thời gian dự kiến

3-5 ngày

Mức độ hoạt động

Đình trệ

Độ rõ ràng

Cần làm rõ

Mức phù hợp với người mới

25/100