Skip to content

DOC: fix timestamp timedelta quotes #25118

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.

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 20 commits into from
Mar 30, 2019
Merged
Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
dc0b8c3
TST: clean up to change setup.cfg to `xfail_strict = True` (GH23057)
Nov 15, 2018
2bac2c6
TST: clean up to change setup.cfg to `xfail_strict = True` edit (GH23…
Nov 15, 2018
f645380
TST: clean up to change setup.cfg to `xfail_strict = True` edit2 (GH2…
Nov 16, 2018
b0b23b9
TST: remove redundant `strict=True` parameter (GH23057)
Nov 17, 2018
e2261f9
Merge branch 'master' of github.com:pandas-dev/pandas
Nov 18, 2018
ac0003f
Merge branch 'master' of github.com:pandas-dev/pandas
Nov 20, 2018
a02a7b4
Merge remote-tracking branch 'upstream/master'
Dec 3, 2018
bd97e5e
Merge remote-tracking branch 'upstream/master'
Jan 25, 2019
6e2fb3a
Merge branch 'master' of https://github.com/pandas-dev/pandas
Feb 2, 2019
099cd57
Merge branch 'master' of https://github.com/pandas-dev/pandas
Feb 3, 2019
7815ef0
DOC: Reposition quotes in pandas.Timestamp and pandas.Timedelta #24070
Feb 3, 2019
bc1fb28
DOC: edit nattype.pyx to match changes in timedeltas.pyx
Feb 3, 2019
2aec3e1
DOC: make timedeltas.pyx to_pytimedelta an actual docstring
Feb 4, 2019
b84ef90
DOC: small edits to pandas.Timestamp docstring
Feb 5, 2019
c09d83a
DOC: consolidate pandas.Timedelta.to_pytimedelta docstring
Feb 6, 2019
27c97d1
DOC: corrections to timedeltas.pyx docstrings
Mar 4, 2019
fd0de80
DOC: adjust indentation of docstring example
Mar 5, 2019
6349040
DOC: another correction
Mar 6, 2019
5cb7828
DOC: correct pandas.Timestamp.to_datetime64
Mar 29, 2019
549633d
DOC: delete examples for pandas.Timedelta.to_pytimedelta
Mar 29, 2019
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
2 changes: 1 addition & 1 deletion pandas/_libs/tslibs/nattype.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ cdef class _NaT(datetime):

def total_seconds(self):
"""
Total duration of timedelta in seconds (to ns precision)
Total duration of timedelta in seconds (to ns precision).
"""
# GH#10939
return np.nan
Expand Down
48 changes: 41 additions & 7 deletions pandas/_libs/tslibs/timedeltas.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -815,28 +815,62 @@ cdef class _Timedelta(timedelta):

cpdef timedelta to_pytimedelta(_Timedelta self):
"""
return an actual datetime.timedelta object
note: we lose nanosecond resolution if any
Convert a Timedelta object into a python datetime.timedelta object.

Timedelta objects are internally saved as numpy datetime64[ns] dtype.
Use to_pytimedelta() to convert to object dtype.

Returns
-------
datetime.timedelta or numpy.array of datetime.timedelta

See Also
--------
to_timedelta : Convert argument to Timedelta type.

Notes
-----
Any nanosecond resolution will be lost.

Examples
--------
Copy link
Contributor

Choose a reason for hiding this comment

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

not sure i would add all of these examples, 1 example at most and it should actually use this function

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@jreback
I've made these changes: c09d83a
If there's anything else, please let me know.

Copy link
Contributor

Choose a reason for hiding this comment

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

Do these doctests pass? It looks like the whitespace formatting is off.

You may need to add a doctest: +NORMALIZE_WHITESPACE

Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think any of these examples are needed, they are not showing this internal rountine. I would simply remove them.

Copy link
Contributor

Choose a reason for hiding this comment

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

@dcreekp as I said above I would remove all of these examples

>>> idx = pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
>>> idx
TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015',
NaT],
dtype='timedelta64[ns]', freq=None)

>>> idx.to_pytimedelta()
array([datetime.timedelta(1, 21901, 30), datetime.timedelta(0, 0, 16),
NaT], dtype=object)
Copy link
Contributor

Choose a reason for hiding this comment

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

this should be indented. to align with the d in datetime.

Copy link
Contributor Author

@dcreekp dcreekp Mar 5, 2019

Choose a reason for hiding this comment

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

$ python scripts/validate_docstrings.py pandas.Timedelta.to_pytimedelta

################################################################################
################# Docstring (pandas.Timedelta.to_pytimedelta)  #################
################################################################################

Convert a Timedelta object into a python datetime.timedelta object.

Timedelta objects are internally saved as numpy datetime64[ns] dtype.
Use to_pytimedelta() to convert to object dtype.

Returns
-------
datetime.timedelta or numpy.array of datetime.timedelta

See Also
--------
to_timedelta : Convert argument to Timedelta type.

Notes
-----
Any nanosecond resolution will be lost.

Examples
--------
>>> idx = pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
>>> idx
TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015',
               NaT],
               dtype='timedelta64[ns]', freq=None)

>>> idx.to_pytimedelta()
array([datetime.timedelta(1, 21901, 30), datetime.timedelta(0, 0, 16),
NaT], dtype=object)
>>> idx[1].to_pytimedelta()
datetime.timedelta(0, 0, 16)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Timedelta.to_pytimedelta" correct. :)

It passed but I changed it to your spec.

I also found NORMALIZE_WHITESPACE in validate_docstrings.py line 517

    @property
    def examples_errors(self):
        flags = doctest.NORMALIZE_WHITESPACE | doctest.IGNORE_EXCEPTION_DETAIL
        finder = doctest.DocTestFinder()
        runner = doctest.DocTestRunner(optionflags=flags)
        ...

@TomAugspurger

>>> idx[1].to_pytimedelta()
datetime.timedelta(0, 0, 16)
"""
return timedelta(microseconds=int(self.value) / 1000)

def to_timedelta64(self):
""" Returns a numpy.timedelta64 object with 'ns' precision """
"""
Return a numpy.timedelta64 object with 'ns' precision.
"""
return np.timedelta64(self.value, 'ns')

def total_seconds(self):
"""
Total duration of timedelta in seconds (to ns precision)
Total duration of timedelta in seconds (to ns precision).
"""
return self.value / 1e9

def view(self, dtype):
""" array view compat """
"""
Array view compatibility.
"""
return np.timedelta64(self.value).view(dtype)

@property
def components(self):
""" Return a Components NamedTuple-like """
"""
Return a components namedtuple-like.
"""
self._ensure_components()
# return the named tuple
return Components(self._d, self._h, self._m, self._s,
Expand Down Expand Up @@ -1135,8 +1169,8 @@ class Timedelta(_Timedelta):
Notes
-----
The ``.value`` attribute is always in ns.

"""

def __new__(cls, object value=_no_input, unit=None, **kwargs):
cdef _Timedelta td_base

Expand Down
7 changes: 4 additions & 3 deletions pandas/_libs/tslibs/timestamps.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -526,7 +526,8 @@ cdef class _Timestamp(datetime):


class Timestamp(_Timestamp):
"""Pandas replacement for datetime.datetime
"""
Pandas replacement for python datetime.datetime object.

Timestamp is the pandas equivalent of python's Datetime
and is interchangeable with it in most cases. It's the type used
Expand All @@ -536,9 +537,9 @@ class Timestamp(_Timestamp):
Parameters
----------
ts_input : datetime-like, str, int, float
Value to be converted to Timestamp
Value to be converted to Timestamp.
freq : str, DateOffset
Offset which Timestamp will have
Offset which Timestamp will have.
tz : str, pytz.timezone, dateutil.tz.tzfile or None
Time zone for time which Timestamp will have.
unit : str
Expand Down