make GILOnceCell::get_or_try_init_type_ref public

[glevco]

Resolves #4516.

• Change GILOnceCell::get_or_try_init_type_ref to GILOnceCell::import and make it public API, adding an example for it.
• Update "Executing existing Python code" section of the guide:
  • Add mention to GILOnceCell::import.
  • Change Python::eval_bound (which is deprecated) to Python::eval.
  • Change Python::run_bound (which is deprecated) to Python::run, also adding missing link.

[mejrs]

Change PyModule::import suggestion to Python::import instead

Why? I don't have a strong opinion either way, but slightly prefer PyModule::import.

[mejrs]

This can use a better name. Maybe just "import"? 🤔

[glevco]

I agree, but then maybe it should be implemented for GILOnceCell<Py<T>> where T: PyTypeInfo instead of GILOnceCell<Py<PyType>>? Otherwise, I would call it import_type.

[davidhewitt]

I'd be fine with that. I think you want T: PyTypeCheck rather than T: PyTypeInfo, though.

[glevco]

Right, done in 79568f6!

[glevco]

@mejrs

Why? I don't have a strong opinion either way, but slightly prefer PyModule::import.

Since Python::import was used in the implementation of get_or_try_init_type_ref, I assumed it was preferable. Also, it pairs nicely with the other entries in this section of the guide, as they recommend other "global" functions such as Python::eval and Python::run. What do you think?

[davidhewitt]

I prefer PyModule::import too, I think it's nicer to think of that as a "constructor" for the PyModule type.

[mejrs]

What do you think?

From a documentation perspective I would prefer that people visit PyModule::import over Python::import. Python has a lot of not module related api, and its page is a lot bigger.

Also, using "constructor" syntax also makes it clear that when they use it, they're getting a module (rather than something arbitrary like from foo import bar might do).

[glevco]

@davidhewitt @mejrs Fair enough, I reverted the guide back to PyModule::import in 79568f6. I also changed the method name to GILOnceCell::import and made its impl generic for PyTypeCheck, as discussed above. I updated the PR description accordingly.