xtl.common.tables module

xtl.common.tables module#

class xtl.common.tables.MissingValue[source]#

Bases: object

Represents a missing value.

Parameters:

value – The original value

__init__(value)#
Parameters:

value (Any)

Return type:

None

value: Any#
class xtl.common.tables.MissingValueConfig[source]#

Bases: object

Defines which values should be treated as missing and how they should be represented.

Parameters:

  • values – Values to consider as missing

  • repr – Value to use when representing missing values

  • checker – Optional function to check if a value should be considered missing

__init__(values, repr=XTLUndefined, checker=None)[source]#
Parameters:

  • values (Any)

  • repr (Any)

  • checker (Callable[[Any], bool] | None)

checker: Callable[[Any], bool] | None = None#
repr: Any = None#
to_repr(value)[source]#

Convert a value to its representation if it is considered missing.

Parameters:

value – The value to convert

Returns:

The representation if the value is missing, otherwise the original value

values: Set[Any]#
class xtl.common.tables.Table[source]#

Bases: object

__init__(data=None, *, headers=None, missing_values=XTLUndefined, missing_value_repr=None)[source]#

Initialize a Table object.

Parameters:

  • data (List[List[Any]] | None) – Optional data as a list of rows

  • headers (List[str] | None) – Optional list of column names

  • missing_values (MissingValueConfig | Any) – Values to consider as missing

  • missing_value_repr (Any | None) – Value to use for missing data when outputting

add_col(data=None, *, col_name=None)[source]#

Append a new column to the table.

Parameters:

  • data (List[Any] | Dict[str, Any] | str | None) – The column data to append

  • col_name (str | None) – The name of the new column

Raises:

  • ValueError – If the number of values does not match the number of rows

  • ValueError – If the table has headers but no column name is provided

add_row(data)[source]#

Append a new row to the table.

Parameters:

data (List[Any] | Dict[str | int, Any]) – The row data to append. Can be either: - A list of values in column order - A dictionary mapping column names/indices to values

Raises:

  • ValueError – If the row length does not match the number of columns

  • KeyError – If a dictionary key is a column name that doesn’t exist

  • IndexError – If a dictionary key is a column index that is out of range

property data: List[List[Any]]#

Get the raw data of the table.

Returns:

The table data as a list of rows

del_col(idx)[source]#

Remove a column by name or index.

Parameters:

idx (str | int) – The column name or index to remove

Raises:

  • KeyError – If the column name does not exist

  • IndexError – If the column index is out of range

del_row(idx)[source]#

Remove a row at the given index.

Parameters:

idx (int) – The row index to remove

Raises:

IndexError – If the row index is out of range

classmethod from_csv(s, *, delimiter=',', new_line='\n', header_line=None, header_char='')[source]#

Create a Table from a CSV file or string.

Parameters:

  • s (str | Path) – Path to CSV file or CSV string content

  • delimiter (str) – Delimiter used in the CSV (default: ‘,’)

  • header_line (int | None) – Line that contains headers (default: None)

  • header_char (str) – Character that might prefix the header line (e.g., ‘#’)

  • new_line (str)

Returns:

A new Table instance

Return type:

Table

classmethod from_dict(data, *, missing_values=XTLUndefined, missing_value_repr=None)[source]#

Create a Table from a dictionary of columns.

Parameters:

  • data (Dict[str | int, List[Any]]) – Dictionary with column names as keys and column data as values

  • missing_values (MissingValueConfig | Any) – Values to consider as missing

  • missing_value_repr (Any | None) – Value to use for missing data when outputting

Returns:

A new Table instance

Raises:

ValueError – If the columns are not of equal length

Return type:

Table

classmethod from_numpy(array, *, headers=None, missing_values=XTLUndefined, missing_value_repr=None)[source]#

Create a Table from a numpy ndarray.

Parameters:

  • array (np.ndarray) – 2D numpy array

  • headers (List[str] | None) – Optional list of column names

  • missing_values (MissingValueConfig | Any) – Values to consider as missing

  • missing_value_repr (Any) – Value to use for missing data when outputting

Returns:

A new Table instance

Raises:

  • ImportError – If numpy is not installed

  • ValueError – If the array is not 2D

Return type:

Table

classmethod from_pandas(df, *, missing_values=XTLUndefined, missing_value_repr=None)[source]#

Create a Table from a pandas DataFrame.

Parameters:

  • df (pd.DataFrame) – pandas DataFrame

  • missing_values (MissingValueConfig | Any) – Values to consider as missing

  • missing_value_repr (Any) – Value to use for missing data when outputting

Returns:

A new Table instance

Raises:

ImportError – If pandas is not installed

Return type:

Table

get_col(idx)[source]#

Get a column by name or index.

Parameters:

idx (str | int) – The column name or index

Raises:

  • KeyError – If the column name does not exist

  • IndexError – If the column index is out of range

Return type:

List[Any]

get_row(idx)[source]#

Get a row by index.

Parameters:

idx (int) – The row index

Return type:

List[Any]

property has_missing: bool#

Check if the table contains any missing values.

Returns:

True if there are missing values, False otherwise

property headers: List[str]#

Get the column headers.

Returns:

The column headers

items()[source]#

Iterate over columns as (name, values) pairs.

Return type:

Iterator[Tuple[str, List[Any]]]

property missing: MissingValueConfig#

Get the MissingValueConfig instance for this table.

Returns:

The MissingValueConfig instance

property no_cols: int#

Get the number of columns in the table.

Returns:

The number of columns

property no_rows: int#

Get the number of rows in the table.

Returns:

The number of rows

set_col(idx, values)[source]#

Set the data for a column by name or index.

Parameters:

  • idx (str | int) – The column name or index

  • values (List[Any]) – The new column data

Raises:

  • KeyError – If the column name does not exist

  • IndexError – If the column index is out of range

  • ValueError – If the number of values does not match the number of rows

set_row(idx, row)[source]#

Set the data for a row at a given index.

Parameters:

  • idx (int) – The row index

  • row (List[Any]) – The new row data

Raises:

ValueError – If the row length does not match the number of columns

property shape: Tuple[int, int]#

Get the shape of the table as (rows, columns).

Returns:

A tuple with the number of rows and columns

property size: int#

Get the total number of elements in the table.

Returns:

The total number of elements (rows * columns)

to_csv(filename=None, delimiter=',', new_line='\n', header_char='', overwrite=False, keep_file_ext=False)[source]#

Write the table to a CSV file. If filename is not provided, then the CSV will be returned as a string.

Parameters:

  • filename (str | Path | None) – Optional output path for the CSV file.

  • delimiter (str) – Delimiter to use in the CSV.

  • new_line (str) – Newline character to use in the CSV.

  • header_char (str) – Character to prepend to the header line (e.g., ‘#’).

  • overwrite (bool) – Overwrite the file if it already exists.

  • keep_file_ext (bool) – Keep the file extension if filename is provided.

Returns:

Either the CSV string or the output path.

Raises:

FileExistsError – If the file already exists and overwrite is False

Return type:

str | Path

to_dict()[source]#

Convert the table to a dictionary with column names as keys.

Returns:

The table data as a dictionary

Return type:

Dict[str | int, List[Any]]

to_list()[source]#

Convert the table to a flattened list

Returns:

The table data as a list

Return type:

List[Any]

to_numpy()[source]#

Convert the table to a numpy ndarray. Requires numpy to be installed.

Returns:

The table as a numpy array

Return type:

numpy.ndarray

to_pandas()[source]#

Convert the table to a pandas DataFrame. Requires pandas to be installed.

Returns:

The table as a DataFrame

Return type:

pandas.DataFrame

to_rich(cast_as=None)[source]#

Convert the table to a rich.Table for pretty console output. Requires rich to be installed.

Parameters:

cast_as (Callable) – Optional function to cast values before adding to the rich table

Returns:

The table as a rich Table object

Return type:

rich.table.Table

Contents