Types MecaPy ↔ Python

Un manifeste déclare des types canoniques MecaPy (Force, Length, File, Vector3, …). Au runtime, le handler Python reçoit des valeurs Python : float, str, pathlib.Path, list[float], etc. Cette page documente la correspondance exacte dans les deux sens.

Le catalogue complet (description, unité, hiérarchie de sous-typage) est dans Type system ; la présente page se concentre sur le mapping vers Python.

Note

La correspondance s’applique aux trois modes runtime (python / dockerfile / image). En modes B/C tu lis / écris in/data.json et in/files/ toi-même — les types Python ci-dessous sont ce que tu désérialises depuis JSON ou ce que tu y sérialises.

Entrées — ce que le handler reçoit

Les scalaires non-File arrivent désérialisés depuis /workspace/in/data.json. Les ports File sont stagés sous /workspace/in/files/ et passés comme pathlib.Path (le nom du fichier = nom du port pour les Files simples, nom de fichier original pour les collections list[File]).

Primitifs

Type MecaPy	Type Python
Numeric	int | float
Integer	int
Float	float
Boolean	bool
String	str
Tier	str
Object	dict[str, Any]

Grandeurs physiques (SI)

Type MecaPy	Unité SI	Type Python
Length	m	float
Area	m^2	float
Volume	m^3	float
Mass	kg	float
Density	kg/m^3	float
Time	s	float
Frequency	Hz	float
Angle	rad	float
Force	N	float
Moment	N.m	float
Pressure	Pa	float
Stress	Pa	float
Temperature	K	float
TemperatureDelta	K	float
Energy	J	float
Power	W	float
Velocity	m/s	float
Acceleration	m/s^2	float

Composites

Type MecaPy	Unité SI	Type Python
Vector3	—	list[float] # [x, y, z]
Force3	N	list[float] # [Fx, Fy, Fz] in N
Moment3	N.m	list[float] # [Mx, My, Mz] in N·m
Torsor	—	dict # {"F": [Fx, Fy, Fz], "M": [Mx, My, Mz]}
Matrix	—	list[list[float]]
File	—	pathlib.Path # staged under /workspace/in/files/<port>.<ext>

Sorties — ce que le handler renvoie

Le handler renvoie un dict (sérialisé en /workspace/out/data.json). Les ports File ne sont pas dans ce dict : tu écris le fichier sous /workspace/out/files/<port>.<ext>. Les artifacts (s3 free-form) vont dans /workspace/out/artifacts/.

Primitifs

Type MecaPy	Type Python
Numeric	int | float
Integer	int
Float	float
Boolean	bool
String	str
Tier	str
Object	dict[str, Any]

Grandeurs physiques (SI)

Type MecaPy	Unité SI	Type Python
Length	m	float
Area	m^2	float
Volume	m^3	float
Mass	kg	float
Density	kg/m^3	float
Time	s	float
Frequency	Hz	float
Angle	rad	float
Force	N	float
Moment	N.m	float
Pressure	Pa	float
Stress	Pa	float
Temperature	K	float
TemperatureDelta	K	float
Energy	J	float
Power	W	float
Velocity	m/s	float
Acceleration	m/s^2	float

Composites

Type MecaPy	Unité SI	Type Python
Vector3	—	list[float]
Force3	N	list[float]
Moment3	N.m	list[float]
Torsor	—	dict # {"F": [...], "M": [...]}
Matrix	—	list[list[float]]
File	—	(not in return dict — write to /workspace/out/files/<port>.<ext>)

Cas particuliers

File et list[File]

Un port File est staged depuis S3 vers /workspace/in/files/<port>.<ext> avant que le handler soit appelé. Le handler reçoit un pathlib.Path :

def handler(report: "File") -> dict:
    text = report.read_text()       # ou report.open("rb") pour du binaire
    return {"n_lines": text.count("\n")}

Pour un port list[File], les membres sont stagés sous leur nom de fichier d’origine (pas le nom du port) dans /workspace/in/files/ :

def handler(meshes: "list[File]") -> dict:
    # meshes est une list[pathlib.Path]
    total = sum(p.stat().st_size for p in meshes)
    return {"total_bytes": total}

Object — dict hétérogène

Object est le sommet du lattice d’entrées : un dict[str, Any] quand la forme exacte n’est pas connue à la déclaration. Utile pour les fonctions génériques (core/template_render, core/xlsx_solver…) ou les variables d’un workflow map.

Tier et autres énumérés

Tier est un str côté Python — mais le manifeste contraint la valeur à un ensemble fermé (nano, micro, …, xlarge_32). L’éditeur UI rend un dropdown au lieu d’un free-text input.

Annotations Python sûres (lambda)

Dans l’image canonique mecapy-lambda:python3.12 (mode stdlib), les types MecaPy comme File ne sont pas importables — utiliser une annotation brute def handler(doc: File) lèverait NameError au load du module. L’éditeur lambda génère des annotations chaîne (PEP 484 forward refs) qui restent visuellement utiles sans être évaluées :

def handler(force: "Force", doc: "File") -> dict:
    ...

C’est valable en mode lambda ; en mode A package, tu peux annoter avec les types Python sous-jacents (float, pathlib.Path, …) sans souci.