Documentation update

Author: jakechirsch

pandas/_libs/src/vendored/numpy/datetime/np_datetime_strings.c

@@ -441,7 +441,7 @@ int parse_iso_8601_datetime(const char *str, int len, int want_exc,
     if (sublen > 0) {
       int has_sep = 0;
       int j = 0;
-      for (j = 0; j < (sublen > 2 ? 2 : sublen); ++j) {
+      for (j = 0; j < (sublen > 2 && !has_ymd_sep ? 2 : sublen); ++j) {
         char c = substr[j];
         for (i = 0; i < valid_ymd_sep_len; ++i) {
           if (c == valid_ymd_sep[i]) {

pandas/_libs/tslibs/strptime.pyx

@@ -368,23 +368,7 @@ def array_strptime(
     errors : string specifying error handling, {'raise', 'coerce'}
     creso : NPY_DATETIMEUNIT, default NPY_FR_GENERIC
         Set to NPY_FR_GENERIC to infer a resolution.
-
-    /// INSERT DOCUMENTATION UPDATE HERE ///
-    ########################
-        ########################
-            ########################
-                ########################
-                    ########################
-                        ########################
-                            ########################
-                                ########################
-                            ########################
-                        ########################
-                    ########################
-                ########################
-            ########################
-        ########################
-    ########################
+    threshold : minimum fraction of valid datetime components required
     """
 
     cdef:

pandas/core/tools/datetimes.py

@@ -351,23 +351,8 @@ def _convert_listlike_datetimes(
         yearfirst parsing behavior from to_datetime
     exact : bool, default True
         exact format matching behavior from to_datetime
-
-    /// INSERT DOCUMENTATION UPDATE HERE ///
-    ########################
-        ########################
-            ########################
-                ########################
-                    ########################
-                        ########################
-                            ########################
-                                ########################
-                            ########################
-                        ########################
-                    ########################
-                ########################
-            ########################
-        ########################
-    ########################
+    threshold : float
+        Minimum fraction of valid datetime components required
 
     Returns
     -------
@@ -660,6 +645,7 @@ def to_datetime(
     unit: str | None = ...,
     origin=...,
     cache: bool = ...,
+    threshold: float = ...,
 ) -> Timestamp: ...
 
 
@@ -675,6 +661,7 @@ def to_datetime(
     unit: str | None = ...,
     origin=...,
     cache: bool = ...,
+    threshold: float = ...,
 ) -> Series: ...
 
 
@@ -690,6 +677,7 @@ def to_datetime(
     unit: str | None = ...,
     origin=...,
     cache: bool = ...,
+    threshold: float = ...,
 ) -> DatetimeIndex: ...
 
 
@@ -814,24 +802,19 @@ def to_datetime(
         is only used when there are at least 50 values. The presence of
         out-of-bounds values will render the cache unusable and may slow down
         parsing.
-
-    /// INSERT DOCUMENTATION UPDATE HERE ///
-    ########################
-        ########################
-            ########################
-                ########################
-                    ########################
-                        ########################
-                            ########################
-                                ########################
-                            ########################
-                        ########################
-                    ########################
-                ########################
-            ########################
-        ########################
-    ########################
-
+    threshold : float
+        Minimum fraction of valid datetime components required to consider parsing
+        successful. Components include year, month, day, hour, minute, and second
+        if present in the input. An invalid component has too many or too few digits
+        or a number outside the possible range (e.g., month outside [1, 12]). Behavior
+        depends on the threshold:
+
+        - 1.0 (default): all components must be valid, else raises error (unless
+        ``errors='coerce'``).
+        - 0.0: any invalid component produces NaT, else returns a valid datetime.
+        - Values between 0 and 1: if all components are valid, returns a valid
+          datetime; if the fraction of valid components >= threshold, returns NaT;
+          otherwise raises error.
     Returns
     -------
     datetime
@@ -1032,6 +1015,14 @@ def to_datetime(
     >>> pd.to_datetime(["2018-10-26 12:00", datetime(2020, 1, 1, 18)], utc=True)
     DatetimeIndex(['2018-10-26 12:00:00+00:00', '2020-01-01 18:00:00+00:00'],
                   dtype='datetime64[us, UTC]', freq=None)
+
+    - Input string with one invalid component returns NaT if threshold allows
+      partial validity
+
+    >>> pd.to_datetime(
+    ...     "2018-100-26 12:00:00", format="%Y-%m-%d %H:%M:%S", threshold=0.5
+    ... )
+    NaT
     """
     if exact is not lib.no_default and format in {"mixed", "ISO8601"}:
         raise ValueError("Cannot use 'exact' when 'format' is 'mixed' or 'ISO8601'")

pandas/tests/tools/test_to_datetime.py

@@ -4147,3 +4147,11 @@ def test_parse_mixed_format_threshold(self):
         result = to_datetime(series, format="mixed", threshold=0.5, errors="coerce")
         expected = Series([Timestamp("2020-01-01"), Timestamp("2021-01-02"), NaT])
         tm.assert_series_equal(result, expected)
+
+    def test_example(self):
+        result = to_datetime(
+            "2018-100-26 12:00:00",
+            format="%Y-%m-%d %H:%M:%S",
+            threshold=0.5,
+        )
+        assert isna(result)