scaffold_kit package¶
Subpackages¶
Submodules¶
scaffold_kit.checklist module¶
Generates a checklist of files in a directory.
This module scans the current directory and creates a text-based checklist of all files, excluding those specified in an ignore file (e.g., .gitignore). Each file in the checklist is marked with an ‘[x]’ if it contains content or ‘[ ]’ if it is empty. The final checklist is saved to a file and printed to the console.
- Usage:
To run this script, navigate to your project’s root directory and execute it as a module:
$ uv run python -m scaffold_kit.checklist
- scaffold_kit.checklist.file_is_empty(file_path: str) bool[source]¶
Checks if a file is empty by checking its size.
- Parameters:
file_path – The path to the file.
- Returns:
True if the file’s size is 0 bytes, False otherwise.
- scaffold_kit.checklist.generate_checklist(ignore_file: str = '.gitignore', output_file: str = 'checklist.txt', output_dir: str | None = None)[source]¶
Generates a checklist of files and directories in the current directory.
The traversal is hierarchical. Within each directory, entries are sorted case-insensitively with directories first and then files. Directories are always marked “[x]”. Files are marked “[ ]” if empty and “[x]” otherwise. Paths matching patterns from the ignore file are skipped. The checklist is written to the output location and printed to stdout.
- Parameters:
ignore_file – Name of the ignore file with patterns (e.g., “.gitignore”).
output_file – Name of the output checklist file.
output_dir – Directory for the output file. Created if it does not exist.
- Raises:
OSError – If writing the checklist file fails due to I/O errors.
- scaffold_kit.checklist.walk_sorted(base: Path, root: Path | None = None) list[str][source]¶
Walks a directory tree and returns relative paths in hierarchical order.
Directories appear before files within each directory, both sorted case-insensitively. Parent directories are listed before their children.
- Parameters:
base – The base path to walk.
root – The root used to compute relative paths. Defaults to the base.
- Returns:
A list of relative paths as strings in stable, hierarchical order.
scaffold_kit.config module¶
Provides utilities for locating and loading configuration files.
This module searches for a configuration file in the current directory, supporting multiple names and formats (YAML and JSON). It then loads the first file found and uses the values to set a series of module-level constants, providing sensible defaults if the file or specific keys are not found.
- Demo:
To run the module’s demonstration code, use the following command:
$ uv run python -m scaffold_kit.config
- scaffold_kit.config.CHECKLIST_DIRECTORY = 'docs/checklists'¶
Constant signifying checklist directory config.
- scaffold_kit.config.CHECKLIST_FILE = 'empty-files-checklist.txt'¶
Constant signifying checklist file config.
- scaffold_kit.config.IGNORE_FILE = '.scaffoldignore'¶
Constant signifying ignore file config.
- scaffold_kit.config.SCAFFOLD_FILE = 'scaffold.yaml'¶
Constant signifying scaffold file config.
- scaffold_kit.config.TREE_DIRECTORY = 'docs/trees'¶
Constant signifying tree directory config.
- scaffold_kit.config.TREE_FILE = 'tree.txt'¶
Constant signifying tree file config.
- scaffold_kit.config.find_config_file() str | None[source]¶
Searches for a configuration file in the current directory.
The function checks for a predefined list of filenames in a specific order to locate a configuration file.
- Returns:
The path to the first configuration file found, or None if no file is found.
scaffold_kit.init module¶
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
- scaffold_kit.init.init_project(example_name: str | None = None) int[source]¶
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:
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:
0 for success, 1 if any errors occurred.
- Return type:
Exit code
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
scaffold_kit.main module¶
Main CLI entry point for scaffold-kit.
This module provides a unified command-line interface for all scaffold-kit subcommands: init, scaffold, checklist, and tree. It imports the core functionality from each module and builds a proper CLI interface around them.
- Usage:
To run this script, navigate to your project’s root directory or parent directory and execute it as a module: $ uv run python -m scaffold_kit.main init [options] $ uv run python -m scaffold_kit.main scaffold [options] $ uv run python -m scaffold_kit.main checklist $ uv run python -m scaffold_kit.main tree [options] $ uv run python -m scaffold_kit.main –help
During development: $ uv run scaffold-kit init [options] $ uv run scaffold-kit scaffold [options] $ uv run scaffold-kit checklist $ uv run scaffold-kit tree [options] $ uv run scaffold-kit –help
After installation: $ scaffold-kit init [options] $ scaffold-kit scaffold [options] $ scaffold-kit checklist $ scaffold-kit tree [options] $ scaffold-kit –help
scaffold_kit.scaffold module¶
Creates project structure from a structured data file.
This module provides the core logic for the scaffolding utility. It can read a project structure definition from a YAML or JSON file and create the corresponding folders and files in the current working directory. It handles common use cases like root-level project folders, nested structures, and skipping existing files.
- Usage:
To run this script, navigate to your project’s root directory or parent directory and execute it as a module:
# Generate from project’s root directory: $ uv run python -m scaffold_kit.scaffold
# Generate project’s parent directory: $ uv run python -m scaffold_kit.scaffold –root
- scaffold_kit.scaffold.main()[source]¶
Main entry point to run the scaffolding process.
Parses command-line arguments and runs the scaffolding process.
- scaffold_kit.scaffold.read_structure_file(scaffold_file: str) dict[str, Any][source]¶
Reads a project structure file and returns its content.
This function attempts to load a project structure definition from either a YAML or JSON file. It prioritizes the file extension provided, but will raise an error if the file is not found.
- Parameters:
scaffold_file – The name of the file to read (e.g., ‘scaffold.yaml’).
- Returns:
The content of the file as a dictionary.
- Raises:
ValueError – If a found file has invalid YAML or JSON syntax.
FileNotFoundError – If the specified scaffold_file is not found in the current working directory.
- scaffold_kit.scaffold.scaffold_project(root: bool = False, scaffold_file: str = 'scaffold.yaml') dict[str, Any][source]¶
Creates a project structure from a structured data file.
This function reads a project structure definition from a YAML or JSON file and creates the corresponding folders and files. It supports creating a top-level root folder and recursively creating nested files and directories.
- Parameters:
root – If True, creates the top-level folder defined in the structure file. If False, it scaffolds the contents directly in the current directory.
scaffold_file – The path to the project structure definition file.
- Returns:
The parsed data from the structure file as a dictionary.
- Raises:
OSError – If a file or directory cannot be created due to permissions.
ValueError – If a found file is not valid YAML or JSON.
FileNotFoundError – If the specified file is not found.
scaffold_kit.tree module¶
Generates a hierarchical tree representation of a directory.
This module scans a specified directory, builds a hierarchical structure of its contents, and renders a text-based tree diagram. It uses an IgnoreParser to exclude files and directories based on patterns found in a specified ignore file (e.g., ‘.gitignore’). The generated tree is written to a file and also printed to the console.
- Usage:
To run this script, navigate to your project’s root directory and execute it as a module:
# Generate full project tree: $ uv run python -m scaffold_kit.tree
# Generate partial tree from subdirectory: $ uv run python -m scaffold_kit.tree my_project/data
- scaffold_kit.tree.build_tree_structure(paths: list[str], ignore_matches: Callable) dict[source]¶
Builds a hierarchical tree structure from a list of file paths.
- Parameters:
paths – A list of file/directory paths.
ignore_matches – A function to check if a path should be ignored.
- Returns:
A nested dictionary representing the directory structure.
- scaffold_kit.tree.generate_tree(root_dir: str = '.', ignore_file: str = '.gitignore', output_file: str = 'directory-tree.txt', output_dir: str | None = None)[source]¶
Generates a directory tree of files in the specified directory.
The function scans a directory, applies ignore patterns, and creates a text-based tree representation that is saved to a file and printed to the console.
- Parameters:
root_dir – The root directory to scan (default: current directory).
ignore_file – The name of the file containing ignore patterns.
output_file – The name of the output file for the tree.
output_dir – The directory where the output file will be saved. (default: current directory).
- Raises:
SystemExit – If the specified root_dir does not exist.
- scaffold_kit.tree.main()[source]¶
Main entry point to run the directory tree generation process.
Parses command-line arguments and runs the tree generation process.
- scaffold_kit.tree.render_tree(tree: dict, prefix: str = '', current_path: str = '') list[source]¶
Recursively renders the tree structure with proper tree characters.
- Parameters:
tree – The nested dictionary representing the directory structure.
prefix – The current line prefix for indentation.
current_path – The full path to the current directory being processed.
- Returns:
A list of formatted lines representing the tree structure.
- scaffold_kit.tree.sort_tree_items(items: list, current_path: str = '') list[source]¶
Sorts items with directories first, then files, both alphabetically.
- Parameters:
items – A list of (name, subtree) tuples.
current_path – The current path for checking if items are directories.
- Returns:
A sorted list of (name, subtree) tuples.
