What counts as public API#

The public application programming interface (API) of mathspec is the set of names you import from it, such as to_spec and to_latex. A function joins it when both of these are true:

1. The function returns the same result for the same specification of an optimisation model (a spec). to_spec('spec.yaml') returns the same Spec today, tomorrow, and on a machine with no data and no solver. A function whose result depends on data, a solver, the network or the clock cannot join. The rule exists because software that reads a spec without data (a checker) and software that builds the model (an engine) must get one result.
2. Every rule that the function applies is on a page of the reference. So you could rewrite the function in another programming language from the pages alone, and get the same result. The rule exists because software that reads a spec (a tool) may be written in another programming language. Such a tool has only the pages to go by.

The test file tests/test_public_surface.py lists the names that mathspec exports and the list of public modules. So a name joins or leaves the top level of the public API only with a change to that test.

A key or a function#

Where a feature can be a key in the file, it is a key and not a function. A function argument, such as an option on to_spec, could set the feature instead. A key is better here, because a key shows up in a git diff. The typesetter prints the key, and an engine written in another programming language reads it. An option on a function changes what the file means without a trace in the file.

The size of the public API#

A small public API is better here than a public module for every helper, because a small API follows from the second rule. Any release can change a private module, such as the one that computes the dimensions of an expression. A tool that needs the dimensions of an expression instead reads the dims of a node in the compiled spec (a Program).

You can now judge whether a function belongs in the public API, and whether a feature belongs in the file as a key.