What is the correct way to import components? (aka pylance reportPrivateImportUsage error)

[anakin87]

Discussed in #9499

^{Originally posted by jantrienes June 5, 2025}
What is the correct way to import components like ChatPromptBuilder? Two ways can be found in the documentation:

# Option 1
from haystack.components.builders import ChatPromptBuilder

# Option 2
from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder

While both work fine, option 1 leads to following Pylance error:

"ChatPromptBuilder" is not exported from module "haystack.components.builders"
  Import from "haystack.components.builders.chat_prompt_builder" instead Pylance[reportPrivateImportUsage](https://github.com/microsoft/pylance-release/blob/main/docs/diagnostics/reportPrivateImportUsage.md)

If option 1 is valid, I guess haystack.components.builders should have exports as below.

if TYPE_CHECKING:
    from .answer_builder import AnswerBuilder as AnswerBuilder
    from .chat_prompt_builder import ChatPromptBuilder as ChatPromptBuilder
    from .prompt_builder import PromptBuilder as PromptBuilder

This would align with typing conventions and makes Pylance happy, but I am not familiar enough to say for sure.

Thanks!

[anakin87]

Both import options are correct and in an ideal world should not raise warnings/errors.

I also noticed the errors in Pylance and when running mypy --strict.

We should understand if the proposed solution works properly. If yes, I would adopt it.

[denisw]

I just hit this issue after updating to Haystack v2.14.x. The documentation heavily uses the shorter package names, so supporting them in type checkers is critical IMO.