BUG: string date parsing for at_time and indexer_at_time have many inconsistencies with indexer_at_time documentation; should be more like between_time

[mvashishtha]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

import pandas as pd

rng = pd.date_range("1/1/2000", "1/5/2000", freq="5min")
ts = pd.DataFrame(list(range(len(rng))), index=rng)

# This selects everything at time 00:00:00, while the documentation
# does not say this format is supported
print(ts.at_time('1'))
# This “%I%M%p" format should select everything at time 00:05:00, but I get
# ParserError
print(ts.at_time('1205AM'))
# this format isn't supposed to work, but instead it select things
# at time 00:00:00
print(ts.at_time("2022-12-12 00:00:00"))
# this format isn't supposed to work, but it does, and, alarmingly, it discards
# the time offset, probably cause calling time() instead of timetz() here:
# https://github.com/pandas-dev/pandas/blob/3d8993146ccb6054ecad6b7e97ee39e97c6d84e5/pandas/core/indexes/datetimes.py#L721
print(ts.at_time("2022-12-12 00:00:00 +09:00"))
# seconds with decimal component is not documented, but it works
print(ts.at_time("2022-12-12 00:00:00.000000"))
# “%H%M%S” should work, but raises ParserError
print(ts.at_time("235500"))
# “%I%M%S%p” format should work, but raises ParserError
print(ts.at_time("115500PM"))

Issue Description

To start with, documentation for pandas.DataFrame.at_time gives no information about the allowed formats for the time string. I saw that the implementation of at_time uses DatetimeIndex.indexer_at_time, and that method lists several date formats that should work. However, not all of these formats work for at_time, and some formats not in the list there do work. String parsing for at_time uses datetime.parser.parse(time).time():

pandas/pandas/core/indexes/datetimes.py

Lines 719 to 721 in 3d89931

	from dateutil.parser import parse
	time = parse(time).time()

whereas indexer_between_time uses to_time from pandas.core.tools.times. to_time implements what seems to be the intended behavior, including allowing only the valid time formats.

If I convert my at_time(x) calls to between_time(x, x) I get the expected, behavior, e.g.

• ts.between_time("1", "1") gives ValueError
• ts.between_time('1205AM', '1205AM') selects 4 times

Expected Behavior

1. at_time should document the kinds of strings that work
2. at_time time strings should be consistent with DatetimeIndex.indexer_at_time strings
3. both at_time and indexer_at_time time strings should be consistent with the documentation,between_time, and indexer_between_time

Installed Versions

INSTALLED VERSIONS

commit : 8dab54d
python : 3.10.4.final.0
python-bits : 64
OS : Darwin
OS-release : 21.5.0
Version : Darwin Kernel Version 21.5.0: Tue Apr 26 21:08:22 PDT 2022; root:xnu-8020.121.3~4/RELEASE_X86_64
machine : x86_64
processor : i386
byteorder : little
LC_ALL : None
LANG : en_US.UTF-8
LOCALE : en_US.UTF-8

pandas : 1.5.2
numpy : 1.23.3
pytz : 2022.2.1
dateutil : 2.8.2
setuptools : 63.4.1
pip : 22.1.2
Cython : 0.29.32
pytest : None
hypothesis : None
sphinx : None
blosc : None
feather : None
xlsxwriter : None
lxml.etree : None
html5lib : None
pymysql : None
psycopg2 : None
jinja2 : None
IPython : 8.5.0
pandas_datareader: None
bs4 : None
bottleneck : None
brotli : None
fastparquet : None
fsspec : None
gcsfs : None
matplotlib : None
numba : None
numexpr : None
odfpy : None
openpyxl : None
pandas_gbq : None
pyarrow : None
pyreadstat : None
pyxlsb : None
s3fs : None
scipy : None
snappy : None
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
xlwt : None
zstandard : None
tzdata : None

[jbrockmendel]

Improving the parsing behavior seems really cumbersome since it would need to be with a deprecation and enabling the new behavior would require its own keyword. Would it make more sense to just deprecate allowing strings at all and require users to parse themselves?