file_utils.py

Overview

file_utils.py is a utility module designed to programmatically create a variety of common file types with simple, predefined content. It provides independent functions to generate files such as DOCX, Excel (XLSX), PowerPoint (PPTX), images, PDFs, plain text, Markdown, JSON, EML (email), and HTML files. Each function creates a minimal example of the file format, writes it to the specified path, and returns the path for further use.

This module is useful in contexts where automated file generation is needed for testing, templating, or demonstration purposes. It abstracts the complexity of using different libraries and APIs for each file format behind easy-to-use functions.

Functions

All functions accept a single parameter path specifying the file path where the generated file will be saved. They return the same path after successfully creating the file.

1. create_docx_file(path: str) -> str

Creates a Microsoft Word DOCX file containing a single paragraph of text.

• Parameters:

  • path (str): The output filepath for the DOCX file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_docx_file("example.docx")
  

• Details:
  Uses the python-docx library to create a new document, add a paragraph with the text "This is a test DOCX file.", and save it.

2. create_excel_file(path: str) -> str

Creates an Excel XLSX file with a single worksheet and "Test Excel File" in cell A1.

• Parameters:

  • path (str): The output filepath for the Excel file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_excel_file("example.xlsx")
  

• Details:
  Uses the openpyxl library to create a workbook, access the active sheet, set cell A1, and save.

3. create_ppt_file(path: str) -> str

Generates a PowerPoint PPTX file with a single title slide containing the title "Test PPT File".

• Parameters:

  • path (str): The output filepath for the PPTX file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_ppt_file("example.pptx")
  

• Details:
  Uses the python-pptx library to create a presentation, add a slide from the default layout, set the slide title, and save.

4. create_image_file(path: str) -> str

Creates a 100x100 pixel blue RGB image with the white text "Test" drawn on it.

• Parameters:

  • path (str): The output filepath for the image file (e.g., PNG, JPEG).

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_image_file("example.png")
  

• Details:
  Uses the Pillow (PIL) library to create an image, draw text, and save.

5. create_pdf_file(path: str) -> str

Generates a simple PDF file with the string "Test PDF File" written near the top.

• Parameters:

  • path (str): The output filepath for the PDF file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_pdf_file("example.pdf")
  

• Details:
  Uses the reportlab library's canvas to draw text and save the PDF.

• Implementation Note:
  Converts non-string path inputs to string to avoid errors.

6. create_txt_file(path: str) -> str

Creates a plain text file with a fixed test content.

• Parameters:

  • path (str): The output filepath for the TXT file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_txt_file("example.txt")
  

• Details:
  Opens a file in write mode with UTF-8 encoding and writes static content.

7. create_md_file(path: str) -> str

Generates a Markdown file containing a header and a paragraph.

• Parameters:

  • path (str): The output filepath for the Markdown file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_md_file("example.md")
  

• Details:
  Writes simple Markdown syntax into the file.

8. create_json_file(path: str) -> str

Creates a JSON file with a sample dictionary containing a message and a numeric value.

• Parameters:

  • path (str): The output filepath for the JSON file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_json_file("example.json")
  

• Details:
  Uses Python's built-in json module to serialize and pretty-print data.

9. create_eml_file(path: str) -> str

Generates a simple EML (email) file with typical email headers and a body.

• Parameters:

  • path (str): The output filepath for the EML file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_eml_file("example.eml")
  

• Details:
  Writes raw string representing email headers and content.

10. create_html_file(path: str) -> str

Creates a basic HTML file with a title and a header.

• Parameters:

  • path (str): The output filepath for the HTML file.

• Returns:

  • path (str): The path where the file was saved.

• Usage Example:

  create_html_file("example.html")
  

• Details:
  Writes a minimal HTML structure as plain text.

Important Implementation Details

• The module relies on multiple third-party libraries for specific file formats:

  • python-docx for DOCX files.

  • openpyxl for XLSX files.

  • python-pptx for PPTX files.

  • Pillow for image files.

  • reportlab for PDF files.

• For simpler text-based formats (TXT, MD, JSON, EML, HTML), the module uses standard Python file I/O.

• Each file creation function is synchronous and blocking.

• The functions do not handle exceptions internally; callers should implement error handling as needed.

• File paths should be writable locations; no directory creation logic is included.

Interaction with Other System Components

• This utility module is likely to be used by higher-level components that require automated file generation for:

  • Testing file processing pipelines.

  • Creating sample files for demos or user interfaces.

  • Seeding data in file-based workflows.

• It can be integrated with file upload handlers, file validation systems, or automated report generators.

• Since each function returns the file path, the files can then be passed to other system parts for uploading, parsing, or further processing.

Visual Diagram: Function Flowchart of file_utils.py

flowchart TD
    A[Start: Call create_*_file(path)] --> B{Which file type?}
    B --> |DOCX| C[create_docx_file]
    B --> |Excel| D[create_excel_file]
    B --> |PPTX| E[create_ppt_file]
    B --> |Image| F[create_image_file]
    B --> |PDF| G[create_pdf_file]
    B --> |TXT| H[create_txt_file]
    B --> |MD| I[create_md_file]
    B --> |JSON| J[create_json_file]
    B --> |EML| K[create_eml_file]
    B --> |HTML| L[create_html_file]

    C --> M[Write file to disk]
    D --> M
    E --> M
    F --> M
    G --> M
    H --> M
    I --> M
    J --> M
    K --> M
    L --> M

    M --> N[Return file path]

    style M fill:#f9f,stroke:#333,stroke-width:1px
    style N fill:#bbf,stroke:#333,stroke-width:1px

Summary

file_utils.py serves as a straightforward, library-encapsulated toolkit for generating example files across a broad range of formats. Its simple interface and use of well-established libraries make it a practical choice for developers needing quick, programmatic file creation without delving into format-specific details.