Skip to content

Use imports to collect (scoped) type information #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 23, 2025
Merged

Conversation

lagru
Copy link
Member

@lagru lagru commented Jul 17, 2025

Closes #20.

Adds support for collecting additional type information from existing imports in the parsed package. Also does quite a bit of internal refactoring and maintenance.

E.g. with this

import dogs
from calendar import January as Jan, Day

def last_day(m, d):
    """
    Parameters
    ----------
    m : Jan
    d : dogs.Bernese

    Returns
    -------
    day : Day
    """

will work out of the box. Jan or Day will be picked up as implicitly available symbols in the given module. dogs will be collected as an import prefix in the module. They won't be available in other modules that don't feature these import statements.

We could also make these available to be used in other modules but for now I think this more conservative approach should be a good trade-off. It should save users from having to specify a large number of types manually. And weird import choices or naming conflicts are guarded by the scoping.

However, calendar.January will be collected as a global type and can be used in other modules.

This makes it more apparent that a full reference on docstubs type inference would be good to have in the documentation.

Release note

Use import statements in the parsed package to collect additional type
information. This makes imported types available in the same module
scope to be used in docstrings. Some of the imports can be used package
wide even if not imported there. E.g. `from pathlib import Path` will
allow using "Path" inside the modules scope. Outside of that module, 
you must use the full `pathlib.Path` to reference that type.
{label="enhancement"}
Type nicknames specified in the configuration are now resolved recursively.
That means one nickname can point to another nickname.
{label="enhancement"}

@lagru lagru added this to the v0.4 milestone Jul 17, 2025
@lagru lagru added the enhancement New feature or request label Jul 17, 2025
@lagru lagru force-pushed the collect-from-imports branch 2 times, most recently from 3a3315a to 033d560 Compare July 22, 2025 20:05
@lagru lagru marked this pull request as draft July 22, 2025 20:06
lagru added 5 commits July 23, 2025 16:26
"from imports" are collected as types within the scope of the containing
module. E.g. "from pathlib import Path" will allow using "Path" inside
the modules scope.

"import" without "from" are collected as scoped type prefixes. Meaning
if a module contains "import scipy as sp", "sp." can be used as a valid
type prefix in that module.
And also improve the class representation and various other things.
`py_import` can already be imported manually in the module's namespace.
In which case `py_import` cannot be formatted as an import and shouldn't
be collected.
@lagru lagru force-pushed the collect-from-imports branch from 033d560 to 945b59e Compare July 23, 2025 15:34
@lagru lagru marked this pull request as ready for review July 23, 2025 15:40
@lagru lagru added the maintenance Keeps the lights on label Jul 23, 2025
@lagru lagru changed the title Collect "from imports" as referencable names for docstrings Use imports to collect (scoped) type information Jul 23, 2025
@lagru lagru merged commit d2a1dfd into main Jul 23, 2025
7 checks passed
@lagru lagru deleted the collect-from-imports branch July 23, 2025 22:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request maintenance Keeps the lights on
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Make a module's imports reference-able for doctypes?
1 participant