API: make Timestamp/Timedelta _as_unit public as_unit

[jbrockmendel]

• closes #xxxx (Replace xxxx with the Github issue number)
• Tests added and passed if fixing a bug or adding a new feature
• All code checks passed.
• Added type annotations to new arguments/methods/functions.
• Added an entry in the latest doc/source/whatsnew/vX.X.X.rst file if fixing a bug or adding a new feature.

[mroeschke]

Could you add an Examples section too? (Hoping to have all public APIs have examples in the near future)

[jbrockmendel]

that would make sense, but first i think we should determine if we want unit to somehow show up in the repr

[mroeschke]

Hmm, frequency didn't end up in the repr before right? (just as a comparison note)

[jbrockmendel]

In 1.5.x freq is in the repr when it is non-None

[mroeschke]

Might be helpful then to have the unit resolution show up in the repr then (guess it would be an API change)

[jbrockmendel]

yah that's on my todo list, just not a priority ATM

[jbrockmendel]

@jreback mentioned this earlier this week

[jbrockmendel]

Following today's call, I'm leaning towards changing "reso" to "creso" for the cdef methods and "unit" to "reso" for the python methods.

[jbrockmendel]

After spending more time on this, im again really reticent to use "reso" and "as_reso" for the public keyword/attribute/method referring to the unit abbreviation (s, ms, us, ns). "unit" is just used everywhere else. DatetimeTZDtype refers to it as .unit. numpy docs call it unit (though it isnt a keyword in the dt64/td64 constructors). IIUC pyarrow dtypes have a .unit attribute for this.

I think the public-facing keyword/attribute/method should be unit/unit/as_unit. The argument against has been that in the constructors this means "unit" plays two roles: 1) how to interpret int inputs, 2) how to represent the data internally. Increasingly I think that if a user passes ints and unit="s", it makes more sense to keep this as second-resolution than cast to nanosecond (and should be more performant). Moreover, doing this would avoid some overflow cases.

That leaves cases where a user passes a unit that is supported for input but not for storage, i.e. Y, M, D, h, m. For these we'd treat the inputs the same and use the closest-supported (i.e. second) for storage.

Thoughts?

[mroeschke]

I think the public-facing keyword/attribute/method should be unit/unit/as_unit

Yeah I would be okay if the "problematic" situation of to_datetime/to_timedelta/Timestamp/TImedelta(ints, unit="s") to interpret [ints] as epoch seconds and having the resulting unit be seconds, so having the public naming be unit would be okay to me.

[jbrockmendel]

all good here? we have the option of changing unit->reso later, but for now id like to get started on some follow-ups to this.

[mroeschke]

LGTM. I am still partial to unit over reso (for now). Good to have examples in as_unit once the unit-in-the-repr question is resolved.

[mroeschke]

Thanks @jbrockmendel