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

callback(ctx, version=False)

Azure Functions scaffold CLI.

Source code in src/azure_functions_scaffold/cli.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
@app.callback()
def callback(
    ctx: typer.Context,
    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()
    if ctx.invoked_subcommand is None:
        typer.echo(ctx.get_help())
        raise typer.Exit()

legacy_add(ctx, trigger=typer.Argument(..., help='Trigger type (e.g. http, timer, queue).'), function_name=typer.Argument(..., help='Function name.'), project_root=typer.Option(Path('.'), '--project-root', '-p', help='Project root.'), dry_run=typer.Option(False, '--dry-run', help='Preview without writing files.'))

DEPRECATED shim. Forwards to the modern command.

Source code in src/azure_functions_scaffold/cli.py 
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
@app.command(
    "add",
    deprecated=True,
    help="DEPRECATED: use 'afs api add' (http) or 'afs advanced add <trigger>' instead.",
    hidden=False,
)
def legacy_add(
    ctx: typer.Context,
    trigger: str = typer.Argument(..., help="Trigger type (e.g. http, timer, queue)."),
    function_name: str = typer.Argument(..., help="Function name."),
    project_root: Path = typer.Option(Path("."), "--project-root", "-p", help="Project root."),
    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without writing files."),
) -> None:
    """DEPRECATED shim. Forwards to the modern command."""
    del ctx
    normalized = trigger.strip().lower()
    if normalized == "http":
        replacement = f"afs api add {function_name} --project-root {project_root}"
    else:
        replacement = f"afs advanced add {normalized} {function_name} --project-root {project_root}"
    typer.echo(
        f"warning: 'afs add' is deprecated and will be removed in a future release. "
        f"Use: {replacement}",
        err=True,
    )
    from azure_functions_scaffold.errors import ScaffoldError
    from azure_functions_scaffold.generator import add_function, describe_add_function

    try:
        if dry_run:
            for line in describe_add_function(
                project_root=project_root, trigger=normalized, function_name=function_name
            ):
                typer.echo(line)
        else:
            path = add_function(
                project_root=project_root, trigger=normalized, function_name=function_name
            )
            typer.echo(f"Created: {path}")
    except ScaffoldError as exc:
        typer.echo(f"Error: {exc}", err=True)
        raise typer.Exit(code=1) from exc

legacy_profiles()

DEPRECATED shim. Forwards to 'afs presets'.

Source code in src/azure_functions_scaffold/cli.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
@app.command(
    "profiles",
    deprecated=True,
    help="DEPRECATED: use 'afs presets' instead.",
    hidden=False,
)
def legacy_profiles() -> None:
    """DEPRECATED shim. Forwards to 'afs presets'."""
    typer.echo(
        "warning: 'afs profiles' is deprecated and will be removed in a future release. "
        "Use: afs presets",
        err=True,
    )
    show_presets()

new(project_name=typer.Argument(..., help='Directory name for the new project.'), destination=Path('.'), python_version='3.10', include_github_actions=False, initialize_git=False, include_azd=False, dry_run=False, overwrite=False, yes=False)

Create a new API project (shortcut for 'afs api new').

Source code in src/azure_functions_scaffold/cli.py 
 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
@app.command("new")
def new(
    project_name: str = typer.Argument(..., help="Directory name for the new project."),
    destination: DestinationOption = Path("."),
    python_version: PythonVersionOption = "3.10",
    include_github_actions: GithubActionsOption = False,
    initialize_git: GitOption = False,
    include_azd: AzdOption = False,
    dry_run: DryRunOption = False,
    overwrite: OverwriteOption = False,
    yes: YesOption = False,
) -> None:
    """Create a new API project (shortcut for 'afs api new')."""
    run_intent(
        "api/new",
        project_name,
        destination=destination,
        python_version=python_version,
        include_github_actions=include_github_actions,
        initialize_git=initialize_git,
        include_azd=include_azd,
        dry_run=dry_run,
        overwrite=overwrite,
        yes=yes,
    )

show_presets()

List available project presets.

Source code in src/azure_functions_scaffold/cli.py 
69
70
71
72
73
74
@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 
62
63
64
65
66
@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

IntentSpec(template, preset, features=frozenset()) dataclass

Maps a CLI intent (e.g. 'api/new') to its template, preset, and features.

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
  • ADDABLE_TRIGGERS - Tuple of trigger names that can be added to an existing project via 'afs advanced add'. Excludes templates (e.g. langgraph) that only support full project creation.

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