API contract

This page defines what is public, how it behaves, and what callers may rely on across releases. The reference listing is in API reference.

Public surface

Two modules are supported import facades:

pyiecwind: The primary package namespace. Everything needed for normal use is importable from here: IECParameters, parse_input_file(), generate_all(), generate_from_input_file(), write_template(), format_openfast_input(), GenerationResult, GenerationError, IECWindWarning, the default filenames, and __version__.
pyiecwind.core: A compatibility facade that additionally exposes the individual condition generators (gen_ecd, gen_ews, gen_eog, gen_edc, gen_nwp, gen_ewm) and the shared constants.

Every module declares an explicit __all__. Any name not listed in a module’s ``__all__`` - in particular underscore-prefixed helpers - is internal and may change or disappear without notice. Importing internals from their defining modules is unsupported.

Versioning

The project follows semantic versioning. __version__ is single-sourced from the installed package metadata, so the runtime value, pip show, and the distribution always agree; a test guards against drift. Breaking changes to the public surface above will be accompanied by a major-version bump and a changelog entry (Changelog).

Behavioural guarantees

Validated, immutable parameters

IECParameters is a frozen dataclass that validates on construction. Every public path - the parser, the wizard, and direct construction - goes through the same validation, so an object that violates the IEC class/category/edition, geometry, or speed-ordering rules cannot exist. The conditions field is stored as a tuple; instances cannot be mutated into an invalid state afterwards.

Fail-closed generation

generate_all() and generate_from_input_file() default to strict=True: the first invalid condition raises ValueError, so a caller never silently receives partial output. Pass strict=False to collect failures into the returned GenerationResult instead (the CLI does this and chooses its exit code from the result).

Condition grammar

Condition codes follow the grammar in Theory. Speed modifiers are valid only on the rated (R) reference; a modifier on cut-in (I) or cut-out (O) is rejected rather than silently ignored.

Diagnostics

Library code does not print. Advisory, non-fatal validation issues are emitted as IECWindWarning and can be escalated to errors:

import warnings
from pyiecwind import IECWindWarning

warnings.simplefilter("error", IECWindWarning)

Hard errors are raised as ValueError (or FileNotFoundError for a missing input file). Only the command-line interface writes to stdout/stderr and selects a process exit code.

Module layout

For contributors, the internal organisation is single-responsibility:

Module	Responsibility
`models`	Constants, `IECParameters`, `IECWindWarning`, `VERSION`.
`parsing`	Read and validate the three input layouts.
`generation`	The six generators, the writer, and the batch helpers.
`template`	Render parameters back to an input file / template.
`core`	Public compatibility facade (re-exports only).
`cli`	Argument parsing, the wizard, and all user-facing output.
`__main__`	The `python -m pyiecwind` entry point.

Concurrency and thread-safety

IECParameters is immutable and safe to share across threads or processes without copying.
Generation holds no global mutable state; each call builds its own writer. Generating different conditions, or the same conditions into different output directories, is safe to run concurrently.
The one shared resource is the filesystem. Writing the same output path from multiple workers at once is not safe - give each worker a distinct output_dir. The batch helpers already write one file per condition code.