REF: Replace args/kwargs in groupby.resample with TimeGrouper arguments

[rhshadrach]

The args/kwargs to this method are currently documented as:

*args, **kwargs
Possible arguments are how, fill_method, limit, kind and on, and other arguments of TimeGrouper.

I think we should instead have these argument as being keyword arguments to groupby.resample and a test that ensures the arguments to TimeGrouper are a subset of the arguments to this method.

Also, it looks like some of these arguments, how, fill_method, and limit, are entirely ignored? But I haven't checked thoroughly.

cc @mroeschke

[mfenner1]

@rhshadrach Do you happen to know when TimeGrouper was resurrected? It was deprecated in 0.21.0: (see https://pandas.pydata.org/pandas-docs/stable/whatsnew/v0.21.0.html#deprecations and #16747).

But today, in main, TimeGrouper is a key member variable of class Resampler:

pandas/pandas/core/resample.py

Line 144 in 7c6d26f

_timegrouper: TimeGrouper

In the deprecation comments (#16747 (comment)), it appears that TimeGrouper was a relic of the old-school groupby framework and its functionality was integrated into the Grouper interface.

So, I'm super curious if it was never fully removed, if it was only "deprecated" in terms of being an exposed/external capability, or if it was gone and has returned. Does anyone have any insight?

[rhshadrach]

@mfenner1 - at one point in pandas there were two separate TimeGrouper classes:

pandas/pandas/core/api.py

Lines 73 to 81 in e567949

	class TimeGrouper(object):
	def __new__(cls, *args, **kwargs):
	from pandas.core.resample import TimeGrouper
	import warnings
	warnings.warn("pd.TimeGrouper is deprecated and will be removed; "
	"Please use pd.Grouper(freq=...)",
	FutureWarning, stacklevel=2)
	return TimeGrouper(*args, **kwargs)

pandas/pandas/core/resample.py

Lines 1321 to 1323 in 51db82d

	class TimeGrouper(Grouper):
	"""
	Custom groupby class for time-interval grouping.

The deprecation was only for pd.TimeGrouper. You can still get a TimeGrouper today by creating a Grouper with the freq argument not None. This was never deprecated, and shouldn't be.

[mfenner1]

@rhshadrach That is really useful! I didn't get that little detail. Thank you!

Can I follow up with another question or two?

Do both pd.Grouper(freq=) and pd.resample() lead to the same class TimeGrouper objects? Are there any explicit tests about guarantees between arguments and resulting TimeGroupers? [Maybe those questions play back into your original comments about handling the arguments .... Or maybe aligning those is exactly what you are proposing?]

Thanks,
Mark

[rhshadrach]

Do both pd.Grouper(freq=) and pd.resample() lead to the same class TimeGrouper objects? Are there any explicit tests about guarantees between arguments and resulting TimeGroupers?

Offhand, I do not know. Would need to step through the code and search the tests.