Backwards compatibility

reader uses semantic versioning.

This means you should never be afraid to upgrade reader between minor versions if you’re using its public API.

If breaking compatibility will ever be needed, it will be done by incrementing the major version, announcing it in the Changelog, and raising deprecation warnings for at least one minor version before the new major version is published.

That said, new major versions will be released as conservatively as possible. Even during the initial development phase (versions 0.*), over 20+ minor versions spanning 1.5 years, backwards compatibility was only broken 3 times, with the approriate deprecation warnings.

What is the public API

The reader follows the PEP 8 definition of public interface.

The following are part of the public API:

  • Every interface documented in the API reference.
  • Any module, function, object, method, and attribute, defined in the reader package, that is accessible without passing through a name that starts with underscore.
  • The number and position of positional arguments.
  • The names of keyword arguments.
  • Argument types (argument types cannot become more strict).
  • Attribute types (attribute types cannot become less strict).

While argument and attribute types are part of the public API, type annotations and type aliases (even if not private), are not part of the public API.

Other exceptions are possible; they will be marked aggresively as such.


As of version 1.18, the command-line interface, web application, and plugin system/hooks are not part of the public API; they are not stable yet and might change without any notice.