Unused Path

Pick non-colliding file or folder names with browser-style numeric suffixes

unused-path is a dependency-free Python library that suggests unused_filename and unused_directory paths by appending incrementing numeric suffixes (for example report (1).pdf) when the target already exists. It supports custom formatters, optional atomic create=True to reduce races in concurrent workers, max_tries, and full type hints, as documented in the GitHub / PyPI package page.

When it is useful

You export downloads, backups, logs, or CSVs and need safe names without overwriting prior runs. It fits scripts, CLIs, and services that may write from multiple workers at once.

What you can do

Resolve a unique path next to an existing name, continuing the sequence if numbered siblings are already present.
Turn on atomic creation when you want the library to create the empty file or directory as part of claiming the name.
Plug in a formatter for styles like zero-padded versions or underscore numbering.

Limits

Uniqueness is filesystem-level at generation time; another process could still race you unless you use create=True appropriately.
Extremely dense directories could hit max_tries; handle RuntimeError from the API contract.
It does not manage retention, quotas, or cloud object-store semantics; only path naming.

Frequently asked questions

What does Unused Path generate?

It is a dependency-free Python library that suggests unused_filename and unused_directory paths by appending incrementing numeric suffixes (for example report (1).pdf) when the target already exists, similar to how browsers name duplicate downloads.

How do I install and call it?

Install with pip install unused-path, then from unused_path import unused_filename, unused_directory. Pass a desired path; if it exists, the library continues the numbered sequence of siblings.

How do I avoid races between workers?

Pass create=True for optional atomic creation of the empty file or directory when claiming the name. You can also plug in a custom formatter for styles like zero-padded versions or underscore numbering.

What happens if no free name is found?

Extremely dense directories can hit max_tries (default 10,000), which raises RuntimeError. Uniqueness is filesystem-level at generation time; the library does not manage retention, quotas, or cloud object-store semantics.