reportPrivateUsage.md

April 8, 2026 · View on GitHub

Overview

reportPrivateUsage flags cases where private variables or functions (those prefixed with an underscore) are accessed from outside their defining module or class. This diagnostic helps enforce encapsulation and prevent accidental use of private implementation details.

Representative Issues

  • #3102: Ensure that default argument types in functions match the annotated parameter types.
  • #3853: Configure Pylance's packageIndexDepths and ensure the correct Python environment for accurate auto-imports.
  • #3855: Enable Python indexing in VSCode settings for auto-imports.
  • #4163: Ensure consistency in the use of type stubs between Pyright's CLI and Pylance settings.
  • #495: Use the exclude property in Pyright's config to prevent analysis of unwanted folders.
  • #5200: Provide a configuration setting to allow users to customize diagnostic rule severities by type checking mode.
  • #5755: Avoid accessing functions with a leading underscore from other modules.
  • #6300: Exclude unnecessary folders like .venv to improve performance.
  • #7001: Prefer 'openFilesOnly' diagnostic mode for large projects.
  • #1443: Use comments to indicate strict type checking for new files and configure directories in pyrightconfig.json.
  • #1462: Always verify that configuration settings are respected by CLI tools.
  • #2277: Use alias imports to indicate public interface symbols in py.typed libraries.

Examples

# my_module.py
class MyClass:
    _internal_value = 42
    __private_value = "secret"

# other_module.py
from my_module import MyClass

obj = MyClass()
print(obj._internal_value)   # Warning: "_internal_value" is private
print(obj.__private_value)   # Warning: "__private_value" is private

Fix — use the public API or expose needed values:

class MyClass:
    _internal_value = 42

    @property
    def value(self) -> int:
        return self._internal_value  # Accessed through a public property

Common Fixes & Workarounds

  1. Avoid accessing private variables or functions from outside their defining module or class.
  2. Use alias imports to clarify public API symbols.
  3. Configure your project to exclude unnecessary folders from analysis.
  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