From dcdf2abed53fbebe7bd0e3a4c1136e5f16a534ea Mon Sep 17 00:00:00 2001 From: Mortada Mehyar Date: Sat, 16 Dec 2017 19:46:05 -0800 Subject: [PATCH] DOC: improve pd.Timestamp docs with more examples and clarify different forms of API usage --- pandas/_libs/tslibs/nattype.pyx | 12 +++++------ pandas/_libs/tslibs/timestamps.pyx | 34 ++++++++++++++++++++++-------- 2 files changed, 31 insertions(+), 15 deletions(-) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index a058b9d7de9c4..086657e8c97b4 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -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. @@ -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 @@ -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 @@ -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 @@ -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. @@ -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. diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 478611fe9cab9..1bbfa1b3aa4d8 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -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. @@ -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 @@ -405,9 +407,23 @@ class Timestamp(_Timestamp): Examples -------- + Using the primary calling convention: + + 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') @@ -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 @@ -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): @@ -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) @@ -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. @@ -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.