os_helper.temp_utils module

Temporary Utilities

This module provides helper functions and context managers for creating and managing temporary files and directories. It ensures that temporary resources are handled safely and cleaned up appropriately after use.

Author:
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