DOC: should `DateOffset` always be used instead of `BaseOffset`?

[MarcoGorelli]

There's currently 4 pages in the docs which mention BaseOffset:

• https://pandas.pydata.org/docs/reference/api/pandas.Period.asfreq.html
• https://pandas.pydata.org/docs/reference/api/pandas.Period.now.html
• https://pandas.pydata.org/docs/reference/api/pandas.tseries.frequencies.to_offset.html

However, BaseOffset isn't user-facing

Should they just be replaced with DateOffset?

This is also relevant for pandas-stubs which uses BaseOffset in a few places

@jbrockmendel is this ok to do?

Based on

pandas/pandas/_libs/tslibs/offsets.pyx

Lines 1620 to 1632 in 0c4ca3a

	class OffsetMeta(type):
	"""
	Metaclass that allows us to pretend that all BaseOffset subclasses
	inherit from DateOffset (which is needed for backward-compatibility).
	"""
	@classmethod
	def __instancecheck__(cls, obj) -> bool:
	return isinstance(obj, BaseOffset)
	@classmethod
	def __subclasscheck__(cls, obj) -> bool:
	return issubclass(obj, BaseOffset)

they should be interchangeable?

[jbrockmendel]

Do type checkers understand the isinstance override behavior? Using BaseOffset strikes me as less likely to cause misunderstandings.

Isn't there a namespace like pd.typing for things that aren't supposed to be used directly by users but can be used for annotation purposes? Seems like BaseOffset would be a good fit there.

[MarcoGorelli]

sure, for type checking that's fine

but for public-facing docs, BaseOffset isn't documented, shouldn't DateOffset be used there?