Nerodia Reference Manual

2. API Stability🔗

While Nerodia is still in development, it nonetheless strives to maintain stability in its public API across versions. Generally, definitions to be removed from the public API will undergo a period of deprecation (usually one version cycle). In the event Nerodia makes changes that break the public API without deprecation, those changes will be recorded as breaking changes in the changelog for that version.

Nerodia uses the module system, and its public API is primarily defined by the content available through its exported module interface. For instance, public definitions are public API, private ones are not. If import all is needed to access a part of Nerodia, that part is not public API and the code relying on it may break between revisions without warning.

However, there are aspects of Nerodia's exported module interface that are, nonetheless, not part of its public API. These exceptions are detailed below.

2.1. Module Names🔗

Nerodia is expected to be imported via import Nerodia. Submodules of Nerodia (e.g., Nerodia.Data) are not part of its public API. Thus, the definitions within may change, the entire module may be removed, or code may otherwise be reorganized without warning.

2.2. Instances🔗

Nerodia instances are only partially public API. Nerodia will try to maintain consistency in what instances are available, but the precise definitions may change between revisions without warning.

2.3. @[irreducible, expose]🔗

Due to the limitations of Lean, both in Nerodia code generation and Lean's own compiler, some definitions in the public API are marked @[irreducible, expose] instead of having private bodies. The bodies of these functions should nonetheless be considered private and may change without warning.

2.4. Nerodia.Internal🔗

All definitions within the Nerodia.Internal namespace are internal implementation details and not part of the public API. They can change between revisions without warning. Users should not rely on them.

If you need a definition from the internal namespace, please file a feature request on the Nerodia issue tracker. If feasible, we will try to design a usable public API.

2.5. Nerodia.Compiler🔗

Similar to Nerodia.Internal, definitions within Nerodia.Compiler are also not part of the public API. The compiler may become part of the public API in the future, but it currently is not.

Compiler annotations like py_module and @[py_module_fn] are part of the public API in their user interface and semantics. However, their meta definitions are part of Nerodia.Compiler and, therefore, internal. Their definitions may change without notice, as long as they maintain the same user interface.