ENH/DOC: call for Timestamp

[adamgreenhall]

When you create a timestamp with a timezone and don't use a keyword argument, it fails silently:

>> pd.Timestamp('2012-01-01', 'US/Pacific')
Timestamp('2012-01-01 00:00:00', tz=None)

[cpcloud]

The second argument is not the timezone, it's the offset. This could maybe use some better documentation if that wasn't already clear somewhere in the docs.

[cpcloud]

Thought ideally, it should fail in this case and not just continue on

[adamgreenhall]

I agree. I don't see an example of creating a standalone pd.Timestamp in the current docs. The docstring could also use some mention of which arguments the function takes.

[jreback]

here
(or in the first section, whatever looks more natural), an example of using Timestamp would be nice

would welcome a PR & docstring update!

[jreback]

@adamgreenhall want to do some docs / example for Timestamp?

maybe update the doc string as well

Timestamp has a different constructor than datetime need to show that

[jorisvandenbossche]

However, there is a problem with documenting Timestamp in the api docs, see #5218. But of course, you can already update the docstring for intereactive use, or start to add a section in the narrative docs.

[jbrockmendel]

Is this handled by #17943, or is there a distinct issue?

[jreback]

yep, want to add a validation test to close this?