mirror of
https://github.com/microsoft/pyright.git
synced 2024-08-17 03:40:44 +03:00
Made a few small improvements to documentation.
This commit is contained in:
parent
3661fe3d5e
commit
d3221ca343
@ -6,15 +6,15 @@ Type stubs are “.pyi” files that specify the public interface for a library.
|
||||
|
||||
Regardless of the search path, Pyright always attempts to resolve an import with a type stub (“.pyi”) file before falling back to a python source (“.py”) file. If a type stub cannot be located for an external import, that import will be treated as a “black box” for purposes of type analysis. Any symbols imported from these modules will be of type “Unknown”, and wildcard imports (of the form `from foo import *`) will not populate the module’s namespace with specific symbol names.
|
||||
|
||||
Why does Pyright not attempt to determine types from imported python sources? There are several reasons.
|
||||
Why does Pyright not attempt (by default) to determine types from imported python sources? There are several reasons.
|
||||
|
||||
1. Imported libraries can be quite large, so analyzing them would require significant time and computation.
|
||||
1. Imported libraries can be quite large, so analyzing them can require significant time and computation.
|
||||
2. Some libraries are thin shims on top of native (C++) libraries. Little or no type information would be inferable in these cases.
|
||||
3. Some libraries override Python’s default loader logic. Static analysis is not possible in these cases.
|
||||
4. Type information inferred from source files is often of low value because many types cannot be inferred correctly. Even if concrete types can be inferred, generic type definitions cannot.
|
||||
5. Type analysis would expose all symbols from an imported module, even those that are not meant to be exposed by the author. Unlike many other languages, Python offers no way of differentiating between a symbol that is meant to be exported and one that isn’t.
|
||||
|
||||
If you’re serious about static type checking for your Python source base, it’s highly recommended that you use type stub files for all external imports. If you are unable to find a type stub for a particular library, the recommended approach is to create a custom type stub file that defines the portion of that module’s interface used by your code. Hopefully, more library authors will provide type stub files in the future.
|
||||
If you’re serious about static type checking for your Python source base, it’s highly recommended that you use type stub files for all external imports. If you are unable to find a type stub for a particular library, the recommended approach is to create a custom type stub file that defines the portion of that module’s interface used by your code. More library authors have started to provide type stub files.
|
||||
|
||||
## Generating Type Stubs
|
||||
If you use only a few classes, methods or functions within a library, writing a type stub file by hand is feasible. For large libraries, this can become tedious and error-prone. Pyright can generate “draft” versions of type stub files for you.
|
||||
|
Loading…
Reference in New Issue
Block a user