Media

media

Defines helper functions to perform asynchronous file operations within the HOST_MEDIA_PATH directory

Paths

• BASE_PATH is the media root (HOST_MEDIA_PATH)

• TEMP_PATH and PROFILES_PATH are its temp and profiles subdirectories

• Operations take destinations relative to BASE_PATH, and get_relative_path converts an absolute path back to that format

Modal Paths

• When using the modal transcription backend, the server uploads input files to (and downloads processed files from) an ephemeral per-job volume shared between it and the Modal container running the job (See modal_processing.app)

• Both the server and the container pass the in-volume paths in which they've stored files so that the server's media handling doesn't depend on the container sharing its file system layout

• The media-relative path from get_relative_path is only used as the path in which the server stores files inside the modal volume to maintain consistency

clean_temp(check=False) async

Deletes everything in the temp directory and recreates it

Parameters:

Name	Type	Description	Default
check	bool	When True, raise on failure. Otherwise log and skip	False

Raises:

Type	Description
StorageError	If the directory cannot be cleared and check is True

copy_file(src, dest_relative) async

Copies a file to a destination relative to the media directory

Parameters:

Name	Type	Description	Default
src	str | PathLike[str]	Absolute source path of the file to copy	required
dest_relative	str | PathLike[str]	Destination path, relative to the media directory	required

Returns:

Type	Description
Path	The absolute path to the new file

Raises:

Type	Description
StorageError	If the file cannot be copied

delete_dir(dir_path_relative) async

Deletes a directory located relative to the media directory

Parameters:

Name	Type	Description	Default
dir_path_relative	str | PathLike[str]	Path of the directory to delete, relative to the media directory	required

Raises:

Type	Description
StorageError	If the directory cannot be deleted

delete_file(file_path_relative, check=False) async

Deletes a single file located relative to the media directory

Parameters:

Name	Type	Description	Default
file_path_relative	str | PathLike[str]	Path of the file to delete, relative to the media directory	required
check	bool	When True, raise on failure. Otherwise log and skip	False

Raises:

Type	Description
StorageError	If the file cannot be deleted and check is True

get_profile_dir(profile_id, subfolder)

Creates and returns a profile-specific subdirectory

Parameters:

Name	Type	Description	Default
profile_id	str	ID of the profile	required
subfolder	str	Subfolder within the profile's directory	required

Returns:

Type	Description
Path	The absolute path to the profile-specific subdirectory

get_relative_path(full_path)

Converts an absolute path into one relative to the media directory

Modal File Transfer

• This relative form is used as the file's path within the per-job ephemeral Modal volume when the server uploads it

• This is done so that the in-volume layout of media_files mirrors the HOST_MEDIA_PATH directory

• See modal_processing.app for more information on this

Parameters:

Name	Type	Description	Default
full_path	str | PathLike[str]	Absolute path inside the media directory	required

Returns:

Type	Description
Path	The path relative to BASE_PATH

Raises:

Type	Description
InvalidMediaPathError	If full_path is not inside the media directory

get_temp_dir(name)

Creates and returns a named directory inside TEMP_PATH

Parameters:

Name	Type	Description	Default
name	str	Name of the temporary directory	required

Returns:

Type	Description
Path	The absolute path to the created temporary directory

init_storage()

Creates the media directory tree (base, temp, profiles) if missing

Meant to be called once on application startup so module import stays free of filesystem side effects

move_file(src, dest_relative) async

Moves a file to a destination relative to the media directory

Parameters:

Name	Type	Description	Default
src	str | PathLike[str]	Absolute source path of the file to move	required
dest_relative	str | PathLike[str]	Destination path, relative to the media directory	required

Returns:

Type	Description
Path	The absolute path to the moved file

Raises:

Type	Description
StorageError	If the file cannot be moved

save_upload_file(request, output_path, tqdm_description=None) async

Saves a FastAPI.Request.stream to the file system by reading and writing the streamed chunks to output_path while logging the progress to a TQDM progress bar with tqdm_description as its message

Parameters:

Name	Type	Description	Default
request	Request	The FastAPI.Request object	required
output_path	str | PathLike[str]	File path in which to save the stream	required
tqdm_description	str | None	Optional description for the TQDM progress bar. When None, defaults to f"Saving File To {output_path}"	None

Returns:

Type	Description
Path	output_path, if the file was written successfully

Raises:

Type	Description
UploadError	If the upload fails for any reason

save_upload_object(upload, output_path) async

Saves a FastAPI.UploadFile (a multipart file part) to the file system by streaming it to output_path in chunks

Difference From save_upload_file

save_upload_file is used for large raw-body streamed uploads while save_upload_object is used for multipart uploads (File(...)) where the file travels alongside form metadata

Parameters:

Name	Type	Description	Default
upload	UploadFile	The multipart file part to save	required
output_path	str | PathLike[str]	File path in which to save it	required

Returns:

Type	Description
Path	output_path, if the file was written successfully

Raises:

Type	Description
UploadError	If the upload fails for any reason

write_file(file_path_relative, content) async

Writes text content to a file relative to the media directory, creating parent directories as needed

Parameters:

Name	Type	Description	Default
file_path_relative	str | PathLike[str]	Path of the file to write, relative to the media directory	required
content	str	Text content to append to the file	required

Returns:

Type	Description
Path	The absolute path to the written file

Raises:

Type	Description
StorageError	If the file cannot be written