Exporters¶

def supported_formats() -> list[str]:
    """Return the export format identifiers accepted by
    [`get_exporter`][recursivist.exporters.get_exporter].

    This is the single source of truth for which formats are valid; callers (e.g. the
    CLI) should derive their validation from it rather than hard-coding a list.

    Returns:
        The supported format identifiers, sorted for stable presentation. Alias keys are
        included, so both ``"md"`` and ``"markdown"`` appear.
    """
    return sorted(_EXPORTERS)

def canonical_extension(format_type: str) -> str:
    """Return the canonical output file extension for a format identifier.

    The extension is read from the exporter class, so aliases that share an exporter
    collapse to a single extension.

    Args:
        format_type: Export format identifier (e.g. ``"json"`` or ``"markdown"``).
            Matched case-insensitively.

    Returns:
        The exporter's canonical file extension, without a leading dot (e.g. ``"md"``
        for both ``"md"`` and ``"markdown"``). Falls back to the lowercased
        *format_type* for unknown formats, mirroring
        [`get_exporter`][recursivist.exporters.get_exporter]'s lookup.
    """
    exporter_class = _EXPORTERS.get(format_type.lower())
    if exporter_class is not None and exporter_class.extension:
        return exporter_class.extension
    return format_type.lower()

def get_exporter(format_type: str, **kwargs: Any) -> BaseExporter:
    """Construct the exporter for a given format.

    Args:
        format_type: Export format identifier (e.g. ``"json"`` or ``"txt"``). Matched
            case-insensitively; ``"md"`` and ``"markdown"`` are equivalent.
        **kwargs: Keyword arguments forwarded to the exporter's constructor (see
            [`BaseExporter`][recursivist.exporters.base.BaseExporter]).

    Returns:
        A ready-to-use exporter instance; call its ``export`` method to write the output
        file.

    Raises:
        ValueError: If *format_type* is not a supported format.
    """
    exporter_class = _EXPORTERS.get(format_type.lower())
    if not exporter_class:
        raise ValueError(
            f"Unsupported export format: {format_type}. "
            f"Supported formats: {', '.join(_EXPORTERS.keys())}"
        )

    return exporter_class(**kwargs)

def write_text(output_path: str, text: str) -> None:
    """Atomically write *text* to *output_path* as UTF-8.

    Lone surrogates, which stand in for the undecodable bytes of a non-UTF-8 file name,
    are replaced with U+FFFD so the text always encodes.

    The text is written to a temporary file in the destination directory, which is then
    renamed over the destination. A failure at any point leaves an existing file
    untouched and creates no partial one. Symbolic links are followed and the
    permissions of a file being overwritten are kept, as with a plain ``open``. A
    destination that exists but is not a regular file (such as ``/dev/stdout``) cannot
    be replaced, so it is written to directly.

    Args:
        output_path: Path the file is written to.
        text: Content to write.

    Raises:
        OSError: If the file cannot be written.
    """
    text = _SURROGATES.sub("\ufffd", text)
    target = os.path.realpath(output_path)
    if os.path.exists(target):
        if not os.path.isfile(target):
            with open(target, "w", encoding="utf-8") as f:
                f.write(text)
            return
        if not os.access(target, os.W_OK):
            raise PermissionError(errno.EACCES, os.strerror(errno.EACCES), output_path)

    temp_path = os.path.join(
        os.path.dirname(target), f".recursivist-{secrets.token_hex(8)}.tmp"
    )
    try:
        with open(temp_path, "x", encoding="utf-8") as f:
            f.write(text)
        with contextlib.suppress(OSError):
            shutil.copymode(target, temp_path)
        os.replace(temp_path, target)
    except BaseException:
        with contextlib.suppress(OSError):
            os.unlink(temp_path)
        raise