35 enforce documentation (#40)

Achaad · web-flow · commit 4ec18e4d06df · 2025-05-22T11:37:10.000+03:00
* ci: enforce correct documentation

* docs: fix code documentation

* fix: remove erroneous import
diff --git a/.flake8 b/.flake8
@@ -0,0 +1,4 @@
+[flake8]
+docstring-convention = numpy
+max-line-length = 120
+exclude = tests, .tox
diff --git a/.github/workflows/docstyle.yml b/.github/workflows/docstyle.yml
@@ -0,0 +1,24 @@
+name: Check Docstrings
+on: [push, pull_request]
+
+jobs:
+  docstyle:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install flake8 flake8-docstrings
+
+      - name: Run flake8
+        run: flake8 .
diff --git a/.gitignore b/.gitignore
@@ -296,4 +296,7 @@ pyrightconfig.json
 /.idea/sonarlint.xml
 
 # Large test resources
-tests/resources/ASA_IMS_1PNESA20040109_194924_000000182023_00157_09730_0000.N1
+tests/resources/ASA_IMS_1PNESA20040109_194924_000000182023_00157_09730_0000.N1
+
+# Pylint
+pylint.xml
diff --git a/README.md b/README.md
@@ -61,6 +61,21 @@ The project uses git lfs for tracking satellite imagery. In order to use git lfs
 
 If you need to track any other large files, execute `git lfs track "*.${extension}"`.
 
+### flak8 documentation
+
+The project actively uses flake8 for documentation and code style checking. Before pushing the changes,
+it is highly recommended to run:
+```bash
+
+pip install flake8 flake8-docstrings
+flake8 .
+```
+The repository is configured to run flake8 checks on every commit. If the code style is not correct, the commit will be rejected.
+
+If using Pycharm for development, use of _flake8-for-pycharm_ plugin is recommended. Installation instructions can be 
+found 
+[here](https://pypi.org/project/flake8-for-pycharm/).
+
 ### Issue tracking
 When the development on the issue begins, tag _In progress_ should be added to it.
 
diff --git a/asar_xarray/__init__.py b/asar_xarray/__init__.py
@@ -0,0 +1,4 @@
+"""asar_xarray: A library for mapping ASAR/ENVISAT Level-1 products into xarray format."""
+
+__all__: list[str] = [
+]
diff --git a/asar_xarray/asar.py b/asar_xarray/asar.py
@@ -1,3 +1,5 @@
+"""ASAR Xarray Dataset Reader."""
+
 import os
 from typing import Dict, Any
 
@@ -26,30 +28,54 @@ def get_attributes(gdal_dataset: gdal.Dataset) -> Dict[str, Any]:
     process_records_metadata(gdal_dataset, attributes)
     process_derived_subdatasets_metadata(gdal_dataset, attributes)
 
-
     attributes['chirp_parameters'] = get_chirp_parameters(gdal_dataset)
 
     return attributes
 
 
 def open_asar_dataset(filepath: str | os.PathLike[Any] | ReadBuffer[Any] | AbstractDataStore) -> xr.Dataset:
+    """
+    Open an ASAR dataset and converts it into an xarray Dataset.
+
+    This function reads the metadata and pixel data from the given ASAR dataset file,
+    processes the metadata into attributes, and constructs an xarray Dataset.
+
+    :param filepath: The path to the ASAR dataset file. It can be a string,
+                     a PathLike object, a ReadBuffer, or an AbstractDataStore.
+    :return: An xarray Dataset containing the pixel data and metadata attributes.
+    :raises NotImplementedError: If the filepath is not a string.
+    """
     if not isinstance(filepath, str):
         raise NotImplementedError(f'Filepath type {type(filepath)} is not supported')
+
     logger.debug('Opening ASAR dataset {}', filepath)
+
+    # Open the dataset using a custom reader
     gdal_dataset: gdal.Dataset = reader.get_gdal_dataset(filepath)
+
+    # Extract metadata attributes
     attributes = get_attributes(gdal_dataset)
+
+    # Read pixel data from the dataset
     data = gdal_dataset.ReadAsArray()
-    dataset: xr.Dataset = xr.Dataset(data_vars={'pixel_values': (('y', 'x'), data)},
-                                     coords={
-                                         'x': np.arange(data.shape[1]),
-                                         'y': np.arange(data.shape[0])
-                                     }, attrs=attributes)
+
+    # Create an xarray Dataset with pixel data and metadata attributes
+    dataset: xr.Dataset = xr.Dataset(
+        data_vars={'pixel_values': (('y', 'x'), data)},
+        coords={
+            'x': np.arange(data.shape[1]),
+            'y': np.arange(data.shape[0])
+        },
+        attrs=attributes
+    )
+
     return dataset
 
 
 def get_chirp_parameters(dataset: gdal.Dataset) -> dict[str, Any]:
     """
-    Parses dataset metadata for chirp parameters.
+    Parse dataset metadata for chirp parameters.
+
     :param dataset: ASAR dataset.
     :return: dictionary with chirp parameters.
     """
diff --git a/asar_xarray/derived_subdatasets_metadata.py b/asar_xarray/derived_subdatasets_metadata.py
@@ -1,3 +1,5 @@
+"""Process derived subdatasets metadata from GDAL dataset."""
+
 from typing import Any
 
 from osgeo import gdal
diff --git a/asar_xarray/general_metadata.py b/asar_xarray/general_metadata.py
@@ -1,3 +1,5 @@
+"""General metadata processing for ASAR datasets."""
+
 from datetime import datetime
 import re
 from typing import Any
@@ -9,6 +11,18 @@
 
 
 def process_general_metadata(dataset: gdal.Dataset, attributes: dict[str, Any]) -> None:
+    """
+    Process general metadata from a GDAL dataset and update the attributes dictionary.
+
+    This function retrieves metadata from the provided GDAL dataset and processes it
+    using three helper functions: `process_mph_metadata`, `process_sph_metadata`, and
+    `process_ds_metadata`. The processed metadata is then added to the `attributes`
+    dictionary.
+
+    :param dataset: A GDAL dataset object from which metadata is retrieved.
+    :param attributes: A dictionary to be updated with processed metadata.
+    :return: None
+    """
     metadata = dataset.GetMetadata(domain='')
     attributes.update(process_mph_metadata(metadata))
     attributes.update(process_sph_metadata(metadata))
@@ -18,6 +32,7 @@ def process_general_metadata(dataset: gdal.Dataset, attributes: dict[str, Any])
 def process_mph_metadata(metadata: dict[str, str]) -> dict[str, Any]:
     """
     Process MPH metadata by removing 'MPH_' prefix and converting values to appropriate types.
+
     Uses numpy.datetime64 for datetime values.
 
     :param metadata: Dictionary with MPH metadata
@@ -67,6 +82,7 @@ def process_mph_metadata(metadata: dict[str, str]) -> dict[str, Any]:
 def process_sph_metadata(metadata: dict[str, str]) -> dict[str, Any]:
     """
     Process SPH metadata by removing 'SPH_' prefix and converting values to appropriate types.
+
     Uses numpy.datetime64 for datetime values.
 
     :param metadata: Dictionary with SPH metadata
diff --git a/asar_xarray/main.py b/asar_xarray/main.py
@@ -1,9 +1,10 @@
+"""Shows how to use the asar xarray plugin."""
+
 import xarray as xr
 
 if __name__ == "__main__":
     # Example usage
     test_file = ('../tests/resources'
                  '/ASA_IMS_1PNESA20040109_194924_000000182023_00157_09730_0000.N1')
     dataset = xr.open_dataset(test_file, engine='asar')
-    # print(dataset)
-    print(dataset.attrs)
+    print(dataset)
diff --git a/asar_xarray/reader.py b/asar_xarray/reader.py
@@ -1,16 +1,17 @@
-from osgeo import gdal, ogr
+"""Reading GDAL dataset."""
+
+from osgeo import gdal
 
 gdal.UseExceptions()
 
 
 def get_gdal_dataset(filepath: str) -> gdal.Dataset:
     """
-    Reads file into gdal dataset.
+    Read file into gdal dataset.
 
     :param filepath: File to be read
     :return: Opened dataset
     """
-
     dataset: gdal.Dataset = gdal.Open(filepath)
     if not dataset:
         raise RuntimeError(f'Could not open file: {filepath}')
diff --git a/asar_xarray/records_metadata.py b/asar_xarray/records_metadata.py
@@ -1,3 +1,5 @@
+"""Records metadata processing for ASAR datasets."""
+
 from typing import Any
 from osgeo import gdal
 
@@ -32,6 +34,27 @@ def process_records_metadata(dataset: gdal.Dataset, attributes: dict[str, Any])
 
 
 def process_main_processing_params(metadata: dict[str, str]) -> dict[str, Any]:
+    """
+    Process the main processing parameters metadata and organize it into a structured dictionary.
+
+    This function extracts and processes various categories of main processing parameters
+    from the provided metadata dictionary. Each category is handled by a dedicated helper function.
+
+    :param metadata: Dictionary containing the main processing parameters metadata.
+    :return: A dictionary with the processed main processing parameters, structured as follows:
+        - 'general': General main processing parameters.
+        - 'raw_data_analysis': List of dictionaries with raw data analysis parameters.
+        - 'image_parameters': Dictionary with image parameters.
+        - 'bandwidth': Dictionary with bandwidth parameters.
+        - 'nominal_chirp': List of dictionaries with nominal chirp parameters.
+        - 'calibration_factors': List of dictionaries with calibration factors.
+        - 'output_statistics': List of dictionaries with output statistics.
+        - 'orbit_state_vectors': List of dictionaries with orbit state vectors.
+        - 'start_time': List of dictionaries with start time parameters.
+        - 'parameter_codes': Dictionary with parameter codes.
+        - 'error_counters': Dictionary with error counters.
+        - 'noise_estimation': Dictionary with noise estimation parameters.
+    """
     params = dict()
     params.update(process_general_main_processing_params(metadata))
     params['raw_data_analysis'] = process_raw_data_analysis(metadata)
@@ -88,8 +111,7 @@ def process_raw_data_analysis(metadata: dict[str, str]) -> list[dict[str, Any]]:
 
 def process_image_parameters(metadata: dict[str, str]) -> dict[str, Any]:
     """
-    Process image parameters metadata by converting values to appropriate types
-    and removing trailing zeros from arrays.
+    Process image parameters metadata.
 
     :param metadata: Dictionary with image parameters metadata
     :return: Processed metadata dictionary
@@ -386,8 +408,7 @@ def process_noise_estimation(metadata: dict[str, str]) -> dict[str, list[float]]
 
 def process_general_main_processing_params(metadata: dict[str, str]) -> dict[str, Any]:
     """
-    Process basic main processing parameters metadata by removing 'MAIN_PROCESSING_PARAMS_ADS_' prefix
-    and converting values to appropriate types. Excludes complex nested data structures.
+    Process basic main processing parameters metadata.
 
     :param metadata: Dictionary with main processing parameters metadata
     :return: Processed metadata dictionary with basic parameters only
diff --git a/asar_xarray/utils.py b/asar_xarray/utils.py
@@ -1,3 +1,5 @@
+"""General dataset processing utils."""
+
 import re
 
 import numpy as np
@@ -8,7 +10,7 @@
 
 def get_envisat_time(time_str: str) -> datetime64 | None:
     """
-    Converts time string to envisat epoch time in numpy datetime64 format.
+    Convert time string to envisat epoch time in numpy datetime64 format.
 
     :param time_str: String containing MJD in format "days, seconds, microseconds"
     :return: numpy datetime64 object
@@ -38,6 +40,7 @@ def get_envisat_time(time_str: str) -> datetime64 | None:
 
 def get_mjd_time(mjd_str: str) -> datetime64 | None:
     """
+    Convert mjd time to numpy.datetime64 format.
 
     :param mjd_str: String containing MJD in format "days, seconds, microseconds"
     :return: numpy datetime64 object
@@ -66,6 +69,16 @@ def get_mjd_time(mjd_str: str) -> datetime64 | None:
 
 
 def try_parse_datetime(value: str) -> np.datetime64 | None:
+    """
+    Attempt to parse a string into a numpy.datetime64 object.
+
+    This function checks if the input string matches a specific datetime format
+    (e.g., "DD-MMM-YYYY HH:MM:SS") and converts it into a numpy.datetime64 object
+    if valid. If the string does not match the format or cannot be parsed, it returns None.
+
+    :param value: The string to parse, expected in the format "DD-MMM-YYYY HH:MM:SS".
+    :return: A numpy.datetime64 object if parsing is successful, otherwise None.
+    """
     datetime_pattern = re.compile(r'\d{2}-[A-Z]{3}-\d{4}\s+\d{2}:\d{2}:\d{2}')
     if datetime_pattern.match(value):
         try:
@@ -77,20 +90,52 @@ def try_parse_datetime(value: str) -> np.datetime64 | None:
 
 
 def try_parse_latlong(value: str) -> float | None:
+    """
+    Attempt to parse a latitude/longitude value from a string.
+
+    This function checks if the input string matches the expected format for latitude
+    or longitude values (a signed 10-digit integer). If the format is valid, it converts
+    the value to a float by dividing it by 1e7. If the format is invalid, it returns None.
+
+    :param value: The string to parse, expected to be a signed 10-digit integer.
+    :return: A float representing the latitude/longitude if parsing is successful, otherwise None.
+    """
     latlong_pattern = re.compile(r'[+-]\d{10}$')
     if latlong_pattern.match(value):
         return float(value) / 1e7
     return None
 
 
 def try_parse_int(value: str) -> int | None:
+    """
+    Attempt to parse an integer value from a string.
+
+    This function checks if the input string represents a valid integer.
+    It removes any '+' or '-' signs for validation purposes and then
+    converts the string to an integer if valid. If the string is not a valid
+    integer, it returns None.
+
+    :param value: The string to parse, expected to represent an integer.
+    :return: An integer if parsing is successful, otherwise None.
+    """
     numeric = value.replace('+', '-').replace('-', '')
     if numeric.isdigit():
         return int(value.replace('+', ''))
     return None
 
 
 def try_parse_float(value: str) -> float | None:
+    """
+    Attempt to parse a floating-point number from a string.
+
+    This function checks if the input string contains a valid floating-point number,
+    indicated by the presence of 'E' (scientific notation) or a decimal point ('.').
+    If valid, it converts the string to a float. If the string is not a valid float,
+    it returns None.
+
+    :param value: The string to parse, expected to represent a floating-point number.
+    :return: A float if parsing is successful, otherwise None.
+    """
     if 'E' in value or '.' in value:
         try:
             return float(value.replace('+', ''))
@@ -100,6 +145,20 @@ def try_parse_float(value: str) -> float | None:
 
 
 def try_parse_float_list(value: str) -> float | list[float] | None:
+    """
+    Attempt to parse a string into a float or a list of floats.
+
+    This function splits the input string into parts and checks if each part matches
+    the format of a valid floating-point number (including scientific notation).
+    If all parts are valid, it converts them to floats. If there is only one float,
+    it returns that float. If there are multiple floats, it returns a list of floats.
+    If the input string is invalid, it returns None.
+
+    :param value: The string to parse, expected to contain one or more floating-point numbers
+                  separated by whitespace.
+    :return: A single float if the input contains one valid number, a list of floats if
+             multiple valid numbers are present, or None if parsing fails.
+    """
     parts = value.strip().split()
     if all(re.fullmatch(r'^[+-]?\d+(?:\.\d+)?(?:e[+-]?\d+)?$', p, re.IGNORECASE) for p in parts):
         try:
diff --git a/asar_xarray/xarray_backends.py b/asar_xarray/xarray_backends.py

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +"""asar_xarray: A library for mapping ASAR/ENVISAT Level-1 products into xarray format."""
++
 +__all__: list[str] = [
 +]
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+"""Process derived subdatasets metadata from GDAL dataset."""`
	`2`	`+`
`1`	`3`	`from typing import Any`
`2`	`4`
`3`	`5`	`from osgeo import gdal`