Skip to content

reportPrivateImportUsage.md

Latest commit

 

History

History
48 lines (34 loc) · 3.17 KB

reportPrivateImportUsage.md

File metadata and controls

48 lines (34 loc) · 3.17 KB

Overview

reportPrivateImportUsage flags cases where imports from private modules or symbols are used in a way that exposes internal implementation details. This diagnostic helps enforce encapsulation and maintain a clean public API for your packages.

Representative Issues

  • #2943: Ensure that the use of '# type: ignore' comments is respected and correctly flagged by static analysis tools.
  • #3003: Ensure Pylint plugins are installed and configured, and VSCode parses their diagnostics into editor warnings.
  • #3102: Ensure that default argument types in functions match the annotated parameter types.
  • #4163: Ensure consistency in the use of type stubs between Pyright's CLI and Pylance settings.
  • #5200: Provide a configuration setting to allow users to customize diagnostic rule severities by type checking mode.
  • #7001: Prefer 'openFilesOnly' diagnostic mode for large projects.
  • #2277: Use alias imports to indicate public interface symbols in py.typed libraries.
  • #2639: Ensure symbols are explicitly re-exported if they should be part of the public API.
  • #8377: Invoke Pyright with the project root directory for correct import resolution.

Examples

Error:

# some_package is a py.typed library.
# Its __init__.py imports helper from _internal without re-exporting it.
from some_package import helper  # "helper" is not exported from "some_package"

In a py.typed package, symbols imported into __init__.py are considered private unless they appear in __all__ or are re-exported using the import X as X pattern.

Fix — use the public API or import from the declared source:

from some_package._internal import helper  # Import from the source module directly

Or ask the library maintainer to add helper to __all__ or re-export it explicitly.

Common Fixes & Workarounds

  1. Avoid importing private modules or symbols unless necessary.
  2. Use alias imports and explicit re-exports to clarify your package's public API.
  3. Configure your project to use the correct root directory for import resolution.
  4. Use strict type checking and configure directories as needed in your config files.
  5. Review the Pyright configuration documentation for details on configuring or disabling this diagnostic.

See Also