Merge pull request #22 from wvenialbo/support/flake8-issues

Support/flake8 issues

.github/workflows/python-docsig.py

@@ -0,0 +1,25 @@
+name: DocSig
+
+on: [workflow_dispatch]
+
+jobs:
+  docsig:
+    name: Document method signature checking with DocSig
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade docsig
+        pip install -r requirements.txt
+    - name: Analysing the code with docsig
+      run: |
+        docsig "./src/GOES_DL"

.github/workflows/python-flake.yml

@@ -4,7 +4,7 @@ on: [workflow_dispatch]
 
 jobs:
   flake:
-    name: Code format checking with Flake8
+    name: Linting and style checking with Flake8
     runs-on: ubuntu-latest
     strategy:
       matrix:

.github/workflows/python-lint.yml

@@ -196,8 +196,71 @@ jobs:
       run: |
         autopep8 "./src/GOES_DL" --recursive --jobs 0 --diff --aggressive
 
+  pydocstyle:
+    name: Documentation linting with PyDocStyle
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade pydocstyle
+        pip install -r requirements.txt
+    - name: Analysing the code with pydocstyle
+      run: |
+        pydocstyle "./src/GOES_DL"
+
+  pydoclint:
+    name: Documentation linting with PyDocLint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade pydoclint
+        pip install -r requirements.txt
+    - name: Analysing the code with pydoclint
+      run: |
+        pydoclint "./src/GOES_DL"
+
+  docsig:
+    name: Document method signature checking with DocSig
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade docsig
+        pip install -r requirements.txt
+    - name: Analysing the code with docsig
+      run: |
+        docsig "./src/GOES_DL"
+
   flake:
-    name: Code format checking with Flake8
+    name: Linting and style checking with Flake8
     runs-on: ubuntu-latest
     strategy:
       matrix:

.github/workflows/python-pydoclint.py

@@ -0,0 +1,25 @@
+name: PyDocLint
+
+on: [workflow_dispatch]
+
+jobs:
+  pydoclint:
+    name: Documentation linting with PyDocLint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade pydoclint
+        pip install -r requirements.txt
+    - name: Analysing the code with pydoclint
+      run: |
+        pydoclint "./src/GOES_DL"

.github/workflows/python-pydocstyle.py

@@ -0,0 +1,25 @@
+name: PyDocStyle
+
+on: [workflow_dispatch]
+
+jobs:
+  pydocstyle:
+    name: Documentation linting with PyDocStyle
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade pydocstyle
+        pip install -r requirements.txt
+    - name: Analysing the code with pydocstyle
+      run: |
+        pydocstyle "./src/GOES_DL"

scripts/toolchain.ps1

@@ -149,7 +149,7 @@ Write-Host ""
 Write-Host "--- Running pydoctest {<file>|<dir>} [--parser {google|numpy|sphinx}]"
 if ($isFolder) {
     Push-Location -Path $project
-    pydoctest --parser numpy
+    #pydoctest --parser numpy
     Pop-Location
 }
 else {

src/GOES_DL/__init__.py

@@ -1,6 +1,4 @@
-"""
-Provide functionalities for downloading GOES and GridSat datasets.
-"""
+"""Provide functionalities for downloading GOES and GridSat datasets."""
 
 __package_id__ = "GOES-DL"
 __package_name__ = f"GOES Dataset Downloader - {__package_id__}"

src/GOES_DL/dataset/base/locator_gg.py

@@ -7,9 +7,9 @@
 """
 
 from abc import abstractmethod
+from collections.abc import Iterable
 from datetime import datetime, timezone
 from re import Match, findall, fullmatch
-from typing import Iterable
 
 from ..locator import ProductLocator
 
@@ -215,11 +215,14 @@ def timestamp_to_datetime(self, timestamp: str) -> datetime:
 
         Notes
         -----
-        The timestamp string extracted from the product's filename
-        are (or assumed to be) always in UTC timezone. Consumer of
-        product utilities should be aware of this assumption. The
-        user could convert the `datetime` object to the desired
-        timezone if needed.
+        The timestamp string extracted from the product's filename are
+        (or assumed to be) always in UTC timezone. Consumer of product
+        utilities should be aware of this assumption. The user could
+        convert the `datetime` object to the desired timezone if needed.
+
+        The framework raises `ValueError` if the timestamp does not
+        match the expected format or if the format specification is
+        ill-formed.
 
         Parameters
         ----------
@@ -230,13 +233,6 @@ def timestamp_to_datetime(self, timestamp: str) -> datetime:
         -------
         datetime
             The converted `datetime` object in UTC timezone.
-
-        Raises
-        ------
-        ValueError
-            The framework raises an exception if the timestamp does not
-            match the expected format or if the format specification is
-            ill-formed.
         """
         # File dates are always in UTC.
         file_timestamp: str = f"{timestamp}+0000"
@@ -278,40 +274,54 @@ def _validate_set(
 
     @classmethod
     def _validate_channels(
-        cls, channel: str | Iterable[str], available_channels: Iterable[str]
+        cls: type["ProductLocatorGG"],
+        channel: str | Iterable[str],
+        available_channels: Iterable[str],
     ) -> None:
         cls._validate_set("channel", channel, available_channels)
 
     @classmethod
     def _validate_datasource(
-        cls, datasource: str, available_datasources: Iterable[str]
+        cls: type["ProductLocatorGG"],
+        datasource: str,
+        available_datasources: Iterable[str],
     ) -> None:
         cls._validate_entity("datasource", datasource, available_datasources)
 
     @classmethod
     def _validate_instrument(
-        cls, instrument: str, available_instruments: Iterable[str]
+        cls: type["ProductLocatorGG"],
+        instrument: str,
+        available_instruments: Iterable[str],
     ) -> None:
         cls._validate_entity("instrument", instrument, available_instruments)
 
     @classmethod
-    def _validate_level(cls, level: str, available_levels: set[str]) -> None:
+    def _validate_level(
+        cls: type["ProductLocatorGG"], level: str, available_levels: set[str]
+    ) -> None:
         cls._validate_entity("level", level, available_levels)
 
     @classmethod
     def _validate_origin(
-        cls, origin: str, available_origins: Iterable[str]
+        cls: type["ProductLocatorGG"],
+        origin: str,
+        available_origins: Iterable[str],
     ) -> None:
         cls._validate_entity("origin", origin, available_origins)
 
     @classmethod
     def _validate_product(
-        cls, name: str, available_products: Iterable[str]
+        cls: type["ProductLocatorGG"],
+        name: str,
+        available_products: Iterable[str],
     ) -> None:
         cls._validate_entity("product", name, available_products)
 
     @classmethod
     def _validate_scene(
-        cls, scene: str, available_scenes: Iterable[str]
+        cls: type["ProductLocatorGG"],
+        scene: str,
+        available_scenes: Iterable[str],
     ) -> None:
         cls._validate_entity("scene", scene, available_scenes)

src/GOES_DL/dataset/goes/locator.py

@@ -56,32 +56,6 @@ class GOESProductLocator(ProductLocatorGG):
     Subclasses are responsible for initialising the attributes with the
     appropriate values for the dataset and product details.
 
-    Attributes
-    ----------
-    name : str
-        The name of the GOES-R Series imagery dataset product. Due to
-        how the dataset directories are organised, only a single product
-        can be provided.
-    level : str
-        The level of the GOES-R Series imagery dataset product, e.g.
-        "L1b" or "L2".
-    scene : str
-        The scene of the GOES-R Series imagery dataset product, e.g.
-        "F" or "C".
-    instrument : str
-        The instrument of the GOES-R Series imagery dataset product,
-        e.g. "ABI" or "GLM".
-    modes : list[str]
-        The list of modes of the GOES-R Series imagery dataset product,
-        e.g. "M3" or "M6".
-    channels : list[str]
-        The list of channels of the GOES-R Series imagery dataset
-        product, e.g. "C08" or "C13".
-    origin : str
-        The  origin identifier of the GOES-R Series imagery dataset
-        product, e.g. "G16". Due to how the dataset directories are
-        organised, only a single origin may be provided.
-
     Methods
     -------
     get_base_url(datasource: str)
@@ -132,7 +106,7 @@ class GOESProductLocator(ProductLocatorGG):
     # Satellites in the GOES-R Series are identified by the following
     # IDs:
     AVAILABLE_ORIGINS: dict[str, str] = {
-        f"G{id:02d}": f"goes{id:02d}" for id in range(16, 19)
+        f"G{idn:02d}": f"goes{idn:02d}" for idn in range(16, 19)
     }
 
     # Supported instruments from the GOES-R series:
@@ -208,12 +182,11 @@ def __init__(
             dataset directories are organised, only a single origin may
             be provided.
 
-        Raises
-        ------
-        ValueError
-            If the provided origin, level or instrument is invalid. Or
-            if an unexpected or unsupported setting is required for an
-            instrument that does not support it.
+        Notes
+        -----
+        ValueError is raised if the provided origin, level or instrument
+        is invalid. Or if an unexpected or unsupported setting is
+        required for an instrument that does not support it.
         """
         # TODO: Too many positional arguments. Solve it by using
         #       the Builder or Factory methods, or patterns like

src/GOES_DL/dataset/goes/locator_abi.py

@@ -79,10 +79,10 @@ def __init__(
             dataset directories are organised, only a single origin may
             be provided.
 
-        Raises
-        ------
-        ValueError
-            If the provided origin, level or scene is invalid.
+        Notes
+        -----
+        ValueError is raised if the provided origin, level or scene is
+        invalid.
         """
         # TODO: Too many positional arguments. Solve it by using
         #       the Builder or Factory methods, or patterns like

src/GOES_DL/dataset/goes/locator_dc.py

@@ -52,7 +52,7 @@ def __init__(
         scene : str
             The scene of the GOES-R Series imagery dataset product, e.g.
             "F" or "C".
-        channels : list[str]
+        channels : str | list[str]
             The list of channels of the GOES-R Series imagery dataset
             ABI product, e.g. "C08" or "C13".
         origin : str
@@ -112,7 +112,7 @@ def __init__(
         scene : str
             The scene of the GOES-R Series imagery dataset product, e.g.
             "F" or "C".
-        channels : list[str]
+        channels : str | list[str]
             The list of channels of the GOES-R Series imagery dataset
             ABI product, e.g. "C08" or "C14".
         origin : str
@@ -161,7 +161,6 @@ def __init__(self, scene: str, origin: str) -> None:
             dataset directories are organised, only a single origin may
             be provided.
         """
-
         self.available_channels = self.WV_CHANNELS
 
         super().__init__(

src/GOES_DL/dataset/goes/locator_dp.py

@@ -112,6 +112,11 @@ def __init__(self, name: str, scene: str, origin: str) -> None:
             namely a satellite identifier, e.g. "G16". Due to how the
             dataset directories are organised, only a single origin may
             be provided.
+
+        Raises
+        ------
+        ValueError
+            If the provided scene or origin is invalid.
         """
         self._validate_product(name, self.AVAILABLE_PRODUCTS)