Skip to content

Commit 522cd97

Browse files
committed
Update doc-string in .rename
1 parent 2a2d1cf commit 522cd97

File tree

2 files changed

+60
-26
lines changed

2 files changed

+60
-26
lines changed

pandas/core/indexes/base.py

+59-25
Original file line numberDiff line numberDiff line change
@@ -1278,39 +1278,46 @@ def _set_names(self, values, level=None):
12781278

12791279
def set_names(self, names, level=None, inplace=False):
12801280
"""
1281-
Set new names on index. Defaults to returning new index.
1281+
Set Index or MultiIndex name.
1282+
1283+
Able to set new names partially and by level.
12821284
12831285
Parameters
12841286
----------
1285-
names : str or sequence
1286-
name(s) to set
1287-
level : int, level name, or sequence of int/level names (default None)
1288-
If the index is a MultiIndex (hierarchical), level(s) to set (None
1289-
for all levels). Otherwise level must be None
1290-
inplace : bool
1291-
if True, mutates in place
1287+
names : int, str, list-like, optional
1288+
Name(s) to set.
1289+
level : int, str, list-like, optional, default None
1290+
If the index is a MultiIndex(hierarchical), level(s) to set (None
1291+
for all levels). Otherwise level must be None.
1292+
inplace : boolean, default False
1293+
Modifies the object directly, instead of creating a new Index or
1294+
MultiIndex.
12921295
12931296
Returns
12941297
-------
1295-
new index (of same type and class...etc) [if inplace, returns None]
1298+
renamed : Index, MultiIndex or None
1299+
The same type as the caller or None if inplace is True.
1300+
1301+
See also
1302+
--------
1303+
Index.rename : Able to set new names without level
12961304
12971305
Examples
12981306
--------
12991307
>>> pd.Index([1, 2, 3, 4]).set_names('foo')
13001308
Int64Index([1, 2, 3, 4], dtype='int64', name='foo')
1301-
>>> pd.Index([1, 2, 3, 4]).set_names(['foo'])
1302-
Int64Index([1, 2, 3, 4], dtype='int64', name='foo')
1303-
>>> idx = pd.MultiIndex.from_tuples([(1, u'one'), (1, u'two'),
1304-
(2, u'one'), (2, u'two')],
1305-
names=['foo', 'bar'])
1309+
1310+
>>> idx = pd.MultiIndex.from_tuples([(1, 'one'), (1, 'two'),
1311+
... (2, 'one'), (2, 'two')],
1312+
... names=['foo', 'bar'])
13061313
>>> idx.set_names(['baz', 'quz'])
1307-
MultiIndex(levels=[[1, 2], [u'one', u'two']],
1314+
MultiIndex(levels=[[1, 2], ['one', 'two']],
13081315
labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
1309-
names=[u'baz', u'quz'])
1316+
names=['baz', 'quz'])
13101317
>>> idx.set_names('baz', level=0)
1311-
MultiIndex(levels=[[1, 2], [u'one', u'two']],
1318+
MultiIndex(levels=[[1, 2], ['one', 'two']],
13121319
labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
1313-
names=[u'baz', u'bar'])
1320+
names=['baz', 'bar'])
13141321
"""
13151322

13161323
from .multi import MultiIndex
@@ -1319,7 +1326,8 @@ def set_names(self, names, level=None, inplace=False):
13191326

13201327
if level is not None and not is_list_like(level) and is_list_like(
13211328
names):
1322-
raise TypeError("Names must be a string")
1329+
msg = "Length of names must match number of levels in MultiIndex."
1330+
raise TypeError(msg)
13231331

13241332
if not is_list_like(names) and level is None and self.nlevels > 1:
13251333
raise TypeError("Must pass list-like as `names`.")
@@ -1339,18 +1347,44 @@ def set_names(self, names, level=None, inplace=False):
13391347

13401348
def rename(self, name, inplace=False):
13411349
"""
1342-
Set new names on index. Defaults to returning new index.
1350+
Alter Index or MultiIndex name.
1351+
1352+
Able to set new names without level. Defaults to returning new index.
1353+
Length of names must match number of levels in MultiIndex.
13431354
13441355
Parameters
13451356
----------
1346-
name : str or list
1347-
name to set
1348-
inplace : bool
1349-
if True, mutates in place
1357+
name : int, str, list-like, optional
1358+
Name(s) to set.
1359+
inplace : boolean, default False
1360+
Modifies the object directly, instead of creating a new Index or
1361+
MultiIndex.
13501362
13511363
Returns
13521364
-------
1353-
new index (of same type and class...etc) [if inplace, returns None]
1365+
renamed : Index, MultiIndex or None
1366+
The same type as the caller or None if inplace is True.
1367+
1368+
See also
1369+
--------
1370+
Index.set_names : Able to set new names partially and by level
1371+
1372+
Examples
1373+
--------
1374+
>>> idx = pd.Index([1, 2, 3, 4], name='foo')
1375+
>>> idx.rename('bar')
1376+
Int64Index([1, 2, 3, 4], dtype='int64', name='bar')
1377+
1378+
>>> idx = pd.MultiIndex.from_tuples([(1, 'one'), (1, 'two'),
1379+
... (2, 'one'), (2, 'two')],
1380+
... names=['foo', 'bar'])
1381+
>>> idx.rename(['bar', None])
1382+
MultiIndex(levels=[[1, 2], ['one', 'two']],
1383+
labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
1384+
names=['bar', None])
1385+
>>> idx.rename(['bar'])
1386+
Traceback (most recent call last):
1387+
ValueError: Length of names must match number of levels in MultiIndex.
13541388
"""
13551389
return self.set_names([name], inplace=inplace)
13561390

pandas/tests/indexes/multi/test_get_set.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -360,7 +360,7 @@ def test_set_levels_labels_names_bad_input(idx):
360360
with tm.assert_raises_regex(ValueError, 'Length of names'):
361361
idx.set_names(names[0], level=[0, 1])
362362

363-
with tm.assert_raises_regex(TypeError, 'string'):
363+
with tm.assert_raises_regex(TypeError, 'Length of names'):
364364
idx.set_names(names, level=0)
365365

366366

0 commit comments

Comments
 (0)