Update codecov, type hints, and documentation

Author: TedBrookings

fgpyo/util/inspect.py

@@ -1,7 +1,9 @@
 import sys
+import types as python_types
 import typing
 from typing import Any
 from typing import Dict
+from typing import FrozenSet
 from typing import Iterable
 from typing import List
 from typing import Literal
@@ -31,23 +33,24 @@
 
 import fgpyo.util.types as types
 
+attr: Optional[python_types.ModuleType]
+MISSING: FrozenSet[Any]
+
 try:
     import attr
 
     _use_attr = True
-    from attr import NOTHING as ATTR_NOTHING
     from attr import fields as get_attr_fields
     from attr import fields_dict as get_attr_fields_dict
 
-    Attribute = attr.Attribute
+    Attribute: TypeAlias = attr.Attribute  # type: ignore[name-defined, no-redef]
     # dataclasses and attr have internal tokens for missing values, join into a set so that we can
     # check if a value is missing without knowing the type of backing class
-    MISSING = {DATACLASSES_MISSING, ATTR_NOTHING}
-except ImportError:
+    MISSING = frozenset({DATACLASSES_MISSING, attr.NOTHING})
+except ImportError:  # pragma: no cover
     _use_attr = False
     attr = None
-    ATTR_NOTHING = None
-    Attribute = TypeVar("Attribute", bound=object)  # type: ignore[misc, assignment]
+    Attribute: TypeAlias = TypeVar("Attribute", bound=object)  # type: ignore[misc, assignment, no-redef]  # noqa: E501
 
     # define empty placeholders for getting attr fields as a tuple or dict. They will never be
     # called because the import failed; but they're here to ensure that the function is defined in
@@ -62,17 +65,17 @@ def get_attr_fields_dict(cls: type) -> Dict[str, dataclasses.Field]:  # type: ig
         return {}
 
     # for consistency with successful import of attr, create a set for missing values
-    MISSING = {DATACLASSES_MISSING}
+    MISSING = frozenset({DATACLASSES_MISSING})
 
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover
     from _typeshed import DataclassInstance as DataclassesProtocol
 else:
 
     class DataclassesProtocol(Protocol):
         __dataclasses_fields__: Dict[str, dataclasses.Field]
 
 
-if TYPE_CHECKING and _use_attr:
+if TYPE_CHECKING and _use_attr:  # pragma: no cover
     from attr import AttrsInstance
 else:
 
@@ -85,7 +88,7 @@ def is_attr_class(cls: type) -> bool:  # type: ignore[arg-type]
     return hasattr(cls, "__attrs_attrs__")
 
 
-_MISSING_OR_NONE = {*MISSING, None}
+_MISSING_OR_NONE: FrozenSet[Any] = frozenset({*MISSING, None})
 """Set of values that are considered missing or None for dataclasses or attr classes"""
 _DataclassesOrAttrClass: TypeAlias = Union[DataclassesProtocol, AttrsInstance]
 """
@@ -148,7 +151,7 @@ def split_at_given_level(
     return out_vals
 
 
-NoneType = type(None)
+NoneType: TypeAlias = type(None)  # type: ignore[no-redef]
 
 
 def list_parser(

fgpyo/util/tests/test_metric.py

@@ -58,7 +58,23 @@ def make_dataclasses(cls: T) -> T:
 
 
 class DataBuilder:
-    """Holds classes and data for testing, either using attr- or dataclasses-style dataclass"""
+    """
+    Holds classes and data for testing, either using attr- or dataclasses-style dataclass
+    We need to run each test both with attr and dataclasses classes, so use this class to construct
+    the test metrics appropriately, governed by the use_attr flag. After construction, the
+    DataBuilder object will have all the required Metrics:
+
+    Attributes:
+        use_attr: If True use attr classes for Metrics, if False use dataclasses
+        DummyMetric: Metric with many different field types
+        Person: Metric with optional name and age string fields
+        Name: Metric with first and last name string fields and a parse method
+        NamedPerson: Metric with name (Name Metric) field and age (int) fields, and parsers.
+        PersonMaybeAge = Person with required name string field and optional age int field
+        PersonDefault = Person with required name string field and age int field with default value
+        ListPerson = Person with list[str] name and list[int] age fields
+        DUMMY_METRICS: a list of 3 different DummyMetrics
+    """
 
     def __init__(self, use_attr: bool) -> None:
         self.use_attr = use_attr
@@ -186,15 +202,21 @@ class ListPerson(Metric["ListPerson"]):
         ]
 
 
+# construct the attr and dataclasses DataBuilder objects
 attr_data_and_classes = DataBuilder(use_attr=True)
 dataclasses_data_and_classes = DataBuilder(use_attr=False)
 
+# get helper type and helper num_metrics that will be used frequently in tests
 AnyDummyMetric = Union[attr_data_and_classes.DummyMetric, dataclasses_data_and_classes.DummyMetric]
 num_metrics = len(attr_data_and_classes.DUMMY_METRICS)
 
 
 @pytest.mark.parametrize("use_attr", [False, True])
 def test_is_correct_dataclass_type(use_attr: bool) -> None:
+    """
+    Test that the DataBuilder class works as expected, as do the is_attr_class and
+    is_dataclasses_class methods
+    """
     data_and_classes = DataBuilder(use_attr=use_attr)
     assert use_attr == data_and_classes.use_attr
     assert is_attr_class(data_and_classes.DummyMetric) is use_attr