From d3221ca343f8b04cb13f3eeae05520033508270e Mon Sep 17 00:00:00 2001 From: Eric Traut Date: Mon, 17 Feb 2020 01:16:30 -0700 Subject: [PATCH] Made a few small improvements to documentation. --- docs/type-stubs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/type-stubs.md b/docs/type-stubs.md index c77d63462..b3c5b733f 100644 --- a/docs/type-stubs.md +++ b/docs/type-stubs.md @@ -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.