DataFrameGroupBy.apply missing include_groups argument

[rhshadrach]

Describe the bug

pandas-stubs/pandas-stubs/core/groupby/generic.pyi

Lines 227 to 236 in 6ce988b

	class DataFrameGroupBy(GroupBy[DataFrame], Generic[ByT, _TT]):
	# error: Overload 3 for "apply" will never be used because its parameters overlap overload 1
	@overload # type: ignore[override]
	def apply( # pyrefly: ignore[bad-override]
	self,
	func: DFCallable1[P],
	/,
	*args: P.args,
	**kwargs: P.kwargs,
	) -> Series: ...

This method should have an include_groups argument which was added in pandas 2.2.0.

https://pandas.pydata.org/docs/reference/api/pandas.core.groupby.DataFrameGroupBy.apply.html

Note this argument while be deprecated in pandas 3.x and then removed in pandas 4.0.

[cmp0xff]

@Dr-Irv do you have the capacity to work on it? It seems that you are the last one who worked on GroupBy.apply in #1268.

[Dr-Irv]

Because include_groups will be deprecated in version 3.0, we are purposely not including it in the stubs. This allows us to better support args and kwargs in apply.

See discussion at #1270 and #1268 (comment)

[rhshadrach]

Just to be sure, the argument is not deprecated yet, but will plan to deprecate during the 3.x series. I would like to wait for 3.1 to introduce the deprecation.

[Dr-Irv]

Just to be sure, the argument is not deprecated yet, but will plan to deprecate during the 3.x series. I would like to wait for 3.1 to introduce the deprecation.

Yes, but right now, the only valid value that is not deprecated is include_groups=False, which is the default, so it is effectively deprecated now. My goal with the stubs is to get people to start writing code that is "future proof".

I guess we should have some docs that tell people how to remove the dependency on include_groups=True if that is what is needed for their code to work.