Merge pull request #29 from bedrock-engineer/small-docstring-fixes

Small docstring fixes

Author: JoostGevaert

src/bedrock_ge/gi/ags/read.py

@@ -18,7 +18,7 @@ def ags_to_dfs(ags_data: str) -> Dict[str, pd.DataFrame]:
 
     Returns:
         Dict[str, pd.DataFrame]]: A dictionary where keys represent AGS group
-        names with corresponding DataFrames for the corresponding group data.
+            names with corresponding DataFrames for the corresponding group data.
     """
     # Process each line to find the AGS version and delegate parsing
     for line in ags_data.splitlines():
@@ -57,8 +57,9 @@ def ags3_to_dfs(ags3_data: str) -> Dict[str, pd.DataFrame]:
         ags3_data (str): The AGS 3 data as a string.
 
     Returns:
-        Dict[str, pd.DataFrame]: A dictionary of pandas DataFrames, where each key represents a group name from AGS 3 data,
-        and the corresponding value is a pandas DataFrame containing the data for that group.
+        Dict[str, pd.DataFrame]: A dictionary of pandas DataFrames, where each key
+            represents a group name from AGS 3 data, and the corresponding value is a
+            pandas DataFrame containing the data for that group.
     """
     # Initialize dictionary and variables used in the AGS 3 read loop
     ags3_dfs = {}
@@ -156,8 +157,9 @@ def ags4_to_dfs(ags4_data: str) -> Dict[str, pd.DataFrame]:
         ags4_data (str): The AGS 4 data as a string.
 
     Returns:
-        Dict[str, pd.DataFrame]: A dictionary of pandas DataFrames, where each key represents a group name from AGS 4 data,
-        and the corresponding value is a pandas DataFrame containing the data for that group.
+        Dict[str, pd.DataFrame]: A dictionary of pandas DataFrames, where each key 
+            represents a group name from AGS 4 data, and the corresponding value is a
+            pandas DataFrame containing the data for that group.
     """
     # AGS4.AGS4_to_dataframe accepts the file, not the data string
     ags4_file = io.StringIO(ags4_data)

src/bedrock_ge/gi/ags/transform.py

@@ -43,7 +43,7 @@ def ags3_db_to_no_gis_brgi_db(
 
     Returns:
         Dict[str, pd.DataFrame]: A dictionary containing Bedrock GI database tables,
-        where keys are table names and values are transformed pandas DataFrames.
+            where keys are table names and values are transformed pandas DataFrames.
 
     Note:
         The function creates a copy of the input database to avoid modifying the original data.

src/bedrock_ge/gi/concatenate.py

@@ -20,7 +20,7 @@ def concatenate_databases(
         db2 (Dict[str, pd.DataFrame]): A dictionary of pandas DataFrames, i.e. a database.
 
     Returns:
-        dict: A dictionary of concatenated pandas DataFrames.
+        concatenated_dict (Dict[str, pd.DataFrame]): A dictionary of concatenated pandas DataFrames.
     """
     # Create a new dict to store the concatenated dataframes
     concatenated_dict = {key: df.dropna(axis=1, how="all") for key, df in db1.items()}

src/bedrock_ge/gi/gis_geometry.py

@@ -28,14 +28,15 @@ def calculate_gis_geometry(
 
     Returns:
         Dict[str, gpd.GeoDataFrame]: Dictionary containing the Bedrock GI database tables
-        with added GIS geometry. All tables are converted to GeoDataFrames with
-        appropriate CRS and geometry columns.
+            with added GIS geometry. All tables are converted to GeoDataFrames with
+            appropriate CRS and geometry columns.
 
     Raises:
         ValueError: If the projects in the database use different Coordinate Reference Systems (CRS).
 
     Note:
         The function performs the following operations:
+
         1. Verifies all projects use the same CRS
         2. Calculates GIS geometry for the 'Location' table
         3. Creates a 'LonLatHeight' table for 2D visualization
@@ -155,7 +156,7 @@ def calculate_location_gis_geometry(
 
 def calculate_wgs84_coordinates(
     from_crs: CRS, easting: float, northing: float, elevation: Union[float, None] = None
-) -> Tuple:
+) -> Tuple[float, float, (float | None)]:
     """Transforms coordinates from an arbitrary Coordinate Reference System (CRS) to the WGS84 CRS, which is the standard for geodetic coordinates.
 
     Args:
@@ -166,9 +167,10 @@ def calculate_wgs84_coordinates(
             transform. Defaults to None.
 
     Returns:
-        tuple: A tuple containing the longitude, latitude and WGS84 height of the
-            transformed point, in that order. The height is None if no elevation was
-            given, or if the provided CRS doesn't have a proper datum defined.
+        Tuple[float, float, (float | None)]: A tuple containing the longitude, latitude
+            and WGS84 height of the transformed point, in that order.
+            The height is None if no elevation was given, or if the provided CRS doesn't
+            have a proper datum defined.
     """
     transformer = Transformer.from_crs(from_crs, 4326, always_xy=True)
     if elevation:
@@ -177,7 +179,7 @@ def calculate_wgs84_coordinates(
         lon, lat = transformer.transform(easting, northing)
         wgs84_height = None
 
-    return lon, lat, wgs84_height
+    return (lon, lat, wgs84_height)
 
 
 def create_lon_lat_height_table(
@@ -197,7 +199,7 @@ def create_lon_lat_height_table(
         crs (CRS): The Coordinate Reference System of the GI locations.
 
     Returns:
-        GeoDataFrame: The 'LonLatHeight' GeoDataFrame.
+        gpd.GeoDataFrame: The 'LonLatHeight' GeoDataFrame.
     """
     lon_lat_height = gpd.GeoDataFrame(
         brgi_location[
@@ -231,9 +233,9 @@ def calculate_in_situ_gis_geometry(
 
     Returns:
         gpd.GeoDataFrame: The GIS geometry for the given in-situ data, with additional columns:
-        - elevation_at_top: The elevation at the top of the in-situ data.
-        - elevation_at_base: The elevation at the base of the in-situ data.
-        - geometry: The GIS geometry of the in-situ data.
+            - elevation_at_top: The elevation at the top of the in-situ data.
+            - elevation_at_base: The elevation at the base of the in-situ data.
+            - geometry: The GIS geometry of the in-situ data.
     """
     location_child = brgi_in_situ.copy()
 

src/bedrock_ge/gi/validate.py

@@ -33,7 +33,7 @@ def check_brgi_database(brgi_db: Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]
             values are the corresponding data tables (DataFrame or GeoDataFrame).
 
     Returns:
-        bool: True if all tables are valid and relationships are properly maintained.
+        is_valid (bool): True if all tables are valid and relationships are properly maintained.
 
     Example:
         ```python

src/bedrock_ge/gi/write.py

@@ -16,7 +16,8 @@ def write_gi_db_to_gpkg(
     separate table named by the keys of the dictionary.
 
     Args:
-        brgi_db (dict): A dictionary where keys are brgi table names and values are DataFrames
+        brgi_db (Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]]): A dictionary where
+            keys are brgi table names and values are pandas DataFrames or GeoDataFrames
             with brgi data.
         gpkg_path (str): The name of the output GeoPackage file.
 
@@ -39,7 +40,7 @@ def write_gi_db_to_gpkg(
 
 
 def write_gi_db_to_excel(
-    gi_db: Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]],
+    gi_dfs: Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]],
     excel_path: Union[str, Path],
 ) -> None:
     """Writes a database with Ground Investigation data to an Excel file.
@@ -49,15 +50,17 @@ def write_gi_db_to_excel(
     AGS, Bedrock, or another format.
 
     Args:
-        gi_dfs (dict): A dictionary where keys are GI table names and values are DataFrames with GI data.
-        excel_path (str): The name of the output Excel file.
+        gi_dfs (Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]]): A dictionary where
+            keys are GI table names and values are DataFrames with GI data.
+        excel_path (Union[str, Path]): Path to the output Excel file. Can be provided as a
+            string or Path object.
 
     Returns:
         None
     """
     # Create an Excel writer object
     with pd.ExcelWriter(excel_path, engine="openpyxl") as writer:
-        for sheet_name, df in gi_db.items():
+        for sheet_name, df in gi_dfs.items():
             sanitized_sheet_name = sanitize_table_name(sheet_name)
             if isinstance(df, pd.DataFrame) or isinstance(df, gpd.GeoDataFrame):
                 df.to_excel(writer, sheet_name=sanitized_sheet_name, index=False)
@@ -76,7 +79,7 @@ def sanitize_table_name(sheet_name):
         sheet_name (str): The original sheet name.
 
     Returns:
-        sanitized_name: A sanitized sheet name with invalid characters and spaces replaced.
+        sanitized_name (str): A sanitized sheet name with invalid characters and spaces replaced.
     """
     # Trim to a maximum length of 31 characters
     trimmed_name = sheet_name.strip()[:31]