Refactor functions to complexity 10 or below

dataretrieval/_configuration_core.py

@@ -1113,16 +1113,9 @@ def _adapter_file_settings(
 def _load_file(path: Path) -> _ParsedFile:
     """Parse the configuration file at *path*, caching until it changes on disk."""
     global _file_cache
-    try:
-        st = path.stat()
-    except FileNotFoundError:
-        # No file is the normal case: continue to the built-in default. One
-        # shared empty instance rather than a fresh one per read -- nothing
-        # mutates a ``_ParsedFile``, and returning the same object each time is
-        # what lets callers memoize on its identity.
+    st = _stat_config_file(path)
+    if st is None:
         return _NO_FILE
-    except OSError as exc:
-        raise ConfigurationError(f"could not access {path}: {exc}") from exc
 
     if stat.S_ISDIR(st.st_mode):
         raise ConfigurationError(
@@ -1134,32 +1127,42 @@ def _load_file(path: Path) -> _ParsedFile:
     # opened, which is what ``DATARETRIEVAL_CONFIG=/dev/null`` asks for and the
     # only coherent answer for a stream: settings are re-resolved on every
     # request, so a FIFO would hand its contents to the first getter and
-    # nothing to the rest, making the API key vanish mid-run. (It would also
-    # block on open until a writer appeared.)
+    # nothing to the rest, making the API key vanish mid-run.
     if not stat.S_ISREG(st.st_mode):
         return _ParsedFile(exists=True)
 
-    # POSIX ``st_ctime_ns`` advances on any inode change, so the metadata stamp
-    # catches even a rewrite that restores the original mtime (``cp -p``, rsync
-    # ``--times``, an editor that preserves timestamps). Windows ctime is
-    # *creation* time, so there the stamp cannot see that class of edit and the
-    # content compare below is the only correct check -- worth the re-read,
-    # since serving a stale API key is the alternative.
-    #
-    # Dropping this gate (or dropping ctime from the stamp so Windows can use
-    # it) has been proposed repeatedly on the grounds that the re-read is
-    # wasteful. It is, but it is also the only thing standing between a
-    # timestamp-preserving write and a stale credential; a ctime-less stamp is
-    # identical across exactly that edit. ``test_file_edit_is_picked_up``
-    # pins the behavior. Please do not "optimize" it without a Windows-safe
-    # change detector.
-    #
-    # Measured, so the next reviewer does not have to re-derive it: forcing the
-    # Windows branch costs 27 us per settings read against 5 us with the stamp
-    # (5 syscalls instead of 1; a 64-byte file and a 6.5 kB one measure the
-    # same, since the content compare still spares the TOML parse). At the 8
-    # reads a one-chunk query performs that is ~175 us against a 100-500 ms
-    # round trip -- 0.04%, and the alternative is serving a stale key.
+    cached_parse = _cached_parse_by_metadata(path, st)
+    if cached_parse is not None:
+        return cached_parse
+
+    content, opened_st = _read_file_content(path)
+    parsed = _parse_or_reuse_cache(path, content)
+    _warn_on_loose_permissions(path, opened_st, parsed)
+    _file_cache = (path, _file_stamp(opened_st), content, parsed)
+    return parsed
+
+
+def _stat_config_file(path: Path) -> os.stat_result | None:
+    """Stat the config file, returning ``None`` if it does not exist."""
+    try:
+        return path.stat()
+    except FileNotFoundError:
+        return None
+    except OSError as exc:
+        raise ConfigurationError(f"could not access {path}: {exc}") from exc
+
+
+def _cached_parse_by_metadata(path: Path, st: os.stat_result) -> _ParsedFile | None:
+    """The cached parse when the metadata stamp still matches, else ``None``.
+
+    POSIX ``st_ctime_ns`` advances on any inode change, so the metadata stamp
+    catches even a rewrite that restores the original mtime. Windows ctime is
+    *creation* time, so there the stamp cannot see that class of edit and the
+    content compare in :func:`_parse_or_reuse_cache` is the only correct check
+    -- the re-read it forces is deliberate, and ``test_file_edit_is_picked_up``
+    pins it. Do not drop the ctime gate (or extend the stamp to Windows)
+    without a Windows-safe change detector.
+    """
     cached = _file_cache
     if (
         os.name != "nt"
@@ -1168,28 +1171,33 @@ def _load_file(path: Path) -> _ParsedFile:
         and cached[1] == _file_stamp(st)
     ):
         return cached[3]
+    return None
+
 
+def _read_file_content(path: Path) -> tuple[bytes, os.stat_result]:
+    """Read the file content and return it with the stat of the opened handle."""
     try:
         with path.open("rb") as handle:
             content = handle.read()
             opened_st = os.fstat(handle.fileno())
     except OSError as exc:
         raise ConfigurationError(f"could not read {path}: {exc}") from exc
+    return content, opened_st
+
 
+def _parse_or_reuse_cache(path: Path, content: bytes) -> _ParsedFile:
+    """Parse the TOML content, reusing the cache if content is unchanged."""
+    cached = _file_cache
     if cached is not None and cached[0] is path and cached[2] == content:
-        parsed = cached[3]
-    else:
-        tomllib = _toml_parser()
-        try:
-            data = tomllib.loads(content.decode("utf-8"))
-        except UnicodeDecodeError as exc:
-            raise ConfigurationError(f"{path} is not valid UTF-8: {exc}") from exc
-        except tomllib.TOMLDecodeError as exc:
-            raise ConfigurationError(f"{path} is not valid TOML: {exc}") from exc
-        parsed = _interpret(data, path)
-    _warn_on_loose_permissions(path, opened_st, parsed)
-    _file_cache = (path, _file_stamp(opened_st), content, parsed)
-    return parsed
+        return cached[3]
+    tomllib = _toml_parser()
+    try:
+        data = tomllib.loads(content.decode("utf-8"))
+    except UnicodeDecodeError as exc:
+        raise ConfigurationError(f"{path} is not valid UTF-8: {exc}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigurationError(f"{path} is not valid TOML: {exc}") from exc
+    return _interpret(data, path)
 
 
 def _file_stamp(st: os.stat_result) -> _FileStamp:

dataretrieval/_wqx.py

@@ -48,6 +48,49 @@ def _build_utc_datetime(
     )
 
 
+def _build_triplet_datetime(
+    df: pd.DataFrame, prefix: str, columns: set[str]
+) -> pd.Series | None:
+    """Try each Time/TimeZone suffix pair and return a UTC Series, or None."""
+    for time_suffix, tz_suffix in _TIME_TZ_SUFFIXES:
+        time_col = prefix + time_suffix
+        tz_col = prefix + tz_suffix
+        if time_col in columns and tz_col in columns:
+            return _build_utc_datetime(df[prefix + "Date"], df[time_col], df[tz_col])
+    return None
+
+
+def _find_datetime_triplets(df: pd.DataFrame) -> dict[str, pd.Series]:
+    """Detect Date/Time/TimeZone column triplets and build UTC datetime columns.
+
+    Returns a mapping of new column names to UTC Series.
+    """
+    columns = set(df.columns)
+    new_columns: dict[str, pd.Series] = {}
+
+    for col in df.columns:
+        if not col.endswith("Date"):
+            continue
+        prefix = col.removesuffix("Date")
+        target = prefix + "DateTime"
+        if target in columns or target in new_columns:
+            continue
+        utc_series = _build_triplet_datetime(df, prefix, columns)
+        if utc_series is not None:
+            new_columns[target] = utc_series
+
+    return new_columns
+
+
+def _resolve_sort_key(df: pd.DataFrame) -> str | None:
+    """Pick the canonical sort column, falling back to the first ``*Date``."""
+    if "Activity_StartDateTime" in df.columns:
+        return "Activity_StartDateTime"
+    if "ActivityStartDateTime" in df.columns:
+        return "ActivityStartDateTime"
+    return next((c for c in df.columns if c.endswith("Date")), None)
+
+
 def _attach_datetime_columns(df: pd.DataFrame) -> pd.DataFrame:
     """Append a UTC ``<prefix>DateTime`` column per Date/Time/TimeZone triplet.
 
@@ -82,37 +125,16 @@ def _attach_datetime_columns(df: pd.DataFrame) -> pd.DataFrame:
         and rows sorted by the activity-start datetime (if any date column
         was detected).
     """
-    columns = set(df.columns)
-    new_columns = {}
-    first_date_col = None
-    for col in df.columns:
-        if not col.endswith("Date"):
-            continue
-        if first_date_col is None:
-            first_date_col = col
-        prefix = col.removesuffix("Date")
-        target = prefix + "DateTime"
-        if target in columns or target in new_columns:
-            continue
-        for time_suffix, tz_suffix in _TIME_TZ_SUFFIXES:
-            time_col = prefix + time_suffix
-            tz_col = prefix + tz_suffix
-            if time_col in columns and tz_col in columns:
-                new_columns[target] = _build_utc_datetime(
-                    df[col], df[time_col], df[tz_col]
-                )
-                break
+    new_columns = _find_datetime_triplets(df)
+
     if new_columns:
         # Concat in one shot — per-column assignment on a wide CSV-derived
         # frame triggers pandas' fragmentation PerformanceWarning.
         df = pd.concat([df, pd.DataFrame(new_columns, index=df.index)], axis=1)
-    sort_key: str | None
-    if "Activity_StartDateTime" in df.columns:
-        sort_key = "Activity_StartDateTime"
-    elif "ActivityStartDateTime" in df.columns:
-        sort_key = "ActivityStartDateTime"
-    else:
-        sort_key = first_date_col
+
+    # The appended columns end in "DateTime", so the first "*Date" column is
+    # the same before and after the concat.
+    sort_key = _resolve_sort_key(df)
     if sort_key is not None:
         df = df.sort_values(by=sort_key, ignore_index=True)
     return df

dataretrieval/codes/states.py

@@ -180,6 +180,11 @@ def _to_state_one(value: str | int, to: str) -> str:
             f'code ("WI"), or a two-digit ANSI/FIPS code ("55").'
         )
 
+    return _format_state(name, to)
+
+
+def _format_state(name: str, to: str) -> str:
+    """Render a canonical state *name* in the ``to`` representation."""
     if to == "name":
         return name
     if to == "postal":