Doc: Update the DatetimeIndex.strftime docstring #20103

Tushar987 · 2018-03-10T09:30:58Z

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
################## Docstring (pandas.DatetimeIndex.strftime)  ##################
################################################################################

Convert to specified date_format.

Return an array of formatted strings specified by date_format, which
supports the same string format as the python standard library. Details
of the string format can be found in `python string format doc <https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior>`__

Parameters
----------
date_format : str
    Date format string (e.g. "%Y-%m-%d").

Returns
-------
numpy.ndarray
    n-dimensional array of formatted strings

See Also
--------
DatetimeIndex.normalize : Return DatetimeIndex with times to midnight.
DatetimeIndex.round : Round the DatetimeIndex to the specified freq.
DatetimeIndex.floor : Floor the DatetimeIndex to the specified freq.

Examples
--------
>>> data = ['2015-05-01 18:47:05.060000','2014-05-01 18:47:05.110000']
>>> df = pd.DataFrame(data, columns=['date'])
>>> df.date = pd.to_datetime(df.date)
>>> df.date[1]
Timestamp('2014-05-01 18:47:05.110000')
>>> df.date[1].strftime('%d-%m-%Y')
'01-05-2014'
>>> df.date[1].strftime('%B %d, %Y, %r')
'May 01, 2014, 06:47:05 PM'

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

Docstring for "pandas.DatetimeIndex.strftime" correct. :)

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

jorisvandenbossche

Thanks for the PR! Added some comments

jorisvandenbossche · 2018-03-10T09:49:20Z

pandas/core/indexes/datetimelike.py

@@ -61,18 +61,39 @@ def strftime(self, date_format):
        return np.asarray(self.format(date_format=date_format),
                          dtype=compat.text_type)
    strftime.__doc__ = """
+    Convert to specified date_format.


Maybe mention it is converted to a string?

jorisvandenbossche · 2018-03-10T09:51:46Z

pandas/core/indexes/datetimelike.py

+    --------
+    DatetimeIndex.normalize : Return DatetimeIndex with times to midnight.
+    DatetimeIndex.round : Round the DatetimeIndex to the specified freq.
+    DatetimeIndex.floor : Floor the DatetimeIndex to the specified freq.


I would also link to the similar conversion but other way around: to_datetime

jorisvandenbossche · 2018-03-10T09:53:12Z

pandas/core/indexes/datetimelike.py

+    >>> df.date[1].strftime('%d-%m-%Y')
+    '01-05-2014'
+    >>> df.date[1].strftime('%B %d, %Y, %r')
+    'May 01, 2014, 06:47:05 PM'


The docstring is from DatetimeIndex. Can you update the example to use that? (so eg create an example dataframe with DatetimeIndex with eg pd.date_range)

jorisvandenbossche · 2018-03-10T09:56:45Z

pandas/core/indexes/datetimelike.py


    Returns
    -------
-    ndarray of formatted strings
+    numpy.ndarray
+        n-dimensional array of formatted strings


I would just say "NumPy array" instead of "n-dimensional", as it is always 1D

@jorisvandenbossche separate issue, this should actually return an Index here.

codecov · 2018-03-10T14:10:56Z

Codecov Report

Merging #20103 into master will decrease coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #20103      +/-   ##
==========================================
- Coverage   91.72%    91.7%   -0.03%     
==========================================
  Files         150      150              
  Lines       49149    49149              
==========================================
- Hits        45083    45071      -12     
- Misses       4066     4078      +12

Flag	Coverage Δ
#multiple	`90.08% <ø> (-0.03%)`	⬇️
#single	`41.85% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/indexes/datetimelike.py	`96.7% <ø> (ø)`	⬆️
pandas/plotting/_converter.py	`65.07% <0%> (-1.74%)`	⬇️

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 4131149...8decfa7. Read the comment docs.

jreback · 2018-03-13T23:19:29Z

thanks @Tushar987

Tushar987 added 2 commits March 10, 2018 14:31

Add docstring for DatetimeIndex.strftime method

26338e9

Typo in docstring

7f01a2c

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

jreback added Docs Datetime Datetime data dtype labels Mar 10, 2018

Updated docstring for DatetimeIndex.strftime method

8decfa7

jreback approved these changes Mar 10, 2018

View reviewed changes

jreback added this to the 0.23.0 milestone Mar 10, 2018

jreback mentioned this pull request Mar 10, 2018

DOC: update the Series.dt.strftime docstring #20189

Closed

5 tasks

reidy-p mentioned this pull request Mar 10, 2018

API: Return Index from DatetimeIndex/PeriodIndex.strftime #20240

Merged

4 tasks

jreback merged commit 7230991 into pandas-dev:master Mar 13, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc: Update the DatetimeIndex.strftime docstring #20103

Doc: Update the DatetimeIndex.strftime docstring #20103

Tushar987 commented Mar 10, 2018 •

edited

Loading

jorisvandenbossche left a comment

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jreback Mar 10, 2018

codecov bot commented Mar 10, 2018

jreback commented Mar 13, 2018

Doc: Update the DatetimeIndex.strftime docstring #20103

Doc: Update the DatetimeIndex.strftime docstring #20103

Conversation

Tushar987 commented Mar 10, 2018 • edited Loading

jorisvandenbossche left a comment

Choose a reason for hiding this comment

jorisvandenbossche Mar 10, 2018

Choose a reason for hiding this comment

jorisvandenbossche Mar 10, 2018

Choose a reason for hiding this comment

jorisvandenbossche Mar 10, 2018

Choose a reason for hiding this comment

jorisvandenbossche Mar 10, 2018

Choose a reason for hiding this comment

jreback Mar 10, 2018

Choose a reason for hiding this comment

codecov bot commented Mar 10, 2018

Codecov Report

jreback commented Mar 13, 2018

Tushar987 commented Mar 10, 2018 •

edited

Loading