Bug22373: Enhance documentation for RangeIndex #22421

mikapfl · 2018-08-19T17:34:41Z

Corrects documentation for RangeIndex and enhances documentation for RangeIndex and RangeIndex.from_range
closes #22373
passes git diff upstream/master -u -- "*.py" | flake8 --diff

…ring. Fixes #22373

…ing.

…cording to pandas documentation styleguide.

pep8speaks · 2018-08-19T17:34:43Z

Hello @mikapfl! Thanks for updating the PR.

There are no PEP8 issues in the file pandas/core/indexes/base.py !
In the file pandas/core/indexes/range.py, following are the PEP8 issues :

Line 42:80: E501 line too long (82 > 79 characters)

Comment last updated on September 06, 2018 at 21:17 Hours UTC

datapythonista

Thanks for the changes, looking good. If you want to add examples as part of this PR, that would be great (we can do it in a separate PR too).

Also, if you can add periods at the end of the See Also items description, that would be great.

datapythonista · 2018-08-20T11:55:10Z

pandas/core/indexes/range.py

+        If of type `int` and `stop` is not given, interpreted as `stop`
+        instead.
+    stop : int, default 0
+    step : int, default 1


It'f be good to have these documented. Also, start, which would be good to have a description, besides the behavior described.

Re documenting start, stop and step: I also thought that it would be nice to document them, and figured we could just recycle the python documentation for range. However, the documentation for the arguments is very basic in python as well: "stop: The value of the stop parameter". Maybe there is not much else to say?

But I'll try to adapt the rest of the python range docs (i.e. the long description) and try to come up with some useful examples.

I think it can be useful to say whether the stop value is included or not. It's not obvious to me that range(0, 10) doesn't include the 10.

Also, for beginner users, something as simple as start : The first value of the generated range. can be useful. step can be tricky, do we support negative values, as range?

I do think there is a lot to say. :)

think it can be useful to say whether the stop value is included or not. It's not obvious to me that range(0, 10) doesn't include the 10.

this is standard python behavior to NOT include the rhs on ranges.

jreback · 2018-08-20T23:00:47Z

pandas/core/indexes/range.py

+        If of type `int` and `stop` is not given, interpreted as `stop`
+        instead.
+    stop : int, default 0
+    step : int, default 1


think it can be useful to say whether the stop value is included or not. It's not obvious to me that range(0, 10) doesn't include the 10.

this is standard python behavior to NOT include the rhs on ranges.

jreback · 2018-08-20T23:01:55Z

pandas/core/indexes/range.py

    copy : bool, default False
        Unused, accepted for homogeneity with other index types.
+    name : object, optional
+        Name to be stored in the index


this constructor should be discouraged for using integers on ranges, this is the reason we have .from_range. Actually folks should generally NOT use specific constructors anyhow. pd.Index dispatches in most cases. Only if you have very very specific requreiments do you need to use this constructor.

datapythonista · 2018-08-21T09:00:06Z

Agree that not including the stop of the range is standard, my point is that it's not obvious unless you know about this standard. So, I think it's worth mentioning it in the documentation.

If using the constructor is discouraged, we should also say it in the description I guess.

…ges. Explanation is based on the python documentation for ranges.

…ge to Index. Index docstring: add example of passing a range to construct a RangeIndex.

codecov · 2018-09-06T21:17:58Z

Codecov Report

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

@@           Coverage Diff           @@
##           master   #22421   +/-   ##
=======================================
  Coverage   92.05%   92.05%           
=======================================
  Files         169      169           
  Lines       50714    50714           
=======================================
  Hits        46684    46684           
  Misses       4030     4030

Flag	Coverage Δ
#multiple	`90.46% <ø> (ø)`	⬆️
#single	`42.25% <ø> (ø)`	⬆️

Impacted Files	Coverage Δ
pandas/core/indexes/range.py	`95.7% <ø> (ø)`	⬆️

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 140c7bb...219f5ee. Read the comment docs.

mikapfl · 2018-09-06T21:20:38Z

@datapythonista I have added documentation and examples showing the half-inclusive behaviour of RangeIndex. The documentation is based on the python range documentation.

@jreback I have added langeuage and examples to Index and RangeIndex to guide users towards using Index(range(…)) instead of RangeIndex(…).

datapythonista

Can you change the default of tupleize_cols from (default: True) to `default True

And finish the comment in Notes with a period.

datapythonista · 2018-09-23T14:21:10Z

pandas/core/indexes/base.py

@@ -177,7 +177,7 @@ class Index(IndexOpsMixin, PandasObject):

    Parameters
    ----------
-    data : array-like (1-dimensional)
+    data : array-like (1-dimensional) or python `range`


I think iterable would be the best in this case. If you can add a description, and also comment there about range.

datapythonista · 2018-09-23T14:22:49Z

pandas/core/indexes/base.py

@@ -177,7 +177,7 @@ class Index(IndexOpsMixin, PandasObject):

    Parameters
    ----------
-    data : array-like (1-dimensional)
+    data : array-like (1-dimensional) or python `range`
    dtype : NumPy dtype (default: object)


can you change it to `dtype : dtype, default None

datapythonista · 2018-09-23T14:24:25Z

pandas/core/indexes/base.py

@@ -201,6 +201,9 @@ class Index(IndexOpsMixin, PandasObject):
    >>> pd.Index(list('abc'))
    Index(['a', 'b', 'c'], dtype='object')

+    >>> pd.Index(range(4))
+    RangeIndex(start=0, stop=4, step=1)
+
    See Also


Can you move the See Also section before Notes. Also, if you can end all the description with period.

alimcmaster1 · 2018-11-15T22:33:58Z

@mikapfl could you rebase and merge master if you are still looking to take this on? If not I can potentially take a look

datapythonista · 2018-12-02T00:35:31Z

@alimcmaster1, if you want to open a new PR with this. Closing as this seems abandoned.

mikapfl added 5 commits August 19, 2018 18:45

core/indexes/range.py: Add dtype documentation to RangeIndex.

bf2c14d

core/indexes/range.py: Correct order of arguments in RangeIndex docst…

4d9859c

…ring. Fixes #22373

core/indexes/range.py: Add fastpath argument to the RangeIndex docstr…

7606c7d

…ing.

core/indexes/range.py: Clean up formatting of RangeIndex docstring ac…

bcd985f

…cording to pandas documentation styleguide.

core/indexes/range.py: Full docstring for RangeIndex.from_range.

201408e

pandas/core/indexes/range.py: Make pep8speaks happy.

5624b8d

gfyoung added the Docs label Aug 19, 2018

gfyoung approved these changes Aug 19, 2018

View reviewed changes

gfyoung requested review from jreback and datapythonista August 19, 2018 17:52

gfyoung added this to the 0.23.5 milestone Aug 19, 2018

datapythonista reviewed Aug 20, 2018

View reviewed changes

jreback requested changes Aug 20, 2018

View reviewed changes

mikapfl added 2 commits September 6, 2018 23:01

RangeIndex docstring: add explanation and examples for RangeIndex ran…

a1a1b1b

…ges. Explanation is based on the python documentation for ranges.

RangeIndex docstring: document that users should prefer to pass a ran…

219f5ee

…ge to Index. Index docstring: add example of passing a range to construct a RangeIndex.

datapythonista reviewed Sep 23, 2018

View reviewed changes

jreback modified the milestones: 0.23.5, 0.24.0 Oct 23, 2018

jreback removed this from the 0.24.0 milestone Nov 6, 2018

datapythonista closed this Dec 2, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bug22373: Enhance documentation for RangeIndex #22421

Bug22373: Enhance documentation for RangeIndex #22421

mikapfl commented Aug 19, 2018

pep8speaks commented Aug 19, 2018 •

edited

Loading

datapythonista left a comment

datapythonista Aug 20, 2018

mikapfl Aug 20, 2018

datapythonista Aug 20, 2018

jreback Aug 20, 2018

jreback Aug 20, 2018

jreback Aug 20, 2018

datapythonista commented Aug 21, 2018

codecov bot commented Sep 6, 2018

mikapfl commented Sep 6, 2018

datapythonista left a comment

datapythonista Sep 23, 2018

datapythonista Sep 23, 2018

datapythonista Sep 23, 2018

alimcmaster1 commented Nov 15, 2018

datapythonista commented Dec 2, 2018

Bug22373: Enhance documentation for RangeIndex #22421

Bug22373: Enhance documentation for RangeIndex #22421

Conversation

mikapfl commented Aug 19, 2018

pep8speaks commented Aug 19, 2018 • edited Loading

Comment last updated on September 06, 2018 at 21:17 Hours UTC

datapythonista left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

datapythonista commented Aug 21, 2018

codecov bot commented Sep 6, 2018

Codecov Report

mikapfl commented Sep 6, 2018

datapythonista left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alimcmaster1 commented Nov 15, 2018

datapythonista commented Dec 2, 2018

pep8speaks commented Aug 19, 2018 •

edited

Loading