API stability¶
From its first release, cryptography will have a strong API stability policy.
What does this policy cover?¶
This policy includes any API or behavior that is documented in this documentation.
What does “stable” mean?¶
- Public APIs will not be removed or renamed without providing a compatibility alias.
- The behavior of existing APIs will not change.
What doesn’t this policy cover?¶
- We may add new features, things like the result of dir(obj)) or the contents of obj.__dict__ may change.
- Objects are not guaranteed to be pickleable, and pickled objects from one version of cryptography may not be loadable in future versions.
- Development versions of cryptography. Before a feature is in a release, it is not covered by this policy and may change.
Security¶
One exception to our API stability policy is for security. We will violate this policy as necessary in order to resolve a security issue or harden cryptography against a possible attack.
Deprecation¶
From time to time we will want to change the behavior of an API or remove it entirely. In that case, here’s how the process will work:
- In cryptography X.Y the feature exists.
- In cryptography X.Y+1 using that feature will emit a PendingDeprecationWarning.
- In cryptography X.Y+2 using that feature will emit a DeprecationWarning.
- In cryptography X.Y+3 the feature will be removed or changed.
In short, code that runs without warnings will always continue to work for a period of two releases.