DOC: fix and enable pydocstyle checks by ruff (theroggy#163)

bin_util/calc_dias_weekly.py

@@ -1,6 +1,4 @@
-"""
-Calaculate the timeseries data per week based on per image data.
-"""
+"""Calculate the timeseries data per week based on per image data."""
 
 import os
 from datetime import datetime

bin_util/calc_overlaps.py

@@ -1,6 +1,4 @@
-"""
-Module calculate overlaps between two layers.
-"""
+"""Script to calculate overlaps between two layers."""
 
 import os
 import pprint
@@ -10,10 +8,6 @@
 import cropclassification.helpers.config_helper as conf
 from cropclassification.helpers import log_helper
 
-# -------------------------------------------------------------
-# The real work
-# -------------------------------------------------------------
-
 
 def main():
     # Read the configuration

bin_util/read_head.py

@@ -1,6 +1,4 @@
-"""
-Read first lines of a file.
-"""
+"""Read first lines of a file."""
 
 base_dir = "X:\\PerPersoon\\PIEROG\\Taken\\2018\\2018-05-04_Monitoring_Classificatie"
 path = (

bin_util/timeseries_visualize.py

@@ -1,6 +1,5 @@
 # %%
-"""
-Show the timeseries for a parcel.
+"""Show the timeseries for a parcel.
 
 TODO: Recently hasn't been tested anymore!!!
 """

cropclassification/__init__.py

@@ -0,0 +1 @@
+"""Package with functionalities to support agricultural parcel monitoring."""

cropclassification/calc_cropclass.py

@@ -25,8 +25,7 @@ def calc_marker_task(
     default_basedir: Path,
     config_overrules: list[str] = [],
 ):
-    """
-    Runs a marker using the setting in the config_paths.
+    """Runs a marker using the setting in the config_paths.
 
     Args:
         config_paths (List[Path]): the config files to load

cropclassification/calc_periodic_mosaic.py

@@ -9,8 +9,7 @@
 
 
 def calc_periodic_mosaic_task(config_paths: list[Path], default_basedir: Path):
-    """
-    Runs a periodic mosaic using the setting in the config_paths.
+    """Runs a periodic mosaic using the setting in the config_paths.
 
     Args:
         config_paths (List[Path]): the config files to load

cropclassification/helpers/__init__.py

@@ -0,0 +1 @@
+"""General helper functions for the parcel monitoring package."""

cropclassification/helpers/config_helper.py

@@ -1,6 +1,4 @@
-"""
-Module that manages configuration data.
-"""
+"""Module that manages configuration data."""
 
 import configparser
 import json
@@ -34,12 +32,22 @@
 
 
 class ImageConfig:
+    """Image configuration class."""
+
     def __init__(
         self,
         imageprofile_name: str,
         imageprofile: Optional[ImageProfile] = None,
         bands: Optional[list[str]] = None,
     ):
+        """Constructor for ImageConfig.
+
+        Args:
+            imageprofile_name (str): the name of the image profile.
+            imageprofile (Optional[ImageProfile], optional): ImageProfile to use for
+                this Image. Defaults to None.
+            bands (Optional[list[str]], optional): the bands to read. Defaults to None.
+        """
         self.imageprofile_name = imageprofile_name
         if imageprofile is not None:
             self.imageprofile = imageprofile
@@ -57,8 +65,7 @@ def read_config(
     overrules: list[str] = [],
     preload_defaults: bool = True,
 ):
-    """
-    Read cropclassification configuration file(s).
+    """Read cropclassification configuration file(s).
 
     Args:
         config_paths (Path): path(s) to the configuration file(s) to read. If None, and
@@ -244,6 +251,7 @@ def read_config(
 
 
 def parse_image_config(input) -> dict[str, ImageConfig]:
+    """Parses the json input to a dictionary of ImageConfig objects."""
     result = None
     imageconfig_parsed = None
     try:
@@ -333,6 +341,7 @@ def _validate_image_profiles(profiles: dict[str, ImageProfile]):
 
 
 def pformat_config():
+    """Formats the config as a pretty string."""
     message = (
         f"Config files used: {pprint.pformat(config_paths_used)} \n"
         "Config info listing:\n"
@@ -343,8 +352,7 @@ def pformat_config():
 
 
 def as_dict():
-    """
-    Converts the config objects into a dictionary.
+    """Converts the config objects into a dictionary.
 
     The resulting dictionary has sections as keys which point to a dict of the
     sections options as key => value pairs.

cropclassification/helpers/dir_helper.py

@@ -1,6 +1,4 @@
-"""
-Helper regarding directory operations.
-"""
+"""Helper regarding directory operations."""
 
 import os
 import re
@@ -9,15 +7,13 @@
 
 
 def create_run_dir(class_base_dir: Path, reuse_last_run_dir: bool) -> Path:
-    """
-    Create a new run dir, or get the last run dir.
+    """Create a new run dir, or get the last run dir.
 
-    Args
+    Args:
         class_base_dir: the base dir to use to create the run dir in
         reuse_last_run_dir: True to find the latest existing run dir and return that,
             False to create a new run dir
     """
-
     # Create class_base_dir if it doesn't exist
     if not class_base_dir.exists():
         os.makedirs(class_base_dir)

cropclassification/helpers/log_helper.py

@@ -1,14 +1,24 @@
-"""
-Module to init logging.
-"""
+"""Module to init logging."""
 
 import datetime
 import logging
 import os
 from pathlib import Path
 
 
-def main_log_init(log_dir: Path, log_basefilename: str, log_level: str = "INFO"):
+def main_log_init(
+    log_dir: Path, log_basefilename: str, log_level: str = "INFO"
+) -> logging.Logger:
+    """Initialize the main log file.
+
+    Args:
+        log_dir (Path): the directory where the log file should be stored.
+        log_basefilename (str): the base name of the log file.
+        log_level (str, optional): the level to log. Defaults to "INFO".
+
+    Returns:
+        logging.Logger: the logger object.
+    """
     # Make sure the log dir exists
     if not log_dir.exists():
         os.makedirs(log_dir, exist_ok=True)

cropclassification/helpers/model_helper.py

@@ -1,6 +1,4 @@
-"""
-Module with helper functions regarding (keras) models.
-"""
+"""Module with helper functions regarding (keras) models."""
 
 import glob
 import logging
@@ -23,10 +21,9 @@
 
 
 def get_max_data_version(model_dir: Path) -> int:
-    """
-    Get the maximum data version a model exists for in the model_dir.
+    """Get the maximum data version a model exists for in the model_dir.
 
-    Args
+    Args:
         model_dir: the dir to search models in
     """
     models_df = get_models(model_dir)
@@ -40,10 +37,9 @@ def get_max_data_version(model_dir: Path) -> int:
 def format_model_base_filename(
     segment_subject: str, train_data_version: int, model_architecture: str
 ) -> str:
-    """
-    Format the parameters into a model_base_filename.
+    """Format the parameters into a model_base_filename.
 
-    Args
+    Args:
         segment_subject: the segment subject
         train_data_version: the version of the data used to train the model
         model_architecture: the architecture of the model
@@ -61,10 +57,9 @@ def format_model_filename(
     acc_combined: float,
     epoch: int,
 ) -> str:
-    """
-    Format the parameters into a model_filename.
+    """Format the parameters into a model_filename.
 
-    Args
+    Args:
         segment_subject: the segment subject
         train_data_version: the version of the data used to train the model
         model_architecture: the architecture of the model
@@ -95,10 +90,9 @@ def format_model_filename2(
     acc_combined: float,
     epoch: int,
 ) -> str:
-    """
-    Format the parameters into a model_filename.
+    """Format the parameters into a model_filename.
 
-    Args
+    Args:
         model_base_filename: the base filename of the model
         acc_train: the accuracy reached for the training dataset
         acc_val: the accuracy reached for the validation dataset
@@ -113,8 +107,9 @@ def format_model_filename2(
 
 
 def parse_model_filename(path: Path) -> dict:
-    """
-    Parse a model_filename to a dict containing the properties of the model:
+    """Parse a model_filename to a dict containing the properties of the model.
+
+    Result:
         * segment_subject: the segment subject
         * train_data_version: the version of the data used to train the model
         * model_architecture: the architecture of the model
@@ -123,7 +118,7 @@ def parse_model_filename(path: Path) -> dict:
         * acc_combined: the average of the train and validation accuracy
         * epoch: the epoch during training that reached these model weights
 
-    Args
+    Args:
         path: the path to the model file
     """
     # Prepare path to extract info
@@ -160,16 +155,15 @@ def parse_model_filename(path: Path) -> dict:
 def get_models(
     model_dir: Path, model_base_filename: Optional[str] = None
 ) -> pd.DataFrame:
-    """
-    Return the list of models in the model_dir passed. It is returned as a
-    dataframe with the columns as returned in parse_model_filename()
+    """Return the list of models in the model_dir passed.
+
+    It is returned as a dataframe with the columns as returned in parse_model_filename.
 
-    Args
+    Args:
         model_dir: dir containing the models
         model_base_filename: optional, if passed, only the models with this
             base filename will be returned
     """
-
     # glob search string
     if model_base_filename is not None:
         model_weight_paths = glob.glob(
@@ -189,13 +183,12 @@ def get_models(
 def get_best_model(
     model_dir: Path, acc_metric_mode: str, model_base_filename: Optional[str] = None
 ) -> Optional[dict]:
-    """
-    Get the properties of the model with the highest combined accuracy for the highest
-    traindata version in the dir.
+    """Get model with the highest accuracy for the highest traindata version in the dir.
 
-    Args
+    Args:
         model_dir: dir containing the models
-        acc_metric_mode:
+        acc_metric_mode: use 'min' if the accuracy metrics should be as low as possible,
+            'max' if a higher values is better.
         model_base_filename: optional, if passed, only the models with this
             base filename will be taken in account
     """
@@ -243,19 +236,20 @@ def save_and_clean_models(
     debug: bool = False,
     only_report: bool = False,
 ):
-    """
-    Save the new model if it is good enough... en cleanup existing models
-    if they are worse than the new or other existing models.
+    """Save the new model if it is good enough.
+
+    Existing models are removed if they are worse than the new or other existing models.
 
-    Args
+    Args:
         model_save_dir: dir containing the models
         model_save_base_filename: base filename that will be used
-        model_acc_metric_mode (str): use 'min' if the accuracy metrics should be
+        acc_metric_mode (str): use 'min' if the accuracy metrics should be
                 as low as possible, 'max' if a higher values is better.
         new_model: optional, the keras model object that will be saved
         new_model_acc_train: optional: the accuracy on the train dataset
         new_model_acc_val: optional: the accuracy on the validation dataset
         new_model_epoch: optional: the epoch in the training
+        save_weights_only: optional: only save the weights of the model
         verbose: report the best model after save and cleanup
         debug: write debug logging
         only_report: optional: only report which models would be cleaned up

cropclassification/helpers/pandas_helper.py

@@ -1,6 +1,4 @@
-"""
-Module with helper functions to expand on some features of pandas.
-"""
+"""Module with helper functions to expand on some features of pandas."""
 
 import os
 import sqlite3
@@ -11,6 +9,16 @@
 
 
 def get_table_info(path: Path, table_name: str = "info") -> dict[str, Any]:
+    """Gte information about a table in a database file.
+
+    Args:
+        path (Path): path to the database file.
+        table_name (str, optional): name of the table to get info from.
+            Defaults to "info".
+
+    Returns:
+        dict[str, Any]: information about the table.
+    """
     ext_lower = path.suffix.lower()
     if ext_lower in (".sqlite", ".gpkg"):
         sql_db = None
@@ -42,9 +50,9 @@ def get_table_info(path: Path, table_name: str = "info") -> dict[str, Any]:
 def read_file(
     path: Path, table_name: str = "info", columns: Optional[list[str]] = None
 ) -> pd.DataFrame:
-    """
-    Reads a file to a pandas dataframe. The fileformat is detected based on the
-    path extension.
+    """Read a file to a pandas dataframe.
+
+    The fileformat is detected based on the path extension.
 
     # TODO: think about if possible/how to support  adding optional parameter and pass
     # them to next function, example encoding, float_format,...
@@ -117,9 +125,9 @@ def to_file(
     index: bool = True,
     append: bool = False,
 ):
-    """
-    Reads a pandas dataframe to file. The file format is detected based on the path
-    extension.
+    """Writes a pandas dataframe to file.
+
+    The file format is detected based on the path extension.
 
     # TODO: think about if possible/how to support  adding optional parameter and pass
     # them to next function, example encoding, float_format,...

cropclassification/postprocess/__init__.py

@@ -0,0 +1 @@
+"""Module for postprocessing of classification results."""