reportPrivateImportUsage error on public-looking symbol defined with relative import

[aripollak]

Describe the bug
Prefect defines a symbol with from .kubernetes import ECSRun in src/prefect/run_configs/__init__.py, but I get a reportPrivateImportUsage error from pyright when I have from prefect.run_configs import ECSRun in my application.

To Reproduce

• Install the latest prefect library with pip install prefect
• In test.py, write from prefect.run_configs import ECSRun
• Run pyright test.py

Expected behavior
My understanding from https://github.com/microsoft/pyright/blob/main/docs/typed-libraries.md#library-interface is that I should not be getting an error because this is an implicitly public symbol.

Screenshots or Code

/home/ari/test.py
  /home/ari/test.py:1:33 - error: "ECSRun" is not exported from module "prefect.run_configs"
    Import from "prefect.run_configs.ecs" instead (reportPrivateImportUsage)

VS Code extension or command-line
Commandline version 1.1.191

Additional context
Trying to fix these errors for prefect as a whole in PrefectHQ/prefect#5174, but this is confusing me.

[erictraut]

This is a "py.typed" library, so it is expected to follow the rules in this documentation: https://github.com/microsoft/pyright/blob/main/docs/typed-libraries.md#library-interface.

By default, an imported symbol is considered private (not re-exported). If the intent is to re-export the imported symbol, it needs to either be included in an __all__ list or use a redundant aliased import form from .ecs import ECSRun as ECSRun. The source file prefect/run_configs/__init__.py doesn't do any of these, so ECSRun is considered private.

I recommend filing a bug or a PR for this library. While you're waiting for a fix, you can disable the reportPrivateImageUsage check in pyright.

[zanieb]

Hey @erictraut

They're confused about this specific section from the linked documentation:

“from . import A” forms, symbol “A” is not private unless the name begins with an underscore. If a file init.py uses form “from .A import X”, symbol “A” is treated likewise.

I think this is intended to read :

... “from .A import X”, symbol “X” is treated likewise.

as symbol "A" is not exposed by the latter example.

Assuming that document is correct, these functions should be considered part of the public interface.

[erictraut]

The import statement from .ecs import ECSRun re-exports the symbol ecs, but it doesn't re-export ECSRun. That's consistent with what the document says. If the intent is to re-export ECSRun, you would need to use the statement from .ecs import ECSRun as ECSRun.

[zanieb]

Great, thanks for explaining! Would you be willing to update or accept an update that changes the language to clarify that? For example

... “from .A import X”, symbol “A” is treated likewise but symbol "X" is still private.

[aripollak]

If I may add my input here, I think the "likewise" might be the confusing part. What about:

"from .A import X", symbol "A" is treated as public but symbol "X" is still private.

assuming that is the correct interpretation.

[erictraut]

Thanks for the suggestions.

The word "likewise" was meant to avoid repeating the phrase "unless the name begins with an underscore", but I can see why it might lead to confusion.

The document intentionally doesn't use the term "public" (based on previous feedback).

I've attempted to take into account your feedback and improve the wording.

[zanieb]

Thanks a bunch! Appreciate your timely and considerate responses.