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
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¶
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
withsmartcols.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