Resolution docstring #21122

chalmerlowe · 2018-05-18T16:16:56Z

closes #xxxx
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

################################################################################
################### Docstring (pandas.Timedelta.resolution)  ###################
################################################################################

Return a string representing the lowest (i.e. smallest) time resolution.

Each timedelta has a defined resolution that represents the lowest OR
most granular level of precision. Each level of resolution is
represented by a short string as defined below:

============ ============
Resolution   Return value
============ ============
Days         ``'D'``
Hours        ``'H'``
Minutes      ``'T'``
Seconds      ``'S'``
Milliseconds ``'L'``
Microseconds ``'U'``
Nanoseconds  ``'N'``
============ ============

Returns
-------
str
    Time resolution.

Examples
--------
**Using string input**

>>> td = pd.Timedelta('1 days 2 min 3 us 42 ns')
>>> td.resolution
'N'

>>> td = pd.Timedelta('1 days 2 min 3 us')
>>> td.resolution
'U'

>>> td = pd.Timedelta('2 min 3 s')
>>> td.resolution
'S'

**Using integer input**

>>> td = pd.Timedelta(36, unit='us')
>>> td.resolution
'U'

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

Errors found:
	See Also section not found

…solution-docstring

WillAyd

Thanks for the update! Certainly an improvement - just a minor comment from me but otherwise lgtm

chalmerlowe · 2018-05-18T16:56:43Z

@WillAyd

I am new to contributing to pandas.

What specific changes do you want me to make? I have been looking at this thread and clicking through to various links and I am not sure what changes I should make.

Are your requested changes to that I should tweak the PR to use the three commits marked above with the red xs?

IF yes... I would request some guidance on the matter of the Return values...

When I look at the documentation guide produced for the recent Pandas Documentation Sprints, this guidance is present on how to handle single and multiple return values:

**With a single return value**
Returns
-------
float
    Random number generated.

**With multiple return values**
Returns
-------
length : int
    Length of the returned string.
letters : str
    String of random letters.

Lastly...

I see that ci/circleci failed. When I visited the details, the failure does not appear to be anything related to my change (maybe I am missing something)? Any guidance you can offer is greatly appreciated.

WillAyd · 2018-05-18T17:02:03Z

Not sure what happened to my comment so probably an error on my end, but I was just asking why you had the table and the information directly below it as bullet points. It's the same information (?) so if it's duplicated I would just stick with the table and delete the bullets

Took a quick glance at the CI failures and they are LINT related to your change, so you will want to read through them and fix. The steps to reproduce are below:

https://pandas.pydata.org/pandas-docs/stable/contributing.html#python-pep8

That said, if you have run that locally you probably aren't seeing any errors because the diff in that command is only run against ".py" files and not ".pyx" which you've modified (most users only modify the former). If feeling ambitious that could be another change to update the docs to make sure that that rule covers both .py and .pyx files.

Hope that helps but if you get stuck let me know

chalmerlowe · 2018-05-18T17:05:47Z

Thanks. This helps.
For some reason, I thought I deleted bullets. Sigh. Will do so.
I will go back and rerun the linter checks against the .pyx

codecov · 2018-05-18T17:26:02Z

Codecov Report

Merging #21122 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #21122   +/-   ##
=======================================
  Coverage   91.95%   91.95%           
=======================================
  Files         160      160           
  Lines       49858    49858           
=======================================
  Hits        45845    45845           
  Misses       4013     4013

Flag	Coverage Δ
#multiple	`90.33% <ø> (ø)`	⬆️
#single	`42.08% <ø> (ø)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5cb5880...ce7c795. Read the comment docs.

chalmerlowe · 2018-05-18T23:39:10Z

Fixed the linting problems.
Removed the bulleted items in deference to using the table.

Hope this works!

################################################################################
################### Docstring (pandas.Timedelta.resolution)  ###################
################################################################################

Return a string representing the lowest (i.e. smallest) time resolution.

Each timedelta has a defined resolution that represents the lowest OR
most granular level of precision. Each level of resolution is
represented by a short string as defined below:

============ ============
Resolution   Return value
============ ============
Days         ``'D'``
Hours        ``'H'``
Minutes      ``'T'``
Seconds      ``'S'``
Milliseconds ``'L'``
Microseconds ``'U'``
Nanoseconds  ``'N'``
============ ============

Returns
-------
str
    Time resolution.

Examples
--------
**Using string input**

>>> td = pd.Timedelta('1 days 2 min 3 us 42 ns')
>>> td.resolution
'N'

>>> td = pd.Timedelta('1 days 2 min 3 us')
>>> td.resolution
'U'

>>> td = pd.Timedelta('2 min 3 s')
>>> td.resolution
'S'

**Using integer input**

>>> td = pd.Timedelta(36, unit='us')
>>> td.resolution
'U'

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

WillAyd

Hmm well I am nitpicking but can we get rid of the double backquotes on the return values? Those are typically reserved for literals / code blocks which these technically are not

chalmerlowe · 2018-05-19T03:32:01Z

Removed the backticks. Let me know if we need any additional changes.
This is a good learning experience. I have PRs for Timedelta.delta and Timedelta.asm8 in the wings and this is hopefully setting the stage so those will go more smoothly.

################### Docstring (pandas.Timedelta.resolution)  ###################
################################################################################

Return a string representing the lowest (i.e. smallest) time
resolution.

Each timedelta has a defined resolution that represents the lowest OR
most granular level of precision. Each level of resolution is
represented by a short string as defined below:

============ ============
Resolution   Return value
============ ============
Days         'D'
Hours        'H'
Minutes      'T'
Seconds      'S'
Milliseconds 'L'
Microseconds 'U'
Nanoseconds  'N'
============ ============

Returns
-------
str
    Time resolution.

Examples
--------
**Using string input**

>>> td = pd.Timedelta('1 days 2 min 3 us 42 ns')
>>> td.resolution
'N'

>>> td = pd.Timedelta('1 days 2 min 3 us')
>>> td.resolution
'U'

>>> td = pd.Timedelta('2 min 3 s')
>>> td.resolution
'S'

**Using integer input**

>>> td = pd.Timedelta(36, unit='us')
>>> td.resolution
'U'

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

Errors found:
	See Also section not found

jreback

cc @TomAugspurger

jreback · 2018-05-19T17:50:07Z

pandas/_libs/tslibs/timedeltas.pyx

+        most granular level of precision. Each level of resolution is
+        represented by a short string as defined below:
+
+        ============ ============


I don't think this will render in a doc-string, not really sure what the standard is for a table like list

Do you have a suggestion?
Do bulleted lists work?

- Days: 'D' - Hours: 'H' - Minutes: 'T' - Seconds: 'S' - Milliseconds: 'L' - Microseconds: 'U' - Nanoseconds: 'N'

yep that's prob ok

jreback · 2018-05-19T17:50:38Z

pandas/_libs/tslibs/timedeltas.pyx

+        Returns
+        -------
+        str
+            Time resolution.


Time -> Timedelta

jreback · 2018-05-19T17:50:58Z

pandas/_libs/tslibs/timedeltas.pyx

+
+        Examples
+        --------
+        **Using string input**


you don't need the 'Using string input' or numeric input section

jreback · 2018-05-19T17:51:15Z

pandas/_libs/tslibs/timedeltas.pyx

@@ -770,7 +770,53 @@ cdef class _Timedelta(timedelta):

    @property
    def resolution(self):
-        """ return a string representing the lowest resolution that we have """
+        """
+        Return a string representing the lowest (i.e. smallest) time


this should be a single line

jreback · 2018-06-19T01:43:43Z

can you update for comments

chalmerlowe · 2018-06-19T17:51:04Z

I will update the PR.

jreback · 2018-07-03T16:11:41Z

can you update

chalmerlowe · 2018-07-05T15:55:33Z

@jreback not deliberately ignoring this. will get this done, so this open item can be cleared off the books.

chalmerlowe · 2018-07-07T05:54:51Z

Attempted to resolve the comments above.

################################################################################
################### Docstring (pandas.Timedelta.resolution)  ###################
################################################################################

Return a string representing the lowest timedelta resolution.

Each timedelta has a defined resolution that represents the lowest OR
most granular level of precision. Each level of resolution is
represented by a short string as defined below:

Resolution:     Return value

* Days:         'D'
* Hours:        'H'
* Minutes:      'T'
* Seconds:      'S'
* Milliseconds: 'L'
* Microseconds: 'U'
* Nanoseconds:  'N'

Returns
-------
str
    Timedelta resolution.

Examples
--------
>>> td = pd.Timedelta('1 days 2 min 3 us 42 ns')
>>> td.resolution
'N'

>>> td = pd.Timedelta('1 days 2 min 3 us')
>>> td.resolution
'U'

>>> td = pd.Timedelta('2 min 3 s')
>>> td.resolution
'S'

>>> td = pd.Timedelta(36, unit='us')
>>> td.resolution
'U'

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

Errors found:
	See Also section not found

chalmerlowe · 2018-07-07T07:33:49Z

I tried to look in the Travis CI logs and I am not sure what exactly caused the Travis build to fail. Can someone advise?

mroeschke · 2018-07-07T19:48:10Z

@chalmerlowe There is a linting error:

pandas/_libs/tslibs/timedeltas.pyx:837:4: W291 trailing whitespace

After that fix, LGTM

jreback · 2018-07-07T23:02:50Z

@mroeschke can you push that fix?

jreback · 2018-07-08T12:58:49Z

thanks @chalmerlowe and @mroeschke for the fixup!

chalmerlowe added 13 commits May 15, 2018 12:12

updated docstring for nanoseconds function

4dcb4b4

Merge remote-tracking branch 'upstream/master' into nanosecond-docstring

e0ae113

DOC: updated docstring for nanoseconds function per doc guidelines

11a9266

DOC: added examples to nanoseconds function and minor formatting edits

04e204b

DOC: added example header

5ac6ef1

DOC: added example header and space

fb45759

DOC: fixed minor spelling error

b0977f4

removed trailing whitespace, long lines

85bcb52

Merge remote-tracking branch 'upstream/master' into nanosecond-docstring

841611e

DOC: updates to docstring for nanoseconds function per doc guidelines

4237391

DOC: documentation guide update to resolution docstring

5035798

Merge branch 'master' of https://github.com/pandas-dev/pandas into re…

3de9d58

…solution-docstring

DOC: Improve docstring of Timedelta.resolution

23a8aae

WillAyd requested changes May 18, 2018

View reviewed changes

WillAyd added the Docs label May 18, 2018

DOC: Improve docstring of Timedelta.resolution

2c91847

DOC: Improve the docstring of Timedelta.resolution

83da2fe

WillAyd requested changes May 19, 2018

View reviewed changes

DOC: Improve the docstring of Timedelta.resolution

764f91a

WillAyd approved these changes May 19, 2018

View reviewed changes

WillAyd mentioned this pull request May 19, 2018

DOC: Improve docstring of Timedelta.delta #21135

Closed

4 tasks

jreback requested changes May 19, 2018

View reviewed changes

jreback added the Timedelta Timedelta data type label May 19, 2018

Minor edits as suggested

886f21a

chalmerlowe added 2 commits July 6, 2018 19:46

DOC: Improve the docstring of Timedelta.resolution

5737c67

Merge remote-tracking branch 'upstream/master' into resolution-docstring

bf0def0

jreback added this to the 0.24.0 milestone Jul 7, 2018

Matt Roeschke added 2 commits July 7, 2018 18:09

Merge remote-tracking branch 'upstream/master' into resolution-docstring

1d0d397

remove whitespace

ce7c795

jreback approved these changes Jul 8, 2018

View reviewed changes

jreback merged commit 9fd7db5 into pandas-dev:master Jul 8, 2018

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

Resolution docstring (pandas-dev#21122)

1666a0a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Resolution docstring #21122

Resolution docstring #21122

chalmerlowe commented May 18, 2018

WillAyd left a comment

chalmerlowe commented May 18, 2018

WillAyd commented May 18, 2018

chalmerlowe commented May 18, 2018

codecov bot commented May 18, 2018 •

edited

Loading

chalmerlowe commented May 18, 2018 •

edited

Loading

WillAyd left a comment

chalmerlowe commented May 19, 2018 •

edited

Loading

jreback left a comment

jreback May 19, 2018

chalmerlowe May 19, 2018

jreback May 19, 2018

jreback May 19, 2018

jreback May 19, 2018

jreback May 19, 2018

jreback commented Jun 19, 2018

chalmerlowe commented Jun 19, 2018

jreback commented Jul 3, 2018

chalmerlowe commented Jul 5, 2018

chalmerlowe commented Jul 7, 2018

chalmerlowe commented Jul 7, 2018

mroeschke commented Jul 7, 2018

jreback commented Jul 7, 2018

jreback commented Jul 8, 2018

Resolution docstring #21122

Resolution docstring #21122

Conversation

chalmerlowe commented May 18, 2018

WillAyd left a comment

Choose a reason for hiding this comment

chalmerlowe commented May 18, 2018

WillAyd commented May 18, 2018

chalmerlowe commented May 18, 2018

codecov bot commented May 18, 2018 • edited Loading

Codecov Report

chalmerlowe commented May 18, 2018 • edited Loading

WillAyd left a comment

Choose a reason for hiding this comment

chalmerlowe commented May 19, 2018 • edited Loading

jreback left a comment

Choose a reason for hiding this comment

jreback May 19, 2018

Choose a reason for hiding this comment

chalmerlowe May 19, 2018

Choose a reason for hiding this comment

jreback May 19, 2018

Choose a reason for hiding this comment

jreback May 19, 2018

Choose a reason for hiding this comment

jreback May 19, 2018

Choose a reason for hiding this comment

jreback May 19, 2018

Choose a reason for hiding this comment

jreback commented Jun 19, 2018

chalmerlowe commented Jun 19, 2018

jreback commented Jul 3, 2018

chalmerlowe commented Jul 5, 2018

chalmerlowe commented Jul 7, 2018

chalmerlowe commented Jul 7, 2018

mroeschke commented Jul 7, 2018

jreback commented Jul 7, 2018

jreback commented Jul 8, 2018

codecov bot commented May 18, 2018 •

edited

Loading

chalmerlowe commented May 18, 2018 •

edited

Loading

chalmerlowe commented May 19, 2018 •

edited

Loading