smartcols API Reference

Note

str represents both the types str and unicode. It is not compatible with the bytes type.

Warning

Don’t try to use copy.copy() or copy.deepcopy(), it’s not implemented and can break things.

Cell

class smartcols.Cell

Bases: object

Cell.

There is no way to create cell, only way to get this object is from smartcols.Line.

color

Color for text in cell.

Getter

Get color

Setter

Set color

Type

str or None

data

Text in cell.

Getter

Get text

Setter

Set text

Type

str or None

userdata

Private user data.

Getter

Get user data

Setter

Set user data

Type

object or None

Title

class smartcols.Title

Bases: smartcols.Cell

Title.

There is no way to create title, only way to get this object is from smartcols.Table.

color

Color for text in cell.

Getter

Get color

Setter

Set color

Type

str or None

data

Text in cell.

Getter

Get text

Setter

Set text

Type

str or None

position

Position.

Getter

Get position

Setter

Set position (accepts only str)

Type

smartcols.CellPosition

userdata

Private user data.

Getter

Get user data

Setter

Set user data

Type

object or None

Column

class smartcols.Column(self, name=None)

Bases: object

Column.

Parameters

name (str) – Column name

color

The default color for data cells in column and column header.

customwrap

Custom wrapping is activated.

header

The header of column. Used in table’s header.

Getter

Get header

Type

weakproxy to smartcols.Cell

hidden

Make column hidden for user.

name

The title of column. Shortcut for getting/setting data for smartcols.Column.header.

Getter

Get title

Setter

Set title

Type

str or None

right

Align text in cells to the right.

safechars

Bytes you don’t want to encode on output. This is for example necessary if you want to use custom wrap function based on newline character.

set_cmpfunc

Set sorting function for the column.

Parameters
  • func (object) – Comparison function

  • data (object) – Additional data for function

set_wrapfunc

Set wrapping functions for the column.

Parameters
  • func_chunksize (object) – Function which will return size of largest chunk

  • func_nextchunk (object) – Function which will return next chunk

  • data (object) – Additional data for function

strictwidth

Do not reduce width if column is empty.

tree

Use tree “ASCII Art”.

trunc

Truncate text in cells if necessary.

whint

Width hint of column.

wrap

Wrap long lines to multi-line cells.

Line

class smartcols.Line(self, parent=None)

Bases: object

Line.

Parameters

parent (smartcols.Line) – Parent line (used if table has column with tree-output)

Get cell

>>> table = smartcols.Table()
>>> column = table.new_column("FOO")
>>> line = table.new_line()
>>> line[column]
<smartcols.Cell object at 0x7f8fb6cc9900>

Set text to cell

>>> table = smartcols.Table()
>>> column = table.new_column("FOO")
>>> line = table.new_line()
>>> line[column] = "bar"
color

The color for data cells in line.

parent

Parent line.

Getter

Get parent line

Setter

Set parent line

Type

smartcols.Line

userdata

Private user data.

Getter

Get user data

Setter

Set user data

Type

object or None

Symbols

class smartcols.Symbols(self)

Bases: object

Symbols.

branch

String which represents the branch part of a tree output.

cell_padding

Padding of a table’s cells.

right

Right part of a tree output.

title_padding

Padding of a table’s title.

vertical

Vertical part of a tree output.

Table

class smartcols.Table(self)

Bases: object

Table.

Create and print table

>>> table = smartcols.Table()
>>> column_name = table.new_column("NAME")
>>> column_age = table.new_column("AGE")
>>> column_age.right = True
>>> ln = table.new_line()
>>> ln[column_name] = "Igor Gnatenko"
>>> ln[column_age] = "18"
>>> print(table)
NAME          AGE
Igor Gnatenko  18
add_column

Add column to the table.

Parameters

column (smartcols.Column) – Column

add_line

Add line to the table.

Parameters

line (smartcols.Line) – Line

ascii

Force the library to use ASCII chars for the smartcols.Column with smartcols.Column.tree activated.

colors

Enable/Disable colors.

column_separator

Column separator.

columns
Returns

Columns view

Return type

smartcols.ColumnsView

json
Returns

JSON dictionary

Return type

dict

line_separator

Line separator.

lines
Returns

Lines view

Return type

smartcols.LinesView

maxout

The extra space after last column is ignored by default. The output maximization use the extra space for all columns. In short words - use full width of terminal.

new_column

Create and add column to the table.

The arguments are the same as for the smartcols.Column constructor.

Returns

Column

Return type

smartcols.Column

new_line

Create and add line to the table.

The arguments are the same as for the smartcols.Line constructor.

Returns

Line

Return type

smartcols.Line

noheadings

Do not print header.

nolinesep

Enable/disable line separator printing. This is useful if you want to re-printing the same line more than once (e.g. progress bar). Don’t use it if you’re not sure.

nowrap

Never continue on next line, remove last column(s) when too large, truncate last column.

str_line

Print range of lines of the table to string including header.

Parameters
  • start (smartcols.Line) – First printed line or None to print from begin of the table

  • end (smartcols.Line) – Last printed line or None to print all lines from start

Returns

Lines

Return type

str

symbols

Used symbols. See smartcols.Symbols.

termforce

Force terminal output. One of auto, never, always.

termwidth

Terminal width. The library automatically detects terminal, in case of failure it uses 80 characters. You can override terminal width here.

title

Title of the table. Printed before table.

Getter

Get title object

Setter

Set title text (shortcut for smartcols.Title.data)

Type

weakproxy to smartcols.Title

tree

Tree-like output.

Getter

Get if tree-like output is expected

Type

bool

Useful Functions

smartcols.init_debug(mask=0)

Initialize debugging features. If mask equals to 0, then this function reads the LIBSMARTCOLS_DEBUG environment variable to get mask.

Don’t call this function multiple times.

Parameters

mask (int) – Debug mask (0xffff to enable full debugging)

smartcols.cmpstr_cells(c1, c2, data=None)

Shorthand wrapper around strcmp(). data is ignored.

Parameters
smartcols.wrapnl_chunksize(cl, data, userdata=None)

Split string by newline character and return size of the largest chunk.

Parameters
  • cl (smartcols.Column) – (unused) Column

  • data (str) – String

  • userdata (object or None) – (unused) Additional data

Returns

Size of the largest chunk

Return type

int

smartcols.wrapnl_nextchunk()

wrapnl_chunksize(cl, data, userdata=None)

Parameters
  • cl (smartcols.Column) – (unused) Column

  • data (str) – String

  • userdata (object or None) – (unused) Additional data

Returns

Chunk text and separator

Return type

tuple

Enumerations used by functions

class smartcols.CellPosition

Cell position. Currently used only in smartcols.Title.

left
Align text to the left.
center
Align text to the center.
right
Align text to the right.
class smartcols.TermForce

Control terminal output usage.

auto
Automatically detect if terminal or non-terminal output.
never
Force to use stdout as non-terminal output.
always
Force to use stdout as terminal output.