File I/O

class meyelens.fileio.BufferedFileWriter(path_to_file, filename: str = 'data', buffer_size: int = 1000, metadata=None, headers=None, sep: str = ';', extension: str = '.txt', flush_every: int = 50, flush_interval: float = 1.0, overflow_policy: str = 'raise', encoding: str = 'utf-8')

Bases: object

Initialize the writer.

Parameters:

• path_to_file (str or pathlib.Path) – Directory where the output file will be created.

• filename (str, optional) –

  Base filename. A timestamp is prepended and extension is appended.

  Example:

  filename=”subject01”

  produces something like:

  20260519_154201-subject01.txt

• buffer_size (int, optional) –

  Maximum number of rows allowed in the queue.

  If the acquisition loop produces rows faster than the background thread can write them, the queue grows. Once it reaches buffer_size, the behavior depends on overflow_policy.

• metadata (dict or None, optional) –

  Metadata written at the top of the file as comment lines:

  # subject: S01 # condition: baseline

  Metadata are written once at file creation.

• headers (list[str] or None, optional) –

  Column names. Written as the first non-comment row.

  If None, defaults to:

  [“timestamp”, “value”]

• sep (str, optional) – Separator used for headers and data rows. Default is ";".

• extension (str, optional) – File extension. Default is ".txt".

• flush_every (int, optional) –

  Flush the Python file buffer after this many written rows.

  This does not drain the queue. It only forces rows that have already been written to the file object to be pushed from Python’s buffer to the operating system.

  Smaller value:

  safer in case of crash, but slower.

  Larger value:

  faster, but more recently written rows may remain unflushed if the process crashes.

• flush_interval (float, optional) –

  Flush the Python file buffer at least every this many seconds.

  This is useful when the acquisition rate is low. For example, if flush_every=50 but only 5 rows are written per second, then without flush_interval the file might not flush for 10 seconds.

  The file is always flushed on close().

• overflow_policy ({"raise", "block", "drop"}, optional) –

  Behavior when the queue is full.

  ”raise”:

  Raise a RuntimeError immediately. Recommended for experiments.

  ”block”:

  Block until queue space is available. No data loss, but the acquisition loop may pause.

  ”drop”:

  Discard the new row and print a warning. Fast, but data loss is possible.

• encoding (str, optional) – File encoding. Default is "utf-8".

write(string: str) → bool

Queue a pre-formatted row.

Parameters:

string (str) – Row to write, without trailing newline.

Returns:

True if the row was queued. False only if overflow_policy="drop" and the queue is full.

Return type:

bool

Raises:

RuntimeError – If called after close(). If overflow_policy="raise" and the queue is full.

write_sv(values) → bool

Queue a separator-separated row.

Parameters:

values (iterable) – Values to serialize. Each element is converted to text.

Returns:

Same return value as write().

Return type:

bool

qsize() → int

Return the approximate number of rows currently waiting in the queue.

stats() → dict

Return writer statistics.

Returns:

Dictionary with queued, written, dropped, and current queue size.

Return type:

dict

close() → None

Stop the writer, drain the queue, flush the file buffer, and close.

This method is safe to call more than once.