pyshp-3.0.1 release is broken

[dl1jbe]

The python ecosystem does not support of annotating a simple module as being 'typed'. That is only supported for packages,

see https://typing.python.org/en/latest/spec/distributing.html#packaging-type-information for details and especially the last two sentences of that chapter.

So please convert the shapefile.py module into a regular python package by moving the files into shapefile directory and adding an init.py file.

[JamesParrott]

Thanks for raising this Thomas, and thanks for the link. Sorry to hear a marker file is enough to break the release for you. You're quite right - I've probably got it wrong by adding py.typed to ./src.

I'd prefer to keep the single module format. Would things be fixed for you if py.typed is deleted?

[dl1jbe]

Thanks for the reply.
If you think about how the module file gets installed - directly into site-packages, like any other module only python library it is easy to understand why an 'py.typed' file causes problems. The only relation between your module file and py.typed would be a common package directory. Otherwise one module with a py.typed directly in site-packages gets interpreted as ALL module only file are py.typed.

I'd prefer to keep the single module format. Would things be fixed for you if py.typed is deleted?

Well, deleting the file would work but you would loose all positive aspects of the type hints.

May I ask what speaks against converting it into an module. It is easy to do and can be done without breaking any code using teh code.

[JamesParrott]

May I ask what speaks against converting it into an module.

This requires introducing a large boilerplate __init__.py simply to preserve importing everything at the package level, that would then become an defacto API that must also be maintained. PyShp's historically been a single file project. Over the years our existing users could've imported anything. Even if it's a dunder 'private' item, I see no reason to break someone's code, by not re-exporting it, to comply with an optional standard that is still under development.

There are tonnes of other benefits to introducing type hints (if there weren't, I wouldn't have spent all that time adding them). If the lack of a py.typed marker file means auto suggestions in IDEs no longer work, I'd say that's a rather short sighted design of whichever plug-in that is.

In the absense of an example of a compelling real world example of something that PyShp breaks, I'm happy to just be a little standards incomplete, or even non-compliant, and ignore that PEP's requirement that 10s of thousands of single module projects refactor. A marker file is a mostly harmless hack after all - signifying use of the type system really ought to supported by Python packaging system's project meta data these days.

[JamesParrott]

I'm persuaded PyShp shouldn't ship py.typed in our wheels, with the single file format. Thanks for the explanation re:
site-packages, I now see how PyShp 3 breaks type checking of mixed typed / non-typed environments.

[dl1jbe]

Thanks for the explanation James.

[JamesParrott]

You're welcome. I forgot to mention another obvious simple option - copy the entire file into __init__.py. I admit I'm mainly opposed to this for aesthetic reasons. It just wouldn't look right!

Maybe it's time for a refactor into more modules anyway. The Geodict stuff is distinct, and much of the Reader and Writer machinery is independent of eachother.

[JamesParrott]

I've created a few example branches, and started a discussion to gather feedback regarding refactoring #371 .