{"id":6288,"library":"types-pywin32","title":"Typing stubs for pywin32","description":"types-pywin32 is a type stub package providing static type annotations for the pywin32 library. It allows type checkers like Mypy or Pyright to analyze code that uses pywin32, enhancing code quality and developer experience by catching type-related errors before runtime. This version aims to provide accurate annotations for pywin32==311.*. As part of the typeshed project, it receives frequent, often daily, updates to ensure currency with underlying libraries and Python typing standards.","status":"active","version":"311.0.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","pywin32","windows","type-hints","typeshed","static-analysis"],"install":[{"cmd":"pip install types-pywin32","lang":"bash","label":"Install types-pywin32"}],"dependencies":[{"reason":"Runtime library for which these stubs provide type information.","package":"pywin32","optional":false},{"reason":"Common static type checker that utilizes these stubs.","package":"mypy","optional":true},{"reason":"Another common static type checker that utilizes these stubs.","package":"pyright","optional":true}],"imports":[{"note":"Type information for win32api is provided by types-pywin32 when a type checker is run.","symbol":"win32api","correct":"import win32api"},{"note":"Used for COM automation; types-pywin32 adds static type checking to these interactions.","symbol":"win32com.client","correct":"import win32com.client"},{"note":"Contains core Windows types; types-pywin32 provides their definitions for static analysis.","symbol":"pywintypes","correct":"import pywintypes"}],"quickstart":{"code":"import win32api\nimport win32con\nfrom typing import TYPE_CHECKING\nimport os\n\n# types-pywin32 provides type information for pywin32 modules like win32api.\n# It is not imported directly into your runtime code.\n# Its benefits are seen when running a static type checker (e.g., mypy, pyright).\n\n# Example 1: Getting a Windows system directory with type hint\nwindows_directory: str = win32api.GetWindowsDirectory()\nprint(f\"Windows Directory: {windows_directory}\")\n\n# Example 2: Using a constant from win32con and a function from win32api\n# The actual MessageBox call is commented out to prevent interactive prompts\n# during automated tests or in non-interactive environments.\n\nif TYPE_CHECKING:\n    # Type checkers will use the stubs for win32api.MessageBox here.\n    # In a real application, you'd ensure the function call arguments match\n    # the stub definitions provided by types-pywin32.\n    pass\nelse:\n    try:\n        # Example of a win32api call (commented out for quickstart execution)\n        # win32api.MessageBox(0, \"Hello from pywin32!\", \"Pywin32 Example\", win32con.MB_OK)\n        print(\"MessageBox call skipped in quickstart to avoid UI interaction.\")\n    except Exception as e:\n        print(f\"Could not display message box (expected if not on Windows or interactive): {e}\")\n\nprint(\"Static type checking for pywin32 is enhanced by types-pywin32.\")\n","lang":"python","description":"This quickstart demonstrates typical usage of `pywin32` and how `types-pywin32` silently provides type annotations for static analysis tools. You do not import `types-pywin32` directly; rather, its presence enables type checkers to understand the `pywin32` API."},"warnings":[{"fix":"Ensure the installed `types-pywin32` version matches the `pywin32` version you are using (e.g., `types-pywin32==311.*` for `pywin32==311.*`). Pin both dependencies in your project.","message":"Type stubs are versioned to align with specific `pywin32` major versions. If `pywin32` undergoes a major API change, `types-pywin32` will update to reflect the new API, potentially causing type-checking errors for code using older `pywin32` versions.","severity":"breaking","affected_versions":"All versions, especially across `pywin32` major releases"},{"fix":"After installing `pywin32`, run `python -m pywin32_postinstall -install` from an elevated command prompt outside of a virtual environment for global installs, or ensure proper environment setup for virtual environments or services. Verify `PATH` settings.","message":"The underlying `pywin32` library often requires a post-install script (`python -m pywin32_postinstall -install`) to register COM components and place DLLs. Failure to run this, especially in virtual environments or when running as a Windows Service, can lead to runtime errors even if `types-pywin32` is correctly installed.","severity":"gotcha","affected_versions":"All versions of pywin32, implicitly affecting types-pywin32 users."},{"fix":"Refer to the official `pywin32` documentation or typeshed for the exact expected parameter signature. If necessary, create a local stub override or contribute a fix to typeshed. Consider using positional arguments if keyword arguments are not recognized by the type checker.","message":"Some `pywin32` functions may exhibit incorrect parameter resolution or `reportCallIssue` warnings in type checkers (e.g., Pylance) due to stubs defining parameters as positional-only when they are commonly used as keyword arguments, or other discrepancies in stub definitions.","severity":"gotcha","affected_versions":"All versions of types-pywin32 (depends on specific function stub)."},{"fix":"Ensure correct `pywin32` installation, try reinstalling `pywin32`, manually running the `pywin32_postinstall` script, or testing with specific PyInstaller versions known to be compatible. Ensure the environment `PATH` is correctly configured.","message":"When bundling applications with tools like PyInstaller, users may encounter `win32ctypes.pywin32.pywintypes.error`. This typically indicates issues with the `pywin32` installation, version incompatibilities with PyInstaller, or incorrect PATH configurations for its DLLs.","severity":"gotcha","affected_versions":"All versions of pywin32, especially when used with PyInstaller."},{"fix":"This warning typically comes from the `pywin32` library itself and often does not impact functionality. Ensure you are using a recent version of `pywin32` and Python, as updates to `pywin32` may address this internally.","message":"Users might encounter `DeprecationWarning: getargs: The 'u' format is deprecated. Use 'U' instead` originating from `pywintypes.py` within `pywin32`. This indicates internal usage of an older Python C API format for Unicode, which has a newer, preferred alternative.","severity":"deprecated","affected_versions":"Older versions of Python with newer pywin32, or specific pywin32 builds."}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}