Support pyi files for local projects

[sausix]

I understand the purpose of pyi files:

• Provide type hinting for missing type hints in external packages
• Provide type hinting for wrapper interfaces to non native Python packages (compiled binaries)

But there's a third category which is not supported by pyright.
So now my own local project has "invisible code" which is resulting in missing type hints. I'm speaking of PySide/PyQt user interfaces which can also be loaded during runtime right from ".ui" files.

Here's a description of my tool that creates pyi stubs including reasons for this method: https://github.com/sausix/qtui2pyi

Having pyi files along py modules works fine in PyCharm. But I could not get pyi files be preferred in pyright. It does not work by having main.py and main.pyi in the same directory. Also doesn't work by having {"include": ["src"], "stubPath": "typings"}.

Can we have an option in pyright which loads pyi files prior to the corresponding py files?

Example usage with current warning:

# main.py
class MainWindow(BasicMainWindow):  # qtui: res/ui/main.ui
    def __init__(self):
        BasicMainWindow.__init__(self, "PY:/res/ui/main.ui")
        self.treeViewTools  # Pyright: Cannot access attribute "treeViewTools" for class "MainWindow*"
                            #   Attribute "treeViewTools" is unknown (reportAttributeAccessIssue)

# main.pyi (same directory or in /typings)
from PySide6.QtWidgets import QTreeView, QMainWindow

class MainWindow(QMainWindow):
    treeViewTools: QTreeView

Thank you!

[erictraut]

Stub files are always preferred over normal source files when resolving imports. This behavior is described by PEP 561 and mandated by the Python typing spec, and pyright is compliant with the spec.

It sounds like what you're asking for is to somehow "merge" the type information in a stub file with the type information in a corresponding source file, using the former to type check the latter? That's not what stub files were designed for. In general, that wouldn't be possible given the design of stubs. It's unlikely that pyright (or any other standards-compliant type checker) would support this feature. A stub is meant as a "stand-in" for a source file. It's not meant to somehow "augment" the type information in a source file.

[sausix]

So solution is I can't use pyright for this?

Can't pyright be ahead of PEP standards? Enabled by some config flag? Is my use case too rare?

That's not what stub files were designed for. In general, that wouldn't be possible given the design of stubs.

PyCharm does internally support pyi files next to the py files without complaints. The pyi syntax is spot on.

[erictraut]

Can't pyright be ahead of PEP standards?

I often implement new PEPs and changes to the typing spec when they're still in the draft phase. If you'd like to propose a new PEP or typing spec change, you're welcome to do so. I think it will be difficult for you to convince the broader typing community that stubs should be used in the manner you're suggesting here, but you can pitch it and see. Here is the process by which the typing spec can be amended.

[erictraut]

Is there a reason you don't just add type information directly to your code? Why do you want to replicate it in a separate stub file? If your tool is able to generate annotations in stubs, wouldn't it be better to have it insert annotations directly in the code? This is much more maintainable and gives both humans and coding agents valuable information they need to modify the code with confidence. That's the approach I'd recommend.

[sausix]

If you'd like to propose a new PEP or typing spec change

Thanks. I do Python for 10 years now and "soft" typing for the majority of that time now. But started strict typing just recently. While I consider having quite good Python skills today I'm not yet capable to propose a new PEP especially about typing. I could with the help of ChatGPT but that feels wrong.

I would first do a survey how others feel about this topic. I think most people compile their PySide/PyQt UIs to Python code. But I hate this method because it either bloats __init__ or instance attributes are defined outside of __init__, which is unpythonic. The Qt Designer at least outputs a bad implementation by default.
The UI definition module could be a base class. This is going into my notes now.

Is there a reason you don't just add type information directly to your code?

I did this years before like this:

self.tv: QTreeView = self.treeview

But that's obviously ugly.
In the last years PyCharm just worked with pyi files so recently I made the converter for this, which simply creates/overwrites a pyi file.

Modifying py files by a script is more dangerous for obvious reasons. Imports have to be made and a function have to hold some attribute typing.
Some definitons are often not needed. Like QLayouts. They would still bloat the module.

Until now I thought these definitions have to be in __init__. But this seems to be valid:

class MainWindow(MainWindowTreeView, BasicMainWindow):  # qtui: res/ui/main.ui
    def __init__(self):
        BasicMainWindow.__init__(self, "PY:/res/ui/main.ui")

        MainWindowTreeView.__init__(self, self.treeView)  # No warning!

    def _(self):  # Unused method
        # imports here may go here
        self.treeView: QTreeView

Haven't run linters and checkers on this example yet. That method is unused at least.
I could put the imports into this method too... But then it starts to be more ugly.

The pyi method would be clean. Simple, separated and effective. The type hints are not needed for external packages in general. So pyi files could be omitted for packaging.

[erictraut]

But that's obviously ugly.

I don't think this is at all obvious. This is subjective, but this approach looks great to me. It results in highly readable and self-documenting code.