def savefile(fname, content, dt, dn, folder=None, decode=False, isprivate=0, df=None):…
- User
def save_file(fname, content, dt, dn, folder=None, decode=False, is_private=0, df=None): if decode: if isinstance(content, str): content = content.encode("utf-8")
if b"," in content: content = content.split(b",")[1] content = safe_b64decode(content) file_size = check_max_file_size(content) content_hash = get_content_hash(content) content_type = mimetypes.guess_type(fname)[0] fname = get_file_name(fname, content_hash[-6:]) file_data = get_file_data_from_hash(content_hash, is_private=is_private) if not file_data: call_hook_method("before_write_file", file_size=file_size) write_file_method = get_hook_method("write_file", fallback=save_file_on_filesystem) file_data = write_file_method(fname, content, content_type=content_type, is_private=is_private) file_data = copy(file_data) file_data.update( { "doctype": "File", "attached_to_doctype": dt, "attached_to_name": dn, "attached_to_field": df, "folder": folder, "file_size": file_size, "content_hash": content_hash, "is_private": is_private, } ) f = frappe.get_doc(file_data) f.flags.ignore_permissions = True try: f.insert() except frappe.DuplicateEntryError: return frappe.get_doc("File", f.duplicate_entry) return f - Assistant
The
save_filefunction you've provided is designed to handle file storage within the Frappe framework. It manages various aspects of file handling, including decoding, hashing, MIME type determination, deduplication, and database insertion. Here's a detailed breakdown of its functionality, along with some observations and potential improvements:Function Overview
def save_file(fname, content, dt, dn, folder=None, decode=False, is_private=0, df=None): # Function implementation- Purpose: Saves a file to the system, handling decoding (if necessary), ensuring the file size is within limits, avoiding duplicate storage by using content hashing, and associating the file with a specific document in Frappe.
Parameters
fname(str): The name of the file to be saved.content(str or bytes): The actual content of the file. IfdecodeisTrue, it can be a base64-encoded string.dt(str): The doctype to which the file is attached.dn(str): The name of the document to which the file is attached.folder(str, optional): The folder where the file will be stored.decode(bool, optional): Flag indicating whether the content needs to be base64-decoded.is_private(int, optional): Flag indicating if the file is private (1) or public (0).df(str, optional): The field name in the doctype that the file is attached to.
Step-by-Step Breakdown
-
Decoding Content (if required)
if decode: if isinstance(content, str): content = content.encode("utf-8") if b"," in content: content = content.split(b",")[1] content = safe_b64decode(content)- Purpose: If
decodeisTrue, the function decodes the content from a base64-encoded string to bytes. - Process:
- Ensures the content is in bytes.
- Splits the content at the first comma (common in data URIs) and decodes the second part.
- Uses
safe_b64decodeto decode the base64 content.
- Purpose: If
-
Validating File Size
file_size = check_max_file_size(content)- Purpose: Ensures the file does not exceed the maximum allowed size.
- Assumption: The
check_max_file_sizefunction likely raises an exception if the file is too large.
-
Generating Content Hash
content_hash = get_content_hash(content)- Purpose: Creates a hash of the file content to enable deduplication and integrity checks.
-
Determining MIME Type
content_type = mimetypes.guess_type(fname)[0]- Purpose: Guesses the MIME type based on the file extension, which is useful for serving the file correctly later.
-
Generating a Unique File Name
fname = get_file_name(fname, content_hash[-6:])- Purpose: Modifies the original filename to include a unique suffix derived from the content hash, reducing the likelihood of name collisions.
-
Checking for Existing File Data
file_data = get_file_data_from_hash(content_hash, is_private=is_private)- Purpose: Checks if a file with the same content hash already exists to avoid storing duplicate files.
-
Handling New File Entries
if not file_data: call_hook_method("before_write_file", file_size=file_size) write_file_method = get_hook_method("write_file", fallback=save_file_on_filesystem) file_data = write_file_method(fname, content, content_type=content_type, is_private=is_private) file_data = copy(file_data)- Purpose: If the file doesn't already exist:
- Invokes any pre-write hooks (
before_write_file), allowing for custom behavior or validations. - Determines the method to use for writing the file, allowing for customization via hooks. If no custom method is provided, it defaults to
save_file_on_filesystem. - Writes the file and makes a copy of the returned file data for further processing.
- Invokes any pre-write hooks (
- Purpose: If the file doesn't already exist:
-
Updating File Metadata
file_data.update( { "doctype": "File", "attached_to_doctype": dt, "attached_to_name": dn, "attached_to_field": df, "folder": folder, "file_size": file_size, "content_hash": content_hash, "is_private": is_private, } )- Purpose: Updates the file data with metadata, including associations to specific doctypes and fields, folder location, size, hash, and privacy settings.
-
Creating and Inserting the File Document
f = frappe.get_doc(file_data) f.flags.ignore_permissions = True try: f.insert() except frappe.DuplicateEntryError: return frappe.get_doc("File", f.duplicate_entry) return f- Purpose:
- Creates a new
Filedocument in Frappe with the prepared metadata. - Ignores permission checks to ensure the file can be inserted without user permission interference.
- Attempts to insert the document into the database.
- If a duplicate entry error occurs (i.e., the file already exists), it retrieves and returns the existing file document instead of inserting a new one.
- Creates a new
- Purpose:
Observations & Recommendations
-
Error Handling Enhancements
- While the function handles
DuplicateEntryError, other potential exceptions (e.g., decoding errors, file write failures) aren't explicitly handled. Consider adding more comprehensive error handling to provide clearer feedback or rollback mechanisms.
- While the function handles
-
Type Annotations & Docstrings
- Adding type hints and a docstring would improve the readability and maintainability of the function. It helps other developers understand the expected input types and the function's purpose without diving deep into the code.
from typing import Optional def save_file( fname: str, content: Union[str, bytes], dt: str, dn: str, folder: Optional[str] = None, decode: bool = False, is_private: int = 0, df: Optional[str] = None ) -> frappe.Document: """ Saves a file to the Frappe system, handling decoding, hashing, and deduplication. Parameters: fname (str): Name of the file. content (str or bytes): File content, optionally base64-encoded. dt (str): Doctype to which the file is attached. dn (str): Document name to which the file is attached. folder (str, optional): Folder to store the file in. decode (bool, optional): Whether to decode the content from base64. is_private (int, optional): Privacy flag (1 for private, 0 for public). df (str, optional): Field name in the doctype that the file is attached to. Returns: frappe.Document: The saved File document. """ -
Dependency Management
- Ensure that all helper functions (
safe_b64decode,check_max_file_size,get_content_hash,get_file_name,get_file_data_from_hash,call_hook_method,get_hook_method,save_file_on_filesystem) are properly imported and handle their own exceptions. Without seeing their implementations, it's crucial they behave as expected to prevent unexpected crashes.
- Ensure that all helper functions (
-
Security Considerations
- When handling file uploads, always ensure that the system is protected against malicious files. This includes validating file types, sanitizing filenames, and storing files in secure locations to prevent unauthorized access.
-
Performance Optimizations
- If the system handles a large number of files, consider implementing caching mechanisms for frequently accessed data, such as
get_file_data_from_hash, to reduce database load.
- If the system handles a large number of files, consider implementing caching mechanisms for frequently accessed data, such as
-
Logging
- Implement logging at critical steps (e.g., after decoding, before and after writing the file, upon catching exceptions) to aid in debugging and monitoring the system's behavior.
-
Extensibility
- The use of hooks (
before_write_file,write_file) is a good practice, allowing for customization without modifying the core function. Ensure comprehensive documentation for these hooks so that developers know how to extend or modify the file-saving behavior.
- The use of hooks (
Conclusion
The
save_filefunction is thoughtfully designed to handle file storage efficiently within the Frappe framework, addressing key aspects like decoding, deduplication, and metadata management. By incorporating the recommendations above, you can enhance its robustness, maintainability, and security, ensuring it serves as a reliable component in your application.