Write Output Deep Dive

Write Output (Deep Dive)

write_output() in src/indicators.py builds a path and writes a polars.DataFrame using asyncio.to_thread so file I/O does not block the event loop.

Signature (conceptual)

write_output(df, dir, output_file, ticker, period, timeframe, type)

• type: the --format value (csv, parquet, …) — used to choose extension and writer.
• timeframe: passed through for auto-generated filenames when output_file is None.

Path resolution (cases)

Let type be the format string (e.g. csv). The final file path is chosen roughly as:

1. output_file set, dir set, type is None
   Join dir with output_file[0] (see quirks below).

2. output_file set, dir set, type not None
   Join dir with {basename}.{type} where basename is derived from output_file[0] (see quirks).

3. output_file is None, dir set
   {dir}/{ticker}_{period}_{timeframe}.{type}

4. output_file is None, dir is None
{ticker}_{period}_{timeframe}.{type}

Implementation quirks (read before relying on -o)

The branches use output_file[0] as if output_file were a one-element sequence. In Python, indexing a string with [0] returns the first character, not the filename. When run_main passes a normal string from -o out.csv, output_file[0] is "o", not "out.csv".

Practical guidance:

• Prefer auto naming (-d only, no -o) or verify output paths on your version.
• If you need predictable names, confirm behavior with a dry run or inspect written paths in logs.

When timeframe is not a string

Auto names use f"{ticker}_{period}_{timeframe}.{type}". If timeframe is a dict (timeframe JSON), the string representation may be unsuitable as a filename segment. Prefer explicit -o / outputs.txt patterns or a single string -t when filenames must be clean.

Writers

Extension	Polars method
.csv	write_csv
.parquet	write_parquet
.json	write_json
.xlsx	write_excel
.avro	write_avro
else	falls back to write_csv

Directory creation

If dir is set and does not exist, os.makedirs creates it.

Related pages:

• Output Writing
• CLI Parsing
• Advanced Usage