@@ -1278,39 +1278,46 @@ def _set_names(self, values, level=None):
1278
1278
1279
1279
def set_names (self , names , level = None , inplace = False ):
1280
1280
"""
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.
1282
1284
1283
1285
Parameters
1284
1286
----------
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.
1292
1295
1293
1296
Returns
1294
1297
-------
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
1296
1304
1297
1305
Examples
1298
1306
--------
1299
1307
>>> pd.Index([1, 2, 3, 4]).set_names('foo')
1300
1308
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'])
1306
1313
>>> idx.set_names(['baz', 'quz'])
1307
- MultiIndex(levels=[[1, 2], [u 'one', u 'two']],
1314
+ MultiIndex(levels=[[1, 2], ['one', 'two']],
1308
1315
labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
1309
- names=[u 'baz', u 'quz'])
1316
+ names=['baz', 'quz'])
1310
1317
>>> idx.set_names('baz', level=0)
1311
- MultiIndex(levels=[[1, 2], [u 'one', u 'two']],
1318
+ MultiIndex(levels=[[1, 2], ['one', 'two']],
1312
1319
labels=[[0, 0, 1, 1], [0, 1, 0, 1]],
1313
- names=[u 'baz', u 'bar'])
1320
+ names=['baz', 'bar'])
1314
1321
"""
1315
1322
1316
1323
from .multi import MultiIndex
@@ -1319,7 +1326,8 @@ def set_names(self, names, level=None, inplace=False):
1319
1326
1320
1327
if level is not None and not is_list_like (level ) and is_list_like (
1321
1328
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 )
1323
1331
1324
1332
if not is_list_like (names ) and level is None and self .nlevels > 1 :
1325
1333
raise TypeError ("Must pass list-like as `names`." )
@@ -1339,18 +1347,44 @@ def set_names(self, names, level=None, inplace=False):
1339
1347
1340
1348
def rename (self , name , inplace = False ):
1341
1349
"""
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.
1343
1354
1344
1355
Parameters
1345
1356
----------
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.
1350
1362
1351
1363
Returns
1352
1364
-------
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.
1354
1388
"""
1355
1389
return self .set_names ([name ], inplace = inplace )
1356
1390
0 commit comments