CLI File Staging and Collision Handling#

Overview#

The docling convert CLI command collects, resolves, and stages source files into a flat list of Path | str objects before handing them to DocumentConverter.convert_all(). The staging logic lives in the convert() function in docling/cli/main.py, and the lower-level URL-to-path resolution lives in docling_core/utils/file.py.

Input Resolution Pipeline#

All source arguments are iterated inside a tempfile.TemporaryDirectory() context 1. For each src string:

1. HTTP URL + HTML source — passed through as a bare str 2.
2. Local directory — recursively expanded by _iter_input_paths_from_directory(), which uses rglob("*"), filters by extension via _name_matches_format(), and skips temporary Word lock files (~$*.docx) 3.
3. Local file (HTML) — appended as a Path directly without further download 4.
4. Local file (all other formats) — passed through resolve_source_to_path() even though it already exists locally; see Staging via resolve_source_to_path below 5.
5. Remote URL (non-HTML) — passed to resolve_source_to_path(), which downloads the file into the shared tempdir 6.

Format filtering via --from is applied during directory expansion (step 2) and at the DocumentConverter level via allowed_formats=from_formats 7.

Staging via resolve_source_to_path#

resolve_source_to_path() in docling_core wraps the internal _resolve_source_to_path(), which:

1. Calls resolve_source_to_stream() to obtain a DocumentStream (either by HTTP download or local file read).
2. Derives a filename: for remote sources, it reads the Content-Disposition header first, then falls back to the URL path's basename, then to a "file" fallback 8.
3. Writes the stream to workdir / doc_stream.name — a flat path with no subdirectory structure 9.

The CLI passes workdir=Path(tempdir) — the single shared temporary directory — to every resolve_source_to_path() call 5 6.

Basename Collision Behavior (No Deduplication)#

There is no collision detection. When two different remote URLs or local files resolve to the same basename (e.g., both named report.pdf), the second write silently overwrites the first in workdir 9. The overwritten path is still added to input_doc_paths, so convert_all() processes it — but it now contains the content of whichever file was staged last.

The same silent-overwrite risk applies during output: export_documents() names every output file as {conv_res.input.file.stem}.{ext} 10. Two inputs sharing a stem (e.g., subdir_a/report.pdf and subdir_b/report.pdf) will produce colliding output files, with the last write winning.

Implication for directory inputs: _iter_input_paths_from_directory() preserves full absolute paths (it yields Path objects from rglob), so directory-sourced files are not routed through resolve_source_to_path() and are not staged into tempdir. They do not collide at the staging layer — but they can still collide at the output layer if two files in the directory share a stem.

Temporary Word File Filtering#

Lock files created by Microsoft Word (~$*.docx) are explicitly filtered out in two places: inside _iter_input_paths_from_directory() 11 and in the top-level source loop for direct file arguments 12.

Key Source Locations#