Skip to content

API Reference

This page documents the Python API surface for azure-functions-scaffold. Use it when embedding scaffold behavior in tests, custom automation, or other developer tooling.

CLI-first project

The primary public interface is the command line (afs / azure-functions-scaffold). Python imports are useful for advanced flows, but CLI compatibility is the main stability target.

Module Overview

Core modules in the package:

  • azure_functions_scaffold.cli: Typer application and command handlers.
  • azure_functions_scaffold.scaffolder: project scaffolding orchestration.
  • azure_functions_scaffold.models: shared dataclasses for options and context.
  • azure_functions_scaffold.generator: add-function workflow and code updates.
  • azure_functions_scaffold.template_registry: template and preset discovery.
  • azure_functions_scaffold.errors: domain-specific exception types.

Import Patterns

from pathlib import Path

from azure_functions_scaffold.models import ProjectOptions
from azure_functions_scaffold.scaffolder import (
    describe_scaffold_project,
    scaffold_project,
)
from azure_functions_scaffold.template_registry import build_project_options

options = build_project_options(
    preset_name="strict",
    python_version="3.12",
    include_github_actions=True,
    initialize_git=False,
    include_openapi=True,
    include_validation=True,
    include_doctor=True,
)

preview = describe_scaffold_project(
    project_name="my-api",
    destination=Path("."),
    template_name="http",
    options=options,
)

for line in preview:
    print(line)

project_path = scaffold_project(
    project_name="my-api",
    destination=Path("."),
    template_name="http",
    options=options,
)
print(project_path)

Error Handling

Most failures raise ScaffoldError with actionable messages.

from pathlib import Path

from azure_functions_scaffold.errors import ScaffoldError
from azure_functions_scaffold.scaffolder import scaffold_project

try:
    scaffold_project(project_name="bad name", destination=Path("."))
except ScaffoldError as exc:
    print(f"Scaffold failed: {exc}")

Common failure classes include:

  • invalid project names
  • unknown templates or presets
  • unsupported Python versions
  • target directory collisions without overwrite
  • invalid add project roots

Stability Notes

Treat the following as stable integration points:

  • CLI commands and flags in CLI Reference
  • dataclasses in azure_functions_scaffold.models
  • high-level orchestration functions in azure_functions_scaffold.scaffolder

Treat internals as implementation details:

  • private helpers prefixed with _
  • direct template file internals under templates/
  • insertion-marker implementation details in generator internals

Programmatic dry-run

Use describe_scaffold_project and describe_add_function to integrate preview behavior in automation without touching the filesystem.

mkdocstrings Reference

The sections below are rendered directly from source using mkdocstrings.

CLI Module

add_project_function(trigger, function_name, project_root=Path('.'), dry_run=False)

Add a new function module to an existing scaffolded project.

Source code in src/azure_functions_scaffold/cli.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
@app.command("add")
def add_project_function(
    trigger: Annotated[
        str,
        typer.Argument(
            ...,
            help=f"Trigger type to add. Supported: {', '.join(SUPPORTED_TRIGGERS)}",
        ),
    ],
    function_name: Annotated[
        str,
        typer.Argument(..., help="Function name to add."),
    ],
    project_root: Annotated[
        Path,
        typer.Option(
            ".",
            "--project-root",
            help="Existing scaffolded project directory.",
        ),
    ] = Path("."),
    dry_run: Annotated[
        bool,
        typer.Option(
            "--dry-run",
            help="Preview the added files without modifying the project.",
        ),
    ] = False,
) -> None:
    """Add a new function module to an existing scaffolded project."""
    try:
        if dry_run:
            for line in describe_add_function(
                project_root=project_root,
                trigger=trigger,
                function_name=function_name,
            ):
                typer.echo(line)
            return
        function_path = add_function(
            project_root=project_root,
            trigger=trigger,
            function_name=function_name,
        )
    except ScaffoldError as exc:
        typer.secho(str(exc), fg=typer.colors.RED)
        raise typer.Exit(code=1) from exc

    typer.echo(f"Created function at {function_path}")

callback(version=False)

Azure Functions scaffold CLI.

Source code in src/azure_functions_scaffold/cli.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@app.callback()
def callback(
    version: Annotated[
        bool,
        typer.Option(
            "--version",
            help="Show the installed version and exit.",
            is_eager=True,
        ),
    ] = False,
) -> None:
    """Azure Functions scaffold CLI."""
    if version:
        typer.echo(__version__)
        raise typer.Exit()

new_project(project_name=typer.Argument(None, help='Directory name for the new project. Omit to enter interactive mode.'), destination=Path('.'), template='http', preset='standard', python_version='3.10', include_github_actions=False, initialize_git=False, with_openapi=False, with_validation=False, with_doctor=False, interactive=False, dry_run=False, overwrite=False)

Create a new Azure Functions Python v2 scaffold.

Source code in src/azure_functions_scaffold/cli.py 
 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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
@app.command("new")
def new_project(
    project_name: str | None = typer.Argument(
        None,
        help="Directory name for the new project. Omit to enter interactive mode.",
    ),
    destination: DestinationOption = Path("."),
    template: TemplateOption = "http",
    preset: PresetOption = "standard",
    python_version: Annotated[
        str,
        typer.Option(
            "--python-version",
            help="Python version for the generated project.",
        ),
    ] = "3.10",
    include_github_actions: Annotated[
        bool,
        typer.Option(
            "--github-actions/--no-github-actions",
            help="Include a basic GitHub Actions CI workflow.",
        ),
    ] = False,
    initialize_git: Annotated[
        bool,
        typer.Option(
            "--git/--no-git",
            help="Initialize a git repository in the generated project.",
        ),
    ] = False,
    with_openapi: Annotated[
        bool,
        typer.Option(
            "--with-openapi/--no-openapi",
            help="Include OpenAPI documentation support (HTTP template only).",
        ),
    ] = False,
    with_validation: Annotated[
        bool,
        typer.Option(
            "--with-validation/--no-validation",
            help="Include request validation support (HTTP template only).",
        ),
    ] = False,
    with_doctor: Annotated[
        bool,
        typer.Option(
            "--with-doctor/--no-doctor",
            help="Include azure-functions-doctor health checks.",
        ),
    ] = False,
    interactive: Annotated[
        bool,
        typer.Option(
            "--interactive",
            "-i",
            help="Prompt for project options interactively.",
        ),
    ] = False,
    dry_run: Annotated[
        bool,
        typer.Option(
            "--dry-run",
            help="Preview the generated project without writing files.",
        ),
    ] = False,
    overwrite: Annotated[
        bool,
        typer.Option(
            "--overwrite",
            help="Replace an existing target directory before generating the project.",
        ),
    ] = False,
) -> None:
    """Create a new Azure Functions Python v2 scaffold."""
    try:
        resolved_name, resolved_template, resolved_options = _resolve_new_project_inputs(
            project_name=project_name,
            template=template,
            preset=preset,
            python_version=python_version,
            include_github_actions=include_github_actions,
            initialize_git=initialize_git,
            include_openapi=with_openapi,
            include_validation=with_validation,
            include_doctor=with_doctor,
            interactive=interactive or project_name is None,
        )
        if dry_run:
            for line in describe_scaffold_project(
                project_name=resolved_name,
                destination=destination,
                template_name=resolved_template,
                options=resolved_options,
                overwrite=overwrite,
            ):
                typer.echo(line)
            return
        project_path = scaffold_project(
            project_name=resolved_name,
            destination=destination,
            template_name=resolved_template,
            options=resolved_options,
            overwrite=overwrite,
        )
    except ScaffoldError as exc:
        typer.secho(str(exc), fg=typer.colors.RED)
        raise typer.Exit(code=1) from exc

    typer.echo(f"Created project at {project_path}")

show_presets()

List available project presets.

Source code in src/azure_functions_scaffold/cli.py 
250
251
252
253
254
255
@app.command("presets")
def show_presets() -> None:
    """List available project presets."""
    for preset in list_presets():
        tooling = ", ".join(preset.tooling) or "none"
        typer.echo(f"{preset.name}: {preset.description} [tooling: {tooling}]")

show_templates()

List available scaffold templates.

Source code in src/azure_functions_scaffold/cli.py 
243
244
245
246
247
@app.command("templates")
def show_templates() -> None:
    """List available scaffold templates."""
    for template in list_templates():
        typer.echo(f"{template.name}: {template.description}")

Scaffolder Module

Models Module

Additional Useful Modules

These modules are often imported by advanced users even though they are not the primary API entry points.

azure_functions_scaffold.generator

Use for adding triggers to existing projects:

  • add_function(...)
  • describe_add_function(...)
  • SUPPORTED_TRIGGERS

azure_functions_scaffold.template_registry

Use for template/preset discovery and input validation:

  • list_templates()
  • list_presets()
  • build_project_options(...)
  • validate_python_version(...)

azure_functions_scaffold.errors

Domain exception:

  • ScaffoldError