Skip to content

scaffold_kit.init

Project initialization module.

This module provides functionality to initialize new projects by copying example configuration and scaffold files from the scaffold_kit package. It supports copying individual example files or all example files at once to help users quickly set up their project structure.

Usage

To run this script, navigate to your project’s root directory or parent directory and execute it as a module:

Copy all example files:#

$ uv run python -m scaffold_kit.init

Copy a specific example file:#

$ uv run python -m scaffold_kit.scaffold config-file

init_project(example_name=None) #

Initialize a new project by copying example files.

This function initializes a new project by copying example files from the scaffold_kit package. It can copy either a specific example file or all example files to the current working directory.

Parameters:

Name Type Description Default
example_name Optional[str]

The name of the example file to copy. If None, all example files will be copied. Valid options include ‘ignore-file’, ‘config-file’, and ‘scaffold-file’.

 None

Returns:

Type Description
int

Exit code: 0 for success, 1 if any errors occurred.

Examples:

Copy a specific example file:

>>> init_project('config-file')
Successfully copied '.scaffoldkitrc.yaml' to the current directory.
0

Copy all example files:

>>> init_project()
No example specified. Copying all example files...
Successfully copied '.scaffoldignore' to the current directory.
Successfully copied '.scaffoldkitrc.yaml' to the current directory.
Successfully copied 'scaffold.yaml' to the current directory.
0
Source code in src/scaffold_kit/init.py 
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def init_project(example_name: Optional[str] = None) -> int:
    """Initialize a new project by copying example files.

    This function initializes a new project by copying example files from
    the scaffold_kit package. It can copy either a specific example file
    or all example files to the current working directory.

    Args:
        example_name: The name of the example file to copy.
            If None, all example files will be copied. Valid options include
            'ignore-file', 'config-file', and 'scaffold-file'.

    Returns:
        Exit code: 0 for success, 1 if any errors occurred.

    Examples:
        Copy a specific example file:
        >>> init_project('config-file')
        Successfully copied '.scaffoldkitrc.yaml' to the current directory.
        0

        Copy all example files:
        >>> init_project()
        No example specified. Copying all example files...
        Successfully copied '.scaffoldignore' to the current directory.
        Successfully copied '.scaffoldkitrc.yaml' to the current directory.
        Successfully copied 'scaffold.yaml' to the current directory.
        0
    """

    try:
        # Access the examples directory bundled with the package
        examples_path = importlib.resources.files("scaffold_kit").joinpath(
            "examples"
        )

        # Define mapping of user-friendly names to actual file paths
        file_map = {
            "ignore-file": examples_path.joinpath(".scaffoldignore"),
            "config-file": examples_path.joinpath(  # pylint: disable=too-many-function-args
                "configs", ".scaffoldkitrc.yaml"
            ),
            "scaffold-file": examples_path.joinpath(  # pylint: disable=too-many-function-args
                "scaffold", "scaffold.yaml"
            ),
        }

        exit_code = 0

        if example_name:
            # Copy specific file
            if example_name not in file_map:
                print(
                    f"Error: Example file '{example_name}' not found.",
                    file=sys.stderr,
                )
                print("Available options:")
                for key in file_map:
                    print(f"  - {key}")
                return 1

            source_path = file_map[example_name]
            destination_name = Path(source_path).name
            exit_code = _copy_file(source_path, destination_name)

        else:
            # Copy all files
            print("No example specified. Copying all example files...")
            for _, source_path in file_map.items():
                destination_name = Path(source_path).name
                result = _copy_file(source_path, destination_name)
                if result != 0:
                    exit_code = 1

        return exit_code

    except Exception as e:  # pylint: disable=broad-except
        print(f"Unexpected error accessing example files: {e}", file=sys.stderr)
        return 1

main() #

Main entry point to run the init process.

Parses command-line arguments and runs the init_project process.

Source code in src/scaffold_kit/init.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def main():
    """Main entry point to run the init process.

    Parses command-line arguments and runs the init_project process.
    """
    # 1. Create the argument parser.
    parser = argparse.ArgumentParser(
        description="Initialize a new project by copying example files."
    )
    # 2. Add the optional target argument.
    parser.add_argument(
        "target",
        type=str,
        nargs="?",
        choices=["ignore-file", "config-file", "scaffold-file"],
        help="Target file to copy (optional). "
        "If not provided, all files will be copied.",
    )
    args = parser.parse_args()

    # 3. Call the main scaffolding function with parsed arguments.
    exit_code = init_project(args.target)
    sys.exit(exit_code)