CSV to Markdown Converter

Common errors

• csv2md: command not found

  cause `csv2md` is not installed or the directory where `pip` installs scripts is not in your system's PATH.
  fix Run `pip install csv2md`. If the command still isn't found, ensure your pip script directory (e.g., `~/.local/bin` on Linux/macOS or `Scripts` folder in your Python install on Windows) is added to your system's PATH environment variable.

• Markdown table output is garbled or misaligned when CSV cells contain '|' characters.

  cause You are likely using an older version of `csv2md` that does not escape pipe characters in CSV cell values.
  fix Upgrade your `csv2md` installation: `pip install --upgrade csv2md`. Version `1.4.0` and later include the fix for pipe escaping.

• TypeError: convert() missing 1 required positional argument: 'input_csv_file'

  cause When calling `csv2md.convert()` programmatically, you must pass a file-like object (such as `io.StringIO(csv_data)`) as the `input_csv_file` argument.
  fix Correct your programmatic call to include a file-like object: `from csv2md import convert; import io; markdown_output = convert(io.StringIO(your_csv_string_data))`.

Warnings

• gotcha CSV cells containing pipe characters (`|`) were not escaped in Markdown output prior to `v1.4.0`, leading to malformed tables.
  Fix: Upgrade to `csv2md>=1.4.0` to ensure proper escaping of pipe characters in your Markdown tables.
• gotcha The `csv2md` library is primarily designed as a command-line tool. While programmatic use via `from csv2md import convert` is possible, the `convert` function expects a file-like object (like `io.StringIO` or an open file handle), not a file path string directly.
  Fix: When using `convert` programmatically, pass an `io.StringIO(csv_string)` object or an opened file handle as input, not a string representing the file path.
• gotcha Empty lines within CSV files were not consistently handled across all versions, potentially leading to errors or unexpected output. As of `v1.5.0`, empty lines are now properly ignored.
  Fix: Upgrade to `csv2md>=1.5.0` to ensure robust handling and ignoring of empty lines in your CSV input.

Install

• pip install csv2md Install csv2md

Imports

• convert
  wrong:

  import csv2md

  correct:

  from csv2md import convert

  The library is primarily a CLI tool. For programmatic use, import the 'convert' function, which expects a file-like object.

Quickstart

This quickstart demonstrates both command-line and programmatic usage. It creates a temporary CSV file and then uses `csv2md` to convert it. For CLI usage, ensure `csv2md` is installed and in your system's PATH. For programmatic use, the `convert` function expects a file-like object (e.g., `io.StringIO`).

import os
import subprocess
import tempfile
import io

# 1. Create a dummy CSV file for demonstration
csv_content = """Name,Age,City
Alice,30,New York
Bob,24,London
Charlie,22,"San Francisco|CA""" # Includes a pipe for testing escaping

csv_file_path = None
try:
    with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix=".csv", encoding="utf-8") as temp_csv_file:
        csv_file_path = temp_csv_file.name
        temp_csv_file.write(csv_content)
        temp_csv_file.flush() # Ensure content is written to disk

    print(f"--- CLI Usage (requires csv2md installed): {csv_file_path} ---")
    # This will only work if csv2md is installed and in PATH
    try:
        # Check if csv2md command is available
        subprocess.run(["csv2md", "--version"], capture_output=True, check=True)
        cmd_output = subprocess.run(
            ["csv2md", "--", csv_file_path], # Use -- to separate options from filename
            capture_output=True, text=True, check=True, encoding="utf-8"
        )
        print(cmd_output.stdout.strip())
    except FileNotFoundError:
        print("Skipping CLI example: 'csv2md' command not found. Please 'pip install csv2md'.")
    except subprocess.CalledProcessError as e:
        print(f"CLI Error: {e.stderr.strip()}")
        print(f"Output: {e.stdout.strip()}")


    print("\n--- Programmatic Usage (importing convert function) ---")
    try:
        from csv2md import convert
        # The 'convert' function expects a file-like object.
        input_stream = io.StringIO(csv_content)
        markdown_output = convert(input_stream)
        print(markdown_output.strip())
    except ImportError:
        print("Error: 'csv2md' library not found. Please 'pip install csv2md'.")
    except Exception as e:
        print(f"Programmatic Error: {e}")

finally:
    if csv_file_path and os.path.exists(csv_file_path):
        os.remove(csv_file_path)
        print(f"\nCleaned up temporary CSV: {csv_file_path}")