twisted.logger.extractField() has return type typing.Any, but in the output this is not linked to the standard library documentation, despite the intersphinx inventory being available and other types being linked successfully.

What I think is happening here is that extractField() is implemented in twisted.logger._flatten, which imports Any from the typing module in the standard library. However, by the time the link is resolved, the extractField() has been moved into the twisted.logger module, it's public location. But this module does not import Any, so the lookup fails.

Note that doing the lookup before the move isn't correct either: when we link to other objects that get moved around, that link would be broken after the move. A similar problem occurs if we'd keep a reference to the original parent location and attempt to do a lookup there after all moves have happened, since the target would have been moved away then. I think the only way to do it correctly is to look up the target Documentable in a code model that reflects the actual source and when presenting ask that Documentable where in the output it resides and link there.

In an earlier discussion of problems related to cyclic imports, I wrote:

As for a long term solution, I'm starting to think that reparenting is a bad idea: it means we lose information about how the code is structured. Instead of altering the code model, we could create layer on top of it that contains the documentation structure. That would also allow us to thin down the interface of the model classes a bit, by moving presentation data out of the code model.

Linking annotations containing imported names would then work as follows:

• look up the original code object in the same way Python does (trace it back recursively to source location)
• look up where the code object ended up in the documentation layer (might not match source location if name was re-exported)
• link to the documentation location

@adiroiban replied:

+1 yes. I think that we should always have a layer with the true structure.. and with that we can have a public API layer which does it best to remove duplicates and present the doc links using "canonical" paths.

I think that's a good way to look at it: objects have an implementation location, being the source file they're defined in, and a public API location, which is where the user will read about them in the documentation and import them from.

There are more issues related to reparenting, for example #184, in which the same name is re-exported in more than one location. So the mapping between implementation layer and public API layer might not be 1:1.