DOC: fix timestamp timedelta quotes #25118
Conversation
|
The problem is these ones are still left because pandas inherits these docstrings from cpython's datetime library: |
Codecov Report
@@ Coverage Diff @@
## master #25118 +/- ##
===========================================
- Coverage 92.37% 42.86% -49.51%
===========================================
Files 166 166
Lines 52415 52415
===========================================
- Hits 48418 22469 -25949
- Misses 3997 29946 +25949
Continue to review full report at Codecov.
|
Codecov Report
@@ Coverage Diff @@
## master #25118 +/- ##
==========================================
- Coverage 92.37% 91.79% -0.58%
==========================================
Files 166 174 +8
Lines 52415 52536 +121
==========================================
- Hits 48418 48227 -191
- Misses 3997 4309 +312
Continue to review full report at Codecov.
|
|
This doesn't entirely close #24070, right? Do we have a plan for the problematic inherited docstrings? Rewrite to be compliant, or add skips for those? |
|
@TomAugspurger sorry I should of mentioned I created another issue to discuss/address the situation. |
pandas/_libs/tslibs/timedeltas.pyx
Outdated
| @@ -815,28 +815,34 @@ cdef class _Timedelta(timedelta): | |||
|
|
|||
| cpdef timedelta to_pytimedelta(_Timedelta self): | |||
| """ | |||
| return an actual datetime.timedelta object | |||
| note: we lose nanosecond resolution if any | |||
| Return an actual datetime.timedelta object. | |||
There was a problem hiding this comment.
can you make this an actual doc-string (e.g. have a Notes section)
There was a problem hiding this comment.
@jreback I ended up editting the whole doc-string...
pandas/_libs/tslibs/timedeltas.pyx
Outdated
| Any nanosecond resolution will be lost. | ||
|
|
||
| Examples | ||
| -------- |
There was a problem hiding this comment.
not sure i would add all of these examples, 1 example at most and it should actually use this function
There was a problem hiding this comment.
Do these doctests pass? It looks like the whitespace formatting is off.
You may need to add a doctest: +NORMALIZE_WHITESPACE
There was a problem hiding this comment.
I don't think any of these examples are needed, they are not showing this internal rountine. I would simply remove them.
There was a problem hiding this comment.
@dcreekp as I said above I would remove all of these examples
dcreekp
changed the title
|
@TomAugspurger @jreback |
|
@datapythonista we talked about this PR at the sprint the other day |
|
@dcreekp you need to respond to comments. |
There was a problem hiding this comment.
Looks good, just few minor things.
For the next time, if you're working on the formatting (line breaks, capitalization...) of many docstrings, avoid working on the content of a docstring in the same PR.
It's better to review to have a whole PR of minor formatting changes, or a full docstring refactored, but not both in the same PR.
pandas/_libs/tslibs/timedeltas.pyx
Outdated
| @@ -815,28 +815,63 @@ cdef class _Timedelta(timedelta): | |||
|
|
|||
| cpdef timedelta to_pytimedelta(_Timedelta self): | |||
| """ | |||
| return an actual datetime.timedelta object | |||
| note: we lose nanosecond resolution if any | |||
| Converts a Timedelta object into a python datetime.timedelta object. | |||
There was a problem hiding this comment.
Convert instead of Converts
I think it'd be more clear: Convert a pandas Timedelta object into a python timedelta object.
pandas/_libs/tslibs/timedeltas.pyx
Outdated
| -------- | ||
| Converting an array of Timedeltas: | ||
|
|
||
| >>> arr = pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan']) |
There was a problem hiding this comment.
our convention is to use idx instead of arr
pandas/_libs/tslibs/timedeltas.pyx
Outdated
| note: we lose nanosecond resolution if any | ||
| Converts a Timedelta object into a python datetime.timedelta object. | ||
|
|
||
| Timedelta objects are typecast to numpy datetime64[ns] dtype, |
There was a problem hiding this comment.
internally saved as instead of typecast to would wound better to me
I'd use a stop mark to separate the second sentence instead of a comma, would make this easier to read.
convert back -> convert
|
@datapythonista I've made changes and a comment |
pandas/_libs/tslibs/timedeltas.pyx
Outdated
| Any nanosecond resolution will be lost. | ||
|
|
||
| Examples | ||
| -------- |
There was a problem hiding this comment.
Do these doctests pass? It looks like the whitespace formatting is off.
You may need to add a doctest: +NORMALIZE_WHITESPACE
pandas/_libs/tslibs/timedeltas.pyx
Outdated
|
|
||
| >>> idx.to_pytimedelta() | ||
| array([datetime.timedelta(1, 21901, 30), datetime.timedelta(0, 0, 16), | ||
| NaT], dtype=object) |
There was a problem hiding this comment.
this should be indented. to align with the d in datetime.
There was a problem hiding this comment.
$ 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)
...
pandas/_libs/tslibs/timedeltas.pyx
Outdated
| Any nanosecond resolution will be lost. | ||
|
|
||
| Examples | ||
| -------- |
There was a problem hiding this comment.
I don't think any of these examples are needed, they are not showing this internal rountine. I would simply remove them.
|
I just want to clarify; the docstings is for this function and am I not using it?? @jreback |
pandas/_libs/tslibs/timedeltas.pyx
Outdated
| Any nanosecond resolution will be lost. | ||
|
|
||
| Examples | ||
| -------- |
There was a problem hiding this comment.
@dcreekp as I said above I would remove all of these examples
|
@jreback deleted. |
|
thanks @dcreekp
|
git diff upstream/master -u -- "*.py" | flake8 --diff