Fix docs + retroactively add version added and version changed

parafoxia · Feb 11, 2023 · 2193590 · 2193590
1 parent fc2ebe8
commit 2193590
Showing 1 changed file with 67 additions and 3 deletions.
diff --git a/analytix/reports/interfaces.py b/analytix/reports/interfaces.py
@@ -54,6 +54,8 @@
 class DataType(Enum):
     """An enum representing data types. Can be `STRING`, `INTEGER`,
     or `FLOAT`.
+
+    *New in version 3.0.0.*
     """
 
     STRING = "STRING"
@@ -64,6 +66,8 @@ class DataType(Enum):
 class ColumnType(Enum):
     """An enum representing column types. Can be `DIMENSION` or
     `METRIC`.
+
+    *New in version 3.0.0.*
     """
 
     DIMENSION = "DIMENSION"
@@ -77,6 +81,8 @@ class ColumnHeader:
     Column headers contain various information about the columns in the
     report. You will never need to create one of these yourself.
 
+    *New in version 3.0.0.*
+
     Parameters
     ----------
     name : str
@@ -106,6 +112,8 @@ class ColumnHeader:
     def data(self) -> ResponseT:
         """The raw data for this column header in JSON format.
 
+        *New in version 4.0.0.*
+
         Returns
         -------
         dict of str-Any
@@ -126,6 +134,8 @@ class ResultTable:
     This is the resource type that gets sent from the YouTube Analytics
     API.
 
+    *New in version 4.0.0.*
+
     Parameters
     ----------
     kind : str
@@ -161,6 +171,8 @@ class ResultTable:
     def from_json(cls, data: ResponseT) -> ResultTable:
         """Create a new `ResultTable` instance from JSON data.
 
+        *New in version 4.0.0.*
+
         Parameters
         ----------
         data : JSON object
@@ -189,6 +201,8 @@ def from_json(cls, data: ResponseT) -> ResultTable:
     def data(self) -> ResponseT:
         """The raw data for this result table in JSON format.
 
+        *New in version 4.0.0.*
+
         Returns
         -------
         dict of str-Any
@@ -209,6 +223,9 @@ class AnalyticsReport:
     provides additional methods on top of one, largely designed to save
     the report data into different formats.
 
+    *Changed in version 4.0.0:* The `data` attribute no longer exists,
+    and the `resource` attribute has been added in its place.
+
     Parameters
     ----------
     data : JSON object
@@ -249,6 +266,8 @@ def shape(self) -> tuple[int, int]:
 
         This is presented in (rows, columns) format.
 
+        *New in version 2.0.0.*
+
         Returns
         -------
         tuple of two ints
@@ -273,6 +292,10 @@ def shape(self) -> tuple[int, int]:
     def columns(self) -> list[str]:
         """A list of all columns names in the report.
 
+        *New in version 2.0.0.*
+
+        *Changed in version 3.5.0:* This is now a property.
+
         Returns
         -------
         list of str
@@ -289,6 +312,11 @@ def columns(self) -> list[str]:
     def dimensions(self) -> list[str]:
         """A list of all dimensions in the report.
 
+        *New in version 3.3.0.*
+
+        *Changed in version 4.0.0:* This now returns a list of ordered
+        dimensions.
+
         Returns
         -------
         list of str
@@ -305,6 +333,11 @@ def dimensions(self) -> list[str]:
     def metrics(self) -> list[str]:
         """A list of all metrics in the report.
 
+        *New in version 3.3.0.*
+
+        *Changed in version 4.0.0:* This now returns a list of ordered
+        metrics.
+
         Returns
         -------
         list of str
@@ -321,6 +354,8 @@ def metrics(self) -> list[str]:
     def numeric(self) -> list[str]:
         """A list of all numerical columns in the report.
 
+        *New in version 4.0.0.*
+
         Returns
         -------
         list of str
@@ -337,6 +372,8 @@ def numeric(self) -> list[str]:
     def non_numeric(self) -> list[str]:
         """A list of all non-numerical columns in the report.
 
+        *New in version 4.0.0.*
+
         Returns
         -------
         list of str
@@ -357,6 +394,10 @@ def to_json(
         This saves the data as it arrived from the YouTube Analytics
         API.
 
+        *New in version 1.0.0.*
+
+        *Changed in version 4.0.0:* Added the `overwrite` parameter.
+
         Parameters
         ----------
         path : Path object or str
@@ -403,6 +444,12 @@ def to_csv(
         pass a tab character as a delimiter, the file will be saved as
         a TSV. It will be saved as a CSV in all other cases.
 
+        *New in version 1.0.0.*
+
+        *Changed in version 3.0.0:* Added TSV support.
+
+        *Changed in version 4.0.0:* Added the `overwrite` parameter.
+
         Parameters
         ----------
         path : Path object or str
@@ -444,6 +491,10 @@ def to_excel(
     ) -> None:
         """Save this report as an Excel spreadsheet.
 
+        *New in version 3.1.0.*
+
+        *Changed in version 4.0.0:* Added the `overwrite` parameter.
+
         Parameters
         ----------
         path : Path object or str
@@ -495,9 +546,14 @@ def to_excel(
     def to_pandas(self, *, skip_date_conversion: bool = False) -> pd.DataFrame:
         """Return this report as a pandas DataFrame.
 
-        If Modin is installed, it will automatically be used instead of
-        pandas. However, you will need to select and initialise your
-        preferred engine before calling this method.
+        *New in version 1.0.0.*
+
+        *Changed in version 3.0.0:* Added `skip_date_conversion`
+        parameter.
+
+        *Changed in version 3.1.0:* Added native Modin support.
+
+        *Changed in version 4.0.0:* Removed native Modin support.
 
         Parameters
         ----------
@@ -550,6 +606,8 @@ def to_pandas(self, *, skip_date_conversion: bool = False) -> pd.DataFrame:
     def to_arrow(self, *, skip_date_conversion: bool = False) -> pa.Table:
         """Return this report as a Apache Arrow table.
 
+        *New in version 3.2.0.*
+
         Parameters
         ----------
         skip_date_conversion : bool, optional
@@ -605,6 +663,8 @@ def to_arrow(self, *, skip_date_conversion: bool = False) -> pa.Table:
     def to_polars(self, *, skip_date_conversion: bool = False) -> pl.DataFrame:
         """Return the data as a Polars DataFrame.
 
+        *New in version 3.6.0.*
+
         Parameters
         ----------
         skip_date_conversion : bool, optional
@@ -671,6 +731,8 @@ def to_feather(
         To do this, the data is first converted to an Apache Arrow
         table, which is returned from the method.
 
+        *New in version 3.2.0*.
+
         Parameters
         ----------
         path : Path object or str
@@ -720,6 +782,8 @@ def to_parquet(
         To do this, the data is first converted to an Apache Arrow
         table, which is returned from the method.
 
+        *New in version 3.2.0*.
+
         Parameters
         ----------
         path : Path object or str