1************************************************************************* 2Quickstart 3************************************************************************* 4 5========================================================================= 6Building the Table 7========================================================================= 8 9Building a table is very easy. :class:`.BeautifulTable` provides two views 10``rows`` and ``columns``. You can use them to modify their respective properties. 11 12Let's create our first table and add some rows. 13 14.. code:: python 15 16 >>> from beautifultable import BeautifulTable 17 >>> table = BeautifulTable() 18 >>> table.rows.append(["Jacob", 1, "boy"]) 19 >>> table.rows.append(["Isabella", 1, "girl"]) 20 >>> table.rows.append(["Ethan", 2, "boy"]) 21 >>> table.rows.append(["Sophia", 2, "girl"]) 22 >>> table.rows.append(["Michael", 3, "boy"]) 23 >>> table.columns.header = ["name", "rank", "gender"] 24 >>> table.rows.header = ["S1", "S2", "S3", "S4", "S5"] 25 >>> print(table) 26 +----+----------+------+--------+ 27 | | name | rank | gender | 28 +----+----------+------+--------+ 29 | S1 | Jacob | 1 | boy | 30 +----+----------+------+--------+ 31 | S2 | Isabella | 1 | girl | 32 +----+----------+------+--------+ 33 | S3 | Ethan | 2 | boy | 34 +----+----------+------+--------+ 35 | S4 | Sophia | 2 | girl | 36 +----+----------+------+--------+ 37 | S5 | Michael | 3 | boy | 38 +----+----------+------+--------+ 39 40BeautifulTable initializes the shape lazily. Here when you appended the first row, 41the number of columns was set to 3. Further rows had to be of length 3. If you had 42set the columns and/or row headers beforehand as follows, the table shape would already be 43set to (5, 3). Hence you would just set the rows directly using their indices or keys. 44 45.. code:: python 46 47 >>> from beautifultable import BeautifulTable 48 >>> table = BeautifulTable() 49 >>> table.columns.header = ["name", "rank", "gender"] 50 >>> table.rows.header = ["S1", "S2", "S3", "S4", "S5"] 51 >>> table.rows[0] = ["Jacob", 1, "boy"] 52 >>> table.rows[1] = ["Isabella", 1, "girl"] 53 >>> table.rows[2] = ["Ethan", 2, "boy"] 54 >>> table.rows[3] = ["Sophia", 2, "girl"] 55 >>> table.rows[4] =["Michael", 3, "boy"] 56 >>> print(table) 57 +----+----------+------+--------+ 58 | | name | rank | gender | 59 +----+----------+------+--------+ 60 | S1 | Jacob | 1 | boy | 61 +----+----------+------+--------+ 62 | S2 | Isabella | 1 | girl | 63 +----+----------+------+--------+ 64 | S3 | Ethan | 2 | boy | 65 +----+----------+------+--------+ 66 | S4 | Sophia | 2 | girl | 67 +----+----------+------+--------+ 68 | S5 | Michael | 3 | boy | 69 +----+----------+------+--------+ 70 71 72So, We created our first table. Let's add a new column. 73 74.. code:: python 75 76 >>> table.columns.append(["2010", "2012", "2008", "2010", "2011"], header="year") 77 >>> print(table) 78 +----+----------+------+--------+------+ 79 | | name | rank | gender | year | 80 +----+----------+------+--------+------+ 81 | S1 | Jacob | 1 | boy | 2010 | 82 +----+----------+------+--------+------+ 83 | S2 | Isabella | 1 | girl | 2012 | 84 +----+----------+------+--------+------+ 85 | S3 | Ethan | 2 | boy | 2008 | 86 +----+----------+------+--------+------+ 87 | S4 | Sophia | 2 | girl | 2010 | 88 +----+----------+------+--------+------+ 89 | S5 | Michael | 3 | boy | 2011 | 90 +----+----------+------+--------+------+ 91 92You can also build a :class:`.BeautifulTable` using slicing. Slicing creates a 93new table with it's own copy of data. But it retains the properties 94of the original object. You can slice both rows or columns. 95 96.. code:: python 97 98 >>> new_table = table.rows[:3] 99 >>> print(new_table) 100 +----+----------+------+--------+------+ 101 | | name | rank | gender | year | 102 +----+----------+------+--------+------+ 103 | S1 | Jacob | 1 | boy | 2010 | 104 +----+----------+------+--------+------+ 105 | S2 | Isabella | 1 | girl | 2012 | 106 +----+----------+------+--------+------+ 107 | S3 | Ethan | 2 | boy | 2008 | 108 +----+----------+------+--------+------+ 109 110 111.. code:: python 112 113 >>> new_table = table.columns[:3] 114 >>> print(new_table) 115 +----+----------+------+--------+ 116 | | name | rank | gender | 117 +----+----------+------+--------+ 118 | S1 | Jacob | 1 | boy | 119 +----+----------+------+--------+ 120 | S2 | Isabella | 1 | girl | 121 +----+----------+------+--------+ 122 | S3 | Ethan | 2 | boy | 123 +----+----------+------+--------+ 124 | S4 | Sophia | 2 | girl | 125 +----+----------+------+--------+ 126 | S5 | Michael | 3 | boy | 127 +----+----------+------+--------+ 128 129As you can see how easy it is to create a Table with **beautifultable**. 130Now lets move on to see some common use cases. For details, please refer the API Documentation. 131 132 133========================================================================= 134Accessing Rows 135========================================================================= 136 137You can access a row using it's index or it's header. It returns a **BTRowData** object. 138 139.. code:: python 140 141 >>> print(list(table.rows[3])) 142 ['Sophia', 2, 'girl', '2010'] 143 144To access a particular field of a row, you can again use the index, or the header 145of the required column. 146 147.. code:: python 148 149 >>> print(table.rows[3][2]) 150 girl 151 >>> print(table.rows[3]['gender']) 152 girl 153 154 155========================================================================= 156Accessing Columns 157========================================================================= 158 159You can access a column using it's index or it's header. It returns a **BTColumnData** object. 160 161.. code:: python 162 163 >>> print(list(table.columns['name'])) 164 ['Jacob', 'Isabella', 'Ethan', 'Sophia', 'Michael'] 165 166To access a particular field of a column, you can again use the index, or the header 167of the required row. 168 169.. code:: python 170 171 >>> print(table.columns[2][3]) 172 girl 173 >>> print(table.columns[2]['S4']) 174 girl 175 176========================================================================= 177Counting Rows and Columns 178========================================================================= 179 180You can get the number of columns or rows in the table by using the 181``len`` function. You can also use the :attr:`.BeautifulTable.shape` 182attribute. 183 184.. code:: python 185 186 >>> print(len(table.columns)) 187 3 188 >>> print(len(table.rows)) 189 5 190 >>> print(table.shape) 191 (5,3) 192 193========================================================================= 194Inserting Rows and Columns 195========================================================================= 196 197BeautifulTable provides 2 methods, :meth:`.BTRowCollection.insert` and 198:meth:`.BTColumnCollection.insert` for this purpose. 199 200.. code:: python 201 202 >>> table.rows.insert(3, ['Gary', 2, 'boy', 2009], header='S6') 203 >>> table.columns.insert(2, [78, 67, 82, 56, 86, 74], header='marks') 204 >>> print(table) 205 +----+----------+------+-------+--------+------+ 206 | | name | rank | marks | gender | year | 207 +----+----------+------+-------+--------+------+ 208 | S1 | Jacob | 1 | 78 | boy | 2010 | 209 +----+----------+------+-------+--------+------+ 210 | S2 | Isabella | 1 | 67 | girl | 2012 | 211 +----+----------+------+-------+--------+------+ 212 | S3 | Ethan | 2 | 82 | boy | 2008 | 213 +----+----------+------+-------+--------+------+ 214 | S6 | Gary | 2 | 56 | boy | 2009 | 215 +----+----------+------+-------+--------+------+ 216 | S4 | Sophia | 2 | 86 | girl | 2010 | 217 +----+----------+------+-------+--------+------+ 218 | S5 | Michael | 3 | 74 | boy | 2011 | 219 +----+----------+------+-------+--------+------+ 220 221 222========================================================================= 223Removing Rows and Columns 224========================================================================= 225 226Removing a row or column is very easy. Just delete it using ``del`` 227statement. 228 229.. code:: python 230 231 >>> del table.rows[3] 232 >>> del table.columns['year'] 233 >>> print(table) 234 +----+----------+------+-------+--------+ 235 | | name | rank | marks | gender | 236 +----+----------+------+-------+--------+ 237 | S1 | Jacob | 1 | 78 | boy | 238 +----+----------+------+-------+--------+ 239 | S2 | Isabella | 1 | 67 | girl | 240 +----+----------+------+-------+--------+ 241 | S3 | Ethan | 2 | 82 | boy | 242 +----+----------+------+-------+--------+ 243 | S4 | Sophia | 2 | 86 | girl | 244 +----+----------+------+-------+--------+ 245 | S5 | Michael | 3 | 74 | boy | 246 +----+----------+------+-------+--------+ 247 248You can also use the helper methods :meth:`.BTRowCollection.pop`, 249:meth:`.BTColumnCollection.pop` to do the same thing. Both these 250methods take the index or header of the row/column to be removed. 251 252Therefore the following 2 snippets are equivalent. 253 254.. code:: python 255 256 >>> table.columns.pop('marks') 257 258.. code:: python 259 260 >>> table.columns.pop(2) 261 262 263========================================================================= 264Updating data in the Table 265========================================================================= 266 267Let's change the name in the 4th row to ``'Sophie'``. 268 269.. code:: python 270 271 >>> table.rows[3][0] = 'Sophie' # index of 4th row is 3 272 >>> print(list(table.rows[3])) 273 ['Sophie', 2, 86, 'girl'] 274 275You could have done the same thing using the header. 276 277.. code:: python 278 279 >>> table.rows[3]['name'] = 'Sophie' 280 281 282Or, you can also change the entire row, or even multiple rows 283using slicing. 284 285.. code:: python 286 287 >>> table.rows[3] = ['Sophie', 2, 56, 'girl'] 288 289 290You can also update existing columns as shown below. 291 292.. code:: python 293 294 >>> table.columns['marks'] = [75, 46, 89, 56, 82] 295 >>> print(table) 296 +----+----------+------+-------+--------+ 297 | | name | rank | marks | gender | 298 +----+----------+------+-------+--------+ 299 | S1 | Jacob | 1 | 75 | boy | 300 +----+----------+------+-------+--------+ 301 | S2 | Isabella | 1 | 46 | girl | 302 +----+----------+------+-------+--------+ 303 | S3 | Ethan | 2 | 89 | boy | 304 +----+----------+------+-------+--------+ 305 | S4 | Sophie | 2 | 56 | girl | 306 +----+----------+------+-------+--------+ 307 | S5 | Michael | 3 | 82 | boy | 308 +----+----------+------+-------+--------+ 309 310The methods :meth:`.BTRowCollection.update` and :meth:`.BTColumnCollection.update` 311can be used to perform the operations discussed in this section. 312 313Note that you can only update existing columns but can't create 314a new column using this method. For that you need to use the 315methods :meth:`.BTRowCollection.append`, :meth:`.BTRowCollection.insert`, 316:meth:`.BTColumnCollection.append` or :meth:`.BTColumnCollection.insert`. 317 318 319========================================================================= 320Searching for rows or columns headers 321========================================================================= 322 323Cheking if a column header is in the table. 324 325.. code:: python 326 327 >>> 'rank' in table.columns.header 328 True 329 330Cheking if a row header is in the table. 331 332.. code:: python 333 334 >>> 'S2' in table.rows.header 335 True 336 337Cheking if a row is in table 338 339.. code:: python 340 341 >>> ["Ethan", 2, 89, "boy"] in table.rows 342 True 343 344Cheking if a column is in table 345 346.. code:: python 347 348 >>> ["Jacob", "Isabella", "Ethan", "Sophie", "Michael"] in table.columns 349 True 350 351========================================================================= 352Sorting based on a Column 353========================================================================= 354 355You can also :meth:`.BTRowCollection.sort` the table based on a column 356by specifying it's index or it's header. 357 358.. code:: python 359 360 >>> table.rows.sort('marks') 361 >>> print(table) 362 +----+----------+------+-------+--------+ 363 | | name | rank | marks | gender | 364 +----+----------+------+-------+--------+ 365 | S2 | Isabella | 1 | 46 | girl | 366 +----+----------+------+-------+--------+ 367 | S4 | Sophia | 2 | 56 | girl | 368 +----+----------+------+-------+--------+ 369 | S1 | Jacob | 1 | 75 | boy | 370 +----+----------+------+-------+--------+ 371 | S5 | Michael | 3 | 82 | boy | 372 +----+----------+------+-------+--------+ 373 | S3 | Ethan | 2 | 89 | boy | 374 +----+----------+------+-------+--------+ 375 376========================================================================= 377Customizing the look of the Table 378========================================================================= 379 380------------------------------------------------------------------------- 381Alignment 382------------------------------------------------------------------------- 383 384Let's change the way some columns are aligned in our table. 385 386.. code:: python 387 388 >>> table.columns.alignment['name'] = BeautifulTable.ALIGN_LEFT 389 >>> table.columns.alignment['gender'] = BeautifulTable.ALIGN_RIGHT 390 >>> print(table) 391 +----+----------+------+-------+--------+ 392 | | name | rank | marks | gender | 393 +----+----------+------+-------+--------+ 394 | S2 | Isabella | 1 | 46 | girl | 395 +----+----------+------+-------+--------+ 396 | S4 | Sophia | 2 | 56 | girl | 397 +----+----------+------+-------+--------+ 398 | S1 | Jacob | 1 | 75 | boy | 399 +----+----------+------+-------+--------+ 400 | S5 | Michael | 3 | 82 | boy | 401 +----+----------+------+-------+--------+ 402 | S3 | Ethan | 2 | 89 | boy | 403 +----+----------+------+-------+--------+ 404 405You can also set all columns to a specific alignment 406 407.. code:: python 408 409 >>> table.columns.alignment = BeautifulTable.ALIGN_RIGHT 410 >>> print(table) 411 +----+----------+------+-------+--------+ 412 | | name | rank | marks | gender | 413 +----+----------+------+-------+--------+ 414 | S2 | Isabella | 1 | 46 | girl | 415 +----+----------+------+-------+--------+ 416 | S4 | Sophia | 2 | 56 | girl | 417 +----+----------+------+-------+--------+ 418 | S1 | Jacob | 1 | 75 | boy | 419 +----+----------+------+-------+--------+ 420 | S5 | Michael | 3 | 82 | boy | 421 +----+----------+------+-------+--------+ 422 | S3 | Ethan | 2 | 89 | boy | 423 +----+----------+------+-------+--------+ 424 425Headers can have a different alignment that the column. 426 427.. code:: python 428 429 >>> table.columns.header.alignment= BeautifulTable.ALIGN_RIGHT 430 >>> table.columns.alignment = BeautifulTable.ALIGN_LEFT 431 >>> print(table) 432 +----+----------+------+-------+--------+ 433 | | name | rank | marks | gender | 434 +----+----------+------+-------+--------+ 435 | S2 | Isabella | 1 | 46 | girl | 436 +----+----------+------+-------+--------+ 437 | S4 | Sophia | 2 | 56 | girl | 438 +----+----------+------+-------+--------+ 439 | S1 | Jacob | 1 | 75 | boy | 440 +----+----------+------+-------+--------+ 441 | S5 | Michael | 3 | 82 | boy | 442 +----+----------+------+-------+--------+ 443 | S3 | Ethan | 2 | 89 | boy | 444 +----+----------+------+-------+--------+ 445 446 447------------------------------------------------------------------------- 448Padding 449------------------------------------------------------------------------- 450 451You can change the padding for individual column similar to 452the alignment. 453 454.. code:: python 455 456 >>> table.columns.padding_left['rank'] = 5 457 >>> table.columns.padding_right['rank'] = 3 458 >>> print(table) 459 +----+----------+------------+--------+ 460 | | name | rank | gender | 461 +----+----------+------------+--------+ 462 | S1 | Jacob | 1 | boy | 463 +----+----------+------------+--------+ 464 | S2 | Isabella | 1 | girl | 465 +----+----------+------------+--------+ 466 | S3 | Ethan | 2 | boy | 467 +----+----------+------------+--------+ 468 | S4 | Sophia | 2 | girl | 469 +----+----------+------------+--------+ 470 | S5 | Michael | 3 | boy | 471 +----+----------+------------+--------+ 472 473 474You can use a helper attribute :attr:`.BTColumnCollection.padding` to 475set the left and right padding to a common value. 476 477 478------------------------------------------------------------------------- 479Styling 480------------------------------------------------------------------------- 481 482**beautifultable** comes with several predefined styles for various use cases. 483You can use the :meth:`.BeautifulTable.set_style` method to set the style 484of the table. The following styles are available: 485 486* **STYLE_DEFAULT** 487 488 .. code:: python 489 490 >>> table.set_style(BeautifulTable.STYLE_DEFAULT) 491 >>> print(table) 492 +----+----------+------+--------+ 493 | | name | rank | gender | 494 +----+----------+------+--------+ 495 | S1 | Jacob | 1 | boy | 496 +----+----------+------+--------+ 497 | S2 | Isabella | 1 | girl | 498 +----+----------+------+--------+ 499 | S3 | Ethan | 2 | boy | 500 +----+----------+------+--------+ 501 | S4 | Sophia | 2 | girl | 502 +----+----------+------+--------+ 503 | S5 | Michael | 3 | boy | 504 +----+----------+------+--------+ 505 506* **STYLE_NONE** 507 508 .. code:: python 509 510 >>> table.set_style(BeautifulTable.STYLE_NONE) 511 >>> print(table) 512 name rank gender 513 S1 Jacob 1 boy 514 S2 Isabella 1 girl 515 S3 Ethan 2 boy 516 S4 Sophia 2 girl 517 S5 Michael 3 boy 518 519* **STYLE_DOTTED** 520 521 .. code:: python 522 523 >>> table.set_style(BeautifulTable.STYLE_DOTTED) 524 >>> print(table) 525 ................................. 526 : : name : rank : gender : 527 ................................. 528 : S1 : Jacob : 1 : boy : 529 : S2 : Isabella : 1 : girl : 530 : S3 : Ethan : 2 : boy : 531 : S4 : Sophia : 2 : girl : 532 : S5 : Michael : 3 : boy : 533 ................................. 534 535* **STYLE_SEPARATED** 536 537 .. code:: python 538 539 >>> table.set_style(BeautifulTable.STYLE_SEPARATED) 540 >>> print(table) 541 +====+==========+======+========+ 542 | | name | rank | gender | 543 +====+==========+======+========+ 544 | S1 | Jacob | 1 | boy | 545 +----+----------+------+--------+ 546 | S2 | Isabella | 1 | girl | 547 +----+----------+------+--------+ 548 | S3 | Ethan | 2 | boy | 549 +----+----------+------+--------+ 550 | S4 | Sophia | 2 | girl | 551 +----+----------+------+--------+ 552 | S5 | Michael | 3 | boy | 553 +----+----------+------+--------+ 554 555* **STYLE_COMPACT** 556 557 .. code:: python 558 559 >>> table.set_style(BeautifulTable.STYLE_COMPACT) 560 >>> print(table) 561 name rank gender 562 ---- ---------- ------ -------- 563 S1 Jacob 1 boy 564 S2 Isabella 1 girl 565 S3 Ethan 2 boy 566 S4 Sophia 2 girl 567 S5 Michael 3 boy 568 569* **STYLE_MYSQL** 570 571 .. code:: python 572 573 >>> table.set_style(BeautifulTable.STYLE_MYSQL) 574 >>> print(table) # Yes, the default style is same as this style 575 +----+----------+------+--------+ 576 | | name | rank | gender | 577 +----+----------+------+--------+ 578 | S1 | Jacob | 1 | boy | 579 +----+----------+------+--------+ 580 | S2 | Isabella | 1 | girl | 581 +----+----------+------+--------+ 582 | S3 | Ethan | 2 | boy | 583 +----+----------+------+--------+ 584 | S4 | Sophia | 2 | girl | 585 +----+----------+------+--------+ 586 | S5 | Michael | 3 | boy | 587 +----+----------+------+--------+ 588 589* **STYLE_MARKDOWN** 590 591 .. code:: python 592 593 >>> table.set_style(BeautifulTable.STYLE_MARKDOWN) 594 >>> print(table) # Markdown alignment not supported currently 595 | | name | rank | gender | 596 |----|----------|------|--------| 597 | S1 | Jacob | 1 | boy | 598 | S2 | Isabella | 1 | girl | 599 | S3 | Ethan | 2 | boy | 600 | S4 | Sophia | 2 | girl | 601 | S5 | Michael | 3 | boy | 602 603* **STYLE_RST** 604 605 .. code:: python 606 607 >>> table.set_style(BeautifulTable.STYLE_RST) 608 >>> print(table) 609 ==== ========== ====== ======== 610 name rank gender 611 ==== ========== ====== ======== 612 S1 Jacob 1 boy 613 S2 Isabella 1 girl 614 S3 Ethan 2 boy 615 S4 Sophia 2 girl 616 S5 Michael 3 boy 617 ==== ========== ====== ======== 618 619* **STYLE_BOX** 620 621 .. code:: python 622 623 >>> table.set_style(BeautifulTable.STYLE_BOX) 624 >>> print(table) 625 ┌────┬──────────┬──────┬────────┐ 626 │ │ name │ rank │ gender │ 627 ├────┼──────────┼──────┼────────┤ 628 │ S1 │ Jacob │ 1 │ boy │ 629 ├────┼──────────┼──────┼────────┤ 630 │ S2 │ Isabella │ 1 │ girl │ 631 ├────┼──────────┼──────┼────────┤ 632 │ S3 │ Ethan │ 2 │ boy │ 633 ├────┼──────────┼──────┼────────┤ 634 │ S4 │ Sophia │ 2 │ girl │ 635 ├────┼──────────┼──────┼────────┤ 636 │ S5 │ Michael │ 3 │ boy │ 637 └────┴──────────┴──────┴────────┘ 638 639* **STYLE_BOX_DOUBLED** 640 641 .. code:: python 642 643 >>> table.set_style(BeautifulTable.STYLE_BOX_DOUBLED) 644 >>> print(table) 645 ╔════╦══════════╦══════╦════════╗ 646 ║ ║ name ║ rank ║ gender ║ 647 ╠════╬══════════╬══════╬════════╣ 648 ║ S1 ║ Jacob ║ 1 ║ boy ║ 649 ╠════╬══════════╬══════╬════════╣ 650 ║ S2 ║ Isabella ║ 1 ║ girl ║ 651 ╠════╬══════════╬══════╬════════╣ 652 ║ S3 ║ Ethan ║ 2 ║ boy ║ 653 ╠════╬══════════╬══════╬════════╣ 654 ║ S4 ║ Sophia ║ 2 ║ girl ║ 655 ╠════╬══════════╬══════╬════════╣ 656 ║ S5 ║ Michael ║ 3 ║ boy ║ 657 ╚════╩══════════╩══════╩════════╝ 658 659* **STYLE_BOX_ROUNDED** 660 661 .. code:: python 662 663 >>> table.set_style(BeautifulTable.STYLE_BOX_ROUNDED) 664 >>> print(table) 665 ╭────┬──────────┬──────┬────────╮ 666 │ │ name │ rank │ gender │ 667 ├────┼──────────┼──────┼────────┤ 668 │ S1 │ Jacob │ 1 │ boy │ 669 ├────┼──────────┼──────┼────────┤ 670 │ S2 │ Isabella │ 1 │ girl │ 671 ├────┼──────────┼──────┼────────┤ 672 │ S3 │ Ethan │ 2 │ boy │ 673 ├────┼──────────┼──────┼────────┤ 674 │ S4 │ Sophia │ 2 │ girl │ 675 ├────┼──────────┼──────┼────────┤ 676 │ S5 │ Michael │ 3 │ boy │ 677 ╰────┴──────────┴──────┴────────╯ 678 679* **STYLE_GRID** 680 681 .. code:: python 682 683 >>> table.set_style(BeautifulTable.STYLE_GRID) 684 >>> print(table) 685 ╔════╤══════════╤══════╤════════╗ 686 ║ │ name │ rank │ gender ║ 687 ╟────┼──────────┼──────┼────────╢ 688 ║ S1 │ Jacob │ 1 │ boy ║ 689 ╟────┼──────────┼──────┼────────╢ 690 ║ S2 │ Isabella │ 1 │ girl ║ 691 ╟────┼──────────┼──────┼────────╢ 692 ║ S3 │ Ethan │ 2 │ boy ║ 693 ╟────┼──────────┼──────┼────────╢ 694 ║ S4 │ Sophia │ 2 │ girl ║ 695 ╟────┼──────────┼──────┼────────╢ 696 ║ S5 │ Michael │ 3 │ boy ║ 697 ╚════╧══════════╧══════╧════════╝ 698 699For more finer customization, you can change what characters are used to draw 700various parts of the table. Here we show you an example of how you can use 701this feature. You can read the API Reference for more details. 702 703.. code:: python 704 705 >>> table.set_style(BeautifulTable.STYLE_NONE) # clear all formatting 706 >>> table.border.left = 'o' 707 >>> table.border.right = 'o' 708 >>> table.border.top = '<~>' 709 >>> table.border.bottom = '=' 710 >>> table.columns.header.separator = '^' 711 >>> table.columns.separator = ':' 712 >>> table.rows.separator = '~' 713 >>> print(table) 714 <~><~><~><~><~><~><~><~><~><~><~> 715 o : name : rank : gender o 716 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 717 o S1 : Jacob : 1 : boy o 718 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 719 o S2 : Isabella : 1 : girl o 720 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 721 o S3 : Ethan : 2 : boy o 722 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 723 o S4 : Sophia : 2 : girl o 724 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 725 o S5 : Michael : 3 : boy o 726 ================================= 727 728As you can see, you can change quite a lot about your *BeautifulTable* instance. 729For further sections, We switch the look of the table to *default* again. 730 731------------------------------------------------------------------------- 732Colored Tables 733------------------------------------------------------------------------- 734 735**beautifultable** comes with out of the box support for colored tables using 736ansi escape sequences. You can also use any library which makes use of 737these sequences to produce colored text output. 738 739:: 740 741 python3 -m pip install termcolor 742 743.. code:: python 744 745 >>> from termcolor import colored 746 >>> table.rows.append([colored("John", 'red'), 4, colored("boy", 'blue')]) 747 >>> print(table) 748 749.. raw:: html 750 751 <p style="font-family: monospace; background-color: #eeffcc;"> 752 +----+----------+------+--------+<br /> 753 | | name | rank | gender |<br /> 754 +----+----------+------+--------+<br /> 755 | S1 | Jacob | 1 | boy |<br /> 756 +----+----------+------+--------+<br /> 757 | S2 | Isabella | 1 | girl |<br /> 758 +----+----------+------+--------+<br /> 759 | S3 | Ethan | 2 | boy |<br /> 760 +----+----------+------+--------+<br /> 761 | S4 | Sophia | 2 | girl |<br /> 762 +----+----------+------+--------+<br /> 763 | S5 | Michael | 3 | boy |<br /> 764 +----+----------+------+--------+<br /> 765 | S6 | <span style="color: #ff0000;">John</span> | 4 | <span style="color: #0000ff;">boy</span> |<br /> 766 +----+----------+------+--------+ 767 </p> 768 769You can also use these sequences for making texts bold, italics, etc. 770 771------------------------------------------------------------------------- 772Paragraphs 773------------------------------------------------------------------------- 774 775A cell can contain multiple paragraphs such that each one start from 776a new line. **beautifultable** parses ``\n`` as a paragraph change. 777 778.. code:: python 779 780 >>> new_table = BeautifulTable(max_width=40) 781 >>> new_table.columns.header = ["Heading 1", "Heading 2"] 782 >>> new_table.rows.append(["first Line\nsecond Line", "single line"]) 783 >>> new_table.rows.append(["first Line\nsecond Line\nthird Line", "first Line\nsecond Line"]) 784 >>> new_table.rows.append(["single line", "this is a very long first line\nThis is a very long second line"]) 785 >>> print(new_table) 786 +-------------+------------------------+ 787 | Heading 1 | Heading 2 | 788 +-------------+------------------------+ 789 | first Line | single line | 790 | second Line | | 791 +-------------+------------------------+ 792 | first Line | first Line | 793 | second Line | second Line | 794 | third Line | | 795 +-------------+------------------------+ 796 | single line | this is a very long fi | 797 | | rst line | 798 | | This is a very long se | 799 | | cond line | 800 +-------------+------------------------+ 801 802------------------------------------------------------------------------- 803Subtables 804------------------------------------------------------------------------- 805 806You can even render a :class:`.BeautifulTable` instance inside another 807table. To do that, just pass the table as any regular text and it just 808works. 809 810.. code:: python 811 812 >>> subtable = BeautifulTable() 813 >>> subtable.rows.append(["Jacob", 1, "boy"]) 814 >>> subtable.rows.append(["Isabella", 1, "girl"]) 815 >>> subtable.left_border_char = '' 816 >>> subtable.right_border_char = '' 817 >>> subtable.top_border_char = '' 818 >>> subtable.bottom_border_char = '' 819 >>> parent_table = BeautifulTable() 820 >>> parent_table.columns.header = ["Heading 1", "Heading 2"] 821 >>> parent_table.rows.append(["Sample text", "Another sample text"]) 822 >>> parent_table.rows.append([subtable, "More sample text"]) 823 >>> parent_table.columns.padding_left[0] = 0 824 >>> parent_table.columns.padding_right[0] = 0 825 >>> print(parent_table) 826 +---------------------+---------------------+ 827 | Heading 1 | Heading 2 | 828 +---------------------+---------------------+ 829 | Sample text | Another sample text | 830 +---------------------+---------------------+ 831 | Jacob | 1 | boy | More sample text | 832 |----------+---+------| | 833 | Isabella | 1 | girl | | 834 +---------------------+---------------------+ 835 836========================================================================= 837Streaming Tables 838========================================================================= 839 840There are situations where data retrieval is slow such as when data is 841recieved over a network and you want to display the data as soon as 842possible. In these cases, you can use streaming tables to render the table 843with the help of a generator. 844 845Streaming table do have their limitation. The width calculation routine 846requires you to either set it manually or specify the column header or 847add atleast 1 row. You also cannot have row headers for streaming tables. 848 849.. code:: python 850 851 >>> import time 852 >>> def time_taking_process(): 853 ... for i in range(5): 854 ... time.sleep(1) 855 ... yield [i, i**2] 856 ... 857 ... 858 >>> table = BeautifulTable() 859 >>> table.columns.header = ["Number", "It's Square"] 860 >>> for line in table.stream(time_taking_process()): 861 ... print(line) 862 ... 863 +--------+-------------+ 864 | Number | It's Square | 865 +--------+-------------+ 866 | 0 | 0 | 867 +--------+-------------+ 868 | 1 | 1 | 869 +--------+-------------+ 870 | 2 | 4 | 871 +--------+-------------+ 872 | 3 | 9 | 873 +--------+-------------+ 874 | 4 | 16 | 875 +--------+-------------+ 876 877========================================================================= 878Support for Multibyte Unicode characters 879========================================================================= 880 881**beautifultable** comes with built-in support for multibyte unicode such as 882east-asian characters. 883 884You can do much more with BeautifulTable but this much should give you a 885good start. Those of you who are interested to have more control can 886read the API Documentation. 887