Repository: pandas-dev/pandas

Issue:
ENH: make guess_datetime_format public
### Feature Type

- [ ] Adding new functionality to pandas

- [X] Changing existing functionality in pandas

- [ ] Removing existing functionality in pandas


### Problem Description

Pandas can infer datetime formats when parsing datetimes, but does not provide access to the inferred format via a public API.

### Feature Description

Currently, `guess_datetime_format` is in `pandas.core.tools.datetimes` which is not public. Exporting it from a non-private module would address the issue.

### Alternative Solutions

As far as I can tell, no other Python library provides this requested feature.

### Additional Context

As discussed in https://github.com/dateutil/dateutil/issues/1138


Discussion:
sounds good - fancy making a pull request?
take
Hey @joefutrelle ,
I could not find `guess_datetime_format`  are you referring to `_guess_datetime_format_for_array`?
If I read this correctly, the import into `pandas.core.tools.datetimes` is [here](https://github.com/pandas-dev/pandas/blob/1ecfa6749d07a08d501d56b98ae60d483cf1078f/pandas/core/tools/datetimes.py#L36) and the implementation is [here](https://github.com/pandas-dev/pandas/blob/1ecfa6749d07a08d501d56b98ae60d483cf1078f/pandas/_libs/tslibs/parsing.pyx#L867).
Hey @joefutrelle ,
From what I understood the `guess_datetime_format` should be moved to `pandas.core.tools.datetimes`, is this correct or is there some other place it should be. Or should I write a function in `pandas.core.tools.datetimes` which uses `guess_datetime_format`  internally?
According to the docs, everything in `pandas.core.*` is private, so it would need to go somewhere else. `to_datetime` is at the top level and because this is related it could go there but I would defer to core developers on where the appropriate place for datetime utilities is.

> The pandas.core, pandas.compat, and pandas.util top-level modules are PRIVATE. Stable functionality in such modules is not guaranteed.
How about adding `pandas.api.tools`, and putting this in there?
As suggested on Slack by @mroeschke , `pandas.tseries` might be a better place
Hi! Is see that @nikhilreddy2002 is assigned to this issue. But I can't see any activity the last week. I would like to start contributing to this project. I'm studying an open source course at University that requires us to get involved in an open source project. So I would love to contribute to Pandas codebase :) And this issue seems like a good start for me @joefutrelle 
Sure go ahead thanks

Patch:
diff --git a/doc/source/reference/general_functions.rst b/doc/source/reference/general_functions.rst
index 02b0bf5d13dde..e93514de5f762 100644
--- a/doc/source/reference/general_functions.rst
+++ b/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::
diff --git a/doc/source/whatsnew/v2.2.0.rst b/doc/source/whatsnew/v2.2.0.rst
index 795d277268e44..4ebd65208df81 100644
--- a/doc/source/whatsnew/v2.2.0.rst
+++ b/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`)
diff --git a/pandas/_libs/tslibs/__init__.py b/pandas/_libs/tslibs/__init__.py
index 2cabbe3ff07da..c622121578dcb 100644
--- a/pandas/_libs/tslibs/__init__.py
+++ b/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,
diff --git a/pandas/_libs/tslibs/parsing.pyi b/pandas/_libs/tslibs/parsing.pyi
index 2a2d98dab0d8b..40394f915d4b0 100644
--- a/pandas/_libs/tslibs/parsing.pyi
+++ b/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(
diff --git a/pandas/_libs/tslibs/parsing.pyx b/pandas/_libs/tslibs/parsing.pyx
index 56581ba383730..bfdd6c58432fa 100644
--- a/pandas/_libs/tslibs/parsing.pyx
+++ b/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
diff --git a/pandas/tseries/api.py b/pandas/tseries/api.py
index 9fdf95d09fe52..ec2d7d2304839 100644
--- a/pandas/tseries/api.py
+++ b/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"]


Test patch:
diff --git a/pandas/tests/tslibs/test_api.py b/pandas/tests/tslibs/test_api.py
index a596d4a85074e..b52bc78d58296 100644
--- a/pandas/tests/tslibs/test_api.py
+++ b/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)