Better API or documentation on `warn`

[cmpute]

Currently the exposed API for instantiate a warning in PyO3 is

/// Issues a warning message. May return a `PyErr` if warnings-as-errors is enabled.
pub fn warn(py: Python<'_>, category: &PyAny, message: &str, stacklevel: i32) -> PyResult<()>

One issue here is that first the category and stacklevel arguments are not documented in detail, and another issue is that the possible values for the category are not exposed from the ffi. The availble categories in the original Python docs are listed here, and the corresponding values are exposed only in ffi.

I think one solution is to accept category with a generic type just like PyErr::from_type, and wrap the warning types in the pyo3::exceptions module for users to pass to the warn function

[cmpute]

Quote from the Python docs:

The category argument is a warning category (see below) or NULL; the message argument is a UTF-8 encoded string. stack_level is a positive number giving a number of stack frames; the warning will be issued from the currently executing line of code in that stack frame. A stack_level of 1 is the function calling PyErr_WarnEx(), 2 is the function above that, and so forth.

Warning categories must be subclasses of PyExc_Warning; PyExc_Warning is a subclass of PyExc_Exception; the default warning category is PyExc_RuntimeWarning. The standard Python warning categories are available as global variables whose names are enumerated at Standard Warning Categories.

Maybe these paragraphs should be included in the docs for warn

[cmpute]

Close because this is already solved as in the latest version.