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.

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(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:	c1 (smartcols.Cell) – First cell c2 (smartcols.Cell) – Second cell data (`object` or None) – (unused) Additional data

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.

smartcols API Reference¶

Cell¶

Title¶

Column¶

Line¶

Symbols¶

Table¶

Useful Functions¶

Enumerations used by functions¶

python-smartcols

Navigation