I thought this was #907, but I can't be sure.

It's not #907, no, that was an ordering thing which affected a very large stub (which went away, and even on the old version I reported it for didn't persist to the end of the analysis; only observed while debugging).

Need to check if we actually discover stubs next to the file. There is typeshed discovery and standard discovery for module stubs in <module_name>-stubs folder. You can also place stubs in a separate folder and add path to the folder to the python.analysis.typeshedPaths setting like in

https://github.com/python/mypy/wiki/Creating-Stubs-For-Python-Modules as well.

Actually, since you are using 3.6 is there any reason you don't want to annotate in the module source code?

@MikhailArkhipov I find the type annotation syntax very verbose and distracting and I dislike having to import from typing just for the type annotations. I prefer to write them into a special field in docstrings (in Python 2 format) where they are less distracting, and I've developed a utility that generates the stub file from these docstrings automatically. I trigger the utility whenever I save the source file so I can keep the code and the annotations close by.

@MikhailArkhipov I've created a typeshed folder in the same folder and moved the stub file there:

foo.py
typeshed/
  `- foo.pyi

And I've set:

python.analysis.typeshedPaths": [ "${workspaceFolder}/typeshed" ]
python.autoComplete.typeshedPaths": [ "${workspaceFolder}/typeshed" ]

But I couldn't make it work, still the same :(

@MikhailArkhipov Although the mypy document you've referred to doesn't mention stub files in the same directory, the documentation on readthedocs does (the first bullet under "Creating a stub"):

https://mypy.readthedocs.io/en/latest/stubs.html

"Write a stub file for the library (or an arbitrary module) and store it as a .pyi file in the same directory as the library module."

Am I misinterpreting something?

We should support having the pyi next to the file and provide info (#296), though I'm not sure how the merging works out in contexts where a function is needing info about itself from the stub; that might be the issue here.

@jakebailey I don't know how analysis works but could this sentence from PEP-484 be relevant?

"The type checker should have a configurable search path for stub files. If a stub file is found the type checker should not read the corresponding "real" module."

We aren't a type checker by that definition per se. We provide editor features; if we were to do exactly what that line says, then you'd never get any completion, references, docstrings, etc, for a file that happens to have a stub, since we would go "hey, there's a stub" and never read the real code. Instead, we analyze both and merge the data together.

Actually we do discover pyi next to the file, just not for the user code that we expect to have annotations instead. See MergeStub in ModuleWalker.