feature: include explicit re-exports

[DetachHead]

Is your feature request related to a problem? Please describe.

in python, it's common give an import an alias of the same name to indicate to type checkers that it's an explicit re-export. see here

Modules and variables imported into the stub are not considered exported from the stub unless the import uses the import ... as ... form or the equivalent from ... import ... as ... form. (UPDATE: To clarify, the intention here is that only names imported using the form X as X will be exported, i.e. the name before and after as must be the same.)

note that it says stub files, but this documentation seems to have been written before it was common practice to have type annotations in your source code. type checkers such as pyright and mypy will report an error if the user imports a symbol from a module that it was not either defined in or "re-exported" in regardless of whether it's a stub file or not

for example:

# _private/foo.py

def foo():
    """this function is part of the public api"""
def bar():
    """this function is not"""

# public.py

# this is an explicit re-export, which means the user is supposed to import it from here
# instead of the private module
from _private.foo import foo as foo

# this is not an explicit re-export, indicating that it's only imported within this module to be used internally
from _private.foo import bar

# something_else.py

from public import foo # no error
from public import bar # error: this symbol is not explicitly re-exported from this module

Describe the solution you'd like

when a symbol from a private module is imported into a public module, it should appear in the rendered docs

Describe alternatives you've considered

Additional context

[pawamoy]

Hi @DetachHead, thanks for the feature request 🙂

I think you're interested in this extension: https://mkdocstrings.github.io/griffe/extensions/official/public-redundant-aliases/?

[pawamoy]

I'll also link to this issue just in case: #167 (linking re-exports instead of rendering them).

[DetachHead]

thanks, looks like that's exactly what i need! though i see it's only available for sponsors and i'd rather not complicate my project's build process with a privately hosted dependency.

though i'm still happy to sponsor you and just wait until it's ready for a public release if you have any idea when that'll be. if not, no worries if you intend to keep it sponsors only

[pawamoy]

I don't have a precise date but it should soon become available to everyone for free. In the meantime, a more robust convention is to declare your re-exports with __all__ (which is visible at runtime too, contrary to redundant aliases) 😄

[pawamoy]

Since there's already an extension fulfilling your use-case, and we're just waiting for it to become free, I think we can say there's nothing actionable here and I'll therefore close the issue 🙂 Feel free to comment further of course!