Doc improvements: `pyfunction` usages and acquiring `Python` object

[cmpute]

I found some details making me a little confused when reading the docs, which I think can be improved.

The first is about the argument parsing for pyfunction macro. I searched for how to add keyword arguments to function and surprised to find that the related article is the arg macro under "Method argument" section. And later I found that there's one small section in function documentation referring to the method argument section. I think it's more intuitive to put the documentation of specifying argument behavior under the page for normal function, and then add a referring link on the method argument section.

The second is about how to acquire the Python generally in PyO3. There are documentations to the usage of py: Python object in the GIL page, but it seems that there's no guide of how to acquire a Python object (e.g. for creating a Python list). In my case, I want a function to return objects of different type from the same function, so I have to use a PyObject as a return type (no sure if this is the designed way), then the code will look like

// just for demonstration
#[pyfunction]
fn some_func(input: u8) -> PyResult<PyObject> {
    match input {
        0 => Ok(py.None()), // how to get a `py`?
        1 => Ok(PyList::new(py)),
        2 => Ok(PyDict::new(py)),
        _ => Err(...)
    }
}

Then after looking around the docs, I found some example directly put py: Python as the first argument of the function, so I tried

#[pyfunction]
fn some_func(py: Python, input: u8) -> PyResult<PyObject> {
    match input {
        0 => Ok(py.None()), // how to get a `py`?
        1 => Ok(PyList::new(py)),
        2 => Ok(PyDict::new(py)),
        _ => Err(...)
    }
}

and it works! I'm not sure if this is the idiomatic way to do this, so it's better to document how to get a py object. Thanks!

[birkenfeld]

As you say, the argument parsing section refers to the "method arguments" chapter, but there, "A Python parameter can be specified as part of method signature, in this case the py argument gets injected by the method wrapper, e.g." is basically hidden in "Instance methods", that should be much more prominent.

[cmpute]

Thanks for pointing that out! Maybe we can add a section in the GIL page to organize possible ways to acquire the py by referring to here? And the description here is a little ambiguous, does the py parameter has to be the first one or anywhere is ok?

[mejrs]

Thanks, this is excellent feedback :)

It is mentioned in the api documentation. but not really anywhere in the guide. This is something I initially found annoying as well, I remember having to scour both the docs and the guide to learn how to do things.

Maybe we can add a section in the GIL page to organize possible ways to acquire the py by referring to here?

100% agree 👍. Where did you first start looking when you tried figuring this out?

[cmpute]

The first page I looked at is the GIL page because I know the Python is related to the GIL lock. This page is also where the Python object is introduced. It feels right to me to directly describe how to obtain this object after it's first introduction.

[cmpute]

And maybe the title of that page can be changed to GIL, mutability and object representations? I was expecting to see the docs of builtin Python types (PyLong, PyDict, etc) in this page at first.