Document the reason for first field always being a DeletionFlag #241
Description
Hello! I'm trying to port some code from using the GDAL library to pyshp, because it only needs to read shapefiles, and many things about GDAL are not very nice to deal with.
So I'm liking pyshp so far, but I'm confused why it explicitly prepends a DeletionFlag field to the start of its fields:
Line 1469 in d9f917a
...there are various comments in the source which allude to this, but don't explain why it is done, e.g.
- "by default, read all fields except the deletion flag, hence
"[1:]"" - "Note that this always includes the DeletionFlag at index 0, regardless of the 'fields' arg."
- "deletion flag field is always unpacked as first value (see __recordFmt)"
- "# drop deletion flag from values"
It's a bit confusing when porting from GDAL, because I can take the list of fields parsed from the same shapefile by GDAL and pyshp, and the following is true:
assert gdal_fields == pyshp_fields[1:]It even turns up in the README, in some code samples and a bugfix ("Fix Reader geo interface including DeletionFlag field in feature properties"):
https://github.com/GeospatialPython/pyshp/blob/d9f917a59a922c6981302f99fad8d94013bcf5cd/README.md
>>> r = shapefile.Reader('shapefiles/test/polygon')
>>> w = shapefile.Writer('shapefiles/test/copy')
>>> w.fields = r.fields[1:] # skip first deletion field
It seems like a sort of minor internal hack which is easy to work around, except that fields is exposed to the user, so the user has to deal with it too.
Can it be documented somewhere? :)