From bf2c14d1f9d0693f73cc8bfa9eea198980919ba2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Sun, 19 Aug 2018 18:32:23 +0200 Subject: [PATCH 1/8] core/indexes/range.py: Add dtype documentation to RangeIndex. --- pandas/core/indexes/range.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 939ec0b79ac6b..21afd039ee056 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -43,6 +43,9 @@ class RangeIndex(Int64Index): If int and "stop" is not given, interpreted as "stop" instead. stop : int (default: 0) step : int (default: 1) + dtype : numpy dtype or pandas type, default int64 + Only the default int64 is supported, argument accepted for homogeneity + with other index types. name : object, optional Name to be stored in the index copy : bool, default False From 4d9859c3fd128613ff170d445aca375921b8a18d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Sun, 19 Aug 2018 18:33:26 +0200 Subject: [PATCH 2/8] core/indexes/range.py: Correct order of arguments in RangeIndex docstring. Fixes #22373 --- pandas/core/indexes/range.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 21afd039ee056..32095c6a6301b 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -46,10 +46,10 @@ class RangeIndex(Int64Index): dtype : numpy dtype or pandas type, default int64 Only the default int64 is supported, argument accepted for homogeneity with other index types. - name : object, optional - Name to be stored in the index copy : bool, default False Unused, accepted for homogeneity with other index types. + name : object, optional + Name to be stored in the index See Also -------- From 7606c7d77af19ac6cb8352696178c081af05949b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Sun, 19 Aug 2018 18:36:32 +0200 Subject: [PATCH 3/8] core/indexes/range.py: Add fastpath argument to the RangeIndex docstring. --- pandas/core/indexes/range.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 32095c6a6301b..10269736529d7 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -50,6 +50,9 @@ class RangeIndex(Int64Index): Unused, accepted for homogeneity with other index types. name : object, optional Name to be stored in the index + fastpath : bool, default False + Do not validate arguments. If `fastpath` is `True`, `start` has to be + of type `int`. See Also -------- From bcd985f5d587a26f72b5a015d6875a96594bc300 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Sun, 19 Aug 2018 18:47:57 +0200 Subject: [PATCH 4/8] core/indexes/range.py: Clean up formatting of RangeIndex docstring according to pandas documentation styleguide. --- pandas/core/indexes/range.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 10269736529d7..ae6532c252b2b 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -30,21 +30,21 @@ 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) + 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 dtype : numpy dtype or pandas type, default int64 - Only the default int64 is supported, argument accepted for homogeneity + 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. From 201408e2ecd9706fc215e12f780a81c45c9c5aa0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Sun, 19 Aug 2018 18:53:19 +0200 Subject: [PATCH 5/8] core/indexes/range.py: Full docstring for RangeIndex.from_range. --- pandas/core/indexes/range.py | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index ae6532c252b2b..b5c4d76271f91 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -125,7 +125,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 ' From 5624b8d94081f3cea2bc0538babee962b98a737c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Sun, 19 Aug 2018 19:36:12 +0200 Subject: [PATCH 6/8] pandas/core/indexes/range.py: Make pep8speaks happy. --- pandas/core/indexes/range.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index b5c4d76271f91..79e83a775b833 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -40,12 +40,13 @@ class RangeIndex(Int64Index): Parameters ---------- start : int or other RangeIndex instance, default 0 - If of type `int` and `stop` is not given, interpreted as `stop` instead. + If of type `int` and `stop` is not given, interpreted as `stop` + instead. stop : int, default 0 step : int, default 1 dtype : numpy dtype or pandas type, default int64 - Only the default `int64` is supported, argument accepted for homogeneity - with other index types. + 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 @@ -134,8 +135,8 @@ def from_range(cls, data, name=None, dtype=None, **kwargs): 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. + Only the default int64 is supported, argument accepted for + homogeneity with other index types. **kwargs These parameters will be passed to :class:`~pandas.RangeIndex`. """ From a1a1b1b8b059abd8ffc37e55109b4068c52bf29a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Thu, 6 Sep 2018 23:01:10 +0200 Subject: [PATCH 7/8] RangeIndex docstring: add explanation and examples for RangeIndex ranges. Explanation is based on the python documentation for ranges. --- pandas/core/indexes/range.py | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index 79e83a775b833..ea74740d1d8a0 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -28,10 +28,19 @@ class RangeIndex(Int64Index): """ - Immutable Index implementing a monotonic integer range. - - RangeIndex is a memory-saving special case of :class:`~pandas.Int64Index` - limited to representing monotonic ranges. Using RangeIndex may in some + Immutable :class:`~pandas.Index` implementing a monotonic integer range. + + Like a python `range`, a `RangeIndex` contains values from `start` + (inclusive) to `stop` (exclusive) + with increments of size `step`. This means that for a positive `step`, + the contents of a `RangeIndex` r are determined by + the formula ``r[i] = start + step*i where i >= 0 and r[i] < stop``. + Accordingly, for a negative `step`, the contents of the `RangeIndex` are + still determined by the formula ``r[i] = start + step*i``, but the constraints + are ``i >= 0 and r[i] > stop``. + + `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 @@ -60,6 +69,17 @@ class RangeIndex(Int64Index): Index : The base pandas Index type Int64Index : Index of int64 data + Examples + -------- + >>> pd.RangeIndex(0, 4, 1) + RangeIndex(start=0, stop=4, step=1) + + The step and start parameters are optional, and `RangeIndex` excludes stop: + + >>> list(pd.RangeIndex(4)) + [0, 1, 2, 3] + + Attributes ---------- None From 219f5ee93ee04e996dcbbac5db8d2f561d1a70ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mika=20Pfl=C3=BCger?= Date: Thu, 6 Sep 2018 23:16:56 +0200 Subject: [PATCH 8/8] RangeIndex docstring: document that users should prefer to pass a range to Index. Index docstring: add example of passing a range to construct a RangeIndex. --- pandas/core/indexes/base.py | 5 ++++- pandas/core/indexes/range.py | 11 +++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 7237b7754b09e..fdd246134ae5c 100644 --- a/pandas/core/indexes/base.py +++ b/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) If dtype is None, we find the dtype that best fits the data. If an actual dtype is provided, we coerce to that dtype if it's safe. @@ -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 --------- RangeIndex : Index implementing a monotonic integer range diff --git a/pandas/core/indexes/range.py b/pandas/core/indexes/range.py index ea74740d1d8a0..e30917886bb3c 100644 --- a/pandas/core/indexes/range.py +++ b/pandas/core/indexes/range.py @@ -30,6 +30,9 @@ class RangeIndex(Int64Index): """ Immutable :class:`~pandas.Index` implementing a monotonic integer range. + Most users do not need to use this class and should instead pass a python + `range` to :class:`~pandas.Index` to construct a `RangeIndex`. + Like a python `range`, a `RangeIndex` contains values from `start` (inclusive) to `stop` (exclusive) with increments of size `step`. This means that for a positive `step`, @@ -71,6 +74,14 @@ class RangeIndex(Int64Index): Examples -------- + Most users should use :class:`~pandas.RangeIndex` to construct a + `RangeIndex`. + + >>> pd.Index(range(4)) + RangeIndex(start=0, stop=4, step=1) + + However, `RangeIndex` can also directly be constructed. + >>> pd.RangeIndex(0, 4, 1) RangeIndex(start=0, stop=4, step=1)