DOC: Meaning of Timestamp freq attribute is unclear in docs

[nmusolino]

Problem description

The freq attribute of the pandas.Timestamp class is not well explained on the class's documentation page.

For background, there is an existing issue #15146 which proposes removing the freq attribute. I agree with that proposal, although I don't know how much technical complexity weighs against that.

If pandas decides not to deprecate/remove it, the documentation for it should be improved. The current (version 0.24.1) documentation reads:

ts_input : datetime-like, str, int, float
     Value to be converted to Timestamp
freq : str, DateOffset                                <----
     Offset which Timestamp will have                 <----
tz : str, pytz.timezone, dateutil.tz.tzfile or None
    Time zone for time which Timestamp will have.

The Timestamp class or datetime.datetime class represents a point in time, an instant. There is no "offset" that a time point has, semantically speaking.

As far as I can tell, the role of freq is (1) to provide an implicit timedelta for Timestamp + integer operations, which are now deprecated, and (2) to provide a default in Timestamp.to_period() when that method's freq argument is None.

The freq value does not influence equality comparisons between Timestamp objects, and does not influence the hash of a Timestamp object. It is dropped in a few Timestamp transformations like tz localization

It's hard for me to suggest what the documentation should be here, since the attribute seems like a vestige from the days before a Period class, and since it doesn't influence the semantic meaning of a timestamp.

[mroeschke]

I think there's an overall preference to remove this attribute from Timestamp (cc @jbrockmendel), and if that's the case, the work is better spent deprecating this attribute.

[jbrockmendel]

I'd generally like to see freq go. The thing that comes up is what to do with the is_foo_begin properties that rely on freq.

[nmusolino]

For the record, I agree with you, @jbrockmendel , and would like to see freq be deprecated. In a way, the difficulty of writing a succinct description in a docstring is an indicator that it's an awkward fit.

[mroeschke]

freq will be deprecated in 1.3 so I don't think there's a need to document this further. Closing