generate_folders.py

Overview

`generate_folders.py` is a utility script designed to automate the creation of nested folder structures populated with Python test files. It generates directories and test files according to user-specified numeric arguments, supporting multi-level folder hierarchies with customizable breadth and depth.

The script reads a predefined test file template (`template_test.py`) from the same directory and replicates its content into newly created test files or `__init__.py` files inside generated folders. This setup is useful for creating a scaffold of test modules for large Python projects, facilitating bulk test organization and initial setup.

Detailed Explanation

Constants and Globals

• HERE: A pathlib.Path object pointing to the directory where generate_folders.py resides.

• TEST_CONTENT: A bytes object containing the entire content of template_test.py read in binary mode. Used as a template for all generated test files and __init__.py files.

• parser: An argparse.ArgumentParser instance configured to accept zero or more integers as positional arguments named numbers.

Function: generate_folders

def generate_folders(root: pathlib.Path, elements: int, *more_numbers: int) -> None:

Purpose:

Recursively generates a folder hierarchy under the specified `root` path based on the numeric parameters provided.

Parameters:

• root (pathlib.Path): The base directory under which the folders and test files will be created.

• elements (int): The number of folders or test files to create at the current level.

• *more_numbers (int): Optional additional integers specifying subsequent levels of folder generation.

Behavior:

• Determines the zero-padding length (fill_len) for numbering folder or file names based on the number of elements.

• If more_numbers is not empty (i.e., there are further levels):

  • Creates elements subfolders named foo_<index> with zero-padded indices.

  • Inside each folder, writes an __init__.py file with the contents of template_test.py.

  • Recursively calls itself with the subfolder as the new root and the remaining numbers in more_numbers.

• If more_numbers is empty (last level):

  • Creates elements test files named test_<index>.py with zero-padded indices.

  • Writes the contents of template_test.py into each test file.

Return Value:

• None. The function performs filesystem operations and does not return any value.

Usage Example:

from pathlib import Path

# Generate 5 folders under "./tests", each containing 10 test files
generate_folders(Path("./tests"), 5, 10)

This will create:

./tests/
    foo_0/
        test_0.py
        test_1.py
        ...
        test_9.py
        __init__.py
    foo_1/
        ...
    ...
    foo_4/
        ...

Script Entry Point

if __name__ == "__main__":
    args = parser.parse_args()
    generate_folders(HERE, *(args.numbers or (10, 100)))

• Parses command line integer arguments (numbers).

• If no arguments are provided, defaults to generating 10 folders, each containing 100 test files.

• Calls generate_folders with the current directory (HERE) as the root and the parsed numbers as parameters.

**Example CLI Usage:**

python generate_folders.py 3 5 2

This generates 3 folders at the root level, each containing 5 subfolders, each of those containing 2 test files.

Implementation Details and Algorithms

• Zero-padding logic: The function calculates the zero-padding for folder and file numbering by taking the length of the string representation of elements. This ensures consistent lexicographical ordering of generated names.

• Recursive folder generation: The function uses recursion to handle arbitrary depths of folder nesting as dictated by the number of numeric arguments passed. Each recursive call reduces the unpacked more_numbers tuple until it is empty, at which point test files are created instead of folders.

• Template reuse: The template_test.py content is read once at script startup and reused as byte content for all generated files, optimizing I/O operations.

• File/directory creation: Uses pathlib.Path.mkdir() and pathlib.Path.write_bytes() for clean and cross-platform filesystem operations.

Interaction with Other Parts of the System

• Dependency on template_test.py: The script expects a file named template_test.py to exist in the same directory. This file serves as the template content for all generated test files and __init__.py files. Changes to this template directly affect the generated files.

• Usage in Project Setup: This file is likely used during project scaffolding or test environment setup phases, enabling rapid creation of complex test folder hierarchies.

• Command-line integration: It can be integrated into build systems or CI pipelines that need a large number of test modules generated dynamically.

Mermaid Diagram: Flowchart of Main Functions and Workflow

flowchart TD
    A[Start: Script Execution] --> B{Parse CLI Args}
    B --> |Args Provided| C[Call generate_folders(HERE, *args.numbers)]
    B --> |No Args| D[Call generate_folders(HERE, 10, 100)]
    C --> E[generate_folders Function]
    D --> E
    E --> F{more_numbers Present?}
    F --> |Yes| G[Create 'foo_i' folders with __init__.py]
    G --> H[Recursive call generate_folders(subfolder, *more_numbers)]
    H --> F
    F --> |No| I[Create 'test_i.py' files]
    I --> J[Write TEST_CONTENT into files]
    J --> K[End]

Summary

`generate_folders.py` is a recursive folder and test file generator that simplifies the setup of nested Python test module structures. It leverages a template test file and supports flexible multi-level generation defined by command-line numeric arguments. This utility is a practical aid for developers managing large test suites or needing automated scaffolding of test directories.