Skip to content

API

Auto-generated from source docstrings and type annotations. See index.md for how mkdocstrings works and docstring conventions.

Engine

Core business logic — version info, environment diagnostics, and data processing. This module is interface-agnostic and contains no CLI or HTTP dependencies.

engine

Core business logic and processing engine.

This module contains the core functionality of the application, independent of any interface (CLI, API, etc.). It should be interface-agnostic and focused purely on domain logic.

Typical contents
  • Data processing functions
  • Business rule implementations
  • Core algorithms
  • State management
  • Environment diagnostics
Usage

from simple_python_boilerplate.engine import process_data

Example

from simple_python_boilerplate.engine import process_data result = process_data(input_data)

VersionInfo

Bases: TypedDict

Version information structure.

DiagnosticInfo

Bases: TypedDict

Environment diagnostic information structure.

get_version_info()

Get version information for the package and environment.

Returns:

Type Description
VersionInfo

Dictionary with version details.

diagnose_environment()

Diagnose the development environment.

Returns:

Type Description
DiagnosticInfo

Dictionary with diagnostic information.

process_data(data)

Process input data and return result.

Parameters:

Name Type Description Default
data str

Input data to process.

 required

Returns:

Type Description
str

Processed data string.

validate_input(data)

Validate input data before processing.

Parameters:

Name Type Description Default
data str

Input data to validate.

 required

Returns:

Type Description
bool

True if valid, False otherwise.

Main

Application entry points — the glue between CLI parsing and engine logic. Configured as console scripts in pyproject.toml under [project.scripts].

main

Application entry points (thin wrappers).

This module contains the entry points configured in pyproject.toml. These are the functions that get called when users run CLI commands. They should be thin wrappers that delegate to cli.py for argument parsing and engine.py for logic.

File Workflow

main.py → starts the program (entry points, thin wrappers) cli.py → defines CLI contract (argument parsing, commands) engine.py → defines behavior (core logic, interface-agnostic) api.py → defines callable interface (HTTP/REST, optional)

Entry points (configured in pyproject.toml): - main: Primary CLI command - print_version: Show version info - doctor: Diagnose environment issues

See Also
  • cli.py: Argument parsing and command structure
  • engine.py: Core business logic
  • api.py: HTTP/REST interface

main()

Main CLI entry point.

Delegates to cli.run() for argument parsing and dispatch.

print_version()

Print version information and exit.

start()

Bootstrap the project for first-time setup.

Runs scripts/bootstrap.py from the repository root so new contributors can type spb-start instead of remembering the full python scripts/bootstrap.py path.

All arguments are forwarded to the bootstrap script, so spb-start --dry-run works exactly like python scripts/bootstrap.py --dry-run.

doctor()

Diagnose environment and configuration issues.

Delegates to engine.diagnose_environment() for the actual checks, then formats the output for the terminal.

CLI

Command-line interface definitions and argument parsing. Uses argparse from the standard library.

cli

Command-line interface definitions and argument parsing.

This module handles CLI argument parsing and command definitions. It provides the user-facing command structure while delegating actual work to the engine module. Entry points in main.py call into this module.

Typical contents
  • Argument parser setup
  • Command definitions
  • Input validation for CLI
  • Output formatting for terminal
Usage

As entry point (configured in pyproject.toml)

$ my-command --help

Programmatic

from simple_python_boilerplate.cli import parse_args, run args = parse_args() run(args)

Note

For simple CLIs, argparse is sufficient. For complex CLIs, consider click, typer, or rich-click.

create_parser()

Create and configure the argument parser.

Returns:

Type Description
ArgumentParser

Configured ArgumentParser instance.

parse_args(args=None)

Parse command-line arguments.

Parameters:

Name Type Description Default
args Sequence[str] | None

Arguments to parse. If None, uses sys.argv.

 None

Returns:

Type Description
Namespace

Parsed arguments namespace.

run(args)

Execute the CLI based on parsed arguments.

Parameters:

Name Type Description Default
args Namespace

Parsed command-line arguments.

 required

Returns:

Type Description
int

Exit code (0 for success, non-zero for errors).

API Layer

HTTP/REST interface helpers. Currently a placeholder — choose a framework (FastAPI, Flask, etc.) and implement.

api

HTTP/REST API interface.

This module provides the API layer for the application. It handles HTTP requests, routing, serialization, and response formatting. The actual business logic is delegated to the engine module.

Typical contents
  • Route handlers / endpoints
  • Request/response models
  • Authentication middleware
  • API-specific error handling
Usage

With FastAPI

from simple_python_boilerplate.api import app uvicorn.run(app, host="0.0.0.0", port=8000)

With Flask

from simple_python_boilerplate.api import app app.run()

Note

This is a placeholder. Choose your framework (FastAPI, Flask, etc.) and implement accordingly.

create_app()

Create and configure the API application.

Returns:

Type Description
Any

Configured application instance.

health_check()

Check API health status.

Returns:

Type Description
dict[str, str]

Health status dictionary.

Dev Tools

Development utilities (not part of the public API). Provides cache cleanup and build artifact removal used by scripts/clean.py and task clean.

dev_tools

Development tools for repository maintenance.

See Also