mafw.scaffold.names

Distribution-to-import name derivation and validation.

A MAFw project is identified by two related names:

• the distribution name written in pyproject.toml (for example my-analysis), which may contain hyphens;

• the import name, the importable Python package (for example my_analysis), obtained by replacing every hyphen with an underscore.

This module provides the single, total derivation function to_import_name() and the validation routine validate(), which together guarantee that a generated project always has a safe, importable package name and that a malicious or malformed name can never reach the filesystem.

Added in version 2.4.

Module Attributes

MAX_NAME_LENGTH

Maximum accepted length of a project name.

Functions

to_import_name(distribution_name)	Derive the import name from a distribution name.
validate(distribution_name, import_name)	Validate a distribution name and its derived import name.
validate_email(email)	Validate that email is a well-formed author e-mail address.

mafw.scaffold.names.to_import_name(distribution_name: str) → str

Derive the import name from a distribution name.

The mapping replaces every hyphen with a single underscore and leaves every other character unchanged. It is total (it never raises) and idempotent (applying it twice gives the same result as applying it once), because the output contains no hyphens for a second pass to rewrite.

Parameters:

distribution_name (str) – The distribution name, possibly containing hyphens.

Returns:

The derived import name.

Return type:

str

mafw.scaffold.names.validate(distribution_name: str, import_name: str) → None

Validate a distribution name and its derived import name.

The checks are applied in a fixed order and each failure raises a specific error with an actionable message:

1. Path safety — reject any name containing a path separator or a . / .. component. This is checked first so a dangerous name never reaches the filesystem.

2. Non-empty and length — reject an empty name or one longer than MAX_NAME_LENGTH characters.

3. Identifier grammar — reject a derived import name that is not a valid Python package identifier.

4. Keyword collision — reject an import name that is a hard or soft Python keyword.

5. Standard-library collision — reject an import name that shadows a top-level standard-library module.

Parameters:

• distribution_name (str) – The distribution name supplied by the user.

• import_name (str) – The import name derived by to_import_name().

Raises:

• 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.names.validate_email(email: str) → None

Validate that email is a well-formed author e-mail address.

The check is intentionally pragmatic rather than a full RFC 5322 parser: it rejects the common malformed inputs (no @, no domain, no top-level domain, whitespace) that produce invalid package metadata and make the build backend fail, while accepting ordinary addresses.

Parameters:

email (str) – The e-mail address to validate.

Raises:

mafw.scaffold.errors.InvalidEmailError – If the address is not well formed.

mafw.scaffold.names.MAX_NAME_LENGTH = 214

Maximum accepted length of a project name.

This mirrors the de-facto package-name length limit used by the Python packaging ecosystem, keeping generated distribution names portable.