ci: update lints Ruff & docformatter (#3130)

*Issue #, if available:*
`dofformatter` gave a false positive signal; it has lots of issues, but
as `--check` was missing, it just fixed without any real code change and
so passed green even if it failed, see for example
https://github.com/awslabs/gluonts/actions/runs/7975893111/job/21775154024?pr=3130

*Description of changes:*

validation of the actual Ruff & Docfroatter on the latest codebase


**Please tag this pr with at least one of these labels to make our
release process faster:**
this is just fixing the actual linting issue, but the better and ext
step shall be #3111

cc: @jaheba @kashif @lostella

---------

Co-authored-by: Lorenzo Stella <lorenzostella@gmail.com>

.github/workflows/lints.yml

@@ -0,0 +1,23 @@
+name: Ruff & Docformat
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        check: ["ruff", "docformatter"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+    - name: Install tools
+      run: pip install "ruff==0.2.2" "docformatter[tomli]==1.5.0"
+    - name: Ruff (Flake8)
+      if: matrix.check == 'ruff'
+      working-directory: src/
+      run: ruff check .
+    - name: Docformatter
+      if: matrix.check == 'docformatter'
+      run: docformatter --check -r src/

Justfile

@@ -34,7 +34,7 @@ release:
   python setup.py sdist
 
 black:
-  black --check --color src test examples
+  black --check --diff --color src test examples
 
 mypy:
   python setup.py type_check

examples/persist_model.py

@@ -12,7 +12,7 @@
 # permissions and limitations under the License.
 
 """
-This example shows how to serialize and deserialize a model
+This example shows how to serialize and deserialize a model.
 """
 import os
 import pprint

pyproject.toml

@@ -22,17 +22,15 @@ filterwarnings = "ignore"
 line-length = 79
 
 lint.ignore = [
-    # line-length is handled by black
-    "E501",
-
-    # TODO: remove usage of `l`
-    "E741"
+    "E501",  # line-length is handled by black
+    "E741"  # TODO: remove usage of `l`
 ]
 
 exclude = ["src/gluonts/nursery"]
 
 
 [tool.docformatter]
+black = true
 pre-summary-newline = true
 make-summary-multi-line = true
 wrap-descriptions = 79

setup.py

@@ -41,7 +41,9 @@ def get_version_cmdclass(version_file) -> dict:
 
 
 class TypeCheckCommand(distutils.cmd.Command):
-    """A custom command to run MyPy on the project sources."""
+    """
+    A custom command to run MyPy on the project sources.
+    """
 
     description = "run MyPy on Python source files"
     user_options = []

src/gluonts/dataset/artificial/recipe.py

@@ -1063,10 +1063,10 @@ def normalized_ar1(tau, x0=None, norm="minmax", sigma=1.0):
     r"""
     Returns an ar1 process with an auto correlation time of tau.
 
-    norm can be
-    None -> no normalization
-    'minmax' -> min_max_scaled
-    'standard' -> 0 mean, unit variance
+    norm can be:
+      - None -> no normalization
+      - 'minmax' -> min_max_scaled
+      - 'standard' -> 0 mean, unit variance
     """
     assert norm in [None, "minmax", "standard"]
     phi = lifted_numpy.exp(-1.0 / tau)

src/gluonts/dataset/common.py

@@ -128,10 +128,11 @@ def infer_file_type(path):
 
 
 def _rglob(path: Path, pattern="*", levels=1):
-    """Like ``path.rglob(pattern)`` except this limits the number of sub
-    directories that are traversed. ``levels = 0`` is thus the same as
-    ``path.glob(pattern)``.
+    """
+    Like ``path.rglob(pattern)`` except this limits the number of sub
+    directories that are traversed.
 
+    ``levels = 0`` is thus the same as  ``path.glob(pattern)``.
     """
     if levels is not None:
         levels -= 1

src/gluonts/dataset/jsonl.py

@@ -146,6 +146,7 @@ def __len__(self):
     def _line_starts(self):
         """
         Calculate the position for each line in the file.
+
         This information can be used with ``file.seek`` to directly jump to a
         specific line in the file.
         """

src/gluonts/dataset/multivariate_grouper.py

@@ -92,8 +92,9 @@ def _preprocess(self, dataset: Dataset) -> None:
         The preprocess function iterates over the dataset to gather data that
         is necessary for alignment.
 
-        This includes     1) Storing first/last timestamp in the dataset     2)
-        Storing the frequency of the dataset
+        This includes:
+             1. Storing first/last timestamp in the dataset
+             2. Storing the frequency of the dataset
         """
         for data in dataset:
             timestamp = data[FieldName.START]

src/gluonts/dataset/schema/translate.py

@@ -44,7 +44,9 @@ def fields(self):
 
 @dataclass
 class Get(Op):
-    """Extracts the field ``name`` from the input."""
+    """
+    Extracts the field ``name`` from the input.
+    """
 
     name: str
 
@@ -69,7 +71,9 @@ def fields(self):
 
 @dataclass
 class GetAttr(Op):
-    """Invokes ``obj.name``"""
+    """
+    Invokes ``obj.name``.
+    """
 
     obj: Op
     name: str
@@ -298,7 +302,8 @@ def parse(x: Union[str, list]) -> Op:
 
 @dataclass
 class Translator:
-    """Simple translation for GluonTS Datasets.
+    """
+    Simple translation for GluonTS Datasets.
 
     A given translator transforms an input dictionary (data-entry) into an
     output dictionary.

src/gluonts/dataset/split.py

@@ -86,8 +86,8 @@ def periods_between(
     end: pd.Period,
 ) -> int:
     """
-    Count how many periods fit between ``start`` and ``end``
-    (inclusive). The frequency is taken from ``start``.
+    Count how many periods fit between ``start`` and ``end`` (inclusive). The
+    frequency is taken from ``start``.
 
     For example:
 

src/gluonts/ev/aggregations.py

@@ -34,7 +34,8 @@ def get(self) -> np.ndarray:
 
 @dataclass
 class Sum(Aggregation):
-    """Map-reduce way of calculating the sum of a stream of values.
+    """
+    Map-reduce way of calculating the sum of a stream of values.
 
     `partial_result` represents one of two things, depending on the axis:
     Case 1 - axis 0 is aggregated (axis is None or 0):
@@ -75,7 +76,8 @@ def get(self) -> np.ndarray:
 
 @dataclass
 class Mean(Aggregation):
-    """Map-reduce way of calculating the mean of a stream of values.
+    """
+    Map-reduce way of calculating the mean of a stream of values.
 
     `partial_result` represents one of two things, depending on the axis:
     Case 1 - axis 0 is aggregated (axis is None or 0):

src/gluonts/ev/metrics.py

@@ -50,15 +50,19 @@ class MetricCollection:
     metrics: List[Metric]
 
     def update(self, data: Mapping[str, np.ndarray]) -> Self:
-        """Update metrics using a single data instance."""
+        """
+        Update metrics using a single data instance.
+        """
 
         for metric in self.metrics:
             metric.update(data)
 
         return self
 
     def update_all(self, stream: Iterator[Mapping[str, np.ndarray]]) -> Self:
-        """Update metrics using a stream of data instances."""
+        """
+        Update metrics using a stream of data instances.
+        """
 
         for element in stream:
             self.update(element)
@@ -74,12 +78,16 @@ class Metric:
     name: str
 
     def update(self, data: Mapping[str, np.ndarray]) -> Self:
-        """Update metric using a single data instance."""
+        """
+        Update metric using a single data instance.
+        """
 
         raise NotImplementedError
 
     def update_all(self, stream: Iterator[Mapping[str, np.ndarray]]) -> Self:
-        """Update metric using a stream of data instances."""
+        """
+        Update metric using a stream of data instances.
+        """
 
         for element in stream:
             self.update(element)
@@ -92,7 +100,9 @@ def get(self) -> np.ndarray:
 
 @dataclass
 class DirectMetric(Metric):
-    """A Metric which uses a single function and aggregation strategy."""
+    """
+    A Metric which uses a single function and aggregation strategy.
+    """
 
     stat: Callable
     aggregate: Aggregation
@@ -108,10 +118,11 @@ def get(self) -> np.ndarray:
 
 @dataclass
 class DerivedMetric(Metric):
-    """A Metric that is computed using other metrics.
+    """
+    A Metric that is computed using other metrics.
 
-    A derived metric updates multiple, simpler metrics independently and in
-    the end combines their results as defined in `post_process`.
+    A derived metric updates multiple, simpler metrics independently and in the
+    end combines their results as defined in `post_process`.
     """
 
     metrics: Dict[str, Metric]
@@ -237,7 +248,9 @@ def __call__(self, axis: Optional[int] = None) -> DirectMetric:
 
 @dataclass
 class MAE(BaseMetricDefinition):
-    """Mean Absolute Error"""
+    """
+    Mean Absolute Error.
+    """
 
     forecast_type: str = "0.5"
 
@@ -254,7 +267,9 @@ def __call__(self, axis: Optional[int] = None) -> DirectMetric:
 
 @dataclass
 class MSE(BaseMetricDefinition):
-    """Mean Squared Error"""
+    """
+    Mean Squared Error.
+    """
 
     forecast_type: str = "mean"
 
@@ -295,7 +310,9 @@ def __call__(self, axis: Optional[int] = None) -> DirectMetric:
 
 @dataclass
 class MAPE(BaseMetricDefinition):
-    """Mean Absolute Percentage Error"""
+    """
+    Mean Absolute Percentage Error.
+    """
 
     forecast_type: str = "0.5"
 
@@ -314,7 +331,9 @@ def __call__(self, axis: Optional[int] = None) -> DirectMetric:
 
 @dataclass
 class SMAPE(BaseMetricDefinition):
-    """Symmetric Mean Absolute Percentage Error"""
+    """
+    Symmetric Mean Absolute Percentage Error.
+    """
 
     forecast_type: str = "0.5"
 
@@ -334,7 +353,9 @@ def __call__(self, axis: Optional[int] = None) -> DirectMetric:
 
 @dataclass
 class MSIS(BaseMetricDefinition):
-    """Mean Scaled Interval Score"""
+    """
+    Mean Scaled Interval Score.
+    """
 
     alpha: float = 0.05
 
@@ -351,7 +372,9 @@ def __call__(self, axis: Optional[int] = None) -> DirectMetric:
 
 @dataclass
 class MASE(BaseMetricDefinition):
-    """Mean Absolute Scaled Error"""
+    """
+    Mean Absolute Scaled Error.
+    """
 
     forecast_type: str = "0.5"
 
@@ -382,7 +405,9 @@ def __call__(self, axis: Optional[int] = None) -> DirectMetric:
 
 @dataclass
 class ND(BaseMetricDefinition):
-    """Normalized Deviation"""
+    """
+    Normalized Deviation.
+    """
 
     forecast_type: str = "0.5"
 
@@ -410,7 +435,9 @@ def __call__(self, axis: Optional[int] = None) -> DerivedMetric:
 
 @dataclass
 class RMSE(BaseMetricDefinition):
-    """Root Mean Squared Error"""
+    """
+    Root Mean Squared Error.
+    """
 
     forecast_type: str = "mean"
 
@@ -435,7 +462,9 @@ def __call__(self, axis: Optional[int] = None) -> DerivedMetric:
 
 @dataclass
 class NRMSE(BaseMetricDefinition):
-    """RMSE, normalized by the mean absolute label"""
+    """
+    RMSE, normalized by the mean absolute label.
+    """
 
     forecast_type: str = "mean"
 
@@ -582,7 +611,9 @@ def __call__(self, axis: Optional[int] = None) -> DerivedMetric:
 
 @dataclass
 class OWA(BaseMetricDefinition):
-    """Overall Weighted Average"""
+    """
+    Overall Weighted Average.
+    """
 
     forecast_type: str = "0.5"