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