pyshp-3.0.1 release is broken #367
Description
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.
Activity
JamesParrott commentedon Sep 27, 2025
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.typedto./src.I'd prefer to keep the single module format. Would things be fixed for you if
py.typedis deleted?dl1jbe commentedon Sep 29, 2025
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.
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 commentedon Sep 29, 2025
This requires introducing a large boilerplate
__init__.pysimply 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.typedmarker 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 commentedon Sep 29, 2025
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 commentedon Sep 30, 2025
Thanks for the explanation James.
JamesParrott commentedon Sep 30, 2025
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 commentedon Oct 10, 2025
I've created a few example branches, and started a discussion to gather feedback regarding refactoring #371 .