erlab.io.metadata

Fill loaded data metadata from spreadsheet rows.

Spreadsheet metadata sources match a loaded path’s bare file name directly against a spreadsheet row, falling back to its file number when needed. Selected columns are then mapped to scalar coordinates or attributes on data returned by erlab.io.load().

SpreadsheetMetadataSource(*[, ...])	Base class for spreadsheet-backed loader metadata.
SpreadsheetMetadataError	Base class for failures reading a configured spreadsheet source.
ExcelMetadataSource(path, *[, sheet_name, ...])	Metadata source backed by a local Excel worksheet.
GoogleSheetsMetadataSource(share_url, *[, ...])	Metadata source backed by a publicly readable Google Sheets link.

Classes

ExcelMetadataSource(path, *[, sheet_name, ...])	Metadata source backed by a local Excel worksheet.
GoogleSheetsMetadataSource(share_url, *[, ...])	Metadata source backed by a publicly readable Google Sheets link.
SpreadsheetMetadataSource(*[, ...])	Base class for spreadsheet-backed loader metadata.

Exceptions

SpreadsheetMetadataError

Base class for failures reading a configured spreadsheet source.

class erlab.io.metadata.ExcelMetadataSource(path, *, sheet_name=0, file_name_column=None, coordinate_mapping=None, attribute_mapping=None, overwrite=False, row_range=None)

Bases: SpreadsheetMetadataSource

Metadata source backed by a local Excel worksheet.

Parameters:

• path (str | Path) – Path to an .xlsx or .xlsm workbook.

• sheet_name (str | int, default: 0) – Worksheet name or zero-based worksheet index.

• file_name_column (str | None, default: None) – See SpreadsheetMetadataSource.

• coordinate_mapping (Mapping[str, str] | None, default: None) – See SpreadsheetMetadataSource.

• attribute_mapping (Mapping[str, str] | None, default: None) – See SpreadsheetMetadataSource.

• overwrite (bool, default: False) – See SpreadsheetMetadataSource.

• row_range (tuple[int, int] | None, default: None) – See SpreadsheetMetadataSource.

Notes

Worksheet names and headers are cached, while row content is read from the workbook for every metadata lookup. Call refresh() to revalidate the selected worksheet and header.

refresh()

Refresh the cached worksheet selection and column names.

property source_name: str

class erlab.io.metadata.GoogleSheetsMetadataSource(share_url, *, sheet_name=None, timeout=10.0, file_name_column=None, coordinate_mapping=None, attribute_mapping=None, overwrite=False, row_range=None)

Bases: SpreadsheetMetadataSource

Metadata source backed by a publicly readable Google Sheets link.

Parameters:

• share_url (str) – Shareable link copied from Google Sheets. The linked worksheet is used automatically.

• sheet_name (str | None, default: None) – Visible tab name of another worksheet to use instead of the worksheet linked by share_url. The name is validated against the workbook’s worksheet list before any concurrently fetched values are accepted. If the link has no worksheet and this is omitted, the first worksheet is used.

• timeout (float, default: 10.0) – HTTP request timeout in seconds.

• file_name_column (str | None, default: None) – See erlab.io.metadata.SpreadsheetMetadataSource.

• coordinate_mapping (Mapping[str, str] | None, default: None) – See erlab.io.metadata.SpreadsheetMetadataSource.

• attribute_mapping (Mapping[str, str] | None, default: None) – See erlab.io.metadata.SpreadsheetMetadataSource.

• overwrite (bool, default: False) – See erlab.io.metadata.SpreadsheetMetadataSource.

• row_range (tuple[int, int] | None, default: None) – See erlab.io.metadata.SpreadsheetMetadataSource.

Notes

The spreadsheet must be shared publicly or with anyone who has the link. Numeric and boolean CSV values are converted to Python scalars; other values retain their displayed text. Worksheet names and headers are cached, while row content is read again for every metadata lookup. Independent requests needed for an uncached lookup run concurrently. Worksheet names are still validated so that an invalid sheet_name cannot silently fall back to the first worksheet.

get_selected_sheet_name()

Return the visible name of the worksheet selected by the link or name.

refresh()

Refresh the cached worksheet validation and column names.

property source_name: str

exception erlab.io.metadata.SpreadsheetMetadataError

Bases: Exception

Base class for failures reading a configured spreadsheet source.

The exception describes one attempted read. It does not invalidate the source, so callers may retry after a temporary network, permission, or filesystem failure.

class erlab.io.metadata.SpreadsheetMetadataSource(*, file_name_column=None, coordinate_mapping=None, attribute_mapping=None, sheet_name=None, overwrite=False, row_range=None)

Bases: ABC

Base class for spreadsheet-backed loader metadata.

Use the subclasses ExcelMetadataSource or GoogleSheetsMetadataSource to read metadata from a specific spreadsheet format.

Parameters:

• file_name_column (str | None, default: None) – Header of the column containing the file name or number used to match loaded data. For path-based loads, whitespace-trimmed cell text is first matched exactly and case-sensitively against the file name without its path or final extension. The loader derives a file number from the path with erlab.io.dataloader.LoaderBase.infer_index() for numeric fallback and to check whether a range also claims a direct match. That number is compared with spreadsheet cells containing an integer or a simple filename ending in a number, such as f_0001.pxt. Cells can also contain an inclusive range separated by ~ or an en dash, such as f_0015~20 or f_0015~f_0020. file_name_column may be omitted while inspecting get_sheet_names() or get_column_names().

• coordinate_mapping (Mapping[str, str] | None, default: None) – Mapping from spreadsheet headers to scalar coordinate names. This and attribute_mapping may both be omitted while inspecting get_column_names(), but at least one is required when applying metadata. The normalized mapping is immutable after construction.

• attribute_mapping (Mapping[str, str] | None, default: None) – Mapping from spreadsheet headers to attribute names. The normalized mapping is immutable after construction.

• sheet_name (str | int | None, default: None) – Worksheet name or zero-based worksheet index. If omitted, the source chooses its default worksheet.

• overwrite (bool, default: False) – Whether spreadsheet values replace existing scalar coordinates and attributes.

• row_range (tuple[int, int] | None, default: None) – Optional inclusive range of 1-based data row numbers to search. Row 1 contains headers, so the first valid data row is 2.

Notes

Configured source-column names are matched exactly first. If no exact header exists, a spreadsheet header containing newlines also matches the same name with each newline replaced by a space.

property attribute_mapping: Mapping[str, str]

Immutable mapping from spreadsheet columns to attribute names.

property coordinate_mapping: Mapping[str, str]

Immutable mapping from spreadsheet columns to coordinate names.

property file_name_column: str | None

Spreadsheet column used to resolve the file name or number.

get_column_names()

Return the spreadsheet column names.

Only the header row is read on the first call. The result is reused until refresh() is called. A new list is returned on every call so modifying it does not affect the cached column names.

Returns:

list of str – Column names from the first spreadsheet row, in their original order.

Return type:

list[str]

get_selected_sheet_name()

Return the visible name of the selected worksheet.

The worksheet list is read on the first call and then follows the same cache lifetime as get_sheet_names().

get_sheet_names()

Return the worksheet names in workbook order.

The names are read on the first call and reused until refresh() is called. A new list is returned on every call.

Returns:

list of str – Visible worksheet names in workbook order.

Return type:

list[str]

property overwrite: bool

Whether mapped values replace existing metadata.

refresh()

Clear and revalidate cached spreadsheet structure.

Sources that always read current row content only revalidate their cached worksheet and header information.

property row_range: tuple[int, int] | None

Inclusive range of 1-based spreadsheet data rows to search.

property sheet_name: str | int | None

Selected worksheet name or index.

abstract property source_name: str

Human-readable source name used in messages.