Skip to content

Bug22373: Enhance documentation for RangeIndex #22421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
Closed

Bug22373: Enhance documentation for RangeIndex #22421

Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
bf2c14d
core/indexes/range.py: Add dtype documentation to RangeIndex.
mikapfl Aug 19, 2018
4d9859c
core/indexes/range.py: Correct order of arguments in RangeIndex docst…
mikapfl Aug 19, 2018
7606c7d
core/indexes/range.py: Add fastpath argument to the RangeIndex docstr…
mikapfl Aug 19, 2018
bcd985f
core/indexes/range.py: Clean up formatting of RangeIndex docstring ac…
mikapfl Aug 19, 2018
201408e
core/indexes/range.py: Full docstring for RangeIndex.from_range.
mikapfl Aug 19, 2018
5624b8d
pandas/core/indexes/range.py: Make pep8speaks happy.
mikapfl Aug 19, 2018
a1a1b1b
RangeIndex docstring: add explanation and examples for RangeIndex ran…
mikapfl Sep 6, 2018
219f5ee
RangeIndex docstring: document that users should prefer to pass a ran…
mikapfl Sep 6, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 31 additions & 11 deletions pandas/core/indexes/range.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,23 +30,30 @@ class RangeIndex(Int64Index):
"""
Immutable Index implementing a monotonic integer range.

RangeIndex is a memory-saving special case of Int64Index limited to
representing monotonic ranges. Using RangeIndex may in some instances
improve computing speed.
RangeIndex is a memory-saving special case of :class:`~pandas.Int64Index`
limited to representing monotonic ranges. Using RangeIndex may in some
instances improve computing speed.

This is the default index type used
by DataFrame and Series when no explicit index is provided by the user.
by `DataFrame` and `Series` when no explicit index is provided by the user.

Parameters
----------
start : int (default: 0), or other RangeIndex instance.
If int and "stop" is not given, interpreted as "stop" instead.
stop : int (default: 0)
step : int (default: 1)
name : object, optional
Name to be stored in the index
start : int or other RangeIndex instance, default 0
If of type `int` and `stop` is not given, interpreted as `stop`
instead.
stop : int, default 0
step : int, default 1
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

dtype : numpy dtype or pandas type, default int64
Only the default `int64` is supported, argument accepted for
homogeneity with other index types.
copy : bool, default False
Unused, accepted for homogeneity with other index types.
name : object, optional
Name to be stored in the index
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

fastpath : bool, default False
Do not validate arguments. If `fastpath` is `True`, `start` has to be
of type `int`.

See Also
--------
Expand Down Expand Up @@ -119,7 +126,20 @@ def ensure_int(value, field):

@classmethod
def from_range(cls, data, name=None, dtype=None, **kwargs):
""" create RangeIndex from a range (py3), or xrange (py2) object """
"""
Create RangeIndex from a range (py3), or xrange (py2) object.

Parameters
----------
data : range (py3), or xrange (py2)
name : object
Name to be stored in the index
dtype : numpy dtype or pandas type, default int64
Only the default int64 is supported, argument accepted for
homogeneity with other index types.
**kwargs
These parameters will be passed to :class:`~pandas.RangeIndex`.
"""
if not isinstance(data, range):
raise TypeError(
'{0}(...) must be called with object coercible to a '
Expand Down