gh-142349: Document LazyImportType.resolve() method

[Viicos]

resolve() is referenced several times in PEP 810, but not documented. I believe it would make sense to explicitly document it.

See also #156924.

• Issue: Implement PEP 810 – Explicit lazy imports #142349

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34393043 | 📁 Comparing 1ddd01d against main (7d71b3e)

  🔍 Preview build  

1 file changed

± library/types.html

[johnslavik]

Hmmm, https://docs.python.org/3.16/reference/simple_stmts.html#lazy doesn't know about types.LazyImportType. Additionally, none of the classes in types have method documentations.

Maybe the right place for this documentation is in https://docs.python.org/3.16/reference/simple_stmts.html#lazy?

[johnslavik]

And https://docs.python.org/3.16/library/types.html#types.LazyImportType doesn't know about https://docs.python.org/3.16/reference/simple_stmts.html#lazy. These guys should talk to each other.

[johnslavik]

Actually, this belongs to built-in types. Generator (that isn't a builtin name) interface is documented there too.

@Viicos can we move this to built-in types?

[JelleZijlstra]

I think documenting this in types.rst makes more sense; MappingProxyType is also documented there with some methods.

[Viicos]

I indeed took MappingProxyType as a precedent when documenting the method. However, it is the only one currently doing so. Maybe we should move the method definitions of MappingProxyType to https://docs.python.org/3/library/stdtypes.html, and ensure this is done for other types (such as lazy imports) in the future? As mentioned, this is already the case for generator-iterators, which has types.GeneratorType without any method documented.

I also know the stdlib page is huge and there are plans to split it, so not sure what should be done today.

[johnslavik]

@encukou, what would you recommend?

[encukou]

IMO, eventually this should be in a new builtins section, but, that's not in place now :)
Any of the proposed locations fine; stick with the current version.

And https://docs.python.org/3.16/library/types.html#types.LazyImportType doesn't know about https://docs.python.org/3.16/reference/simple_stmts.html#lazy

The bigger issue is that reference/simple_stmts has a stub that refers to PEP 810 for the “full specification”, while PEP 810 points right back for the “canonical documentation”. The full spec should move to the docs. But that's not for this PR to solve.

[johnslavik]

The full spec should move to the docs. But that's not for this PR to solve.

I worked on this a while ago!

[encukou]

Looking at it again, this should mention the return value. Maybe like this:

Suggested change

	Resolve the lazy object by reifying the lazily imported module.
	Resolve the lazy import and return the "real" imported module.

[johnslavik]

It would perhaps also be nice to define reifying/resolving "fully" (with all the effects of reifying a lazy import, such as what it does to sys.lazy_modules), but I assume that the spec will do a better job at it.

[Viicos]

It would perhaps also be nice to define reifying/resolving "fully" (with all the effects of reifying a lazy import, such as what it does to sys.lazy_modules), but I assume that the spec will do a better job at it.

Yeah most likely it makes more sense to wait for the full spec to be written out, and update this with a :ref: to what reifying means.

Resolve the lazy import and return the "real" imported module.

lazy proxy objects aren't necessarily proxying module objects, so maybe something like:

Suggested change

	Resolve the lazy object by reifying the lazily imported module.
	Reify the lazy import and return the "real" object being imported.