mafw.scaffold

Project scaffolding service for the mafw init command.

This package turns a validated ProjectSpec into a ready-to-use MAFw analysis project on disk. It is deliberately separated from the command line presentation layer in mafw.scripts.mafw_exe: the service validates inputs, renders the canonical template bundled with MAFw, and writes the result atomically, while the command line layer only parses options, prompts the user, and reports results.

The public entry point is generate_project(). The typed error hierarchy (ScaffoldError and subclasses) lets the caller map every failure to a precise message and a non-zero exit code.

Added in version 2.4.

Functions

generate_project(spec)

Generate a MAFw analysis project described by spec and return its root.

exception mafw.scaffold.DestinationNotEmptyError

Bases: ScaffoldError

Raised when the resolved destination directory already contains entries.

The service never overwrites an existing, non-empty project; the user must pick an empty or non-existent destination instead.

exception mafw.scaffold.GenerationError

Bases: ScaffoldError

Raised when rendering or writing the project fails partway through.

The service rolls back to the exact pre-run filesystem state before raising this error, so no partially generated project is ever left behind.

exception mafw.scaffold.InvalidNameError

Bases: ScaffoldError

Raised when the requested project name cannot become a valid package name.

This covers an empty or over-long name, a name that does not match the Python package identifier grammar, and a name that contains a path separator or a ./.. path component (a traversal attempt).

exception mafw.scaffold.MissingTemplateError

Bases: ScaffoldError

Raised when the bundled canonical template cannot be located.

This indicates that the template package data was not shipped with the installed MAFw distribution; it is an installation problem rather than a user input problem.

exception mafw.scaffold.MissingValueError

Bases: ScaffoldError

Raised in non-interactive mode when a required value was not supplied.

In non-interactive mode the service never prompts, so a missing required value is a hard error that names each missing value.

exception mafw.scaffold.NameCollisionError

Bases: ScaffoldError

Raised when the derived import name clashes with a reserved name.

The clash is either a Python (hard or soft) keyword or a top-level module of the standard library; importing such a package would shadow or be shadowed by existing names, so generation is refused.

exception mafw.scaffold.ScaffoldError

Bases: Exception

Base class for every error raised by the scaffolding service.

Catching mafw.scaffold.errors.ScaffoldError is enough to intercept all expected failure modes of the generation service (invalid names, unsafe destinations, missing template resources, and so on).

class mafw.scaffold.ProjectSpec(distribution_name: str, import_name: str, description: str, python_version: str, author_name: str, author_email: str, license_id: str, destination: Path, mafw_version: str)

Bases: object

An immutable, fully validated description of a project to generate.

Variables:

• distribution_name – The installable distribution name (may contain hyphens).

• import_name – The importable package name derived from the distribution name.

• description – A short, human-readable project description.

• python_version – The minimum supported Python version (for example 3.11).

• author_name – The project author’s name, written into the package metadata.

• author_email – The project author’s e-mail, written into the package metadata.

• license_id – The SPDX license identifier for the generated project.

• destination – The resolved, absolute destination directory for the project.

• mafw_version – The MAFw version the generated project depends on.

classmethod create(*, raw_name: str | None, description: str | None = None, python_version: str | None = None, author_name: str | None = None, author_email: str | None = None, path: Path | None = None, license_id: str | None = None) → ProjectSpec

Build a validated mafw.scaffold.spec.ProjectSpec from raw inputs.

The project name is the only required value. The description, Python version, author name/e-mail and license fall back to documented defaults when omitted, and the destination defaults to <path>/<distribution_name> (or <cwd>/<distribution_name> when no path is given). The default Python version is derived from the installed MAFw metadata, not hard-coded.

Parameters:

• raw_name (str | None) – The project name as typed by the user, or None.

• description (str | None) – An optional project description.

• python_version (str | None) – An optional minimum Python version.

• author_name (str | None) – An optional author name.

• author_email (str | None) – An optional author e-mail address.

• path (Path | None) – An optional destination parent directory.

• license_id (str | None) – An optional SPDX license identifier; defaults to MIT.

Returns:

A validated project specification.

Return type:

mafw.scaffold.spec.ProjectSpec

Raises:

• mafw.scaffold.errors.MissingValueError – If no project name is supplied.

• mafw.scaffold.errors.InvalidNameError – If the name is unsafe, empty, too long or not a valid identifier.

• mafw.scaffold.errors.NameCollisionError – If the import name collides with a keyword or a standard-library module.

• mafw.scaffold.errors.InvalidEmailError – If the author e-mail is malformed.

mafw.scaffold.generate_project(spec: ProjectSpec) → Path

Generate a MAFw analysis project described by spec and return its root.

The project is rendered into a temporary staging directory and only moved to the final destination once every file has been produced successfully, so a failure never leaves a partially generated project behind.

Parameters:

spec (mafw.scaffold.spec.ProjectSpec) – The validated description of the project to generate.

Returns:

The absolute path to the generated project root.

Return type:

Path

Raises:

• mafw.scaffold.errors.DestinationNotEmptyError – If the destination already contains entries.

• mafw.scaffold.errors.MissingTemplateError – If the bundled template cannot be located.

• mafw.scaffold.errors.GenerationError – If rendering or writing fails partway through.

Modules

errors	Typed error hierarchy for the project scaffolding service.
installer	Optional installation of a generated project.
names	Distribution-to-import name derivation and validation.
renderer	Rendering of the canonical project template.
spec	Validated description of a project to generate.
steering	Deterministic generation of the example steering file.
writer	Atomic, roll-back-safe writer for generated projects.