2.4. pycsamt.io#

Input/output configuration and parser helpers.

Unified readers, writers, and configuration-file I/O.

class pycsamt.io.Config#

Bases: object

Container of un‐modifiable I/O settings and lookup tables.

property parsers: dict[str, callable]#: Mapping of file extensions → pandas reader functions.

static writers(obj)#

Mapping of file extensions → DataFrame writer methods. Pass in the DataFrame (or similar) instance as obj.

Return type:: dict[str, callable]

pycsamt.io.read_any(path, **kwargs)#

Read a table‐like file into a pandas object using the Config parser map.

Parameters:

path (str) – Path to file. Extension must be one of Config().parsers.keys().
**kwargs – Passed directly to the pandas reader (e.g. sep, sheet_name, parse_dates, etc.)

Return type:

DataFrame or similar

pycsamt.io.write_any(obj, path, **kwargs)#

Write a pandas‐like object to disk using Config writers.

Parameters:

obj (pandas.DataFrame or similar)
path (str) – Output path with one of the Config.writers() extensions.
**kwargs – Passed directly to the pandas writer (e.g. index, compression, etc.)

class pycsamt.io.TransferFunctionFormat(name, reader, writer=None, extensions=(), detector=None, aliases=(), description='')#

Bases: object

Definition of one registered transfer-function serialization.

Parameters:

name (str) – Canonical, case-insensitive format name.
reader (callable) – Callable accepting the source as its first argument.
writer (callable, optional) – Callable accepting (object, target) for serialization.
extensions (tuple of str, optional) – Filename extensions used only as hints. Detection remains content based whenever a detector is available.
detector (callable, optional) – Callable returning True when the source belongs to this format.
aliases (tuple of str, optional) – Alternative names accepted by get_tf_format().
description (str, optional) – Human-readable summary.

name: str#

reader: Callable[[...], Any]#

writer: Callable[[...], Any] | None = None#

extensions: tuple[str, ...] = ()#

detector: Callable[[Any], bool] | None = None#

aliases: tuple[str, ...] = ()#

description: str = ''#

exception pycsamt.io.TransferFunctionFormatError#

Bases: ValueError

Raised when a transfer-function format cannot be resolved.

pycsamt.io.register_tf_format(name, *, reader, writer=None, extensions=(), detector=None, aliases=(), description='', replace=False)#

Register one transfer-function reader definition.

Registration is deliberately small and additive. A format may be readable without being writable; write support is advertised explicitly through the optional writer callable.

Parameters:

name (str)
reader (Callable[[...], Any])
writer (Callable[[...], Any] | None)
extensions (tuple[str, ...] | list[str])
detector (Callable[[Any], bool] | None)
aliases (tuple[str, ...] | list[str])
description (str)
replace (bool)

Return type:

TransferFunctionFormat

pycsamt.io.get_tf_format(name)#

Return a registered format by canonical name or alias.

Parameters:: name (str)
Return type:: TransferFunctionFormat

pycsamt.io.get_tf_format_for_target(target)#

Resolve a writable format from a target filename extension.

Content detection cannot be used for a file that does not yet exist. Therefore writing uses explicit format selection or a unique registered extension. Streams require an explicit format at the higher-level API.

Parameters:: target (Any)
Return type:: TransferFunctionFormat

pycsamt.io.list_tf_formats()#

Return stable public information about registered formats.

Return type:: dict[str, dict[str, Any]]

pycsamt.io.detect_tf_format(source)#

Detect the canonical transfer-function format from source content.

Detection is content-first. Filename extensions are intentionally not accepted as proof of a format; they are metadata hints stored in the registry for interfaces and future writer dispatch.

Parameters:: source (Any)
Return type:: str

class pycsamt.io.ModelFormat(name, reader, writer=None, extensions=(), detector=None, aliases=(), description='')#

Bases: object

Definition of one registered inversion-model serialization.

Parameters:

name (str) – Canonical, case-insensitive format name.
reader (callable) – Callable accepting the source as its first argument.
writer (callable, optional) – Callable accepting (object, target) for serialization.
extensions (tuple of str, optional) – Filename extensions used only as hints. Detection remains content based whenever a detector is available.
detector (callable, optional) – Callable returning True when the source belongs to this format.
aliases (tuple of str, optional) – Alternative names accepted by get_model_format().
description (str, optional) – Human-readable summary.

name: str#

reader: Callable[[...], Any]#

writer: Callable[[...], Any] | None = None#

extensions: tuple[str, ...] = ()#

detector: Callable[[Any], bool] | None = None#

aliases: tuple[str, ...] = ()#

description: str = ''#

exception pycsamt.io.ModelFormatError#

Bases: ValueError

Raised when an inversion-model format cannot be resolved.

pycsamt.io.register_model_format(name, *, reader, writer=None, extensions=(), detector=None, aliases=(), description='', replace=False)#

Register one inversion-model reader definition.

Parameters:

name (str)
reader (Callable[[...], Any])
writer (Callable[[...], Any] | None)
extensions (tuple[str, ...] | list[str])
detector (Callable[[Any], bool] | None)
aliases (tuple[str, ...] | list[str])
description (str)
replace (bool)

Return type:

ModelFormat

pycsamt.io.get_model_format(name)#

Return a registered format by canonical name or alias.

Parameters:: name (str)
Return type:: ModelFormat

pycsamt.io.get_model_format_for_target(target)#

Resolve a writable format from a target filename extension.

Content detection cannot be used for a file that does not yet exist. Therefore writing uses explicit format selection or a unique registered extension.

Parameters:: target (Any)
Return type:: ModelFormat

pycsamt.io.list_model_formats()#

Return stable public information about registered formats.

Return type:: dict[str, dict[str, Any]]

pycsamt.io.detect_model_format(source)#

Detect the canonical inversion-model format from source content.

Parameters:: source (Any)
Return type:: str

pycsamt.io.read_transfer_function(source, *, format=None, **kwargs)#

Read a supported electromagnetic transfer-function source.

Parameters:

source (path-like, str, bytes, or readable file object) – Input transfer-function source. Historical EDI currently requires a filesystem path because pycsamt.seg.EDIFile owns that parser. EMTF XML additionally accepts inline XML, bytes, and file-like input.
format (str, optional) – Explicit registered format name or alias. When omitted, content-based detection is used.
**kwargs – Passed to the selected backend reader.

Returns:

The established backend scientific object for the detected format. EDI returns EDIFile and EMTF XML returns EMTF. Explicit conversion between them is available through EMTF.from_edi() and EMTF.to_edi().

Return type:

object

pycsamt.io.write_transfer_function(obj, target, *, format=None, **kwargs)#

Write a transfer-function object through a registered serializer.

Parameters:

obj (object) – Scientific/backend object accepted by the selected writer. EMTF XML accepts pycsamt.emtf.EMTF; EDI accepts EMTF or the established pycsamt.seg.EDIFile.
target (path-like or writable stream) – Destination. A path ending in .xml can select EMTF XML automatically. Streams require format= because no extension is available before serialization.
format (str, optional) – Explicit registered format name or alias.
**kwargs – Passed to the selected backend writer.

Return type:

Any

Notes

EMTF -> EDI may be information-losing because standard EDI cannot carry every EMTF covariance, metadata, or arbitrary transfer-function type. The EDI writer exposes an on_loss policy through **kwargs.

pycsamt.io.read_tf(source, *, format=None, **kwargs)#

Read a supported electromagnetic transfer-function source.

Parameters:

source (path-like, str, bytes, or readable file object) – Input transfer-function source. Historical EDI currently requires a filesystem path because pycsamt.seg.EDIFile owns that parser. EMTF XML additionally accepts inline XML, bytes, and file-like input.
format (str, optional) – Explicit registered format name or alias. When omitted, content-based detection is used.
**kwargs – Passed to the selected backend reader.

Returns:

The established backend scientific object for the detected format. EDI returns EDIFile and EMTF XML returns EMTF. Explicit conversion between them is available through EMTF.from_edi() and EMTF.to_edi().

Return type:

object

pycsamt.io.write_tf(obj, target, *, format=None, **kwargs)#

Write a transfer-function object through a registered serializer.

Parameters:

obj (object) – Scientific/backend object accepted by the selected writer. EMTF XML accepts pycsamt.emtf.EMTF; EDI accepts EMTF or the established pycsamt.seg.EDIFile.
target (path-like or writable stream) – Destination. A path ending in .xml can select EMTF XML automatically. Streams require format= because no extension is available before serialization.
format (str, optional) – Explicit registered format name or alias.
**kwargs – Passed to the selected backend writer.

Return type:

Any

Notes

EMTF -> EDI may be information-losing because standard EDI cannot carry every EMTF covariance, metadata, or arbitrary transfer-function type. The EDI writer exposes an on_loss policy through **kwargs.

2.4.1. IO Modules#

`pycsamt.io.config`
`pycsamt.io.parsers`