Possible to get --verifytypes to ignore script files in a library?

[Pyprohly]

I have some script files bundled in a library that are to be invoked through python3 -m. Is there a way to tell Pyright --verifytypes that these are script files (never to be imported) and shouldn’t be part of the --verifytypes check?

Or do you recommend that these script files be type complete too? Scripts tend to have lots of top levels variables.

[erictraut]

Do you include these scripts within the package of your library, or are the used only at build time? If they're build-only, I recommend excluding them from your package.

If these scripts need to be included within your library package, I recommend putting them in their own subdirectory that starts with an underscore, such as _scripts. This will tell type checkers that the files within this directory are not part of the library interface and are not meant to be imported by consumers of the library. The --verifytypes check will also ignore all files in that directory.

Does that address your needs?

[jakebailey]

Unless I'm mistaken, the scripts in questions are things like how you can do python -m http.server, and it runs a module as a script, not that they are build scripts.

I'm wondering if these could be done via __main__.py, and the type verifier just ignores these files as not-intended-to-be-imported. (If the script is in some other file like server.py with a __name__ check, then that could be a module or a script, so I can see us retaining our behavior there.)

[Pyprohly]

The scripts are command line utilities intended for users of the library. One of them is one that everyone needs to run to obtain an OAuth2 refresh token before the library can be used.

The underscore trick is indeed the behaviour that I want. However, it would be regrettable to have users need to invoke a script from an underscore directory.

An additional reason for not having type completeness in these scripts is that some of them double as examples of using some library functionality. Users may wonder why there are so many redundant type annotations all over the place if they see fully type complete code here. It would be like these scripts are trying to encourage everyone to achieve 100% type completeness in their own Python programs.
 

I’m using module-executable scripts, not (__main__.py) package scripts. For package executable scripts though, special casing the package executable __main__.py file seems very reasonable since importing directly from __main__.py, like __init__.py, is never recommended.

All my library’s script files are under a cli directory in the root. It doesn’t have an __init__.py. Maybe a rule suggestion could be that any modules in a directory that doesn’t have an __init__.py file should not be considered part of the public importable interface of the library.

It’s possible some library writers would like to put (module) script files in the root, or in other places that contain an __init__.py. I can’t think of why anyone would need this though.

[hmc-cs-mdrissi]

__init__.py based rules sound like a bad idea given namespace packages. Several libraries already struggle in weird ways with namespace packages. I'd rather avoid more rules of a folder being treated special in a new way based on __init__.py. I already have to do some config settings to guide mypy to understand my package structure and pytest just behaves weirdly on test uniqueness rule with namespace packages.

If we need exclusions my ideal solution would be marker files of untyped or py.typed having that info. The underscore trick is a bit curious to me as unsure it's documented in type peps or something different type checkers treat differently. The current py.typed file is kind of a minimal python config file.

Alternative solution is global type ignores. mypy has unique feature that a type ignore on the first line ignores the entire file fully. python/mypy#964

edit: From PEP 484

A # type: ignore comment on a line by itself at the top of a file, before any docstrings, imports, or other executable code, silences all errors in the file. Blank lines and other comments, such as shebang lines and coding cookies, may precede the # type: ignore comment.
I didn't realize that was actually in the pep.

[erictraut]

The important thing is that tools should not treat these scripts as part of your library's importable interface. It would be unfortunate if a smart editor were to suggest an auto-import completion suggestion of the form from foo.my_script import bar. To avoid this, a tool like pyright needs to be able to distinguish between "modules that represent your library's public interface contract" and modules that are outside of that interface (like samples, tests, other scripts).

Right now, the only mechanism that we have in place is a directory name that begins with an underscore.

I played around with the idea of augmenting the "py.typed" file to support additional metadata about the package, but my proposal received negative feedback from other members of the typing-sig and python-sig community, so I quickly abandoned it. It would have required a new PEP or an extension to PEP 561 to standardize the format of this metadata. I still think it's a reasonable approach, but given the earlier feedback, I think it's unlikely to gain sufficient support to become part of the standard.

We could consider other ways to demarcate modules that are not meant to be treated as importable, but that would need to go through the typing-sig to get agreement and ratification. I don't think that # type: ignore is a good solution because it already has other uses that are unrelated to marking a module as "not importable".

[Pyprohly]

I found a nice solution:

from . import _cli
sys.modules[__name__ + '.cli'] = _cli