Strict Setting for Return Types

[hmc-cs-mdrissi]

Is your feature request related to a problem? Please describe.
Can we have a config option for a library to require return type annotations? So that code like,

def f(x: int):
  return x

is an error on strict for missing return type.

Describe the solution you'd like
A configuration setting for missing return type annotations. May optionally be included in strict.

Additional context
While pyright can infer return types, I would like return type for explicitness/documentation and also to be friendly to other type checkers. Also inferred return type may be valid but not intended one by the author.

It would also make strict check vs verifytypes more similar. verifytypes rightly detects missing return types, but I'd rather not run verifytypes for every pre-commit/ci check while running pyright there is fine to me.

[erictraut]

I presume you mean emitting an error in the library source file. Pyright doesn't emit errors for library code when analyzing code that consumes libraries. It emits errors only for files that it has been asked to type check.

If you want an error emitted at the call site, there's already a set of options that covers this case. Set useTypesFromLibraryCode to false (which the default value for this setting in pyright). Then turn on strict type checking options. This will disable type inference for library code, so return types will be evaluated as Unknown, and any use of an Unknown will be flagged by the strict type checking options.

[hmc-cs-mdrissi]

I mean for my own code/files that pyright checks. I'm calling it a library since I mainly work on code for others to use as a library. Sorry for making that confusing. If I make a file foo.py with contents,

def f(x: int):
  return x

and run pyright foo.py then I get no errors even on strict mode. So I want files I ask pyright to type check are annotated with return types. I agree that errors from libraries my code uses should not be shown.

[erictraut]

In cases where the function type can be inferred, there's no reason to provide a return type annotation unless the function is part of a library's public interface. In that case, the return type should be explicitly annotated. That can already be checked with the "pyright --verifytypes" command. Outside of the "--verifytypes" command, there's no way for pyright to know whether any particular function or method is public, and I don't think it makes sense to provide a setting that requires return type annotations for internal functions and methods.

[hmc-cs-mdrissi]

I'd be happy with just a rule for all functions. My primary reasons for using types are readability and detection of errors. My goal for return types is clarity/documentation to other people working in the codebase. I find return types help readability. So I want private functions to have return types. Also if we want our codebase to mypy strict check, mypy has no inference of return types and this is largest inconsistency between strict mypy vs pyright errors. We're currently leaning to drop mypy for other reasons and just use pyright for other reasons but will miss having return types documented.

If you'd prefer a public interface rule a simple one would be underscore convention. I don't think it's necessary to distinguish though if this an optional strict rule. The simplest rule of all functions have return types would be easier and fit happily for me.

As for verifytypes, verifytypes does not show errors while using pylance. I mostly fix type errors by relying on pylance to show me them and use pyright for CI/debugging.

[erictraut]

We wouldn't be able to include such a feature in the general "strict" category, so it would likely go undiscovered and unused by pretty much everyone but you. We generally don't add new features that are so specific that only a handful of pyright users want them.

I'm going to close this for now. We might reconsider the decision in the future if we receive signal of interest from other users in the form of upvotes (thumbs up).

[sawaca96]

@erictraut Can you re-open this issue? I think this option is required

[erictraut]

@sawaca96, I'm going to leave the issue closed for now. The issue has received some thumbs up but not enough to justify adding it. We may revisit this in the future if there is sufficient interest, but I'm still unconvinced that this is a good feature to add for all of the reasons I mentioned above.

[erictraut]

I think this issue has received enough upvotes for us to open it up for discussion again.

I'm still not 100% convinced that we should include such a feature. To summarize the arguments against adding this:

1. If we add the feature, it will be off by default, even in strict mode, so it will likely be discovered and used by a very small percentage of pyright and pylance users.
2. It will do little or nothing to catch bugs in your code that are not already caught by pyright today. It effectively just creates a bunch of extra unnecessary work for little or no benefit.
3. Inferred return types already appear in hover text and signature help.
4. Pylance also recently added support for "inlayed" type annotations, so the inferred return types appear within the code.

The arguments I've heard in favor of this feature:

1. Mypy doesn't provide return type inference, so return type annotations are always needed for mypy. This sounds to me like a problem in mypy, not in pyright ;). If you run mypy in addition to pyright, you can ask mypy to report missing return type annotations, right?
2. For library authors who use "--verifytypes", this command requires that all public functions and methods (other than __init__) have explicit return types, and it would be useful for pyright to report a similar error when used in interactive editing mode. The problem with this argument is that when pyright is used in normal mode, it can't tell what functions make up the public interface for a library. So consistency here isn't possible.
3. Inferred return types might be accurate but not what was intended by the author. I think this is the strongest argument in favor of this feature, but it's still pretty weak IMO. Authors can always override the inferred type by adding an (optional) return type annotation. This is consistent with how variable type annotations work.

I'm interested in hearing from those of you who upvoted this feature. How and why would you use it?

[hmc-cs-mdrissi]

There is 4th reason,

4. Useful as documentation to others reading the code and in generated documentation that extract type hints. Sphinx-autodoc-typehints is one tool that can generate api documentation including type signatures it finds.

With your three that does cover all my reasons.

The recent support for inlayed type hints and adding them definitely helps and lowers my want for this.

I am a bit confused by 2. Why can’t single file mode recognize public interface? Is rule more complex then leading underscore functions are private?

[erictraut]

The rule for "what is the public interface" is a bit more complicated, at least for modules whose names start with an underscore or are located within a directory whose name starts with an underscore. In those cases, it's necessary to understand whether that symbol is imported and re-exported from a publicly-visible module. The --verifytypes logic performs this cross-module analysis.

[erictraut]

After further deliberation and discussion with the pylance team, we've concluded that this feature is not sufficiently compelling for the reasons discussed above. As such, I'm going to close it again.

The Pylance team is planning to add a "fix all" code action that adds explicit return types for all functions and methods within a file based on inferred types.