DOC: Timestamp EX01 errors #37904

lucasrodes · 2020-11-16T23:58:34Z

Example section added for several methods in class pd.Timestamp

xref DOC: Fix EX01 issues in docstrings #37875
tests added / passed
passes black pandas
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

Examples added for:

pandas.Timestamp.asm8
pandas.Timestamp.day_of_week
pandas.Timestamp.day_of_year
pandas.Timestamp.days_in_month
pandas.Timestamp.is_leap_year
pandas.Timestamp.is_month_end
pandas.Timestamp.is_month_start
pandas.Timestamp.is_quarter_end
pandas.Timestamp.is_quarter_start
pandas.Timestamp.is_year_end
pandas.Timestamp.is_year_start
pandas.Timestamp.quarter
pandas.Timestamp.tz
pandas.Timestamp.week
pandas.Timestamp.ceil
pandas.Timestamp.combine
pandas.Timestamp.day_name
pandas.Timestamp.floor
pandas.Timestamp.fromordinal
pandas.Timestamp.fromtimestamp
pandas.Timestamp.month_name
pandas.Timestamp.normalize
pandas.Timestamp.now
pandas.Timestamp.replace
pandas.Timestamp.round
pandas.Timestamp.strftime
pandas.Timestamp.timestamp
pandas.Timestamp.to_numpy
pandas.Timestamp.to_julian_date
pandas.Timestamp.to_period
pandas.Timestamp.to_pydatetime
pandas.Timestamp.today
pandas.Timestamp.tz_convert
pandas.Timestamp.tz_localize
pandas.Timestamp.utcfromtimestamp
pandas.Timestamp.utcnow
pandas.Timestamp.weekday

…tcfromtimestamp, fromtimestamp, combine. Typos in ceil, round, floor corrected

lucasrodes · 2020-11-17T11:43:13Z

From the checks, I believe that there are some docstrings that were not supposed to be changed?

I am starting to contribute and trying to follow up on this #17327

jreback

looks good a couple of comments. pls merge master and ping on green.

pandas/_libs/tslibs/timestamps.pyx

jreback · 2020-11-19T02:45:51Z

pandas/_libs/tslibs/timestamps.pyx

+        Timestamp('2020-03-14 15:32:00')
+        >>> ts.floor(freq='S') # seconds
+        Timestamp('2020-03-14 15:32:52')
+        >>> ts.floor(freq='L') # miliseconds


prob can show just a few rather than all

pandas/_libs/tslibs/timestamps.pyx

jreback · 2020-11-20T03:14:40Z

can you merge master and ping on green (to make sure no failures are real).

lucasrodes · 2020-11-20T16:07:23Z

Added few changes to pandas/_libs/tslibs/nattype.pyx so the docstrings match (this check is done by test attached below). Should pass the tests now, I'll ping you once the checks finish.

pandas/pandas/tests/scalar/test_nat.py

Line 326 in 456fcb9

def test_nat_doc_strings(compare):

lucasrodes · 2020-11-24T16:16:05Z

@jreback changes reverted

jreback · 2020-11-25T23:42:01Z

Sure @jreback, can do that. However, this pull request won't go through the tests as I mentioned before (won't be green). Should we merge it regardless?

oh how is master passing now then?

yeah this needs to be green. ok i guess re-revert. the only thing with the NaT tests is that they should be showing NaT int he examples

lucasrodes · 2020-11-26T11:33:31Z

Hi @jreback ,
The test I attach below is checking if the docstrings between methods in pandas/_libs/tslibs/nattype.pyx and pandas/_libs/tslibs/timestamps.pyx match. That's why I also used pd.Timestamp instead of pd.NaT.

pandas/pandas/tests/scalar/test_nat.py

Line 326 in 456fcb9

def test_nat_doc_strings(compare):

Should we maybe change the test pandas/pandas/tests/scalar/test_nat.py in onther PR?

jreback · 2020-11-26T16:49:52Z

Hi @jreback ,
The test I attach below is checking if the docstrings between methods in pandas/_libs/tslibs/nattype.pyx and pandas/_libs/tslibs/timestamps.pyx match. That's why I also used pd.Timestamp instead of pd.NaT.

pandas/pandas/tests/scalar/test_nat.py

Line 326 in 456fcb9

def test_nat_doc_strings(compare):

Should we maybe change the test pandas/pandas/tests/scalar/test_nat.py in onther PR?

ok instead let's use the same doc-string, BUT add a NaT example to it, this should make tests pass and make the examples useful.

ping on green.

lucasrodes · 2020-11-27T15:05:48Z

Error in the following test from pandas/tests/io/test_gcs.py in Windows. Not sure what is causing it.

pandas/pandas/tests/io/test_gcs.py

Lines 83 to 119 in 5abc06f

    
           def test_to_csv_compression_encoding_gcs(gcs_buffer, compression_only, encoding): 
        
               """ 
        
               Compression and encoding should with GCS. 
        
               GH 35677 (to_csv, compression), GH 26124 (to_csv, encoding), and 
        
               GH 32392 (read_csv, encoding) 
        
               """ 
        
               from fsspec import registry 
        
               registry.target.clear()  # remove state 
        
               df = tm.makeDataFrame() 
        
               # reference of compressed and encoded file 
        
               compression = {"method": compression_only} 
        
               if compression_only == "gzip": 
        
                   compression["mtime"] = 1  # be reproducible 
        
               buffer = BytesIO() 
        
               df.to_csv(buffer, compression=compression, encoding=encoding, mode="wb") 
        
               # write compressed file with explicit compression 
        
               path_gcs = "gs://test/test.csv" 
        
               df.to_csv(path_gcs, compression=compression, encoding=encoding) 
        
               assert gcs_buffer.getvalue() == buffer.getvalue() 
        
               read_df = read_csv( 
        
                   path_gcs, index_col=0, compression=compression_only, encoding=encoding 
        
               ) 
        
               tm.assert_frame_equal(df, read_df) 
        
               # write compressed file with implicit compression 
        
               if compression_only == "gzip": 
        
                   compression_only = "gz" 
        
               compression["method"] = "infer" 
        
               path_gcs += f".{compression_only}" 
        
               df.to_csv(path_gcs, compression=compression, encoding=encoding) 
        
               assert gcs_buffer.getvalue() == buffer.getvalue() 
        
               read_df = read_csv(path_gcs, index_col=0, compression="infer", encoding=encoding) 
        
               tm.assert_frame_equal(df, read_df)

lucasrodes · 2020-11-27T15:07:08Z

On another note:

Hi @jreback, thanks for your feedback.

Let me summarize last commits below.

1) `NaT` examples added

I have added examples with NaT in the docstrings of the following functions in nattype.pyx and timestamps.pyx:

tz_convert
tz_localize
today
to_pydatetime
to_numpy
round
replace
now
month_name
floor
day_name
ceil

Hence, these methods now have the same docstring in both modules and should pass the tests ✔️.

2) `NaT` examples not added

Next, I have not added NaT examples in the following examples as these methods basically raise a ValueError if called from a NaT object. However I have copied the docstrings from timestamps.pyx (otherwise tests are not passed).

utcnow
utcfromtimestamp
timestamp
strftime
fromtimestamp
fromordinal
combine
astimezone

Note that these methods were created using method _make_error_func instead of _make_nat_func or _make_nan_func.

As these methods now have the same docstring in both modules and should pass the tests ✔️.

3) Way forward

From here I see three ways out:

A) Review of this PR, iterate and merge.
B) Remove the Example section from all methods listed in 2) in both modules (so docstrings still match), commit, review and merge PR.
C) Review the tests in test_nat.pyx. In particular the parametrization of compare. Probably another PR is required.

pandas/pandas/tests/scalar/test_nat.py

Lines 319 to 334 in 11a5a4b

    
           @pytest.mark.parametrize( 
        
               "compare", 
        
               ( 
        
                   _get_overlap_public_nat_methods(Timestamp, True) 
        
                   + _get_overlap_public_nat_methods(Timedelta, True) 
        
               ), 
        
           ) 
        
           def test_nat_doc_strings(compare): 
        
               # see gh-17327 
        
               # 
        
               # The docstrings for overlapping methods should match. 
        
               klass, method = compare 
        
               klass_doc = getattr(klass, method).__doc__ 
        
               nat_doc = getattr(NaT, method).__doc__ 
        
               assert klass_doc == nat_doc

github-actions · 2020-12-28T00:21:28Z

This pull request is stale because it has been open for thirty days with no activity. Please update or respond to this comment if you're still interested in working on this.

jreback · 2020-12-28T00:40:09Z

@lucasrodes i am ok prob merging this as is, if you can merge master and ping

jreback · 2021-02-11T01:37:20Z

@lucasrodes this was close. if you can merge master and see if can get all passing.

lucasrodes · 2021-02-13T14:49:46Z

Sorry for the late reply @jreback. Will do asap

lucasrodes · 2021-02-17T20:07:40Z

@jreback merged with master

mroeschke · 2021-03-21T00:40:27Z

pandas/_libs/tslibs/nattype.pyx

+        Add 'Europe/Stockholm' as timezone:
+
+        >>> ts.tz_localize(tz='Europe/Stockholm')
+        Timestamp('2020-03-14 15:32:52.192548651+0100', tz='Europe/Stockholm'


Missing an ending )

mroeschke · 2021-03-21T00:42:43Z

Sorry for the long delay @lucasrodes . Looks mostly good. One comment otherwise LGTM

lucasrodes · 2021-03-21T15:08:25Z

@mroeschke Merged with upstream & fixed typos (missing '(' in docstring examples)

mroeschke · 2021-04-30T00:47:25Z

Thanks @lucasrodes! Apologies for the long wait getting this one in.

* SS01 errors fixed * trailing-whitespace error fixed * added coded to code_checks.sh script * fixed docstrings consistency * mistaken file * trailing-whitespace typo * Example section for ceil method * Added example section for ceil, floor and round * example section added to methods day_name, month_name, fromordinal, utcfromtimestamp, fromtimestamp, combine. Typos in ceil, round, floor corrected * trailing whitespace * typo in floor method * added example section for method normalize * typo * recommendations from pull request review * typo * revert changes. to be addressed in another PR * Added NaT examples in nattype and timestamp docstrings where needed. * trigger GitHub actions * added missing ( in docstring examples * added missing ( in docstring example Co-authored-by: lucasrodes <lucasrodesg@gmail.com>

luikn added 17 commits November 14, 2020 18:48

SS01 errors fixed

85f8193

trailing-whitespace error fixed

f459a0b

merge with upstream

31f4484

added coded to code_checks.sh script

b6a0da2

fixed docstrings consistency

90abe5d

mistaken file

e99135b

merge upstream

ac70cf4

merge upstream

1e132b5

trailing-whitespace typo

88131f8

merge master

ee3838d

merge upstream

cf5f4f1

Example section for ceil method

badea7b

Added example section for ceil, floor and round

d49c16d

example section added to methods day_name, month_name, fromordinal, u…

b5b26f3

…tcfromtimestamp, fromtimestamp, combine. Typos in ceil, round, floor corrected

trailing whitespace

3793584

typo in is_quarter_start

696d4d4

typo in floor method

12e560c

lucasrodes changed the title ~~Feature/docstrings errors~~ DOC: Timestamp EX01 errors Nov 16, 2020

luikn added 2 commits November 17, 2020 00:06

added example section for method normalize

8897d30

typo

45bafac

jreback requested changes Nov 19, 2020

View reviewed changes

jreback added Docs Datetime Datetime data dtype labels Nov 19, 2020

luikn added 2 commits November 19, 2020 22:16

merge upstream

b5b465a

recommendations from pull request review

f6bb54e

luikn added 2 commits November 20, 2020 16:01

typo

2f7a124

merge upstream

c21ebd0

lucasrodes added 4 commits November 26, 2020 16:56

merge upstream

50add86

Added NaT examples in nattype and timestamp docstrings where needed.

1563e39

merge upstream

710f216

trigger GitHub actions

83edb1c

github-actions bot added the Stale label Dec 28, 2020

Merge branch 'master' into feature/docstrings-errors

cfcf7b6

mroeschke reviewed Mar 21, 2021

View reviewed changes

mroeschke removed the Stale label Mar 21, 2021

lucas rg added 3 commits March 21, 2021 10:47

Merge branch 'master' into feature/docstrings-errors

7a09df2

added missing ( in docstring examples

c622449

added missing ( in docstring example

bcbf195

mroeschke approved these changes Mar 21, 2021

View reviewed changes

mroeschke added this to the 1.3 milestone Mar 21, 2021

mroeschke merged commit 0acbff8 into pandas-dev:master Apr 30, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Timestamp EX01 errors #37904

DOC: Timestamp EX01 errors #37904

lucasrodes commented Nov 16, 2020 •

edited

Loading

lucasrodes commented Nov 17, 2020

jreback left a comment

jreback Nov 19, 2020

jreback commented Nov 20, 2020

lucasrodes commented Nov 20, 2020 •

edited

Loading

lucasrodes commented Nov 24, 2020

jreback commented Nov 25, 2020

lucasrodes commented Nov 26, 2020

jreback commented Nov 26, 2020

lucasrodes commented Nov 27, 2020

lucasrodes commented Nov 27, 2020

github-actions bot commented Dec 28, 2020

jreback commented Dec 28, 2020

jreback commented Feb 11, 2021

lucasrodes commented Feb 13, 2021

lucasrodes commented Feb 17, 2021

mroeschke Mar 21, 2021

mroeschke commented Mar 21, 2021

lucasrodes commented Mar 21, 2021

mroeschke commented Apr 30, 2021

DOC: Timestamp EX01 errors #37904

DOC: Timestamp EX01 errors #37904

Conversation

lucasrodes commented Nov 16, 2020 • edited Loading

lucasrodes commented Nov 17, 2020

jreback left a comment

Choose a reason for hiding this comment

jreback Nov 19, 2020

Choose a reason for hiding this comment

jreback commented Nov 20, 2020

lucasrodes commented Nov 20, 2020 • edited Loading

lucasrodes commented Nov 24, 2020

jreback commented Nov 25, 2020

lucasrodes commented Nov 26, 2020

jreback commented Nov 26, 2020

lucasrodes commented Nov 27, 2020

lucasrodes commented Nov 27, 2020

1) NaT examples added

2) NaT examples not added

3) Way forward

github-actions bot commented Dec 28, 2020

jreback commented Dec 28, 2020

jreback commented Feb 11, 2021

lucasrodes commented Feb 13, 2021

lucasrodes commented Feb 17, 2021

mroeschke Mar 21, 2021

Choose a reason for hiding this comment

mroeschke commented Mar 21, 2021

lucasrodes commented Mar 21, 2021

mroeschke commented Apr 30, 2021

lucasrodes commented Nov 16, 2020 •

edited

Loading

lucasrodes commented Nov 20, 2020 •

edited

Loading

1) `NaT` examples added

2) `NaT` examples not added