Refactoring PyShp to support py.typed marker file.

[JamesParrott]

Thomas (@dl1jbe) raised a great point (#367), that by adding py.typed, I broke typechecking for users using PyShp together with non-statically typed deps, so for now I've simply deleted py.typed (PyShp v3.0.2).

Other than not breaking our user's workflows, I have no strong opinions, just a mild preference for option C. But I wanted to gather everyone's thoughts about complying (or not) with the current typing system spec for distribution https://typing.python.org/en/latest/spec/distributing.html#packaging-type-information. In a nutshell, the spec states we must refactor from the single file module PyShp's always been, to a package.

1. Package maintainers who wish to support type checking of their code MUST add a marker file named py.typed to their package supporting typing. This marker applies recursively: if a top-level package includes it, all its sub-packages MUST support type checking as well.

2. This specification does not support distributing typing information as part of module-only distributions or single-file modules within namespace packages.

3. The single-file module should be refactored into a package and indicate that the package supports typing as described above.

This year, together with Mike (@mwtoews) , the repo was refactored already, from a flat layout to src format.

I believe this leaves us with the following options.

[JamesParrott]

Example branch demonstrating Option B): https://github.com/GeospatialPython/pyshp/tree/Option-B)-Trivial-single-file-package-(src/shapefile/__init__.py)

Example branch demonstrating possible Option C): https://github.com/GeospatialPython/pyshp/tree/Option-C)-Multiple-file-package-(src/shapefile/%7B__init__%2Creader%2Cwriter%2Cgeoson%2C.%7D.py)
Full disclosure: in Option C, to avoid recalculating all the paths to shapefiles in README.md but still get the tests to pass, I've dropped the legacy python shapefile.py doctest runner (the newer python test_shapefile.py one can still be supported, as can pytest of course). Running python test_shapefile.py in an editable install does the same thing as python shapefile.py.

[JamesParrott]

An alternative approach A) ii):

Keep the single file format (don't refactor), and let users who want to indicate typechecking should be done install pyshp[stubs]:

[project.optional-dependencies]

dev = ["pyshp[test]", "pre-commit", "ruff"]

test = ["pytest"]


stubs=["pyshp-stubs"]

4cf66d5

https://pypi.org/project/pyshp-stubs/ (I'm undertaking to maintain that, it's largely automatable, e.g. with stubgen).

[JamesParrott]

Implemented fix (shapefile-stubs/py.typed) and tested. v3.0.4 and PyShp-stubs 0.0.1