Future API standard evolution¶
Proposals for scope extensions in a future version of the API standard will be proposed in an issue on the data-apis/dataframe-api repository, and discussed in public and decided upon.
In the future, once the API standard matures, this may be changed and follow the more formal process documented at data-apis/governance::process_document.md.
Functions, objects, keywords and specified behavior are added to this API standard only if there is a clear need, and functionality is either very minimally scoped or are already present in multiple existing dataframe libraries. Therefore it is highly unlikely that future versions of this standard will make backwards-incompatible changes.
The aim is for future versions to be 100% backwards compatible with older versions. Any exceptions must have strong rationales and be clearly documented in the updated API specification and Changelog for a release.
This API standard uses the following versioning scheme:
The version is date-based, in the form
The version shall not include a standard way to do
.devtype versions. Rationale: that’s for Python packages, not for a standard.
The version must be made available at runtime via an attribute
__dataframe_api_version__by a compliant implementation, in
'yyyy.mm'format as a string, in the namespace that implements the API standard. Rationale: dunder version strings are the standard way of doing this.
No utilities for dealing with version comparisons need to be provided; given
the format simple string comparisons with Python operators (
etc.) will be enough.
Rationale for the
yyyy.mm versioning scheme choice:
the API will be provided as part of a library, which already has a versioning
scheme (typically PEP 440 compliant and in the form
and a way to access it via
module.__version__. The API standard version is
completely independent from the package version. Given the standardization
process, it resembles a C/C++ versioning scheme (e.g.
than Python package versioning.
The frequency of releasing a new version of an API standard will likely be at regular intervals and on the order of one year, however no assumption on frequency of new versions appearing must be made.