How to configure custom stubs and custom typeshed

[hunterhogan]

First, there is an open issue related to my questions, #7308, but I am sure there are some other things I don't understand.

General environment and settings--probably not important

VS Code and Pylance

Version: 1.103.0-insider (user setup)
Commit: c915ea118358deb3dc6b18d3ad079e03adbe8d14
Date: 2025-07-29T18:32:35.175Z
Electron: 37.2.3
ElectronBuildId: 12035395
Chromium: 138.0.7204.100
Node.js: 22.17.0
V8: 13.8.500258-electron.0
OS: Windows_NT x64 10.0.26100

Identifier
ms-python.vscode-pylance
Version
2025.7.1
Last Updated
2025-07-24, 19:14:26

I always update the app and extensions.

I'll use https://github.com/hunterhogan/hunterMakesPy as an example. I never put Pyright, Pylance, or other linting rules in pyproject.toml or any other file in a repo.

Details

[project]
name = "hunterMakesPy"
version = "0.2.1"
description = "Easy Python functions making making functional Python functions easier."
readme = "README.md"
requires-python = ">=3.11"
license = { 'text' = "CC-BY-NC-4.0" }
authors = [{ name = "Hunter Hogan", email = "HunterHogan@pm.me" }]
keywords = [
  "attribute loading",
  "concurrency limit",
  "configuration",
  "defensive programming",
  "dictionary merging",
  "directory creation",
  "dynamic import",
  "error propagation",
  "file system utilities",
  "input validation",
  "integer parsing",
  "module loading",
  "nested data structures",
  "package settings",
  "parameter validation",
  "pytest",
  "string extraction",
  "test utilities",
]
classifiers = [
  "Development Status :: 4 - Beta",
  "Environment :: Console",
  "Framework :: Pytest",
  "Intended Audience :: Developers",
  "Intended Audience :: End Users/Desktop",
  "Intended Audience :: Other Audience",
  "Natural Language :: English",
  "Operating System :: OS Independent",
  "Programming Language :: Python",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Programming Language :: Python :: Implementation :: CPython",
  "Topic :: Software Development :: Libraries :: Python Modules",
  "Topic :: Utilities",
  "Typing :: Typed",
]
urls = { Donate = "https://www.patreon.com/integrated", Homepage = "https://github.com/hunterhogan/hunterMakesPy", Issues = "https://github.com/hunterhogan/hunterMakesPy/issues", Repository = "https://github.com/hunterhogan/hunterMakesPy" }
dependencies = [
  "charset_normalizer",
  "more_itertools",
  "numpy",
  "python_minifier; python_version < '3.14'",
]
optional-dependencies = { development = [
  "mypy",
  "pyupgrade",
  "setuptools-scm",
], testing = [
  "pytest",
  "pytest-cov",
  "pytest-xdist",
] }

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[tool.coverage]
report = { exclude_lines = [
  "if TYPE_CHECKING:",
  "if __name__ == \"__main__\":",
], ignore_errors = false }
run = { branch = true, concurrency = [
  "multiprocessing",
], data_file = "tests/coverage/.coverage", omit = [
  "tests/*",
  "hunterMakesPy/tests/*",
  "hunterMakesPy/pytestForYourUse.py",
], parallel = true, source = [
  ".",
] }

[tool.pytest.ini_options]
addopts = ["--color=auto"]
log_auto_indent = true
testpaths = ["hunterMakesPy/tests"]

[tool.setuptools]
package-data = { "*" = ["py.typed"] }
packages = { find = {  } }

[tool.updateCitation]
filenameCitationDOTcff = "CITATION.cff"
pathFilenameCitationSSOT = "citations/CITATION.cff"

Repo .vscode/settings.json

{
    "python.testing.pytestArgs": [
        "hunterMakesPy/tests"
    ],
    "python.testing.unittestEnabled": false,
    "python.testing.pytestEnabled": true
}

How I try to configure stubs and typeshed

VS Code settings

I think these are all relevant settings:

    "python.analysis.stubPath": "C:\\apps\\stubFileNotFound\\stubs",
    "python.analysis.typeshedPaths": [
        "typings",
        "/apps/stubFileNotFound/stubs",
        "/apps/stubFileNotFound/stubs/stdlib",
        "/mnt/c/apps/stubFileNotFound/stubs",
        "/mnt/c/apps/stubFileNotFound/stubs/stdlib",
        "/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance*/dist/typeshed-fallback/stubs",
        "/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance*/dist/typeshed-fallback/stubs/stdlib",
        "/mnt/c/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance*/dist/typeshed-fallback/stubs",
        "/mnt/c/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance*/dist/typeshed-fallback/stubs/stdlib"
    ],

All settings

{
    "[python]": {
        "diffEditor.ignoreTrimWhitespace": true
    },
    "[toml]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 2
    },
    "@azure.argTenant": "",
    "chat.mcp.serverSampling": {
        "Global in Code - Insiders: microsoft.docs.mcp": {
            "allowedModels": [
                "github.copilot-chat/gpt-4.1",
                "github.copilot-chat/claude-sonnet-4"
            ]
        }
    },
    "chat.tools.autoApprove": true,
    "cmake.additionalCompilerSearchDirs": [
        "C:/msys64/mingw32/bin",
        "C:/msys64/mingw64/bin",
        "C:/msys64/clang32/bin",
        "C:/msys64/clang64/bin",
        "C:/msys64/clangarm64/bin",
        "C:/msys64/ucrt64/bin"
    ],
    "cSpell.customDictionaries": {
        "custom": true, // Enable the `custom` dictionary
        "internal-terms": false, // Disable the `internal-terms` dictionary
        "project-words": {
            "addWords": true,
            "description": "Words used in this workspace.",
            "name": "project-words",
            "path": "${workspaceFolder}/.vscode/code-spell-dictionary-workspace.txt"
        },
        "user-words": {
            "addWords": true,
            "description": "Words used by this user profile.",
            "name": "user-words",
            "path": "${env:APPDATA}/Code Spell Checker/code-spell-dictionary-user.txt"
        }
    },
    "cSpell.maxNumberOfProblems": 1000,
    "dataWrangler.useRelativePath": true,
    "diffEditor.ignoreTrimWhitespace": true,
    "editor.bracketPairColorization.independentColorPoolPerBracketType": true,
    "editor.codeActionsOnSave": {
        "source.organizeImports": "always"
    },
    "editor.cursorSurroundingLines": 5,
    "editor.emptySelectionClipboard": false,
    "editor.find.seedSearchStringFromSelection": "selection",
    "editor.fontFamily": "Fira Code, Consolas, 'Courier New', monospace",
    "editor.guides.bracketPairs": "active",
    "editor.guides.highlightActiveIndentation": false,
    "editor.guides.indentation": false,
    "editor.hover.above": false,
    "editor.hover.delay": 400,
    "editor.inlayHints.fontFamily": "InputMonoCompressed-Thin",
    "editor.inlayHints.padding": true,
    "editor.matchBrackets": "never",
    "editor.minimap.enabled": false,
    "editor.occurrencesHighlight": "multiFile",
    "files.autoSave": "afterDelay",
    "files.defaultLanguage": "${activeEditorLanguage}",
    "files.dialog.defaultPath": "C:\\apps",
    "files.trimTrailingWhitespace": true,
    "git.autofetch": "all",
    "git.confirmSync": false,
    "git.openRepositoryInParentFolders": "never",
    "git.path": "C:\\Program Files\\Git\\cmd\\git.exe",
    "git.postCommitCommand": "sync",
    "github.copilot.chat.agent.thinkingTool": true,
    "github.copilot.chat.codeGeneration.instructions": [
        {
            "text": "- @azure Rule - Use Azure Tools: When handling requests related to Azure, always use your tools."
        },
        {
            "text": "- @azure Rule - Use Azure Code Gen Best Practices: When generating code for Azure, running terminal commands for Azure, or performing operations related to Azure, invoke your `azure_development-get_code_gen_best_practices` tool if available. Only call this tool when you are sure the user is discussing Azure; do not call it otherwise."
        },
        {
            "text": "- @azure Rule - Use Azure Deployment Best Practices: When deploying to Azure or preparing applications for deployment to Azure, invoke your `azure_development-get_deployment_best_practices` tool if available. Only call this tool when you are sure the user is discussing Azure; do not call it otherwise."
        },
        {
            "text": "- @azure Rule - Use Azure Functions Code Gen Best Practices: When generating code for Azure Functions or performing operations related to Azure Functions, invoke your `bestpractices_azurefunctions_get-code-generation` tool if available. Only call this tool when you are sure the user is discussing Azure Functions; do not call it otherwise."
        },
        {
            "text": "- @azure Rule - Use Azure Functions Deployment Best Practices: When deploying Azure Functions apps to Azure or preparing for the deployment, invoke your `bestpractices_azurefunctions_get-deployment` tool if available. Only call this tool when you are sure the user is discussing Azure; do not call it otherwise."
        },
        {
            "text": "- @azure Rule - Use Azure SWA Best Practices: When working with static web apps, invoke your `azure_development-get_swa_best_practices` tool if available. Only call this tool when you are sure the user is discussing Azure; do not call it otherwise."
        }
    ],
    "github.copilot.chat.codeGeneration.useInstructionFiles": true,
    "github.copilot.chat.codesearch.enabled": true,
    "github.copilot.enable": {
        "*": true,
        "jsonc": false,
        "markdown": false,
        "plaintext": false,
        "python": true,
        "scminput": false
    },
    "github.copilot.nextEditSuggestions.enabled": true,
    "githubPullRequests.codingAgent.uiIntegration": true,
    "githubPullRequests.pullBranch": "never",
    "githubPullRequests.remotes": [
        "origin",
        "upstream",
        "github"
    ],
    "indentRainbow.indicatorStyle": "light",
    "indentRainbow.lightIndicatorStyleLineWidth": 5,
    "indentRainbow.updateDelay": 200,
    "isort.args": [
        "--multi-line",
        "4",
        "--skip",
        "__init__.py",
        "--line-length",
        "120",
        "--no-sections",
        "--use-parentheses",
        "--lines-between-types",
        "0",
        "--indent",
        "\t",
        "--from-first",
        "--force-alphabetical-sort-within-sections",
        "--honor-noqa",
        "--lines-after-imports",
        "1",
        "--combine-as"
    ],
    "isort.check": true,
    "isort.severity": {
        "E": "Information"
    },
    "jupyter.askForKernelRestart": false,
    "mypy-type-checker.args": [
        "--strict"
    ],
    "problems.visibility": true,
    "python-envs.terminal.showActivateButton": true,
    "python.analysis.autoFormatStrings": true,
    "python.analysis.diagnosticSeverityOverrides": {
        "reportConstantRedefinition": false,
        "reportInvalidTypeVarUse": false,
        "reportPrivateUsage": false,
        "reportUnnecessaryIsInstance": false,
        "reportUnusedClass": "information",
        "reportUnusedFunction": "information",
        "reportUnusedImport": "information",
        "reportUnusedVariable": "information"
    },
    "python.analysis.enableTroubleshootMissingImports": true,
    "python.analysis.exclude": [
        "**/__pycache__",
        "**/.*",
        "**/typings",
        "**\\Python*\\Lib\\**",
        "**/typeshed-fallback",
        "${workspaceFolder}/typings"
    ],
    "python.analysis.generateWithTypeAnnotation": true,
    "python.analysis.include": [
        "."
    ],
    "python.analysis.includeAliasesFromUserFiles": true,
    "python.analysis.inlayHints.functionReturnTypes": true,
    "python.analysis.inlayHints.pytestParameters": true,
    "python.analysis.inlayHints.variableTypes": true,
    "python.analysis.packageIndexDepths": [
        {
            "depth": 200,
            "includeAllSymbols": true,
            "name": "matplotlib"
        },
        {
            "depth": 200,
            "includeAllSymbols": true,
            "name": "numpy"
        },
        {
            "depth": 10,
            "includeAllSymbols": true,
            "name": "pandas"
        },
        {
            "depth": 200,
            "includeAllSymbols": true,
            "name": "scipy"
        },
        {
            "depth": 20,
            "name": "soundfile"
        },
        {
            "depth": 20,
            "name": "stdlib"
        },
        {
            "depth": 20,
            "name": "toolz"
        },
    ],
    "python.analysis.stubPath": "C:\\apps\\stubFileNotFound\\stubs",
    "python.analysis.typeCheckingMode": "strict",
    "python.analysis.typeEvaluation.deprecateTypingAliases": true,
    "python.analysis.typeEvaluation.disableBytesTypePromotions": true,
    "python.analysis.typeEvaluation.enableTypeIgnoreComments": false,
    "python.analysis.typeEvaluation.strictListInference": true,
    "python.analysis.typeEvaluation.strictSetInference": true,
    "python.analysis.typeshedPaths": [
        "typings",
        "/apps/stubFileNotFound/stubs",
        "/apps/stubFileNotFound/stubs/stdlib",
        "/mnt/c/apps/stubFileNotFound/stubs",
        "/mnt/c/apps/stubFileNotFound/stubs/stdlib",
        "/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance*/dist/typeshed-fallback/stubs",
        "/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance*/dist/typeshed-fallback/stubs/stdlib",
        "/mnt/c/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance*/dist/typeshed-fallback/stubs",
        "/mnt/c/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance*/dist/typeshed-fallback/stubs/stdlib"
    ],
    "python.analysis.usePullDiagnostics": true,
    "python.analysis.userFileIndexingLimit": -1,
    "python.defaultInterpreterPath": "c:\\Users\\hunte\\AppData\\Local\\Programs\\Python\\Python314\\python.exe",
    "python.experiments.optInto": [
        "pythonDiscoveryUsingWorkers",
        "pythonPromptNewToolsExt",
        "pythonTestAdapter"
    ],
    "python.experiments.optOutFrom": [
        "pythonSurveyNotification"
    ],
    "python.interpreter.infoVisibility": "always",
    "python.REPL.sendToNativeREPL": true,
    "python.terminal.shellIntegration.enabled": true,
    "python.useEnvironmentsExtension": true,
    "redhat.telemetry.enabled": false,
    "remote.SSH.remotePlatform": {
        "mapFoldingVM": "linux"
    },
    "remove-empty-lines.allowedNumberOfEmptyLines": 1,
    "rewrap.wrappingColumn": 130,
    "ruff.configurationPreference": "filesystemFirst",
    "ruff.exclude": [
        "*.ipynb"
    ],
    "ruff.lineLength": 320,
    "ruff.organizeImports": false,
    "search.maxResults": 200,
    "security.workspace.trust.untrustedFiles": "open",
    "sortLines.filterBlankLines": true,
    "sortLines.ignoreUnselectedLastLine": true,
    "telemetry.telemetryLevel": "off",
    "terminal.integrated.defaultProfile.windows": "Command Prompt",
    "terminal.integrated.enablePersistentSessions": false,
    "terminal.integrated.fontLigatures.enabled": true,
    "terminal.integrated.scrollback": 3000,
    "terminal.integrated.shellIntegration.history": 1000,
    "window.newWindowDimensions": "inherit",
    "window.newWindowProfile": "Default",
    "window.restoreWindows": "preserve",
    "workbench.colorCustomizations": {
        "editor.foldBackground": "#2a2d2e7c",
        "editor.lineHighlightBackground": "#1e3f612a"
    },
    "workbench.editorAssociations": {
        "*.copilotmd": "vscode.markdown.preview.editor",
        "file:/**/*.parquet": "jupyter-data-wrangler"
    },
    "workbench.iconTheme": "material-icon-theme",
    "workbench.navigationControl.enabled": false,
    "workbench.productIconTheme": "material-product-icons"
}

File locations

My repo, https://github.com/hunterhogan/stubFileNotFound, is cloned to C:\apps (aka /apps, aka /mnt/c/apps).

The stdlib files are physically in /apps/stubFileNotFound/stubs/stdlib. Stub files for other packages are physically in /apps/stubFileNotFound/stubs.

Furthermore, I have a symlink named "typings".

(.venv) C:\apps\hunterMakesPy>dir /ad
 Volume in drive C has no label.
 Volume Serial Number is EE8F-7C8C

 Directory of C:\apps\hunterMakesPy

07/29/2025  11:40 PM    <DIR>          .
07/26/2025  01:49 PM    <DIR>          ..
07/14/2025  09:48 PM    <DIR>          .314
07/29/2025  11:40 PM    <DIR>          .git
07/12/2025  02:59 PM    <DIR>          .github
07/05/2025  10:47 PM    <DIR>          .pytest_cache
07/06/2025  10:21 PM    <DIR>          .venv
07/05/2025  10:46 PM    <DIR>          .vscode
07/29/2025  11:40 PM    <DIR>          citations
07/14/2025  11:28 PM    <DIR>          hunterMakesPy
07/14/2025  09:48 PM    <DIR>          hunterMakesPy.egg-info
07/15/2025  12:22 AM    <DIR>          tests
06/29/2025  07:12 PM    <SYMLINKD>     typings [\apps\stubFileNotFound\stubs]

But something isn't right

Imagine I am looking at one of my Python files in my repo. Imagine a variable is of type networkx.classes.digraph.DiGraph, and I choose "Go to Definition." VS Code will usually take me to my stub file, which is great.

DiGraph subclasses networkx.classes.graph.Graph, so imagine I choose "Go to Definition" for Graph. VS Code will almost always take me to ".venv\Lib\site-packages\networkx\classes\graph.py" instead of taking me to my stub file.

So what? Well, here is the really weird thing: when I am in the stub file, Pylance will show me diagnostic errors in the stub file based on the information in the installed .py file instead of using the stub file. But, Pylance does not show me incorrect diagnostic errors in my files.

😖 😞

My explanation failed. Everything fell apart in the last paragraph. idk. if I figure out how to improve this, I'll add more.