os_helper.temp_utils module

Temporary Utilities

A scratch file that a function creates for its own bookkeeping (a downloaded archive before extraction, an intermediate render before the final one) is easy to forget to delete, and a crash mid-function skips whatever cleanup line was written after it. A context manager fixes that by tying the deletion to Python’s own with block: whether the block finishes normally or raises, the file or folder underneath it is removed on the way out.

temporary_filename() and temporary_folder() are that pattern for local disk. temporary_remote_file() extends the same guarantee to a remote store (S3, GCS, SFTP, anywhere): give it an upload and a delete callable already wired to your own credentials, and the remote copy is deleted on exit exactly like a local temp file would be. make_temporary_directory() is the one exception to the pattern, for when the caller genuinely needs to own cleanup itself rather than hand it to a with block.

Usage example

>>> import os_helper as osh
>>> with osh.temporary_filename(suffix=".log") as tmp:
...     tmp.endswith(".log")
True

Author

Warith HARCHAOUI, https://linkedin.com/in/warith-harchaoui

os_helper.temp_utils.make_temporary_directory(prefix='', directory=None)[source]

Create a temporary directory and return its path — caller owns cleanup.

The non-context-manager companion to temporary_folder(). Use this when the directory must outlive a with block: a request handler that schedules deletion after streaming a response, a process-lifetime scratch dir cleaned at exit, or any case where the created path is stored and removed later. It is the suite’s tempfile.mkdtemp() — the caller is responsible for removing the tree (e.g. via remove_directory() / shutil.rmtree / atexit).

Parameters:

  • prefix (str, optional) – Prefix for the directory name, aiding recognition in /tmp.

  • directory (str or None, optional) – Parent directory to create it in (default: the system temp location).

Returns:

Absolute path to the freshly created directory.

Return type:

str

Example

>>> work = make_temporary_directory(prefix="myjob-")
>>> # ... use `work`, then clean up when you are done ...
>>> remove_directory(work)
os_helper.temp_utils.temporary_filename(suffix='', mode='wt', prefix='', delete=True, directory=None)[source]

Create a temporary file with a unique name that persists even after closing.

This context manager generates a temporary file with a unique name, which is optionally removed after use. It ensures that temporary files are managed safely and are cleaned up to prevent clutter or security issues.

Parameters:

  • suffix (str, optional) – File suffix (e.g., “.txt”). Defaults to “”.

  • mode (str, optional) – Mode in which the file is opened (e.g., “wt” for writing text). Defaults to “wt”.

  • prefix (str, optional) – Prefix for the file name. Defaults to “”.

  • delete (bool, optional) – Whether to delete the file after exiting the context. Defaults to True.

  • directory (str or None, optional) – Parent directory to create the file in (default: the system temp dir). Use this when the temp file must sit next to other inputs — e.g. so a tool that resolves paths relative to the file still finds its siblings.

Yields:

str – The name of the temporary file.

Return type:

Generator[str, None, None]

Example

>>> with temporary_filename(suffix=".txt") as temp_file:
...     with open(temp_file, "wt") as fout:
...         fout.write("Temporary content")
...     # temp_file is automatically deleted after the block
os_helper.temp_utils.temporary_folder(prefix='', delete=True)[source]

Create a temporary directory with a unique name that persists during the context.

This context manager generates a temporary directory with a unique name, which is optionally removed after use. It ensures that temporary directories are managed safely and are cleaned up to prevent clutter or security issues.

Parameters:

  • prefix (str, optional) – Prefix for the folder name. Defaults to “”.

  • delete (bool, optional) – Whether to delete the directory and its contents after exiting the context. Defaults to True.

Yields:

str – The name of the temporary directory.

Return type:

Generator[str, None, None]

Example

>>> with temporary_folder(prefix="tempdir") as temp_dir:
...     # Use the temporary directory
...     with open(os.path.join(temp_dir, "file.txt"), "w") as f:
...         f.write("Temporary content")
...     # temp_dir and its contents are automatically deleted after the block
os_helper.temp_utils.temporary_remote_file(upload_function, delete_function, *, prefix='', suffix='', from_local_file=None, checkfile_function=None, mode='wb', initial_content=None)[source]

Context manager that uploads a file to a remote location and guarantees deletion of the remote artifact when the context exits.

Two modes:

  • If from_local_file is given, that existing local file is uploaded as-is and left untouched on cleanup; only the remote copy is deleted.

  • Otherwise, a uniquely named local temp file is created (optionally pre-populated with initial_content), uploaded, and removed locally when the context manager exits.

Useful for staging files to S3/GCS/SFTP/anywhere when you only need them briefly: pass in the upload + delete callables for your storage backend and the helper handles the lifecycle.

Parameters:

  • upload_function (Callable[[str], str]) – Called with a local file path; must return the remote path/URI.

  • delete_function (Callable[[str], None]) – Called with the remote path/URI to remove the remote artifact.

  • prefix (str, optional) – Prefix for the temporary file name (ignored when from_local_file is provided).

  • suffix (str, optional) – File extension for the temporary file (with or without leading “.”).

  • from_local_file (str, optional) – Path to an existing local file to upload instead of creating one.

  • checkfile_function (Callable[[str], bool], optional) – Optional post-upload sanity check; must return True for success.

  • mode (str, optional) – Open mode used when writing initial_content to the temp file. Defaults to "wb".

  • initial_content (bytes | str, optional) – Optional content written into the new temp file before upload. Type must match mode (bytes for "wb", str for "wt").

Yields:

str – The remote file path/URI returned by upload_function.

Raises:

  • TypeError – If any supplied callable is not actually callable.

  • FileNotFoundError – If from_local_file is given but the path does not exist.

  • RuntimeError – If checkfile_function is provided and returns False after upload.

Return type:

Generator[str, None, None]

Examples

>>> storage = {}
>>> def upload(p):
...     with open(p, "rb") as f: storage[p] = f.read()
...     return p
>>> def delete(r):
...     storage.pop(r, None)
>>> with temporary_remote_file(upload, delete, suffix=".bin",
...                            initial_content=b"hello") as remote:
...     assert storage[remote] == b"hello"
>>> # remote artifact is gone after the block