mafw.scaffold.spec

Validated description of a project to generate.

mafw.scaffold.spec.ProjectSpec is the single immutable value object that carries every input needed to render a MAFw analysis project. Building it through ProjectSpec.create() is the one place where raw, user-supplied values are normalized, validated and defaulted, so that the rest of the generation service only ever sees known-good data and never has to prompt or re-validate.

Added in version 2.4.

Module Attributes

DEFAULT_DESCRIPTION

Default one-line description used when the user does not supply one.

DEFAULT_AUTHOR_NAME

Default author name used when the user does not supply one.

DEFAULT_AUTHOR_EMAIL

Default author e-mail used when the user does not supply one.

DEFAULT_LICENSE

Default SPDX license identifier for a generated project.

Functions

default_python_version()

Return the default minimum Python version for a generated project.

Classes

ProjectSpec(distribution_name, import_name, ...)

An immutable, fully validated description of a project to generate.
class mafw.scaffold.spec.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)[source]

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[source]

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.spec.default_python_version() → str[source]

Return the default minimum Python version for a generated project.

The value is taken from the installed MAFw distribution’s Requires-Python metadata (for example >=3.11 yields 3.11). That metadata is generated from MAFw’s own pyproject.toml, which the maintainers keep aligned with the single source of truth tool.mafw.supported-python. Reading it here means the scaffold never hard-codes a Python floor and needs no copy of MAFw’s source pyproject.toml at runtime (it also works from a uvx install).

If the metadata cannot be read or parsed, _FALLBACK_PYTHON_VERSION is returned.

Returns:

The default minimum Python version as a major.minor string.

Return type:

str

mafw.scaffold.spec.DEFAULT_AUTHOR_EMAIL = 'anonymous@example.org'

Default author e-mail used when the user does not supply one.

mafw.scaffold.spec.DEFAULT_AUTHOR_NAME = 'Anonymous Scientist'

Default author name used when the user does not supply one.

mafw.scaffold.spec.DEFAULT_DESCRIPTION = 'Scientific analysis with MAFw'

Default one-line description used when the user does not supply one.

mafw.scaffold.spec.DEFAULT_LICENSE = 'MIT'

Default SPDX license identifier for a generated project.

MIT is a permissive, widely understood license in the scientific community; the generated README explains how the author can switch to a different one.

mafw.scaffold.spec._FALLBACK_PYTHON_VERSION = '3.11'

Fallback minimum Python version used only if MAFw metadata cannot be read.

The authoritative value is derived at runtime from the installed MAFw distribution’s own Requires-Python metadata (see default_python_version()), which the maintainers keep in sync with tool.mafw.supported-python. This constant is a last resort for the unlikely case where that metadata is unavailable.