Document replacement for sphinx.util.import_object or un-deprecate

[mgeier]

Describe the bug

According to https://www.sphinx-doc.org/en/master/extdev/deprecated.html, sphinx.util.import_object is deprecated and importlib.import_module is suggested as alternative.

However, sphinx.util.import_object, does much more:

sphinx/sphinx/util/_importer.py

Lines 9 to 27 in 116a430

	def import_object(object_name: str, /, source: str = '') -> Any:
	"""Import python object by qualname."""
	obj_path = object_name.split('.')
	module_name = obj_path.pop(0)
	try:
	obj = import_module(module_name)
	for name in obj_path:
	module_name += '.' + name
	try:
	obj = getattr(obj, name)
	except AttributeError:
	obj = import_module(module_name)
	except (AttributeError, ImportError) as exc:
	if source:
	msg = f'Could not import {object_name} (needed for {source})'
	raise ExtensionError(msg, exc) from exc
	msg = f'Could not import {object_name}'
	raise ExtensionError(msg, exc) from exc
	return obj

Am I supposed to copy all that code into my extension?

Or is there another (shorter) replacement?

Either way, this information should be added to the docs.

How to Reproduce

• Use sphinx.util.import_object(). This will give a warning:

  sphinx.deprecation.RemovedInSphinx10Warning: 'sphinx.util.import_object' is deprecated. Check CHANGES for Sphinx API modifications.
  

• Look for CHANGES -> not found

• try CHANGES.rst -> the relevant content isn't there

• try doc/changes/8.1.rst -> importlib.import_module is suggested

• use importlib.import_module -> doesn't work, because it provides only a small part of original functionality

Environment Information

-

Sphinx extensions

No response

Additional context

No response

[mgeier]

If there is no alternative, maybe sphinx.util.import_object() should be un-deprecated?

[timhoffm]

#12762 moved import_object into the private module sphinx.util._importer. It will continue to be needed in the autodoc extension. From the introduced changes, I would deduce that the intention is to make it private so that we don't have to make any compatibility guarantees on it in the future. It's a valid approach to minimize the API surface. OTOH if this is an essential functionality for other extensions we may reconsider. But @AA-Turner as the author should comment on this.

[AA-Turner]

Within Sphinx, sphinx.util._importer.import_object() is only used in sphinx.builders (to load a custom template_bridge) and sphinx.search.ja (to load a custom splitter). autodoc has a private import_object() that does even more work, though this is unaffected.

I initially deprecated the function as I am slowly trying to reduce the surface of our "public API", as ill-defined as that is currently, and the implementation of import_object() is fairly primitive.

For me, "importing a dotted name" is sufficiently generic that I don't think Sphinx should be in the business of providing a utility function for it. However, given we have up until now (and will until at least Sphinx 10), I am open to un-deprecating it (but perhaps discouraging its use?).

To your other points:

• CHANGES was renamed to CHANGES.rst for syntax highlighting (and better support on Windows), sorry for the confusion.
• The deprecation is listed in the "Deprecated APIs" page. Perhaps we need to signpost this better?

A

[bsipocz]

I've run into this, namely that import_module is not equivalent with import_object, in my case I'm importing a function rather than a module, and thus a former is failing into a ModuleNotFoundError

[timhoffm]

The replacement note is misleading. It’s not a full replacement, but only a starting point to build upon. AFAICS the list is autogenerated and does not allow for additional context information. In that case (and if there’s no undeprecation) it may be better to not state a replacement at all.

[mgeier]

Since there doesn't seem to be a replacement (apart from copying the whole implementation), I think it would be best to un-deprecate.

Apart from my original issue (spatialaudio/nbsphinx#819 (comment)), I've seen that this problem also appeared in executablebooks/MyST-NB#647 and felix-hilden/sphinx-codeautolink#149.

[AA-Turner]

My position remains as in November, but I will accept a PR to un-deprecate, if you or anyone else would submit one.

Ideally I would want to discourage use of the function, but I'm not sure what the best way to do that is.

A