make api_version required (#295)

Author: MarcoGorelli

spec/API_specification/dataframe_api/typing.py

@@ -154,13 +154,13 @@ def date(self, year: int, month: int, day: int) -> Scalar:
 
 class SupportsDataFrameAPI(Protocol):
     def __dataframe_consortium_standard__(
-        self, *, api_version: str | None = None
+        self, *, api_version: str
     ) -> DataFrame:
         ...
 
 class SupportsColumnAPI(Protocol):
     def __column_consortium_standard__(
-        self, *, api_version: str | None = None
+        self, *, api_version: str
     ) -> Column:
         ...
 

spec/API_specification/examples/02_plotting.py

@@ -14,9 +14,9 @@ def group_by_and_plot(
     y_any: SupportsColumnAPI,
     color_any: SupportsColumnAPI,
 ) -> None:
-    x = x_any.__column_consortium_standard__()
-    y = y_any.__column_consortium_standard__()
-    color = color_any.__column_consortium_standard__()
+    x = x_any.__column_consortium_standard__(api_version='2023-10.beta')
+    y = y_any.__column_consortium_standard__(api_version='2023-10.beta')
+    color = color_any.__column_consortium_standard__(api_version='2023-10.beta')
 
     namespace = x.__column_namespace__()
 

spec/API_specification/examples/tpch/q5.py

@@ -31,12 +31,12 @@ def query(
     nation_raw: SupportsDataFrameAPI,
     region_raw: SupportsDataFrameAPI,
 ) -> SupportsDataFrameAPI:
-    customer = customer_raw.__dataframe_consortium_standard__()
-    orders = orders_raw.__dataframe_consortium_standard__()
-    lineitem = lineitem_raw.__dataframe_consortium_standard__()
-    supplier = supplier_raw.__dataframe_consortium_standard__()
-    nation = nation_raw.__dataframe_consortium_standard__()
-    region = region_raw.__dataframe_consortium_standard__()
+    customer = customer_raw.__dataframe_consortium_standard__(api_version='2023-10.beta')
+    orders = orders_raw.__dataframe_consortium_standard__(api_version='2023-10.beta')
+    lineitem = lineitem_raw.__dataframe_consortium_standard__(api_version='2023-10.beta')
+    supplier = supplier_raw.__dataframe_consortium_standard__(api_version='2023-10.beta')
+    nation = nation_raw.__dataframe_consortium_standard__(api_version='2023-10.beta')
+    region = region_raw.__dataframe_consortium_standard__(api_version='2023-10.beta')
 
     namespace = customer.__dataframe_namespace__()
 

spec/purpose_and_scope.md

@@ -260,20 +260,19 @@ For example, pandas has ``pandas.DataFrame.__dataframe_consortium_standard__`` a
 The signatures should be (note: docstring is optional):
 ```python
 def __dataframe_consortium_standard__(
-    self, *, api_version: str | None = None
+    self, *, api_version: str
 ) -> Any:
 
 def __column_consortium_standard__(
-    self, *, api_version: str | None = None
+    self, *, api_version: str
 ) -> Any:
 ```
 `api_version` is
 a string representing the version of the dataframe API specification
 to be returned, in ``'YYYY.MM'`` form, for example, ``'2023.04'``.
-If it is ``None``, it should return the namespace corresponding to
-latest version of the dataframe API specification.  If the given
-version is invalid or not implemented for the given module, an
-error should be raised. Default: ``None``.
+If the given version is invalid or not implemented for the given module,
+an error should be raised. It is suggested to use the earliest API
+version required for maximum compatibility.
 
 For some examples, please check https://github.com/data-apis/dataframe-api/tree/main/spec/examples.