ENH: make guess_datetime_format public (#55079)

* updating init to include guess_datetime_format func

* included guess_datetime_format in api

* updated test to include guess_datetime_format method

* ran pre-commit hook

* updated latest rst doc with enhancement note

* removed enhancement update

* alphabetize other-enhancement list

* added guess_datetime_format

* updated guess_datetime_format docstring with warning sphinx directive

* fixed spelling from pre-commit hook

* update guess_datetime_format docstring examples

* fixed trailing whitespace

* correct sphinx directive for guess_datetime_format with trailing whitespace

* updated whatsnew with corrected guess_datatime_format api method string

* removed extra line

* removed comment lines in example for guess_datetime_format

* removed api from method call for guess_datetime_format

* pre-commit hook fix for whitespace

* fix extra char

* fix whitespace

* removed toctree api

* fixup

* try fixing docstring

* add whatsnew note

---------

Co-authored-by: Donald Thevalingam <donaldthevalingam@Donalds-MacBook-Pro.local>
Co-authored-by: MarcoGorelli <33491632+MarcoGorelli@users.noreply.github.com>

Author: 3 people

doc/source/reference/general_functions.rst

@@ -73,6 +73,13 @@ Top-level evaluation
 
    eval
 
+Datetime formats
+~~~~~~~~~~~~~~~~
+.. autosummary::
+   :toctree: api/
+
+   tseries.api.guess_datetime_format
+
 Hashing
 ~~~~~~~
 .. autosummary::

doc/source/whatsnew/v2.2.0.rst

@@ -78,6 +78,7 @@ Other enhancements
 - :attr:`Series.attrs` / :attr:`DataFrame.attrs` now uses a deepcopy for propagating ``attrs`` (:issue:`54134`).
 - :func:`read_csv` now supports ``on_bad_lines`` parameter with ``engine="pyarrow"``. (:issue:`54480`)
 - :func:`read_spss` now returns a :class:`DataFrame` that stores the metadata in :attr:`DataFrame.attrs`. (:issue:`54264`)
+- :func:`tseries.api.guess_datetime_format` is now part of the public API (:issue:`54727`)
 - :meth:`ExtensionArray._explode` interface method added to allow extension type implementations of the ``explode`` method (:issue:`54833`)
 - :meth:`ExtensionArray.duplicated` added to allow extension type implementations of the ``duplicated`` method (:issue:`55255`)
 - DataFrame.apply now allows the usage of numba (via ``engine="numba"``) to JIT compile the passed function, allowing for potential speedups (:issue:`54666`)

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"]