ENH: make guess_datetime_format public

doc/source/reference/general_functions.rst

@@ -61,6 +61,7 @@ Top-level dealing with datetimelike data
 
 Top-level dealing with Interval data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. autosummary::
    :toctree: api/
 
@@ -73,6 +74,13 @@ Top-level evaluation
 
    eval
 
+Datetime formats
+~~~~~~~~~~~~~~~~
+.. autosummary::
+   :toctree: api/
+
+   tseries.api.guess_datetime_format
+
 Hashing
 ~~~~~~~
 .. autosummary::

pandas/_libs/tslibs/__init__.py

@@ -33,6 +33,7 @@
     "is_supported_unit",
     "npy_unit_to_abbrev",
     "get_supported_reso",
+    "guess_datetime_format",
 ]
 
 from pandas._libs.tslibs import dtypes  # pylint: disable=import-self
@@ -63,6 +64,7 @@
     Tick,
     to_offset,
 )
+from pandas._libs.tslibs.parsing import guess_datetime_format
 from pandas._libs.tslibs.period import (
     IncompatibleFrequency,
     Period,

pandas/_libs/tslibs/parsing.pyi

@@ -24,7 +24,7 @@ def try_parse_dates(
     parser,
 ) -> npt.NDArray[np.object_]: ...
 def guess_datetime_format(
-    dt_str,
+    dt_str: str,
     dayfirst: bool | None = ...,
 ) -> str | None: ...
 def concat_date_cols(

pandas/_libs/tslibs/parsing.pyx

@@ -855,14 +855,24 @@ def guess_datetime_format(dt_str: str, bint dayfirst=False) -> str | None:
         Datetime string to guess the format of.
     dayfirst : bool, default False
         If True parses dates with the day first, eg 20/01/2005
-        Warning: dayfirst=True is not strict, but will prefer to parse
-        with day first (this is a known bug).
+
+        .. warning::
+            dayfirst=True is not strict, but will prefer to parse
+            with day first (this is a known bug).
 
     Returns
     -------
     str or None : ret
         datetime format string (for `strftime` or `strptime`),
         or None if it can't be guessed.
+
+    Examples
+    --------
+    >>> from pandas.tseries.api import guess_datetime_format
+    >>> guess_datetime_format('09/13/2023')
+    '%m/%d/%Y'
+
+    >>> guess_datetime_format('2023|September|13')
     """
     cdef:
         NPY_DATETIMEUNIT out_bestunit

pandas/tests/tslibs/test_api.py

@@ -57,6 +57,7 @@ def test_namespace():
         "is_supported_unit",
         "get_supported_reso",
         "npy_unit_to_abbrev",
+        "guess_datetime_format",
     ]
 
     expected = set(submodules + api)

pandas/tseries/api.py

@@ -2,7 +2,9 @@
 Timeseries API
 """
 
+from pandas._libs.tslibs.parsing import guess_datetime_format
+
 from pandas.tseries import offsets
 from pandas.tseries.frequencies import infer_freq
 
-__all__ = ["infer_freq", "offsets"]
+__all__ = ["infer_freq", "offsets", "guess_datetime_format"]