Passes doctests (adjusted to reflect new API: Field, BBox, ZBox & MBox)

Author: JamesParrott

README.md

@@ -406,7 +406,7 @@ and the bounding box area the shapefile covers:
 	>>> len(sf)
 	663
 	>>> sf.bbox
-	(-122.515048, 37.652916, -122.327622, 37.863433)
+	BBox(xmin=-122.515048, ymin=37.652916, xmax=-122.327622, ymax=37.863433)
 
 Finally, if you would prefer to work with the entire shapefile in a different
 format, you can convert all of it to a GeoJSON dictionary, although you may lose
@@ -553,45 +553,34 @@ in the shp geometry file and the dbf attribute file.
 
 The field names of a shapefile are available as soon as you read a shapefile.
 You can call the "fields" attribute of the shapefile as a Python list. Each
-field is a Python tuple with the following information:
+field is a Python namedtuple (Field) with the following information:
 
-  * Field name: the name describing the data at this column index.
-  * Field type: the type of data at this column index. Types can be:
+  * name: the name describing the data at this column index (a string).
+  * field_type: a FieldType enum member determining the type of data at this column index. Names can be:
        * "C": Characters, text.
 	   * "N": Numbers, with or without decimals.
 	   * "F": Floats (same as "N").
 	   * "L": Logical, for boolean True/False values.
 	   * "D": Dates.
 	   * "M": Memo, has no meaning within a GIS and is part of the xbase spec instead.
-  * Field length: the length of the data found at this column index. Older GIS
+  * size: Field length: the length of the data found at this column index. Older GIS
 	   software may truncate this length to 8 or 11 characters for "Character"
 	   fields.
-  * Decimal length: the number of decimal places found in "Number" fields.
+  * deci: Decimal length. The number of decimal places found in "Number" fields.
+
+A new field can be created directly from the type enum member etc., or as follows:
+
+	>>> shapefile.Field.from_unchecked("Population", "N", 10,0)
+	Field(name="Population", field_type=FieldType.N, size=10, decimal=0)
+
+Using this method the conversion from string to enum is done automatically.
 
 To see the fields for the Reader object above (sf) call the "fields"
 attribute:
 
 
-	>>> fields = sf.fields
-
-	>>> assert fields == [("DeletionFlag", "C", 1, 0), ("AREA", "N", 18, 5),
-	... ("BKG_KEY", "C", 12, 0), ("POP1990", "N", 9, 0), ("POP90_SQMI", "N", 10, 1),
-	... ("HOUSEHOLDS", "N", 9, 0),
-	... ("MALES", "N", 9, 0), ("FEMALES", "N", 9, 0), ("WHITE", "N", 9, 0),
-	... ("BLACK", "N", 8, 0), ("AMERI_ES", "N", 7, 0), ("ASIAN_PI", "N", 8, 0),
-	... ("OTHER", "N", 8, 0), ("HISPANIC", "N", 8, 0), ("AGE_UNDER5", "N", 8, 0),
-	... ("AGE_5_17", "N", 8, 0), ("AGE_18_29", "N", 8, 0), ("AGE_30_49", "N", 8, 0),
-	... ("AGE_50_64", "N", 8, 0), ("AGE_65_UP", "N", 8, 0),
-	... ("NEVERMARRY", "N", 8, 0), ("MARRIED", "N", 9, 0), ("SEPARATED", "N", 7, 0),
-	... ("WIDOWED", "N", 8, 0), ("DIVORCED", "N", 8, 0), ("HSEHLD_1_M", "N", 8, 0),
-	... ("HSEHLD_1_F", "N", 8, 0), ("MARHH_CHD", "N", 8, 0),
-	... ("MARHH_NO_C", "N", 8, 0), ("MHH_CHILD", "N", 7, 0),
-	... ("FHH_CHILD", "N", 7, 0), ("HSE_UNITS", "N", 9, 0), ("VACANT", "N", 7, 0),
-	... ("OWNER_OCC", "N", 8, 0), ("RENTER_OCC", "N", 8, 0),
-	... ("MEDIAN_VAL", "N", 7, 0), ("MEDIANRENT", "N", 4, 0),
-	... ("UNITS_1DET", "N", 8, 0), ("UNITS_1ATT", "N", 7, 0), ("UNITS2", "N", 7, 0),
-	... ("UNITS3_9", "N", 8, 0), ("UNITS10_49", "N", 8, 0),
-	... ("UNITS50_UP", "N", 8, 0), ("MOBILEHOME", "N", 7, 0)]
+	>>> sf.fields
+	[Field(name="DeletionFlag", field_type=FieldType.C, size=1, decimal=0), Field(name="AREA", field_type=FieldType.N, size=18, decimal=5), Field(name="BKG_KEY", field_type=FieldType.C, size=12, decimal=0), Field(name="POP1990", field_type=FieldType.N, size=9, decimal=0), Field(name="POP90_SQMI", field_type=FieldType.N, size=10, decimal=1), Field(name="HOUSEHOLDS", field_type=FieldType.N, size=9, decimal=0), Field(name="MALES", field_type=FieldType.N, size=9, decimal=0), Field(name="FEMALES", field_type=FieldType.N, size=9, decimal=0), Field(name="WHITE", field_type=FieldType.N, size=9, decimal=0), Field(name="BLACK", field_type=FieldType.N, size=8, decimal=0), Field(name="AMERI_ES", field_type=FieldType.N, size=7, decimal=0), Field(name="ASIAN_PI", field_type=FieldType.N, size=8, decimal=0), Field(name="OTHER", field_type=FieldType.N, size=8, decimal=0), Field(name="HISPANIC", field_type=FieldType.N, size=8, decimal=0), Field(name="AGE_UNDER5", field_type=FieldType.N, size=8, decimal=0), Field(name="AGE_5_17", field_type=FieldType.N, size=8, decimal=0), Field(name="AGE_18_29", field_type=FieldType.N, size=8, decimal=0), Field(name="AGE_30_49", field_type=FieldType.N, size=8, decimal=0), Field(name="AGE_50_64", field_type=FieldType.N, size=8, decimal=0), Field(name="AGE_65_UP", field_type=FieldType.N, size=8, decimal=0), Field(name="NEVERMARRY", field_type=FieldType.N, size=8, decimal=0), Field(name="MARRIED", field_type=FieldType.N, size=9, decimal=0), Field(name="SEPARATED", field_type=FieldType.N, size=7, decimal=0), Field(name="WIDOWED", field_type=FieldType.N, size=8, decimal=0), Field(name="DIVORCED", field_type=FieldType.N, size=8, decimal=0), Field(name="HSEHLD_1_M", field_type=FieldType.N, size=8, decimal=0), Field(name="HSEHLD_1_F", field_type=FieldType.N, size=8, decimal=0), Field(name="MARHH_CHD", field_type=FieldType.N, size=8, decimal=0), Field(name="MARHH_NO_C", field_type=FieldType.N, size=8, decimal=0), Field(name="MHH_CHILD", field_type=FieldType.N, size=7, decimal=0), Field(name="FHH_CHILD", field_type=FieldType.N, size=7, decimal=0), Field(name="HSE_UNITS", field_type=FieldType.N, size=9, decimal=0), Field(name="VACANT", field_type=FieldType.N, size=7, decimal=0), Field(name="OWNER_OCC", field_type=FieldType.N, size=8, decimal=0), Field(name="RENTER_OCC", field_type=FieldType.N, size=8, decimal=0), Field(name="MEDIAN_VAL", field_type=FieldType.N, size=7, decimal=0), Field(name="MEDIANRENT", field_type=FieldType.N, size=4, decimal=0), Field(name="UNITS_1DET", field_type=FieldType.N, size=8, decimal=0), Field(name="UNITS_1ATT", field_type=FieldType.N, size=7, decimal=0), Field(name="UNITS2", field_type=FieldType.N, size=7, decimal=0), Field(name="UNITS3_9", field_type=FieldType.N, size=8, decimal=0), Field(name="UNITS10_49", field_type=FieldType.N, size=8, decimal=0), Field(name="UNITS50_UP", field_type=FieldType.N, size=8, decimal=0), Field(name="MOBILEHOME", field_type=FieldType.N, size=7, decimal=0)]
 
 The first field of a dbf file is always a 1-byte field called "DeletionFlag",
 which indicates records that have been deleted but not removed. However,
@@ -1375,7 +1364,7 @@ Shapefiles containing M-values can be examined in several ways:
 	>>> r = shapefile.Reader('shapefiles/test/linem')
 
 	>>> r.mbox # the lower and upper bound of M-values in the shapefile
-	(0.0, 3.0)
+	MBox(mmin=0.0, mmax=3.0)
 
 	>>> r.shape(0).m # flat list of M-values
 	[0.0, None, 3.0, None, 0.0, None, None]
@@ -1408,7 +1397,7 @@ To examine a Z-type shapefile you can do:
 	>>> r = shapefile.Reader('shapefiles/test/linez')
 
 	>>> r.zbox # the lower and upper bound of Z-values in the shapefile
-	(0.0, 22.0)
+	ZBox(zmin=0.0, zmax=22.0)
 
 	>>> r.shape(0).z # flat list of Z-values
 	[18.0, 20.0, 22.0, 0.0, 0.0, 0.0, 0.0, 15.0, 13.0, 14.0]

src/shapefile.py

@@ -327,7 +327,7 @@ class GeoJSONFeatureCollectionWithBBox(GeoJSONFeatureCollection):
 
 # Helpers
 
-MISSING = {None, ""}
+MISSING = (None, "")  # Don't make a set, as user input may not be Hashable
 NODATA = -10e38  # as per the ESRI shapefile spec, only used for m-values.
 
 unpack_2_int32_be = Struct(">2i").unpack
@@ -2538,7 +2538,7 @@ def __record(
         # parse each value
         record = []
         for (__name, typ, __size, decimal), value in zip(fieldTuples, recordContents):
-            if typ in {"N", "F"}:
+            if typ in {FieldType.N, FieldType.F}:
                 # numeric or float: number stored as a string, right justified, and padded with blanks to the width of the field.
                 value = value.split(b"\0")[0]
                 value = value.replace(b"*", b"")  # QGIS NULL is all '*' chars
@@ -2564,7 +2564,7 @@ def __record(
                         except ValueError:
                             # not parseable as int, set to None
                             value = None
-            elif typ == "D":
+            elif typ is FieldType.D:
                 # date: 8 bytes - date stored as a string in the format YYYYMMDD.
                 if (
                     not value.replace(b"\x00", b"")
@@ -2582,7 +2582,7 @@ def __record(
                     except (TypeError, ValueError):
                         # if invalid date, just return as unicode string so user can decimalde
                         value = str(value.strip())
-            elif typ == "L":
+            elif typ is FieldType.L:
                 # logical: 1 byte - initialized to 0x20 (space) otherwise T or F.
                 if value == b" ":
                     value = None  # space means missing or not yet set
@@ -3225,7 +3225,7 @@ def __shxRecord(self, offset: int, length: int) -> None:
 
     def record(
         self,
-        *recordList: list[RecordValue],
+        *recordList: RecordValue,
         **recordDict: RecordValue,
     ) -> None:
         """Creates a dbf attribute record. You can submit either a sequence of
@@ -3241,7 +3241,7 @@ def record(
         record: list[RecordValue]
         fieldCount = sum(1 for field in self.fields if field[0] != "DeletionFlag")
         if recordList:
-            record = list(*recordList)
+            record = list(recordList)
             while len(record) < fieldCount:
                 record.append("")
         elif recordDict:
@@ -3272,7 +3272,7 @@ def _dbf_missing_placeholder(
             return "0" * 8  # QGIS NULL for date type
         if field_type is FieldType.L:
             return " "
-        return str(value)
+        return str(value)[:size].ljust(size)
 
     @overload
     @staticmethod
@@ -3362,20 +3362,20 @@ def __dbfRecord(self, record: list[RecordValue]) -> None:
                 str_val = self._try_coerce_to_logical_str(value)
             else:
                 if isinstance(value, bytes):
-                    decoded_val = value.decode(self.encoding, self.encodingErrors)
+                    str_val = value.decode(self.encoding, self.encodingErrors)
                 else:
                     # anything else is forced to string.
-                    decoded_val = str(value)
-                # Truncate to the length of the field
-                str_val = decoded_val[:size].ljust(size)
+                    str_val = str(value)
 
-            # should be default ascii encoding
-            encoded_val = str_val.encode("ascii", self.encodingErrors)
+            # Truncate or right pad to the length of the field
+            encoded_val = str_val.encode(self.encoding, self.encodingErrors)[
+                :size
+            ].ljust(size)
 
             if len(encoded_val) != size:
                 raise ShapefileException(
-                    "Shapefile Writer unable to pack incorrect sized value"
-                    f" (size {len(encoded_val)}) into field '{fieldName}' (size {size})."
+                    f"Shapefile Writer unable to pack incorrect sized {value=!r} "
+                    f"(size {len(encoded_val)}) into field '{fieldName}' (size {size})."
                 )
             f.write(encoded_val)
 
@@ -3674,7 +3674,7 @@ def _test(args: list[str] = sys.argv[1:], verbosity: bool = False) -> int:
             new_url = _replace_remote_url(old_url)
             example.source = example.source.replace(old_url, new_url)
 
-    runner = doctest.DocTestRunner(verbose=verbosity)
+    runner = doctest.DocTestRunner(verbose=verbosity, optionflags=doctest.FAIL_FAST)
 
     if verbosity == 0:
         print(f"Running {len(tests.examples)} doctests...")