Add typing stubs

[lovetox]

No description provided.

[lovetox]

.pyi and py.typed are added to the source distribution, but i did not succeed in adding it to the wheel. Without shipping those two files this MR is not useful though.

I suspect this i a problem with the layout of this project, there is no proper module defined with a init.py. But thats just a guess.

[vergenzt]

Thank you for starting on this! ❤️

[lovetox]

pip install mypy
python -m mypy.stubtest gnupg
Success: no issues found in 1 module

[vsajip]

but i did not succeed in adding it to the wheel

Perhaps you should add them to MANIFEST.in, then try rebuilding.

[lovetox]

@vsajip this does not change anything, adding the file to manifest.in or setup.cfg includes them correctly in the source distribution. The problem is afterwards the files are not included in the wheel.

include_package_data = True is meant to fix that, but for some reason it does not.

if i now think about it, this makes sense. As you are not distributing a python package. A python package is defined as a folder with a __init__.py. Here we distribute a module, seems we cannot add additional data to distribute with a module.

[lovetox]

i tried with a src layout and everything worked fine, this is a very common way how packages are layout today

https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#using-a-src-layout

[vsajip]

i tried with a src layout and everything worked fine

It's a common layout nowadays, but it wasn't when this package was developed. There should be a way of doing it without forcing a src layout - what tool and invocation did you use to build the wheel?

[lovetox]

python -m build -s
python -m build -w

[lovetox]

As guessed, module only distributions cannot ship typing stubs see

https://peps.python.org/pep-0561/

This PEP does not support distributing typing information as part of module-only distributions or single-file modules within namespace packages.
The single-file module should be refactored into a package and indicate that the package supports typing as described above.

Module only distribution is a kind of legacy behavior, i don't think it has any benefits over distributing a proper package, its simply there for historic reasons.

let me know if you want to migrate to a package, i dont see any impact on users (python2 or python3) by such a step. The most impact it probably has would be on some helper scripts, or CI jobs which would need to be adapted.

[vsajip]

I don't especially want to move to a package just to add typing - it's a one-module package, anyway. I guess perhaps it's because py.typed is ambiguous when not in a package - it could apply to any number of modules in a given directory. Too bad they didn't think of something along the lines of XXX.py.typed (e.g. gnupg.py.typed in our case) when they designed this feature. Oh, well.

[vsajip]

But I appreciate your efforts in this direction. Thanks!

[vsajip]

By the way @lovetox , I don't agree with this statement of yours:

Module only distribution is a kind of legacy behavior, i don't think it has any benefits over distributing a proper package, its simply there for historic reasons.

There are many modules (not packages) both in the standard library and on PyPI. Do you have a source for your claim, or is it just your opinion? Modules (single .py files) are not just here for historical reasons, they are useful and as far as I know, here to stay.

[lovetox]

What i said is my opinion from my experiences over the years.

Python import resolution works in the way that it will load modules directly put into the site-package dir. This behavior will not change as far as i know. And as long as python does this, an installation frontend like pip can of course put a module there.

historic was maybe not the best chosen word, its not historic as in obsolete. Its historic because almost no project today will distribute only a single module.

All kind of packaging features will need a proper package (namespace packages, distributing non-py files, mark package as typed). A package is defined as a folder with an __init__.py, thats it.

These are not two competing ways of distributing a python module, its more like, either you have the most simple project possible then you can put your module into the site-packages dir or for everything else you need to put it into a subfolder (package).

Even the official tutorial distributes a single example module, and does this by using a package. https://packaging.python.org/en/latest/tutorials/packaging-projects/

Im not aware of any advantage distributing a single module vs a package. I don't think its more useful to distribute a single module vs a package. Useful for who? The user that installs via pypi? Why would they care about if your module is directly in the site-package dir or in a subfolder?

For me this is simply a decision of what i want to distribute, if i want to distribute more than a .py file, i simply need to put it into a subfolder (package), there are not more considerations you would need to do.

[vsajip]

Im not aware of any advantage distributing a single module vs a package. I don't think its more useful to distribute a single module vs a package.

As I see it, there is no advantage or disadvantage between packages and modules. When a piece of software becomes too unwieldy to manage in a single source file, I make a package. Because python-gnupg is just a wrapper over GPG, it's conceptually fairly simple and so a single module works well (and has done since its first release around 15 years ago).

[lovetox]

The advantage is that you can distribute non-py files with a package.
And thats whats necessary if you want a typed package.

A typed package makes the project vastly more useful to users

• It allows type checkers to catch bugs and errors
• It provides autocomplete functionality
• It makes the package more easy to use and attractive to users

And all that will hopefully lead to gnupg being used another 15 years.

If you still think that users profit more from the fact that after they install gnupg its a single file in their site-packages dir instead of a folder, then so be it, i tried my best to convince you.

In the event this does not convince you, you could still merge the pyi file, even if it is not distributed, people could still download it here from the project repository and add it to their own repositories. Type checkers can pick up typing stubs that are locally added to a project.

[vsajip]

The advantage is that you can distribute non-py files with a package.

Sure, I get that.

And thats whats necessary if you want a typed package.

Sure, but I'm not especially pushing for it. I'm not against typing per se - I'm just fine with Python being dynamically typed, and this project specifically doesn't have a lot of different types and complex APIs that would really benefit from type checks - though I can see the benefits in general. So I'm not against merging the .pyi, but I guess we should lose py.typed. (As I said earlier, admittedly with no experience of the issue, that using XXX.py.typed instead of py.typed could have supported module files, but that's a different discussion.) There should be some documentation added around "optional typing" telling people how to set it up and use it. Also, I presume pyright is just a third-party tool, right? I'm not sure we should necessarily assume everyone who uses this package will choose it.

Remember, you can contribute this change and move on. I expect it will lead to more maintenance for me (for, as I see it currently, not enough benefit) which is not welcome specifically because (a) I don't generally using typing in my projects, as I'm fine with dynamic typing and (b) I'm not sure the ecosystem around typing is mature enough yet. But that is no doubt because I haven't really gotten into it, because of (a).

[lovetox]

There is another option.

python allows it that a third party can provide stubs via a different package. The package needs to be named python-gnupg-stubs and published to pypi. This package would only ship the pyi files.

It would make most sense if you would create this project under your name. If you dont want to maintain it for now, i would offer to do that, you could simply add me as maintainer to this new project.

EDIT: I could also contribute the stubs to https://github.com/python/typeshed which is automatically pulled in by type checkers.

[lovetox]

I will try to get the stubs into typeshed, i opened a PR python/typeshed#13465

If you ever come around and include stubs in this package, a simple PR in typeshed can be done to mark the stubs obsolete.

So i close this PR for now.