# Copyright 2025–2026 European Union
# Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
# SPDX-License-Identifier: EUPL-1.2
"""
Typed error hierarchy for the project scaffolding service.
Every failure of the ``mafw init`` generation service is reported through a
subclass of :class:`mafw.scaffold.errors.ScaffoldError`. The command line layer maps each error to a
non-zero exit code and a specific message, so that a scientist always receives a
clear reason for a failed generation instead of a half-written project.
.. versionadded:: 2.4
"""
[docs]
class ScaffoldError(Exception):
"""Base class for every error raised by the scaffolding service.
Catching :class:`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).
"""
[docs]
class InvalidNameError(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).
"""
[docs]
class NameCollisionError(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.
"""
[docs]
class InvalidEmailError(ScaffoldError):
"""Raised when the supplied author e-mail address is not well formed.
A malformed e-mail (for example one missing the ``@`` or the domain part)
produces invalid ``pyproject.toml`` metadata that makes the build backend fail,
so it is rejected up front with a clear message.
"""
[docs]
class DestinationNotEmptyError(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.
"""
[docs]
class MissingTemplateError(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.
"""
[docs]
class MissingValueError(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.
"""
[docs]
class GenerationError(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.
"""