applying "Import Conventions" to stubs-only vs all modules?

[carljm]

It seems like pyright, unlike mypy, applies https://typing.readthedocs.io/en/latest/spec/distributing.html#import-conventions only to imports from stub files. The current wording/structure in the typing spec suggests that this is intended to apply to all modules (It is a separate top-level header, not under the "stub files" header, and the text doesn't mention stub files).

I realize that these import conventions were only added to the spec relatively recently (python/typing#1815), though they previously were mentioned in other typing documentation. I'm not sure where the conventions originated.

Is it an intentional choice by pyright to apply these conventions only to stub files? Would pyright ever adopt mypy's behavior of applying these conventions to all modules?

[erictraut]

The rules that you're citing in the typing spec were originally written by me. They appeared first in the pyright documentation and were later incorporated into a typing document. This document was more recently used by rchen as a source for the typing spec addition that you cited above. These rules build upon precedent set by PEP 484 (the section on stubs).

Pyright applies these rules to both stubs and any module found within a library with a "py.typed" marker file. That's consistent with what the typing spec says (or at least what was intended). If you see a place where pyright is not applying these rules for modules found in a "py.typed" library, please let me know because I'd consider that a conformance issue and a bug.

I see what you mean about the wording/structure of the typing spec. The way it's currently structured, it's not clear that the "Import Conventions" subsection is meant to be a continuation of the previous subsection titled "Library interface (public and private symbols)". I think this is just a formatting issue, and it's something we should fix/clarify. We can probably do so by simply deleting the "Import Conventions" subheading. The intent was clearer in the original typing document; the subheading was added during the editing/feedback process for the typing spec PR.

I'll note that pyright is less strict when it comes to imports of internal modules (i.e. modules located within your project) or modules within libraries that are not marked "py.typed". Authors of these modules have not opted in to these stricter rules about "public" vs "private" symbols, and we got strong feedback from pylance users and library authors that they didn't want these rules to be strictly enforced in these cases. The typing spec is intentionally silent on whether these rules should be enforced for non-"py.typed" modules.

[carljm]

Thank you for the clarification! I had just tested pyright vs mypy with a couple local files in a directory, and it hadn't occurred to me that first-party vs third-party was the differentiating factor. That makes sense.

I think relying on sub-heading structure to clarify the intent of this section is probably easy to miss or mis-interpret regardless of the structure, so if we edit that part of the spec, I would suggest wording in the import conventions text itself explicitly clarifying to which modules it is intended to apply.