API Stability

at-py is still a 0.x package. The current API is intended to be practical and well tested, but not frozen.

Public Surface

The top-level at_py package is the curated application API. It exports ATClient, common parsers and formatters, MAT helpers, runtime constants, and selected result dataclasses.

The at_py.readwrite package exposes the full read/write surface, including lower-level helpers and additional result types. Import from this namespace when you need a symbol that is not intentionally re-exported at the package root.

Current Stabilization Decisions

These choices are part of the current 0.x contract and should be changed only with a changelog entry and focused tests:

  • at_py remains the application namespace. It should include the runner client, common parse/read/format helpers, MAT helpers, runtime constants, and the result dataclasses needed by those helpers.

  • at_py.readwrite remains the full implementation namespace. Lower-level helpers such as load_mat_normalized_path and parse_readvector_lines stay there unless a concrete application use case justifies promoting them.

  • Runtime parse and format APIs stay in-memory-first. Path-based convenience wrappers are limited to explicit helpers such as load_mat_normalized_path; they are not added to every parser/formatter by default.

  • Model dispatch follows Matlab read_env.m behavior. Writer-only aliases such as simplePE are not accepted by parse_read_env or format_parsed_env unless read-side behavior is implemented and tested.

  • MAT v7.3 support stays demand-driven. Unsupported high-level MATLAB types should continue to fail loudly until an Acoustics Toolbox workflow needs them.

1.0 Exit Criteria

Before a 1.0 release, maintainers should verify:

  • the top-level at_py.__all__ set is intentionally curated;

  • result dataclasses used by top-level helpers are documented as public result contracts;

  • runner-backed validation covers the primary application workflows;

  • the release workflow can publish through PyPI Trusted Publishing;

  • any breaking changes are either completed or explicitly deferred.

Current Compatibility Promise

Within the 0.x line, prefer additive changes and clear deprecations where possible. Breaking changes should be documented in the changelog and released as minor bumps while major_version_zero = true remains configured for Commitizen.