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
-
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
-
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
-
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
-
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