26040350358

Committed 18 May 2026 02:36PM UTC coverage: 58.354% (+1.9%) from 56.443%

Build # 26040350358

Build Type

Pull #19

github

Committed by

MuellerSeb

Commit Message

Add Python wrapper handle invalidation

Pull Request Pull Request #19: F2py wrapper support

Coverage Stats

233 of 349 new or added lines in 4 files covered. (66.76%)

1 existing line in 1 file now uncovered.

1652 of 2831 relevant lines covered (58.35%)

0.58 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

91.24

/src/nml_tools/codegen_f2py.py

"""f2py and Python wrapper code generation."""

from __future__ import annotations

import keyword
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterable, cast

from jinja2 import Environment, FileSystemLoader, StrictUndefined

from .codegen_fortran import (
    FieldSpec,
    FieldTypeInfo,
    _build_context,
    _field_type_info,
)

_TEMPLATE_ENV = Environment(
    loader=FileSystemLoader(Path(__file__).resolve().parent / "templates"),
    trim_blocks=True,
    lstrip_blocks=False,
    keep_trailing_newline=True,
    undefined=StrictUndefined,
)


@dataclass
class F2pyArgumentSpec:
    """Python wrapper argument metadata."""

    name: str
    title: str
    required: bool
    rank: int
    numpy_dtype: str | None
    dummy_value: str
    doc_type: str
    requirement: str
    has_flag: str | None = None


@dataclass
class F2pyArrayDimensionSpec:
    """Dimension arguments for a f2py-visible array dummy."""

    field_name: str
    names: list[str]


@dataclass
class F2pyNamelistSpec:
    """Metadata needed for f2py wrapper generation."""

    namelist_name: str
    brief: str
    details: str
    details_lines: list[str]
    module_name: str
    type_name: str
    helper_module: str
    kind_module: str
    kind_imports: list[str]
    f2py_module_name: str
    resolve_handle_name: str
    handle_ctype: str
    errmsg_len: int
    argument_list: list[str]
    argument_declarations: list[str]
    bridge_declarations: list[str]
    bridge_assignments: list[str]
    set_call_arguments: list[str]
    array_dimensions: list[F2pyArrayDimensionSpec]
    required_args: list[F2pyArgumentSpec]
    optional_args: list[F2pyArgumentSpec]
    all_args: list[F2pyArgumentSpec]


@dataclass
class PythonWrapperSpec:
    """Metadata needed for Python wrapper generation."""

    class_name: str
    namelist_name: str
    brief: str
    f2py_module_name: str
    extension_module: str
    required_args: list[F2pyArgumentSpec]
    optional_args: list[F2pyArgumentSpec]
    all_args: list[F2pyArgumentSpec]


@dataclass
class F2pyKindUsage:
    """Kind aliases used by f2py wrapper dummy arguments."""

    real: set[str]
    integer: set[str]


@dataclass
class F2pyCTypeMap:
    """Explicit C type mapping for f2py kinds."""

    real: dict[str, str]
    integer: dict[str, str]


def generate_f2py_wrappers(
    schemas: Iterable[dict[str, Any]],
    output: str | Path,
    *,
    helper_module: str = "nml_helper",
    kind_module: str | None = None,
    kind_map: dict[str, str] | None = None,
    kind_allowlist: Iterable[str] | None = None,
    constants: dict[str, int | float] | None = None,
    errmsg_len: int = 1024,
) -> None:
    """Generate f2py-facing Fortran wrappers for *schemas* at *output*."""
    specs = [
        build_f2py_namelist_spec(
            schema,
            helper_module=helper_module,
            kind_module=kind_module,
            kind_map=kind_map,
            kind_allowlist=kind_allowlist,
            constants=constants,
            errmsg_len=errmsg_len,
        )
        for schema in schemas
    ]
    output_path = Path(output)
    rendered = _TEMPLATE_ENV.get_template("f2py_wrappers.f90.j2").render(
        {"file_name": output_path.name, "specs": specs}
    )
    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_text(rendered, encoding="ascii")


def generate_python_wrappers(
    specs: Iterable[tuple[F2pyNamelistSpec, str]],
    output: str | Path,
    *,
    py_style: str = "numpy",
) -> None:
    """Generate Python wrapper classes for f2py namelist *specs* at *output*."""
    if py_style not in {"numpy", "doxygen"}:
        raise ValueError("python documentation style must be 'numpy' or 'doxygen'")
    output_path = Path(output)
    spec_entries = list(specs)
    extension_modules: set[str] = set()
    for _, extension_module in spec_entries:
        _validate_python_module_name(extension_module)
        extension_modules.add(extension_module)
    classes: list[PythonWrapperSpec] = []
    for spec, extension_module in spec_entries:
        classes.append(
            PythonWrapperSpec(
                class_name=_class_name(spec.namelist_name),
                namelist_name=spec.namelist_name,
                brief=spec.brief,
                f2py_module_name=spec.f2py_module_name,
                extension_module=extension_module,
                required_args=spec.required_args,
                optional_args=spec.optional_args,
                all_args=spec.all_args,
            )
        )
    rendered = _TEMPLATE_ENV.get_template("python_wrappers.py.j2").render(
        {"imports": sorted(extension_modules), "classes": classes, "py_style": py_style}
    )
    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_text(rendered, encoding="ascii")


def generate_f2cmap(
    output: str | Path,
    usage: F2pyKindUsage,
    c_types: F2pyCTypeMap,
) -> None:
    """Generate a .f2py_f2cmap file for the explicitly mapped *usage*."""
    missing_real = sorted(usage.real - set(c_types.real))
    missing_integer = sorted(usage.integer - set(c_types.integer))
    if missing_real:
        raise ValueError("missing f2py real C type mappings: " + ", ".join(missing_real))
    if missing_integer:
        raise ValueError(
            "missing f2py integer C type mappings: " + ", ".join(missing_integer)
        )

    integer_map = dict(c_types.integer)
    integer_map.setdefault("c_intptr_t", "long_long")
    real_items = ", ".join(
        f"{name}={c_types.real[name]!r}" for name in sorted(usage.real)
    )
    integer_items = ", ".join(
        f"{name}={integer_map[name]!r}" for name in sorted(usage.integer | {"c_intptr_t"})
    )
    rendered = f"dict(real=dict({real_items}), integer=dict({integer_items}))\n"
    output_path = Path(output)
    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_text(rendered, encoding="ascii")


def collect_f2py_kind_usage(
    schemas: Iterable[dict[str, Any]],
    *,
    constants: dict[str, int | float] | None = None,
) -> F2pyKindUsage:
    """Collect schema kind aliases used in f2py wrapper arguments."""
    usage = F2pyKindUsage(real=set(), integer=set())
    for schema in schemas:
        for _, type_info in _iter_field_type_infos(schema, constants):
            category = (
                type_info.element_category
                if type_info.category == "array"
                else type_info.category
            )
            if type_info.kind is None:
                continue
            if category == "real":
                usage.real.add(type_info.kind)
            elif category == "integer":
                usage.integer.add(type_info.kind)
    return usage


def merge_f2py_kind_usage(usages: Iterable[F2pyKindUsage]) -> F2pyKindUsage:
    """Merge multiple f2py kind usage objects."""
    merged = F2pyKindUsage(real=set(), integer=set())
    for usage in usages:
        merged.real.update(usage.real)
        merged.integer.update(usage.integer)
    return merged


def build_f2py_namelist_spec(
    schema: dict[str, Any],
    *,
    helper_module: str = "nml_helper",
    kind_module: str | None = None,
    kind_map: dict[str, str] | None = None,
    kind_allowlist: Iterable[str] | None = None,
    constants: dict[str, int | float] | None = None,
    errmsg_len: int = 1024,
) -> F2pyNamelistSpec:
    """Build f2py wrapper metadata for one namelist schema."""
    context = _build_context(
        schema,
        helper_module=helper_module,
        kind_module=kind_module,
        kind_map=kind_map,
        kind_allowlist=kind_allowlist,
        constants=constants,
        module_doc=None,
    )
    fields = cast("list[FieldSpec]", context["fields"])
    type_infos = {
        name: type_info for name, type_info in _iter_field_type_infos(schema, constants)
    }
    required_args: list[F2pyArgumentSpec] = []
    optional_args: list[F2pyArgumentSpec] = []
    argument_list: list[str] = []
    argument_declarations: list[str] = []
    bridge_declarations: list[str] = []
    bridge_assignments: list[str] = []
    set_call_arguments: list[str] = []
    array_dimensions: list[F2pyArrayDimensionSpec] = []
    for field in fields:
        type_info = type_infos[field.name]
        rank = len(type_info.dimensions) if type_info.category == "array" else 0
        has_flag = None if field.required else f"has_{field.name}"
        spec = F2pyArgumentSpec(
            name=field.name,
            title=_one_line(field.title),
            required=field.required,
            rank=rank,
            numpy_dtype=_numpy_dtype(type_info),
            dummy_value=_python_dummy_value(type_info),
            doc_type=_python_doc_type(type_info),
            requirement="required" if field.required else "optional",
            has_flag=has_flag,
        )
        if field.required:
            required_args.append(spec)
        else:
            optional_args.append(spec)
        field_arguments, field_declarations = _f2py_field_arguments(field, type_info)
        argument_list.extend(field_arguments)
        argument_declarations.extend(field_declarations)
        if rank > 0:
            dim_names = _array_dimension_argument_names(field.name, rank)
            array_dimensions.append(
                F2pyArrayDimensionSpec(field_name=field.name, names=dim_names)
            )
        if has_flag is not None:
            argument_list.append(has_flag)
            argument_declarations.append(
                f"logical, intent(in) :: {has_flag} !< whether {field.name} was provided"
            )
            bridge_declarations.append(_optional_bridge_declaration(field.name, type_info))
            bridge_assignments.append(_optional_bridge_assignment(field.name, type_info))
            set_call_arguments.append(f"{field.name}=maybe_{field.name}")
        else:
            set_call_arguments.append(f"{field.name}={field.name}")

    namelist_name = cast("str", context["namelist_name"])
    details = cast("str", context["details_text"])
    return F2pyNamelistSpec(
        namelist_name=namelist_name,
        brief=_one_line(cast("str", context["brief_text"])),
        details=details,
        details_lines=details.splitlines() or [details],
        module_name=cast("str", context["module_name"]),
        type_name=cast("str", context["type_name"]),
        helper_module=helper_module,
        kind_module=cast("str", context["kind_module"]),
        kind_imports=cast("list[str]", context["kind_imports"]),
        f2py_module_name=f"f2py_{namelist_name}",
        resolve_handle_name=f"{context['module_name']}_resolve_handle",
        handle_ctype="c_intptr_t",
        errmsg_len=errmsg_len,
        argument_list=argument_list,
        argument_declarations=argument_declarations,
        bridge_declarations=bridge_declarations,
        bridge_assignments=bridge_assignments,
        set_call_arguments=set_call_arguments,
        array_dimensions=array_dimensions,
        required_args=required_args,
        optional_args=optional_args,
        all_args=required_args + optional_args,
    )


def _iter_field_type_infos(
    schema: dict[str, Any],
    constants: dict[str, int | float] | None,
) -> list[tuple[str, FieldTypeInfo]]:
    properties = schema.get("properties")
    if not isinstance(properties, dict):
        raise ValueError("schema must define object 'properties'")
    entries: list[tuple[str, FieldTypeInfo]] = []
    seen: set[str] = set()
    for raw_name, prop in properties.items():
        if not isinstance(raw_name, str):
            raise ValueError("property names must be strings")
        if not isinstance(prop, dict):
            raise ValueError(f"property '{raw_name}' must be an object")
        name = raw_name.lower()
        if name in seen:
            raise ValueError(f"duplicate property '{raw_name}'")
        seen.add(name)
        entries.append((name, _field_type_info(prop, constants)))
    return entries


def _class_name(namelist_name: str) -> str:
    parts = [part for part in re.split(r"[^0-9A-Za-z]+", namelist_name) if part]
    if not parts:
        return "Namelist"
    name = "".join(part[:1].upper() + part[1:] for part in parts)
    if name[0].isdigit():
        name = f"Namelist{name}"
    if keyword.iskeyword(name):
        name = f"{name}Namelist"
    return name


def _numpy_dtype(type_info: FieldTypeInfo) -> str | None:
    category = (
        type_info.element_category
        if type_info.category == "array"
        else type_info.category
    )
    if category == "real":
        return "float"
    if category == "integer":
        return "int"
    if category == "boolean":
        return "bool"
    if category == "string":
        return "str"
    return None


def _python_dummy_value(type_info: FieldTypeInfo) -> str:
    category = (
        type_info.element_category
        if type_info.category == "array"
        else type_info.category
    )
    if category == "real":
        return "0.0"
    if category == "integer":
        return "0"
    if category == "boolean":
        return "False"
    if category == "string":
        return '""'
    return "None"


def _python_doc_type(type_info: FieldTypeInfo) -> str:
    category = (
        type_info.element_category
        if type_info.category == "array"
        else type_info.category
    )
    if category == "real":
        type_name = "float"
    elif category == "integer":
        type_name = "int"
    elif category == "boolean":
        type_name = "bool"
    elif category == "string":
        type_name = "str"
    else:
        type_name = "Any"
    if type_info.category == "array":
        return f"array_like of {type_name}"
    return type_name


def _one_line(value: str) -> str:
    return " ".join(value.splitlines()).strip()


def _array_dimension_argument_names(name: str, rank: int) -> list[str]:
    return [f"{name}_n{idx}" for idx in range(1, rank + 1)]


def _f2py_field_arguments(
    field: FieldSpec,
    type_info: FieldTypeInfo,
) -> tuple[list[str], list[str]]:
    requirement = "required" if field.required else "optional"
    if type_info.category != "array":
        return [field.name], [
            f"{type_info.arg_type_spec}, intent(in) :: {field.name} "
            f"!< {_one_line(field.title)} ({requirement})"
        ]

    dim_names = _array_dimension_argument_names(field.name, len(type_info.dimensions))
    dims = ", ".join(dim_names)
    declarations = [
        f"integer, intent(in) :: {dim_name} !< extent for {field.name}"
        for dim_name in dim_names
    ]
    declarations.append(
        f"{type_info.arg_type_spec}, dimension({dims}), intent(in) :: {field.name} "
        f"!< {_one_line(field.title)} ({requirement})"
    )
    return [*dim_names, field.name], declarations


def _optional_bridge_declaration(name: str, type_info: FieldTypeInfo) -> str:
    if type_info.category == "array":
        dims = ", ".join(":" for _ in type_info.dimensions)
        return f"{type_info.arg_type_spec}, dimension({dims}), allocatable :: maybe_{name}"
    if type_info.category == "string":
        return f"character(len=:), allocatable :: maybe_{name}"
    return f"{type_info.arg_type_spec}, allocatable :: maybe_{name}"


def _optional_bridge_assignment(name: str, type_info: FieldTypeInfo) -> str:
    has_flag = f"has_{name}"
    maybe_name = f"maybe_{name}"
    if type_info.category == "array":
        dims = ", ".join(_array_dimension_argument_names(name, len(type_info.dimensions)))
        return (
            f"if ({has_flag}) then\n"
            f"  allocate({maybe_name}({dims}))\n"
            f"  {maybe_name} = {name}\n"
            "end if"
        )
    if type_info.category == "string":
        return (
            f"if ({has_flag}) then\n"
            f"  {maybe_name} = {name}\n"
            "end if"
        )
    return (
        f"if ({has_flag}) then\n"
        f"  allocate({maybe_name})\n"
        f"  {maybe_name} = {name}\n"
        "end if"
    )


def _validate_python_module_name(module_name: str) -> None:
    if not module_name.isidentifier() or keyword.iskeyword(module_name):
        raise ValueError(
            f"f2py extension module name '{module_name}' must be a valid Python identifier"
        )

1	"""f2py and Python wrapper code generation."""
2
3	from __future__ import annotations	1✔
4
5	import keyword	1✔
6	import re	1✔
7	from dataclasses import dataclass	1✔
8	from pathlib import Path	1✔
9	from typing import Any, Iterable, cast	1✔
10
11	from jinja2 import Environment, FileSystemLoader, StrictUndefined	1✔
12
13	from .codegen_fortran import (	1✔
14	FieldSpec,
15	FieldTypeInfo,
16	_build_context,
17	_field_type_info,
18	)
19
20	_TEMPLATE_ENV = Environment(	1✔
21	loader=FileSystemLoader(Path(__file__).resolve().parent / "templates"),
22	trim_blocks=True,
23	lstrip_blocks=False,
24	keep_trailing_newline=True,
25	undefined=StrictUndefined,
26	)
27
28
29	@dataclass	1✔
30	class F2pyArgumentSpec:	1✔
31	"""Python wrapper argument metadata."""
32
33	name: str	1✔
34	title: str	1✔
35	required: bool	1✔
36	rank: int	1✔
37	numpy_dtype: str \| None	1✔
38	dummy_value: str	1✔
39	doc_type: str	1✔
40	requirement: str	1✔
41	has_flag: str \| None = None	1✔
42
43
44	@dataclass	1✔
45	class F2pyArrayDimensionSpec:	1✔
46	"""Dimension arguments for a f2py-visible array dummy."""
47
48	field_name: str	1✔
49	names: list[str]	1✔
50
51
52	@dataclass	1✔
53	class F2pyNamelistSpec:	1✔
54	"""Metadata needed for f2py wrapper generation."""
55
56	namelist_name: str	1✔
57	brief: str	1✔
58	details: str	1✔
59	details_lines: list[str]	1✔
60	module_name: str	1✔
61	type_name: str	1✔
62	helper_module: str	1✔
63	kind_module: str	1✔
64	kind_imports: list[str]	1✔
65	f2py_module_name: str	1✔
66	resolve_handle_name: str	1✔
67	handle_ctype: str	1✔
68	errmsg_len: int	1✔
69	argument_list: list[str]	1✔
70	argument_declarations: list[str]	1✔
71	bridge_declarations: list[str]	1✔
72	bridge_assignments: list[str]	1✔
73	set_call_arguments: list[str]	1✔
74	array_dimensions: list[F2pyArrayDimensionSpec]	1✔
75	required_args: list[F2pyArgumentSpec]	1✔
76	optional_args: list[F2pyArgumentSpec]	1✔
77	all_args: list[F2pyArgumentSpec]	1✔
78
79
80	@dataclass	1✔
81	class PythonWrapperSpec:	1✔
82	"""Metadata needed for Python wrapper generation."""
83
84	class_name: str	1✔
85	namelist_name: str	1✔
86	brief: str	1✔
87	f2py_module_name: str	1✔
88	extension_module: str	1✔
89	required_args: list[F2pyArgumentSpec]	1✔
90	optional_args: list[F2pyArgumentSpec]	1✔
91	all_args: list[F2pyArgumentSpec]	1✔
92
93
94	@dataclass	1✔
95	class F2pyKindUsage:	1✔
96	"""Kind aliases used by f2py wrapper dummy arguments."""
97
98	real: set[str]	1✔
99	integer: set[str]	1✔
100
101
102	@dataclass	1✔
103	class F2pyCTypeMap:	1✔
104	"""Explicit C type mapping for f2py kinds."""
105
106	real: dict[str, str]	1✔
107	integer: dict[str, str]	1✔
108
109
110	def generate_f2py_wrappers(	1✔
111	schemas: Iterable[dict[str, Any]],
112	output: str \| Path,
113	*,
114	helper_module: str = "nml_helper",
115	kind_module: str \| None = None,
116	kind_map: dict[str, str] \| None = None,
117	kind_allowlist: Iterable[str] \| None = None,
118	constants: dict[str, int \| float] \| None = None,
119	errmsg_len: int = 1024,
120	) -> None:
121	"""Generate f2py-facing Fortran wrappers for schemas at output."""
122	specs = [	1✔
123	build_f2py_namelist_spec(
124	schema,
125	helper_module=helper_module,
126	kind_module=kind_module,
127	kind_map=kind_map,
128	kind_allowlist=kind_allowlist,
129	constants=constants,
130	errmsg_len=errmsg_len,
131	)
132	for schema in schemas
133	]
134	output_path = Path(output)	1✔
135	rendered = _TEMPLATE_ENV.get_template("f2py_wrappers.f90.j2").render(	1✔
136	{"file_name": output_path.name, "specs": specs}
137	)
138	output_path.parent.mkdir(parents=True, exist_ok=True)	1✔
139	output_path.write_text(rendered, encoding="ascii")	1✔
140
141
142	def generate_python_wrappers(	1✔
143	specs: Iterable[tuple[F2pyNamelistSpec, str]],
144	output: str \| Path,
145	*,
146	py_style: str = "numpy",
147	) -> None:
148	"""Generate Python wrapper classes for f2py namelist specs at output."""
149	if py_style not in {"numpy", "doxygen"}:	1✔
150	raise ValueError("python documentation style must be 'numpy' or 'doxygen'")	1✔
151	output_path = Path(output)	1✔
152	spec_entries = list(specs)	1✔
153	extension_modules: set[str] = set()	1✔
154	for _, extension_module in spec_entries:	1✔
155	_validate_python_module_name(extension_module)	1✔
156	extension_modules.add(extension_module)	1✔
157	classes: list[PythonWrapperSpec] = []	1✔
158	for spec, extension_module in spec_entries:	1✔
159	classes.append(	1✔
160	PythonWrapperSpec(
161	class_name=_class_name(spec.namelist_name),
162	namelist_name=spec.namelist_name,
163	brief=spec.brief,
164	f2py_module_name=spec.f2py_module_name,
165	extension_module=extension_module,
166	required_args=spec.required_args,
167	optional_args=spec.optional_args,
168	all_args=spec.all_args,
169	)
170	)
171	rendered = _TEMPLATE_ENV.get_template("python_wrappers.py.j2").render(	1✔
172	{"imports": sorted(extension_modules), "classes": classes, "py_style": py_style}
173	)
174	output_path.parent.mkdir(parents=True, exist_ok=True)	1✔
175	output_path.write_text(rendered, encoding="ascii")	1✔
176
177
178	def generate_f2cmap(	1✔
179	output: str \| Path,
180	usage: F2pyKindUsage,
181	c_types: F2pyCTypeMap,
182	) -> None:
183	"""Generate a .f2py_f2cmap file for the explicitly mapped usage."""
184	missing_real = sorted(usage.real - set(c_types.real))	1✔
185	missing_integer = sorted(usage.integer - set(c_types.integer))	1✔
186	if missing_real:	1✔
187	raise ValueError("missing f2py real C type mappings: " + ", ".join(missing_real))	1✔
188	if missing_integer:	1✔
NEW 189	raise ValueError(	×
190	"missing f2py integer C type mappings: " + ", ".join(missing_integer)
191	)
192
193	integer_map = dict(c_types.integer)	1✔
194	integer_map.setdefault("c_intptr_t", "long_long")	1✔
195	real_items = ", ".join(	1✔
196	f"{name}={c_types.real[name]!r}" for name in sorted(usage.real)
197	)
198	integer_items = ", ".join(	1✔
199	f"{name}={integer_map[name]!r}" for name in sorted(usage.integer \| {"c_intptr_t"})
200	)
201	rendered = f"dict(real=dict({real_items}), integer=dict({integer_items}))\n"	1✔
202	output_path = Path(output)	1✔
203	output_path.parent.mkdir(parents=True, exist_ok=True)	1✔
204	output_path.write_text(rendered, encoding="ascii")	1✔
205
206
207	def collect_f2py_kind_usage(	1✔
208	schemas: Iterable[dict[str, Any]],
209	*,
210	constants: dict[str, int \| float] \| None = None,
211	) -> F2pyKindUsage:
212	"""Collect schema kind aliases used in f2py wrapper arguments."""
213	usage = F2pyKindUsage(real=set(), integer=set())	1✔
214	for schema in schemas:	1✔
215	for _, type_info in _iter_field_type_infos(schema, constants):	1✔
216	category = (	1✔
217	type_info.element_category
218	if type_info.category == "array"
219	else type_info.category
220	)
221	if type_info.kind is None:	1✔
222	continue	1✔
223	if category == "real":	1✔
224	usage.real.add(type_info.kind)	1✔
225	elif category == "integer":	1✔
226	usage.integer.add(type_info.kind)	1✔
227	return usage	1✔
228
229
230	def merge_f2py_kind_usage(usages: Iterable[F2pyKindUsage]) -> F2pyKindUsage:	1✔
231	"""Merge multiple f2py kind usage objects."""
NEW 232	merged = F2pyKindUsage(real=set(), integer=set())	×
NEW 233	for usage in usages:	×
NEW 234	merged.real.update(usage.real)	×
NEW 235	merged.integer.update(usage.integer)	×
NEW 236	return merged	×
237
238
239	def build_f2py_namelist_spec(	1✔
240	schema: dict[str, Any],
241	*,
242	helper_module: str = "nml_helper",
243	kind_module: str \| None = None,
244	kind_map: dict[str, str] \| None = None,
245	kind_allowlist: Iterable[str] \| None = None,
246	constants: dict[str, int \| float] \| None = None,
247	errmsg_len: int = 1024,
248	) -> F2pyNamelistSpec:
249	"""Build f2py wrapper metadata for one namelist schema."""
250	context = _build_context(	1✔
251	schema,
252	helper_module=helper_module,
253	kind_module=kind_module,
254	kind_map=kind_map,
255	kind_allowlist=kind_allowlist,
256	constants=constants,
257	module_doc=None,
258	)
259	fields = cast("list[FieldSpec]", context["fields"])	1✔
260	type_infos = {	1✔
261	name: type_info for name, type_info in _iter_field_type_infos(schema, constants)
262	}
263	required_args: list[F2pyArgumentSpec] = []	1✔
264	optional_args: list[F2pyArgumentSpec] = []	1✔
265	argument_list: list[str] = []	1✔
266	argument_declarations: list[str] = []	1✔
267	bridge_declarations: list[str] = []	1✔
268	bridge_assignments: list[str] = []	1✔
269	set_call_arguments: list[str] = []	1✔
270	array_dimensions: list[F2pyArrayDimensionSpec] = []	1✔
271	for field in fields:	1✔
272	type_info = type_infos[field.name]	1✔
273	rank = len(type_info.dimensions) if type_info.category == "array" else 0	1✔
274	has_flag = None if field.required else f"has_{field.name}"	1✔
275	spec = F2pyArgumentSpec(	1✔
276	name=field.name,
277	title=_one_line(field.title),
278	required=field.required,
279	rank=rank,
280	numpy_dtype=_numpy_dtype(type_info),
281	dummy_value=_python_dummy_value(type_info),
282	doc_type=_python_doc_type(type_info),
283	requirement="required" if field.required else "optional",
284	has_flag=has_flag,
285	)
286	if field.required:	1✔
287	required_args.append(spec)	1✔
288	else:
289	optional_args.append(spec)	1✔
290	field_arguments, field_declarations = _f2py_field_arguments(field, type_info)	1✔
291	argument_list.extend(field_arguments)	1✔
292	argument_declarations.extend(field_declarations)	1✔
293	if rank > 0:	1✔
294	dim_names = _array_dimension_argument_names(field.name, rank)	1✔
295	array_dimensions.append(	1✔
296	F2pyArrayDimensionSpec(field_name=field.name, names=dim_names)
297	)
298	if has_flag is not None:	1✔
299	argument_list.append(has_flag)	1✔
300	argument_declarations.append(	1✔
301	f"logical, intent(in) :: {has_flag} !< whether {field.name} was provided"
302	)
303	bridge_declarations.append(_optional_bridge_declaration(field.name, type_info))	1✔
304	bridge_assignments.append(_optional_bridge_assignment(field.name, type_info))	1✔
305	set_call_arguments.append(f"{field.name}=maybe_{field.name}")	1✔
306	else:
307	set_call_arguments.append(f"{field.name}={field.name}")	1✔
308
309	namelist_name = cast("str", context["namelist_name"])	1✔
310	details = cast("str", context["details_text"])	1✔
311	return F2pyNamelistSpec(	1✔
312	namelist_name=namelist_name,
313	brief=_one_line(cast("str", context["brief_text"])),
314	details=details,
315	details_lines=details.splitlines() or [details],
316	module_name=cast("str", context["module_name"]),
317	type_name=cast("str", context["type_name"]),
318	helper_module=helper_module,
319	kind_module=cast("str", context["kind_module"]),
320	kind_imports=cast("list[str]", context["kind_imports"]),
321	f2py_module_name=f"f2py_{namelist_name}",
322	resolve_handle_name=f"{context['module_name']}_resolve_handle",
323	handle_ctype="c_intptr_t",
324	errmsg_len=errmsg_len,
325	argument_list=argument_list,
326	argument_declarations=argument_declarations,
327	bridge_declarations=bridge_declarations,
328	bridge_assignments=bridge_assignments,
329	set_call_arguments=set_call_arguments,
330	array_dimensions=array_dimensions,
331	required_args=required_args,
332	optional_args=optional_args,
333	all_args=required_args + optional_args,
334	)
335
336
337	def _iter_field_type_infos(	1✔
338	schema: dict[str, Any],
339	constants: dict[str, int \| float] \| None,
340	) -> list[tuple[str, FieldTypeInfo]]:
341	properties = schema.get("properties")	1✔
342	if not isinstance(properties, dict):	1✔
NEW 343	raise ValueError("schema must define object 'properties'")	×
344	entries: list[tuple[str, FieldTypeInfo]] = []	1✔
345	seen: set[str] = set()	1✔
346	for raw_name, prop in properties.items():	1✔
347	if not isinstance(raw_name, str):	1✔
NEW 348	raise ValueError("property names must be strings")	×
349	if not isinstance(prop, dict):	1✔
NEW 350	raise ValueError(f"property '{raw_name}' must be an object")	×
351	name = raw_name.lower()	1✔
352	if name in seen:	1✔
NEW 353	raise ValueError(f"duplicate property '{raw_name}'")	×
354	seen.add(name)	1✔
355	entries.append((name, _field_type_info(prop, constants)))	1✔
356	return entries	1✔
357
358
359	def _class_name(namelist_name: str) -> str:	1✔
360	parts = [part for part in re.split(r"[^0-9A-Za-z]+", namelist_name) if part]	1✔
361	if not parts:	1✔
NEW 362	return "Namelist"	×
363	name = "".join(part[:1].upper() + part[1:] for part in parts)	1✔
364	if name[0].isdigit():	1✔
NEW 365	name = f"Namelist{name}"	×
366	if keyword.iskeyword(name):	1✔
NEW 367	name = f"{name}Namelist"	×
368	return name	1✔
369
370
371	def _numpy_dtype(type_info: FieldTypeInfo) -> str \| None:	1✔
372	category = (	1✔
373	type_info.element_category
374	if type_info.category == "array"
375	else type_info.category
376	)
377	if category == "real":	1✔
378	return "float"	1✔
379	if category == "integer":	1✔
380	return "int"	1✔
381	if category == "boolean":	1✔
NEW 382	return "bool"	×
383	if category == "string":	1✔
384	return "str"	1✔
NEW 385	return None	×
386
387
388	def _python_dummy_value(type_info: FieldTypeInfo) -> str:	1✔
389	category = (	1✔
390	type_info.element_category
391	if type_info.category == "array"
392	else type_info.category
393	)
394	if category == "real":	1✔
395	return "0.0"	1✔
396	if category == "integer":	1✔
397	return "0"	1✔
398	if category == "boolean":	1✔
NEW 399	return "False"	×
400	if category == "string":	1✔
401	return '""'	1✔
NEW 402	return "None"	×
403
404
405	def _python_doc_type(type_info: FieldTypeInfo) -> str:	1✔
406	category = (	1✔
407	type_info.element_category
408	if type_info.category == "array"
409	else type_info.category
410	)
411	if category == "real":	1✔
412	type_name = "float"	1✔
413	elif category == "integer":	1✔
414	type_name = "int"	1✔
415	elif category == "boolean":	1✔
NEW 416	type_name = "bool"	×
417	elif category == "string":	1✔
418	type_name = "str"	1✔
419	else:
NEW 420	type_name = "Any"	×
421	if type_info.category == "array":	1✔
422	return f"array_like of {type_name}"	1✔
423	return type_name	1✔
424
425
426	def _one_line(value: str) -> str:	1✔
427	return " ".join(value.splitlines()).strip()	1✔
428
429
430	def _array_dimension_argument_names(name: str, rank: int) -> list[str]:	1✔
431	return [f"{name}_n{idx}" for idx in range(1, rank + 1)]	1✔
432
433
434	def _f2py_field_arguments(	1✔
435	field: FieldSpec,
436	type_info: FieldTypeInfo,
437	) -> tuple[list[str], list[str]]:
438	requirement = "required" if field.required else "optional"	1✔
439	if type_info.category != "array":	1✔
440	return [field.name], [	1✔
441	f"{type_info.arg_type_spec}, intent(in) :: {field.name} "
442	f"!< {_one_line(field.title)} ({requirement})"
443	]
444
445	dim_names = _array_dimension_argument_names(field.name, len(type_info.dimensions))	1✔
446	dims = ", ".join(dim_names)	1✔
447	declarations = [	1✔
448	f"integer, intent(in) :: {dim_name} !< extent for {field.name}"
449	for dim_name in dim_names
450	]
451	declarations.append(	1✔
452	f"{type_info.arg_type_spec}, dimension({dims}), intent(in) :: {field.name} "
453	f"!< {_one_line(field.title)} ({requirement})"
454	)
455	return [*dim_names, field.name], declarations	1✔
456
457
458	def _optional_bridge_declaration(name: str, type_info: FieldTypeInfo) -> str:	1✔
459	if type_info.category == "array":	1✔
460	dims = ", ".join(":" for _ in type_info.dimensions)	1✔
461	return f"{type_info.arg_type_spec}, dimension({dims}), allocatable :: maybe_{name}"	1✔
462	if type_info.category == "string":	1✔
NEW 463	return f"character(len=:), allocatable :: maybe_{name}"	×
464	return f"{type_info.arg_type_spec}, allocatable :: maybe_{name}"	1✔
465
466
467	def _optional_bridge_assignment(name: str, type_info: FieldTypeInfo) -> str:	1✔
468	has_flag = f"has_{name}"	1✔
469	maybe_name = f"maybe_{name}"	1✔
470	if type_info.category == "array":	1✔
471	dims = ", ".join(_array_dimension_argument_names(name, len(type_info.dimensions)))	1✔
472	return (	1✔
473	f"if ({has_flag}) then\n"
474	f" allocate({maybe_name}({dims}))\n"
475	f" {maybe_name} = {name}\n"
476	"end if"
477	)
478	if type_info.category == "string":	1✔
NEW 479	return (	×
480	f"if ({has_flag}) then\n"
481	f" {maybe_name} = {name}\n"
482	"end if"
483	)
484	return (	1✔
485	f"if ({has_flag}) then\n"
486	f" allocate({maybe_name})\n"
487	f" {maybe_name} = {name}\n"
488	"end if"
489	)
490
491
492	def _validate_python_module_name(module_name: str) -> None:	1✔
493	if not module_name.isidentifier() or keyword.iskeyword(module_name):	1✔
NEW 494	raise ValueError(	×
495	f"f2py extension module name '{module_name}' must be a valid Python identifier"
496	)

MuellerSeb / nml-tools / 26040350358

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous