Skip to content

DOC: improve pd.Timestamp docs with more examples and clarify differe… #18811

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 20, 2017
Merged

DOC: improve pd.Timestamp docs with more examples and clarify differe… #18811

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions pandas/_libs/tslibs/nattype.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -381,7 +381,7 @@ class NaTType(_NaT):

Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will be converted to.
None will remove timezone holding UTC time.

Expand All @@ -407,7 +407,7 @@ class NaTType(_NaT):
date corresponding to a proleptic Gregorian ordinal
freq : str, DateOffset
Offset which Timestamp will have
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will have.
offset : str, DateOffset
Deprecated, use freq
Expand All @@ -430,7 +430,7 @@ class NaTType(_NaT):

Parameters
----------
tz : string / timezone object, default None
tz : str or timezone object, default None
Timezone to localize to
""")
today = _make_nat_func('today', # noqa:E128
Expand All @@ -443,7 +443,7 @@ class NaTType(_NaT):

Parameters
----------
tz : string / timezone object, default None
tz : str or timezone object, default None
Timezone to localize to
""")
round = _make_nat_func('round', # noqa:E128
Expand Down Expand Up @@ -485,7 +485,7 @@ class NaTType(_NaT):

Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will be converted to.
None will remove timezone holding UTC time.

Expand All @@ -505,7 +505,7 @@ class NaTType(_NaT):

Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will be converted to.
None will remove timezone holding local time.

Expand Down
34 changes: 25 additions & 9 deletions pandas/_libs/tslibs/timestamps.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -369,7 +369,7 @@ cdef class _Timestamp(datetime):
class Timestamp(_Timestamp):
"""Pandas replacement for datetime.datetime

TimeStamp is the pandas equivalent of python's Datetime
Timestamp is the pandas equivalent of python's Datetime
and is interchangable with it in most cases. It's the type used
for the entries that make up a DatetimeIndex, and other timeseries
oriented data structures in pandas.
Expand All @@ -380,10 +380,12 @@ class Timestamp(_Timestamp):
Value to be converted to Timestamp
freq : str, DateOffset
Offset which Timestamp will have
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will have.
unit : string
numpy unit used for conversion, if ts_input is int or float
unit : str
Unit used for conversion if ts_input is of type int or float. The
valid values are 'D', 'h', 'm', 's', 'ms', 'us', and 'ns'. For
example, 's' means seconds and 'ms' means milliseconds.
offset : str, DateOffset
Deprecated, use freq

Expand All @@ -405,9 +407,23 @@ class Timestamp(_Timestamp):

Examples
--------
Using the primary calling convention:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we use this nomenclature above? if not can you reconcile

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes in the above the doc says:

    Notes
    -----
    There are essentially three calling conventions for the constructor. The
    primary form accepts four parameters. They can be passed by position or
    keyword.

    The other two forms mimic the parameters from ``datetime.datetime``. They
    can be passed by either position or keyword, but not both mixed together.


This converts a datetime-like string
>>> pd.Timestamp('2017-01-01T12')
Timestamp('2017-01-01 12:00:00')

This converts a float representing a Unix epoch in units of seconds
>>> pd.Timestamp(1513393355.5, unit='s')
Timestamp('2017-12-16 03:02:35.500000')

This converts an int representing a Unix-epoch in units of seconds
and for a particular timezone
>>> pd.Timestamp(1513393355, unit='s', tz='US/Pacific')
Timestamp('2017-12-15 19:02:35-0800', tz='US/Pacific')

Using the other two forms that mimic the API for ``datetime.datetime``:

>>> pd.Timestamp(2017, 1, 1, 12)
Timestamp('2017-01-01 12:00:00')

Expand All @@ -429,7 +445,7 @@ class Timestamp(_Timestamp):
date corresponding to a proleptic Gregorian ordinal
freq : str, DateOffset
Offset which Timestamp will have
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will have.
offset : str, DateOffset
Deprecated, use freq
Expand All @@ -447,7 +463,7 @@ class Timestamp(_Timestamp):

Parameters
----------
tz : string / timezone object, default None
tz : str or timezone object, default None
Timezone to localize to
"""
if is_string_object(tz):
Expand All @@ -465,7 +481,7 @@ class Timestamp(_Timestamp):

Parameters
----------
tz : string / timezone object, default None
tz : str or timezone object, default None
Timezone to localize to
"""
return cls.now(tz)
Expand Down Expand Up @@ -774,7 +790,7 @@ class Timestamp(_Timestamp):

Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will be converted to.
None will remove timezone holding local time.

Expand Down Expand Up @@ -828,7 +844,7 @@ class Timestamp(_Timestamp):

Parameters
----------
tz : string, pytz.timezone, dateutil.tz.tzfile or None
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will be converted to.
None will remove timezone holding UTC time.

Expand Down