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(self, func, data=None)

Set sorting function for the column.

Parameters:
  • func (object) – Comparison function
  • data (object) – Additional data for function
set_wrapfunc(self, func_chunksize, func_nextchunk, data=None)

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(self, column)

Add column to the table.

Parameters:column (smartcols.Column) – Column
add_line(self, 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(self)
Returns:Columns view
Return type:smartcols.ColumnsView
json(self)
Returns:JSON dictionary
Return type:dict
line_separator

Line separator.

lines(self)
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(self, *args, **kwargs)

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(self, *args, **kwargs)

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.

str_line(self, start=None, end=None)

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.