papyri.utils:full_qual

Extended Summary

Unlike what we typically think of the fully qualified name of an object only comporting identifiers and dots(.) this uses a colon as the separator between the module part and the object's name and sub attributes.

This is to lift an ambiguity when trying to get an object back from its fully qualified name.

Assuming the following files, top level init imports a function from a submodule that has the same name as the submodule

# project/__init__.py
from .sub import sub

A submodule that define a class (here we use lowercase for the example

# project/sub.py

class sub:
    attribute:str

attribute = 'hello'

and a second submodule

# project/attribute.py

None

Using qualified names only with dots (.) Can make it difficult to find out which object we are referring, or at least implements the logic to get those object back.

For example, to get the object project.sub.attribute, one would import project and x = getattr(project, 'sub'), getattr(x, 'attribute').

Though because of the from .sub import sub, we end up getting the class attribute instead of the module.

This ambiguity is lifted with a : as we now explicitly know the module part. package.sub.attribute, package.sub:attribute. Note that package:sub.attribute is also non-ambiguous, even if not the right fully qualified name for an object.

Moreover, using : as a separator make the implementation much easier, as in the case of package.sub:attribute, it is possible to directly execute importlib.import_module('package.sub') to obtain a reference to the sub submodule, without try/except or recursive getattr checking the the type of an object.